usb_sg_init(9)

📦 version 7.3.1, in nixpkgs unstable

💫 usb_sg_init — the Kernel API Manual glow-up 💫

okay so bestie, welcome to usb_sg_init(9) from the Kernel API Manual — this is the function that initializes scatterlist-based bulk/interrupt I/O requests and honestly? it's kind of the moment. 🎀

✨ SYNOPSIS ✨

int usb_sg_init (struct usb_sg_request *io , struct usb_device *dev ,
unsigned pipe , unsigned period , struct scatterlist *sg , int nents ,
size_t length , gfp_t mem_flags );

like yes that's a lot of parameters, breathe, we're gonna go through every single one 💅

🦋 ARGUMENTS 🦋

  • io — the request block that's being initialized. real talk: until usb_sg_wait returns, you gotta treat this as a pointer to an opaque block of memory. no peeking, no cap 👀
  • dev — the usb device that's gonna send or receive the data. the main character of this whole operation, fr
  • pipe — the endpoint "pipe" used to transfer the data. the lil delivery chute 💌
  • period — the polling rate for interrupt endpoints, in frames or (for high speed endpoints) microframes; it's ignored for bulk, so don't stress about it if you're doing bulk i/o, bestie 🫶
  • sg — the scatterlist entries. this is the whole point of the function honestly
  • nents — how many entries are in that scatterlist. gotta know the count, iykyk
  • length — how many bytes to send from the scatterlist, or zero to send every byte identified in the list. zero = send it all, iconic behavior 🌈
  • mem_flags — the SLAB_* flags affecting memory allocations in this call. memory allocation vibes set here ✨

💖 DESCRIPTION 💖

so this initializes a scatter/gather request, allocating resources such as I/O mappings and urb memory (except maybe memory used by USB controller drivers). it's giving "getting everything ready for you before the real work starts" 💅

the request must be issued using usb_sg_wait, which waits for the I/O to complete (or to be canceled) and then cleans up all resources allocated by usb_sg_init. so like, usb_sg_wait is the responsible friend who cleans up after the party 🧹

the request may be canceled with usb_sg_cancel, either before or after usb_sg_wait is called. flexible queen behavior honestly 👑

⭐ RETURN ⭐

zero for success, else a negative errno value. simple as that, no notes 😌

🔥 SEE ALSO 🔥

kernel file ./drivers/usb/core/message.c plus the whole friend group:

like, the whole squad showed up for this one 🫂💜

bestie reminder: usb_sg_init does not clean up after itself — that's on usb_sg_wait. don't leave your resources hanging, that's not the vibe 🙈

and that's the tea! 🍓 this page lives in ./drivers/usb/core, dated October 2026, and we out here shipping usb_sg_init(9) into your brain. slay, go write some scatter/gather i/o, you're doing amazing ✨🎀💖

📦 where this page comes from