Re: [PATCH] Add documentation on meaning of -EPROBE_DEFER

[Saravana Kannan]

On Fri, Mar 27, 2020 at 4:25 PM Grant Likely <grant.likely@xxxxxxx> wrote:
>
>
>
> On 27/03/2020 18:10, Saravana Kannan wrote:
> > On Fri, Mar 27, 2020 at 10:01 AM Grant Likely <grant.likely@xxxxxxx> wrote:
> >>
> >> Add a bit of documentation on what it means when a driver .probe() hook
> >> returns the -EPROBE_DEFER error code, including the limitation that
> >> -EPROBE_DEFER should be returned as early as possible, before the driver
> >> starts to register child devices.
> >>
> >> Also: minor markup fixes in the same file
> >>
> >> Signed-off-by: Grant Likely <grant.likely@xxxxxxx>
> >> Cc: Jonathan Corbet <corbet@xxxxxxx>
> >> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> >> Cc: Saravana Kannan <saravanak@xxxxxxxxxx>
> >> Cc: Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx>
> >> ---
> >>   .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
> >>   1 file changed, 27 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
> >> index baa6a85c8287..63057d9bc8a6 100644
> >> --- a/Documentation/driver-api/driver-model/driver.rst
> >> +++ b/Documentation/driver-api/driver-model/driver.rst
> >> @@ -4,7 +4,6 @@ Device Drivers
> >>
> >>   See the kerneldoc for the struct device_driver.
> >>
> >> -
> >>   Allocation
> >>   ~~~~~~~~~~
> >>
> >> @@ -167,9 +166,26 @@ the driver to that device.
> >>
> >>   A driver's probe() may return a negative errno value to indicate that
> >>   the driver did not bind to this device, in which case it should have
> >> -released all resources it allocated::
> >> +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.
> >> +
> >> +.. warning::
> >> +      -EPROBE_DEFER must not be returned if probe() has already created
> >> +      child devices, even if those child devices are removed again
> >> +      in a cleanup path. If -EPROBE_DEFER is returned after a child
> >> +      device has been registered, it may result in an infinite loop of
> >> +      .probe() calls to the same driver.
> >
> > The infinite loop is a current implementation behavior. Not an
> > intentional choice. So, maybe we can say the behavior is undefined
> > instead?
>
> If you feel strongly about it, but I don't have any problem with
> documenting it as the current implementation behaviour, and then
> changing the text if that ever changes.

Assuming Greg is okay with this doc update, I'm kinda leaning towards
"undefined" because if documented as "infinite loop" people might be
hesitant towards removing that behavior. But I'll let Greg make the
final call. Not going to NACK for this point.

-Saravana