NAME

udbc — USB Debug Class device driver

SYNOPSIS

device usb
device ucom
device udbc

In rc.conf(5):
kld_list="udbc"

DESCRIPTION

The udbc driver provides support for USB Debug Class devices whose interface class is Diagnostic Class and the subclass is DbC.GP.

The USB Debug Class is defined in the USB 3.1 Device Class Specification for Debug Devices. This is 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.

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.

HARDWARE CONFIGURATION

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

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 is to 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 that 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.

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

STANDARDS

eXtensible Host Controller Interface for Universal Serial Bus (XHCI), https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf. USB 3.1 Device Class Specification for Debug Devices, https://www.usb.org/sites/default/files/documents/usb_debug_class_rev_1_0_final_0.pdf. USB 3.1 Legacy Cable and Connector Specification, https://www.usb.org/document-library/usb-31-legacy-cable-and-connector-revision-10.

HISTORY

The udbc driver first appeared FreeBSD 15.0.

AUTHORS

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

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.