[U-Boot] [PATCH] of-platdata: improve documentation

Simon Goldschmidt
2019-01-07T19:23:32Z

Improve some things in the documentation of OF_PLATDATA that I found
while porting socfgpa_gen5 to it.

Signed-off-by: Simon Goldschmidt <simon.k.r.goldschmidt@gmail.com>
---

doc/driver-model/of-plat.txt | 18 ++++++++++++------
dts/Kconfig | 6 ++----
2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt
index 732bc34f06..ecb5f1724b 100644
--- a/doc/driver-model/of-plat.txt
+++ b/doc/driver-model/of-plat.txt
@@ -69,12 +69,12 @@ How it works
------------

The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
-in SPL and should be tested with:
+in SPL/TPL and should be tested with:

#if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)

A new tool called 'dtoc' converts a device tree file either into a set of
-struct declarations, one for each compatible node, or a set of
+struct declarations, one for each compatible node, and a set of
U_BOOT_DEVICE() declarations along with the actual platform data for each
device. As an example, consider this MMC node:

@@ -156,6 +156,12 @@ This avoids the code overhead of converting the device tree data to
platform data in the driver. The ofdata_to_platdata() method should
therefore do nothing in such a driver.

+Note that for the platform data to be matched with a driver, the 'name'
+property of the U_BOOT_DEVICE() declaration has to match a driver declared
+via U_BOOT_DRIVER(). This effectively means that a U_BOOT_DRIVER() with a
+'name' identical to the devicetree 'compatible' string is needed, so a
+dedicated driver is required for each 'compatible' string.
+
Where a node has multiple compatible strings, a #define is used to make them
equivalent, e.g.:

@@ -165,8 +171,8 @@ equivalent, e.g.:
Converting of-platdata to a useful form
---------------------------------------

-Of course it would be possible use the of-platdata directly in your driver
-whenever configuration information is required. However this meands that the
+Of course it would be possible to use the of-platdata directly in your driver
+whenever configuration information is required. However this means that the
driver will not be able to support device tree, since the of-platdata
structure is not available when device tree is used. It would make no sense
to use this structure if device tree were available, since the structure has
@@ -282,8 +288,8 @@ prevents them being used inadvertently. All usage must be bracketed with
The dt-platdata.c file contains the device declarations and is is built in
spl/dt-platdata.c.

-Some phandles (thsoe that are recognised as such) are converted into
-points to platform data. This pointer can potentially be used to access the
+Some phandles (those that are recognised as such) are converted into
+pointer to platform data. This pointer can potentially be used to access the
referenced device (by searching for the pointer value). This feature is not
yet implemented, however.

diff --git a/dts/Kconfig b/dts/Kconfig
index 8917f42444..3e85914d11 100644
--- a/dts/Kconfig
+++ b/dts/Kconfig
@@ -265,8 +265,7 @@ config SPL_OF_PLATDATA

This option works by generating C structure declarations for each
compatible string, then adding platform data and U_BOOT_DEVICE
- declarations for each node. See README.platdata for more
- information.
+ declarations for each node. See of-plat.txt for more information.

config TPL_OF_PLATDATA
bool "Generate platform data for use in TPL"
@@ -287,8 +286,7 @@ config TPL_OF_PLATDATA

This option works by generating C structure declarations for each
compatible string, then adding platform data and U_BOOT_DEVICE
- declarations for each node. See README.platdata for more
- information.
+ declarations for each node. See of-plat.txt for more information.

endmenu

--
2.17.1