The existing documentation for EPROBE_DEFER explains its purpose
and usage, but does not specify when deferred probes are retried.
This patch adds information about the retry mechanism to provide
a more complete explanation of how EPROBE_DEFER works.

Specifically, it clarifies that:

1. Deferred probes are added to a pending list
2. A successful probe of any device triggers moving all devices
   from the pending list to an active list
3. A workqueue processes the active list to retry deferred probes

This additional context helps developers better understand the
behavior and implications of using EPROBE_DEFER in their drivers.

Signed-off-by: anish kumar <yesanishhere@gmail.com>
---
 Documentation/driver-api/driver-model/driver.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index 06f818b1d622..c86b948d0dfe 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -171,10 +171,13 @@ released all resources it allocated.
 Optionally, probe() may return -EPROBE_DEFER if the driver depends on
 resources that are not yet available (e.g., supplied by a driver that
 hasn't initialized yet).  The driver core will put the device onto the
-deferred probe list and will try to call it again later. If a driver
-must defer, it should return -EPROBE_DEFER as early as possible to
-reduce the amount of time spent on setup work that will need to be
-unwound and reexecuted at a later time.
+deferred probe list and will retry again as and when a device or driver
+gets added to the system. A successful probe of any device will trigger
+moving all devices from pending list to active list. A workqueue processes
+the active list to retry deferred probes. If a driver must defer, it
+should return -EPROBE_DEFER as early as possible to reduce the amount
+of time spent on setup work that will need to be unwound and reexecuted
+at a later time.
 
 .. warning::
       -EPROBE_DEFER must not be returned if probe() has already created
-- 
2.39.3 (Apple Git-146)

anish kumar <yesanishhere@gmail.com> writes:

> The existing documentation for EPROBE_DEFER explains its purpose
> and usage, but does not specify when deferred probes are retried.
> This patch adds information about the retry mechanism to provide
> a more complete explanation of how EPROBE_DEFER works.
>
> Specifically, it clarifies that:
>
> 1. Deferred probes are added to a pending list
> 2. A successful probe of any device triggers moving all devices
>    from the pending list to an active list
> 3. A workqueue processes the active list to retry deferred probes
>
> This additional context helps developers better understand the
> behavior and implications of using EPROBE_DEFER in their drivers.
>
> Signed-off-by: anish kumar <yesanishhere@gmail.com>
> ---
>  Documentation/driver-api/driver-model/driver.rst | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
> index 06f818b1d622..c86b948d0dfe 100644
> --- a/Documentation/driver-api/driver-model/driver.rst
> +++ b/Documentation/driver-api/driver-model/driver.rst
> @@ -171,10 +171,13 @@ released all resources it allocated.
>  Optionally, probe() may return -EPROBE_DEFER if the driver depends on
>  resources that are not yet available (e.g., supplied by a driver that
>  hasn't initialized yet).  The driver core will put the device onto the
> -deferred probe list and will try to call it again later. If a driver
> -must defer, it should return -EPROBE_DEFER as early as possible to
> -reduce the amount of time spent on setup work that will need to be
> -unwound and reexecuted at a later time.
> +deferred probe list and will retry again as and when a device or driver
> +gets added to the system. A successful probe of any device will trigger
> +moving all devices from pending list to active list. A workqueue processes
> +the active list to retry deferred probes. If a driver must defer, it
> +should return -EPROBE_DEFER as early as possible to reduce the amount
> +of time spent on setup work that will need to be unwound and reexecuted
> +at a later time.

Honestly, I don't see how this improves the situation?  How does this
improve a driver developer's work?

jon

On Tue, Nov 12, 2024 at 12:21 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> anish kumar <yesanishhere@gmail.com> writes:
>
> > The existing documentation for EPROBE_DEFER explains its purpose
> > and usage, but does not specify when deferred probes are retried.
> > This patch adds information about the retry mechanism to provide
> > a more complete explanation of how EPROBE_DEFER works.
> >
> > Specifically, it clarifies that:
> >
> > 1. Deferred probes are added to a pending list
> > 2. A successful probe of any device triggers moving all devices
> >    from the pending list to an active list
> > 3. A workqueue processes the active list to retry deferred probes
> >
> > This additional context helps developers better understand the
> > behavior and implications of using EPROBE_DEFER in their drivers.
> >
> > Signed-off-by: anish kumar <yesanishhere@gmail.com>
> > ---
> >  Documentation/driver-api/driver-model/driver.rst | 11 +++++++----
> >  1 file changed, 7 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
> > index 06f818b1d622..c86b948d0dfe 100644
> > --- a/Documentation/driver-api/driver-model/driver.rst
> > +++ b/Documentation/driver-api/driver-model/driver.rst
> > @@ -171,10 +171,13 @@ released all resources it allocated.
> >  Optionally, probe() may return -EPROBE_DEFER if the driver depends on
> >  resources that are not yet available (e.g., supplied by a driver that
> >  hasn't initialized yet).  The driver core will put the device onto the
> > -deferred probe list and will try to call it again later. If a driver
> > -must defer, it should return -EPROBE_DEFER as early as possible to
> > -reduce the amount of time spent on setup work that will need to be
> > -unwound and reexecuted at a later time.
> > +deferred probe list and will retry again as and when a device or driver
> > +gets added to the system. A successful probe of any device will trigger
> > +moving all devices from pending list to active list. A workqueue processes
> > +the active list to retry deferred probes. If a driver must defer, it
> > +should return -EPROBE_DEFER as early as possible to reduce the amount
> > +of time spent on setup work that will need to be unwound and reexecuted
> > +at a later time.
>
> Honestly, I don't see how this improves the situation?  How does this
> improve a driver developer's work?

It talks about when the retry mechanism executes. In my workplace we
had the discussion about this and some of the developers were assuming
EPROBE_DEFER gets called a fixed number of times which is not the case.
This explains when EPROBE_DEFER gets called and the mechanism for the
same.

>
> jon

Hello Jonathan,

Wondering if you have any comments?

On Mon, Nov 4, 2024 at 8:55 PM anish kumar <yesanishhere@gmail.com> wrote:
>
> The existing documentation for EPROBE_DEFER explains its purpose
> and usage, but does not specify when deferred probes are retried.
> This patch adds information about the retry mechanism to provide
> a more complete explanation of how EPROBE_DEFER works.
>
> Specifically, it clarifies that:
>
> 1. Deferred probes are added to a pending list
> 2. A successful probe of any device triggers moving all devices
>    from the pending list to an active list
> 3. A workqueue processes the active list to retry deferred probes
>
> This additional context helps developers better understand the
> behavior and implications of using EPROBE_DEFER in their drivers.
>
> Signed-off-by: anish kumar <yesanishhere@gmail.com>
> ---
>  Documentation/driver-api/driver-model/driver.rst | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
> index 06f818b1d622..c86b948d0dfe 100644
> --- a/Documentation/driver-api/driver-model/driver.rst
> +++ b/Documentation/driver-api/driver-model/driver.rst
> @@ -171,10 +171,13 @@ released all resources it allocated.
>  Optionally, probe() may return -EPROBE_DEFER if the driver depends on
>  resources that are not yet available (e.g., supplied by a driver that
>  hasn't initialized yet).  The driver core will put the device onto the
> -deferred probe list and will try to call it again later. If a driver
> -must defer, it should return -EPROBE_DEFER as early as possible to
> -reduce the amount of time spent on setup work that will need to be
> -unwound and reexecuted at a later time.
> +deferred probe list and will retry again as and when a device or driver
> +gets added to the system. A successful probe of any device will trigger
> +moving all devices from pending list to active list. A workqueue processes
> +the active list to retry deferred probes. If a driver must defer, it
> +should return -EPROBE_DEFER as early as possible to reduce the amount
> +of time spent on setup work that will need to be unwound and reexecuted
> +at a later time.
>
>  .. warning::
>        -EPROBE_DEFER must not be returned if probe() has already created
> --
> 2.39.3 (Apple Git-146)
>

anish kumar <yesanishhere@gmail.com> writes:

> Hello Jonathan,
>
> Wondering if you have any comments?

It has been three days - and not the nicest days at that.  Please be
more patient.

jon