1.\" 2.\" Copyright (c) 2025 The FreeBSD Foundation 3.\" 4.\" This documentation was written by Tom Jones <thj@freebsd.org> under 5.\" sponsorship from the FreeBSD Foundation. 6.\" 7.\" SPDX-License-Identifier: BSD-2-Clause 8.\" 9.\" 10.Dd September 3, 2025 11.Dt UDBC 4 12.Os 13.Sh NAME 14.Nm udbc 15.Nd USB Debug Class device driver 16.Sh SYNOPSIS 17.Cd "device usb" 18.Cd "device ucom" 19.Cd "device udbc" 20.Pp 21In 22.Xr rc.conf 5 : 23.Cd kld_list="udbc" 24.Sh DESCRIPTION 25The 26.Nm 27driver provides support for USB Debug Class devices whose 28interface class is Diagnostic Class and the subclass is DbC.GP. 29.Pp 30The USB Debug Class is defined in the USB 3.1 Device Class 31Specification for Debug Devices. 32This is designed to provide a general-purpose communication channel 33for debugging. 34It has also been widely implemented in USB xHCs 35.Pq USB eXtensible Host Controllers , 36which can be found on many commodity computers, 37as an optional feature. 38Once this feature is enabled on a USB xHC, one of the USB ports will 39behave as a USB Debug Class device, 40not a host port, 41when a USB debug cable is connected. 42The supported class in USB xHCs is typically DbC.GP, 43while the specification defines several types of Debug Class devices. 44The DbC.GP uses IN and OUT endpoint pairs and realizes a single 45bidirectional serial communication channel. 46On most systems, 47including 48.Fx , 49the DbC.GP is seen as a simple serial device. 50.Pp 51Most systems with USB xHC can be configured to provide DbC.GP access. 52The 53.Nm 54is a driver that connects to DbC.GP-supported devices, 55offering 56.Xr tty 4 57devices to connect to them via the 58.Xr ucom 4 59device driver. 60.Sh HARDWARE CONFIGURATION 61A native DbC.GP device can be attached using the 62.Nm 63driver in a straightforward way. 64.Pp 65A USB xHC DbC.GP device on a target system needs a special hardware 66configuration because all of the ports are supposed to be a USB Host. 67There is one method to expose DbC.GP is to use a USB 3.1 A-to-A cable 68.Pq section 5.5.2 in USB 3.1 Legacy Cable and Connector Specification . 69When this cable is connected to a USB 3.1 port on the target system, 70the DbC-enabled USB xHC automatically switches the port as a USB Device. 71The 72.Nm 73driver can find a DbC.GP device on that port. 74.Pp 75Note that a USB xHC with USB 3.2 support 76.Pq USB Type-C connectors 77is not compatible with the USB 3.1 A-to-A cable. 78Connecting a USB 3.2 C-to-C cable or A-to-C cable does not automatically work, 79either, 80because it needs role configuration of the port, which is not supported on 81.Fx 82yet. 83.Sh FILES 84.Bl -tag -width "/dev/ttyU*.*.init" -compact 85.It Pa /dev/ttyU*.* 86for callin ports 87.It Pa /dev/ttyU*.*.init 88.It Pa /dev/ttyU*.*.lock 89corresponding callin initial-state and lock-state devices 90.Pp 91.It Pa /dev/cuaU*.* 92for callout ports 93.It Pa /dev/cuaU*.*.init 94.It Pa /dev/cuaU*.*.lock 95corresponding callout initial-state and lock-state devices 96.El 97.Sh SEE ALSO 98.Xr tty 4 , 99.Xr ucom 4 , 100.Xr usb 4 , 101.Xr xhci 4 102.Sh STANDARDS 103.Rs 104.%T eXtensible Host Controller Interface for Universal Serial Bus (XHCI) 105.%U https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf 106.Re 107.Rs 108.%T USB 3.1 Device Class Specification for Debug Devices 109.%U https://www.usb.org/sites/default/files/documents/usb_debug_class_rev_1_0_final_0.pdf 110.Re 111.Rs 112.%T USB 3.1 Legacy Cable and Connector Specification 113.%U https://www.usb.org/document-library/usb-31-legacy-cable-and-connector-revision-10 114.Re 115.Sh HISTORY 116The 117.Nm 118driver first appeared 119.Fx 12015.0. 121.Sh AUTHORS 122.An -nosplit 123The 124.Nm 125driver was written by 126.An Hiroki Sato Aq Mt hrs@FreeBSD.org . 127.Sh BUGS 128According to the XHCI specification the host side of USB Debug should work with 129any USB 3.0 port, 130whether connected directly to a controller or with a hub in between. 131Testing on some controllers has encountered issues when using a hub rather than 132a directly connected port on the controller. 133