EHCI(4)

📦
version 15.1 · 3 versions
, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 EHCI(4) — the USB Enhanced Host Controller driver, bestie edition 🦋

okay so real talk, this is the manual page for ehci from the Kernel Interfaces Manual — yes that Kernel Interfaces Manual, the one your kernel-nerd mutual keeps quoting at parties. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

ehci — the USB Enhanced Host Controller driver. iconic behavior, no notes 👑

🌸 SYNOPSIS 🌸

device ehci

that's it. that's the whole vibe. one line, one device declaration, and you're in 💅

🦋 DESCRIPTION 🦋

so the ehci driver provides support for the USB Enhanced Host Controller Interface, which is what USB 2.0 controllers use. literally the whole point. main character energy ✨

here's the tea though: EHCI controllers are peculiar 😭 and by peculiar i mean they can only handle the USB 2.0 protocol. only. exclusively. that's their one job.

which means — and this is the part everyone gets confused about — they normally have one or more companion controllers (ohci(4) or uhci(4)) hanging around handling the USB 1.x devices. so every single USB connector is electrically connected to two USB controllers at once. two. at the same time. it's giving twin flames 💖

the handling of all of this is totally automatic — you don't have to do a single thing, it just works. but you can notice it, because USB 1.x devices and USB 2.0 devices plugged into the same connector appear to connect to different USB buses. same hole, different bus. iykyk 🫶

🎀 LOADER TUNABLES 🎀

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 store them in loader.conf(5). flexible queen behavior 💅

  • hw.usb.ehci.lostintrbug — this tunable enables the lost interrupt quirk. the default value is 0 (off). leave it off unless you know, bestie 🙈
  • hw.usb.ehci.iaadbug — this tunable enables the EHCI doorbell quirk. the default value is 0 (off). ding dong, it's optional 🔔
  • 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). high-speed? not today. we're going low and slow 🐢
ngl, all three of these default to 0 (off), so if you're not debugging you can literally forget they exist. but now you know they exist. you're welcome 😌

🌈 SYSCTL VARIABLES 🌈

the following variables are available as both sysctl(8) variables and loader(8) tunables. dual threat. multitalented. we love to see it 👑

  • hw.usb.ehci.debug — debug output level, where 0 is debugging disabled and larger values increase debug message verbosity. default is 0. so zero is quiet, bigger numbers are louder, and there is no in-between, periodt 🔥

⭐ SEE ALSO ⭐

  • ohci(4) — companion controller bestie #1
  • uhci(4) — companion controller bestie #2
  • usb(4) — the whole USB situation
  • xhci(4) — the newer kid on the block

go read them, they're literally right there 📚

💜 HISTORY 💜

the ehci device driver first appeared in FreeBSD 5.1. a legend since day one 🎀

alright bestie, that's the whole page 🫶 i'm obsessed with how much lore is hidden in one tiny driver. this Debian build of the page is dated April 24, 2018, and it came from the Kernel Interfaces Manual (section 4, obviously). stan ehci. bye 💖✨💅

📦 where this page comes from