| Message ID | 20250819160431.382820-1-joaomarcos.costa@bootlin.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | ref-manual/variables.rst: expand IMAGE_OVERHEAD_FACTOR glossary entry | expand |
Hi Joao, On 8/19/25 6:04 PM, Joao Marcos Costa via lists.yoctoproject.org wrote: > From: Joao Marcos Costa <joaomarcos.costa@bootlin.com> > > There's a (second) overhead factor applied in images generated with Wic, > and this is already documented in the .wks reference. However, the > IMAGE_OVERHEAD_FACTOR entry does not mention it, and by looking at the > partition sizes (e.g. with parted) one may find it confusing that they > don't match with the expected rootfs size (e.g. in a scenario where the > extra space is "0" and IMAGE_OVERHEAD_FACTOR="1.0"). > > This second overhead is already documented, though: > https://docs.yoctoproject.org/ref-manual/kickstart.html#command-part-or-partition > > Mention the '--overhead-factor' option in the glossary entry and add a > reference to the wks documentation. > I'm wondering if this isn't rather a bug than a feature? Why would we need to have two overhead factors? Also, I'm wondering if this isn't a case of: - IMAGE_OVERHEAD_FACTOR for setting an overhead factor for the filesystem - --overhead-factor for setting an overhead factor for the partition In which case you would have a filesystem which doesn't take the whole partition. I assume if you have systemd-growfs/systemd-repart it'll take the whole partition at first boot? Both would have a valid use-case. I imagine that it'd be perfectly fine to have an overhead-factor of 0 for a filesystem that already has an overhead (e.g. for journaling). > Signed-off-by: Joao Marcos Costa <joaomarcos.costa@bootlin.com> > --- > documentation/ref-manual/variables.rst | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index d559899c6..c18bc7ba4 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -4166,6 +4166,11 @@ system and gives an overview of their function and contents. > added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` > variable. > > + When using Wic tool, beware that a second overhead factor is also applied. > + This overhead's value is defined by the ``--overhead-factor`` option, and Gut feeling says we shouldn't us "'s" here. How this sentence is worded could be interpreted like so: "I do not put --overhead-factor so there is no overhead factor" whereas what actually happens is that the default is 30% if this argument is missing. > + not by :term:`IMAGE_OVERHEAD_FACTOR`. See the > + ":doc:`/ref-manual/kickstart`" chapter for details. Maybe we could point at the section (command: part or partition) since that parameter only applies to that? Cheers, Quentin
Hello, Quentin On 8/22/25 16:32, Quentin Schulz wrote: > Hi Joao, > > On 8/19/25 6:04 PM, Joao Marcos Costa via lists.yoctoproject.org wrote: >> From: Joao Marcos Costa <joaomarcos.costa@bootlin.com> >> >> There's a (second) overhead factor applied in images generated with Wic, >> and this is already documented in the .wks reference. However, the >> IMAGE_OVERHEAD_FACTOR entry does not mention it, and by looking at the >> partition sizes (e.g. with parted) one may find it confusing that they >> don't match with the expected rootfs size (e.g. in a scenario where the >> extra space is "0" and IMAGE_OVERHEAD_FACTOR="1.0"). >> >> This second overhead is already documented, though: >> https://docs.yoctoproject.org/ref-manual/kickstart.html#command-part-or-partition >> >> Mention the '--overhead-factor' option in the glossary entry and add a >> reference to the wks documentation. >> > > I'm wondering if this isn't rather a bug than a feature? > > Why would we need to have two overhead factors? > > Also, I'm wondering if this isn't a case of: > - IMAGE_OVERHEAD_FACTOR for setting an overhead factor for the filesystem > - --overhead-factor for setting an overhead factor for the partition > > In which case you would have a filesystem which doesn't take the whole > partition. I assume if you have systemd-growfs/systemd-repart it'll take > the whole partition at first boot? Even though I like the idea of having a partition size coherent with what was defined by those IMAGE_* variables, I wouldn't say this is a bug. I see it rather as undocumented behavior, hence this patch. > Both would have a valid use-case. I imagine that it'd be perfectly fine > to have an overhead-factor of 0 for a filesystem that already has an > overhead (e.g. for journaling). A "no overhead" would actually be "1.0" (since this is a multiplier), not "0.0", right? > >> Signed-off-by: Joao Marcos Costa <joaomarcos.costa@bootlin.com> >> --- >> documentation/ref-manual/variables.rst | 5 +++++ >> 1 file changed, 5 insertions(+) >> >> diff --git a/documentation/ref-manual/variables.rst >> b/documentation/ref-manual/variables.rst >> index d559899c6..c18bc7ba4 100644 >> --- a/documentation/ref-manual/variables.rst >> +++ b/documentation/ref-manual/variables.rst >> @@ -4166,6 +4166,11 @@ system and gives an overview of their function >> and contents. >> added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` >> variable. >> + When using Wic tool, beware that a second overhead factor is >> also applied. >> + This overhead's value is defined by the ``--overhead-factor`` >> option, and > > Gut feeling says we shouldn't us "'s" here. Not sure if I got your point here. Is there any link between the "'s" and the possible misinterpretation? > > How this sentence is worded could be interpreted like so: > > "I do not put --overhead-factor so there is no overhead factor" > > whereas what actually happens is that the default is 30% if this > argument is missing. I'm not sure about the likelihood of this (mistaken) conclusion, since I refer to it as "a second overhead factor is also applied" rather than "may/could be applied". Maybe replacing "defined" by something more bullet-proof? I'm open to suggestions. > >> + not by :term:`IMAGE_OVERHEAD_FACTOR`. See the >> + ":doc:`/ref-manual/kickstart`" chapter for details. > > Maybe we could point at the section (command: part or partition) since > that parameter only applies to that? Agreed. > Cheers, > Quentin Thanks for the review.
Hi Joao, On 8/29/25 9:36 AM, Joao Marcos Costa wrote: > Hello, Quentin > > On 8/22/25 16:32, Quentin Schulz wrote: >> Hi Joao, >> >> On 8/19/25 6:04 PM, Joao Marcos Costa via lists.yoctoproject.org wrote: >>> From: Joao Marcos Costa <joaomarcos.costa@bootlin.com> >>> >>> There's a (second) overhead factor applied in images generated with Wic, >>> and this is already documented in the .wks reference. However, the >>> IMAGE_OVERHEAD_FACTOR entry does not mention it, and by looking at the >>> partition sizes (e.g. with parted) one may find it confusing that they >>> don't match with the expected rootfs size (e.g. in a scenario where the >>> extra space is "0" and IMAGE_OVERHEAD_FACTOR="1.0"). >>> >>> This second overhead is already documented, though: >>> https://eur02.safelinks.protection.outlook.com/? >>> url=https%3A%2F%2Fdocs.yoctoproject.org%2Fref- >>> manual%2Fkickstart.html%23command-part-or- >>> partition&data=05%7C02%7Cquentin.schulz%40cherry.de%7Ce48ea4510efd49c6331b08dde6ced62b%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C638920498249508207%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=sVfz7%2Fa8eR9YyX71dpb05PmJIg3DKkpVRiIlVhaAMUY%3D&reserved=0 >>> >>> Mention the '--overhead-factor' option in the glossary entry and add a >>> reference to the wks documentation. >>> >> >> I'm wondering if this isn't rather a bug than a feature? >> >> Why would we need to have two overhead factors? >> >> Also, I'm wondering if this isn't a case of: >> - IMAGE_OVERHEAD_FACTOR for setting an overhead factor for the filesystem >> - --overhead-factor for setting an overhead factor for the partition >> >> In which case you would have a filesystem which doesn't take the whole >> partition. I assume if you have systemd-growfs/systemd-repart it'll >> take the whole partition at first boot? > > Even though I like the idea of having a partition size coherent with > what was defined by those IMAGE_* variables, I wouldn't say this is a > bug. I see it rather as undocumented behavior, hence this patch. > >> Both would have a valid use-case. I imagine that it'd be perfectly >> fine to have an overhead-factor of 0 for a filesystem that already has >> an overhead (e.g. for journaling). > A "no overhead" would actually be "1.0" (since this is a multiplier), > not "0.0", right? > Correct. >> >>> Signed-off-by: Joao Marcos Costa <joaomarcos.costa@bootlin.com> >>> --- >>> documentation/ref-manual/variables.rst | 5 +++++ >>> 1 file changed, 5 insertions(+) >>> >>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ >>> ref-manual/variables.rst >>> index d559899c6..c18bc7ba4 100644 >>> --- a/documentation/ref-manual/variables.rst >>> +++ b/documentation/ref-manual/variables.rst >>> @@ -4166,6 +4166,11 @@ system and gives an overview of their function >>> and contents. >>> added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` >>> variable. >>> + When using Wic tool, beware that a second overhead factor is >>> also applied. >>> + This overhead's value is defined by the ``--overhead-factor`` >>> option, and >> >> Gut feeling says we shouldn't us "'s" here. > > Not sure if I got your point here. Is there any link between the "'s" > and the possible misinterpretation? > Not related no. It's just that "This overhead's value" sounds wrong to me, but I'm not a native speaker so it might just be that my intuition is wrong here :) Can be easily replaced with "This overhead" if you want. >> >> How this sentence is worded could be interpreted like so: >> >> "I do not put --overhead-factor so there is no overhead factor" >> >> whereas what actually happens is that the default is 30% if this >> argument is missing. > > I'm not sure about the likelihood of this (mistaken) conclusion, since I > refer to it as "a second overhead factor is also applied" rather than > "may/could be applied". Maybe replacing "defined" by something more > bullet-proof? I'm open to suggestions. > "--overhead factor option, which defaults to 1.3 when omitted, " for example? Cheers, Quentin
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index d559899c6..c18bc7ba4 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -4166,6 +4166,11 @@ system and gives an overview of their function and contents. added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` variable. + When using Wic tool, beware that a second overhead factor is also applied. + This overhead's value is defined by the ``--overhead-factor`` option, and + not by :term:`IMAGE_OVERHEAD_FACTOR`. See the + ":doc:`/ref-manual/kickstart`" chapter for details. + :term:`IMAGE_PKGTYPE` Defines the package type (i.e. DEB, RPM or IPK) used by the OpenEmbedded build system. The variable is defined appropriately by