Add documentation on meaning of -EPROBE_DEFER
Subsystems (2)
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
--- .../driver-api/driver-model/driver.rst | 32 ++++++++++++++++--- 1 file changed, 27 insertions(+), 5 deletions(-)
Documentation/driver-api/driver-model/driver.rst +27 -5
@@ -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
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
Signed-off-by Grant Likely <[email protected]>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@@ -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
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
Signed-off-by Grant Likely <[email protected]>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@@ -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.
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
Signed-off-by Grant Likely <[email protected]>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@@ -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 createdQuoted 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
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
Jonathan Corbet
maintainerQuoted 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
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
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
Signed-off-by Grant Likely <[email protected]>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@@ -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
Greg Kroah-Hartman
maintainerQuoted 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
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