[PATCH] cmd: pxe: add alias devicetree-overlay for fdtoverlays

[Neil Armstrong]

Hi,

On 19/09/2022 20:50, Edoardo Tomelleri wrote:
> This adds keyword devicetree-overlay as an alias for fdtoverlays in
> extlinux (sysboot) and pxe to better follow the Boot Loader Specification,
> improves documentation around them by adding an example for both
> fdtoverlays and devicetree-overlay and the environment variable required
> for this feature.

The patch looks fine, especially the doc part which is a great +

Concerning the alias name, can you specify in the patch the link to the
Boot Loader Specification ? And probably update the PXE doc but reusing
the same wording.

> 
> Signed-off-by: Edoardo Tomelleri <e.tomell at gmail.com>
> ---
> 
>   boot/pxe_utils.c       |  2 ++
>   doc/README.pxe         |  4 ++++
>   doc/develop/distro.rst | 26 ++++++++++++++++++++++++++
>   3 files changed, 32 insertions(+)
> 
> diff --git a/boot/pxe_utils.c b/boot/pxe_utils.c
> index a364fa8bb5..d5c215ae2c 100644
> --- a/boot/pxe_utils.c
> +++ b/boot/pxe_utils.c
> @@ -380,6 +380,7 @@ err:
>   
>   /**
>    * label_boot_fdtoverlay() - Loads fdt overlays specified in 'fdtoverlays'
> + * or 'devicetree-overlay'
>    *
>    * @ctx: PXE context
>    * @label: Label to process
> @@ -809,6 +810,7 @@ static const struct token keywords[] = {
>   	{"devicetreedir", T_FDTDIR},
>   	{"fdtdir", T_FDTDIR},
>   	{"fdtoverlays", T_FDTOVERLAYS},
> +	{"devicetree-overlay", T_FDTOVERLAYS},
>   	{"ontimeout", T_ONTIMEOUT,},
>   	{"ipappend", T_IPAPPEND,},
>   	{"background", T_BACKGROUND,},
> diff --git a/doc/README.pxe b/doc/README.pxe
> index 75caa01c4a..14aa078d52 100644
> --- a/doc/README.pxe
> +++ b/doc/README.pxe
> @@ -163,6 +163,8 @@ fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT
>                         and then applied in the load order to the fdt blob stored at the
>                         address indicated in the fdt_addr_r environment variable.
>   
> +devicetree-overlay <path> [...] - alias for fdtoverlays, see above.
> +
>   kaslrseed           - set this label to request random number from hwrng as kaslr seed.
>   
>   append <string>	    - use <string> as the kernel command line when booting this
> @@ -178,6 +180,8 @@ fdt <path>	    - if this label is chosen, use tftp to retrieve the fdt blob
>   		      the fdt_addr_r environment variable, and that address will
>   		      be passed to bootm.
>   
> +devicetree <path>   - alias for fdt, see above.
> +
>   fdtdir <path>	    - if this label is chosen, use tftp to retrieve a fdt blob
>   		      relative to <path>. If the fdtfile environment variable
>   		      is set, <path>/<fdtfile> is retrieved. Otherwise, the
> diff --git a/doc/develop/distro.rst b/doc/develop/distro.rst
> index 3ee3dac6a2..920e173548 100644
> --- a/doc/develop/distro.rst
> +++ b/doc/develop/distro.rst
> @@ -81,6 +81,8 @@ as specified at BootLoaderSpec_:
>   * Does not document the fdtdir option, which automatically selects the DTB to
>     pass to the kernel.
>   
> +See also doc/README.pxe under 'pxe file format'.
> +
>   One example extlinux.conf generated by the Fedora installer is::
>   
>       # extlinux.conf generated by anaconda
> @@ -115,6 +117,25 @@ One example extlinux.conf generated by the Fedora installer is::
>           fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
>   
>   
> +One example of hand-crafted extlinux.conf::
> +
> +   menu title Select kernel
> +   timeout 100
> +
> +   label Arch with uart devicetree overlay
> +       kernel /arch/Image.gz
> +       initrd /arch/initramfs-linux.img
> +       fdt /dtbs/arch/board.dtb
> +       fdtoverlays /dtbs/arch/overlay/uart0-gpio0-1.dtbo
> +       append console=ttyS0,115200 console=tty1 rw root=UUID=fc0d0284-ca84-4194-bf8a-4b9da8d66908
> +
> +   label Arch with uart devicetree overlay but with Boot Loader Specification keys
> +       kernel /arch/Image.gz
> +       initrd /arch/initramfs-linux.img
> +       devicetree /dtbs/arch/board.dtb
> +       devicetree-overlay /dtbs/arch/overlay/uart0-gpio0-1.dtbo
> +       append console=ttyS0,115200 console=tty1 rw root=UUID=fc0d0284-ca84-4194-bf8a-4b9da8d66908
> +
>   Another hand-crafted network boot configuration file is::
>   
>       TIMEOUT 100
> @@ -214,6 +235,11 @@ fdt_addr_r:
>   
>     A size of 1MB for the FDT/DTB seems reasonable.
>   
> +fdtoverlay_addr_r:
> +  Mandatory. The location in RAM where DTB overlays will be temporarily
> +  stored and then applied in the load order to the fdt blob stored at the
> +  address indicated in the fdt_addr_r environment variable.
> +
>   fdtfile:
>     Mandatory. the name of the DTB file for the specific board for instance
>     the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb"