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>

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>
Alan Stern · Greg Kroah-Hartman
1 parent bcf3985376
Showing 2 changed files with 34 additions and 0 deletions Side-by-side Diff
Documentation/usb/URB.txt
drivers/usb/core/urb.c
@@ -168,6 +168,28 @@
 they will get a -EPERM error.  Thus you can be sure that when
 usb_kill_urb() returns, the URB is totally idle.
  
+There is a lifetime issue to consider.  An URB may complete at any
+time, and the completion handler may free the URB.  If this happens
+while usb_unlink_urb or usb_kill_urb is running, it will cause a
+memory-access violation.  The driver is responsible for avoiding this,
+which often means some sort of lock will be needed to prevent the URB
+from being deallocated while it is still in use.
+
+On the other hand, since usb_unlink_urb may end up calling the
+completion handler, the handler must not take any lock that is held
+when usb_unlink_urb is invoked.  The general solution to this problem
+is to increment the URB's reference count while holding the lock, then
+drop the lock and call usb_unlink_urb or usb_kill_urb, and then
+decrement the URB's reference count.  You increment the reference
+count by calling
+
+	struct urb *usb_get_urb(struct urb *urb)
+
+(ignore the return value; it is the same as the argument) and
+decrement the reference count by calling usb_free_urb.  Of course,
+none of this is necessary if there's no danger of the URB being freed
+by the completion handler.
+
  
 1.7. What about the completion handler?
  
@@ -539,6 +539,10 @@
  * never submitted, or it was unlinked before, or the hardware is already
  * finished with it), even if the completion handler has not yet run.
  *
+ * The URB must not be deallocated while this routine is running.  In
+ * particular, when a driver calls this routine, it must insure that the
+ * completion handler cannot deallocate the URB.
+ *
  * Unlinking and Endpoint Queues:
  *
  * [The behaviors and guarantees described below do not apply to virtual
@@ -603,6 +607,10 @@
  * with error -EPERM.  Thus even if the URB's completion handler always
  * tries to resubmit, it will not succeed and the URB will become idle.
  *
+ * The URB must not be deallocated while this routine is running.  In
+ * particular, when a driver calls this routine, it must insure that the
+ * completion handler cannot deallocate the URB.
+ *
  * This routine may not be used in an interrupt context (such as a bottom
  * half or a completion handler), or when holding a spinlock, or in other
  * situations where the caller can't schedule().
@@ -639,6 +647,10 @@
  * After and while the routine runs, attempts to resubmit the URB will fail
  * with error -EPERM.  Thus even if the URB's completion handler always
  * tries to resubmit, it will not succeed and the URB will become idle.
+ *
+ * The URB must not be deallocated while this routine is running.  In
+ * particular, when a driver calls this routine, it must insure that the
+ * completion handler cannot deallocate the URB.
  *
  * This routine may not be used in an interrupt context (such as a bottom
  * half or a completion handler), or when holding a spinlock, or in other
...	...	@@ -168,6 +168,28 @@
168	168	they will get a -EPERM error. Thus you can be sure that when
169	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	194	1.7. What about the completion handler?
173	195
...	...	@@ -539,6 +539,10 @@
539	539	* never submitted, or it was unlinked before, or the hardware is already
540	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	546	* Unlinking and Endpoint Queues:
543	547	*
544	548	* [The behaviors and guarantees described below do not apply to virtual
...	...	@@ -603,6 +607,10 @@
603	607	* with error -EPERM. Thus even if the URB's completion handler always
604	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	614	* This routine may not be used in an interrupt context (such as a bottom
607	615	* half or a completion handler), or when holding a spinlock, or in other
608	616	* situations where the caller can't schedule().
...	...	@@ -639,6 +647,10 @@
639	647	* After and while the routine runs, attempts to resubmit the URB will fail
640	648	* with error -EPERM. Thus even if the URB's completion handler always
641	649	* tries to resubmit, it will not succeed and the URB will become idle.
	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.
642	654	*
643	655	* This routine may not be used in an interrupt context (such as a bottom
644	656	* half or a completion handler), or when holding a spinlock, or in other