Differential D51299 Diff 158463 share/man/man4/udbc.4

Changeset View

Standalone View

View Options

share/man/man4/udbc.4

This file was added.

.\" -

ziaeeUnsubmitted

Not Done

- .\" -

+ .\"

.\" SPDX-License-Identifier: BSD-2-Clause

This hyphen was for a long abandoned parser.

ziaee: This hyphen was for a long abandoned parser.

.\" SPDX-License-Identifier: BSD-2-Clause

.\"

.\" This documentation was written by Tom Jones <thj@freebsd.org> under

.\" sponsorship from the FreeBSD Foundation.

.\"

.Dd July 14, 2025

.Dt UDBC 4

.Os

.Sh NAME

.Nm udbc

.Nd USB Debug Host mode driver

hrsUnsubmitted

Not Done

I have a patch to explain the DbC function based on the words in the specification. Could you take a look at it?

https://people.allbsd.org/~hrs/FreeBSD/D51299-udbc.4
https://people.allbsd.org/~hrs/FreeBSD/D51299-udbc.4.diff

These terminologies may be rather difficult to understand, but I feel a bit odd about the original patch since the udbc driver is not xHC-specific. The suggested patch tries to keep more generic description. Plus, I added a reference of the A-to-A cable specification.

hrs: I have a patch to explain the DbC function based on the words in the specification. Could you…

thjAuthorUnsubmitted

Done

These links don't work for me (0930UTC 14th August)

thj: These links don't work for me (0930UTC 14th August)

thjAuthorUnsubmitted

Done

