[PATCH 1/2] dm: clarify DM_FLAG_PROBE_AFTER_BIND behaviour

[Simon Glass]

Hi Caleb,

On Fri, 17 Jan 2025 at 00:29, Caleb Connolly <caleb.connolly at linaro.org>
wrote:
>
> The DM_FLAG_PROBE_AFTER_BIND flag only makes sense on a per-device
> basis, however recently added documentation as well as some confused
> drivers imply that it might be added to a driver definition, this does
> nothing.
>
> Clarify the new documentation and expand on the comment by the
> definition to point people in the right direction.
>
> Signed-off-by: Caleb Connolly <caleb.connolly at linaro.org>
> ---
> Anecdotally, I've spent several hours being confused about this flag,
> this information would have helped me greatly.
> ---
>  doc/develop/driver-model/design.rst | 6 ++++--
>  include/dm/device.h                 | 5 ++++-
>  2 files changed, 8 insertions(+), 3 deletions(-)
>
> diff --git a/doc/develop/driver-model/design.rst
b/doc/develop/driver-model/design.rst
> index 92f638a02047..30093737200c 100644
> --- a/doc/develop/driver-model/design.rst
> +++ b/doc/develop/driver-model/design.rst
> @@ -842,10 +842,12 @@ steps (see device_probe()):
>        cause the uclass to do some housekeeping to record the device as
>        activated and 'known' by the uclass.
>
>  For some platforms, certain devices must be probed to get the platform
into
> -a working state. To help with this, drivers marked with
DM_FLAG_PROBE_AFTER_BIND
> -will be probed immediately after all devices are bound. For now, this
happens in
> +a working state. To help with this, devices marked with
DM_FLAG_PROBE_AFTER_BIND
> +will be probed immediately after all devices are bound. This flag must
be set
> +on the device in its ``bind()`` function with
> +``dev_or_flags(dev, DM_FLAG_PROBE_AFTER_BIND)``. For now, this happens in
>  SPL, before relocation and after relocation. See the call to
``dm_autoprobe()``
>  for where this is done.
>
>  The auto-probe feature is tricky because it bypasses the normal ordering
of
> diff --git a/include/dm/device.h b/include/dm/device.h
> index add67f9ec06f..678cd83c2716 100644
> --- a/include/dm/device.h
> +++ b/include/dm/device.h
> @@ -80,9 +80,12 @@ struct driver_info;
>   * e.g. for clock, which need to be active during the device-removal
phase.
>   */
>  #define DM_FLAG_VITAL                  (1 << 14)
>
> -/* Device must be probed after it was bound */
> +/* Device must be probed after it was bound. This flag is per-device and
does
> + * nothing if set on a U_BOOT_DRIVER() definition. Apply it with
> + * dev_or_flags(dev, DM_FLAG_PROBE_AFTER_BIND) in the devices bind
function.
> + */
>  #define DM_FLAG_PROBE_AFTER_BIND       (1 << 15)
>
>  /*
>   * One or multiple of these flags are passed to device_remove() so that
>
> --
> 2.48.0
>

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

Any interest in writing a test for this feature? We have already found a
few bugs.

Regards,
Simon