USBDI(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 USBDI(9) — Universal Serial Bus driver programming interface 💅

okay so this is USBDI(9) from the Kernel Developer's Manual, and it's the whole USB driver programming interface. Hydrate first, bestie 🫶 because this page is long and it's giving main character energy. ✨

🌸 NAME 🌸

The full squad on this page is:

usb_fifo_alloc_buffer
usb_fifo_attach
usb_fifo_detach
usb_fifo_free_buffer
usb_fifo_get_data
usb_fifo_get_data_buffer
usb_fifo_get_data_error
usb_fifo_get_data_linear
usb_fifo_put_bytes_max
usb_fifo_put_data
usb_fifo_put_data_buffer
usb_fifo_put_data_error
usb_fifo_put_data_linear
usb_fifo_reset
usb_fifo_softc
usb_fifo_wakeup
usbd_do_request
usbd_do_request_flags
usbd_errstr
usbd_lookup_id_by_info
usbd_lookup_id_by_uaa
usbd_transfer_clear_stall
usbd_transfer_drain
usbd_transfer_pending
usbd_transfer_poll
usbd_transfer_setup
usbd_transfer_start
usbd_transfer_stop
usbd_transfer_submit
usbd_transfer_unsetup
usbd_xfer_clr_flag
usbd_xfer_frame_data
usbd_xfer_frame_len
usbd_xfer_get_frame
usbd_xfer_get_priv
usbd_xfer_is_stalled
usbd_xfer_max_framelen
usbd_xfer_max_frames
usbd_xfer_max_len
usbd_xfer_set_flag
usbd_xfer_set_frame_data
usbd_xfer_set_frame_len
usbd_xfer_set_frame_offset
usbd_xfer_set_frames
usbd_xfer_set_interval
usbd_xfer_set_priv
usbd_xfer_set_stall
usbd_xfer_set_timeout
usbd_xfer_softc
usbd_xfer_state
usbd_xfer_status

Together they're the Universal Serial Bus driver programming interface. 💅

✨ SYNOPSIS ✨

Headers first, no cap:

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

And the synopsis calls are literally these:

usb_error_t
usbd_transfer_setup(struct usb_device *udev, const uint8_t *ifaces,
    struct usb_xfer **pxfer, const struct usb_config *setup_start,
    uint16_t n_setup, void *priv_sc, struct mtx *priv_mtx);

void
usbd_transfer_unsetup(struct usb_xfer **pxfer, uint16_t n_setup);

void
usbd_transfer_start(struct usb_xfer *xfer);

void
usbd_transfer_stop(struct usb_xfer *xfer);

void
usbd_transfer_drain(struct usb_xfer *xfer);

🦋 DESCRIPTION 🦋

The Universal Serial Bus (USB) driver programming interface provides USB peripheral drivers with a host controller independent API for controlling and communicating with USB peripherals. The usb module supports both USB Host and USB Device side mode. Periodt. 🌈

🔥 USB TRANSFER MANAGEMENT FUNCTIONS 🔥

The USB standard defines four types of USB transfers: Control transfers, Bulk transfers, Interrupt transfers and Isochronous transfers. All the transfer types are managed using the following five functions:

usbd_transfer_setup() — This function will allocate memory for and initialise an array of USB transfers and all required DMA memory. It can sleep or block waiting for resources to become available. udev is a pointer to struct usb_device. ifaces is an array of interface index numbers to use. See if_index. pxfer is a pointer to an array of USB transfer pointers that are initialized to NULL, and then pointed to allocated USB transfers. setup_start is a pointer to an array of USB config structures. n_setup is a number telling the USB system how many USB transfers should be setup. priv_sc is the private softc pointer, which will be used to initialize xfer->priv_sc. priv_mtx is the private mutex protecting the transfer structure and the softc. This pointer is used to initialize xfer->priv_mtx. This function returns zero upon success. A non-zero return value indicates failure.
usbd_transfer_unsetup() — This function will release the given USB transfers and all allocated resources associated with these USB transfers. pxfer is a pointer to an array of USB transfer pointers, that may be NULL, that should be freed by the USB system. n_setup is a number telling the USB system how many USB transfers should be unsetup. This function can sleep waiting for USB transfers to complete. This function is NULL safe with regard to the USB transfer structure pointer. It is not allowed to call this function from the USB transfer callback. 🚨
usbd_transfer_start() — This function will start the USB transfer pointed to by xfer, if not already started. This function is always non-blocking and must be called with the so-called private USB mutex locked. This function is NULL safe with regard to the USB transfer structure pointer.
usbd_transfer_stop() — This function will stop the USB transfer pointed to by xfer, if not already stopped. This function is always non-blocking and must be called with the so-called private USB mutex locked. This function can return before the USB callback has been called. This function is NULL safe with regard to the USB transfer structure pointer. If the transfer was in progress, the callback will be called with USB_ST_ERROR and error = USB_ERR_CANCELLED. 💀
usbd_transfer_drain() — This function will stop an USB transfer, if not already stopped and wait for any additional USB hardware operations to complete. Buffers that are loaded into DMA using usbd_xfer_set_frame_data() can safely be freed after this function has returned. This function can block the caller and will not return before the USB callback has been called. This function is NULL safe with regard to the USB transfer structure pointer.

🎀 USB TRANSFER CALLBACK 🎀

The USB callback has three states: USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the initial state. After the callback has been called with this state it will always be called back at a later stage in one of the other two states. The USB callback should not restart the USB transfer in case the error cause is USB_ERR_CANCELLED. The USB callback is protected from recursion. That means one can start and stop whatever transfer from the callback of another transfer one desires. Also the transfer that is currently called back. Recursion is handled like this: when the callback that wants to recurse returns it is called one more time.

usbd_transfer_submit() — This function should only be called from within the USB callback and is used to start the USB hardware. An USB transfer can have multiple frames consisting of one or more USB packets making up an I/O vector for all USB transfer types.

Here's the default callback vibe, bestie:

void
usb_default_callback(struct usb_xfer *xfer, usb_error_t error)
{
        int actlen;

        usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);

        switch (USB_GET_STATE(xfer)) {
        case USB_ST_SETUP:
                /*
                 * Setup xfer frame lengths/count and data
                 */
                usbd_transfer_submit(xfer);
                break;

        case USB_ST_TRANSFERRED:
                /*
                 * Read usb frame data, if any.
                 * "actlen" has the total length for all frames
                 * transferred.
                 */
                break;

        default: /* Error */
                /*
                 * Print error message and clear stall
                 * for example.
                 */
                break;
        }
        /*
         * Here it is safe to do something without the private
         * USB mutex locked.
         */
        return;
}

