USBD_TRANSFER(9)

📦 in nixpkgs unstable

💅 USBD_TRANSFER(9) — ok so this is a kernel developer's manual page, and yes we're doing this 🎀

bestie. sit down. we're talking about usbd_setup_xfer and usbd_transfer, from the Kernel Developer's Manual, section 9. this is the whole page, header line and all, and it's gonna be iconic, i promise 🫶

✨ NAME ✨

usbd_setup_xfer, usbd_transfer — submit USB data transfers 💾🔥

🌸 SYNOPSIS 🌸

#include <dev/usb/usb.h>
#include <dev/usb/usbdi.h>

void
usbd_setup_xfer(struct usbd_xfer *xfer, struct usbd_pipe *pipe,
    void *priv, void *buffer, uint32_t length, uint16_t flags,
    uint32_t timeout, usbd_callback callback);

usbd_status
usbd_transfer(struct usbd_xfer *xfer);

like, look at that signature. it's giving "i know exactly what i'm doing" 💅

🦋 DESCRIPTION 🦋

okay so these functions are the controller-independent way to actually do USB data transfers. controller independent means the USB stack handles the host-controller-specific mess so you don't have to, and honestly? slay. they make use of a pipe that you got from usbd_open_pipe(9) or usbd_open_pipe_intr(9) — you can't just vibe your way in here, you need a pipe first, iykyk.

🎀 usbd_setup_xfer() — the setup girlie

usbd_setup_xfer() initializes the structure pointed to by xfer, and that structure describes one individual transfer you're about to submit. it takes these arguments, and yes we're going through all of them, no skipping, that's not the vibe:

  • xfer — a pointer to an existing structure that describes a transfer. note the word existing, bestie, it's not creating one for you 🙈
  • pipe — a pointer to a pipe associated with the endpoint for this transfer.
  • priv — a pointer to a private cookie. the USB stack does not touch it, it's yours, and the whole point is you can reuse it inside the callback later. it's literally your little secret 🍓
  • buffer — a pointer to the data buffer.
  • length — the total length of the data to read or write. the whole amount. not part of it. 💜
  • flags — the characteristics of the transfer, and this is the main character of the argument list, so let's go:
    • USBD_NO_COPY — do not copy data between buffer and the DMA buffer. no copying. none. ✨
    • USBD_SYNCHRONOUS — makes usbd_transfer() sleep until the I/O transfer is complete, or the timeout expires. so it goes to sleep and it waits, and you're just gonna sit there with it, respectfully 😴
    • USBD_SHORT_XFER_OK — do not report short reads as errors, when the length of the data read is lower than length. like yeah it's short, but we're chill about it 🫶
    • USBD_FORCE_SHORT_XFER — submit a supplementary zero length packet at the end of the written data. some requests may need such packets in order to be properly terminated. it's the little period at the end of the sentence, fr fr 🌈
    • USBD_CATCH — used together with the USBD_SYNCHRONOUS flag, to pass the PCATCH flag to tsleep(9) so signals get checked before and after sleeping. it's a combo move, you don't use it alone 💅
  • timeout — the timeout of the transfer, in milliseconds. ⏳
  • callback — a routine that gets invoked upon completion of the transfer, whether it succeeded or not. success or flop, the callback is showing up to the function. that's commitment 💖

🔥 usbd_transfer() — the one that actually submits

usbd_transfer() submits the USB transfer described by xfer to the corresponding usb(4) host controller, so the I/O with devices actually happens. setup was the plan, this is the execution. main character energy, no cap 👑

🌟 CONTEXT 🌟

where can you call these? okay so, location check:

  • usbd_setup_xfer() can be called during autoconf, from process context, or from interrupt context. all three, she's flexible ✨
  • usbd_transfer() can be called during autoconf, from process context, or from interrupt context if USBD_SYNCHRONOUS has not been passed via flags. and that "if" is doing so much work, bestie, do not skip it. synchronous transfer from interrupt context is not the move 😭
fr fr, that conditional on usbd_transfer() is real. read it twice. the synchronous flag changes where you're allowed to call from, and the manual is being very clear about it 🚨

🌈 SEE ALSO 🌈

go read them. all of them. knowledge is hot 💜

aaaand that's the page 🎀 it came from Debian and it's dated May 4, 2015 — so, like, a 2015 vintage manual page, which honestly still ate. go submit your transfers, bestie, and remember: setup first, then transfer, and check your flags before you call anything from interrupt context 💅✨🦋

📦 where this page comes from