[U-Boot] [RFC PATCH 17/22] dm: Expand and improve the device lifecycle docs

[Jon Loeliger]

On Sat, May 24, 2014 at 4:21 PM, Simon Glass <sjg at chromium.org> wrote:
> The lifecycle of a device is an important part of driver model. Add to the
> existing documentation and clarify it.
>
> Thanks for Jon Loeliger <jdl at jdl.com> for helping with the text and
> suggesting improvements.
>
> (Jon please comment/adjust to help clarify things further)

Clearly that line should be below the '---'. :-)

> Reported-by: Jon Loeliger <jdl at jdl.com>
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---

A few nits, but otherwise feel free to add my ACK as well.



>  Platform Data
>  -------------
>
> +Platform data is like Linux platform data, if you are familiar with that.
> +It provides the board-specific information to start up a device.
> +
> +Why is this information not just stored in the device driver itself? The
> +idea is that the device driver is generic, and can in principle operate on
> +any board that has that type of device. For example, with modern
> +highly-complex SoCs it is common for the IP to come from an IP vendor, and
> +therefore (for example) the MMC controller may be the same on chips from
> +different vendors. It makes no sense to write independent drivers for the
> +MMC controller on each vendor's SoC, when they are all almost the same.
> +Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same,
> +but lie at different addresses in the address space.
> +
> +Using the UART example, we have a single driver and it is instantiated 6
> +times by supplying 6 lots of platform data. Each lot of platform data
> +gives the driver name and a pointer to a structure containing information
> +about this instance - e.g. the address of the register space. It may be that
> +one of the UARTS supports RS-485 operation - this can be added as a flag in
> +the platform data, which is set for this one port and clear for the rest.
> +
> +Think of your driver as a generic piece of code which knows how to talk to
> +a device, but needs to know where it is, any variant/option information and
> +so on. Platform data provides this link between the generic piece of code
> +and the specific way it is bound on a particular board.
> +
> +Examples of platform data include:
> +
> +   - The base address of the IP block's register space
> +   - Configuration options, like:
> +         - the SPI polarity and maximum speed for a SPI controller
> +         - the I2C speed to use for an I2C device
> +         - the number of GPIOs available in a GPIO device
> +   - Note this can be parsed from the Device Tree (see below)

Not sure to what 'this' refers in that last bullet.  Should that whole last
line read more like:

    - Data that can be parsed from the Device Tree (see below)


>  Where does the platform data come from? See demo-pdata.c which
>  sets up a table of driver names and their associated platform data.

This is a weak explanation of platform data origin.  At the very least
we need to say it is allocated per-device if needed, and then point
to the demo-pdata.c as an *example*.


>  The data can be interpreted by the drivers however they like - it is
> @@ -259,21 +296,30 @@ following device tree fragment:
>                 sides = <4>;
>         };
>
> +This means that instead of having lots of U_BOOT_DEVICE() declarations in
> +the board file, we put these in the device tree. The allows a lot more

s/The/This approach/

> +generality, since the same board file can support many types of boards (e,g.
> +with the same SoC) just by using different device trees. An added benefit
> +is that the Linux device tree can be used, thus further simplifying the
> +task of board-bring up either for U-Boot or Linux devs (whoever gets to the
> +baord first!).

I'd also s/devs/developers/.  But that may be just me. :-)

>  The easiest way to make this work it to add a few members to the driver:
>
>         .platdata_auto_alloc_size = sizeof(struct dm_test_pdata),
>         .ofdata_to_platdata = testfdt_ofdata_to_platdata,
> -       .probe  = testfdt_drv_probe,
>
>  The 'auto_alloc' feature allowed space for the platdata to be allocated
>  and zeroed before the driver's ofdata_to_platdata method is called. This
> -method reads the information out of the device tree and puts it in
> -dev->platdata. Then the probe method is called to set up the device.
> +method (which the driver writer supplies) should read the information out
> +of the device tree and puts it in dev->platdata. Thus when the probe method

s/puts/put/..; But *which* method here?  The ofdata_to_platdata()?  I think
that needs to be explicitly referenced in the text here:

    The ofdata_to_platdata() method, which the driver write supplies, should
    parse the device tree node for this device and place it in the
dev->platdata.


