[PATCH] doc: dm: clarify activation.

[Heinrich Schuchardt]

On 8/4/22 22:30, Simon Glass wrote:
> Hi Michal,
>
> On Thu, 4 Aug 2022 at 13:42, Michal Suchánek <msuchanek at suse.de> wrote:
>>
>> On Thu, Aug 04, 2022 at 01:22:53PM -0600, Simon Glass wrote:
>>> 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

When merging I will put the following here:

The device should be probed by the uclass code or generic device code
(e.g. device_find_global_by_ofnode()). Uclasses differ but two common
use cases can be seen:

Best regards

Heinrich

>>>
>>> or the device code (e.g. device_get_child())
>>
>> Can you elaborate a bit more, please?
>
> I mean that we can use 'device' code to probe, as well as the 'uclass'
> code. The function I cite is an example of that, but actually a better
> one is device_find_global_by_ofnode()
>
>>
>> This change is the reasult of some previous discussion about the device
>> activation with Marek.
>>
>> The device activation is really difficult to understand for people who
>> did not participate in designing the DM, and is probably quite specific
>> to U-Boot.
>
> OK, well good to have it. I wish more people would do what you have
> done here, i.e. go back and update the docs to clarify things that you
> found confusing / inadequate.
>
>>
>>>
>>> BTW probing a child probes all its parents automatically (that is said
>>> elsewhere I think).
>>
>> Yes, right below this part.
>>
>> Thanks
>>
>> Michal
>
> OK
>
> Regards,
> Simon
>
>
>>
>>>
>>>> +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