usb_sg_wait(9)

💅 usb_sg_wait(9) — like, the kernel API manual, but make it make sense

okay bestie, welcome to usb_sg_wait(9) from the Kernel API Manual ✨ this is the one that does a whole scatter/gather request and waits for it, synchronously, no cap.

---

🎀 NAME 🎀

usb_sg_wait — synchronously execute scatter/gather request. yes, synchronously. like, it will wait. that's the whole vibe.

---

✨ SYNOPSIS ✨

void usb_sg_wait (struct usb_sg_request *io );

---

🫶 ARGUMENTS 🫶

• io — the request block handle, exactly as initialized with usb_sg_init. some of its fields become accessible when this call returns 👀 (yes, after, not during — patience, queen).

---

🌸 CONTEXT 🌸

task context, might sleep. 😴 lowkey important: it might sleep, so act accordingly.

---

💖 DESCRIPTION 💖

okay so this function blocks until the specified I/O operation completes. periodt. it leverages the grouping of the related I/O requests to get good transfer rates, by queueing the requests. and at higher speeds, that queuing can significantly improve USB throughput 🔥 like, genuinely iconic behaviour.

there are three kinds of completion for this function:

1. success — where io->status is zero. the number of io->bytes transferred is as requested. slay. 💅
2. error — where io->status is a negative errno value. the number of io->bytes transferred before the error is usually less than requested, and can be nonzero. 😭 yeah. partial. it happens.
3. cancellation — a type of error with status -ECONNRESET that is initiated by usb_sg_cancel. not you cancelling your own request 💀

when this function returns, all memory allocated through usb_sg_init or this call will have been freed. the request block parameter may still be passed to usb_sg_cancel, or it may be freed. it could also be reinitialized and then reused. so many options, main character energy fr fr ✨

🌈 Data Transfer Rates 🌈

bulk transfers are valid for full or high speed endpoints. the best full speed data rate is 19 packets of 64 bytes each per frame, or 1216 bytes per millisecond. the best high speed data rate is 13 packets of 512 bytes each per microframe, or 52 KBytes per millisecond. numbers!! look at them!! 👑

the reason to use interrupt transfers through this API would most likely be to reserve high speed bandwidth, where up to 24 KBytes per millisecond could be transferred. that capability is less useful for low or full speed interrupt endpoints, which allow at most one packet per millisecond, of at most 8 or 64 bytes (respectively). like, cute, but tiny. 🍓

it is not necessary to call this function to reserve bandwidth for devices under an xHCI host controller, because the bandwidth is reserved when the configuration or interface alt setting is selected. so don't do extra work for no reason, bestie 🙈

---

🦋 SEE ALSO 🦋

kernel file ./drivers/usb/core/message.c — and honestly the whole friend group:

• usb_control_msg(9)
• usb_control_msg_send(9)
• usb_control_msg_recv(9)
• usb_interrupt_msg(9)
• usb_bulk_msg(9)
• usb_bulk_msg_killable(9)
• usb_sg_init(9)
• usb_sg_cancel(9)
• usb_get_descriptor(9)
• usb_get_string(9)
• usb_string(9)
• usb_cache_string(9)
• usb_get_status(9)
• usb_clear_halt(9)
• usb_disable_endpoint(9)
• usb_reset_endpoint(9)
• usb_disable_interface(9)
• usb_disable_device(9)
• usb_enable_endpoint(9)
• usb_enable_interface(9)
• usb_set_interface(9)
• usb_reset_configuration(9)
• usb_set_wireless_status(9)
• usb_driver_set_configuration(9)
• cdc_parse_cdc_header(9)

---

and that's the page!! 🎀 source/version: ./drivers/usb/core, dated October 2026 — mwah, sending you the biggest kiss, go forth and scatter/gather responsibly 💜🧚⭐