> +is called later (to set up the device ready for use) the platform data will
> +be present.
>
>  Note that both methods are optional. If you provide an ofdata_to_platdata
> -method then it wlil be called first (after bind). If you provide a probe
> -method it will be called next.
> +method then it wlil be called first (during activation). If you provide a
> +probe method it will be called next. See Driver Lifecycle below for more
> +details.
>
>  If you don't want to have the platdata automatically allocated then you
>  can leave out platdata_auto_alloc_size. In this case you can use malloc
> @@ -295,6 +341,145 @@ numbering comes from include/dm/uclass.h. To add a new uclass, add to the
>  end of the enum there, then declare your uclass as above.
>
>
> +Driver Lifecycle
> +----------------
> +
> +Here are the stages that a device goes through in driver model. Note that all
> +methods mentioned here are optional - e.g. if there is no probe() method for
> +a device then it will not be called. A simple device may have very few
> +methods actually defined.
> +
> +1. U-Boot scans the U_BOOT_DEVICE() declarations. It looks up the name
> +specified by each, to find the appropriate driver. It then calls
> +device_bind() to create a new device and bind' it to its driver. This will
> +call the device's bind() method.
> +
> +2. U-Boot scans through top-level nodes in the the device tree. It looks
> +at the compatible string in each node and uses the of_match part of the
> +U_BOOT_DRIVER() structure to find the right driver for each node. It then
> +calls device_bind() to bind the newly-created device to its driver (thereby
> +creating a device structure). This will also call the device's bind()
> +method.


OK.  The combination of paragraph 1. and 2. confused me.  It reads like
a device will have bind() called on it twice.  But I don't think that is true.
I think a device can have bind() called for it in one of two ways: either
from a direct definition of a device using U_BOOT_DEVICE(), or as a
result of inspecting the driver list and pawing through the DTS for appropriate
and matching nodes.  If I understand that correctly, then I think we should
re-word these two paragraphs (1. and 2.) as parts of a first Bind Stage:

1. Bind Step
    A device and its driver are bound using one of these two methods:

    A) Scan the U_BOOT_DEVICE() definitions, blah blah blah.

    B) Scan the DTS and patch driver definitions found in U_BOOT_DRIVER()
         definitions, blah blah blah.


This following paragraph describes what the effect of "Step 1. Bind Stage"
does.  It isn't actually a separate step in the process.  So delete
the "3." here:

> +3. At this point all the devices are known, and bound to their drivers.
> +There is a 'struct device' allocated for all devices. However, nothing
> +has been activated (except for the root device). Each bound device that
> +was created from a U_BOOT_DEVICE() declaration will hold the platdata
> +pointer specified in that declaration. For a bound device created from
> +the device tree, platdata will be NULL, but of_offset will be the offset
> +of the device tree node that caused the device to be created. The uclass
> +is set, and the DM_FLAG_PREFER flag is set if the device node has the
> +'dm,prefer' property.

No idea what the prefer property means or causes yet....


> +Note: The device's bind() method is permitted to perform simple actions,
> +but should not scan the device tree node, not initialise hardware, nor set
> +up structures or allocate memory. All of these tasks should be left for the
> +probe() method.

Excellent.  This is a crucial aspect of the Bind operation.  It is so important
that it should not be a "Note:"!

And this should be a new paragraph:

>  Note that compared to Linux, U-Boot's driver model has a
> +separate step of probe/remove which is independent of bind/unbind. This is
> +partly because in U-Boot it may be expensive to prove devices and we don't
> +want to do it until they are needed, or perhaps until after relocation.

OK, good.   And here really is "2. Probe Stage":

