Skip to contentSkip to conversation

Add documentation on meaning of -EPROBE_DEFER

PATCH In review Grant Likely 6 participants 10 messages Mar 27, 2020 – Mar 31, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Add documentation on meaning of -EPROBE_DEFER

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

Cc Jonathan Corbet <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Saravana Kannan <[email protected]>
Cc Andy Shevchenko <[email protected]>
---
 .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
 1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +27 -5
index baa6a85c8287..63057d9bc8a6 100644
@@ -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.
+
+::
 
-	void (*sync_state)(struct device *dev);
+	void	(*sync_state)	(struct device *dev);
 
 sync_state is called only once for a device. It's called when all the consumer
 devices of the device have successfully probed. The list of consumers of the
@@ -212,6 +228,8 @@ over management of devices from the bootloader, the usage of sync_state() is
 not restricted to that. Use it whenever it makes sense to take an action after
 all the consumers of a device have probed.
 
+::
+
 	int 	(*remove)	(struct device *dev);
 
 remove is called to unbind a driver from a device. This may be
@@ -224,11 +242,15 @@ not. It should free any resources allocated specifically for the
 device; i.e. anything in the device's driver_data field.
 
 If the device is still present, it should quiesce the device and place
-it into a supported low-power state::
+it into a supported low-power state.
+
+::
 
 	int	(*suspend)	(struct device *dev, pm_message_t state);
 
-suspend is called to put the device in a low power state::
+suspend is called to put the device in a low power state.
+
+::
 
 	int	(*resume)	(struct device *dev);
 
Signature · 1 line
2.20.1
#1 lore raw
Quoted 40 lines · Grant Likely

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

Cc Jonathan Corbet <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Saravana Kannan <[email protected]>
Cc Andy Shevchenko <[email protected]>
---
 .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
 1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +6 -2
index baa6a85c8287..63057d9bc8a6 100644
@@ -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

Documentation/driver-api/driver-model/driver.rst the driver to that device. · line 184

Quoted 10 lines
Documentation/driver-api/driver-model/driver.rst +10 -0
+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?

-Saravana

#2 lore raw
Quoted 47 lines · Saravana Kannan
Quoted 46 lines · Grant Likely

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

Cc Jonathan Corbet <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Saravana Kannan <[email protected]>
Cc Andy Shevchenko <[email protected]>
---
  .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
  1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +12 -2
index baa6a85c8287..63057d9bc8a6 100644
@@ -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
Quoted 8 lines

Documentation/driver-api/driver-model/driver.rst the driver to that device. · line 184

Quoted 4 lines
Documentation/driver-api/driver-model/driver.rst +4 -0
+      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.

g.

#3 lore raw
Quoted 60 lines · Grant Likely
Quoted 47 lines · Saravana Kannan
Quoted 46 lines · Grant Likely

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

Cc Jonathan Corbet <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Saravana Kannan <[email protected]>
Cc Andy Shevchenko <[email protected]>
---
  .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
  1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +12 -2
index baa6a85c8287..63057d9bc8a6 100644
@@ -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
Quoted 8 lines

Documentation/driver-api/driver-model/driver.rst the driver to that device. · line 184

Quoted 4 lines
Documentation/driver-api/driver-model/driver.rst +4 -0
+      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?

Quoted 3 lines

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

#4 lore raw
Quoted 8 lines · Saravana Kannan
Quoted 7 lines · Grant Likely
Quoted 6 lines · Saravana Kannan
Quoted 5 lines · Grant Likely

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.

...

Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Documentation/driver-api/driver-model/driver.rst +10 -0
+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
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

Documentation/driver-api/driver-model/driver.rst the driver to that device. · line 184

Quoted 4 lines
Documentation/driver-api/driver-model/driver.rst +4 -0
+      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?

Why? *Good* documentation must describe the actual behaviour, not hide it.

Quoted 6 lines
Quoted 3 lines

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"

I think it should not distort the reality.

Quoted 2 lines

because if documented as "infinite loop" people might be hesitant towards removing that behavior.

This is funny argument. Won't we do kernel better?

