Skip to contentSkip to conversation

cmd: pxe: add alias devicetree-overlay for fdtoverlays

PATCH In review Edoardo Tomelleri 4 participants 6 messages Sep 21, 2022 – Oct 11, 2022

lore
Share & tools
lore
#0 lore raw

PATCH v2 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 [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

---

Changes in v2:
- Updated link to Boot Loader Specification
- Added link to Boot Loader Specification to the patch commit
- Changed README.pxe reusing the same wording as of the aliased commands

 boot/pxe_utils.c       |  2 ++
 doc/README.pxe         | 12 ++++++++++++
 doc/develop/distro.rst | 32 +++++++++++++++++++++++++++++---
 3 files changed, 43 insertions(+), 3 deletions(-)
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 +12 -0
index 75caa01c4a..d14d2bdcc9 100644
@@ -163,6 +163,13 @@ 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> [...] - if this label is chosen, use tftp to retrieve the DT
+                      overlay(s) at <path>. it will be temporarily stored at the
+                      address indicated in the fdtoverlay_addr_r environment variable,
+                      and then applied in the load order to the fdt blob stored at the
+                      address indicated in the fdt_addr_r environment variable.
+                      Alias for fdtoverlays.
+
 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 +185,11 @@ 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>   - if this label is chosen, use tftp to retrieve the fdt blob
+		      at <path>. it will be stored at the address indicated in
+		      the fdt_addr_r environment variable, and that address will
+		      be passed to bootm. Alias for fdt.
+
 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 +29 -3
index 3ee3dac6a2..bc72aa951e 100644
@@ -68,10 +68,10 @@ Boot Configuration Files
 
 The standard format for boot configuration files is that of extlinux.conf, as
 handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
-as specified at BootLoaderSpec_:
+as specified at `Boot Loader Specification`_:
 
 
-... with the exceptions that the BootLoaderSpec document:
+... with the exceptions that the Boot Loader Specification document:
 
 * Prescribes a separate configuration per boot menu option, whereas U-Boot
   lumps all options into a single extlinux.conf file. Hence, U-Boot searches
@@ -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"
@@ -408,7 +434,7 @@ way in future u-boot versions.  In particular the <device type>_boot
 variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
 detail and must not be used as a public interface.
 
-.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
 
 .. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
 .. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
Signature · 1 line
2.37.3
Reviewed-by on v2 1/1
#1 lore raw
Quoted 136 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 [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

---

Changes in v2:
- Updated link to Boot Loader Specification
- Added link to Boot Loader Specification to the patch commit
- Changed README.pxe reusing the same wording as of the aliased commands

  boot/pxe_utils.c       |  2 ++
  doc/README.pxe         | 12 ++++++++++++
  doc/develop/distro.rst | 32 +++++++++++++++++++++++++++++---
  3 files changed, 43 insertions(+), 3 deletions(-)
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 +12 -0
index 75caa01c4a..d14d2bdcc9 100644
@@ -163,6 +163,13 @@ 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> [...] - if this label is chosen, use tftp to retrieve the DT
+                      overlay(s) at <path>. it will be temporarily stored at the
+                      address indicated in the fdtoverlay_addr_r environment variable,
+                      and then applied in the load order to the fdt blob stored at the
+                      address indicated in the fdt_addr_r environment variable.
+                      Alias for fdtoverlays.
+
  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 +185,11 @@ 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>   - if this label is chosen, use tftp to retrieve the fdt blob
+		      at <path>. it will be stored at the address indicated in
+		      the fdt_addr_r environment variable, and that address will
+		      be passed to bootm. Alias for fdt.
+
  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 +28 -2
index 3ee3dac6a2..bc72aa951e 100644
@@ -68,10 +68,10 @@ Boot Configuration Files
 
  The standard format for boot configuration files is that of extlinux.conf, as
  handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
-as specified at BootLoaderSpec_:
+as specified at `Boot Loader Specification`_:
 
 
-... with the exceptions that the BootLoaderSpec document:
+... with the exceptions that the Boot Loader Specification document:
 
  * Prescribes a separate configuration per boot menu option, whereas U-Boot
    lumps all options into a single extlinux.conf file. Hence, U-Boot searches
@@ -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"

doc/develop/distro.rst way in future u-boot versions. In particular the <device type>_boot · line 440

Quoted 8 lines
doc/develop/distro.rst +1 -1
@@ -408,7 +434,7 @@ way in future u-boot versions.  In particular the <device type>_boot
  variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
  detail and must not be used as a public interface.
 
-.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
 
  .. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
  .. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.

Thanks for updating the doc and link to the spec !

#2 lore raw

No problem, I noticed that I forgot to update the link when you asked to add it to the commit message.

Il giorno mer 21 set 2022 alle ore 15:30 Neil Armstrong <[email protected]> ha scritto:

Quoted 150 lines · Edoardo Tomelleri
Quoted 136 lines

This adds keyword devicetree-overlay as an alias for fdtoverlays in extlinux (sysboot) and pxe to better follow the Boot Loader Specification [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

---

Changes in v2:
- Updated link to Boot Loader Specification
- Added link to Boot Loader Specification to the patch commit
- Changed README.pxe reusing the same wording as of the aliased commands

  boot/pxe_utils.c       |  2 ++
  doc/README.pxe         | 12 ++++++++++++
  doc/develop/distro.rst | 32 +++++++++++++++++++++++++++++---
  3 files changed, 43 insertions(+), 3 deletions(-)
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 +12 -0
index 75caa01c4a..d14d2bdcc9 100644
@@ -163,6 +163,13 @@ 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> [...] - if this label is chosen, use tftp to retrieve the DT
+                      overlay(s) at <path>. it will be temporarily stored at the
+                      address indicated in the fdtoverlay_addr_r environment variable,
+                      and then applied in the load order to the fdt blob stored at the
+                      address indicated in the fdt_addr_r environment variable.
+                      Alias for fdtoverlays.
+
  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 +185,11 @@ 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>   - if this label is chosen, use tftp to retrieve the fdt blob
+                   at <path>. it will be stored at the address indicated in
+                   the fdt_addr_r environment variable, and that address will
+                   be passed to bootm. Alias for fdt.
+
  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 +28 -2
index 3ee3dac6a2..bc72aa951e 100644
@@ -68,10 +68,10 @@ Boot Configuration Files
 
  The standard format for boot configuration files is that of extlinux.conf, as
  handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
-as specified at BootLoaderSpec_:
+as specified at `Boot Loader Specification`_:
 
 
-... with the exceptions that the BootLoaderSpec document:
+... with the exceptions that the Boot Loader Specification document:
 
  * Prescribes a separate configuration per boot menu option, whereas U-Boot
    lumps all options into a single extlinux.conf file. Hence, U-Boot searches
@@ -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"

doc/develop/distro.rst way in future u-boot versions. In particular the <device type>_boot · line 440

Quoted 8 lines
doc/develop/distro.rst +1 -1
@@ -408,7 +434,7 @@ way in future u-boot versions.  In particular the <device type>_boot
  variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
  detail and must not be used as a public interface.
 
-.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
 
  .. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
  .. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.

Thanks for updating the doc and link to the spec !

#3 lore raw

Hello,
is there any issue remaining with this patch? Will this be accepted for 2022.10 release?
Thanks,
Edoardo

Il giorno mer 21 set 2022 alle ore 15:41 Edoardo Tomelleri <[email protected]> ha scritto:

Quoted 156 lines

No problem, I noticed that I forgot to update the link when you asked to add it to the commit message.

Il giorno mer 21 set 2022 alle ore 15:30 Neil Armstrong <[email protected]> ha scritto:

Quoted 150 lines · Edoardo Tomelleri
Quoted 136 lines

This adds keyword devicetree-overlay as an alias for fdtoverlays in extlinux (sysboot) and pxe to better follow the Boot Loader Specification [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

---

Changes in v2:
- Updated link to Boot Loader Specification
- Added link to Boot Loader Specification to the patch commit
- Changed README.pxe reusing the same wording as of the aliased commands

  boot/pxe_utils.c       |  2 ++
  doc/README.pxe         | 12 ++++++++++++
  doc/develop/distro.rst | 32 +++++++++++++++++++++++++++++---
  3 files changed, 43 insertions(+), 3 deletions(-)
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 +12 -0
index 75caa01c4a..d14d2bdcc9 100644
@@ -163,6 +163,13 @@ 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> [...] - if this label is chosen, use tftp to retrieve the DT
+                      overlay(s) at <path>. it will be temporarily stored at the
+                      address indicated in the fdtoverlay_addr_r environment variable,
+                      and then applied in the load order to the fdt blob stored at the
+                      address indicated in the fdt_addr_r environment variable.
+                      Alias for fdtoverlays.
+
  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 +185,11 @@ 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>   - if this label is chosen, use tftp to retrieve the fdt blob
+                   at <path>. it will be stored at the address indicated in
+                   the fdt_addr_r environment variable, and that address will
+                   be passed to bootm. Alias for fdt.
+
  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 +28 -2
index 3ee3dac6a2..bc72aa951e 100644
@@ -68,10 +68,10 @@ Boot Configuration Files
 
  The standard format for boot configuration files is that of extlinux.conf, as
  handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
-as specified at BootLoaderSpec_:
+as specified at `Boot Loader Specification`_:
 
 
-... with the exceptions that the BootLoaderSpec document:
+... with the exceptions that the Boot Loader Specification document:
 
  * Prescribes a separate configuration per boot menu option, whereas U-Boot
    lumps all options into a single extlinux.conf file. Hence, U-Boot searches
@@ -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"

doc/develop/distro.rst way in future u-boot versions. In particular the <device type>_boot · line 440

Quoted 8 lines
doc/develop/distro.rst +1 -1
@@ -408,7 +434,7 @@ way in future u-boot versions.  In particular the <device type>_boot
  variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
  detail and must not be used as a public interface.
 
-.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
 
  .. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
  .. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.

Thanks for updating the doc and link to the spec !

Reviewed-by on v2 1/1
#4 lore raw
In reply to Edoardo Tomelleri
Quoted 146 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 [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

---

Changes in v2:
- Updated link to Boot Loader Specification
- Added link to Boot Loader Specification to the patch commit
- Changed README.pxe reusing the same wording as of the aliased commands

 boot/pxe_utils.c       |  2 ++
 doc/README.pxe         | 12 ++++++++++++
 doc/develop/distro.rst | 32 +++++++++++++++++++++++++++++---
 3 files changed, 43 insertions(+), 3 deletions(-)
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 +12 -0
index 75caa01c4a..d14d2bdcc9 100644
@@ -163,6 +163,13 @@ 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> [...] - if this label is chosen, use tftp to retrieve the DT
+                      overlay(s) at <path>. it will be temporarily stored at the
+                      address indicated in the fdtoverlay_addr_r environment variable,
+                      and then applied in the load order to the fdt blob stored at the
+                      address indicated in the fdt_addr_r environment variable.
+                      Alias for fdtoverlays.
+
 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 +185,11 @@ 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>   - if this label is chosen, use tftp to retrieve the fdt blob
+                     at <path>. it will be stored at the address indicated in
+                     the fdt_addr_r environment variable, and that address will
+                     be passed to bootm. Alias for fdt.
+
 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 +29 -4
index 3ee3dac6a2..bc72aa951e 100644
@@ -68,10 +68,10 @@ Boot Configuration Files
 
 The standard format for boot configuration files is that of extlinux.conf, as
 handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
-as specified at BootLoaderSpec_:
+as specified at `Boot Loader Specification`_:
 
 
-... with the exceptions that the BootLoaderSpec document:
+... with the exceptions that the Boot Loader Specification document:
 
 * Prescribes a separate configuration per boot menu option, whereas U-Boot
   lumps all options into a single extlinux.conf file. Hence, U-Boot searches
@@ -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"
@@ -408,7 +434,7 @@ way in future u-boot versions.  In particular the <device type>_boot
 variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
 detail and must not be used as a public interface.
 
-.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
 
 .. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
 .. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
--
Quoted 2 lines

2.37.3

#5 lore raw
In reply to Edoardo Tomelleri
Quoted 11 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 [1], improves documentation around them by adding an example for both fdtoverlays and devicetree-overlay and the environment variable required for this feature. The link for the spec is updated to the current one.

[1] https://systemd.io/BOOT_LOADER_SPECIFICATION/

Applied to u-boot/master, thanks!

Signature · 1 line
Tom