[PATCH 8/8] dtoc: Update documentation to cover warnings in more detail

[Walter Lozano]

Hi Simon,

On 7/4/21 3:19 PM, Simon Glass wrote:
> When things go wrong it can be confusing to figure out what to change.
> Add a few more details to the documentation.
>
> Fix a 'make htmldocs' warning while we are here.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
>   doc/develop/driver-model/of-plat.rst | 53 ++++++++++++++++++++++++++++
>   1 file changed, 53 insertions(+)
>
> diff --git a/doc/develop/driver-model/of-plat.rst b/doc/develop/driver-model/of-plat.rst
> index 74f1932473b..e2763965839 100644
> --- a/doc/develop/driver-model/of-plat.rst
> +++ b/doc/develop/driver-model/of-plat.rst
> @@ -597,6 +597,59 @@ as a macro included in the driver definition::
>   
>   
>   
> +Problems
> +--------
> +
> +In some cases you will you see something like this::
> +
> +   WARNING: the driver rockchip_rk3188_grf was not found in the driver list
> +
> +The driver list is a list of drivers, each with a name. The name is in the
> +U_BOOT_DRIVER() declaration, repeated twice, one in brackets and once as the
> +.name member. For example, in the following declaration the driver name is
> +`rockchip_rk3188_grf`::
> +
> +  U_BOOT_DRIVER(rockchip_rk3188_grf) = {
> +       .name = "rockchip_rk3188_grf",
> +       .id = UCLASS_SYSCON,
> +       .of_match = rk3188_syscon_ids + 1,
> +       .bind = rk3188_syscon_bind_of_plat,
> +  };
> +
> +The first name U_BOOT_DRIVER(xx) is used to create a linker symbol so that the
> +driver can be accessed at build-time without any overhead. The second one
> +(.name = "xx") is used at runtime when something wants to print out the driver
> +name.
> +
> +The dtoc tool expects to be able to find a driver for each compatible string in
> +the devicetree. For example, if the devicetree has::
> +
> +   grf: grf at 20008000 {
> +      compatible = "rockchip,rk3188-grf", "syscon";
> +      reg = <0x20008000 0x200>;
> +      u-boot,dm-spl;
> +   };
> +
> +then dtoc looks at the first compatible string ("rockchip,rk3188-grf"),
> +converts that to a C identifier (rockchip_rk3188_grf) and then looks for that.
> +
> +Various things can cause dtoc to fail to find the driver and it tries to
> +warn about these. For example:
> +
> +   rockchip_rk3188_uart: Missing .compatible in drivers/serial/serial_rockchip.c
> +                    : WARNING: the driver rockchip_rk3188_uart was not found in the driver list
> +
> +Without a compatible string a driver cannot be used by dtoc, even if the
> +compatible string is not actually needed at runtime.
> +
> +If the problem is simply that there are multiple compatible strings, the
> +DM_DRIVER_ALIAS() macro can be used to tell dtoc about this and avoid a problem.
> +
> +Checks are also made the referenced driver has a .compatible member and a .id
> +member. The first provides the array of compatible strings and the second
> +provides the uclass ID.
> +

This paragraph sound strange, maybe

"Checks are are also made to confirm that the referenced driver..."

but your English is better than mine.

Reviewed-by: Walter Lozano <walter.lozano at collabora.com>

Regards,

Walter

> +
>   Caveats
>   -------
>