🌈 USB CONTROL TRANSFERS 🌈

An USB control transfer has three parts. First the SETUP packet, then DATA packet(s) and then a STATUS packet. The SETUP packet is always pointed to by frame 0 and the length is set by usbd_xfer_frame_len() also if there should not be sent any SETUP packet! If an USB control transfer has no DATA stage, then the number of frames should be set to 1. Else the default number of frames is 2.

Here are the exact little recipes, bestie:

Example1: SETUP + STATUS
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_transfer_submit(xfer);

Example2: SETUP + DATA + STATUS
 usbd_xfer_set_frames(xfer, 2);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_xfer_set_frame_len(xfer, 1, 1);
 usbd_transfer_submit(xfer);

Example3: SETUP + DATA + STATUS - split
1st callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_transfer_submit(xfer);

2nd callback:
 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
 usbd_xfer_set_frames(xfer, 2);
 usbd_xfer_set_frame_len(xfer, 0, 0);
 usbd_xfer_set_frame_len(xfer, 1, 1);
 usbd_transfer_submit(xfer);

Example4: SETUP + STATUS - split
1st callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 8);
 usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS);
 usbd_transfer_submit(xfer);

2nd callback:
 usbd_xfer_set_frames(xfer, 1);
 usbd_xfer_set_frame_len(xfer, 0, 0);
 usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS);
 usbd_transfer_submit(xfer);

🎀 USB TRANSFER CONFIG 🎀

okay bestie, so to make endpoint hunting way less chaotic, the usb module defines a USB config structure where you can specify the characteristics of the endpoint you want. it’s giving “matchmaker but for pipes” 💅

             struct usb_config {
                     bufsize,
                     callback
                     direction,
                     endpoint,
                     frames,
                     index flags,
                     interval,
                     timeout,
                     type,
             };

type — selects the USB pipe type. valid values are UE_INTERRUPT, UE_CONTROL, UE_BULK, UE_ISOCHRONOUS. the special value UE_BULK_INTR will select BULK and INTERRUPT pipes. this field is mandatory.
endpoint — selects the USB endpoint number. a value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching endpoint. this field is mandatory.
direction — selects the USB endpoint direction. a value of "UE_DIR_ANY" will select the first matching endpoint. else valid values are "UE_DIR_IN" and "UE_DIR_OUT". "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR’ed by "UE_DIR_SID", which means the direction will be swapped in case of USB_MODE_DEVICE. note that "UE_DIR_IN" refers to the data transfer direction of the "IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of the "OUT" tokens. this field is mandatory.
interval — selects the interrupt interval. the value is given in milliseconds and is independent of device speed. depending on the endpoint type, this field has different meaning:
- UE_INTERRUPT — "0" uses the default interrupt interval based on the endpoint descriptor. "Else" uses the given value for polling rate.
- UE_ISOCHRONOUS — "0" uses default. "Else" the value is ignored.
- UE_BULK — (no extra note here, it just vibes).
- UE_CONTROL — "0" means no transfer pre-delay. "Else" means a delay as given by this field in milliseconds is inserted before the hardware is started when usbd_transfer_submit() is called.

