path: root/usr/src/man/man8/cfgadm_usb.8

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2022 Oxide Computer Company
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CFGADM_USB 8 "Feb 23, 2022"
.SH NAME
cfgadm_usb \- USB hardware-specific commands for cfgadm
.SH SYNOPSIS
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] \fB-c\fR \fIfunction\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-f\fR [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-v\fR [\fB-a\fR] [\fB-s\fR \fIlisting_option\fR]
     [\fB-l\fR [\fIap_id\fR | \fIap_type\fR...]]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR \fB-v\fR \fB-h\fR [\fIap_id\fR]...
.fi

.SH DESCRIPTION
The Universal Serial Bus (\fBUSB\fR) hardware-specific library
\fB/usr/lib/cfgadm/usb.so.1\fR provides the functionality for administering
\fBUSB\fR devices via the \fBcfgadm\fR(8) command. \fBcfgadm\fR operates on
attachment points. For details regarding attachment points, refer to
\fBcfgadm\fR(8).
.sp
.LP
For \fBUSB\fR administration, the only attachment points supported are the
ports of hubs attached to the \fBUSB\fR bus.
.sp
.LP
Attachment points are named through attachment point IDs (\fIap_ids\fR). The
\fBUSB\fR bus is hierarchical, so the \fIap_ids\fR are as well. \fBUSB\fR hubs
have ports, numbered from \fB1\fR to \fIn\fR. All \fBUSB\fR \fIap_ids\fR
consist of a string of the following form:
.sp
.in +2
.nf
usb\fIN\fR/\fIA\fR[.\fIB\fR[.\fIC\fR[...]]]
.fi
.in -2
.sp

.sp
.LP
where
.br
.in +2
\fIN\fR is the \fIN\fRth \fBUSB\fR host controller on the system,
.in -2
.br
.in +2
\fIA\fR is port #\fIA\fR on the root (top) hub.
.in -2
.br
.in +2
\fIB\fR is port #\fIB\fR of the hub plugged into port #\fIA\fR of the hub above
it.
.in -2
.br
.in +2
\fIC\fR is port #\fIC\fR of the hub plugged into port #\fIB \fRof the hub above
it, and so forth.
.in -2
.sp
.LP
For example, the first port on the root hub of USB controller \fB0\fR (the only
controller), has a logical \fIap_id\fR:
.sp
.in +2
.nf
usb0/1
.fi
.in -2
.sp

.sp
.LP
Similarly, the second port on the first external hub plugged into the first
port on the root hub of the first \fBUSB\fR controller has a logical
\fIap_id\fR:
.sp
.in +2
.nf
usb0/1.2
.fi
.in -2
.sp

.sp
.LP
For example, if the \fIap_id\fR is \fBusb0/1.4.3.4\fR, it represents port
\fB4\fR of the hub plugged into port \fB3\fR of the hub plugged into port
\fB4\fR of the hub plugged into port \fB1\fR of the root hub of the first
\fBUSB\fR host controller on the system.
.sp
.in +2
.nf
example# \fBcfgadm -l\fR
Ap_Id                Type         Receptacle   Occupant     Condition
usb0/1               USB-hub      connected    configured   ok
usb0/2               unknown      empty        unconfigured ok
usb0/1.1             USB-storage  connected    configured   ok
usb0/1.2             unknown      empty        unconfigured ok
usb0/1.3             unknown      empty        unconfigured ok
usb0/1.4             USB-device   connected    configured   ok
.fi
.in -2
.sp

.sp
.LP
\fBUSB 2.0\fR chips have one \fBEHCI\fR host \fBUSB 2.0\fR host controller and a
number of companion \fBUSB 1.\fR\fIx\fR host controllers (either \fBOHCI\fR or
\fBUHCI\fR host controllers).
.sp
.LP
When a \fBUSB 2.0\fR device has been plugged in, it shows up on the \fBEHCI\fR
logical ports which might not have a \fB1\fR to \fB1\fR mapping to external
physical port numbers on the system.  When a \fBUSB 1.\fR\fIx\fR device is
plugged in, the \fBEHCI\fR host controller reroutes the device to a companion
host controller and the device shows up on  the companion's logical port
number.
.sp
.LP
The mapping of logical port numbers to physical port numbers can get quite
complicated. For example:
.sp
.in +2
.nf
% cfgadm
Ap_Id                Type         Receptacle   Occupant     Condition
c0                   scsi-bus     connected    configured   unknown
usb0/1               usb-mouse    connected    configured   ok
usb0/2               usb-kbd      connected    configured   ok
usb0/3               unknown      empty        unconfigured ok
usb0/4               usb-hub      connected    configured   ok
usb0/4.1             unknown      empty        unconfigured ok
usb0/4.2             unknown      empty        unconfigured ok
usb0/4.3             unknown      empty        unconfigured ok
usb0/4.4             usb-storage  connected    configured   ok
usb1/1               unknown      empty        unconfigured ok
usb1/2               unknown      empty        unconfigured ok
usb1/3               unknown      empty        unconfigured ok
usb2/1               unknown      empty        unconfigured ok
usb2/2               usb-device   connected    configured   ok
usb3/1               unknown      empty        unconfigured ok
usb3/2               unknown      empty        unconfigured ok
usb3/3               unknown      empty        unconfigured ok
usb3/4               unknown      empty        unconfigured ok
usb3/5               unknown      empty        unconfigured ok
.fi
.in -2
.sp

.sp
.LP
In this example \fBusb0\fR is the onboard USB 1.\fIx\fR host controller.
\fBusb1\fR and \fBusb2\fR are companion \fBOHCI USB 1.\fR\fIx\fR host
controllers and \fBusb3\fR is an \fBEHCI USB 2.0\fR host controller.
.sp
.LP
The following table shows the somewhat confusing routing for this USB 2.0 chip:
.sp
.in +2
.nf
logical port number		physical port number
-------------------		--------------------
	usb1/1			internal port 1
	usb1/2			external port 1
	usb1/3			external port 3

	usb2/1			internal port 2
	usb2/2			external port 2

	usb3/1			internal port 1
	usb3/2			internal port 2
	usb3/3			external port 1
	usb3/4			external port 2
	usb3/5			external port 3
.fi
.in -2
.sp

.sp
.LP
Unfortunately, the exact routing can often only be determined by
experimentation.
.sp
.LP
The receptacle states for attachment points at the \fBUSB\fR port have the
following meanings:
.sp
.ne 2
.na
\fB\fBconnected\fR\fR
.ad
.sp .6
.RS 4n
\fBUSB\fR port is powered on and enabled. A USB device is plugged in to the
port. The device is logically connected to the USB bus.
.RE

.sp
.ne 2
.na
\fB\fBdisconnected\fR\fR
.ad
.sp .6
.RS 4n
\fBUSB\fR port is powered on and enabled. A \fBUSB\fR device is plugged into
the port. The device has been logically disconnected from the \fBUSB\fR bus
(using the \fBcfgadm\fR \fB-c\fR \fBdisconnect\fR command).
.RE

.sp
.ne 2
.na
\fB\fBempty\fR\fR
.ad
.sp .6
.RS 4n
\fBUSB\fR port is powered on, but no device is plugged in to it.
.RE

.sp
.LP
The occupant states for devices at \fBUSB\fR port attachment points at the
\fBUSB\fR port have the following meanings:
.sp
.ne 2
.na
\fB\fBconfigured\fR\fR
.ad
.sp .6
.RS 4n
The \fBUSB\fR device at the \fBUSB\fR port is configured and usable by Solaris.
.RE

.sp
.ne 2
.na
\fB\fBunconfigured\fR\fR
.ad
.sp .6
.RS 4n
The \fBUSB\fR device at the \fBUSB\fR port was explicitly off-lined using
\fBcfgadm\fR \fB-c\fR \fBunconfigure\fR, or was not successfully configured for
use with Solaris, for example, having no driver or a device problem.
.RE

.sp
.LP
The attachment point conditions are:
.sp
.ne 2
.na
\fB\fBok\fR\fB\fR\fR
.ad
.sp .6
.RS 4n
Normal state - ready for use.
.RE

.sp
.ne 2
.na
\fB\fBfailing\fR\fR
.ad
.sp .6
.RS 4n
Not used.
.RE

.sp
.ne 2
.na
\fB\fBfailed\fR\fR
.ad
.sp .6
.RS 4n
Not used.
.RE

.sp
.ne 2
.na
\fB\fBunusable\fR\fR
.ad
.sp .6
.RS 4n
The user has physically removed a device while an application had the device
open (there might be outstanding \fBI/O\fR). Users need to reinsert the same
physical device and close the application properly before removing the device
again. The port cannot configure other inserted devices until this is done.
.sp
If the original device cannot be reinserted into the port, see the \fI\fR for
instructions for clearing this attachment point condition.
.RE

.sp
.ne 2
.na
\fB\fBunknown\fR\fR
.ad
.sp .6
.RS 4n
Not used.
.RE

.sp
.LP
A \fBUSB\fR device can be hotplugged or hotunplugged at any time, and the
system detects the event and takes the appropriate action.
.sp
.LP
It is not necessary to transition a receptacle to the \fBdisconnected\fR state
before removing its device from the \fBUSB\fR. However, it is not recommended
to hot-remove devices currently in use (such as removable disks currently
opened by a volume manager or some other application).
.SH OPTIONS
\fBcfgadm\fR defines several types of operations. These operations include
invoking configuration state changes (\fB-c\fR), invoking hardware-specific
functions (\fB-x\fR), and obtaining configuration administration help messages
(\fB-h\fR).
.sp
.LP
If any of these operations fail, the device and attachment point might not be
in the expected state. Use the \fBcfgadm\fR \fB-l\fR command to display the
device's current status.
.sp
.LP
All other options have the same meaning as defined in \fBcfgadm\fR(8).
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.sp .6
.RS 4n
The following generic commands are defined for the \fBUSB\fR hardware specific
library. The following configuration state change operations are supported:
.sp
.ne 2
.na
\fB\fBconfigure\fR\fR
.ad
.sp .6
.RS 4n
If there is a \fBUSB\fR device plugged into the port, this command attempts to
configure it and set everything up so that it is usable by Solaris. This
command does an implied \fBconnect\fR (reverse of \fBdisconnect\fR) if
necessary. This command accomplishes nothing, and returns an error message, if
the device at that port is already configured. After successful execution of
this command, the device is ready for use under Solaris.
.RE

.sp
.ne 2
.na
\fB\fBdisconnect\fR\fR
.ad
.sp .6
.RS 4n
Performs an \fBunconfigure\fR on the \fIap_id\fR (if it is not already
\fBunconfigured\fR), and then transitions the receptacle to the
\fBdisconnected\fR state, even though a device is still be plugged into the
port. Issuing a \fBcfgadm\fR \fB-c\fR \fBconfigure\fR, or physically
hotplugging the device, brings the device back to the \fBconnected\fR
receptacle state, and to the \fBconfigured\fR occupant state, assuming a driver
can be found and there are no problems enumerating and configuring the device.
.RE

.sp
.ne 2
.na
\fB\fBunconfigure\fR\fR
.ad
.sp .6
.RS 4n
Makes the device plugged into the port unusable by Solaris (offline it). If
successful, \fBcfgadm\fR reports this \fIap_id\fR's occupant state as
\fBunconfigured\fR. Issuing a \fBconfigure\fR to the \fIap_id\fR (if
successful) brings its occupant back to the \fBconfigured\fR (online)
condition, as it physically hotplugging the device on the port.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Not supported.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
\fBUSB\fR specific help can be obtained by using the help option with any
\fBUSB\fR attachment point.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR[\fBv\fR]\fR
.ad
.sp .6
.RS 4n
The \fB-l\fR option works as described in \fBcfgadm\fR(8). When paired with
the \fB-v\fR option, the \fBInformation\fR field contains the following
\fBUSB\fR-specific information:
.RS +4
.TP
.ie t \(bu
.el o
\fBMfg\fR: manufacturer string (\fBiManufacturer\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBProduct\fR: product string (\fBiProduct\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBSerial\fR: serial number (\fBiSerialNumber\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBNConfigs\fR: total number of configurations the device supports
(\fBbNumConfigurations\fR).
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBConfig\fR: current configuration setting in decimal (configuration index,
not configuration value).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The configuration string descriptor for the current configuration
(\fBiConfiguration\fR)
.RE
See the Universal Serial Bus specification for a description of these fields.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIhardware_options\fR\fR
.ad
.sp .6
.RS 4n
Hardware options are only supported for the hardware-specific command, \fB-x\fR
\fBusb_config\fR. See the description of that command below for an explanation
of the options available.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIlisting_options\fR\fR
.ad
.sp .6
.RS 4n
Attachment points of class \fBUSB\fR can be listed by using the \fBselect\fR
sub-option. See \fBcfgadm\fR(8).
.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIhardware_function\fR\fR
.ad
.sp .6
.RS 4n
The following hardware-specific functions are defined:
.sp
.ne 2
.na
\fB\fBusb_config\fR \fB-o\fR \fBconfig=\fR\fIn\fR\fR
.ad
.sp .6
.RS 4n
This command requires the mandatory \fBconfig\fR value to be specified using
the \fB-o\fR option.
.sp
Sets the \fBUSB\fR configuration of a multi-configuration \fBUSB\fR device at
\fIap_id\fR to configuration index \fIn\fR. The device is set to this
configuration henceforth and this setting persists across reboots, hot-removes,
and unconfigure/configure of the device.
.sp
Valid values of \fIn\fR range from \fB0\fR to (\fBNconfigs -1\fR). The device
is reset by a \fBdisconnect\fR followed by a \fBconfigure\fR. The
\fBconfigure\fR causes the device to be configured to the new configuration
setting.
.sp
If any of these steps fail, the configuration file and the device are restored
to their previous state and an error message is issued.
.RE

.sp
.ne 2
.na
\fB\fBusb_reset\fR\fR
.ad
.sp .6
.RS 4n
Performs a software reset (re-enumeration) of the device. This is the
equivalent of removing the device and inserting it back again. The port on the
hub is power cycled if the hub supports power cycling of individual ports.
.sp
If the connected device is a hub, this function has the effect of resetting
that hub and any devices down the tree of which it is the root.
.sp
If any of these steps fail, the device is restored to its previous state and an
error message is issued.
.RE

.RE

.sp
.LP
State table: attachment points state versus commands:
.sp
.in +2
.nf
Valid states:
    empty/unconfigured         \(-> no device connected

    disconnected/unconfigured  \(-> logically disconnected,
                                  unavailable,
                                  devinfo node removed,
                                  device physically connected

    connected/unconfigured     \(-> logically connected,
                                  unavailable,
                                  devinfo node present

    connected/configured       \(-> connected, available
.fi
.in -2
.sp

.sp
.LP
The table below clarifies the state transitions resulting from actions or
commands:
.sp
.in +2
.nf
current state      operation           new state
-------------      ---------           ---------
empty/
unconfigured:
              device plugged in:     connected/configured or
                                     connected/unconfigured
                                     (if enumeration failed)
              device removed:        n/a
              cfgadm -c unconfigure: empty/unconfigured
              cfgadm -c configure:   empty/unconfigured
              cfgadm -c disconnect:  empty/unconfigured
                                     (no-op and error)

disconnected/
unconfigured:
              device plugged in:     n/a
              device removed:        empty/unconfigured
              cfgadm -c unconfigure: disconnected/unconfigured
              cfgadm -c configure:   connected/configured, or
                                     connected/unconfigured
                                     (if reenumeration failed)
             cfgadm -c disconnect:   disconnected/unconfigured

connected/unconfigured:
             device plugged in:      n/a
             device removed:         empty/unconfigured
             cfgadm -c unconfigure:  connected/unconfigured
             cfgadm -c configure:    connected/configured, or
                                     connected/unconfigured
                                     (if reenumeration failed)
             cfgadm -c disconnect:   disconnected/unconfigured

connected/configured:
             device plugged in:      n/a
             device removed:         empty/unconfigured or
                                     connected/configured,
                                     but with ap condition
                                     'unusable' if device
                                     was open when removed
             cfgadm -c unconfigure:  connected/unconfigured
             cfgadm -c configure:    connected/configured
             cfgadm -c disconnect:   disconnected/unconfigured
.fi
.in -2
.sp

.SH EXAMPLES
\fBExample 1 \fRListing the Status of All USB Devices
.sp
.LP
The following command lists the status of all \fBUSB\fR devices on the system:

.sp
.in +2
.nf
# cfgadm
Ap_Id           Type         Receptacle   Occupant     Condition
usb0/1          USB-hub      connected    configured   ok
usb0/2          unknown      empty        unconfigured ok
usb0/1.1        USB-storage  connected    configured   ok
usb0/1.2        unknown      empty        unconfigured ok
usb0/1.3        unknown      empty        unconfigured ok
usb0/1.4        USB-device connected    configured   ok
.fi
.in -2
.sp

.sp
.LP
Notice that \fBcfgadm\fR treats the \fBUSB-device\fR device at \fBap_id
usb0/1.4\fR as a single unit, since it cannot currently control individual
interfaces.

.LP
\fBExample 2 \fRListing the Status of a Port with No Device Plugged In
.sp
.LP
The following command lists the status of a port with no device plugged in:

.sp
.in +2
.nf
example# \fBcfgadm -l usb0/1.3\fR
Ap_Id           Type         Receptacle   Occupant     Condition
usb0/1.3        unknown      empty        unconfigured ok
.fi
.in -2
.sp

.LP
\fBExample 3 \fRListing the Status of the Same Port with a Device Plugged In
.sp
.LP
The following command lists the status of the same port after physically
plugging in a device that configures without problems:

.sp
.in +2
.nf
example# \fBcfgadm -l usb0/1.3\fR
Ap_Id           Type         Receptacle   Occupant     Condition
usb0/1.3        USB-hub      connected    configured   ok
.fi
.in -2
.sp

.LP
\fBExample 4 \fRUnconfiguring an Existing USB Device
.sp
.LP
The following command unconfigures the \fBUSB\fR device attached to
\fBusb0/1.3\fR, then displays the status of the \fBap_id\fR:

.sp
.in +2
.nf
example# \fBcfgadm -c unconfigure usb0/1.3\fR
Unconfigure the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
This operation suspends activity on the USB device
Continue (yes/no)?

Enter:

\fBy\fR

example# \fBcfgadm -l usb0/1.3\fR
Ap_Id           Type         Receptacle   Occupant     Condition
usb0/1.3        unknown      connected    unconfigured ok
.fi
.in -2
.sp

.LP
\fBExample 5 \fRUnconfiguring and Logically Disconnecting an Existing USB
Device
.sp
.LP
The following command unconfigures and logically disconnects a \fBUSB\fR device
attached to \fBusb0/1.3\fR:

.sp
.in +2
.nf
example# \fBcfgadm -c disconnect usb0/1.3\fR
Disconnect the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
This operation suspends activity on the USB device
Continue (yes/no)?

Enter:

\fBy\fR

example# \fBcfgadm -l usb0/1.3\fR
Ap_Id         Type         Receptacle     Occupant        Condition
usb0/1.3      unknown      disconnected   unconfigured    ok
.fi
.in -2
.sp

.sp
.LP
A \fBdisconnect\fR implies that \fBcfgadm\fR does an \fBunconfigure\fR first.
The receptacle status now shows \fBdisconnected\fR, even though the device is
still physically connected. In this case, a physical hotplug or using the
\fBcfgadm \fR\fB-c\fR \fBconfigure\fR on the \fBap_id\fR brings it back
on-line.

.LP
\fBExample 6 \fRConfiguring a Previously Unconfigured USB Device
.sp
.LP
The following command configures a \fBUSB\fR device that was previously
attached to \fBusb0/1.3\fR:

.sp
.in +2
.nf
example # \fBcfgadm -yc configure usb0/1.3\fR
example# \fBcfgadm -l usb0/1.3\fR
Ap_Id           Type         Receptacle   Occupant     Condition
usb0/1.3        unknown      connected    configured   ok
.fi
.in -2
.sp

.LP
\fBExample 7 \fRResetting a USB Device
.sp
.LP
The following command resets a \fBUSB\fR device:

.sp
.in +2
.nf
example# \fBcfgadm -x usb_reset usb0/1.3\fR
Reset the device: /devices/pci@0,0/pci8086,7112@7,2/hub@2:2.3
This operation suspends activity on the USB device
Continue (yes/no)?

Enter:

\fBy\fR
.fi
.in -2
.sp

.LP
\fBExample 8 \fRDisplaying Detailed Information About a USB Device
.sp
.LP
The following command displays detailed information about a \fBUSB\fR device.
This device shows the following \fBUSB\fR-specific information in
the '\fBInformation\fR' field:

.RS +4
.TP
.ie t \(bu
.el o
Manufacturer string: STMicroelectronics
.RE
.RS +4
.TP
.ie t \(bu
.el o
Product string: \fBSTLINK-V3\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
Serial number: 003C00174741500520383733
.RE
.RS +4
.TP
.ie t \(bu
.el o
Number of configurations supported: 1
.RE
.RS +4
.TP
.ie t \(bu
.el o
Configuration currently active: 0
.RE
.RS +4
.TP
.ie t \(bu
.el o
Configuration string descriptor for configuration 0: Default
.RE
.sp
.in +2
.nf
example# \fBcfgadm -lv usb2/1.2\fR
Ap_Id                 Receptacle   Occupant     Condition  Information
When         Type         Busy     Phys_Id
usb2/1.2     connected    configured   ok         Mfg: STMicroelectronics
Product: STLINK-V3  Serial: 003C00174741500520383733  NConfigs: 1  Config:
0  : Default Config
.fi
.in -2
.sp

.sp
.in +2
.nf
example# \fBcfgadm -l -s "cols=ap_id:info" usb2/1.2\fR
Ap_Id                         Information
usb2/1.2                      Mfg: STMicroelectronics  Product: STLINK-V3
Serial: 003C00174741500520383733  NConfigs: 1  Config: 0  : Default Config
.fi
.in -2
.sp

.LP
\fBExample 9 \fRDisplaying Detailed Information About All USB Devices
.sp
.LP
The following command displays detailed information about all \fBUSB\fR devices
on the system:

.sp
.in +2
.nf
example# \fBcfgadm -l -s "select=class(usb),cols=ap_id:info"\fR
Ap_Id            Information
usb1/3           Mfg: VIA Labs, Inc.           Product: USB2.0 Hub
Serial: <undef>  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/3.1         Mfg: STMicroelectronics  Product: STM32 STLink
Serial: 0668FF515754888367141334  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/3.2
usb1/3.3         Mfg: STMicroelectronics  Product: STLINK-V3
Serial: 003700303137511139383538  NConfigs: 1  Config: 0  : Default Config
usb1/3.4         Mfg: FTDI  Product: FT4232H MiniModule
Serial: FT51SZA7  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/4
usb1/5
usb1/6
usb1/7           Mfg: VIA Labs, Inc.           Product: USB3.0 Hub
Serial: <undef>  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/7.1
usb1/7.2
usb1/7.3
usb1/7.4
usb1/8
usb2/1           Mfg: <undef>  Product: <undef>  Serial: <undef>
NConfigs: 1  Config: 0  <no cfg str descr>
usb2/1.1         Mfg: ARM  Product: DAPLink CMSIS-DAP
Serial: 02360b000d96e4fc00000000000000000000000097969905  NConfigs: 1
Config: 0  <no cfg str descr>
usb2/1.2         Mfg: STMicroelectronics  Product: STLINK-V3
Serial: 003C00174741500520383733  NConfigs: 1  Config: 0  : Default Config
.fi
.in -2
.sp

.sp
.LP
Lines containing only an \fBap_id\fR are empty ports. These can be filtered
out. This example only lists \fBUSB\fR \fBap_id\fRs with connected devices, and
information about those devices.

.sp
.in +2
.nf
example# \fBcfgadm -l -s "select=class(usb),cols=ap_id:info" | grep Mfg\fR
usb1/3           Mfg: VIA Labs, Inc.           Product: USB2.0 Hub
Serial: <undef>  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/3.1         Mfg: STMicroelectronics  Product: STM32 STLink
Serial: 0668FF515754888367141334  NConfigs: 1  Config: 0  <no cfg str descr>
usb1/3.3         Mfg: STMicroelectronics  Product: STLINK-V3
Serial: 003700303137511139383538  NConfigs: 1  Config: 0  : Default Config
usb1/3.4         Mfg: FTDI  Product: FT4232H MiniModule
Serial: FT51SZA7  NConfigs: 1  Config: 0  <no cfg str descr>
.fi
.in -2
.sp

.LP
\fBExample 10 \fRListing Information About a Multi-configuration USB Device
.sp
.LP
The following example lists information about a multi-configuration \fBUSB\fR
device.

.sp
.LP
Notice the \fBNConfigs\fR field: the configurations available for this device
are \fB0\fR, \fB1\fR, and \fB2\fR (\fB0\fR to (\fIN\fR\fBConfigs-1\fR)).

.sp
.in +2
.nf
example# \fBcfgadm -l -s "cols=ap_id:info" usb1/3.3\fR
Ap_Id                          Information
usb1/3.3                       Mfg: STMicroelectronics  Product: STLINK-V3
Serial: 003700303137511139383538  NConfigs: 1  Config: 0  : Default Config
.fi
.in -2
.sp

.LP
\fBExample 11 \fRSetting the Current Configuration of a Multi-configuration USB
Device
.sp
.LP
The following example sets the current configuration of a multi-configuration
USB device:

.sp
.in +2
.nf
example# \fBcfgadm -o config=2 -x usb_config usb0/1.4\fR
Setting the device: /devices/pci@1f,2000/usb@1/device@3
to USB configuration 2
This operation suspends activity on the USB device
Continue (yes/no)?

Enter:

\fBy\fR

USB configuration changed successfully.
.fi
.in -2
.sp

.sp
.LP
The device path should be checked to ensure that the right instance of a device
is being referred to, in the case where multiple devices of the exact same type
are on the same bus. This information is available in the '\fBInformation\fR'
field.

.SH FILES
.ne 2
.na
\fB\fB/usr/lib/cfgadm/usb.so.1\fR\fR
.ad
.sp .6
.RS 4n
Hardware specific library for generic USB device administration
.RE

.SH SEE ALSO
.BR config_admin (3CFGADM),
.BR scsa2usb (4D),
.BR usba (4D),
.BR attributes (7),
.BR cfgadm (8)
.sp
.LP
Universal Serial Bus 1.1 Specification (\fBwww.usb.org\fR)
.sp
.LP
\fI\fR
.SH NOTES
\fBcfgadm\fR(8) can not unconfigure, disconnect, reset, or change the
configuration of any \fBUSB\fR device currently opened by any application.
These operations also fail on a hub if a device in its hierarchy is opened by
an application. See \fBscsa2usb\fR(4D) for unconfiguring a \fBUSB\fR
mass-storage device that is currently in use.
.sp
.LP
Only super-users can execute any functions on an attachment point. However, one
need not be a super-user to list the attachment points.