Quoted 2 lines

But I'll let Greg make the
final call. Not going to NACK for this point.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
maintainer
#5 lore raw
In reply to Saravana Kannan
Quoted 4 lines · On Fri, 27 Mar 2020 16:55:34 -0700 Saravana Kannan <[email protected]> wrote:
Quoted 4 lines
Quoted 3 lines

The infinite loop is a current implementation behavior. Not an intentional choice. So, maybe we can say the behavior is undefined instead?

Quoted 8 lines
Quoted 3 lines

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.

FWIW, kernel developers have to cope with enough trouble from "undefined behavior" already; I don't think we should really be adding that to our own docs. We can certainly document the infinite loop behavior as being not guaranteed as part of the API if we're worried that somebody might start to rely on it...:)

Thanks,

jon

#6 lore raw
Quoted 17 lines · Jonathan Corbet
Quoted 4 lines · On Fri, 27 Mar 2020 16:55:34 -0700 Saravana Kannan <[email protected]> wrote:
Quoted 4 lines
Quoted 3 lines

The infinite loop is a current implementation behavior. Not an intentional choice. So, maybe we can say the behavior is undefined instead?

Quoted 8 lines
Quoted 3 lines

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.

Quoted 5 lines

FWIW, kernel developers have to cope with enough trouble from "undefined behavior" already; I don't think we should really be adding that to our own docs. We can certainly document the infinite loop behavior as being not guaranteed as part of the API if we're worried that somebody might start to rely on it...:)

Ok, all of you have convinced me of the error of my ways. :)

Thanks,
Saravana

Reviewed-by on v1 1/1
#7 lore raw
In reply to Grant Likely
Quoted 6 lines · Grant Likely

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

Greg, can we at least for time being have this documented, means applied?

FWIW,

Quoted 80 lines
Cc Jonathan Corbet <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Saravana Kannan <[email protected]>
Cc Andy Shevchenko <[email protected]>
---
 .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
 1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +27 -5
index baa6a85c8287..63057d9bc8a6 100644
@@ -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.
+
+::
 
-	void (*sync_state)(struct device *dev);
+	void	(*sync_state)	(struct device *dev);
 
 sync_state is called only once for a device. It's called when all the consumer
 devices of the device have successfully probed. The list of consumers of the
@@ -212,6 +228,8 @@ over management of devices from the bootloader, the usage of sync_state() is
 not restricted to that. Use it whenever it makes sense to take an action after
 all the consumers of a device have probed.
 
+::
+
 	int 	(*remove)	(struct device *dev);
 
 remove is called to unbind a driver from a device. This may be
@@ -224,11 +242,15 @@ not. It should free any resources allocated specifically for the
 device; i.e. anything in the device's driver_data field.
 
 If the device is still present, it should quiesce the device and place
-it into a supported low-power state::
+it into a supported low-power state.
+
+::
 
 	int	(*suspend)	(struct device *dev, pm_message_t state);
 
-suspend is called to put the device in a low power state::
+suspend is called to put the device in a low power state.
+
+::
 
 	int	(*resume)	(struct device *dev);
 
Signature · 1 line
2.20.1
Signature · 2 lines
With Best Regards,
Andy Shevchenko
#8 lore raw
Quoted 9 lines · Andy Shevchenko
Quoted 6 lines · Grant Likely

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

Greg, can we at least for time being have this documented, means applied?

It's the middle of the merge window, you know I can't take anything in my trees until after -rc1 is out.

I will queue it up then, thanks.

greg k-h

#9 lore raw
Quoted 8 lines · Greg Kroah-Hartman
Quoted 6 lines · Andy Shevchenko
Quoted 5 lines · Grant Likely

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.

Quoted 6 lines
Quoted 3 lines
Quoted 1 line

Also: minor markup fixes in the same file

Greg, can we at least for time being have this documented, means applied?

It's the middle of the merge window, you know I can't take anything in my trees until after -rc1 is out.

Right.

Quoted 1 line

I will queue it up then, thanks.

Thank you!

Signature · 2 lines
With Best Regards,
Andy Shevchenko