Re: [PATCH v3 4/8] dm: doc: Update documentation for new driver model schema
Heinrich Schuchardt
xypron.glpk at gmx.de
Thu Feb 2 01:30:18 CET 2023
Am 1. Februar 2023 23:54:24 MEZ schrieb Simon Glass <sjg at chromium.org>:
>Now that Linux has accepted these tags, move U-Boot over to use them.
>Tidy up the comments and formatting, making sure that VPL is mentioned
>too.
>
>Signed-off-by: Simon Glass <sjg at chromium.org>
Should all these documents be converted to yaml (in future) so that we can test devicetrees against schemas like the kernel does?
Best regards
Heinrich
>---
>
>(no changes since v1)
>
> doc/README.TPL | 4 +--
> doc/develop/driver-model/design.rst | 15 +++++------
> .../driver-model/fs_firmware_loader.rst | 4 +--
> doc/develop/driver-model/of-plat.rst | 25 ++++++++++---------
> doc/develop/driver-model/pci-info.rst | 10 ++++----
> doc/develop/driver-model/serial-howto.rst | 24 +++++++++---------
> doc/develop/spl.rst | 5 ++--
> 7 files changed, 45 insertions(+), 42 deletions(-)
>
>diff --git a/doc/README.TPL b/doc/README.TPL
>index 72027fd692e..95b466e4af9 100644
>--- a/doc/README.TPL
>+++ b/doc/README.TPL
>@@ -35,8 +35,8 @@ is set. Source files can be compiled for TPL with options chosen in the
> board config file.
>
> TPL use a small device tree (u-boot-tpl.dtb), containing only the nodes with
>-the pre-relocation properties: 'u-boot,dm-pre-reloc' and 'u-boot,dm-tpl'
>-(see README.SPL for details).
>+the pre-relocation properties: 'bootph-all' and 'bootph-pre-sram'
>+(see doc/develop/spl.rst for details).
>
> For example:
>
>diff --git a/doc/develop/driver-model/design.rst b/doc/develop/driver-model/design.rst
>index 20611e85e34..8c2c81d7ac9 100644
>--- a/doc/develop/driver-model/design.rst
>+++ b/doc/develop/driver-model/design.rst
>@@ -1114,12 +1114,12 @@ Pre-Relocation Support
> ----------------------
>
> For pre-relocation we simply call the driver model init function. Only
>-drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc'
>+drivers marked with DM_FLAG_PRE_RELOC or the device tree 'bootph-all'
> property are initialised prior to relocation. This helps to reduce the driver
> model overhead. This flag applies to SPL and TPL as well, if device tree is
> enabled (CONFIG_OF_CONTROL) there.
>
>-Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc'
>+Note when device tree is enabled, the device tree 'bootph-all'
> property can provide better control granularity on which device is bound
> before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all
> devices with the same driver are bound, which requires allocation a large
>@@ -1128,14 +1128,15 @@ only way for statically declared devices via U_BOOT_DRVINFO() to be bound
> prior to relocation.
>
> It is possible to limit this to specific relocation steps, by using
>-the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags
>-in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper'
>+the more specialized 'bootph-pre-ram' and 'bootph-pre-sram' flags
>+in the device tree node. For U-Boot proper you can use 'bootph-some-ram'
> which means that it will be processed (and a driver bound) in U-Boot proper
> prior to relocation, but will not be available in SPL or TPL.
>
>-To reduce the size of SPL and TPL, only the nodes with pre-relocation properties
>-('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their
>-device trees (see README.SPL for details); the remaining nodes are always bound.
>+To reduce the size of SPL and TPL, only the nodes with pre-relocation
>+properties ('bootph-all', 'bootph-pre-ram' or 'bootph-pre-sram') are kept in
>+their device trees (see README.SPL for details); the remaining nodes are
>+always bound.
>
> Then post relocation we throw that away and re-init driver model again.
> For drivers which require some sort of continuity between pre- and
>diff --git a/doc/develop/driver-model/fs_firmware_loader.rst b/doc/develop/driver-model/fs_firmware_loader.rst
>index a44708cb4c5..b0823700a90 100644
>--- a/doc/develop/driver-model/fs_firmware_loader.rst
>+++ b/doc/develop/driver-model/fs_firmware_loader.rst
>@@ -28,7 +28,7 @@ defined in fs-loader node as shown in below:
> Example for block device::
>
> fs_loader0: fs-loader {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> compatible = "u-boot,fs-loader";
> phandlepart = <&mmc 1>;
> };
>@@ -41,7 +41,7 @@ device, it can be described in FDT as shown in below:
> Example for ubi::
>
> fs_loader1: fs-loader {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> compatible = "u-boot,fs-loader";
> mtdpart = "UBI",
> ubivol = "ubi0";
>diff --git a/doc/develop/driver-model/of-plat.rst b/doc/develop/driver-model/of-plat.rst
>index b454f7be85e..01724ba72ce 100644
>--- a/doc/develop/driver-model/of-plat.rst
>+++ b/doc/develop/driver-model/of-plat.rst
>@@ -67,7 +67,7 @@ device. As an example, consider this MMC node:
> pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
> vmmc-supply = <&vcc_sd>;
> status = "okay";
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> };
>
>
>@@ -632,7 +632,7 @@ the devicetree. For example, if the devicetree has::
> grf: grf at 20008000 {
> compatible = "rockchip,rk3188-grf", "syscon";
> reg = <0x20008000 0x200>;
>- u-boot,dm-spl;
>+ bootph-pre-ram;
> };
>
> then dtoc looks at the first compatible string ("rockchip,rk3188-grf"),
>@@ -685,21 +685,22 @@ indicates that the two nodes have different phase settings. Looking at the
> source .dts::
>
> i2c_emul: emul {
>- u-boot,dm-spl;
>+ bootph-pre-ram;
> reg = <0xff>;
> compatible = "sandbox,i2c-emul-parent";
> emul0: emul0 {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> compatible = "sandbox,i2c-rtc-emul";
> #emul-cells = <0>;
> };
> };
>
>-you can see that the child node 'emul0' usees 'u-boot,dm-pre-reloc', indicating
>-that the node is present in all SPL builds, but its parent uses 'u-boot,dm-spl'
>-indicating it is only present in SPL, not TPL. For a TPL build, this will fail
>-with the above message. The fix is to change 'emul0' to use the same
>-'u-boot,dm-spl' condition, so that it is not present in TPL, like its parent.
>+you can see that the child node 'emul0' usees 'bootph-all', indicating
>+that the node is present in all SPL builds, but its parent uses
>+'bootph-pre-ram' indicating it is only present in SPL, not TPL. For a TPL
>+build, this will fail with the above message. The fix is to change 'emul0' to
>+use the same 'bootph-pre-ram' condition, so that it is not present in TPL,
>+like its parent.
>
> Link errors / undefined reference
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>@@ -715,16 +716,16 @@ you get a link error, e.g.::
> The first one indicates that the device cannot find its driver. This means that
> there is a driver 'sandbox_spl_test' but it is not compiled into the build.
> Check your Kconfig settings to make sure it is. If you don't want that in the
>-build, adjust your phase settings, e.g. by using 'u-boot,dm-spl' in the node
>+build, adjust your phase settings, e.g. by using 'bootph-pre-ram' in the node
> to exclude it from the TPL build::
>
> spl-test5 {
>- u-boot,dm-tpl;
>+ bootph-pre-sram;
> compatible = "sandbox,spl-test";
> stringarray = "tpl";
> };
>
>-We can drop the 'u-boot,dm-tpl' line so this node won't appear in the TPL
>+We can drop the 'bootph-pre-sram' line so this node won't appear in the TPL
> devicetree and thus the driver won't be needed.
>
> The second error above indicates that the MISC uclass is needed by the driver
>diff --git a/doc/develop/driver-model/pci-info.rst b/doc/develop/driver-model/pci-info.rst
>index 251601a51e3..dea595b6cff 100644
>--- a/doc/develop/driver-model/pci-info.rst
>+++ b/doc/develop/driver-model/pci-info.rst
>@@ -52,7 +52,7 @@ their drivers accordingly. A working example like below::
> #address-cells = <3>;
> #size-cells = <2>;
> compatible = "pci-x86";
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000
> 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000
> 0x01000000 0x0 0x2000 0x2000 0 0xe000>;
>@@ -61,14 +61,14 @@ their drivers accordingly. A working example like below::
> #address-cells = <3>;
> #size-cells = <2>;
> compatible = "pci-bridge";
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> reg = <0x0000b800 0x0 0x0 0x0 0x0>;
>
> topcliff at 0,0 {
> #address-cells = <3>;
> #size-cells = <2>;
> compatible = "pci-bridge";
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> reg = <0x00010000 0x0 0x0 0x0 0x0>;
>
> pciuart0: uart at a,1 {
>@@ -77,7 +77,7 @@ their drivers accordingly. A working example like below::
> "pciclass,070002",
> "pciclass,0700",
> "x86-uart";
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> reg = <0x00025100 0x0 0x0 0x0 0x0
> 0x01025110 0x0 0x0 0x0 0x0>;
> ......
>@@ -98,7 +98,7 @@ bus hierarchy: on the root PCI bus, there is a PCIe root port which connects
> to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a
> PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART
> device are on the PCI bus. Like other devices in the device tree, if we want
>-to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared
>+to bind PCI devices before relocation, "bootph-all" must be declared
> in each of these nodes.
>
> If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
>diff --git a/doc/develop/driver-model/serial-howto.rst b/doc/develop/driver-model/serial-howto.rst
>index 5b1d57d83a8..17b53e3cabf 100644
>--- a/doc/develop/driver-model/serial-howto.rst
>+++ b/doc/develop/driver-model/serial-howto.rst
>@@ -62,7 +62,7 @@ what you need. U-Boot automatically includes these files: see :ref:`dttweaks`.
> Here are some things you might need to consider:
>
> 1. The serial driver itself needs to be present before relocation, so that the
>- U-Boot banner appears. Make sure it has a u-boot,dm-pre-reloc tag in the device
>+ U-Boot banner appears. Make sure it has a bootph-all tag in the device
> tree, so that the serial driver is bound when U-Boot starts.
>
> For example, on iMX8::
>@@ -75,11 +75,11 @@ Here are some things you might need to consider:
> put this in your xxx-u-boot.dtsi file::
>
> &lpuart3 {
>- u-boot,dm-pre-proper;
>+ bootph-some-ram;
> };
>
> 2. If your serial port requires a particular pinmux configuration, you may need
>- a pinctrl driver. This needs to have a u-boot,dm-pre-reloc tag also. Take care
>+ a pinctrl driver. This needs to have a bootph-all tag also. Take care
> that any subnodes have the same tag, if they are needed to make the correct
> pinctrl available.
>
>@@ -107,15 +107,15 @@ Here are some things you might need to consider:
> parents, so put this in your xxx-u-boot.dtsi file::
>
> &pinctrl {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> };
>
> &uart2 {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> };
>
> &uart2_xfer {
>- u-boot,dm-pre-reloc;
>+ bootph-all;
> };
>
> 3. The same applies to power domains. For example, if a particular power domain
>@@ -125,11 +125,11 @@ Here are some things you might need to consider:
> For example, on iMX8, put this in your xxx-u-boot.dtsi file::
>
> &pd_dma {
>- u-boot,dm-pre-proper;
>+ bootph-some-ram;
> };
>
> &pd_dma_lpuart3 {
>- u-boot,dm-pre-proper;
>+ bootph-some-ram;
> };
>
> 4. The same applies to clocks, in the same way. Make sure that when your driver
>@@ -168,10 +168,10 @@ some customisation.
> Serial in SPL
> -------------
>
>-A similar process is needed in SPL, but in this case the u-boot,dm-spl or
>-u-boot,dm-tpl tags are used. Add these in the same way as above, to ensure that
>-the SPL device tree contains the required nodes (see spl/u-boot-spl.dtb for
>-what it actually contains).
>+A similar process is needed in SPL, but in this case the bootph-pre-ram or
>+bootph-pre-sram tags are used. Add these in the same way as above, to ensure
>+that the SPL device tree contains the required nodes (see spl/u-boot-spl.dtb
>+for what it actually contains).
>
> Removing old code
> -----------------
>diff --git a/doc/develop/spl.rst b/doc/develop/spl.rst
>index aec7b562faa..3d1bff81fcd 100644
>--- a/doc/develop/spl.rst
>+++ b/doc/develop/spl.rst
>@@ -113,13 +113,14 @@ with:
>
> - the mandatory nodes (/alias, /chosen, /config)
> - the nodes with one pre-relocation property:
>- 'u-boot,dm-pre-reloc' or 'u-boot,dm-spl'
>+ 'bootph-all' or 'bootph-pre-ram'
>
> fdtgrep is also used to remove:
>
> - the properties defined in CONFIG_OF_SPL_REMOVE_PROPS
> - all the pre-relocation properties
>- ('u-boot,dm-pre-reloc', 'u-boot,dm-spl' and 'u-boot,dm-tpl')
>+ ('bootph-all', 'bootph-pre-ram' (SPL), 'bootph-pre-sram' (TPL) and
>+ 'bootph-verify' (TPL))
>
> All the nodes remaining in the SPL devicetree are bound
> (see doc/driver-model/design.rst).
More information about the U-Boot-Custodians
mailing list