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

[U-Boot] [PATCH] 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>
---

 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

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

[Simon Glass]

On Mon, 7 Jan 2019 at 12:23, 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>
> ---
>
>  doc/driver-model/of-plat.txt | 18 ++++++++++++------
>  dts/Kconfig                  |  6 ++----
>  2 files changed, 14 insertions(+), 10 deletions(-)

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

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

Actually that seems wrong. Shouldn't it omit the SPL_ part?

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

Not identical - e.g. hyphens change to underscores.

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

a pointer to platform data


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

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

[Simon Goldschmidt]

On Thu, Jan 10, 2019 at 1:57 PM Simon Glass <sjg@chromium.org> wrote:
>
> On Mon, 7 Jan 2019 at 12:23, 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>
> > ---
> >
> >  doc/driver-model/of-plat.txt | 18 ++++++++++++------
> >  dts/Kconfig                  |  6 ++----
> >  2 files changed, 14 insertions(+), 10 deletions(-)
>
> Reviewed-by: Simon Glass <sjg@chromium.org>
>
> >
> > 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)
>
> Actually that seems wrong. Shouldn't it omit the SPL_ part?

Right, didn't catch that.

> >
> >  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.
>
> Not identical - e.g. hyphens change to underscores.

Ehrm, yeah. Seems like I need a V2...

> > +
> >  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
>
> a pointer to platform data

I'll change that as well in V2.

Regards,
Simon

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

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

[Lukasz Majewski]

Hi Simon,

> On Thu, Jan 10, 2019 at 1:57 PM Simon Glass <sjg@chromium.org> wrote:
> >
> > On Mon, 7 Jan 2019 at 12:23, 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>
> > > ---
> > >
> > >  doc/driver-model/of-plat.txt | 18 ++++++++++++------
> > >  dts/Kconfig                  |  6 ++----
> > >  2 files changed, 14 insertions(+), 10 deletions(-)  
> >
> > Reviewed-by: Simon Glass <sjg@chromium.org>
> >  
> > >
> > > 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)  
> >
> > Actually that seems wrong. Shouldn't it omit the SPL_ part?  
> 
> Right, didn't catch that.
> 
> > >
> > >  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.  
> >
> > Not identical - e.g. hyphens change to underscores.  
> 
> Ehrm, yeah. Seems like I need a V2...

If I may add my 2 cents.

Simon, could you add the information regarding what can be done and
what is not yet implemented?

For example - from the other mail I've read that phandles are
supported, but not parent/child relationship.

> 
> > > +
> > >  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  
> >
> > a pointer to platform data  
> 
> I'll change that as well in V2.
> 
> Regards,
> Simon
> 
> >  
> > >  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
> > >  
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> https://lists.denx.de/listinfo/u-boot




Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-59 Fax: (+49)-8142-66989-80 Email: lukma at denx.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20190111/07e62aed/attachment.sig>