USB_BUFFER_MAP_SG(9) USB Core APIs USB_BUFFER_MAP_SG(9)NAME
usb_buffer_map_sg - create scatterlist DMA mapping(s) for an endpoint
SYNOPSIS
int usb_buffer_map_sg(const struct usb_device * dev, int is_in, struct scatterlist * sg, int nents);
ARGUMENTS
dev
device to which the scatterlist will be mapped
is_in
mapping transfer 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.
COPYRIGHT Kernel Hackers Manual 2.6. July 2010 USB_BUFFER_MAP_SG(9)
Check Out this Related Man Page
STRUCT USB_REQUEST(9) Kernel Mode Gadget API STRUCT USB_REQUEST(9)NAME
struct_usb_request - describes one i/o request
SYNOPSIS
struct usb_request {
void * buf;
unsigned length;
dma_addr_t dma;
struct scatterlist * sg;
unsigned num_sgs;
unsigned num_mapped_sgs;
unsigned stream_id:16;
unsigned no_interrupt:1;
unsigned zero:1;
unsigned short_not_ok:1;
void (* complete) (struct usb_ep *ep,struct usb_request *req);
void * context;
struct list_head list;
int status;
unsigned actual;
};
MEMBERS
buf
Buffer used for data. Always provide this; some controllers only use PIO, or don't use DMA for some endpoints.
length
Length of that data
dma
DMA address corresponding to 'buf'. If you don't set this field, and the usb controller needs one, it is responsible for mapping and
unmapping the buffer.
sg
a scatterlist for SG-capable controllers.
num_sgs
number of SG entries
num_mapped_sgs
number of SG entries mapped to DMA (internal)
stream_id
The stream id, when USB3.0 bulk streams are being used
no_interrupt
If true, hints that no completion irq is needed. Helpful sometimes with deep request queues that are handled directly by DMA
controllers.
zero
If true, when writing data, makes the last packet be "short" by adding a zero length packet as needed;
short_not_ok
When reading data, makes short packets be treated as errors (queue stops advancing till cleanup).
complete
Function called when request completes, so this request and its buffer may be re-used. The function will always be called with
interrupts disabled, and it must not sleep. Reads terminate with a short packet, or when the buffer fills, whichever comes first. When
writes terminate, some data bytes will usually still be in flight (often in a hardware fifo). Errors (for reads or writes) stop the
queue from advancing until the completion function returns, so that any transfers invalidated by the error may first be dequeued.
context
For use by the completion callback
list
For use by the gadget driver.
status
Reports completion code, zero or a negative errno. Normally, faults block the transfer queue from advancing until the completion
callback returns. Code "-ESHUTDOWN" indicates completion caused by device disconnect, or when the driver disabled the endpoint.
actual
Reports bytes transferred to/from the buffer. For reads (OUT transfers) this may be less than the requested length. If the short_not_ok
flag is set, short reads are treated as errors even when status otherwise indicates successful completion. Note that for writes (IN
transfers) some data bytes may still reside in a device-side FIFO when the request is reported as complete.
DESCRIPTION
These are allocated/freed through the endpoint they're used with. The hardware's driver can add extra per-request data to the memory it
returns, which often avoids separate memory allocations (potential failures), later when the request is queued.
Request flags affect request handling, such as whether a zero length packet is written (the "zero" flag), whether a short read should be
treated as an error (blocking request queue advance, the "short_not_ok" flag), or hinting that an interrupt is not required (the
"no_interrupt" flag, for use with deep request queues).
Bulk endpoints can use any size buffers, and can also be used for interrupt transfers. interrupt-only endpoints can be much less
functional.
NOTE
this is analogous to 'struct urb' on the host side, except that it's thinner and promotes more pre-allocation.
AUTHOR
David Brownell <dbrownell@users.sourceforge.net>
Author.
COPYRIGHT Kernel Hackers Manual 3.10 June 2014 STRUCT USB_REQUEST(9)