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

[Simon Glass]

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

Reviewed-by: Simon Glass <sjg at 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
>