Difuse/u-boot
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

dm: doc: Update documentation for new driver model schema

Browse source 
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@chromium.org>
This commit is contained in:
Simon Glass 2023-02-13 08:56:36 -07:00
parent c8ef3eed61
commit ea4299a213
7 changed files with 49 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/README.TPL
View file

@ -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:

15
doc/develop/driver-model/design.rst
View file

@ -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

4
doc/develop/driver-model/fs_firmware_loader.rst
View file

@ -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";

25
doc/develop/driver-model/of-plat.rst
View file

@ -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@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

10
doc/develop/driver-model/pci-info.rst
View file

@ -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@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@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

24
doc/develop/driver-model/serial-howto.rst
View file

@ -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
-----------------

9
doc/develop/spl.rst
View file

@ -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
---------