[PATCH] doc: dm: clarify activation.

[Simon Glass]

Hi Michal,

On Thu, 4 Aug 2022 at 11:58, Michal Suchanek <msuchanek at suse.de> wrote:
>
> Explain when devices should get activated.
>
> Signed-off-by: Michal Suchanek <msuchanek at suse.de>
> ---
>  doc/develop/driver-model/design.rst | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)

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

Much appreciated!

one note below

>
> diff --git a/doc/develop/driver-model/design.rst b/doc/develop/driver-model/design.rst
> index 5f33f9fbb3..c925d21b24 100644
> --- a/doc/develop/driver-model/design.rst
> +++ b/doc/develop/driver-model/design.rst
> @@ -794,8 +794,26 @@ fall afoul of this rule.
>  Activation/probe
>  ^^^^^^^^^^^^^^^^
>
> -When a device needs to be used, U-Boot activates it, by first reading ofdata
> -as above and then following these steps (see device_probe()):
> +To save resources devices in U-Boot are probed lazily. U-Boot is a bootloader,
> +not an operating system. Many devices are never used during an U-Boot run, and
> +probing them takes time, requires memory, may add delays to the main loop, etc.
> +
> +The device should be probed by the uclass code. Different uclasses are

or the device code (e.g. device_get_child())

BTW probing a child probes all its parents automatically (that is said
elsewhere I think).

> +different but two common use cases can be seen:
> +
> +   1. The uclass is asked to look up a specific device, such as SPI bus 0,
> +   first chip select - in this case the returned device should be
> +   activated.
> +
> +   2. The uclass is asked to perform a specific function on any device that
> +   supports it, eg. reset the board using any sysreset that can be found -
> +   for this case the core uclass code provides iterators that activate
> +   each device before returning it, and the uclass typically implements a
> +   walk function that iterates over all devices of the uclass and tries
> +   to perform the requested function on each in turn until succesful.
> +
> +To activate a device U-Boot first reads ofdata as above and then follows these
> +steps (see device_probe()):
>
>     1. All parent devices are probed. It is not possible to activate a device
>     unless its predecessors (all the way up to the root device) are activated.
> --
> 2.37.1
>

Regards,
Simon