EHCI(4)

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

💖 EHCI(4) — the Kernel Interfaces Manual glow-up 💖

okay bestie, sit down, hydrate, because we're talking about ehci — the USB Enhanced Host Controller driver and honestly? she's iconic. this is from the Kernel Interfaces Manual, section 4, so you know it's kernel-device territory. let's get into it ✨

🌸 NAME 🌸

ehci — USB Enhanced Host Controller driver

✨ SYNOPSIS ✨

device ehci

that's it. that's the whole vibe. one line, no cap 💅

🦋 DESCRIPTION 🦋

so the ehci driver is out here providing support for the USB Enhanced Host Controller Interface, which is the interface that USB 2.0 controllers use. periodt.

now here's the tea, and it's kind of a big deal: EHCI controllers are peculiar (their word, not mine, but fr fr) because they can only handle the USB 2.0 protocol. that's literally all they do. which means they normally have one or more companion controllers hanging around — like ohci(4) or uhci(4) — and those besties are the ones handling all the USB 1.x devices. teamwork, slay 🫶

consequence of all this? every single USB connector is electrically connected to two USB controllers. two. for one physical port. lowkey unhinged but okay.

the handling of this whole situation is totally automatic — you don't have to do anything, she just handles it — but you can notice it, because USB 1.x devices and USB 2.0 devices plugged into the same connector will appear to connect to different USB buses. yes it looks weird. no it's not a bug. it's giving "two controllers, one port, zero drama" 💀

🎀 LOADER TUNABLES 🎀

okay so when the kernel has been compiled with options USB_DEBUG, some tunables become available that affect the behavior of ehci. you can set these at the loader(8) prompt before booting the kernel, or you can store them in loader.conf(5). your call, bestie ⭐

  • hw.usb.ehci.lostintrbug — this tunable enables the lost interrupt quirk. the default value is 0 (off).
  • hw.usb.ehci.iaadbug — this tunable enables the EHCI doorbell quirk. the default value is 0 (off).
  • hw.usb.ehci.no_hs — this tunable disables USB devices from attaching like HIGH-speed ones, and will force all attached devices to attach to the FULL- or LOW-speed companion controller. the default value is 0 (off).
ngl these all default to 0 (off) so if you don't touch them, nothing changes. they're there for when things get weird 🔥

💜 SYSCTL VARIABLES 💜

the following variables are available as both sysctl(8) variables and loader(8) tunables. double duty, main character energy 👑

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

🌈 SEE ALSO 🌈

go read those too, iykyk 📚

🍓 HISTORY 🍓

the ehci device driver first appeared in FreeBSD 5.1. a legend from day one 💅

and that's the whole page, bestie!! this one came from Debian, dated April 24, 2018 — so yeah, vintage but still absolutely eating. go plug something in. 💖🎀🦋

📦 where this page comes from