| Message ID | 20181101170635.13493-5-sbabic@denx.de |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | [1/5] Factorize function to count elements in array of strings | expand |
Hi Stefano, I like your idea about links in the sw-description and have some questions regarding the implementation. Am 01.11.18 um 18:06 schrieb Stefano Babic: > Signed-off-by: Stefano Babic <sbabic@denx.de> > --- > doc/source/sw-description.rst | 255 ++++++++++++++++++++++++++++++++++ > 1 file changed, 255 insertions(+) > > diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst > index ec32e8e..cd28a38 100644 > --- a/doc/source/sw-description.rst > +++ b/doc/source/sw-description.rst > @@ -251,6 +251,261 @@ 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: Typo in sw-description. > + > +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. > + Can you please move this into its own patch because it doesn't belongs to the link description. > +Using links > +----------- > + > +sw-description can become very complex. Let's think to have just one board, but in multiple > +hw revision and they differ in Hardware. Some of them can be grouped together, some of them > +require a dedicated section. A way (but not the only one !) could be to add *mode* and selects > +the section with `-e stable,<rev number>`. > + > +:: > + > + software = > + { > + version = "0.1.0"; > + > + myboard = { > + stable = { > + > + hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, "3.0", "3.1"]; > + rev-1.0: { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev-1.2: { > + hardware-compatibility: ["1.2"]; > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev-2.0: { > + hardware-compatibility: ["2.0"]; > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev-1.3: { > + hardware-compatibility: ["1.3"]; > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + > + rev-3.0: > + { > + hardware-compatibility: ["3.0"]; > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev-3.1: > + { > + hardware-compatibility: ["3.1"]; > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + } > + } > + } > + > +If each of them requires an own section, it is the way to do. Anyway, it is more probable > +than revisions can be grouped together, for example board with the same major revision > +number could have the same installation instructions. This leads in the example to 3 groups > +for rev1.X, rev2.X and rev3.X. Links allow to group section together. When a string is found > +when SWUpdate searches for a group (images, files, script, bootenv), it replaces the current path > +in the tree with the value of the string. In this way, the example above can be written in this way: > + > +:: > + > + software = > + { > + version = "0.1.0"; > + > + myboard = { > + stable = { > + > + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, "3.0", "3.1"]; > + rev-1x: { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev1.0 = "rev-1x"; > + rev1.2 = "rev-1x"; > + rev1.3 = "rev-1x"; > + rev-2x: { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev2.0 = "rev-2x"; > + > + rev-3x: > + { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev3.0 = "rev-3x"; > + rev3.1 = "rev-3x"; > + } > + } > + } > + > +The link can be absolute or relative. A relative path has a number of > +leading ".." to move the current cursor to the parent leaf of the tree. > +In the following example, rev40 sets a link to a "common" section, where `images` > +is found. This is sets via a link, too, to a section in the parent node. > +The path `software.myboard.stable.common.images` is then replaced by > +`software.myboard.stable.trythis` > + > +:: > + > + software = > + { > + version = "1.0"; /* Release Version */ > + > + hardware-compatibility =["rev10","rev11", "rev20"]; > + > + myboard:{ > + stable:{ > + > + common: { > + images = "..trythis"; > + uboot:( > + { > + name = "bootpart"; value = "2:1"; > + } > + ); > + }; > + > + trythis: ( > + { > + filename = "rootfs.ext5"; > + device = "/dev/mmcblk0p8"; > + } > + ); > + rev10: > + { > + images:( > + { > + filename = "rootfs.ext3"; > + device = "/dev/mmcblk0p2"; > + } > + ); > + uboot:( > + { > + name = "bootpart"; value = "0:2"; > + } > + ); > + }; > + rev11 = "rev10"; > + rev20 = "rev10"; > + rev40 = "common"; > + }; > + }; > + } I don't understand you link format. In your example "rev10" is a relative link on the same level and "..trythis" a relative link one level up. How looks an absolute link or a link three level above? Why don't you use something like JSON Pointer [1] / URIs? Furthermore JSON Schema [2] use a special reference object with a "$ref" entry to support references at any place even for string entries. This would make the links explicitly and would allow the reuse of filename or sha256. [1] https://tools.ietf.org/html/rfc6901 [2] https://json-schema.org/understanding-json-schema/structuring.html Best regards Stefan
Hi Stefan, Am 01.11.2018 um 20:47 schrieb Stefan Herbrechtsmeier: > Hi Stefano, > > I like your idea about links in the sw-description and have some > questions regarding the implementation. > > Am 01.11.18 um 18:06 schrieb Stefano Babic: >> Signed-off-by: Stefano Babic <sbabic@denx.de> >> --- >> doc/source/sw-description.rst | 255 ++++++++++++++++++++++++++++++++++ >> 1 file changed, 255 insertions(+) >> >> diff --git a/doc/source/sw-description.rst >> b/doc/source/sw-description.rst >> index ec32e8e..cd28a38 100644 >> --- a/doc/source/sw-description.rst >> +++ b/doc/source/sw-description.rst >> @@ -251,6 +251,261 @@ 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: > Typo in sw-description. > >> + >> +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. >> + > Can you please move this into its own patch because it doesn't belongs > to the link description. > I'll do. >> +Using links >> +----------- >> + >> +sw-description can become very complex. Let's think to have just one >> board, but in multiple >> +hw revision and they differ in Hardware. Some of them can be grouped >> together, some of them >> +require a dedicated section. A way (but not the only one !) could be >> to add *mode* and selects >> +the section with `-e stable,<rev number>`. >> + >> +:: >> + >> + software = >> + { >> + version = "0.1.0"; >> + >> + myboard = { >> + stable = { >> + >> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, >> "3.0", "3.1"]; >> + rev-1.0: { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev-1.2: { >> + hardware-compatibility: ["1.2"]; >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev-2.0: { >> + hardware-compatibility: ["2.0"]; >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev-1.3: { >> + hardware-compatibility: ["1.3"]; >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + >> + rev-3.0: >> + { >> + hardware-compatibility: ["3.0"]; >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev-3.1: >> + { >> + hardware-compatibility: ["3.1"]; >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + } >> + } >> + } >> + >> +If each of them requires an own section, it is the way to do. Anyway, >> it is more probable >> +than revisions can be grouped together, for example board with the >> same major revision >> +number could have the same installation instructions. This leads in >> the example to 3 groups >> +for rev1.X, rev2.X and rev3.X. Links allow to group section together. >> When a string is found >> +when SWUpdate searches for a group (images, files, script, bootenv), >> it replaces the current path >> +in the tree with the value of the string. In this way, the example >> above can be written in this way: >> + >> +:: >> + >> + software = >> + { >> + version = "0.1.0"; >> + >> + myboard = { >> + stable = { >> + >> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, >> "3.0", "3.1"]; >> + rev-1x: { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev1.0 = "rev-1x"; >> + rev1.2 = "rev-1x"; >> + rev1.3 = "rev-1x"; >> + rev-2x: { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev2.0 = "rev-2x"; >> + >> + rev-3x: >> + { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev3.0 = "rev-3x"; >> + rev3.1 = "rev-3x"; >> + } >> + } >> + } >> + >> +The link can be absolute or relative. A relative path has a number of >> +leading ".." to move the current cursor to the parent leaf of the tree. >> +In the following example, rev40 sets a link to a "common" section, >> where `images` >> +is found. This is sets via a link, too, to a section in the parent node. >> +The path `software.myboard.stable.common.images` is then replaced by >> +`software.myboard.stable.trythis` >> + >> +:: >> + >> + software = >> + { >> + version = "1.0"; /* Release Version */ >> + >> + hardware-compatibility =["rev10","rev11", "rev20"]; >> + >> + myboard:{ >> + stable:{ >> + >> + common: { >> + images = "..trythis"; >> + uboot:( >> + { >> + name = "bootpart"; value = "2:1"; >> + } >> + ); >> + }; >> + >> + trythis: ( >> + { >> + filename = "rootfs.ext5"; >> + device = "/dev/mmcblk0p8"; >> + } >> + ); >> + rev10: >> + { >> + images:( >> + { >> + filename = "rootfs.ext3"; >> + device = "/dev/mmcblk0p2"; >> + } >> + ); >> + uboot:( >> + { >> + name = "bootpart"; value = "0:2"; >> + } >> + ); >> + }; >> + rev11 = "rev10"; >> + rev20 = "rev10"; >> + rev40 = "common"; >> + }; >> + }; >> + } > I don't understand you link format. In your example "rev10" is a > relative link on the same level and "..trythis" a relative link one > level up. How looks an absolute link or a link three level above? > You're right. I have implemented the relative link, there is no absolute link. The link in this implementation must always go through the path to the node that is required. That means: rev10 ==> replace current leaf ..trythis ==> one level up ....trythis ==> two level up ......trythis ==> three level up Any malformed link that does not point to a correct node in sw-description results in an error and the parser stops. > Why don't you use something like JSON Pointer [1] / URIs? I have not thought to take a look at some of them. The reason is to have the same solution for both libconfig and Json parser. I have also worked to factorize more functions and the internal representation of the tree, but some differences remain. libconfig has less features compared to JSON and the way I have found to identify a link is to check the type when a group is expected. That means a link works in this implementation for "root" (board + selction) and for images / files / scripts / bootenv, but not for single elements like version / description / filename (and generally, for single attributes). I understand [1] as a rapid way to access inside the JSON document from program, but less how this allow to structure and reuse part of sw-description. > > Furthermore JSON Schema [2] use a special reference object with a "$ref" > entry to support references at any place even for string entries. This > would make the links explicitly and would allow the reuse of filename or > sha256. I can better understand [2], but if this is clear to me for JSON, it is not clear how to map this in libconfig. > > [1] https://tools.ietf.org/html/rfc6901 > > [2] https://json-schema.org/understanding-json-schema/structuring.html > Best regards, Stefano
Hi Stefano, Am 02.11.18 um 10:20 schrieb stefano babic: > Hi Stefan, > > Am 01.11.2018 um 20:47 schrieb Stefan Herbrechtsmeier: >> Hi Stefano, >> >> I like your idea about links in the sw-description and have some >> questions regarding the implementation. >> >> Am 01.11.18 um 18:06 schrieb Stefano Babic: >>> Signed-off-by: Stefano Babic <sbabic@denx.de> >>> --- >>> doc/source/sw-description.rst | 255 ++++++++++++++++++++++++++++++++++ >>> 1 file changed, 255 insertions(+) >>> >>> diff --git a/doc/source/sw-description.rst >>> b/doc/source/sw-description.rst >>> index ec32e8e..cd28a38 100644 >>> --- a/doc/source/sw-description.rst >>> +++ b/doc/source/sw-description.rst [snip] >>> +Using links >>> +----------- >>> + >>> +sw-description can become very complex. Let's think to have just one >>> board, but in multiple >>> +hw revision and they differ in Hardware. Some of them can be grouped >>> together, some of them >>> +require a dedicated section. A way (but not the only one !) could be >>> to add *mode* and selects >>> +the section with `-e stable,<rev number>`. >>> + >>> +:: >>> + >>> + software = >>> + { >>> + version = "0.1.0"; >>> + >>> + myboard = { >>> + stable = { >>> + >>> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, >>> "3.0", "3.1"]; >>> + rev-1.0: { >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev-1.2: { >>> + hardware-compatibility: ["1.2"]; >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev-2.0: { >>> + hardware-compatibility: ["2.0"]; >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev-1.3: { >>> + hardware-compatibility: ["1.3"]; >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + >>> + rev-3.0: >>> + { >>> + hardware-compatibility: ["3.0"]; >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev-3.1: >>> + { >>> + hardware-compatibility: ["3.1"]; >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + } >>> + } >>> + } >>> + >>> +If each of them requires an own section, it is the way to do. Anyway, >>> it is more probable >>> +than revisions can be grouped together, for example board with the >>> same major revision >>> +number could have the same installation instructions. This leads in >>> the example to 3 groups >>> +for rev1.X, rev2.X and rev3.X. Links allow to group section together. >>> When a string is found >>> +when SWUpdate searches for a group (images, files, script, bootenv), >>> it replaces the current path >>> +in the tree with the value of the string. In this way, the example >>> above can be written in this way: >>> + >>> +:: >>> + >>> + software = >>> + { >>> + version = "0.1.0"; >>> + >>> + myboard = { >>> + stable = { >>> + >>> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, >>> "3.0", "3.1"]; >>> + rev-1x: { >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev1.0 = "rev-1x"; >>> + rev1.2 = "rev-1x"; >>> + rev1.3 = "rev-1x"; >>> + rev-2x: { >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev2.0 = "rev-2x"; >>> + >>> + rev-3x: >>> + { >>> + images: ( >>> + ... >>> + ); >>> + scripts: ( >>> + ... >>> + ); >>> + } >>> + rev3.0 = "rev-3x"; >>> + rev3.1 = "rev-3x"; >>> + } >>> + } >>> + } >>> + >>> +The link can be absolute or relative. A relative path has a number of >>> +leading ".." to move the current cursor to the parent leaf of the tree. >>> +In the following example, rev40 sets a link to a "common" section, >>> where `images` >>> +is found. This is sets via a link, too, to a section in the parent node. >>> +The path `software.myboard.stable.common.images` is then replaced by >>> +`software.myboard.stable.trythis` >>> + >>> +:: >>> + >>> + software = >>> + { >>> + version = "1.0"; /* Release Version */ >>> + >>> + hardware-compatibility =["rev10","rev11", "rev20"]; >>> + >>> + myboard:{ >>> + stable:{ >>> + >>> + common: { >>> + images = "..trythis"; >>> + uboot:( >>> + { >>> + name = "bootpart"; value = "2:1"; >>> + } >>> + ); >>> + }; >>> + >>> + trythis: ( >>> + { >>> + filename = "rootfs.ext5"; >>> + device = "/dev/mmcblk0p8"; >>> + } >>> + ); >>> + rev10: >>> + { >>> + images:( >>> + { >>> + filename = "rootfs.ext3"; >>> + device = "/dev/mmcblk0p2"; >>> + } >>> + ); >>> + uboot:( >>> + { >>> + name = "bootpart"; value = "0:2"; >>> + } >>> + ); >>> + }; >>> + rev11 = "rev10"; >>> + rev20 = "rev10"; >>> + rev40 = "common"; >>> + }; >>> + }; >>> + } >> I don't understand you link format. In your example "rev10" is a >> relative link on the same level and "..trythis" a relative link one >> level up. How looks an absolute link or a link three level above? >> > You're right. I have implemented the relative link, there is no absolute > link. The link in this implementation must always go through the path to > the node that is required. > > That means: > rev10 ==> replace current leaf > ..trythis ==> one level up > ....trythis ==> two level up > ......trythis ==> three level up > > Any malformed link that does not point to a correct node in > sw-description results in an error and the parser stops. I think the ".." without any separator is error-prone and not easy to read. The URI could be used for an absolute or relate path inside the document or outside: #./rev10 #../trythis #/software/myboard/trythis ./images.cfg#/rev10 The outside path could be used later to split the sw-description into multiple files and combine them during image creation by append the file content and replace the filename inside the path with a new section (#/images/rev10). >> Why don't you use something like JSON Pointer [1] / URIs? > I have not thought to take a look at some of them. The reason is to have > the same solution for both libconfig and Json parser. I have also worked > to factorize more functions and the internal representation of the tree, > but some differences remain. libconfig has less features compared to > JSON and the way I have found to identify a link is to check the type > when a group is expected. That means a link works in this implementation > for "root" (board + selction) and for images / files / scripts / > bootenv, but not for single elements like version / description / > filename (and generally, for single attributes). > > I understand [1] as a rapid way to access inside the JSON document from > program, but less how this allow to structure and reuse part of > sw-description. > >> Furthermore JSON Schema [2] use a special reference object with a "$ref" >> entry to support references at any place even for string entries. This >> would make the links explicitly and would allow the reuse of filename or >> sha256. > I can better understand [2], but if this is clear to me for JSON, it is > not clear how to map this in libconfig. What about a setting like this: rev11 : { ref = "#./rev10"; } This makes the link explicit and support more features in the future like links for single values or merging of groups. > >> [1] https://tools.ietf.org/html/rfc6901 >> >> [2] https://json-schema.org/understanding-json-schema/structuring.html >> Best regards Stefan
Hi Stefan, On 02/11/18 15:57, Stefan Herbrechtsmeier wrote: > Hi Stefano, > > Am 02.11.18 um 10:20 schrieb stefano babic: > >> Hi Stefan, >> >> Am 01.11.2018 um 20:47 schrieb Stefan Herbrechtsmeier: >>> Hi Stefano, >>> >>> I like your idea about links in the sw-description and have some >>> questions regarding the implementation. >>> >>> Am 01.11.18 um 18:06 schrieb Stefano Babic: >>>> Signed-off-by: Stefano Babic <sbabic@denx.de> >>>> --- >>>> doc/source/sw-description.rst | 255 >>>> ++++++++++++++++++++++++++++++++++ >>>> 1 file changed, 255 insertions(+) >>>> >>>> diff --git a/doc/source/sw-description.rst >>>> b/doc/source/sw-description.rst >>>> index ec32e8e..cd28a38 100644 >>>> --- a/doc/source/sw-description.rst >>>> +++ b/doc/source/sw-description.rst > [snip] > >>>> +Using links >>>> +----------- >>>> + >>>> +sw-description can become very complex. Let's think to have just one >>>> board, but in multiple >>>> +hw revision and they differ in Hardware. Some of them can be grouped >>>> together, some of them >>>> +require a dedicated section. A way (but not the only one !) could be >>>> to add *mode* and selects >>>> +the section with `-e stable,<rev number>`. >>>> + >>>> +:: >>>> + >>>> + software = >>>> + { >>>> + version = "0.1.0"; >>>> + >>>> + myboard = { >>>> + stable = { >>>> + >>>> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, >>>> "3.0", "3.1"]; >>>> + rev-1.0: { >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev-1.2: { >>>> + hardware-compatibility: ["1.2"]; >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev-2.0: { >>>> + hardware-compatibility: ["2.0"]; >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev-1.3: { >>>> + hardware-compatibility: ["1.3"]; >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + >>>> + rev-3.0: >>>> + { >>>> + hardware-compatibility: ["3.0"]; >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev-3.1: >>>> + { >>>> + hardware-compatibility: ["3.1"]; >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + } >>>> + } >>>> + } >>>> + >>>> +If each of them requires an own section, it is the way to do. Anyway, >>>> it is more probable >>>> +than revisions can be grouped together, for example board with the >>>> same major revision >>>> +number could have the same installation instructions. This leads in >>>> the example to 3 groups >>>> +for rev1.X, rev2.X and rev3.X. Links allow to group section together. >>>> When a string is found >>>> +when SWUpdate searches for a group (images, files, script, bootenv), >>>> it replaces the current path >>>> +in the tree with the value of the string. In this way, the example >>>> above can be written in this way: >>>> + >>>> +:: >>>> + >>>> + software = >>>> + { >>>> + version = "0.1.0"; >>>> + >>>> + myboard = { >>>> + stable = { >>>> + >>>> + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, >>>> "3.0", "3.1"]; >>>> + rev-1x: { >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev1.0 = "rev-1x"; >>>> + rev1.2 = "rev-1x"; >>>> + rev1.3 = "rev-1x"; >>>> + rev-2x: { >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev2.0 = "rev-2x"; >>>> + >>>> + rev-3x: >>>> + { >>>> + images: ( >>>> + ... >>>> + ); >>>> + scripts: ( >>>> + ... >>>> + ); >>>> + } >>>> + rev3.0 = "rev-3x"; >>>> + rev3.1 = "rev-3x"; >>>> + } >>>> + } >>>> + } >>>> + >>>> +The link can be absolute or relative. A relative path has a number of >>>> +leading ".." to move the current cursor to the parent leaf of the >>>> tree. >>>> +In the following example, rev40 sets a link to a "common" section, >>>> where `images` >>>> +is found. This is sets via a link, too, to a section in the parent >>>> node. >>>> +The path `software.myboard.stable.common.images` is then replaced by >>>> +`software.myboard.stable.trythis` >>>> + >>>> +:: >>>> + >>>> + software = >>>> + { >>>> + version = "1.0"; /* Release Version */ >>>> + >>>> + hardware-compatibility =["rev10","rev11", "rev20"]; >>>> + >>>> + myboard:{ >>>> + stable:{ >>>> + >>>> + common: { >>>> + images = "..trythis"; >>>> + uboot:( >>>> + { >>>> + name = "bootpart"; value = "2:1"; >>>> + } >>>> + ); >>>> + }; >>>> + >>>> + trythis: ( >>>> + { >>>> + filename = "rootfs.ext5"; >>>> + device = "/dev/mmcblk0p8"; >>>> + } >>>> + ); >>>> + rev10: >>>> + { >>>> + images:( >>>> + { >>>> + filename = "rootfs.ext3"; >>>> + device = "/dev/mmcblk0p2"; >>>> + } >>>> + ); >>>> + uboot:( >>>> + { >>>> + name = "bootpart"; value = "0:2"; >>>> + } >>>> + ); >>>> + }; >>>> + rev11 = "rev10"; >>>> + rev20 = "rev10"; >>>> + rev40 = "common"; >>>> + }; >>>> + }; >>>> + } >>> I don't understand you link format. In your example "rev10" is a >>> relative link on the same level and "..trythis" a relative link one >>> level up. How looks an absolute link or a link three level above? >>> >> You're right. I have implemented the relative link, there is no absolute >> link. The link in this implementation must always go through the path to >> the node that is required. >> >> That means: >> rev10 ==> replace current leaf >> ..trythis ==> one level up >> ....trythis ==> two level up >> ......trythis ==> three level up >> >> Any malformed link that does not point to a correct node in >> sw-description results in an error and the parser stops. > > I think the ".." without any separator is error-prone and not easy to read. > Right, this was more simple as readable. > The URI could be used for an absolute or relate path inside the document > or outside: > #./rev10 > #../trythis > #/software/myboard/trythis > ./images.cfg#/rev10 ok - I will change in this direction. > > The outside path could be used later to split the sw-description into > multiple > files and combine them during image creation by append the file content > and replace > the filename inside the path with a new section (#/images/rev10). > > >>> Why don't you use something like JSON Pointer [1] / URIs? >> I have not thought to take a look at some of them. The reason is to have >> the same solution for both libconfig and Json parser. I have also worked >> to factorize more functions and the internal representation of the tree, >> but some differences remain. libconfig has less features compared to >> JSON and the way I have found to identify a link is to check the type >> when a group is expected. That means a link works in this implementation >> for "root" (board + selction) and for images / files / scripts / >> bootenv, but not for single elements like version / description / >> filename (and generally, for single attributes). >> >> I understand [1] as a rapid way to access inside the JSON document from >> program, but less how this allow to structure and reuse part of >> sw-description. >> >>> Furthermore JSON Schema [2] use a special reference object with a "$ref" >>> entry to support references at any place even for string entries. This >>> would make the links explicitly and would allow the reuse of filename or >>> sha256. >> I can better understand [2], but if this is clear to me for JSON, it is >> not clear how to map this in libconfig. > > What about a setting like this: > rev11 : { > ref = "#./rev10"; > } > > This makes the link explicit and support more features in the future > like links for single values or merging of groups. ok, good. I will move to an explicit link instead of an implicite as I thought before. Thanks for review. Best regards, Stefano
diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index ec32e8e..cd28a38 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -251,6 +251,261 @@ 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. + +Using links +----------- + +sw-description can become very complex. Let's think to have just one board, but in multiple +hw revision and they differ in Hardware. Some of them can be grouped together, some of them +require a dedicated section. A way (but not the only one !) could be to add *mode* and selects +the section with `-e stable,<rev number>`. + +:: + + software = + { + version = "0.1.0"; + + myboard = { + stable = { + + hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, "3.0", "3.1"]; + rev-1.0: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-1.2: { + hardware-compatibility: ["1.2"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-2.0: { + hardware-compatibility: ["2.0"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-1.3: { + hardware-compatibility: ["1.3"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + + rev-3.0: + { + hardware-compatibility: ["3.0"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-3.1: + { + hardware-compatibility: ["3.1"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + } + } + } + +If each of them requires an own section, it is the way to do. Anyway, it is more probable +than revisions can be grouped together, for example board with the same major revision +number could have the same installation instructions. This leads in the example to 3 groups +for rev1.X, rev2.X and rev3.X. Links allow to group section together. When a string is found +when SWUpdate searches for a group (images, files, script, bootenv), it replaces the current path +in the tree with the value of the string. In this way, the example above can be written in this way: + +:: + + software = + { + version = "0.1.0"; + + myboard = { + stable = { + + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, "3.0", "3.1"]; + rev-1x: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev1.0 = "rev-1x"; + rev1.2 = "rev-1x"; + rev1.3 = "rev-1x"; + rev-2x: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev2.0 = "rev-2x"; + + rev-3x: + { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev3.0 = "rev-3x"; + rev3.1 = "rev-3x"; + } + } + } + +The link can be absolute or relative. A relative path has a number of +leading ".." to move the current cursor to the parent leaf of the tree. +In the following example, rev40 sets a link to a "common" section, where `images` +is found. This is sets via a link, too, to a section in the parent node. +The path `software.myboard.stable.common.images` is then replaced by +`software.myboard.stable.trythis` + +:: + + software = + { + version = "1.0"; /* Release Version */ + + hardware-compatibility =["rev10","rev11", "rev20"]; + + myboard:{ + stable:{ + + common: { + images = "..trythis"; + uboot:( + { + name = "bootpart"; value = "2:1"; + } + ); + }; + + trythis: ( + { + filename = "rootfs.ext5"; + device = "/dev/mmcblk0p8"; + } + ); + rev10: + { + images:( + { + filename = "rootfs.ext3"; + device = "/dev/mmcblk0p2"; + } + ); + uboot:( + { + name = "bootpart"; value = "0:2"; + } + ); + }; + rev11 = "rev10"; + rev20 = "rev10"; + rev40 = "common"; + }; + }; + } + + + + hardware-compatibility ----------------------
Signed-off-by: Stefano Babic <sbabic@denx.de> --- doc/source/sw-description.rst | 255 ++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+)