Message ID | 20250225222442.3347665-1-adrian.freihofer@siemens.com |
---|---|
State | Accepted |
Headers | show |
Series | [v4] ref-manual: cover UBOOT_ENV variables | expand |
Hi Adrian, On 2/25/25 11:24 PM, Adrian Freihofer via lists.yoctoproject.org wrote: > Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com> > --- > documentation/ref-manual/variables.rst | 63 ++++++++++++++++++++++++++ > 1 file changed, 63 insertions(+) > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index adbef69d8f3..a3d59390cd1 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -3180,6 +3180,31 @@ system and gives an overview of their function and contents. > The default value for this variable is set to "2048" > by the :ref:`ref-classes-kernel-fitimage` class. > > + :term:`FIT_UBOOT_ENV` > + This variable allows to add a U-Boot script as a text file to the > + FIT image. Such a script can be sourced from the U-Boot shell. > + > + When inheriting the :ref:`ref-classes-kernel-fitimage` class a > + script file should be included in the :term:`SRC_URI` of the Linux > + kernel recipe. > + > + Example: > + > + - Add a script ``boot.cmd`` to the Linux kernel recipe:: > + > + FIT_UBOOT_ENV = "boot.cmd" > + SRC_URI += "file://${FIT_UBOOT_ENV}" > + > + - Use the script file from the U-Boot shell. The name of the script in > + FIT image is ``bootscr-${FIT_UBOOT_ENV}``. This example loads the FIT > + image from a TFTP server:: > + > + tftp $loadaddr $fit_tftp_path > + source $loadaddr#bootscr-boot.cmd > + > + More information can be found in the official U-Boot documentation: > + `U-Boot source command <https://docs.u-boot.org/en/latest/usage/cmd/source.html#fit-image.f>`__ > + > :term:`FONT_EXTRA_RDEPENDS` > When inheriting the :ref:`ref-classes-fontcache` class, > this variable specifies the runtime dependencies for font packages. > @@ -9791,6 +9816,44 @@ system and gives an overview of their function and contents. > :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` > classes. > > + :term:`UBOOT_ENV` > + This variable allows to add additional environment variables or a script > + to be installed together with U-Boot. > + This file, typically ``uEnv.txt`` or ``boot.cmd``, is installed in > + ``/boot`` as well as copied to the :term:`DEPLOYDIR` directory. > + > + For machine configurations needing one of these files a ``.bbappend`` > + file should include it in the :term:`SRC_URI` of the U-Boot recipe. > + > + If the variable :term:`UBOOT_ENV_SUFFIX` is set to ``scr`` the script is > + packaged as a uImage (``mkimage -T script..``) otherwise it gets > + installed verbatim. > + > + Some examples: > + > + - Adding a script ``boot.cmd`` as a uImage to ``/boot``:: > + > + UBOOT_ENV = "boot" > + UBOOT_ENV_SUFFIX = "scr" > + SRC_URI += "file://${UBOOT_ENV_SRC}" > + > + - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``:: > + > + UBOOT_ENV = "uEnv" > + UBOOT_ENV_SUFFIX = "txt" > + SRC_URI += "file://${UBOOT_ENV_BINARY}" > + It is indeed odd to specify UBOOT_ENV_BINARY/UBOOT_ENV_SRC out of nowhere. We could state that one should use UBOOT_ENV_BINARY when referencing the uboot environment in any form, to be installed. And UBOOT_ENV_SRC when referring to the source script that will be installed as uImage, otherwise use UBOOT_ENV_BINARY. Considering setting UBOOT_ENV_SRC_SUFFIX to txt would allow use to use UBOOT_ENV_SRC for every example above, maybe we should do that instead so it's less confusing? Then we would only need to specify what UBOOT_ENV_SRC means in a note (or in a new term in the glossary), e.g. that it defaults to ${UBOOT_ENV}.${UBOOT_ENV_SRC_SUFFIX}? What do you think? In any case, this looks good to me, therefore: Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Thanks! Quentin
Applied, thanks! [1/1] ref-manual: cover UBOOT_ENV variables commit: dc2ff96a3401eba8dac86fc8305b261be52c8a13 Best regards,
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index adbef69d8f3..a3d59390cd1 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -3180,6 +3180,31 @@ system and gives an overview of their function and contents. The default value for this variable is set to "2048" by the :ref:`ref-classes-kernel-fitimage` class. + :term:`FIT_UBOOT_ENV` + This variable allows to add a U-Boot script as a text file to the + FIT image. Such a script can be sourced from the U-Boot shell. + + When inheriting the :ref:`ref-classes-kernel-fitimage` class a + script file should be included in the :term:`SRC_URI` of the Linux + kernel recipe. + + Example: + + - Add a script ``boot.cmd`` to the Linux kernel recipe:: + + FIT_UBOOT_ENV = "boot.cmd" + SRC_URI += "file://${FIT_UBOOT_ENV}" + + - Use the script file from the U-Boot shell. The name of the script in + FIT image is ``bootscr-${FIT_UBOOT_ENV}``. This example loads the FIT + image from a TFTP server:: + + tftp $loadaddr $fit_tftp_path + source $loadaddr#bootscr-boot.cmd + + More information can be found in the official U-Boot documentation: + `U-Boot source command <https://docs.u-boot.org/en/latest/usage/cmd/source.html#fit-image.f>`__ + :term:`FONT_EXTRA_RDEPENDS` When inheriting the :ref:`ref-classes-fontcache` class, this variable specifies the runtime dependencies for font packages. @@ -9791,6 +9816,44 @@ system and gives an overview of their function and contents. :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` classes. + :term:`UBOOT_ENV` + This variable allows to add additional environment variables or a script + to be installed together with U-Boot. + This file, typically ``uEnv.txt`` or ``boot.cmd``, is installed in + ``/boot`` as well as copied to the :term:`DEPLOYDIR` directory. + + For machine configurations needing one of these files a ``.bbappend`` + file should include it in the :term:`SRC_URI` of the U-Boot recipe. + + If the variable :term:`UBOOT_ENV_SUFFIX` is set to ``scr`` the script is + packaged as a uImage (``mkimage -T script..``) otherwise it gets + installed verbatim. + + Some examples: + + - Adding a script ``boot.cmd`` as a uImage to ``/boot``:: + + UBOOT_ENV = "boot" + UBOOT_ENV_SUFFIX = "scr" + SRC_URI += "file://${UBOOT_ENV_SRC}" + + - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``:: + + UBOOT_ENV = "uEnv" + UBOOT_ENV_SUFFIX = "txt" + SRC_URI += "file://${UBOOT_ENV_BINARY}" + + :term:`UBOOT_ENV_SRC_SUFFIX` + If :term:`UBOOT_ENV_SUFFIX` is set to ``scr`` this is the suffix of the + plain text script file as it is specified in the :term:`SRC_URI` of the + U-Boot recipe. It defaults to ``cmd``. + + :term:`UBOOT_ENV_SUFFIX` + If this variable is set to ``scr`` the script referred to by + :term:`UBOOT_ENV` gets packaged as a uImage before it gets installed. + The default is ``txt`` which means the script is installed as-is, with + no modification. + :term:`UBOOT_FIT_ADDRESS_CELLS` Specifies the value of the ``#address-cells`` value for the description of the U-Boot FIT image.
Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com> --- documentation/ref-manual/variables.rst | 63 ++++++++++++++++++++++++++ 1 file changed, 63 insertions(+)