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

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

[Simon Goldschmidt]

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

Changes in v2:
- further fixes noted by Simon Glass
- added info about missing node relations
- moved the passage about phandles into section 'caveats'

 doc/driver-model/of-plat.txt | 31 ++++++++++++++++++++-----------
 dts/Kconfig                  |  6 ++----
 2 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.txt
index 732bc34f06..0109ec56c3 100644
--- a/doc/driver-model/of-plat.txt
+++ b/doc/driver-model/of-plat.txt
@@ -64,17 +64,24 @@ strictly necessary. Notable problems include:
         normally also supports device tree it must use #ifdef to separate
         out this code, since the structures are only available in SPL.
 
+   - Correct relations between nodes are not implemented. This means that
+        parent/child relations (like bus device iteration) do not work yet.
+        Some phandles (those that are recognised as such) are converted into
+        a 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.
+
 
 How it works
 ------------
 
-The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
-in SPL and should be tested with:
+The feature is enabled by CONFIG OF_PLATDATA. This is only available in
+SPL/TPL and should be tested with:
 
-        #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
+        #if CONFIG_IS_ENABLED(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 +163,13 @@ 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' corresponding to the devicetree 'compatible' string (after converting
+it to a valid name for C) 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 +179,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,11 +296,6 @@ 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
-referenced device (by searching for the pointer value). This feature is not
-yet implemented, however.
-
 The beginnings of a libfdt Python module are provided. So far this only
 implements a subset of the features.
 
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

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

[Simon Glass]

On Wed, 16 Jan 2019 at 12:40, Simon Goldschmidt
<simon.k.r.goldschmidt@gmail.com> wrote:
>
> 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>
> ---
>
> Changes in v2:
> - further fixes noted by Simon Glass
> - added info about missing node relations
> - moved the passage about phandles into section 'caveats'
>
>  doc/driver-model/of-plat.txt | 31 ++++++++++++++++++++-----------
>  dts/Kconfig                  |  6 ++----
>  2 files changed, 22 insertions(+), 15 deletions(-)

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

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

[sjg at google.com]

On Wed, 16 Jan 2019 at 12:40, Simon Goldschmidt
<simon.k.r.goldschmidt@gmail.com> wrote:
>
> 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>
> ---
>
> Changes in v2:
> - further fixes noted by Simon Glass
> - added info about missing node relations
> - moved the passage about phandles into section 'caveats'
>
>  doc/driver-model/of-plat.txt | 31 ++++++++++++++++++++-----------
>  dts/Kconfig                  |  6 ++----
>  2 files changed, 22 insertions(+), 15 deletions(-)

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

Applied to u-boot-dm, thanks!

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

[Adam Ford]

On Mon, Jan 21, 2019 at 12:26 PM <sjg@google.com> wrote:
>
> On Wed, 16 Jan 2019 at 12:40, Simon Goldschmidt
> <simon.k.r.goldschmidt@gmail.com> wrote:
> >
> > Improve some things in the documentation of OF_PLATDATA that I found
> > while porting socfgpa_gen5 to it.

Thanks for doing that.  I actually learned a bit.  :-)

This may be more directed at Simon, but it seems like many platforms
are limited in SPL and OF_PLATDATA might be a great feature to get
more drivers supporting device tree booting without as much overhead.

From how the documentation reads, it seems like the drivers may not
necessarily support OF_PLATDATA by default.  I've been struggling
trying to enable basic functions (like serial via 16550 driver)
because the platform data generated doesn't necessarily match the
platform data I use to start the serial device.  I would like to
migrate from using manually entered platform data to using OF_PLATDATA
to reduce the overhead.

A few things I noticed are that the generated device names correspond
to the names listed in the 'compatible' flag and there doesn't seem to
be a good way to link them to the actual driver name.

I see a few drivers that check for OF_PLATDATA, but I am not seeing
many people actually utilize this feature.  Any suggestions on how to
one might migrate a driver (like serial) which already supports
OF_CONTROL in u-boot, but the generated platdata doesn't boot in SPL?

adam
> >
> > Signed-off-by: Simon Goldschmidt <simon.k.r.goldschmidt@gmail.com>
> > ---
> >
> > Changes in v2:
> > - further fixes noted by Simon Glass
> > - added info about missing node relations
> > - moved the passage about phandles into section 'caveats'
> >
> >  doc/driver-model/of-plat.txt | 31 ++++++++++++++++++++-----------
> >  dts/Kconfig                  |  6 ++----
> >  2 files changed, 22 insertions(+), 15 deletions(-)
>
> Reviewed-by: Simon Glass <sjg@chromium.org>
>
> Applied to u-boot-dm, thanks!
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> https://lists.denx.de/listinfo/u-boot

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

[Simon Glass]

Hi Adam,

On Wed, 13 Feb 2019 at 05:14, Adam Ford <aford173@gmail.com> wrote:
>
> On Mon, Jan 21, 2019 at 12:26 PM <sjg@google.com> wrote:
> >
> > On Wed, 16 Jan 2019 at 12:40, Simon Goldschmidt
> > <simon.k.r.goldschmidt@gmail.com> wrote:
> > >
> > > Improve some things in the documentation of OF_PLATDATA that I found
> > > while porting socfgpa_gen5 to it.
>
> Thanks for doing that.  I actually learned a bit.  :-)
>
> This may be more directed at Simon, but it seems like many platforms
> are limited in SPL and OF_PLATDATA might be a great feature to get
> more drivers supporting device tree booting without as much overhead.
>
> From how the documentation reads, it seems like the drivers may not
> necessarily support OF_PLATDATA by default.  I've been struggling
> trying to enable basic functions (like serial via 16550 driver)
> because the platform data generated doesn't necessarily match the
> platform data I use to start the serial device.  I would like to
> migrate from using manually entered platform data to using OF_PLATDATA
> to reduce the overhead.
>
> A few things I noticed are that the generated device names correspond
> to the names listed in the 'compatible' flag and there doesn't seem to
> be a good way to link them to the actual driver name.

Yes, that is the job of the code. See for example
rockchip_serial_probe() which copies the platform data out of the
of-platdata struct and into the normal one.

>
> I see a few drivers that check for OF_PLATDATA, but I am not seeing
> many people actually utilize this feature.  Any suggestions on how to
> one might migrate a driver (like serial) which already supports
> OF_CONTROL in u-boot, but the generated platdata doesn't boot in SPL?

You can have a look at serial_rockchip as an example. If you don't
have a JTAG unit I suggest enabling the debug UART so you can debug
what goes wrong when it cannot find the serial device.

Regards,
Simon