1USB_EP_QUEUE(9)             Kernel Mode Gadget API             USB_EP_QUEUE(9)
2
3
4

NAME

6       usb_ep_queue - queues (submits) an I/O request to an endpoint.
7

SYNOPSIS

9       int usb_ep_queue(struct usb_ep * ep, struct usb_request * req,
10                        gfp_t gfp_flags);
11

ARGUMENTS

13       ep
14           the endpoint associated with the request
15
16       req
17           the request being submitted
18
19       gfp_flags
20           GFP_* flags to use in case the lower level driver couldn't
21           pre-allocate all necessary memory with the request.
22

DESCRIPTION

24       This tells the device controller to perform the specified request
25       through that endpoint (reading or writing a buffer). When the request
26       completes, including being canceled by usb_ep_dequeue, the request's
27       completion routine is called to return the request to the driver. Any
28       endpoint (except control endpoints like ep0) may have more than one
29       transfer request queued; they complete in FIFO order. Once a gadget
30       driver submits a request, that request may not be examined or modified
31       until it is given back to that driver through the completion callback.
32
33       Each request is turned into one or more packets. The controller driver
34       never merges adjacent requests into the same packet. OUT transfers will
35       sometimes use data that's already buffered in the hardware. Drivers can
36       rely on the fact that the first byte of the request's buffer always
37       corresponds to the first byte of some USB packet, for both IN and OUT
38       transfers.
39
40       Bulk endpoints can queue any amount of data; the transfer is packetized
41       automatically. The last packet will be short if the request doesn't
42       fill it out completely. Zero length packets (ZLPs) should be avoided in
43       portable protocols since not all usb hardware can successfully handle
44       zero length packets. (ZLPs may be explicitly written, and may be
45       implicitly written if the request 'zero' flag is set.) Bulk endpoints
46       may also be used for interrupt transfers; but the reverse is not true,
47       and some endpoints won't support every interrupt transfer. (Such as 768
48       byte packets.)
49
50       Interrupt-only endpoints are less functional than bulk endpoints, for
51       example by not supporting queueing or not handling buffers that are
52       larger than the endpoint's maxpacket size. They may also treat data
53       toggle differently.
54
55       Control endpoints ... after getting a setup callback, the driver queues
56       one response (even if it would be zero length). That enables the status
57       ack, after transferring data as specified in the response. Setup
58       functions may return negative error codes to generate protocol stalls.
59       (Note that some USB device controllers disallow protocol stall
60       responses in some cases.) When control responses are deferred (the
61       response is written after the setup callback returns), then
62       usb_ep_set_halt may be used on ep0 to trigger protocol stalls.
63       Depending on the controller, it may not be possible to trigger a
64       status-stage protocol stall when the data stage is over, that is, from
65       within the response's completion routine.
66
67       For periodic endpoints, like interrupt or isochronous ones, the usb
68       host arranges to poll once per interval, and the gadget driver usually
69       will have queued some data to transfer at that time.
70
71       Returns zero, or a negative error code. Endpoints that are not enabled
72       report errors; errors will also be reported when the usb peripheral is
73       disconnected.
74

AUTHOR

76       David Brownell <dbrownell@users.sourceforge.net>
77           Author.
78

80Kernel Hackers Manual 3.10         June 2019                   USB_EP_QUEUE(9)
Impressum