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

[Lukasz Majewski <lukma@denx.de>]

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>