diff mbox series

doc: explain how the parser finds the root node

Message ID 20181114153622.16006-1-sbabic@denx.de
State Accepted
Headers show
Series doc: explain how the parser finds the root node | expand

Commit Message

Stefano Babic Nov. 14, 2018, 3:36 p.m. UTC 
The parser checks for the root node searching for selections and
boardname, and this is now described in the documentation.

Signed-off-by: Stefano Babic <sbabic@denx.de>
---
 doc/source/sw-description.rst | 67 +++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
diff mbox series

Patch

diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst
index ec32e8e..36c02b2 100644
--- a/doc/source/sw-description.rst
+++ b/doc/source/sw-description.rst
@@ -251,6 +251,73 @@  other slot.
 The method of image selection is out of the scope of SWUpdate and user
 is responsible for calling `SWUpdate` passing proper settings.
 
+Priority finding the elements in the file
+-----------------------------------------
+
+SWUpdate search for entries in the sdw-description file according to the following priority:
+
+1. Try <boardname>.<selection>.<mode>.<entry>
+2. Try <selection>.<mode>.<entry>
+3. Try <boardname>.<entry>
+4. Try <entry>
+
+Take an example. The following sw-description describes the release for a set of boards.
+
+::
+
+    software =
+    {
+            version = "0.1.0";
+
+            myboard = {
+                stable = {
+                    copy-1: {
+                            images: (
+                            {
+                                    device = "/dev/mtd4"
+                                    ...
+                            }
+                            );
+                    }
+                    copy-2: {
+                            images: (
+                            {
+                                    device = "/dev/mtd5"
+                                    ...
+                            }
+                            );
+                    }
+                }
+            }
+
+            stable = {
+                copy-1: {
+                      images: (
+                          {
+                               device = "/dev/mtd6"
+                                    ...
+                          }
+                       );
+                }
+                copy-2: {
+                       images: (
+                       {
+                               device = "/dev/mtd7"
+                                    ...
+                       }
+                       );
+                }
+            }
+    }
+
+On *myboard*, SWUpdate searches and find myboard.stable.copy1(2). When running on different
+boards, SWUpdate does not find an enty corresponding to the boardname and it fallbacks to the
+version without boardname. This lets relalize the same release for different boards having
+a complete different hardware. `myboard` could have a eMMC and an ext4 filesystem,
+while another device can have raw flash and install an UBI filesystem. Nevertheless, they are
+both just a different format of the same release and they could be described together in sw-description.
+It is important to understand the priorities how SWUpdate scans for entries during the parsing.
+
 hardware-compatibility
 ----------------------