1STRUCT USB_REQUEST(9) Kernel Mode Gadget API STRUCT USB_REQUEST(9)
2
6 struct_usb_request - describes one i/o request
7
9 struct usb_request {
10 void * buf;
11 unsigned length;
12 dma_addr_t dma;
13 struct scatterlist * sg;
14 unsigned num_sgs;
15 unsigned num_mapped_sgs;
16 unsigned stream_id:16;
17 unsigned no_interrupt:1;
18 unsigned zero:1;
19 unsigned short_not_ok:1;
20 void (* complete) (struct usb_ep *ep,struct usb_request *req);
21 void * context;
22 struct list_head list;
23 int status;
24 unsigned actual;
25 };
26
28 buf
29 Buffer used for data. Always provide this; some controllers only
30 use PIO, or don't use DMA for some endpoints.
31 length
33 Length of that data
34 dma
36 DMA address corresponding to 'buf'. If you don't set this field,
37 and the usb controller needs one, it is responsible for mapping and
38 unmapping the buffer.
39 sg
41 a scatterlist for SG-capable controllers.
42 num_sgs
44 number of SG entries
45 num_mapped_sgs
47 number of SG entries mapped to DMA (internal)
48 stream_id
50 The stream id, when USB3.0 bulk streams are being used
51 no_interrupt
53 If true, hints that no completion irq is needed. Helpful sometimes
54 with deep request queues that are handled directly by DMA
55 controllers.
56 zero
58 If true, when writing data, makes the last packet be “short” by
59 adding a zero length packet as needed;
60 short_not_ok
62 When reading data, makes short packets be treated as errors (queue
63 stops advancing till cleanup).
64 complete
66 Function called when request completes, so this request and its
67 buffer may be re-used. The function will always be called with
68 interrupts disabled, and it must not sleep. Reads terminate with a
69 short packet, or when the buffer fills, whichever comes first. When
70 writes terminate, some data bytes will usually still be in flight
71 (often in a hardware fifo). Errors (for reads or writes) stop the
72 queue from advancing until the completion function returns, so that
73 any transfers invalidated by the error may first be dequeued.
74 context
76 For use by the completion callback
77 list
79 For use by the gadget driver.
80 status
82 Reports completion code, zero or a negative errno. Normally, faults
83 block the transfer queue from advancing until the completion
84 callback returns. Code “-ESHUTDOWN” indicates completion caused by
85 device disconnect, or when the driver disabled the endpoint.
86 actual
88 Reports bytes transferred to/from the buffer. For reads (OUT
89 transfers) this may be less than the requested length. If the
90 short_not_ok flag is set, short reads are treated as errors even
91 when status otherwise indicates successful completion. Note that
92 for writes (IN transfers) some data bytes may still reside in a
93 device-side FIFO when the request is reported as complete.
94
96 These are allocated/freed through the endpoint they're used with. The
97 hardware's driver can add extra per-request data to the memory it
98 returns, which often avoids separate memory allocations (potential
99 failures), later when the request is queued.
100 Request flags affect request handling, such as whether a zero length
102 packet is written (the “zero” flag), whether a short read should be
103 treated as an error (blocking request queue advance, the “short_not_ok”
104 flag), or hinting that an interrupt is not required (the “no_interrupt”
105 flag, for use with deep request queues).
106 Bulk endpoints can use any size buffers, and can also be used for
108 interrupt transfers. interrupt-only endpoints can be much less
109 functional.
110
112 this is analogous to 'struct urb' on the host side, except that it's
113 thinner and promotes more pre-allocation.
114
116 David Brownell <dbrownell@users.sourceforge.net>
117 Author.
118
120Kernel Hackers Manual 3.10 June 2019 STRUCT USB_REQUEST(9)