[PATCH v2 03/37] dm: core: Add macros to access the new linker lists

[Heinrich Schuchardt]

On 03.02.21 17:43, Simon Glass wrote:
> Add macros which work with instantiated devices and uclasses, as created
> at build time by dtoc. Include variants that can be used in data
> structures.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
> (no changes since v1)
>
>  include/dm/device-internal.h | 26 ++++++++++++++++++++++++++
>  include/dm/device.h          | 11 +++++++++++
>  include/dm/uclass-internal.h | 23 +++++++++++++++++++++++
>  include/dm/uclass.h          | 20 ++++++++++++++++++++
>  4 files changed, 80 insertions(+)
>
> diff --git a/include/dm/device-internal.h b/include/dm/device-internal.h
> index 639bbd293d9..9d7256130cd 100644
> --- a/include/dm/device-internal.h
> +++ b/include/dm/device-internal.h
> @@ -10,11 +10,37 @@
>  #ifndef _DM_DEVICE_INTERNAL_H
>  #define _DM_DEVICE_INTERNAL_H
>
> +#include <linker_lists.h>
>  #include <dm/ofnode.h>
>
>  struct device_node;
>  struct udevice;
>
> +/*
> + * These are only allowed these in code generated by dtoc, because the ordering
> + * is important and if other instances creep in then they may mess up the
> + * ordering expected by dtoc.
> + */
> +
> +/* Declare a bound device ready for run-time use */
> +#define DM_DEVICE_INST(__name)						\
> +	ll_entry_declare(struct udevice, __name, udevice)
> +
> +/* Declare a bound device as an extern, so it can be referenced at build time */
> +#define DM_DEVICE_DECL(__name)						\
> +	ll_entry_decl(struct udevice, __name, udevice)
> +
> +/*
> + * Get a pointer to a given device, for use in data structures. This requires
> + * that the symbol be declared with DM_DRIVER_DECL() first
> + */
> +#define DM_DEVICE_REF(__name)						\
> +	ll_entry_ref(struct udevice, __name, udevice)
> +
> +/* Get a pointer to a given device */
> +#define DM_DEVICE_GET(__name)						\
> +	ll_entry_get(struct udevice, __name, udevice)
> +
>  /**
>   * device_bind() - Create a device and bind it to a driver
>   *
> diff --git a/include/dm/device.h b/include/dm/device.h
> index 1c52c9d3120..38ef47baa01 100644
> --- a/include/dm/device.h
> +++ b/include/dm/device.h
> @@ -338,6 +338,17 @@ struct driver {
>  #define DM_DRIVER_GET(__name)						\
>  	ll_entry_get(struct driver, __name, driver)
>
> +/* Declare a driver as an extern, so it can be referenced at build time */
> +#define DM_DRIVER_DECL(__name)					\
> +	ll_entry_decl(struct driver, __name, driver)
> +
> +/*
> + * Get a pointer to a given driver, for use in data structures. This requires
> + * that the symbol be declared with DM_DRIVER_DECL() first
> + */
> +#define DM_DRIVER_REF(__name)					\
> +	ll_entry_ref(struct driver, __name, driver)
> +
>  /**
>   * Declare a macro to state a alias for a driver name. This macro will
>   * produce no code but its information will be parsed by tools like
> diff --git a/include/dm/uclass-internal.h b/include/dm/uclass-internal.h
> index c5a464be7c4..fc4d8dc2b53 100644
> --- a/include/dm/uclass-internal.h
> +++ b/include/dm/uclass-internal.h
> @@ -11,6 +11,29 @@
>
>  #include <dm/ofnode.h>
>
> +/*
> + * These are only allowed these in code generated by dtoc, because the ordering

%s/These/The next three macros/

> + * is important and if other instances creep in then they may mess up the
> + * ordering expected by dtoc.
> + */
> +
> +/*
> + * Declare a uclass ready for run-time use. This adds an actual struct uclass
> + * to a list which is found by driver model on start-up.
> + */

It is unclear which type __name might have.

Please, describe in Sphinx style for each macro  what the macro is used
for, how it is used, what the parameters are used for, which type they take.

Best regards

Heinrich

> +#define DM_UCLASS_INST(__name)						\
> +	ll_entry_declare(struct uclass, __name, uclass)
> +
> +#define DM_UCLASS_DECL(__name)						\
> +	ll_entry_decl(struct uclass, __name, uclass)
> +
> +/*
> + * Declare a uclass as an extern, so it can be referenced at build time. This
> + * is an extern for DM_UCLASS_INST().
> + */
> +#define DM_UCLASS_REF(__name)						\
> +	ll_entry_ref(struct uclass, __name, uclass)
> +
>  /**
>   * uclass_set_priv() - Set the private data for a uclass
>   *
> diff --git a/include/dm/uclass.h b/include/dm/uclass.h
> index d95683740cb..152f49e97dc 100644
> --- a/include/dm/uclass.h
> +++ b/include/dm/uclass.h
> @@ -114,6 +114,26 @@ struct uclass_driver {
>  #define UCLASS_DRIVER(__name)						\
>  	ll_entry_declare(struct uclass_driver, __name, uclass_driver)
>
> +/*
> + * These two macros are related to of-platdata, and normally only used in
> + * code generated by dtoc
> + */
> +
> +/*
> + * Declare a uclass driver as an extern, so it can be referenced at build time
> + * This is the extern equivalent of UCLASS_DRIVER(). You need to place this at
> + * the top level before you use DM_UCLASS_DRIVER_REF() in a file.
> + */
> +#define DM_UCLASS_DRIVER_DECL(__name)					\
> +	ll_entry_decl(struct uclass_driver, __name, uclass_driver)
> +
> +/*
> + * Get a pointer to a given uclass driver, for use in data structures. This
> + * requires that the symbol be declared with DM_UCLASS_DRIVER_DECL() first
> + */
> +#define DM_UCLASS_DRIVER_REF(__name)					\
> +	ll_entry_ref(struct uclass_driver, __name, uclass_driver)
> +
>  /**
>   * uclass_get_priv() - Get the private data for a uclass
>   *
>