diff options
author | Alan Stern <stern@rowland.harvard.edu> | 2012-03-28 16:13:28 -0400 |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@linuxfoundation.org> | 2012-04-06 16:54:00 -0400 |
commit | da8bfb090c2b30af9f3879443355f7eb1d0fe10a (patch) | |
tree | 377d67c3c0cc1ad40d7357f821712c4c9ba6c639 | |
parent | bcf398537630bf20b4dbe59ba855b69f404c93cf (diff) |
USB documentation: explain lifetime rules for unlinking URBs
This patch (as1534c) updates the documentation for usb_unlink_urb and
related functions. It explains that the caller must prevent the URB
being unlinked from getting deallocated while the unlink is taking
place.
Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
CC: Ming Lei <tom.leiming@gmail.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-rw-r--r-- | Documentation/usb/URB.txt | 22 | ||||
-rw-r--r-- | drivers/usb/core/urb.c | 12 |
2 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/usb/URB.txt b/Documentation/usb/URB.txt index 8ffce746d496..00d2c644068e 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/usb/URB.txt | |||
@@ -168,6 +168,28 @@ that if the completion handler or anyone else tries to resubmit it | |||
168 | they will get a -EPERM error. Thus you can be sure that when | 168 | they will get a -EPERM error. Thus you can be sure that when |
169 | usb_kill_urb() returns, the URB is totally idle. | 169 | usb_kill_urb() returns, the URB is totally idle. |
170 | 170 | ||
171 | There is a lifetime issue to consider. An URB may complete at any | ||
172 | time, and the completion handler may free the URB. If this happens | ||
173 | while usb_unlink_urb or usb_kill_urb is running, it will cause a | ||
174 | memory-access violation. The driver is responsible for avoiding this, | ||
175 | which often means some sort of lock will be needed to prevent the URB | ||
176 | from being deallocated while it is still in use. | ||
177 | |||
178 | On the other hand, since usb_unlink_urb may end up calling the | ||
179 | completion handler, the handler must not take any lock that is held | ||
180 | when usb_unlink_urb is invoked. The general solution to this problem | ||
181 | is to increment the URB's reference count while holding the lock, then | ||
182 | drop the lock and call usb_unlink_urb or usb_kill_urb, and then | ||
183 | decrement the URB's reference count. You increment the reference | ||
184 | count by calling | ||
185 | |||
186 | struct urb *usb_get_urb(struct urb *urb) | ||
187 | |||
188 | (ignore the return value; it is the same as the argument) and | ||
189 | decrement the reference count by calling usb_free_urb. Of course, | ||
190 | none of this is necessary if there's no danger of the URB being freed | ||
191 | by the completion handler. | ||
192 | |||
171 | 193 | ||
172 | 1.7. What about the completion handler? | 194 | 1.7. What about the completion handler? |
173 | 195 | ||
diff --git a/drivers/usb/core/urb.c b/drivers/usb/core/urb.c index 7239a73c1b8c..cd9b3a2cd8a7 100644 --- a/drivers/usb/core/urb.c +++ b/drivers/usb/core/urb.c | |||
@@ -539,6 +539,10 @@ EXPORT_SYMBOL_GPL(usb_submit_urb); | |||
539 | * never submitted, or it was unlinked before, or the hardware is already | 539 | * never submitted, or it was unlinked before, or the hardware is already |
540 | * finished with it), even if the completion handler has not yet run. | 540 | * finished with it), even if the completion handler has not yet run. |
541 | * | 541 | * |
542 | * The URB must not be deallocated while this routine is running. In | ||
543 | * particular, when a driver calls this routine, it must insure that the | ||
544 | * completion handler cannot deallocate the URB. | ||
545 | * | ||
542 | * Unlinking and Endpoint Queues: | 546 | * Unlinking and Endpoint Queues: |
543 | * | 547 | * |
544 | * [The behaviors and guarantees described below do not apply to virtual | 548 | * [The behaviors and guarantees described below do not apply to virtual |
@@ -603,6 +607,10 @@ EXPORT_SYMBOL_GPL(usb_unlink_urb); | |||
603 | * with error -EPERM. Thus even if the URB's completion handler always | 607 | * with error -EPERM. Thus even if the URB's completion handler always |
604 | * tries to resubmit, it will not succeed and the URB will become idle. | 608 | * tries to resubmit, it will not succeed and the URB will become idle. |
605 | * | 609 | * |
610 | * The URB must not be deallocated while this routine is running. In | ||
611 | * particular, when a driver calls this routine, it must insure that the | ||
612 | * completion handler cannot deallocate the URB. | ||
613 | * | ||
606 | * This routine may not be used in an interrupt context (such as a bottom | 614 | * This routine may not be used in an interrupt context (such as a bottom |
607 | * half or a completion handler), or when holding a spinlock, or in other | 615 | * half or a completion handler), or when holding a spinlock, or in other |
608 | * situations where the caller can't schedule(). | 616 | * situations where the caller can't schedule(). |
@@ -640,6 +648,10 @@ EXPORT_SYMBOL_GPL(usb_kill_urb); | |||
640 | * with error -EPERM. Thus even if the URB's completion handler always | 648 | * with error -EPERM. Thus even if the URB's completion handler always |
641 | * tries to resubmit, it will not succeed and the URB will become idle. | 649 | * tries to resubmit, it will not succeed and the URB will become idle. |
642 | * | 650 | * |
651 | * The URB must not be deallocated while this routine is running. In | ||
652 | * particular, when a driver calls this routine, it must insure that the | ||
653 | * completion handler cannot deallocate the URB. | ||
654 | * | ||
643 | * This routine may not be used in an interrupt context (such as a bottom | 655 | * This routine may not be used in an interrupt context (such as a bottom |
644 | * half or a completion handler), or when holding a spinlock, or in other | 656 | * half or a completion handler), or when holding a spinlock, or in other |
645 | * situations where the caller can't schedule(). | 657 | * situations where the caller can't schedule(). |