[PATCH v7 6/7] doc: dtbinding: Update documentation for Generic Firmware loader

[Simon Glass]

Hi Christian,

On 2026-06-16T19:18:35, Christian Marangi <ansuelsmth at gmail.com> wrote:
> doc: dtbinding: Update documentation for Generic Firmware loader
>
> Update documentation for Generic Firmware loader, generalize it from FS
> specific and add new property and example for FIP loader.
>
> Also add details on the usage of 'phandlepart', 'mtdpart' and 'ubivol'
> property.
>
> Signed-off-by: Christian Marangi <ansuelsmth at gmail.com>
>
> .../misc/{fs_loader.txt => fw_loader.txt}          | 33 ++++++++++++++++++++--
>  1 file changed, 30 insertions(+), 3 deletions(-)

> diff --git a/doc/device-tree-bindings/misc/fs_loader.txt b/doc/device-tree-bindings/misc/fw_loader.txt
> @@ -46,3 +56,20 @@ ubi in device tree source as shown in below:
> +     Example for FIP from eMMC:
> +     fs_loader4: fip-loader at 4 {
> +             bootph-all;
> +             compatible = 'u-boot,fip-loader';
> +             phandlepart = <&mmc0 0>;
> +             partoffset = <0x100>;
> +     };
> +
> +     Example for FIP from ubi:
> +     fs_loader4: fip-loader at 4 {
> +             bootph-all;
> +             compatible = 'u-boot,fip-loader';
> +             mtdpart = 'ubi',
> +             ubivol = 'bl31';
> +     };

Two issues. First, both nodes reuse the same label and unit address
(fs_loader4: fip-loader at 4) - please bump the second to fs_loader5:
fip-loader at 5

Second, mtdpart = 'ubi', terminates the property with a comma but
should be a semicolon.

> diff --git a/doc/device-tree-bindings/misc/fs_loader.txt b/doc/device-tree-bindings/misc/fw_loader.txt
> @@ -1,17 +1,27 @@
> +- partoffset: valid ONLY for 'u-boot,fip-loader'. Offset of the partition to
> +           parse the FIP partition from.

Wording is confusing - partition appears twice with different
meanings. I suggest "byte offset within the selected partition where
the FIP header is located". Also worth stating the units (bytes) and
whether the offset must be block-aligned.

> diff --git a/doc/device-tree-bindings/misc/fs_loader.txt b/doc/device-tree-bindings/misc/fw_loader.txt
> @@ -1,17 +1,27 @@
> -- compatible: should contain 'u-boot,fs-loader'
> +- compatible: should contain 'u-boot,fs-loader' or 'u-boot,fip-loader'
> +
> +Optional properties:
> +--------------------
> +
>  - phandlepart: which block storage device and partition the image loading from,

Just to check - phandlepart/mtdpart move from required to optional,
but at least one must be present in practice. Please spell it out,
e.g. "exactly one of phandlepart or mtdpart must be provided".

> diff --git a/doc/device-tree-bindings/misc/fs_loader.txt b/doc/device-tree-bindings/misc/fw_loader.txt
> @@ -1,17 +1,27 @@
> -* File system firmware loader
> +* Generic Firmware loader

BTW new bindings in U-Boot are expected to be YAML schemas (or
upstreamed to dt-schema), not free-form .txt. Since you are
effectively rewriting this binding for a new compatible, it would be a
good opportunity to convert. What do you think?

Regards,
Simon