System Administration Commands cfgadmusb(1M)
NAME
cfgadmusb - USB hardware-specific commands for cfgadm
SYNOPSIS
/usr/sbin/cfgadm [-f] [-y -n] [-v] -c function apid...
/usr/sbin/cfgadm -f [-y -n] [-v] [-o hardwareoptions]
-x hardwarefunction apid...
/usr/sbin/cfgadm -v [-a] [-s listingoption]
[-l [apid aptype...]
/usr/sbin/cfgadm -v -h [apid]...
DESCRIPTION
The Universal Serial Bus (USB) hardware-specific library
/usr/lib/cfgadm/usb.so.1 provides the functionality for
administering USB devices via the cfgadm(1M) command. cfgadm
operates on attachment points. For details regarding attach-
ment points, refer to cfgadm(1M).
For USB administration, the only attachment points supported
are the ports of hubs attached to the USB bus.
Attachment points are named through attachment point IDs
(apids). The USB bus is hierarchical, so the apids are as
well. USB hubs have ports, numbered from 1 to n. All USB
apids consist of a string of the following form:
usbN/A[.B[.C[...]
where
N is the Nth USB host controller on the system,
A is port #A on the root (top) hub.
B is port #B of the hub plugged into port #A of the hub
above it.
C is port #C of the hub plugged into port #B of the hub
above it, and so forth.
For example, the first port on the root hub of USB con-
troller 0 (the only controller), has a logical apid:
SunOS 5.11 Last change: 1 Mar 2007 1
System Administration Commands cfgadmusb(1M)
usb0/1
Similarly, the second port on the first external hub plugged
into the first port on the root hub of the first USB con-
troller has a logical apid:
usb0/1.2
For example, if the apid is usb0/1.4.3.4, it represents
port 4 of the hub plugged into port 3 of the hub plugged
into port 4 of the hub plugged into port 1 of the root hub
of the first USB host controller on the system.
example# cfgadm -l
ApId 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
USB2.0 chips have one EHCI host USB2.0 host controller and a
number of companion USB 1.x host controllers (either OHCI or
UHCI host controllers).
When a USB2.0 device has been plugged in, it shows up on the
EHCI logical ports which might not have a 1 to 1 mapping to
external physical port numbers on the system. When a USB1.x
device is plugged in, the EHCI host controller reroutes the
device to a companion host controller and the device shows
up on the companion's logical port number.
The mapping of logical port numbers to physical port numbers
can get quite complicated. For example:
% cfgadm
ApId Type Receptacle Occupant Condition
c0 scsi-bus connected configured unknown
usb0/1 usb-mouse connected configured ok
usb0/2 usb-kbd connected configured ok
SunOS 5.11 Last change: 1 Mar 2007 2
System Administration Commands cfgadmusb(1M)
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
In this example usb0 is the onboard USB 1.x host controller.
usb1 and usb2 are companion OHCI USB1.x host controllers and
usb3 is an EHCI USB2.0 host controller.
The following table shows the somewhat confusing routing for
this USB2.0 chip:
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
Unfortunately, the exact routing can often only be deter-
mined by experimentation.
The receptacle states for attachment points at the USB port
have the following meanings:
SunOS 5.11 Last change: 1 Mar 2007 3
System Administration Commands cfgadmusb(1M)
connected
USB port is powered on and enabled. A USB device is
plugged in to the port. The device is logically con-
nected to the USB bus.
disconnected
USB port is powered on and enabled. A USB device is
plugged into the port. The device has been logically
disconnected from the USB bus (using the cfgadm -c
disconnect command).
empty
USB port is powered on, but no device is plugged in to
it.
The occupant states for devices at USB port attachment
points at the USB port have the following meanings:
configured
The USB device at the USB port is configured and usable
by Solaris.
unconfigured
The USB device at the USB port was explicitly off-lined
using cfgadm -c unconfigure, or was not successfully
configured for use with Solaris, for example, having no
driver or a device problem.
The attachment point conditions are:
ok
Normal state - ready for use.
failing
Not used.
SunOS 5.11 Last change: 1 Mar 2007 4
System Administration Commands cfgadmusb(1M)
failed
Not used.
unusable
The user has physically removed a device while an appli-
cation had the device open (there might be outstanding
I/O). 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.
If the original device cannot be reinserted into the
port, see the for instructions for clearing this
attachment point condition.
unknown
Not used.
A USB device can be hotplugged or hotunplugged at any time,
and the system detects the event and takes the appropriate
action.
It is not necessary to transition a receptacle to the
disconnected state before removing its device from the USB.
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).
OPTIONS
cfgadm defines several types of operations. These operations
include invoking configuration state changes (-c), invoking
hardware-specific functions (-x), and obtaining configura-
tion administration help messages (-h).
If any of these operations fail, the device and attachment
point might not be in the expected state. Use the cfgadm -l
command to display the device's current status.
All other options have the same meaning as defined in
cfgadm(1M).
SunOS 5.11 Last change: 1 Mar 2007 5
System Administration Commands cfgadmusb(1M)
The following options are supported:
-c function
The following generic commands are defined for the USB
hardware specific library. The following configuration
state change operations are supported:
configure
If there is a USB 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 connect (reverse of disconnect) 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.
disconnect
Performs an unconfigure on the apid (if it is not
already unconfigured), and then transitions the
receptacle to the disconnected state, even though a
device is still be plugged into the port. Issuing a
cfgadm -c configure, or physically hotplugging the
device, brings the device back to the connected
receptacle state, and to the configured occupant
state, assuming a driver can be found and there are
no problems enumerating and configuring the device.
unconfigure
Makes the device plugged into the port unusable by
Solaris (offline it). If successful, cfgadm reports
this apid's occupant state as unconfigured. Issuing
a configure to the apid (if successful) brings its
occupant back to the configured (online) condition,
as it physically hotplugging the device on the port.
-f
Not supported.
-h apid
SunOS 5.11 Last change: 1 Mar 2007 6
System Administration Commands cfgadmusb(1M)
USB specific help can be obtained by using the help
option with any USB attachment point.
-l[v]
The -l option works as described in cfgadm(1M). When
paired with the -v option, the Information field con-
tains the following USB-specific information:
o Mfg: manufacturer string (iManufacturer)
o Product: product string (iProduct)
o NConfigs: total number of configurations the
device supports (bNumConfigurations).
o Config: current configuration setting in
decimal (configuration index, not configuration
value).
o The configuration string descriptor for the
current configuration (iConfiguration)
See the Universal Serial Bus specification for a
description of these fields.
-o hardwareoptions
Hardware options are only supported for the hardware-
specific command, -x usbconfig. See the description of
that command below for an explanation of the options
available.
-s listingoptions
Attachment points of class USB can be listed by using
the select sub-option. See cfgadm(1M).
-x hardwarefunction
The following hardware-specific functions are defined:
usbconfig -o config=n
This command requires the mandatory config value to
be specified using the -o option.
Sets the USB configuration of a multi-configuration
USB device at apid to configuration index n. The
SunOS 5.11 Last change: 1 Mar 2007 7
System Administration Commands cfgadmusb(1M)
device is set to this configuration henceforth and
this setting persists across reboots, hot-removes,
and unconfigure/configure of the device.
Valid values of n range from 0 to (Nconfigs -1). The
device is reset by a disconnect followed by a con-
figure. The configure causes the device to be con-
figured to the new configuration setting.
If any of these steps fail, the configuration file
and the device are restored to their previous state
and an error message is issued.
usbreset
Performs a software reset (re-enumeration) of the
device. This is the equivalent of removing the dev-
ice and inserting it back again. The port on the hub
is power cycled if the hub supports power cycling of
individual ports.
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.
If any of these steps fail, the device is restored
to its previous state and an error message is
issued.
State table: attachment points state versus commands:
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
SunOS 5.11 Last change: 1 Mar 2007 8
System Administration Commands cfgadmusb(1M)
The table below clarifies the state transitions resulting
from actions or commands:
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
EXAMPLES
Example 1 Listing the Status of All USB Devices
SunOS 5.11 Last change: 1 Mar 2007 9
System Administration Commands cfgadmusb(1M)
The following command lists the status of all USB devices on
the system:
# cfgadm
ApId 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
Notice that cfgadm treats the USB-device device at apid
usb0/1.4 as a single unit, since it cannot currently control
individual interfaces.
Example 2 Listing the Status of a Port with No Device
Plugged In
The following command lists the status of a port with no
device plugged in:
example# cfgadm -l usb0/1.3
ApId Type Receptacle Occupant Condition
usb0/1.3 unknown empty unconfigured ok
Example 3 Listing the Status of the Same Port with a Device
Plugged In
The following command lists the status of the same port
after physically plugging in a device that configures
without problems:
example# cfgadm -l usb0/1.3
ApId Type Receptacle Occupant Condition
usb0/1.3 USB-hub connected configured ok
Example 4 Unconfiguring an Existing USB Device
SunOS 5.11 Last change: 1 Mar 2007 10
System Administration Commands cfgadmusb(1M)
The following command unconfigures the USB device attached
to usb0/1.3, then displays the status of the apid:
example# cfgadm -c unconfigure usb0/1.3
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:
y
example# cfgadm -l usb0/1.3
ApId Type Receptacle Occupant Condition
usb0/1.3 unknown connected unconfigured ok
Example 5 Unconfiguring and Logically Disconnecting an
Existing USB Device
The following command unconfigures and logically disconnects
a USB device attached to usb0/1.3:
example# cfgadm -c disconnect usb0/1.3
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:
y
example# cfgadm -l usb0/1.3
ApId Type Receptacle Occupant Condition
usb0/1.3 unknown disconnected unconfigured ok
A disconnect implies that cfgadm does an unconfigure first.
The receptacle status now shows disconnected, even though
the device is still physically connected. In this case, a
physical hotplug or using the cfgadm -c configure on the
apid brings it back on-line.
Example 6 Configuring a Previously Unconfigured USB Device
SunOS 5.11 Last change: 1 Mar 2007 11
System Administration Commands cfgadmusb(1M)
The following command configures a USB device that was pre-
viously attached to usb0/1.3:
example # cfgadm -yc configure usb0/1.3
example# cfgadm -l usb0/1.3
ApId Type Receptacle Occupant Condition
usb0/1.3 unknown connected configured ok
Example 7 Resetting a USB Device
The following command resets a USB device:
example# cfgadm -x usbreset usb0/1.3
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:
y
Example 8 Displaying Detailed Information About a USB Device
The following command displays detailed information about a
USB device. This device shows the following USB-specific
information in the 'Information' field:
o Manufacturer string: Iomega
o Product string: USB Zip 250
o Number of configurations supported: 1
o Configuration currently active: 0
o Configuration string descriptor for configuration
0: Default
example# cfgadm -lv usb0/1.5
ApId Receptacle Occupant Condition Information
When Type Busy PhysId
usb0/1.5 connected configured ok Mfg:"Io
mega" Product:"USB Zip 250" NConfigs:1 Config:0 : Default
SunOS 5.11 Last change: 1 Mar 2007 12
System Administration Commands cfgadmusb(1M)
example# cfgadm -l -s "cols=apid:info" usb0/1.5
ApId Information
usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
NConfigs:1 Config:0 : Default
Example 9 Displaying Detailed Information About All USB Dev-
ices
The following command displays detailed information about
all USB devices on the system:
example# cfgadm -l -s "select=class(usb),cols=apid:info"
ApId Information
usb0/1 Mfg: Product:
NConfigs:1 Config:0
usb0/2
usb0/1.1 Mfg: Product:
NConfigs:1 Config:0
usb0/1.2
usb0/1.3
usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
NConfigs:3 Config:1 : V.90 Analog Modem
usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
NConfigs:1 Config:0 : Default
usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR
USB"NConfigs:1 Config:0
usb0/1.7
Lines containing only an apid are empty ports. These can be
filtered out. This example only lists USB apids with con-
nected devices, and information about those devices.
example# cfgadm -l -s "select=class(usb),cols=apid:info" grep Mfg
usb0/1 Mfg: Product:
NConfigs:1 Config:0
usb0/1.1 Mfg: Product:
NConfigs:1 Config:0
usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
NConfigs:3 Config:1 : V.90 Analog Modem
usb0/1.5 Mfg:"Iomega" Product:"USB Zip 250"
NConfigs:1 Config:0 : Default
usb0/1.6 Mfg:"SOLID YEAR" Product:"SOLID YEAR USB"
Config:0
SunOS 5.11 Last change: 1 Mar 2007 13
System Administration Commands cfgadmusb(1M)
Example 10 Listing Information About a Multi-configuration
USB Device
The following example lists information about a multi-
configuration USB device.
Notice the NConfigs field: the configurations available for
this device are 0, 1, and 2 (0 to (NConfigs-1)).
example# cfgadm -l -s "cols=apid:info" usb0/1.4
ApId Information
usb0/1.4 Mfg:"Wizard" Product:"Modem/ISDN"
NConfigs:3 Config:1 V.90 Analog Modem"
Example 11 Setting the Current Configuration of a Multi-
configuration USB Device
The following example sets the current configuration of a
multi-configuration USB device:
example# cfgadm -o config=2 -x usbconfig usb0/1.4
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:
y
USB configuration changed successfully.
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 'Information' field.
FILES
/usr/lib/cfgadm/usb.so.1
SunOS 5.11 Last change: 1 Mar 2007 14
System Administration Commands cfgadmusb(1M)
Hardware specific library for generic USB device
administration
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsl
SEE ALSO
cfgadm(1M), configadmin(3CFGADM), attributes(5),
scsa2usb(7D), usba(7D)
Universal Serial Bus 1.1 Specification (www.usb.org)
NOTES
cfgadm(1M) can not unconfigure, disconnect, reset, or change
the configuration of any USB 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
scsa2usb(7D) for unconfiguring a USB mass-storage device
that is currently in use.
Only super-users can execute any functions on an attachment
point. However, one need not be a super-user to list the
attachment points.
SunOS 5.11 Last change: 1 Mar 2007 15
|
