STRUCT USB_DEVICE(9)

📦 version 7.3.1, in nixpkgs unstable

✨ struct usb_device ✨

okay so real talk, this is from the Kernel API Manual (yes, the struct usb_device(9) page, we're doing this 💅) and it's literally the kernel's whole personality wrapped around a USB device.

🌸 NAME 🌸

struct usb_device — the kernel's representation of a USB device. it's giving "everything you ever wanted to know about a plugged-in thing" 💖

🎀 SYNOPSIS 🎀

bestie. look at this. it's a lot, and every single field is important, so here's the whole thing, character for character, no cap:

struct usb_device {
    int devnum;
    char devpath[16];
    u32 route;
    enum usb_device_state   state;
    enum usb_device_speed   speed;
    unsigned int            rx_lanes;
    unsigned int            tx_lanes;
    enum usb_ssp_rate       ssp_rate;
    struct usb_tt   *tt;
    int ttport;
    unsigned int toggle[2];
    struct usb_device *parent;
    struct usb_bus *bus;
    struct usb_host_endpoint ep0;
    struct device dev;
    struct usb_device_descriptor descriptor;
    struct usb_host_bos *bos;
    struct usb_host_config *config;
    struct usb_host_config *actconfig;
    struct usb_host_endpoint *ep_in[16];
    struct usb_host_endpoint *ep_out[16];
    char **rawdescriptors;
    unsigned short bus_mA;
    u8 portnum;
    u8 level;
    u8 devaddr;
    unsigned can_submit:1;
    unsigned persist_enabled:1;
    unsigned reset_in_progress:1;
    unsigned have_langid:1;
    unsigned authorized:1;
    unsigned authenticated:1;
    unsigned lpm_capable:1;
    unsigned lpm_devinit_allow:1;
    unsigned usb2_hw_lpm_capable:1;
    unsigned usb2_hw_lpm_besl_capable:1;
    unsigned usb2_hw_lpm_enabled:1;
    unsigned usb2_hw_lpm_allowed:1;
    unsigned usb3_lpm_u1_enabled:1;
    unsigned usb3_lpm_u2_enabled:1;
    int string_langid;
    char *product;
    char *manufacturer;
    char *serial;
    struct list_head filelist;
    int maxchild;
    u32 quirks;
    atomic_t urbnum;
    unsigned long active_duration;
    unsigned long connect_time;
    unsigned do_remote_wakeup:1;
    unsigned reset_resume:1;
    unsigned port_is_suspended:1;
    unsigned offload_pm_locked:1;
    int offload_usage;
    spinlock_t offload_lock;
    enum usb_link_tunnel_mode tunnel_mode;
    struct device_link *usb4_link;
    int slot_id;
    struct usb2_lpm_parameters l1_params;
    struct usb3_lpm_parameters u1_params;
    struct usb3_lpm_parameters u2_params;
    unsigned lpm_disable_count;
    u16 hub_delay;
    unsigned use_generic_driver:1;
 };

🦋 Members 🦋

okay okay, field-by-field, buckle up, this is the main character section 👑

  • devnum — device number; address on a USB bus. their little street address on the bus fr fr 🏠
  • devpath — device ID string for use in messages (e.g., /port/...)
  • route — tree topology hex string for use with xHCI
  • state — device state: configured, not attached, etc.
  • speed — device speed: high/full/low (or error)
  • rx_lanes — number of rx lanes in use, USB 3.2 adds dual-lane support
  • tx_lanes — number of tx lanes in use, USB 3.2 adds dual-lane support
  • ssp_rate — SuperSpeed Plus phy signaling rate and lane count
  • tt — Transaction Translator info; used with low/full speed dev, highspeed hub
  • ttport — device port on that tt hub
  • toggle — one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
  • parent — our hub, unless we're the root. everybody's got a parent except the root, iconic 🌳
  • bus — bus we're part of
  • ep0 — endpoint 0 data (default control pipe)
  • dev — generic device interface
  • descriptor — USB device descriptor
  • bos — USB device BOS descriptor set
  • config — all of the device's configs
  • actconfig — the active configuration
  • ep_in — array of IN endpoints
  • ep_out — array of OUT endpoints
  • rawdescriptors — raw descriptors for each config
  • bus_mA — Current available from the bus
  • portnum — parent port number (origin 1)
  • level — number of USB hub ancestors
  • devaddr — device address, XHCI: assigned by HW, others: same as devnum
  • can_submit — URBs may be submitted
  • persist_enabled — USB_PERSIST enabled for this device
  • reset_in_progress — the device is being reset
  • have_langid — whether string_langid is valid
  • authorized — policy has said we can use it; (user space) policy determines if we authorize this device to be used or not. By default, wired USB devices are authorized. WUSB devices are not, until we authorize them from user space. FIXME -- complete doc 🙈 (the kernel literally left a FIXME here, we respect the honesty)
  • authenticated — Crypto authentication passed
  • lpm_capable — device supports LPM
  • lpm_devinit_allow — Allow USB3 device initiated LPM, exit latency is in range
  • usb2_hw_lpm_capable — device can perform USB2 hardware LPM
  • usb2_hw_lpm_besl_capable — device can perform USB2 hardware BESL LPM
  • usb2_hw_lpm_enabled — USB2 hardware LPM is enabled
  • usb2_hw_lpm_allowed — Userspace allows USB 2.0 LPM to be enabled
  • usb3_lpm_u1_enabled — USB3 hardware U1 LPM enabled
  • usb3_lpm_u2_enabled — USB3 hardware U2 LPM enabled
  • string_langid — language ID for strings
  • product — iProduct string, if present (static)
  • manufacturer — iManufacturer string, if present (static)
  • serial — iSerialNumber string, if present (static)
  • filelist — usbfs files that are open to this device
  • maxchild — number of ports if hub
  • quirks — quirks of the whole device
  • urbnum — number of URBs submitted for the whole device
  • active_duration — total time device is not suspended
  • connect_time — time device was first connected
  • do_remote_wakeup — remote wakeup should be enabled
  • reset_resume — needs reset instead of resume
  • port_is_suspended — the upstream port is suspended (L2 or U3)
  • offload_pm_locked — prevents offload_usage changes during PM transitions.
  • offload_usage — number of offload activities happening on this usb device.
  • offload_lock — protects offload_usage and offload_pm_locked
  • tunnel_mode — Connection native or tunneled over USB4
  • usb4_link — device link to the USB4 host interface
  • slot_id — Slot ID assigned by xHCI
  • l1_params — best effor service latency for USB2 L1 LPM state, and L1 timeout. (yes "effor" — that's literally what the doc says, we don't fix typos in other people's homework 💀)
  • u1_params — exit latencies for USB3 U1 LPM state, and hub-initiated timeout.
  • u2_params — exit latencies for USB3 U2 LPM state, and hub-initiated timeout.
  • lpm_disable_count — Ref count used by usb_disable_lpm and usb_enable_lpm to keep track of the number of functions that require USB 3.0 Link Power Management to be disabled for this usb_device. This count should only be manipulated by those functions, with the bandwidth_mutex is held. 🔒 (and yeah, that sentence grammar is exactly the original's, we are merely the messenger)
  • hub_delay — cached value consisting of: parent->hub_delay + wHubDelay + tTPTransmissionDelay (40ns) Will be used as wValue for SetIsochDelay requests.
  • use_generic_driver — ask driver core to reprobe using the generic driver.

🌈 Notes 🌈

🚨 heads up bestie: Usbcore drivers should not set usbdev->state directly. Instead use usb_set_device_state. that's the whole rule, don't be messy, use the setter 💅

⭐ SEE ALSO ⭐

okay that's the whole page, you ate that 🫶 this little beauty lives in ./include/linux, dated October 2026, and it's part of the Kernel API Manual — go forth and read structs responsibly, mwah 💖🧚✨

📦 where this page comes from