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

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

[Edoardo Tomelleri]

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.

Signed-off-by: Edoardo Tomelleri <e.tomell@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"
-- 
2.37.3

Re: [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@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"

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

[Edoardo Tomelleri]

Hello Neil,

> 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.
I'm not sure I understand what you mean about the PXE doc, is it better if the
devicetree and devicetree-overlay keywords have the same description as
fdt and fdtoverlays instead of just a reference, or you are you referring to the
what I've added to distro.rst, like examples? The PXE doc already mentions
required environment variables, so there is not much left to add.
Thanks,
Edoardo

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

[Art Nikpal]

On Tue, Sep 20, 2022 at 7:30 PM Edoardo Tomelleri <e.tomell@gmail.com> wrote:
>
> Hello Neil,
>
> > 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.
> I'm not sure I understand what you mean about the PXE doc, is it better if the

grep ^fdt doc/README.pxe
fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT
fdt <path>        - if this label is chosen, use tftp to retrieve the fdt blob
fdtdir <path>        - if this label is chosen, use tftp to retrieve a fdt blob

> devicetree and devicetree-overlay keywords have the same description as
> fdt and fdtoverlays instead of just a reference, or you are you referring to the
> what I've added to distro.rst, like examples? The PXE doc already mentions
> required environment variables, so there is not much left to add.
> Thanks,
> Edoardo