1STRUCT USB_REQUEST(9)       Kernel Mode Gadget API       STRUCT USB_REQUEST(9)
2
3
4

NAME

6       struct_usb_request - describes one i/o request
7

SYNOPSIS

9       struct usb_request {
10         void * buf;
11         unsigned length;
12         dma_addr_t dma;
13         unsigned no_interrupt:1;
14         unsigned zero:1;
15         unsigned short_not_ok:1;
16         void (* complete) (struct usb_ep *ep,struct usb_request *req);
17         void * context;
18         struct list_head list;
19         int status;
20         unsigned actual;
21       };
22

MEMBERS

24       buf
25           Buffer used for data. Always provide this; some controllers only
26           use PIO, or don´t use DMA for some endpoints.
27
28       length
29           Length of that data
30
31       dma
32           DMA address corresponding to ´buf´. If you don´t set this field,
33           and the usb controller needs one, it is responsible for mapping and
34           unmapping the buffer.
35
36       no_interrupt
37           If true, hints that no completion irq is needed. Helpful sometimes
38           with deep request queues that are handled directly by DMA
39           controllers.
40
41       zero
42           If true, when writing data, makes the last packet be “short” by
43           adding a zero length packet as needed;
44
45       short_not_ok
46           When reading data, makes short packets be treated as errors (queue
47           stops advancing till cleanup).
48
49       complete
50           Function called when request completes, so this request and its
51           buffer may be re-used. The function will always be called with
52           interrupts disabled, and it must not sleep. Reads terminate with a
53           short packet, or when the buffer fills, whichever comes first. When
54           writes terminate, some data bytes will usually still be in flight
55           (often in a hardware fifo). Errors (for reads or writes) stop the
56           queue from advancing until the completion function returns, so that
57           any transfers invalidated by the error may first be dequeued.
58
59       context
60           For use by the completion callback
61
62       list
63           For use by the gadget driver.
64
65       status
66           Reports completion code, zero or a negative errno. Normally, faults
67           block the transfer queue from advancing until the completion
68           callback returns. Code “-ESHUTDOWN” indicates completion caused by
69           device disconnect, or when the driver disabled the endpoint.
70
71       actual
72           Reports bytes transferred to/from the buffer. For reads (OUT
73           transfers) this may be less than the requested length. If the
74           short_not_ok flag is set, short reads are treated as errors even
75           when status otherwise indicates successful completion. Note that
76           for writes (IN transfers) some data bytes may still reside in a
77           device-side FIFO when the request is reported as complete.
78

DESCRIPTION

80       These are allocated/freed through the endpoint they´re used with. The
81       hardware´s driver can add extra per-request data to the memory it
82       returns, which often avoids separate memory allocations (potential
83       failures), later when the request is queued.
84
85       Request flags affect request handling, such as whether a zero length
86       packet is written (the “zero” flag), whether a short read should be
87       treated as an error (blocking request queue advance, the “short_not_ok”
88       flag), or hinting that an interrupt is not required (the “no_interrupt”
89       flag, for use with deep request queues).
90
91       Bulk endpoints can use any size buffers, and can also be used for
92       interrupt transfers. interrupt-only endpoints can be much less
93       functional.
94

NOTE

96       this is analagous to ´struct urb´ on the host side, except that it´s
97       thinner and promotes more pre-allocation.
98

AUTHOR

100       David Brownell <dbrownell@users.sourceforge.net>
101           Author.
102
104Kernel Hackers Manual 2.6.         June 2019             STRUCT USB_REQUEST(9)
Impressum