> +4. When a device needs to be used, U-Boot activates it, by following these
> +steps (see device_probe()):
> +
> +   a. If priv_auto_alloc_size is non-zero, then the device-private space
> +   is allocated for the device and zeroed. It will be accessible as
> +   dev->priv. The driver can put anything it likes in there, but should use
> +   it for run-time information, not platform data (which should be static
> +   and known before the device is probed).
> +
> +   b. If platdata_auto_alloc_size is non-zero, then the platform data space
> +   is allocated. This is only useful for device tree operation, since
> +   otherwise you would have to specific the platform data in the
> +   U_BOOT_DEVICE() declaration. The space is allocated for the device and
> +   zeroed. It will be accessible as dev->platdata.
> +
> +   c. If the device's uclass specifies a non-zero per_device_auto_alloc_size,
> +   then this space is allocated and zeroed also. It is allocated for and
> +   stored in the device, but it is uclass data. owned by the uclass driver.
> +   It is possible for the device to access it.
> +
> +   d. All parent devices are probed. It is not possible to activate a device
> +   unless its parents (all the way up to the root device) are activated.
> +   This means (for example) that an I2C driver will require that its bus
> +   be activated.
> +
> +   e. If the driver provides a ofdata_to_platdata() method, then this is
> +   called to convert the device tree data into platform data. This should
> +   do various calls like fdtdec_get_int(gd->fdt_blob, dev->of_offset, ...)
> +   to access the node and store the resulting information into dev->platdata.
> +   After this point, the device works the same way whether it was bound
> +   using a device tree node or U_BOOT_DEVICE() structure. In either case,
> +   the platform data is now stored in the platdata structure. Typically you
> +   will use the platdata_auto_alloc_size feature to specify the size of the
> +   platform data structure, and U-Boot will automatically allocate and zero
> +   it for you before entry to ofdata_to_platdata(). But if not, you can
> +   allocate it yourself in ofdata_to_platdata(). Note that it is preferable
> +   to do all the device tree decoding in ofdata_to_platdata() rather than
> +   in probe(). (Apart from the ugliness of mixing configuration and run-time
> +   data, one day it is possible that U-Boot will cache platformat data for
> +   devices which are regularly de/activated).
> +
> +   f. The device's probe() method is called. This should do anything that
> +   is required by the device to get it going. This could include checking
> +   that the hardware is actually present, setting up clocks for the
> +   hardware and setting up hardware registers to initial values. The code
> +   in probe() can access:
> +
> +      - platform data in dev->platdata (for configuration)
> +      - private data in dev->priv (for run-time state)
> +      - uclass data in dev->uclass_priv (for things the uclass stores
> +        about this device)
> +
> +   Note: If you don't use priv_auto_alloc_size then you will need to
> +   allocate the priv space here yourself. The same applies also to
> +   platdata_auto_alloc_size. Remember to free them in the remove() method.
> +
> +   g. The device is marked 'activated'
> +
> +   h. The uclass's post_probe() method is called, if one exists. This may
> +   cause the uclass to do some housekeeping to record the device as
> +   activated and 'known' by the uclass.

This is an excellent run of documentation.  Thanks!

> +5. The device is now activated and can be used. From now until it is removed
> +all of the above structures are accessible. The device appears in the
> +uclass's list of devices (so if the device is in UCLASS_GPIO it will appear
> +as a device in the GPIO uclass). This is the 'running' state of the device.

Good.

> +6. When the device is no-longer required, you can call device_remove() to
> +remove it. This performs the probe steps in reverse:
> +
> +   a. The uclass's pre_remove() method is called, if one exists. This may
> +   cause the uclass to do some housekeeping to record the device as
> +   deactivated and no-longer 'known' by the uclass.
> +
> +   b. All the device's children are removed. It is not permitted to have
> +   an active child device with a non-active parent.

Is that "are removed" meant to mean device_remove() is called recursively
on all the children first?

> +   c. The device's remove() method is called. At this stage nothing has been
> +   deallocated so platform data, private data and the uclass data will all
> +   still be present. This is where the hardware can be shut down. It is
> +   intended that the device be completely inactive at this point, For U-Boot
> +   to be sure that no hardware is running, it should be enough to remove
> +   all devices.
> +
> +   d. The device memory is freed (platform data, private data, uclass data).
> +
> +   Note: for a U_BOOT_DEVICE() declaration, the platform data is supplied as
> +   a static pointer and is not allocated. For device tree, the platform
> +   data is allocated during activation and freed during dectivation,
> +   typically automatically using platdata_auto_alloc_size. But if that value
> +   is 0 then U-Boot will not do the allocation/freeing and you will need to
> +   do this yourself in your ofdata_to_platdata() and remove() methods. This
> +   difference is tracked by the device's DM_FLAG_ALLOC_PDATA flag.

"PDATA" is slightly ambiguous: "platform data" vs "priv data".  This is
meant to be PLATDATA, right?

> +   e. The device is marked inactive. Note that it is still bound, so the
> +   device structure itself is not freed at this point. Should the device be
> +   activated again, then the cycle starts again at step 4 above.
> +
> +7. The device is unbound. This is the step that actually destroys the

Destroys the... the... the something!  Dammit getting old is hell! :-)

Overall, yes!  Thank you.  This documentation supplies a lot of the missing
knowledge about the inner workings of the Device Model.

I think there are a few lingering issues around the UCLASS structure that
will need some clarification still, though.

Thanks and HTH,
jdl