USB(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 usb — Universal Serial Bus 💖

okay bestie, sit down, hydrate, because we're doing usb(4) — the Kernel Interfaces Manual entry that runs basically every cable you've ever plugged into anything. it's the whole USB subsystem. no cap. 🦋

✨ SYNOPSIS ✨

want this bad boy baked right into your kernel? drop this line into your kernel configuration file:

device usb

orrrr if you'd rather load it as a module at boot time (way less commitment, honestly), put this in loader.conf(5):

usb_load="YES"

slay. either way works. 💅

🎀 USERLAND PROGRAMMING 🎀

not me forgetting you can poke at USB stuff from userland too?? you can! through the libusb library. go read libusb(3) for the deets. 👑

🌸 DESCRIPTION 🌸

so FreeBSD hands you machine-independent bus support and drivers for USB devices, in both host and device side mode. iconic behavior fr fr.

the usb driver has three layers, and they're giving stacked bestie energy:

  • USB Controller (Bus)
  • USB Device
  • USB Driver

the controller attaches to a physical bus like pci(4). then the USB bus attaches to the controller, and the root hub attaches to the controller. any device you plug in attaches to the root hub — or to another hub hanging off the USB bus. it's a whole tree, iykyk. 🌳

also: the uhub device will always be present, because the root hub literally needs it. it's not optional. it's the main character. 🫶

🌈 INTRODUCTION TO USB 🌈

USB is the system where you connect external devices to a PC. the most common USB speeds are:

  • Low Speed (1.5MBit/sec)
  • Full Speed (12MBit/sec)
  • High Speed (480MBit/sec)

every USB has a USB controller that is the master of the bus. and the physical communication is simplex, which means the host controller only talks to one USB device at a time. one at a time!! it's monogamous like that. 💀

you can have up to 127 devices connected to a USB HUB tree, and the addresses are assigned dynamically by the host whenever each device gets attached to the bus. cute, right?

within each device there can be up to 16 endpoints. each endpoint is individually addressed and the addresses are static. every one of these endpoints communicates in one of four different modes:

  • control
  • isochronous
  • bulk
  • interrupt

a device always has at least one endpoint — it's address 0, it's a control endpoint, and it's the one used to give commands to the device and pull basic data out of it, like descriptors. every endpoint except the control endpoint is unidirectional. 🧭

the endpoints in a device are grouped into interfaces. an interface is a logical unit within a device — like, a compound device with both a keyboard and a trackball would present one interface for each. and an interface can sometimes be set into different modes called alternate settings, which affects how it operates. different alternate settings can have different endpoints inside them. the range!! 💅

a device may also operate in different configurations. depending on the configuration, the device may present different sets of endpoints and interfaces.

the bus enumeration of the USB bus proceeds in several steps:

  1. Any interface specific driver can attach to the device.
  2. If none is found, generic interface class drivers can attach.

and that's the whole glow-up sequence. ⭐

🧚 SYSCTL VARIABLES 🧚

the following variables are available as both sysctl(8) variables and loader(8) tunables:

  • hw.usb.debug — debug output level, where 0 is debugging disabled and larger values increase debug message verbosity. default is 0. 🍓

💜 SEE ALSO 💜

the USB specifications can be found at:

http://www.usb.org/developers/docs/

and here's the whole friend group, in order, no one left out:

libusb(3), aue(4), axe(4), axge(4), cue(4), ehci(4), kue(4), mos(4), ohci(4), pci(4), rue(4), ucom(4), udav(4), uhci(4), uhid(4), ukbd(4), ulpt(4), umass(4), ums(4), uplcom(4), urio(4), uvscom(4), xhci(4)

usbconfig(8), usbdi(9)

⭐ STANDARDS ⭐

the usb module complies with the USB 2.0 standard. periodt. 💯

🦋 HISTORY 🦋

the usb module has been inspired by the NetBSD USB stack, which was initially written by Lennart Augustsson. and the usb module itself was written by Hans Petter Selasky <hselasky@FreeBSD.org>. legends only. 👑

💖 and that's the page!! brought to you by the Debian crew, dated April 24, 2018, filed under USB(4). go plug something in responsibly, bestie. 🎀✨
📦 where this page comes from