usb: core: correct usb_get_dev() documentation
RFC PATCH 1/1 usb: core: correct usb_get_dev() documentation
In reading through a USB interface driver, I noticed that it called usb_{get,put}_dev() in its probe() and disconnect() methods. This seemed unnecessary, but a look at the comments here matched the usage.
USB interface devices seem to be well covered by the parent/child relationship of the device model, and so it should be unnecessary for a child device to grab a refcount on its parent device.
---
This reflects my understanding (and testing), as well as the majority of usage -- there are *very* few interface drivers that actually call usb_get_dev(). If I'm wrong, please feel free to tell me so! But I thought patching the documentation would be the best way to solicit a response :)
drivers/usb/core/usb.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
drivers/usb/core/usb.c +3 -3
@@ -539,9 +539,9 @@ EXPORT_SYMBOL_GPL(usb_alloc_dev);* * Each live reference to a device should be refcounted. * -* Drivers for USB interfaces should normally record such references in -* their probe() methods, when they bind to an interface, and release -* them by calling usb_put_dev(), in their disconnect() methods. +* The device driver core automatically handles this refcounting for USB +* interface drivers, but this API can be used for non-parent/child +* relationships. * * Return: A pointer to the device with the incremented reference counter. */
Signature · 1 line
2.8.0.rc3.226.g39d4020
Quoted 9 lines · Brian Norris
In reading through a USB interface driver, I noticed that it called usb_{get,put}_dev() in its
probe()anddisconnect()methods. This seemed unnecessary, but a look at the comments here matched the usage.USB interface devices seem to be well covered by the parent/child relationship of the device model, and so it should be unnecessary for a child device to grab a refcount on its parent device.
Signed-off-by Brian Norris <[email protected]>
Yes, usb_device is parent of usb_interface and device core does "parent = get_device(dev->parent);" as part of device_add() when registering new interfaces.
Quoted 29 lines
---
This reflects my understanding (and testing), as well as the majority of usage -- there are *very* few interface drivers that actually callusb_get_dev(). If I'm wrong, please feel free to tell me so! But I thought patching the documentation would be the best way to solicit a response :)drivers/usb/core/usb.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)drivers/usb/core/usb.c +3
-3@@ -539,9 +539,9 @@ EXPORT_SYMBOL_GPL(usb_alloc_dev);* * Each live reference to a device should be refcounted. * -* Drivers for USB interfaces should normally record such references in -* their probe() methods, when they bind to an interface, and release -* them by calling usb_put_dev(), in their disconnect() methods. +* The device driver core automatically handles this refcounting for USB +* interface drivers, but this API can be used for non-parent/child +* relationships. * * Return: A pointer to the device with the incremented reference counter. */ Signature · 1 line
2.8.0.rc3.226.g39d4020
Signature · 1 line
Dmitry
Quoted 9 lines · Dmitry Torokhov
Quoted 8 lines · Brian Norris
In reading through a USB interface driver, I noticed that it called usb_{get,put}_dev() in its
probe()anddisconnect()methods. This seemed unnecessary, but a look at the comments here matched the usage.USB interface devices seem to be well covered by the parent/child relationship of the device model, and so it should be unnecessary for a child device to grab a refcount on its parent device.
Quoted 8 lines
Quoted 1 line
Signed-off-by Brian Norris <[email protected]>Yes,
usb_deviceis parent ofusb_interfaceand device core does "parent =get_device(dev->parent);" as part ofdevice_add()when registering new interfaces.Reviewed-by Dmitry Torokhov <[email protected]>
Yes, current code seems a little messy for get{put}_device.
Eg, for USB device, it tries to call get_device again at usb_set_configuration when create its child device (interface device).
For USB interface device, it handles get{put}_device at message.c for common interface, it seems to be not necessary to call usb_get{put}_dev again at individual interface driver.
Peter
Quoted 36 lines
Quoted 29 lines
---
This reflects my understanding (and testing), as well as the majority of usage -- there are *very* few interface drivers that actually callusb_get_dev(). If I'm wrong, please feel free to tell me so! But I thought patching the documentation would be the best way to solicit a response :)drivers/usb/core/usb.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)drivers/usb/core/usb.c +3
-3@@ -539,9 +539,9 @@ EXPORT_SYMBOL_GPL(usb_alloc_dev);* * Each live reference to a device should be refcounted. * -* Drivers for USB interfaces should normally record such references in -* their probe() methods, when they bind to an interface, and release -* them by calling usb_put_dev(), in their disconnect() methods. +* The device driver core automatically handles this refcounting for USB +* interface drivers, but this API can be used for non-parent/child +* relationships. * * Return: A pointer to the device with the incremented reference counter. */ Signature · 1 line
2.8.0.rc3.226.g39d4020Signature · 5 lines
Dmitry -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Signature · 2 lines
Best Regards, Peter Chen