[PATCH v5 06/11] dm: doc: Update documentation for new driver model schema
Simon Glass
sjg at chromium.org
Mon Feb 13 16:56:36 CET 2023
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>
---
Changes in v5:
- Add a note to the SPL file about the migration
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 | 9 +++++--
7 files changed, 49 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..a1515a7b43b 100644
--- a/doc/develop/spl.rst
+++ b/doc/develop/spl.rst
@@ -113,17 +113,22 @@ 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).
+NOTE: U-Boot migrated to a new schema for the u-boot,dm-* tags in 2023. Please
+update to use the new bootph-* tags as described in the
+doc/device-tree-bindings/bootph.yaml binding file.
+
Debugging
---------
--
2.39.1.581.gbfd45094c4-goog
More information about the U-Boot
mailing list