NOTE: the transfer timeout, if any, is started after the pre-delay has elapsed! ⏳

timeout — if non-zero, will set the transfer timeout in milliseconds. if the "timeout" field is zero and the transfer type is ISOCHRONOUS, a timeout of 250ms will be used.
frames — sets the maximum number of frames. if zero is specified it will yield the following results:
- UE_BULK — xfer->nframes = 1;
- UE_INTERRUPT — xfer->nframes = 1;
- UE_CONTROL — xfer->nframes = 2;
- UE_ISOCHRONOUS — not allowed. will cause an error. 💀
ep_index — allows you to give a number, in case more endpoints match the description, that selects which matching "ep_index" should be used.
if_index — allows you to select which of the interface numbers in the "ifaces" array parameter passed to "usbd_transfer_setup" that should be used when setting up the given USB transfer.
flags — has type struct usb_xfer_flags and allows one to set initial flags on a USB transfer. valid flags are:
- force_short_xfer — this flag forces the last transmitted USB packet to be short. a short packet has a length of less than xfer->max_packet_size, which derives from wMaxPacketSize. this flag can be changed during operation.
- short_xfer_ok — this flag allows the received transfer length, xfer->actlen, to be less than xfer->sumlen upon completion of a transfer. this flag can be changed during operation.
- short_frames_ok — this flag allows the reception of multiple short USB frames. this flag only has effect for BULK and INTERRUPT endpoints and if the number of frames received is greater than 1. this flag can be changed during operation.
- pipe_bof — this flag causes a failing USB transfer to remain first in the PIPE queue except in the case of xfer->error equal to USB_ERR_CANCELLED. no other USB transfers in the affected PIPE queue will be started until either:
  1. the failing USB transfer is stopped using usbd_transfer_stop().
  2. the failing USB transfer performs a successful transfer.

the purpose of this flag is to avoid races when multiple transfers are queued for execution on a USB endpoint, and the first executing transfer fails leading to the need for clearing of stall for example. in this case this flag is used to prevent the following USB transfers from being executed at the same time the clear-stall command is executed on the USB control endpoint. this flag can be changed during operation.

"BOF" is short for "Block On Failure".

NOTE: this flag should be set on all BULK and INTERRUPT USB transfers which use an endpoint that can be shared between userland and kernel. 🔥

proxy_buffer — setting this flag will cause that the total buffer size will be rounded up to the nearest atomic hardware transfer size. the maximum data length of any USB transfer is always stored in the xfer->max_data_length. for control transfers the USB kernel will allocate additional space for the 8-bytes of SETUP header. these 8-bytes are not counted by the xfer->max_data_length variable. this flag cannot be changed during operation.
ext_buffer — setting this flag will cause that no data buffer will be allocated. instead the USB client must supply a data buffer. this flag cannot be changed during operation.
manual_status — setting this flag prevents a USB STATUS stage to be appended to the end of the USB control transfer. if no control data is transferred this flag must be cleared. else an error will be returned to the USB callback. this flag is mostly useful for the USB device side. this flag can be changed during operation.
no_pipe_ok — setting this flag causes the USB_ERR_NO_PIPE error to be ignored. this flag cannot be changed during operation.
stall_pipe —
- Device Side Mode — setting this flag will cause STALL pids to be sent to the endpoint belonging to this transfer before the transfer is started. the transfer is started at the moment the host issues a clear-stall command on the STALL’ed endpoint. this flag can be changed during operation.
- Host Side Mode — setting this flag will cause a clear-stall control request to be executed on the endpoint before the USB transfer is started.

if this flag is changed outside the USB callback function you have to use the usbd_xfer_set_stall() and usbd_transfer_clear_stall() functions! this flag is automatically cleared after that the stall or clear stall has been executed. 🫶

pre_scale_frames — if this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames. during transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero. this option only has effect for ISOCHRONOUS transfers.

bufsize — sets the total buffer size in bytes. if this field is zero, wMaxPacketSize will be used, multiplied by the frames field if the transfer type is ISOCHRONOUS. this is useful for setting up interrupt pipes. this field is mandatory.

NOTE: for control transfers bufsize includes the length of the request structure. 🍓

callback — pointer sets the USB callback. this field is mandatory.

🐧 USB LINUX COMPAT LAYER 🐧

the usb module supports the Linux USB API. periodt. ✨

👀 SEE ALSO 👀

libusb(3), usb(4), usbconfig(8) — the little squad of related pages, go read them bestie 💖

📏 STANDARDS 📏

the usb module complies with the USB 2.0 standard. iconic behavior, no cap. 👑

🌸 HISTORY 🌸

the usb module has been inspired by the NetBSD USB stack initially written by Lennart Augustsson. the usb module was written by Hans Petter Selasky <hselasky@FreeBSD.org>. 🧚

💅 that’s the whole page, bestie! it’s from Debian, dated November 14, 2016, and the page is USBDI(9). byeee 🫶

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms