Provided by: linux-doc-2.6.15_2.6.15-23.39_all bug

NAME

       struct urb - USB Request Block

SYNOPSIS

       struct urb {
         struct list_head urb_list;
         struct usb_device * dev;
         unsigned int pipe;
         int status;
         unsigned int transfer_flags;
         void * transfer_buffer;
         dma_addr_t transfer_dma;
         int transfer_buffer_length;
         int actual_length;
         unsigned char * setup_packet;
         dma_addr_t setup_dma;
         int start_frame;
         int number_of_packets;
         int interval;
         int error_count;
         void * context;
         usb_complete_t complete;
         struct usb_iso_packet_descriptor iso_frame_desc[0];
       };

MEMBERS

       urb_list
              For use by current owner of the URB.

       dev    Identifies the USB device to perform the request.

       pipe   Holds  endpoint  number, direction, type, and more. Create these
              values      with      the      eight      macros      available;
              usb_{snd,rcv}TYPEpipe(dev,endpoint),  where the TYPE is ‘‘ctrl’’
              (control),   ‘‘bulk’’,   ‘‘int’’   (interrupt),    or    ‘‘iso’’
              (isochronous).  For  example  usb_sndbulkpipe or usb_rcvintpipe.
              Endpoint numbers range from zero to fifteen.  Note  that  ‘‘in’’
              endpoint  two  is  a  different endpoint (and pipe) from ‘‘out’’
              endpoint two. The current configuration controls the  existence,
              type, and maximum packet size of any given endpoint.

       status This  is  read in non-iso completion functions to get the status
              of the particular request. ISO requests  only  use  it  to  tell
              whether  the URB was unlinked; detailed status for each frame is
              in the fields of the iso_frame-desc.

       transfer_flags
              A variety of flags may be used to  affect  how  URB  submission,
              unlinking,  or operation are handled. Different kinds of URB can
              use different flags.

       transfer_buffer
              This identifies the buffer to (or from) which  the  I/O  request
              will  be performed (unless URB_NO_TRANSFER_DMA_MAP is set). This
              buffer must be suitable for DMA; allocate  it  with  kmalloc  or
              equivalent.  For transfers to ‘‘in’’ endpoints, contents of this
              buffer will be modified. This buffer is used for the data  stage
              of control transfers.

       transfer_dma
              When transfer_flags includes URB_NO_TRANSFER_DMA_MAP, the device
              driver is saying that it provided this DMA  address,  which  the
              host   controller   driver  should  use  in  preference  to  the
              transfer_buffer.

       transfer_buffer_length
              How big is transfer_buffer. The transfer may be broken  up  into
              chunks  according  to  the  current  maximum packet size for the
              endpoint, which is  a  function  of  the  configuration  and  is
              encoded   in   the  pipe.  When  the  length  is  zero,  neither
              transfer_buffer nor transfer_dma is used.

       actual_length
              This is read in non-iso completion functions, and it  tells  how
              many  bytes (out of transfer_buffer_length) were transferred. It
              will normally be the same as requested, unless either  an  error
              was reported or a short read was performed. The URB_SHORT_NOT_OK
              transfer flag may be used to make such short reads  be  reported
              as errors.

       setup_packet
              Only  used  for control transfers, this points to eight bytes of
              setup data. Control transfers always start by sending this  data
              to  the  device.  Then  transfer_buffer  is  read or written, if
              needed.

       setup_dma
              For control transfers with URB_NO_SETUP_DMA_MAP set, the  device
              driver  has  provided this DMA address for the setup packet. The
              host  controller  driver  should  use  this  in  preference   to
              setup_packet.

       start_frame
              Returns the initial frame for isochronous transfers.

       number_of_packets
              Lists the number of ISO transfer buffers.

       interval
              Specifies  the  polling  interval  for  interrupt or isochronous
              transfers. The units are frames (milliseconds) for for full  and
              low   speed  devices,  and  microframes  (1/8  millisecond)  for
              highspeed ones.

       error_count
              Returns the number of ISO transfers that reported errors.

       context
              For  use  in  completion  functions.  This  normally  points  to
              request-specific driver context.

       complete
              Completion  handler.  This URB is passed as the parameter to the
              completion function. The completion function may then do what it
              likes with the URB, including resubmitting or freeing it.

       iso_frame_desc[0]
              Used  to  provide  arrays of ISO transfer buffers and to collect
              the transfer status for each buffer.

DESCRIPTION

       This structure identifies USB transfer requests. URBs must be allocated
       by  calling  usb_alloc_urb  and  freed  with  a  call  to usb_free_urb.
       Initialization may be done using various usb_fill_*_urb functions. URBs
       are  submitted  using  usb_submit_urb,  and  pending  requests  may  be
       canceled using usb_unlink_urb or usb_kill_urb.

