dtoc: Further improve documentation about warnings

Split this information into subsections and expand it.

Signed-off-by: Simon Glass <sjg@chromium.org>

1 files changed, 88 insertions, 4 deletions

diff --git a/doc/develop/driver-model/of-plat.rst b/doc/develop/driver-model/of-plat.rst
index 8a8eaed4c1..0bd978759c 100644
--- a/doc/develop/driver-model/of-plat.rst
+++ b/doc/develop/driver-model/of-plat.rst
@@ -600,6 +600,11 @@ as a macro included in the driver definition::
 Problems
 --------
 
+This section shows some common problems and how to fix them.
+
+Driver not found
+~~~~~~~~~~~~~~~~
+
 In some cases you will you see something like this::
 
    WARNING: the driver rockchip_rk3188_grf was not found in the driver list
@@ -633,6 +638,9 @@ the devicetree. For example, if the devicetree has::
 then dtoc looks at the first compatible string ("rockchip,rk3188-grf"),
 converts that to a C identifier (rockchip_rk3188_grf) and then looks for that.
 
+Missing .compatible or Missing .id
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Various things can cause dtoc to fail to find the driver and it tries to
 warn about these. For example:
 
@@ -649,6 +657,82 @@ Checks are also made to confirm that the referenced driver has a .compatible
 member and a .id member. The first provides the array of compatible strings and
 the second provides the uclass ID.
 
+Missing parent
+~~~~~~~~~~~~~~
+
+When a device is used, its parent must be present as well. If you see an error
+like::
+
+   Node '/i2c@0/emul/emul0' requires parent node '/i2c@0/emul' but it is not in
+      the valid list
+
+it indicates that you are using a node whose parent is not present in the
+devicetree. In this example, if you look at the device tree output
+(e.g. fdtdump tpl/u-boot-tpl.dtb in your build directory), you may see something
+like this::
+
+   emul {
+       emul0 {
+           compatible = "sandbox,i2c-rtc-emul";
+           #emul-cells = <0x00000000>;
+           phandle = <0x00000003>;
+       };
+   };
+
+In this example, 'emul0' exists but its parent 'emul' has no properties. These
+have been dropped by fdtgrep in an effort to reduce the devicetree size. This
+indicates that the two nodes have different phase settings. Looking at the
+source .dts::
+
+   i2c_emul: emul {
+      u-boot,dm-spl;
+      reg = <0xff>;
+      compatible = "sandbox,i2c-emul-parent";
+      emul0: emul0 {
+         u-boot,dm-pre-reloc;
+         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.
+
+Link errors / undefined reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes dtoc does not find the problem for you, but something is wrong and
+you get a link error, e.g.::
+
+   :(.u_boot_list_2_udevice_2_spl_test5+0x0): undefined reference to
+      `_u_boot_list_2_driver_2_sandbox_spl_test'
+   /usr/bin/ld: dts/dt-uclass.o:(.u_boot_list_2_uclass_2_misc+0x8):
+        undefined reference to `_u_boot_list_2_uclass_driver_2_misc'
+
+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
+to exclude it from the TPL build::
+
+	spl-test5 {
+		u-boot,dm-tpl;
+		compatible = "sandbox,spl-test";
+		stringarray = "tpl";
+	};
+
+We can drop the 'u-boot,dm-tpl' 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
+(since it is in the MISC uclass) but that uclass is not compiled in the build.
+The fix above would fix this error too. But if you do want this uclass in the
+build, check your Kconfig settings to make sure the uclass is being built
+(CONFIG_MISC in this case).
+
 
 Caveats
 -------
@@ -697,7 +781,7 @@ Internals
 ---------
 
 Generated files
-```````````````
+~~~~~~~~~~~~~~~
 
 When enabled, dtoc generates the following five files:
 
@@ -738,7 +822,7 @@ spl/dt-plat.c.
 
 
 CONFIG options
-``````````````
+~~~~~~~~~~~~~~
 
 Several CONFIG options are used to control the behaviour of of-platdata, all
 available for both SPL and TPL:
@@ -793,7 +877,7 @@ READ_ONLY
    the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled.
 
 Data structures
-```````````````
+~~~~~~~~~~~~~~~
 
 A few extra data structures are used with of-platdata:
 
@@ -821,7 +905,7 @@ A few extra data structures are used with of-platdata:
    `device_get_by_ofplat_idx()`.
 
 Other changes
-`````````````
+~~~~~~~~~~~~~
 
 Some other changes are made with of-platdata: