[PATCH 1/2] Documentation: document querying of barebox version

[PATCH 1/2] Documentation: document querying of barebox version

[Ahmad Fatoum]

We have a short reference to barebox-version fixup in the device tree section
of the manual. Expand on this by adding a proper documentation section.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/user-manual.rst |  1 +
 Documentation/user/versioning.rst  | 57 ++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 Documentation/user/versioning.rst

diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 83ba9e4c3505..b8272b2235e4 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -33,6 +33,7 @@ Contents:
    reset-reason
    system-reset
    state
+   versioning
    random
    optee
    debugging
diff --git a/Documentation/user/versioning.rst b/Documentation/user/versioning.rst
new file mode 100644
index 000000000000..0eb04158efd3
--- /dev/null
+++ b/Documentation/user/versioning.rst
@@ -0,0 +1,57 @@
+.. _versioning:
+
+barebox Artifact Versioning
+===========================
+
+In addition to the usual barebox release (e.g. ``v2025.03.0``), the
+version number can be extended to encode integrator specific version
+information:
+
+  * When built from git, ``scripts/setlocalversion`` will factor in
+    git revision information into the version string.
+  * The ``EXTRAVERSION = `` in the top-level ``Makefile`` can be used
+    to add a suffix to the version. This is useful if patches are applied
+    on top of the tarball release.
+  * The build host can set the ``BUILDSYSTEM_VERSION`` environment variable
+    prior to executing ``make`` to encode a board support package version.
+    This is useful to encode information about built-in environment
+    and firmware.
+
+Query from barebox
+^^^^^^^^^^^^^^^^^^
+
+When ``CONFIG_BANNER`` is enabled, the version information will be printed
+to the console. From the shell, there is the
+:ref:`version command <command_version>` for interactive use and the
+``global.version`` and ``global.buildsystem.version`` :ref:`magicvars`
+for use in scripts.
+
+Query from OS
+^^^^^^^^^^^^^
+
+The barebox version (formatted as ``barebox-$version``) can be queried
+after boot by different means:
+
+ * If the OS is booted with device tree, barebox will fixup a
+   ``/chosen/barebox-version`` property into the kernel device tree with
+   the version string. Under Linux, this can be accessed at:
+   * ``/sys/firmware/devicetree/base/chosen/barebox-version``
+   * ``/proc/device-tree/base/chosen/barebox-version``
+
+ * If the system is booted through barebox as EFI application (payload),
+   a ``LoaderInfo`` EFI variable with the systemd vendor GUID will
+   be set to the version string. Under Linux, the string is shown in
+   ``bootctl`` output
+
+Query without booting
+^^^^^^^^^^^^^^^^^^^^^
+
+If the barebox boot medium is known, ``bareboximd`` can be used
+to read the barebox :ref:`imd`, provided that barebox was
+compiled with ``CONFIG_IMD=y``::
+
+  linux$ bareboximd /dev/mmc2.boot0 -t release
+  2025.03.0-20250403-1
+
+  barebox$ imd /dev/mmc2.boot0 -t release
+  2025.03.0-20250403-1
-- 
2.39.5

[PATCH 2/2] Documentation: devicetree: add of_diff hint for visualizing fixups

[Ahmad Fatoum]

of_diff - + is a very nifty tool, so make sure to mention it in the
documentation.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/devicetree/index.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst
index 2ca8b72be1ac..94e8d04f63c3 100644
--- a/Documentation/devicetree/index.rst
+++ b/Documentation/devicetree/index.rst
@@ -174,3 +174,12 @@ In the ``chosen``-node, barebox fixes up
 
 These values can be read from the booted linux system in ``/proc/device-tree/``
 or ``/sys/firmware/devicetree/base``.
+
+To see a dry run of what barebox would fixup, the ``of_diff`` command can be
+used::
+
+  # Diff before and after applying fixups on barebox DT
+  of_diff - +
+
+  # Diff kernel device tree before and after fixups
+  of_diff /mnt/mmc2.0/boot/imx6q-tx6q.dtb +
-- 
2.39.5

