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

NAME

       usb_buffer_map_sg - create scatterlist DMA mapping(s) for an endpoint

SYNOPSIS

       int usb_buffer_map_sg  (struct usb_device * dev, unsigned pipe,
                                struct scatterlist * sg, int nents);

ARGUMENTS

       dev    device to which the scatterlist will be mapped

       pipe   endpoint defining the mapping direction

       sg     the scatterlist to map

       nents  the number of entries in the scatterlist

DESCRIPTION

       Return value is either < 0 (indicating no buffers could be mapped),  or
       the number of DMA mapping array entries in the scatterlist.

       The  caller is responsible for placing the resulting DMA addresses from
       the scatterlist into URB transfer buffer pointers, and for setting  the
       URB_NO_TRANSFER_DMA_MAP transfer flag in each of those URBs.

       Top  I/O  rates come from queuing URBs, instead of waiting for each one
       to complete before starting the next I/O. This is particularly easy  to
       do  with  scatterlists.  Just  allocate and submit one URB for each DMA
       mapping entry returned,  stopping  on  the  first  error  or  when  all
       succeed. Better yet, use the usb_sg_*() calls, which do that (and more)
       for you.

       This call would normally be used when translating scatterlist requests,
       rather than usb_buffer_map, since on some hardware (with IOMMUs) it may
       be able to coalesce mappings for improved I/O efficiency.

       Reverse the effect of this call with usb_buffer_unmap_sg.