Thanks these work today (they didn't yesterday).

I'll probably take your text whole in the review

thj: Thanks these work today (they didn't yesterday). I'll probably take your text whole in the…

.Sh SYNOPSIS

To compile this driver into the kernel,

place the following lines in your

kernel configuration file:

.Bd -ragged -offset indent

.Cd "device usb"

.Cd "device ucom"

.Cd "device udbc"

.Ed

.Pp

Alternatively, to load the driver as a

module at boot time, place the following line in

.Xr loader.conf 5 :

.Bd -literal -offset indent

udbc_load="YES"

.Ed

ziaeeUnsubmitted

Done

.Sh SYNOPSIS

- To compile this driver into the kernel,

- place the following lines in your

- kernel configuration file:

- .Bd -ragged -offset indent

.Cd "device usb"

.Cd "device ucom"

.Cd "device udbc"

- .Ed

.Pp

- Alternatively, to load the driver as a

- module at boot time, place the following line in

- .Xr loader.conf 5 :

- .Bd -literal -offset indent

- udbc_load="YES"

- .Ed

+ In

+ .Xr rc.conf 5 :

+ .Cd kld_list="udbc"

.Sh DESCRIPTION

I'm trying to increase the consistency and predictability of the manual. Predictability is one of the greatest strengths of manuals, but it requires consistency, like we have in every other section's synopses. I gave a 5 min lightning talk about section 4 synopses at BSDCan:

https://people.freebsd.org/~ziaee/tmp/bsdcan25lightning-ziaee.webm

ziaee: I'm trying to increase the consistency and predictability of the manual. Predictability is one…

.Sh DESCRIPTION

The USB eXtensible Host Controller Interface standard defines a high speed

debug mode a controller can enter which enables low level debugging of a

Debug Target.

.Pp

The Target must be an XHCI controller with support for the debug extended

capability and a directly accessible port on the controller (connectable

without any intermedia USB hus),

pauamma_chezdork.comUnsubmitted

Done

capability and a directly accessible port on the controller (connectable

- without any intermedia USB hus),

+ without any intermediate USB hub),

the Host can be any system with an available USB 3 port.

pauamma_chezdork.com:

the Host can be any system with an available USB 3 port.

.Nm

driver provides support of the Host side of USB debug.

The

.Nm

enables a Host to debug a Target using the xHCI debug interface.

.Pp

The debug mode must be configured on the Target and Host and Target connected

to the Host with a special USB 3 cable.

.Pp

.Nm

emulates a serial device and is accessed through the

.Xr ucom 4

driver which makes it behave like a

.Xr tty 4 .

.Sh HARDWARE

To attach the Host must be connected to a target with a special USB 3 cable

which has the VBUS, D+ and D- wires disconnected.

Once the target is configured to use xhci debug and a cable connects the Host

and the Target the

pauamma_chezdork.comUnsubmitted

Done

Is there a difference between "target" (uncapitalized) and "Target" (capitalized)?

pauamma_chezdork.com: Is there a difference between "target" (uncapitalized) and "Target" (capitalized)?

.Nm

driver will attach.

ziaeeUnsubmitted

Not Done

This should go earlyish in DESCRIPTION, HARDWARE should say something like:

The
.Nm
driver supports the debugging channel provided by XHCI compliant controllers.

If I'm understanding this patch correctly.

ziaee: This should go earlyish in DESCRIPTION, HARDWARE should say something like: ``` The .Nm driver…

ziaeeUnsubmitted

Not Done

Sorry I didn't explain it well enough. This entire section will appear in the hardware release notes. Its supposed to describe what is supported by the driver, see https://man-dev.freebsd.org/style.mdoc#HARDWARE_Section

ziaee: Sorry I didn't explain it well enough. This entire section will appear in the hardware release…

.Sh FILES

.Bl -tag -width "/dev/ttyU*.*.init" -compact

.It Pa /dev/ttyU*.*

for callin ports

.It Pa /dev/ttyU*.*.init

.It Pa /dev/ttyU*.*.lock

corresponding callin initial-state and lock-state devices

.Pp

.It Pa /dev/cuaU*.*

for callout ports

.It Pa /dev/cuaU*.*.init

.It Pa /dev/cuaU*.*.lock

corresponding callout initial-state and lock-state devices

.El

.Sh SEE ALSO

.Xr tty 4 ,

.Xr ucom 4 ,

.Xr usb 4

ziaeeUnsubmitted

Not Done

.Xr ucom 4 ,

- .Xr usb 4

+ .Xr usb 4 ,

+ .Xr xhci 4

.Pp

.It

.Rs

ziaee:

.Pp

.It

.Rs

.%T eXtensible Host Controller Interface for Universal Serial Bus (XHCI)

.%U https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf

ziaeeUnsubmitted

Done

I think we should move these to STANDARDS

ziaee: I think we should move these to STANDARDS

.Re

.It

.Rs

.%T USB 3.1 Device Class Specification for Debug Devices

.%U https://www.usb.org/sites/default/files/documents/usb_debug_class_rev_1_0_final_0.pdf

.Re

.Sh HISTORY

The

.Nm

driver first appeared

.Fx

15.0.

pauamma_chezdork.comUnsubmitted

Not Done

.Sh HISTORY

The

.Nm

- driver first appeared

- .Fx

- 15.0.

+ driver first appeared in

+ .Fx 15.0 .

.Sh AUTHORS

pauamma_chezdork.com:

ziaeeUnsubmitted

Not Done

The 15.0 is an argument to .Fx so it does need to be on the same line.

ziaee: The 15.0 is an argument to .Fx so it does need to be on the same line.

.Sh AUTHORS

.An -nosplit

The

.Nm

driver was written by

.An Hiroki Sato Aq Mt hrs@FreeBSD.org .

.Sh BUGS

According to the XHCI specification the host side of USB Debug should work with

any USB 3.0 port,

whether connected to directly to a controller or with a hub in between.

Testing on some controllers has encountered issues when using a hub rather than

a port directly.

.Pp

The interaction between USB Debug, USB 3 A connectors and USB-C connectors is

unclear,

USB debug with a USB-C cable is not known to work.

lwhsuUnsubmitted

Done

any USB 3.0 port,

- whether connected to directly to a controller or with a hub in between.

+ 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

lwhsu: