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 attachment 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 (ap_ids). The USB bus is hierarchical, so the ap_ids are as well. USB hubs have ports, numbered from 1 to n. All USB ap_ids 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 controller 0 (the only controller), has a logical ap_id:

usb0/1

Similarly, the second port on the first external hub plugged into the first port on the root hub of the first USB controller has a logical ap_id:

usb0/1.2

For example, if the ap_id 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 bus controller on the system.

The following listing of USB attachment points in the system includes all attachment points for USB ports, even if the port is empty (no device plugged in):

example# cfgadm -l
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-composit connected    configured   ok

The receptacle states for attachment points at the USB port have the following meanings:

connected

USB port is powered on and enabled. A USB device is plugged in to the port. The device is logically connected 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.

failed

Not used.

unusable

The user has physically removed a device while an application had the device open (there may 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 System Administration Guide, Volume 1 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 volume manager (see vold(1M)) or some other application).

cfgadm defines several types of operations. These operations include invoking configuration state changes (-c), invoking hardware-specific functions (-x), and obtaining configuration administration help messages (-h).

If any of these operations fail, the device and attachment point may 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).

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 ap_id (if it is not already unconfigured), and then transitions the receptacle to the disconnected state, even though a device will still be plugged into the port. Issuing a cfgadm -c configure, or physically hotplugging the device, will bring 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 will now report this ap_id's occupant state as unconfigured. Issuing a configure to the ap_id (if successful) will bring its occupant back to the configured (online) condition, as will physically hotplugging the device on the port.

-f

Not supported.

-h ap_id

USB specific help may 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 contains the following USB-specific information:

• Mfg: manufacturer string (iManufacturer)
• Product: product string (iProduct)
• NConfigs: total number of configurations the device supports (bNumConfigurations).
• Config: current configuration setting in decimal (configuration index, not configuration value).
• The configuration string descriptor for the current configuration (iConfiguration)

See the Universal Serial Bus specification for a description of these fields.

-o hardware_options

Hardware options are only supported for the hardware-specific command, -x usb_config. See the description of that command below for an explanation of the options available.

-s listing_options

Attachment points of class USB may be listed by using the select sub-option. See cfgadm(1M).

-x hardware_function

The following hardware-specific functions are defined:

usb_config -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 ap_id to configuration index n. The 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 configure. The configure causes the device to be configured 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.

usb_reset

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 will be 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

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

/usr/lib/cfgadm/usb.so.1

Hardware specific library for generic USB device administration

See attributes(5) for descriptions of the following attributes:

cfgadm(1M), vold(1M), config_admin(3CFGADM), attributes(5), scsa2usb(7D), usba(7D)

Universal Serial Bus 1.1 Specification (www.usb.org)

System Administration Guide, Volume 1

cfgadm(1M) can not unconfigure, disconnect, reset, or change the configuration of any USB device currently opened by vold(1M) or any other 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 being used by vold(1M).

Only super-users can execute any functions on an attachment point. However, one need not be a super-user to list the attachment points.