Changeset View
Changeset View
Standalone View
Standalone View
share/man/man4/usb.4
Show All 18 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd April 24, 2018 | .Dd September 7, 2020 | ||||
.Dt USB 4 | .Dt USB 4 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm usb | .Nm usb | ||||
.Nd Universal Serial Bus | .Nd Universal Serial Bus | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
To compile this driver into the kernel, | To compile this driver into the kernel, | ||||
place the following line in your | place the following line in your | ||||
Show All 11 Lines | |||||
.Sh USERLAND PROGRAMMING | .Sh USERLAND PROGRAMMING | ||||
USB functions can be accessed from userland through the libusb library. | USB functions can be accessed from userland through the libusb library. | ||||
See | See | ||||
.Xr libusb 3 | .Xr libusb 3 | ||||
for more information. | for more information. | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
.Fx | .Fx | ||||
provides machine-independent bus support and drivers for | provides machine-independent bus support and drivers for | ||||
.Tn USB | USB devices in host and device side mode. | ||||
devices in host and device side mode. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Nm | .Nm | ||||
driver has three layers: | driver has three layers: | ||||
.Bl -tag -width 6n -offset indent | .Bl -tag -width 6n -offset indent | ||||
.It USB Controller (Bus) | .It USB Controller (Bus) | ||||
.It USB Device | .It USB Device | ||||
.It USB Driver | .It USB Driver | ||||
.El | .El | ||||
.Pp | .Pp | ||||
The controller attaches to a physical bus | The controller attaches to a physical bus | ||||
like | like | ||||
.Xr pci 4 . | .Xr pci 4 . | ||||
The | The USB bus attaches to the controller, and the root hub attaches | ||||
.Tn USB | |||||
bus attaches to the controller, and the root hub attaches | |||||
to the controller. | to the controller. | ||||
Any devices attached to the bus will attach to the root hub | Any devices attached to the bus will attach to the root hub | ||||
or another hub attached to the | or another hub attached to the USB bus. | ||||
.Tn USB | |||||
bus. | |||||
.Pp | .Pp | ||||
The | The | ||||
.Nm uhub | .Nm uhub | ||||
device will always be present as it is needed for the root hub. | device will always be present as it is needed for the root hub. | ||||
.Sh INTRODUCTION TO USB | .Sh INTRODUCTION TO USB | ||||
The | The USB is a system where external devices can be connected to a PC. | ||||
.Tn USB | |||||
is a system where external devices can be connected to a PC. | |||||
The most common USB speeds are: | The most common USB speeds are: | ||||
.Bl -tag -width 6n -offset indent | .Bl -tag -width 6n -offset indent | ||||
.It Low Speed (1.5MBit/sec) | .It Low Speed (1.5 MBit/sec) | ||||
.It Full Speed (12MBit/sec) | .It Full Speed (12 MBit/sec) | ||||
.It High Speed (480MBit/sec) | .It High Speed (480 MBit/sec) | ||||
.It SuperSpeed (5 GMBit/sec) | |||||
bcr: Shouldn't that be GBit/sec instead of GMBit/sec? | |||||
.El | .El | ||||
.Pp | .Pp | ||||
Each | Each USB has a USB controller that is the master of the bus. | ||||
.Tn USB | |||||
has a USB controller that is the master of the bus. | |||||
The physical communication is simplex which means the host controller only | The physical communication is simplex which means the host controller only | ||||
communicates with one USB device at a time. | communicates with one USB device at a time. | ||||
.Pp | .Pp | ||||
There can be up to 127 devices connected to an USB HUB tree. | There can be up to 127 devices connected to an USB HUB tree. | ||||
The addresses are assigned dynamically by the host when each device is | The addresses are assigned dynamically by the host when each device is | ||||
attached to the bus. | attached to the bus. | ||||
.Pp | .Pp | ||||
Within each device there can be up to 16 endpoints. | Within each device there can be up to 16 endpoints. | ||||
Show All 13 Lines | |||||
An interface can sometimes be set into different modes, called alternate | An interface can sometimes be set into different modes, called alternate | ||||
settings, which affects how it operates. | settings, which affects how it operates. | ||||
Different alternate settings can have different endpoints within it. | Different alternate settings can have different endpoints within it. | ||||
.Pp | .Pp | ||||
A device may operate in different configurations. | A device may operate in different configurations. | ||||
Depending on the configuration, the device may present different sets of | Depending on the configuration, the device may present different sets of | ||||
endpoints and interfaces. | endpoints and interfaces. | ||||
.Pp | .Pp | ||||
The bus enumeration of the | The bus enumeration of the USB bus proceeds in several steps: | ||||
.Tn USB | |||||
bus proceeds in several steps: | |||||
.Bl -enum | .Bl -enum | ||||
.It | .It | ||||
Any interface specific driver can attach to the device. | Any interface specific driver can attach to the device. | ||||
.It | .It | ||||
If none is found, generic interface class drivers can attach. | If none is found, generic interface class drivers can attach. | ||||
.El | .El | ||||
.Sh SYSCTL VARIABLES | .Sh SYSCTL VARIABLES | ||||
The following variables are available as both | The following variables are available as both | ||||
.Xr sysctl 8 | .Xr sysctl 8 | ||||
variables and | variables and | ||||
.Xr loader 8 | .Xr loader 8 | ||||
tunables: | tunables: | ||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
.It Va hw.usb.debug | .It Va hw.usb.debug | ||||
Debug output level, where 0 is debugging disabled and larger values increase | Debug output level, where 0 is debugging disabled and larger values increase | ||||
debug message verbosity. | debug message verbosity. | ||||
Default is 0. | Default is 0. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
The | The USB specifications can be found at: | ||||
.Tn USB | |||||
specifications can be found at: | |||||
.Pp | .Pp | ||||
.D1 Pa http://www.usb.org/developers/docs/ | .D1 Pa https://www.usb.org/documents | ||||
.Pp | .Pp | ||||
.Xr libusb 3 , | .Xr libusb 3 , | ||||
.Xr aue 4 , | .Xr aue 4 , | ||||
.Xr axe 4 , | .Xr axe 4 , | ||||
.Xr axge 4 , | .Xr axge 4 , | ||||
.Xr cue 4 , | .Xr cue 4 , | ||||
.Xr ehci 4 , | .Xr ehci 4 , | ||||
.Xr kue 4 , | .Xr kue 4 , | ||||
Show All 13 Lines | |||||
.Xr urio 4 , | .Xr urio 4 , | ||||
.Xr uvscom 4 , | .Xr uvscom 4 , | ||||
.Xr xhci 4 | .Xr xhci 4 | ||||
.Xr usbconfig 8 , | .Xr usbconfig 8 , | ||||
.Xr usbdi 9 | .Xr usbdi 9 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The | The | ||||
.Nm | .Nm | ||||
module complies with the USB 2.0 standard. | module complies with the USB 3.0 standard. | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
module has been inspired by the | module has been inspired by the | ||||
.Nx | .Nx | ||||
USB stack initially written by | USB stack initially written by | ||||
.An Lennart Augustsson . | .An Lennart Augustsson . | ||||
The | The | ||||
.Nm | .Nm | ||||
module was written by | module was written by | ||||
.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . | .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . |
Shouldn't that be GBit/sec instead of GMBit/sec?