dm: doc: Update documentation for new driver model schema

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>

7 files changed, 49 insertions, 42 deletions

diff --git a/doc/README.TPL b/doc/README.TPL
index 72027fd..95b466e 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 20611e8..8c2c81d 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 a44708c..b082370 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 b454f7b..01724ba 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@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 251601a..dea595b 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@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
diff --git a/doc/develop/driver-model/serial-howto.rst b/doc/develop/driver-model/serial-howto.rst
index 5b1d57d..17b53e3 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 aec7b56..a1515a7 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
 ---------