Skip to contentSkip to conversation

cmd: pxe: add alias devicetree-overlay for fdtoverlays

PATCH Superseded Edoardo Tomelleri 3 participants 4 messages Sep 19, 2022 – Sep 21, 2022

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 cmd: pxe: add alias devicetree-overlay for fdtoverlays

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.

---

 boot/pxe_utils.c       |  2 ++
 doc/README.pxe         |  4 ++++
 doc/develop/distro.rst | 26 ++++++++++++++++++++++++++
 3 files changed, 32 insertions(+)
boot/pxe_utils.c +2 -0
index a364fa8bb5..d5c215ae2c 100644
@@ -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,},
doc/README.pxe +4 -0
index 75caa01c4a..14aa078d52 100644
@@ -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
doc/develop/distro.rst +26 -0
index 3ee3dac6a2..920e173548 100644
@@ -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"
Signature · 1 line
2.37.3
#2 lore raw
In reply to Neil Armstrong

Hello Neil,

Quoted 3 lines

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

#1 lore raw
In reply to Edoardo Tomelleri

Hi,

Quoted 5 lines · 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.

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.

Quoted 102 lines

---

  boot/pxe_utils.c       |  2 ++
  doc/README.pxe         |  4 ++++
  doc/develop/distro.rst | 26 ++++++++++++++++++++++++++
  3 files changed, 32 insertions(+)
boot/pxe_utils.c +2 -0
index a364fa8bb5..d5c215ae2c 100644
@@ -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,},
doc/README.pxe +4 -0
index 75caa01c4a..14aa078d52 100644
@@ -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
doc/develop/distro.rst +26 -0
index 3ee3dac6a2..920e173548 100644
@@ -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"
#3 lore raw
In reply to Edoardo Tomelleri
Quoted 7 lines · Edoardo Tomelleri

Hello Neil,

Quoted 3 lines

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

Quoted 6 lines

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