USB(4)

💖 usb(4) — Universal Serial Bus 💖

okay bestie so this is the usb man page, from the Kernel Interfaces Manual — yeah we're going deep into the kernel today, buckle up 🎀

---

✨ NAME ✨

usb — Universal Serial Bus 🦋

---

✨ SYNOPSIS ✨

so if you wanna bake this driver right into the kernel, drop this line into your kernel configuration file:

device usb

or, alternate vibe, load it as a module at boot time and put this in loader.conf(5):

usb_load="YES"

either way, slay 💅

---

✨ USERLAND PROGRAMMING ✨

good news!! you can touch USB functions from userland through the libusb library. go check libusb(3) for the deets 🫶

---

✨ DESCRIPTION ✨

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

the usb driver has three layers, and the way it's structured is genuinely giving stacked cake 🎂:

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

the controller attaches to a physical bus like pci(4). the USB bus attaches to the controller, and the root hub attaches to the controller. any devices attached to the bus will attach to the root hub or another hub attached to the USB bus.

the uhub device will always be present because it is needed for the root hub — no uhub, no tree, periodt. 💀

---

✨ INTRODUCTION TO USB ✨

so the whole deal with USB is: external devices can be connected to a PC. that's the vibe. 🌈

the most common USB speeds are:

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

each USB has a USB controller that is the master of the bus — main character energy fr fr 👑. the physical communication is simplex, which means the host controller only communicates with one USB device at a time.

up to 127 devices can be connected to an USB HUB tree. the addresses are assigned dynamically by the host when each device attaches to the bus.

within each device there can be up to 16 endpoints. each endpoint is individually addressed, and the addresses are static. each of these endpoints will communicate in one of four different modes: control, isochronous, bulk, or interrupt. a device always has at least one endpoint. that endpoint has address 0 and is a control endpoint, and it's used to give commands to and extract basic data (like descriptors) from the device. each 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 — e.g., a compound device with both a keyboard and a trackball would present one interface for each. an interface can sometimes be set into different modes called alternate settings, which affects how it operates. different alternate settings can have different endpoints within it. it's giving ✨versatility✨

a device may 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.

---

✨ SYSCTL VARIABLES ✨

these variables are available both as sysctl(8) variables and loader(8) tunables — double duty queen 💜:

• 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:

https://www.usb.org/documents

and here's the whole friend group 🫶:

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 3.0 standard. certified, 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>.

---

okay that's the whole page bestie, you're officially USB-literate 💅✨ — brought to you by Debian, dated September 7, 2020, and that's the vibe check, we're done here 🦋💖