DATA TRANSFER BUFFERS

       Normally  drivers  provide  I/O  buffers  allocated  with  kmalloc   or
       otherwise  taken  from  the  general  page  pool.  That  is provided by
       transfer_buffer (control requests  also  use  setup_packet),  and  host
       controller  drivers  perform  a  dma  mapping  (and unmapping) for each
       buffer transferred. Those mapping operations can be expensive  on  some
       platforms  (perhaps  using a dma bounce buffer or talking to an IOMMU),
       although they’re cheap on commodity x86 and ppc hardware.

       Alternatively, drivers may pass the URB_NO_xxx_DMA_MAP transfer  flags,
       which  tell  the  host controller driver that no such mapping is needed
       since the device driver is DMA-aware.  For  example,  a  device  driver
       might   allocate   a   DMA   buffer   with   usb_buffer_alloc  or  call
       usb_buffer_map. When these transfer flags are provided, host controller
       drivers will attempt to use the dma addresses found in the transfer_dma
       and/or  setup_dma  fields  rather  than  determining  a   dma   address
       themselves.  (Note  that transfer_buffer and setup_packet must still be
       set because not all host controllers  use  DMA,  nor  do  virtual  root
       hubs).

INITIALIZATION

       All  URBs  submitted must initialize the dev, pipe, transfer_flags (may
       be  zero),  and  complete  fields.  All  URBs  must   also   initialize
       transfer_buffer   and  transfer_buffer_length.  They  may  provide  the
       URB_SHORT_NOT_OK transfer flag, indicating that short reads are  to  be
       treated as errors; that flag is invalid for write requests.

       Bulk  URBs  may  use the URB_ZERO_PACKET transfer flag, indicating that
       bulk OUT transfers should always terminate with a short packet, even if
       it means adding an extra zero length packet.

       Control   URBs  must  provide  a  setup_packet.  The  setup_packet  and
       transfer_buffer may each be mapped for DMA or not, independently of the
       other.    The    transfer_flags    bits   URB_NO_TRANSFER_DMA_MAP   and
       URB_NO_SETUP_DMA_MAP indicate which buffers have already  been  mapped.
       URB_NO_SETUP_DMA_MAP is ignored for non-control URBs.

       Interrupt   URBs  must  provide  an  interval,  saying  how  often  (in
       milliseconds or, for highspeed devices, 125 microsecond units) to  poll
       for  transfers.  After  the  URB has been submitted, the interval field
       reflects how the transfer was actually scheduled. The polling  interval
       may be more frequent than requested. For example, some controllers have
       a maximum interval of 32 milliseconds, while others  support  intervals
       of  up  to  1024  milliseconds.  Isochronous  URBs  also  have transfer
       intervals. (Note that for isochronous endpoints, as well as high  speed
       interrupt  endpoints,  the  encoding  of  the  transfer interval in the
       endpoint descriptor is logarithmic. Device drivers  must  convert  that
       value to linear units themselves.)

       Isochronous  URBs  normally use the URB_ISO_ASAP transfer flag, telling
       the host controller to schedule  the  transfer  as  soon  as  bandwidth
       utilization  allows,  and  then  set  start_frame to reflect the actual
       frame selected during submission. Otherwise drivers  must  specify  the
       start_frame  and  handle  the case where the transfer can’t begin then.
       However, drivers won’t know how bandwidth is currently  allocated,  and
       while     they     can     find     the     current     frame     using
       usb_get_current_frame_number () they can’t  know  the  range  for  that
       frame number. (Ranges for frame counter values are HC-specific, and can
       go from 256 to 65536 frames from ‘‘now’’.)

       Isochronous URBs have a different data transfer model, in part  because
       the  quality  of  service  is  only  ‘‘best  effort’’.  Callers provide
       specially   allocated   URBs,   with   number_of_packets    worth    of
       iso_frame_desc structures at the end. Each such packet is an individual
       ISO transfer.  Isochronous  URBs  are  normally  queued,  submitted  by
       drivers  to  arrange  that  transfers are at least double buffered, and
       then explicitly resubmitted in completion handlers, so that data  (such
       as audio or video) streams at as constant a rate as the host controller
       scheduler can support.

COMPLETION CALLBACKS

       The completion callback is made in_interrupt,  and  one  of  the  first
       things  that  a completion handler should do is check the status field.
       The status field is provided  for  all  URBs.  It  is  used  to  report
       unlinked  URBs,  and status for all non-ISO transfers. It should not be
       examined before the URB is returned to the completion handler.

       The context field is normally used to link URBs back  to  the  relevant
       driver or request state.

       When  the  completion callback is invoked for non-isochronous URBs, the
       actual_length field tells how many bytes were transferred.  This  field
       is  updated even when the URB terminated with an error or was unlinked.

       ISO transfer status is reported in the status and actual_length  fields
       of  the  iso_frame_desc  array, and the number of errors is reported in
       error_count. Completion  callbacks  for  ISO  transfers  will  normally
       (re)submit URBs to ensure a constant transfer rate.

       Note  that  even  fields marked ‘‘public’’ should not be touched by the
       driver when the urb is owned by the hcd, that is,  since  the  call  to
       usb_submit_urb till the entry into the completion routine.