Re: [PATCH 1/2] Documentation: document querying of barebox version

[Enrico Jörns]

Am Mittwoch, dem 16.04.2025 um 11:35 +0200 schrieb Ahmad Fatoum:
> We have a short reference to barebox-version fixup in the device tree section
> of the manual. Expand on this by adding a proper documentation section.

Many thanks for documenting this!

> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> ---
>  Documentation/user/user-manual.rst |  1 +
>  Documentation/user/versioning.rst  | 57 ++++++++++++++++++++++++++++++
>  2 files changed, 58 insertions(+)
>  create mode 100644 Documentation/user/versioning.rst
> 
> diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
> index 83ba9e4c3505..b8272b2235e4 100644
> --- a/Documentation/user/user-manual.rst
> +++ b/Documentation/user/user-manual.rst
> @@ -33,6 +33,7 @@ Contents:
>     reset-reason
>     system-reset
>     state
> +   versioning
>     random
>     optee
>     debugging
> diff --git a/Documentation/user/versioning.rst b/Documentation/user/versioning.rst
> new file mode 100644
> index 000000000000..0eb04158efd3
> --- /dev/null
> +++ b/Documentation/user/versioning.rst
> @@ -0,0 +1,57 @@
> +.. _versioning:
> +
> +barebox Artifact Versioning
> +===========================
> +
> +In addition to the usual barebox release (e.g. ``v2025.03.0``), the
> +version number can be extended to encode integrator specific version

s/integrator specific/integration-specific/

since I hope it is more a question of the environment than the individual person 🙂.

> +information:
> +
> +  * When built from git, ``scripts/setlocalversion`` will factor in
> +    git revision information into the version string.
> +  * The ``EXTRAVERSION = `` in the top-level ``Makefile`` can be used
> +    to add a suffix to the version. This is useful if patches are applied
> +    on top of the tarball release.
> +  * The build host can set the ``BUILDSYSTEM_VERSION`` environment variable
> +    prior to executing ``make`` to encode a board support package version.
> +    This is useful to encode information about built-in environment
> +    and firmware.
> +
> +Query from barebox
> +^^^^^^^^^^^^^^^^^^
> +
> +When ``CONFIG_BANNER`` is enabled, the version information will be printed
> +to the console. From the shell, there is the
> +:ref:`version command <command_version>` for interactive use and the
> +``global.version`` and ``global.buildsystem.version`` :ref:`magicvars`
> +for use in scripts.
> +
> +Query from OS
> +^^^^^^^^^^^^^
> +
> +The barebox version (formatted as ``barebox-$version``) can be queried
> +after boot by different means:
> +
> + * If the OS is booted with device tree, barebox will fixup a
> +   ``/chosen/barebox-version`` property into the kernel device tree with
> +   the version string. Under Linux, this can be accessed at:

Not fully sure about the markup here, but this might require an empty line.

> +   * ``/sys/firmware/devicetree/base/chosen/barebox-version``
> +   * ``/proc/device-tree/base/chosen/barebox-version``
> +
> + * If the system is booted through barebox as EFI application (payload),
> +   a ``LoaderInfo`` EFI variable with the systemd vendor GUID will
> +   be set to the version string. Under Linux, the string is shown in
> +   ``bootctl`` output
> +
> +Query without booting
> +^^^^^^^^^^^^^^^^^^^^^
> +
> +If the barebox boot medium is known, ``bareboximd`` can be used
> +to read the barebox :ref:`imd`, provided that barebox was
> +compiled with ``CONFIG_IMD=y``::
> +
> +  linux$ bareboximd /dev/mmc2.boot0 -t release
> +  2025.03.0-20250403-1
> +
> +  barebox$ imd /dev/mmc2.boot0 -t release
> +  2025.03.0-20250403-1

Might CONFIG_IMD_TARGET required here, too?


Regards, Enrico

-- 
Pengutronix e.K.                           | Enrico Jörns                |
Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |