| Message ID | 20181114160221.18242-6-sbabic@denx.de |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Support for links into sw-description. | expand |
Hi Stefano, Am 14.11.18 um 17:02 schrieb Stefano Babic: > Signed-off-by: Stefano Babic <sbabic@denx.de> > --- > > Changes in v2: None > > doc/source/sw-description.rst | 225 ++++++++++++++++++++++++++++++++++ > 1 file changed, 225 insertions(+) > > diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst > index 36c02b2..51fe670 100644 > --- a/doc/source/sw-description.rst > +++ b/doc/source/sw-description.rst > @@ -318,6 +318,231 @@ while another device can have raw flash and install an UBI filesystem. Neverthel > 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 The "string" should be replaced by "ref" entry. > +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 = { > + ref = "#../rev-1x"; I'm not sure if the ref should be "#./rev-1x" or "#../rev-1x". In my opinion the ref means that "rev1.0" is replaced by "rev-1x". Because both have the same parent I would use "#./rev-1x". Otherwise this would mean that you use a child of the old object as the new object. What happens if the child itself have a child with the same name? I haven't found any example for a relative URI fragment. > + } > + rev1.2 = { > + ref = "#../rev-1x"; > + } > + rev1.3 = { > + ref = "#../rev-1x"; > + } > + rev-2x: { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev2.0 = { > + ref = "#../rev-2x"; > + } > + > + rev-3x: > + { > + images: ( > + ... > + ); > + scripts: ( > + ... > + ); > + } > + rev3.0 = { > + ref = "#../rev-3x"; > + } > + rev3.1 = { > + ref = "#../rev-3x"; > + } > + } > + } > + } > + The formatting looks wrong. > +The link can be absolute or relative. The keyword *"ref"* is used to indicate a link. If this is found, SWUpdate > +will traverse the tree and replaces the current path with the values find in the string pointed by "ref". There are > +simple rules for a link: > + > + - it must start with the character '#' > + - "." points to the current level in the tree > + - ".." points to the parent level in the tree > + - "/" is used as filed separator in the link > + > + > +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 = { > + ref = "#../commonversion"; > + } > + > + hardware-compatibility = ["rev10", "rev11", "rev20"]; > + > + commonversion = "0.7-linked"; > + > + pc:{ > + stable:{ > + > + common:{ > + images = > + { > + ref = "#../../trythis"; > + } > + }; > + > + trythis:( > + { > + filename = "rootfs1.ext4"; > + device = "/dev/mmcblk0p8"; > + type = "raw"; > + } , > + { > + filename = "rootfs5.ext4"; > + device = "/dev/mmcblk0p7"; > + type = "raw"; > + } > + ); > + pdm3rev10: > + { > + images:( > + { > + filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";} > + ); > + uboot:( > + { name = "bootpart"; > + value = "0:2";} > + ); > + }; > + pdm3rev11 = > + { > + ref = "#../pdm3rev10"; > + } > + pdm3rev20 = > + { > + ref = "#../pdm3rev10"; > + } > + pdm3rev40 = > + { > + ref = "#../common"; > + } > + }; > + }; > + } > + > + > +Each entry in sw-description can be redirect by a link as in the above example for the > +"version" attribute. > + > hardware-compatibility > ---------------------- > > Best regards Stefan
Hi Stefan, On 24/11/18 00:22, Stefan Herbrechtsmeier wrote: > Hi Stefano, > > Am 14.11.18 um 17:02 schrieb Stefano Babic: >> Signed-off-by: Stefano Babic <sbabic@denx.de> >> --- >> >> Changes in v2: None >> >> doc/source/sw-description.rst | 225 ++++++++++++++++++++++++++++++++++ >> 1 file changed, 225 insertions(+) >> >> diff --git a/doc/source/sw-description.rst >> b/doc/source/sw-description.rst >> index 36c02b2..51fe670 100644 >> --- a/doc/source/sw-description.rst >> +++ b/doc/source/sw-description.rst >> @@ -318,6 +318,231 @@ while another device can have raw flash and >> install an UBI filesystem. Neverthel >> 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 > > The "string" should be replaced by "ref" entry. ok > >> +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 = { >> + ref = "#../rev-1x"; > > I'm not sure if the ref should be "#./rev-1x" or "#../rev-1x". Well, it is how the rule (and the related implementation) is defined. I choose the rule to have the full path including the last leaf,that means: software/myboard/rev-10/ref The path for rev-1x is then software/myboard/rev-1x, that means I have to go one level up to myboard. That means ../rev-1x. I agree that there could be different way to see the rule, and probably all of them makes sense. The most important thing is that this is well described in doc and that is clear how to traverse the tree. > > In my opinion the ref means that "rev1.0" is replaced by "rev-1x". > Because both have the same parent I would use "#./rev-1x". Otherwise > this would mean that you use a child of the old object as the new > object. What happens if the child itself have a child with the same name? rev1.0 = { ref = "#./rev-1x"; rev-1x = { ... } This should work, too, even if I do not know if it makes sense. In any case, the recursive function to traverse the tree has a depth check, and bouncing forever in the tree is avoided - at the end, the parser returns with error. > > I haven't found any example for a relative URI fragment. > >> + } >> + rev1.2 = { >> + ref = "#../rev-1x"; >> + } >> + rev1.3 = { >> + ref = "#../rev-1x"; >> + } >> + rev-2x: { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev2.0 = { >> + ref = "#../rev-2x"; >> + } >> + >> + rev-3x: >> + { >> + images: ( >> + ... >> + ); >> + scripts: ( >> + ... >> + ); >> + } >> + rev3.0 = { >> + ref = "#../rev-3x"; >> + } >> + rev3.1 = { >> + ref = "#../rev-3x"; >> + } >> + } >> + } >> + } >> + > > The formatting looks wrong. I check it. > >> +The link can be absolute or relative. The keyword *"ref"* is used to >> indicate a link. If this is found, SWUpdate >> +will traverse the tree and replaces the current path with the values >> find in the string pointed by "ref". There are >> +simple rules for a link: >> + >> + - it must start with the character '#' >> + - "." points to the current level in the tree >> + - ".." points to the parent level in the tree >> + - "/" is used as filed separator in the link >> + >> + >> +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 = { >> + ref = "#../commonversion"; >> + } >> + >> + hardware-compatibility = ["rev10", "rev11", "rev20"]; >> + >> + commonversion = "0.7-linked"; >> + >> + pc:{ >> + stable:{ >> + >> + common:{ >> + images = >> + { >> + ref = "#../../trythis"; >> + } >> + }; >> + >> + trythis:( >> + { >> + filename = "rootfs1.ext4"; >> + device = "/dev/mmcblk0p8"; >> + type = "raw"; >> + } , >> + { >> + filename = "rootfs5.ext4"; >> + device = "/dev/mmcblk0p7"; >> + type = "raw"; >> + } >> + ); >> + pdm3rev10: >> + { >> + images:( >> + { >> + filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";} >> + ); >> + uboot:( >> + { name = "bootpart"; >> + value = "0:2";} >> + ); >> + }; >> + pdm3rev11 = >> + { >> + ref = "#../pdm3rev10"; >> + } >> + pdm3rev20 = >> + { >> + ref = "#../pdm3rev10"; >> + } >> + pdm3rev40 = >> + { >> + ref = "#../common"; >> + } >> + }; >> + }; >> + } >> + >> + >> +Each entry in sw-description can be redirect by a link as in the >> above example for the >> +"version" attribute. >> + >> hardware-compatibility >> ---------------------- >> > Best regards, Stefano
Hi Stefano, Am 24.11.18 um 10:51 schrieb Stefano Babic: > On 24/11/18 00:22, Stefan Herbrechtsmeier wrote: >> Am 14.11.18 um 17:02 schrieb Stefano Babic: >>> Signed-off-by: Stefano Babic <sbabic@denx.de> >>> --- >>> >>> Changes in v2: None >>> >>> doc/source/sw-description.rst | 225 ++++++++++++++++++++++++++++++++++ >>> 1 file changed, 225 insertions(+) >>> >>> diff --git a/doc/source/sw-description.rst >>> b/doc/source/sw-description.rst >>> index 36c02b2..51fe670 100644 >>> --- a/doc/source/sw-description.rst >>> +++ b/doc/source/sw-description.rst >>> @@ -318,6 +318,231 @@ while another device can have raw flash and [snip] >>> + >>> +:: >>> + >>> + 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 = { >>> + ref = "#../rev-1x"; >> >> I'm not sure if the ref should be "#./rev-1x" or "#../rev-1x". > > Well, it is how the rule (and the related implementation) is defined. I'm not sure if the rule is optimal because you will use the '#../' mainly. Other solutions remove the leaf from the path. Relative links on the file system are relative to link location source and a relative URL as a href inside a HTML document use the base URI. > I > choose the rule to have the full path including the last leaf,that means: > > software/myboard/rev-10/ref I think you mean the path without 'ref': /software/myboard/rev-10 /software/myboard/rev-10/../rev-1x > The path for rev-1x is then software/myboard/rev-1x, that means I have > to go one level up to myboard. That means ../rev-1x. > > I agree that there could be different way to see the rule, and probably > all of them makes sense. The most important thing is that this is well > described in doc and that is clear how to traverse the tree. Do you see a use case which needs a reference inside the leaf? >> In my opinion the ref means that "rev1.0" is replaced by "rev-1x". >> Because both have the same parent I would use "#./rev-1x". Otherwise >> this would mean that you use a child of the old object as the new >> object. What happens if the child itself have a child with the same name? > > rev1.0 = { > ref = "#./rev-1x"; > rev-1x = { > ... > } > > This should work, too, even if I do not know if it makes sense. In any > case, the recursive function to traverse the tree has a depth check, and > bouncing forever in the tree is avoided - at the end, the parser returns > with error. The problem is that you always have to use the '#../' to avoid strange behaviors: a = { b = { ref = "#./rev-1' c = { c = "c1" d = "d1" e = "e1" } e = "e2" } } /a/b/c == { c = "c1"; d = "d1"; e = "e1"; } /a/b/d == "d1" /a/b/e == "e2" If you always remove the last leaf you have to place the nodes side by side: a = { b = { ref = "#./rev-1' e = "e2" } c = { c = "c1"; d = "d1"; e = "e1"; } } /a/b/c == "c1" /a/b/d == "d1" /a/b/e == "e2" Best regards Stefan
Hi Stefan, On 25/11/18 18:14, Stefan Herbrechtsmeier wrote: > Hi Stefano, > > Am 24.11.18 um 10:51 schrieb Stefano Babic: >> On 24/11/18 00:22, Stefan Herbrechtsmeier wrote: >>> Am 14.11.18 um 17:02 schrieb Stefano Babic: >>>> Signed-off-by: Stefano Babic <sbabic@denx.de> >>>> --- >>>> >>>> Changes in v2: None >>>> >>>> doc/source/sw-description.rst | 225 >>>> ++++++++++++++++++++++++++++++++++ >>>> 1 file changed, 225 insertions(+) >>>> >>>> diff --git a/doc/source/sw-description.rst >>>> b/doc/source/sw-description.rst >>>> index 36c02b2..51fe670 100644 >>>> --- a/doc/source/sw-description.rst >>>> +++ b/doc/source/sw-description.rst >>>> @@ -318,6 +318,231 @@ while another device can have raw flash and > > [snip] > >>>> + >>>> +:: >>>> + >>>> + 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 = { >>>> + ref = "#../rev-1x"; >>> >>> I'm not sure if the ref should be "#./rev-1x" or "#../rev-1x". >> >> Well, it is how the rule (and the related implementation) is defined. > > I'm not sure if the rule is optimal because you will use the '#../' > mainly. That's true. > Other solutions remove the leaf from the path. This is the other solution. I thought to this, too. IMHO it is important to define this. I would disagree if we change this in future, because it makes sw-description incompatible between SWUpdate releases. And it makes no sense to introduce a CONFIG_ to have a different interpretation. Now we have no SWUpdate release providing this and we can still change how the link is interpreted. If you really ask me which is the best, I cannot answer - but I just say that we should stick with the rule we choose. > Relative links on > the file system are relative to link location source and a relative URL > as a href inside a HTML document use the base URI. Of course, and this is an argument to use "#./ref" instead of "#../ref". > >> I >> choose the rule to have the full path including the last leaf,that means: >> >> software/myboard/rev-10/ref > > I think you mean the path without 'ref': > /software/myboard/rev-10 > /software/myboard/rev-10/../rev-1x > >> The path for rev-1x is then software/myboard/rev-1x, that means I have >> to go one level up to myboard. That means ../rev-1x. >> >> I agree that there could be different way to see the rule, and probably >> all of them makes sense. The most important thing is that this is well >> described in doc and that is clear how to traverse the tree. > > Do you see a use case which needs a reference inside the leaf? Personally, not. I have just thought if I have to block this, as I do if I allow just "#./ref" instead of "#../ref". The second one allows both, even if I do not currently seen a use case. Anyway, SWUpdate users have proofed to be so creative and they introduce use cases that I never thought about... Anyway, it could be fine to use "#./ref" instead of "#../ref". I just wait if someone else wants to comment this and push some points for one or the other rule. If not, I move to your suggestion as I cannot find myself a (useful) case where I need a link inside the same leaf. > >>> In my opinion the ref means that "rev1.0" is replaced by "rev-1x". >>> Because both have the same parent I would use "#./rev-1x". Otherwise >>> this would mean that you use a child of the old object as the new >>> object. What happens if the child itself have a child with the same >>> name? >> >> rev1.0 = { >> ref = "#./rev-1x"; >> rev-1x = { >> ... >> } >> >> This should work, too, even if I do not know if it makes sense. In any >> case, the recursive function to traverse the tree has a depth check, and >> bouncing forever in the tree is avoided - at the end, the parser returns >> with error. > > The problem is that you always have to use the '#../' to avoid strange > behaviors: Yes - it becomes mandatory. > > a = { > b = { > ref = "#./rev-1' > c = { > c = "c1" > d = "d1" > e = "e1" > } > e = "e2" > } > } > > /a/b/c == { c = "c1"; d = "d1"; e = "e1"; } > /a/b/d == "d1" > /a/b/e == "e2" > > If you always remove the last leaf you have to place the nodes side by > side: > > a = { > b = { > ref = "#./rev-1' > e = "e2" > } > c = { > c = "c1"; > d = "d1"; > e = "e1"; > } > } > > /a/b/c == "c1" > /a/b/d == "d1" > /a/b/e == "e2" > ok - so small vote, you have (good) arguments to remove the last leaf. In case I do not see any other comments against this, I'll switch to remove the last leaf. Best regards, Stefano
Hi Stefano, Am 26.11.18 um 11:57 schrieb Stefano Babic: > On 25/11/18 18:14, Stefan Herbrechtsmeier wrote: >> Am 24.11.18 um 10:51 schrieb Stefano Babic: >>> On 24/11/18 00:22, Stefan Herbrechtsmeier wrote: >>>> Am 14.11.18 um 17:02 schrieb Stefano Babic: >>>>> Signed-off-by: Stefano Babic <sbabic@denx.de> >>>>> --- >>>>> >>>>> Changes in v2: None >>>>> >>>>> doc/source/sw-description.rst | 225 >>>>> ++++++++++++++++++++++++++++++++++ >>>>> 1 file changed, 225 insertions(+) >>>>> >>>>> diff --git a/doc/source/sw-description.rst >>>>> b/doc/source/sw-description.rst >>>>> index 36c02b2..51fe670 100644 >>>>> --- a/doc/source/sw-description.rst >>>>> +++ b/doc/source/sw-description.rst >>>>> @@ -318,6 +318,231 @@ while another device can have raw flash and >> >> [snip] >> >>>>> + >>>>> +:: >>>>> + >>>>> + 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 = { >>>>> + ref = "#../rev-1x"; >>>> >>>> I'm not sure if the ref should be "#./rev-1x" or "#../rev-1x". >>> >>> Well, it is how the rule (and the related implementation) is defined. >> >> I'm not sure if the rule is optimal because you will use the '#../' >> mainly. > > That's true. > >> Other solutions remove the leaf from the path. > > This is the other solution. I thought to this, too. IMHO it is important > to define this. I would disagree if we change this in future, because it > makes sw-description incompatible between SWUpdate releases. And it > makes no sense to introduce a CONFIG_ to have a different interpretation. > > Now we have no SWUpdate release providing this and we can still change > how the link is interpreted. If you really ask me which is the best, I > cannot answer - but I just say that we should stick with the rule we choose. > >> Relative links on >> the file system are relative to link location source and a relative URL >> as a href inside a HTML document use the base URI. > > Of course, and this is an argument to use "#./ref" instead of "#../ref". > > >> >>> I >>> choose the rule to have the full path including the last leaf,that means: >>> >>> software/myboard/rev-10/ref >> >> I think you mean the path without 'ref': >> /software/myboard/rev-10 >> /software/myboard/rev-10/../rev-1x >> >>> The path for rev-1x is then software/myboard/rev-1x, that means I have >>> to go one level up to myboard. That means ../rev-1x. >>> >>> I agree that there could be different way to see the rule, and probably >>> all of them makes sense. The most important thing is that this is well >>> described in doc and that is clear how to traverse the tree. >> >> Do you see a use case which needs a reference inside the leaf? > > Personally, not. I have just thought if I have to block this, as I do if > I allow just "#./ref" instead of "#../ref". The second one allows both, > even if I do not currently seen a use case. Anyway, SWUpdate users have > proofed to be so creative and they introduce use cases that I never > thought about... > > Anyway, it could be fine to use "#./ref" instead of "#../ref". I just > wait if someone else wants to comment this and push some points for one > or the other rule. If not, I move to your suggestion as I cannot find > myself a (useful) case where I need a link inside the same leaf. > >> >>>> In my opinion the ref means that "rev1.0" is replaced by "rev-1x". >>>> Because both have the same parent I would use "#./rev-1x". Otherwise >>>> this would mean that you use a child of the old object as the new >>>> object. What happens if the child itself have a child with the same >>>> name? >>> >>> rev1.0 = { >>> ref = "#./rev-1x"; >>> rev-1x = { >>> ... >>> } >>> >>> This should work, too, even if I do not know if it makes sense. In any >>> case, the recursive function to traverse the tree has a depth check, and >>> bouncing forever in the tree is avoided - at the end, the parser returns >>> with error. >> >> The problem is that you always have to use the '#../' to avoid strange >> behaviors: > > Yes - it becomes mandatory. > >> >> a = { >> b = { >> ref = "#./rev-1' >> c = { >> c = "c1" >> d = "d1" >> e = "e1" >> } >> e = "e2" >> } >> } >> >> /a/b/c == { c = "c1"; d = "d1"; e = "e1"; } >> /a/b/d == "d1" >> /a/b/e == "e2" >> >> If you always remove the last leaf you have to place the nodes side by >> side: >> >> a = { >> b = { >> ref = "#./rev-1' >> e = "e2" >> } >> c = { >> c = "c1"; >> d = "d1"; >> e = "e1"; >> } >> } >> >> /a/b/c == "c1" >> /a/b/d == "d1" >> /a/b/e == "e2" >> > > ok - so small vote, you have (good) arguments to remove the last leaf. > In case I do not see any other comments against this, I'll switch to > remove the last leaf. Thank you that you consider my concerns. Best regards Stefan
diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index 36c02b2..51fe670 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -318,6 +318,231 @@ while another device can have raw flash and install an UBI filesystem. Neverthel 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 = { + ref = "#../rev-1x"; + } + rev1.2 = { + ref = "#../rev-1x"; + } + rev1.3 = { + ref = "#../rev-1x"; + } + rev-2x: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev2.0 = { + ref = "#../rev-2x"; + } + + rev-3x: + { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev3.0 = { + ref = "#../rev-3x"; + } + rev3.1 = { + ref = "#../rev-3x"; + } + } + } + } + +The link can be absolute or relative. The keyword *"ref"* is used to indicate a link. If this is found, SWUpdate +will traverse the tree and replaces the current path with the values find in the string pointed by "ref". There are +simple rules for a link: + + - it must start with the character '#' + - "." points to the current level in the tree + - ".." points to the parent level in the tree + - "/" is used as filed separator in the link + + +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 = { + ref = "#../commonversion"; + } + + hardware-compatibility = ["rev10", "rev11", "rev20"]; + + commonversion = "0.7-linked"; + + pc:{ + stable:{ + + common:{ + images = + { + ref = "#../../trythis"; + } + }; + + trythis:( + { + filename = "rootfs1.ext4"; + device = "/dev/mmcblk0p8"; + type = "raw"; + } , + { + filename = "rootfs5.ext4"; + device = "/dev/mmcblk0p7"; + type = "raw"; + } + ); + pdm3rev10: + { + images:( + { + filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";} + ); + uboot:( + { name = "bootpart"; + value = "0:2";} + ); + }; + pdm3rev11 = + { + ref = "#../pdm3rev10"; + } + pdm3rev20 = + { + ref = "#../pdm3rev10"; + } + pdm3rev40 = + { + ref = "#../common"; + } + }; + }; + } + + +Each entry in sw-description can be redirect by a link as in the above example for the +"version" attribute. + hardware-compatibility ----------------------
Signed-off-by: Stefano Babic <sbabic@denx.de> --- Changes in v2: None doc/source/sw-description.rst | 225 ++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+)