Documentation/driver-api/usb/URB.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/usb/URB.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/usb/URB.rst
Extension
.rst
Size
11527 bytes
Lines
291
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. _usb-urb:

USB Request Block (URB)
~~~~~~~~~~~~~~~~~~~~~~~

:Revised: 2000-Dec-05
:Again:   2002-Jul-06
:Again:   2005-Sep-19
:Again:   2017-Mar-29


.. note::

    The USB subsystem now has a substantial section at :ref:`usb-hostside-api`
    section, generated from the current source code.
    This particular documentation file isn't complete and may not be
    updated to the last version; don't rely on it except for a quick
    overview.

Basic concept or 'What is an URB?'
==================================

The basic idea of the new driver is message passing, the message itself is
called USB Request Block, or URB for short.

- An URB consists of all relevant information to execute any USB transaction
  and deliver the data and status back.

- Execution of an URB is inherently an asynchronous operation, i.e. the
  :c:func:`usb_submit_urb` call returns immediately after it has successfully
  queued the requested action.

- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
  at any time.

- Each URB has a completion handler, which is called after the action
  has been successfully completed or canceled. The URB also contains a
  context-pointer for passing information to the completion handler.

- Each endpoint for a device logically supports a queue of requests.
  You can fill that queue, so that the USB hardware can still transfer
  data to an endpoint while your driver handles completion of another.
  This maximizes use of USB bandwidth, and supports seamless streaming
  of data to (or from) devices when using periodic transfer modes.


The URB structure
=================

Some of the fields in struct urb are::

  struct urb
  {
  // (IN) device and pipe specify the endpoint queue
	struct usb_device *dev;         // pointer to associated USB device
	unsigned int pipe;              // endpoint information

	unsigned int transfer_flags;    // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc.

  // (IN) all urbs need completion routines
	void *context;                  // context for completion routine
	usb_complete_t complete;        // pointer to completion routine

  // (OUT) status after each completion
	int status;                     // returned status

  // (IN) buffer used for data transfers
	void *transfer_buffer;          // associated data buffer
	u32 transfer_buffer_length;     // data buffer length
	int number_of_packets;          // size of iso_frame_desc

Annotation

Implementation Notes