[PATCH] doc: dm: clarify activation.

[Michal Suchánek]

Hello,

On Sat, Aug 20, 2022 at 08:27:05AM +0200, Heinrich Schuchardt wrote:
> 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:

I wanted to look at this direct device lookup, and send a v2 when I am
done with it. I am currently trying to figure out how (if at all) the
pins and clocks required by i2c devices are activated, and I suppose
this direct lookup would be related.

Noneteless, if you can fix up the patch right away that's great.

Thanks

Michal

> 
> 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
>