usb_ep_queue(9)

📦 version 7.3.1, in nixpkgs unstable

💅 usb_ep_queue(9) — the usb_ep_queue page from the Kernel API Manual, bestie edition

okay so picture this: you're a gadget driver, you've got a request, and you need the device controller to actually do the thing. That's this function. It's giving "middle management but the good kind" 🫶

✨ NAME ✨

usb_ep_queue — queues (submits) an I/O request to an endpoint. that's it, that's the whole job 💖

🌸 SYNOPSIS 🌸

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

🎀 ARGUMENTS 🎀

  • ep — the endpoint that's associated with the request. the one doing the actual work 💅
  • req — the request you're submitting. the star of the show ✨
  • gfp_flags — the GFP_* flags to use in case the lower level driver couldn't pre-allocate all the necessary memory with the request. yep, that's a lot of memory words, but it matters, trust 🔥

🦋 DESCRIPTION 🦋

So what does this actually do? It tells the device controller to perform the specified request through that endpoint — reading or writing a buffer, depending. 📖✍️

When the request completes — and yes, that includes being canceled by usb_ep_dequeue — the request's completion routine gets called to return the request to the driver. full circle moment 💫

Any endpoint (except control endpoints like ep0, those are special, more on them in a sec) may have more than one transfer request queued up. And they complete in FIFO order — first in, first out, line discipline, no cutting 🙅‍♀️

⚠️ Once a gadget driver submits a request, that request may not be examined or modified until it is given back to that driver through the completion callback. hands off, bestie. literally do not touch it 💀

Each request gets turned into one or more packets. The controller driver never merges adjacent requests into the same packet — no cap, never. And OUT transfers will sometimes use data that's already buffered in the hardware. Drivers can rely on the fact that the first byte of the request's buffer always corresponds to the first byte of some USB packet, for both IN and OUT transfers. so cute that it lines up like that 🥹

Bulk endpoints can queue any amount of data — the transfer is packetized automatically. Slay. The last packet will be short if the request doesn't fill it out completely. Zero length packets (ZLPs) should be avoided in portable protocols, since not all usb hardware can successfully handle zero length packets. (ZLPs may be explicitly written, and may be implicitly written if the request zero flag is set.) 👀 Bulk endpoints may also be used for interrupt transfers — but the reverse is not true, and some endpoints won't support every interrupt transfer. (Such as 768 byte packets.) so like, try it, but manage your expectations 💅

Interrupt-only endpoints are less functional than bulk endpoints — for example by not supporting queueing or not handling buffers that are larger than the endpoint's maxpacket size. They may also treat data toggle differently. ngl they're kind of the low-maintenance cousin of the endpoint family 🙈

Control endpoints … okay this one's a whole saga. After getting a setup callback, the driver queues one response (even if it would be zero length). That enables the status ack, after transferring data as specified in the response. Setup functions may return negative error codes to generate protocol stalls. (Note that some USB device controllers disallow protocol stall responses in some cases.) When control responses are deferred — meaning the response is written after the setup callback returns — then usb_ep_set_halt may be used on ep0 to trigger protocol stalls. Depending on the controller, it may not be possible to trigger a status-stage protocol stall when the data stage is over, that is, from within the response's completion routine. it's giving "it depends on the hardware, bestie" 😭

For periodic endpoints, like interrupt or isochronous ones, the usb host arranges to poll once per interval, and the gadget driver usually will have queued some data to transfer at that time. scheduling! consistency! we love her ⏰👑

🚨 Note that req's ->complete callback must never be called from within usb_ep_queue, as that can create deadlock situations. this is the number one thing people get wrong. don't be that person. periodt 💀

This routine may be called in interrupt context. yes, really. icon behaviour ✨

🌈 RETURN VALUE (it's in the description, but I'm giving it its own moment) 🌈

Returns zero, or a negative error code. Endpoints that are not enabled report errors; errors will also be reported when the usb peripheral is disconnected. rude but fair 🫠

If and only if req is successfully queued (the return value is zero), req->complete will be called exactly once, when the Gadget core and UDC are finished with the request. When the completion function is called, control of the request is returned to the device driver which submitted it. The completion handler may then immediately free or reuse req. exactly once. not zero times, not twice. exactly once. write that down 📝💖

⭐ SEE ALSO ⭐

Kernel file ./drivers/usb/gadget/udc/core.c and struct usb_udc(9) — plus the extended universe:

that's the whole page, bestie 💜 this one lives in ./drivers/usb/gadget/udc, it's part of the Kernel API Manual, and this edition is dated October 2026. go queue some requests. slay. 💅✨

📦 where this page comes from