[U-Boot] [PATCH v5 15/15] dm: Expand and improve the device lifecycle docs

[Jon Loeliger]

On Tue, Jun 10, 2014 at 6:53 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.
>
> Reported-by: Jon Loeliger <jdl at jdl.com>
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
> 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)


This is way betterer now.  Thanks!


Nit typo:

> +   e. If the driver provides a ofdata_to_platdata() method, then this is

s/a/an/



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

The first sentence in that paragraph confused me because I knew where it was
supposed to be headed: namely, the deallocation of the platdata.  So when it
used the "not allocated" phrase, I was taken aback.

How about something like this instead?:

Note:  Because the platform data for a U_BOOT_DEVICE() is defined with a
static pointer, it is not de-allocated during the remove() method.  For a device
instantiated using the device tree data, the platform data will be dynamically
allocated, and thus needs to be deallocated during the remove() method.
If the platdata_auto_alloc_size is non-zero, the deallocation happens
automatically
within the DM core.  However, when platdata_auto_alloc_size is 0, both the
allocation (in probe() or preferably ofdata_to_platdata()) and the deallocation
in remove() are the responsibility of the driver author.

If you'd like:

Acked-by: Jon.Loeliger <jdl at jdl.com>

Thanks,
jdl