UDBC(4)

📦 version 15.1, in freebsd 15.1, nixpkgs unstable

✨ NAME ✨

udbc(4) is the USB Debug Class device driver — and yes, that's the whole name, bestie 💅. This page is from the Kernel Interfaces Manual, and it's about to be your new fave.

🛠️ SYNOPSIS 🛠️

device usb
device ucom
device udbc

In rc.conf(5):

kld_list="udbc"

💖 DESCRIPTION 💖

okay so the udbc driver gives support for USB Debug Class devices where the interface class is Diagnostic Class and the subclass is DbC.GP. Periodt.

The USB Debug Class is defined in the USB 3.1 Device Class Specification for Debug Devices. It's designed to provide a general-purpose communication channel for debugging. It has also been widely implemented in USB xHCs (USB eXtensible Host Controllers), which can be found on many commodity computers, as an optional feature. Once this feature is enabled on a USB xHC, one of the USB ports will behave as a USB Debug Class device, not a host port, when a USB debug cable is connected. The supported class in USB xHCs is typically DbC.GP, while the specification defines several types of Debug Class devices. The DbC.GP uses IN and OUT endpoint pairs and realizes a single bidirectional serial communication channel. On most systems, including FreeBSD, the DbC.GP is seen as a simple serial device. Slay.

Most systems with USB xHC can be configured to provide DbC.GP access. The udbc is a driver that connects to DbC.GP-supported devices, offering tty(4) devices to connect to them via the ucom(4) device driver. obsessed 💖.

🔌 HARDWARE CONFIGURATION 🔌

A native DbC.GP device can be attached using the udbc driver in a straightforward way. Easy peasy.

A USB xHC DbC.GP device on a target system needs a special hardware configuration because all of the ports are supposed to be a USB Host. There is one method to expose DbC.GP: use a USB 3.1 A-to-A cable (section 5.5.2 in USB 3.1 Legacy Cable and Connector Specification). When this cable is connected to a USB 3.1 port on the target system, the DbC-enabled USB xHC automatically switches the port as a USB Device. The udbc driver can find a DbC.GP device on that port.

⚠️ note bestie: a USB xHC with USB 3.2 support (USB Type-C connectors) is not compatible with the USB 3.1 A-to-A cable. Connecting a USB 3.2 C-to-C cable or A-to-C cable does not automatically work, either, because it needs role configuration of the port, which is not supported on FreeBSD yet. So don't come for me if that cable vibe check fails 😭.

📁 FILES 📁

  • /dev/ttyU*.* — for callin ports
  • /dev/ttyU*.*.init, /dev/ttyU*.*.lock — corresponding callin initial-state and lock-state devices
  • /dev/cuaU*.* — for callout ports
  • /dev/cuaU*.*.init, /dev/cuaU*.*.lock — corresponding callout initial-state and lock-state devices

👀 SEE ALSO 👀

tty(4), ucom(4), usb(4), xhci(4) — go read these too, iykyk 💜.

📚 STANDARDS 📚

🕰️ HISTORY 🕰️

The udbc driver first appeared FreeBSD 15.0. iconic behavior.

👑 AUTHORS 👑

The udbc driver was written by Hiroki Sato <hrs@FreeBSD.org>. ty king 🫶.

💀 BUGS 💀

According to the XHCI specification the host side of USB Debug should work with any USB 3.0 port, whether connected directly to a controller or with a hub in between. Testing on some controllers has encountered issues when using a hub rather than a directly connected port on the controller. So yeah, hub drama is real 🙈.

okay that's the page, bestie 💖 — footer vibes: Debian, September 3, 2025, UDBC(4). byeee 🎀✨

📦 where this page comes from