Chapter 8 Using USB Devices (Tasks)

This chapter provides step-by-step instructions for using USB devices in the Solaris environment.

For information on the procedures associated with using USB devices, see the following:

• Managing USB Devices in the Solaris Environment (Roadmap)

• Using USB Mass Storage Devices (Task Map)

• Hot-Plugging USB Devices (Task Map)

• Using USB Audio Devices (Task Map)

• Hot-Plugging USB Devices With the cfgadm Command (Task Map)

For overview information about using USB devices, see Chapter 7, Using USB Devices (Overview).

Managing USB Devices in the Solaris Environment (Roadmap)

Use this map to identify all the tasks for managing USB devices in the Solaris environment. Each task points to a series of additional tasks such as using USB devices, hot-plugging USB devices, or adding USB audio devices.

Using USB Mass Storage Devices (Task Map)

Using USB Mass Storage Devices

For up-to-date information on using USB mass storage devices in this Solaris release, see USB Mass Storage Devices.

Starting in the Solaris 9 release, removable mass storage devices such as USB CD-RWs, hards disks, DVDs, digital cameras, Zip, Peerless, SmartMedia, CompactFlash, ORB, and USB diskette devices are supported.

For a complete list of USB devices that are supported in the Solaris environment, see http://www.sun.com/io_technologies/USB.html.

These devices can be managed with or without volume management. For information on managing devices with volume management, see vold(1M).

Using USB Diskette Devices

USB diskette devices appear as removable media devices like other USB devices. USB diskette devices are not managed by the fd (floppy) driver. Applications that issue ioctl(2) calls intended for the fd (native floppy) driver will fail. Applications that issue only read(2) and write(2) calls will succeed. Other applications, such as SunPCI and rmformat, will also succeed.

CDE's File Manager does not fully support USB diskettes at this time. However, you can open, rename, and format diskettes that contain a UFS file system from File Manager's Removable Media Manager. You can only open diskettes that contain a PCFS file system from the Removable Media Manager. If a diskette contains either type of file system, you can successfully drag and drop files between the diskette and File Manager.

Volume management (vold) sees the USB diskette device as a SCSI removable media device. Volume management makes the device available for access under the /rmdisk directory.

For more information on how to use USB diskette devices, see Chapter 1, Managing Removable Media (Overview).

Using Non-Compliant USB Mass Storage Devices

Some devices might be supported by the USB mass storage driver even though they do not identify themselves as compliant with the USB mass storage class or identify themselves incorrectly. The scsa2usb.conf file contains an attribute-override-list that lists the vendor ID, product ID, and revision for matching mass storage devices, as well as fields for overriding the default device attributes. The entries in this list are commented out by default, and can be copied and uncommented to enable support of particular devices.

If you connect a USB mass storage device to a system running this Solaris release and the system is unable to use it, you can check the /kernel/drv/scsa2usb.conf file to see if there is a matching, commented entry for this device. Follow the information given in the scsa2usb.conf file to see if a particular device can be supported by using the override information. For a listing of recommended USB mass storage devices, go to http://www.sun.com/io_technologies/USB.html.

For more information, see scsa2usb(7D).

Preparing to Use a USB Mass Storage Device With vold Running

If you are running the Solaris Common Desktop Environment (CDE), USB removable mass storage devices are managed by the Removable Media Manager component of the CDE File Manager. For more information on the CDE File Manager, see dtfile(1).

You must include the /usr/dt/man directory in your MANPATH variable to display the man pages that are listed in this section. You must also have the /usr/dt/bin directory in your path and have CDE running to use these commands, or have a DISPLAY variable set to use these commands remotely.

The following table identifies the commands that Removable Media Manager uses to manage storage devices from the CDE environment.

After the USB device is formatted, it is usually mounted under the /rmdisk/label directory. For more information on configuring removable storage devices, see rmmount.conf(4) or vold.conf(4).

The device nodes are created under the /vol/dev directory. For more information, see scsa2usb(7D).

The following procedures describe how to manage USB mass storage devices without vold running. The device nodes are created under the /dev/rdsk directory for character devices and under the /dev/dsk directory for block devices. Device links are created when the devices are hot-plugged. For more information, see scsa2usb(7D).

How to Prepare to Use USB Mass Storage Devices Without vold Running

You can use USB mass storage devices without the volume management (vold) running. Stop vold by issuing the following command:

# /etc/init.d/volmgt stop

Or, use the following procedure to keep vold running, but do not register the USB mass storage devices with vold.

Steps

1. Become superuser.

2. Remove volume manager registration of USB mass storage devices by commenting the following line in the /etc/vold.conf file, like this:

   # use rmdisk drive /dev/rdsk/c*s2 dev_rmdisk.so rmdisk%d

3. After this line is commented, restart vold.

   # /etc/init.d/volmgt start

   ---

   Caution –

   If you comment out this line and other SCSI or ATAPI Zip, Peerless or other removable devices are in the system, vold registration for these devices would be disabled as well.

   ---

   For more information, see vold.conf(4).

How to Display USB Device Information (prtconf)

Use the prtconf command to display information about USB devices.

$ prtconf
        usb, instance #0
                 hub, instance #2
                     device, instance #8
                         interface (driver not attached)
                     printer (driver not attached)
                     mouse, instance #14
                     device, instance #9
                         keyboard, instance #15
                         mouse, instance #16
                     storage, instance #7
                         disk (driver not attached)
                     communications, instance #10
                         modem (driver not attached)
                         data (driver not attached)
                 storage, instance #0
                     disk (driver not attached)
                 storage, instance #1
                     disk (driver not attached)

You can use the prtconf command's -D option to display additional driver information. This information can be used to tell which ports and devices are being driven by the USBA 1.0 framework on SPARC systems, as displayed in the following example:

$ prtconf -D
.
.
.
SUNW,Sun-Blade-1500
.
.
.
1 pci, instance #0 (driver name: pcisch) 
           isa, instance #0 (driver name: ebus)
.
.
.
2 usb, instance #0 (driver name: ohci)
           usb, instance #1 (driver name: ohci)
.
.
.
3 pci, instance #0 (driver name: pci_pci)
4 usb, instance #0 (driver name: usba10_ohci)
            usb, instance #1 (driver name: usba10_ohci)
            usb, instance #0 (driver name: usba10_ehci)
                storage, instance #9 (driver name: usba10_scsa2usb)
                    disk, instance #9 (driver name: usb_sd)
            firewire, instance #0 (driver name: hci1394)
.
.
.

In the output above, note the following configuration characteristics:

• PCI card ports are distinguished by the number of hierarchical pci nodes in the output above their usb nodes.

  PCI card ports (4) fall under two hierarchical pci nodes 1 and 3 because they are driven through both the motherboard and the PCI card. Onboard ports (2) fall under a single PCI node (1) because they are one hardware architectural layer closer to the main system bus.

• The name of a driver associated with a device node indicates which framework is directing the device and the port to which the device is attached. The drivers for all USB instances of (4) begin with usba10, indicating that the USBA 1.0 framework is managing those ports and the devices attached to them. Only those ports can support USB 2.0 devices at high speed.

How to Format a USB Mass Storage Device Without vold Running

USB mass storage devices, as all others used by the Solaris operating system, must be formatted and contain a file system before they can be used. USB mass storage devices, including diskettes, support both PCFS and UFS file systems. Be sure the disk is formatted before putting either a PCFS or UFS file system on it.

Steps

1. See How to Prepare to Use USB Mass Storage Devices Without vold Running for information on disabling vold.

2. (Optional) Add the USB diskette device to your system.

   For information on hot-plugging USB devices, see:

   • Using USB Audio Devices (Task Map)

   • Hot-Plugging USB Devices With the cfgadm Command (Task Map)

3. (Optional) Identify the diskette device.

   For example:

   # cd /dev/rdsk # devfsadm -C # ls -l c*0 | grep usb lrwxrwxrwx 1 root root 55 Mar 5 10:35 c2t0d0s0 -> ../../devices/pci@1f,0/usb@c,3/storage@3/disk@0,0:a,raw

   In this example, the diskette device is c2t0d0s0.

4. Insert a diskette into the diskette drive.

5. Format the diskette.

   % rmformat -Flong raw-device

   For example:

   % rmformat -Flong /dev/rdsk/c2t0d0s0

6. Determine the file system type and select one of the following:

   1. Create a PCFS file system.

      # mkfs -F pcfs -o nofdisk,size=size raw-device

      Specify the -size option in 512–byte blocks.

      The following example shows how to create a PCFS file system on a 1.4 Mbyte diskette.

      # mkfs -F pcfs -o nofdisk,size=2880 /dev/rdsk/c4t0d0s0

      The following example shows how to create a UFS file system on a 100 Mbyte Zip drive.

      # mkfs -F pcfs -o nofdisk,size=204800 /dev/rdsk/c5t0d0s0

      This command can take several minutes to complete.

   2. Create a UFS file system.

      # newfs raw-device

      For example:

      # newfs /dev/rdsk/c4t0d0s0

      ---

      Note –

      UFS file system overhead consumes a significant portion of space on a diskette, due to a diskette's limited storage capacity.

      ---

How to Mount or Unmount a USB Mass Storage Device With vold Running

Steps

1. Display device aliases for all removable mass storage devices, including USB mass storage devices.

   $ eject -n . . . cdrom0 -> /vol/dev/rdsk/c0t6d0/audio_cd (Generic CD device) zip0 -> /vol/dev/rdsk/c1t0d0/zip100 (USB Zip device) zip1 -> /vol/dev/rdsk/c2t0d0/fat32 (USB Zip device) rmdisk0 -> /vol/dev/rdsk/c5t0d0/unnamed_rmdisk (Peerless, HD or floppy) rmdisk1 -> /vol/dev/rdsk/c4t0d0/clik40 (Generic USB storage)

2. Select one of the following to mount or unmount a USB mass storage device.

   1. Mount a USB mass storage device by using the device aliases listed previously.

      $ volrmmount -i device-alias

      This example shows how to mount a USB Zip drive (/rmdisk/zip0).

      $ volrmmount -i zip0

   2. Unmount a USB mass storage device.

      $ volrmmount -e device-alias

      This example shows how to unmount a USB Zip drive (/rmdisk/zip0).

      $ volrmmount -e zip0

3. Eject a USB device from a generic USB drive.

   $ eject device-alias

   For example:

   $ eject rmdisk0

   ---

   Note –

   The eject command also unmounts the device if the device is not unmounted already. The command also terminates any active applications that access the device.

   ---

How to Mount or Unmount a USB Mass Storage Device Without vold Running

Steps

1. See How to Prepare to Use USB Mass Storage Devices Without vold Running for information on disabling vold.

2. Become superuser.

3. (Optional) Identify the diskette device.

   For example:

   # cd /dev/rdsk # devfsadm -C # ls -l c*0 | grep usb lrwxrwxrwx 1 root root 55 Mar 5 10:35 c2t0d0s0 -> ../../devices/pci@1f,0/usb@c,3/storage@3/disk@0,0:a,raw

   In this example, the diskette device is c2t0d0s0.

4. Select one of the following to mount or unmount a USB mass storage device.

   1. Mount a USB mass storage device.

      # mount [ -F fstype ] block-device mount-point

      This example shows how to mount a device with a UFS file system.

      # mount /dev/dsk/c1t0d0s2 /mnt

      This example shows how to mount a device with a PCFS file system.

      # mount -F pcfs /dev/dsk/c1t0d0s0:c /mnt

      This example shows how to mount a CD with a read-only HSFS file system.

      # mount -F hsfs -o ro /dev/dsk/c1t0d0s2 /mnt

   2. Unmount a USB mass storage device.

      First, be sure no one is using the file system on the device.

      For example:

      # fuser -c -u /mnt # umount /mnt

   3. Eject the device.

      # eject /dev/[r]dsk/cntndnsn

      For example:

      # eject /dev/rdsk/c1t0d0s2

Disabling Specific USB Drivers

You can disable specific types of USB devices by disabling their client driver. For example, USB printers can be disabled by disabling the usbprn driver that directs them. Disabling usbprn does not affect other kinds of devices, such as USB storage devices.

Be careful that device types are disabled on both frameworks. You cannot disable device types on one framework only. The following table identifies some USB device types and their corresponding drivers.

If you disable a driver for a USB device that is still connected to the system, you will see a console message similar to the following:

usba10: WARNING: usba:    no driver found for device name

How to Disable Specific USB Drivers

Steps

1. Become superuser.

2. Record the driver aliases that you are about to remove.

   # cp /etc/driver_aliases /etc/driver_aliases.orig

3. Identify the specific USB driver alias name.

   For example:

   # grep usbprn /etc/driver_aliases usbprn "usbif,class7.1.1" usbprn "usbif,class7.1.2"

4. Remove the driver alias entry.

   For example:

   # update_drv -d -i '"usbif,class7.1.1"' usbprn # update_drv -d -i '"usbif,class7.1.2"' usbprn

5. Reboot the system.

   # init 6

How to Remove Unused USB Device Links

Use this procedure if a USB device is removed while the system is powered off. It is possible that removing the USB device while the system is powered off will leave device links for devices that do not exist.

Steps

1. Become superuser.

2. Close all applications that might be accessing the device.

3. Remove the unused links for a specific USB class.

   For example:

   # devfsadm -C -c audio

   Or, just remove the dangling links:

   # devfsadm -C

Hot-Plugging USB Devices (Task Map)

Hot-plugging a device means the device is added or removed without shutting down the operating system or powering off the system. All USB devices are hot-pluggable.

When you hot-plug a USB device, the device is immediately seen in the system's device hierarchy, as displayed in the prtconf command output. When you remove a USB device, the device is removed from the system's device hierarchy, unless the device is in use.

If the USB device is in use when it is removed, the hot-plug behavior is a little different. If a device is in use when it is unplugged, the device node remains, but the driver controlling this device stops all activity on the device. Any new I/O activity issued to this device is returned with an error.

In this situation, the system prompts you to plug in the original device. If the device is no longer available, stop the applications. After a few seconds, the port will become available again.

Data integrity might be impaired if you remove an active or open device. Always close the device before removing, except the console keyboard and mouse, which can be moved while active.

How to Add a USB Mass Storage Device With vold Running

This procedure describes how to add a USB device with vold running.

Steps

1. Connect the USB mass storage device.

2. Instruct vold to scan for new devices.

   # touch /etc/vold.conf

3. Restart vold.

   # pkill -HUP vold

4. Verify that the device has been added.

   $ ls device-alias

   For more information on volume management device names, see Chapter 1, Managing Removable Media (Overview).

How to Add a USB Mass Storage Device Without vold Running

This procedure describes how to add a USB device without vold running.

Steps

1. If needed, see How to Prepare to Use USB Mass Storage Devices Without vold Running for information on disabling vold.

2. Connect the USB mass storage device.

3. Verify that the USB device has been added.

   Locate the USB disk device links, which may be among device links of non-USB storage devices, as follows:

   $ cd /dev/rdsk $ ls -l c*0 | grep usb lrwxrwxrwx 1 root root 67 Apr 30 15:12 c1t0d0s0 -> ../../devices/pci@1f,0/pci@5/pci@0/usb@8,2/storage@1/disk@0,0:a,raw

How to Remove a USB Mass Storage Device With vold Running

The following procedure uses a Zip drive as an example of removing a USB device with vold running.

Steps

1. Stop any active applications that are using the device.

2. Unmount the device.

   For example:

   $ volrmmount -e zip0

3. Eject the device.

   For example:

   $ eject zip0

4. Become superuser and stop vold.

   # /etc/init.d/volmgt stop

5. Remove the USB mass storage device.

6. Start vold.

   # /etc/init.d/volmgt start

How to Remove a USB Mass Storage Device Without vold Running

This procedure describes how to remove a USB device without vold running.

Steps

1. If needed, see How to Prepare to Use USB Mass Storage Devices Without vold Running for information on disabling vold.

2. Become superuser.

3. Stop any active applications that are using the device.

4. Remove the USB device.

   1. Unmount the device.

      For example:

      # umount /mnt

   2. Remove the device.

How to Add a USB Camera

Use this procedure to add a USB camera.

Steps

1. Become superuser.

2. Plug in and turn on the USB camera.

   The system creates a logical device for the camera. After the camera is plugged in, output is written to the /var/adm/messages file to acknowledge the device's connection. The camera is seen as a storage device to the system.

3. Examine the output that is written to the /var/adm/messages file.

   Examining this output enables you to determine which logical device was created so that you can then use that device to access your images. The output will look similar to the following:

   # more /var/adm/messages Jul 15 09:53:35 buffy usba: [ID 349649 kern.info] OLYMPUS, C-3040ZOOM, 000153719068 Jul 15 09:53:35 buffy genunix: [ID 936769 kern.info] scsa2usb1 is /pci@0,0/pci925,1234@7,2/storage@2 Jul 15 09:53:36 buffy scsi: [ID 193665 kern.info] sd3 at scsa2usb1: target 0 lun 0

   Match the device with a mountable /dev/dsk link entry, by doing the following:

   # ls -l /dev/dsk/c*0 | grep /pci@0,0/pci925,1234@7,2/storage@2 lrwxrwxrwx 1 root root 58 Jul 15 2002 c3t0d0p0 -> ../../devices/pci@0,0/pci925,1234@7,2/storage@2/disk@0,0:a

4. Mount the USB camera file system.

   The camera's file system is most likely a PCFS file system. In order to mount the file system on the device created, the slice that represents the disk must be specified. The slice is normally s0 for a SPARC system, and p0 for an x86 system.

   For example, to mount the file system on an x86 system, execute the following command:

   # mount -F pcfs /dev/dsk/c3t0d0p0:c /mnt

   To mount the file system on a SPARC system, execute the following command:

   # mount -F pcfs /dev/dsk/c3t0d0s0:c /mnt

   For information on mounting file systems, see Chapter 17, Mounting and Unmounting File Systems (Tasks).

   For information on mounting different PCFS file systems, see mount_pcfs(1M).

5. Verify that the image files are available.

   For example:

   # ls /mnt/DCIM/100OLYMP/ P7220001.JPG* P7220003.JPG* P7220005.JPG* P7220002.JPG* P7220004.JPG* P7220006.JPG*

6. View and manipulate the image files created by the USB camera.

   # /usr/dt/bin/sdtimage P7220001.JPG &

7. Unmount the file system before disconnecting the camera.

   For example:

   # umount /mnt

8. Turn off and disconnect the camera.

Using USB Audio Devices (Task Map)

Using USB Audio Devices

This Solaris release provides USB audio support that is implemented by a pair of cooperating drivers, usb_ac and usb_as. The audio control driver, usb_ac, is a USBA (Solaris USB Architecture) compliant client driver that provides the controlling interface to user applications. The audio streaming driver, usb_as, is provided to process audio data messages during play and record. It sets sample frequency and precision, and encodes requests from the usb_ac driver. Both drivers comply to the USB audio class 1.0 specification.

Some audio devices can set volume under software control. A STREAMS module, usb_ah, is pushed on top of the HID driver for managing this function.

Solaris supports USB audio devices that are play-only, record-only, or record and play. Hot-plugging of USB audio devices is supported.

• USB audio devices are supported on SPARC Ultra and x86 platforms that have USB connectors.

• USB audio devices that are supported in the Solaris 8 10/01, Solaris 8 2/02, or Solaris 9 releases must support a fixed 44100 or 48000 Hz sampling frequency to play or record.

• For fully supported audio data format information, see usb_ac(7D).

The primary audio device is /dev/audio. You can verify that /dev/audio is pointing to USB audio by using the following command:

% mixerctl
Device /dev/audioctl:
  Name    = USB Audio
  Version = 1.0
  Config  = external

Audio mixer for /dev/audioctl is enabled

After you connect your USB audio devices, you access them with the audioplay and audiorecord command through the /dev/sound/N device links.

Note that the /dev/audio and /dev/sound/N devices can refer to speakers, microphones, or combo devices. If you refer to the incorrect device type, the command will fail. For example, the audioplay command will fail if you try to use it with a microphone.

You can select a specific default audio device for most Sun audio applications, such as audioplay and audiorecord, by setting the AUDIODEV shell variable or by specifying the -d option for these commands. However, setting AUDIODEV does not work for third-party applications that have /dev/audio hardcoded as the audio file.

When you plug in a USB audio device, it automatically becomes the primary audio device, /dev/audio, unless /dev/audio is in use. For instructions on changing /dev/audio from onboard audio to USB audio and vice versa, refer to How to Change the Primary USB Audio Device, and usb_ac(7D).

Hot-Plugging Multiple USB Audio Devices

If a USB audio device is plugged into a system, it becomes the primary audio device, /dev/audio. It remains the primary audio device even after the system is rebooted. If additional USB audio devices are plugged in, the last one becomes the primary audio device.

For additional information on troubleshooting USB audio device problems, see usb_ac(7D).

How to Add USB Audio Devices

Use the following procedure to add USB audio devices.

Steps

1. Plug in the USB speaker.

   The primary audio device, /dev/audio, points to the USB speaker.

   % ls -l /dev/audio lrwxrwxrwx 1 root root 10 Feb 13 08:46 /dev/audio -> usb/audio0

2. (Optional) Remove the speaker. Then plug it back in.

   If you remove the speaker, the /dev/audio device reverts back to onboard audio.

   % ls -l /dev/audio lrwxrwxrwx 1 root root 7 Feb 13 08:47 /dev/audio -> sound/0

3. Add a USB microphone.

   % ls -l /dev/audio lrwxrwxrwx 1 root root 10 Feb 13 08:54 /dev/audio -> usb/audio1

How to Identify Your System's Primary Audio Device

This procedure assumes that you have already connected the USB audio devices.

Step

Examine your system's new audio links.

For example:

% ls -lt /dev/audio* lrwxrwxrwx 1 root root 7 Jul 23 15:46 /dev/audio -> usb/audio0 lrwxrwxrwx 1 root root 10 Jul 23 15:46 /dev/audioctl -> usb/audioctl0/ % ls -lt /dev/sound/* lrwxrwxrwx 1 root root 74 Jul 23 15:46 /dev/sound/1 -> ../../devices/pci@1f,4000/usb@5/hub@1/device@3/sound-control@0:sound,a... lrwxrwxrwx 1 root root 77 Jul 23 15:46 /dev/sound/1ctl -> ../../devices/pci@1f,4000/usb@5/hub@1/device@3/sound-control@0:sound,a... lrwxrwxrwx 1 root other 66 Jul 23 14:21 /dev/sound/0 -> ../../devices/pci@1f,4000/ebus@1/SUNW,CS4231@14,200000:sound,audio lrwxrwxrwx 1 root other 69 Jul 23 14:21 /dev/sound/0ctl -> ../../devices/pci@1f,4000/ebus@1/SUNW,CS4231@14,200000:sound,audioctl %

Notice that the primary audio device, /dev/audio, is pointing to the newly plugged in USB audio device, /dev/usb/audio0.

You can also examine your system's USB audio devices with the prtconf command and look for the USB device information.

% prtconf . . . usb, instance #0 hub, instance #0 mouse, instance #0 keyboard, instance #1 device, instance #0 sound-control, instance #0 sound, instance #0 input, instance #0 . . .

How to Change the Primary USB Audio Device

• If you want the onboard audio device to become the primary audio device, remove the USB audio devices. The /dev/audio link will then point to the /dev/sound/0 entry. If the /dev/sound/0 entry is not the primary audio device, then either shutdown the system and use the boot -r command, or run the devfsadm -i command as root.

• If you want the USB audio device to become primary audio device, just plug it in and check the links.

Troubleshooting USB Audio Device Problems

This section describes how to troubleshoot USB audio device problems.

Solving USB Audio Problems

Sometimes USB speakers do not produce any sound even though the driver is attached and the volume is set to high. Hot-plugging the device might not change this behavior.

The workaround is to power cycle the USB speakers.

Key Points of Audio Device Ownership

Keep the following key points of audio device ownership in mind when working with audio devices.

• When you plug in a USB audio device and you are logged in on the console, the console is the owner of the /dev/* entries. This situation means you can use the audio device as long as you are logged into the console.

• If you are not logged into the console when you plug in a USB audio device, root becomes the owner of the device. However, if you log into the console and attempt to access the USB audio device, device ownership changes to the console. For more information, see logindevperm(4).

• When you remotely login with the rlogin command and attempt to access the USB audio device, the ownership does not change. This means that, for example, unauthorized users cannot listen to conversations over a microphone owned by someone else.

Hot-Plugging USB Devices With the cfgadm Command (Task Map)

Hot-Plugging USB Devices With the cfgadm Command

You can add and remove a USB device from a running system without using the cfgadm command. However, a USB device can also be logically hot-plugged without physically removing the device. This scenario is convenient when you are working remotely and you need to disable or reset a non-functioning USB device. The cfgadm command also provides a way to display the USB device tree including manufacturer and product information.

The cfgadm command displays information about attachment points, which are locations in the system where dynamic reconfiguration operations can occur. An attachment point consists of:

• An occupant, which represents a hardware resource, such as a USB device, that might be configured into the system, and

• A receptacle, which is the location that accepts the occupant, such as a USB port.

Attachment points are represented by logical and physical attachment point IDs (Ap_Ids). The physical Ap_Id is the physical pathname of the attachment point. The logical Ap_Id is a user-friendly alternative for the physical Ap_Id. For more information on Ap_Ids, see cfgadm_usb(1M).

The cfgadm command provides the following USB device status information.

The following sections describe how to hot-plug a USB device through the software with the cfgadm command. All of the sample USB device information in these sections has been truncated to focus on relevant information.

How to Display USB Bus Information (cfgadm)

Use the cfgadm command to display USB bus information. For example:

% cfgadm
Ap_Id                       Type         Receptacle   Occupant     Condition
usb0/4.5                    usb-hub      connected    configured   ok
usb0/4.5.1                  usb-device   connected    configured   ok
usb0/4.5.2                  usb-printer  connected    configured   ok
usb0/4.5.3                  usb-mouse    connected    configured   ok
usb0/4.5.4                  usb-device   connected    configured   ok
usb0/4.5.5                  usb-storage  connected    configured   ok
usb0/4.5.6                  usb-communi  connected    configured   ok
usb0/4.5.7                  unknown      empty        unconfigured ok
usb0/4.6                    usb-storage  connected    configured   ok
usb0/4.7                    usb-storage  connected    configured   ok

In the preceding example, usb0/4.5.1 identifies a device connected to port 1 of the second-level external hub, which is connected to port 5 of first-level external hub, which is connected to the first USB controller's root hub, port 4.

Use the following cfgadm command to display specific USB device information. For example:

% cfgadm -l -s "cols=ap_id:info"
Ap_Id       Information
 usb0/4.5.1  Mfg: Inside Out Networks Product: Edgeport/421 NConfigs: 1 
Config: 0  : ...
 usb0/4.5.2  Mfg: <undef> Product: <undef>   NConfigs: 1 Config: 0 ...
 usb0/4.5.3  Mfg: Mitsumi Product: Apple USB Mouse NConfigs: 1 Config: 0 ...
 usb0/4.5.4  Mfg: NMB  Product: NMB USB KB/PS2 M NConfigs: 1 Config: 0
 usb0/4.5.5  Mfg: Hagiwara Sys-Com  Product: SmartMedia R/W  NConfigs: 1 
Config: 0 : ...
 usb0/4.5.6  Mfg: 3Com Inc.  Product: U.S.Robotics 56000 Voice USB Modem 
NConfigs: 2 ...
 usb0/4.5.7
 usb0/4.6    Mfg: Iomega  Product: USB Zip 250  NConfigs: 1  Config: 0
 : Default
 usb0/4.7    Mfg: Iomega  Product: USB Zip 100  NConfigs: 1  Config: 0
 : Default

For examples of using the prtconf command to display USB configuration information, see How to Display USB Device Information (prtconf).

How to Unconfigure a USB Device

You can unconfigure a USB device that is still physically connected to the system, but a driver will never attach to it. Note that a USB device remains in the prtconf output even after that device is unconfigured.

Steps

1. Become superuser.

2. Unconfigure the USB device.

   # cfgadm -c unconfigure usb0/4.7 Unconfigure the device: /devices/pci@8,700000/usb@5,3/hub@4:4.7 This operation will suspend activity on the USB device Continue (yes/no)? y

3. Verify that the device is unconfigured.

   # cfgadm Ap_Id Type Receptacle Occupant Condition usb0/4.5 usb-hub connected configured ok usb0/4.5.1 usb-device connected configured ok usb0/4.5.2 usb-printer connected configured ok usb0/4.5.3 usb-mouse connected configured ok usb0/4.5.4 usb-device connected configured ok usb0/4.5.5 usb-storage connected configured ok usb0/4.5.6 usb-communi connected configured ok usb0/4.5.7 unknown empty unconfigured ok usb0/4.6 usb-storage connected configured ok usb0/4.7 usb-storage connected unconfigured ok

How to Configure a USB Device

Steps

1. Become superuser.

2. Configure a USB device.

   # cfgadm -c configure usb0/4.7

3. Verify that the USB device is configured.

   # cfgadm usb0/4.7 Ap_Id Type Receptacle Occupant Condition usb0/4.7 usb-storage connected configured ok

How to Logically Disconnect a USB Device

If you want to remove a USB device from the system and the prtconf output, but you are not physically near the system, just logically disconnect the USB device. The device is still physically connected, but it is logically disconnected, unusable, and not visible to the system.

Steps

1. Become superuser.

2. Disconnect a USB device.

   # cfgadm -c disconnect -y usb0/4.7

3. Verify that the device is disconnected.

   # cfgadm usb0/4.7 Ap_Id Type Receptacle Occupant Condition usb0/4.7 unknown disconnected unconfigured ok

How to Logically Connect a USB Device

Use this procedure to logically connect a USB device that was previously logically disconnected or unconfigured.

Steps

1. Become superuser.

2. Connect a USB device.

   # cfgadm -c configure usb0/4.7

3. Verify that the device is connected.

   # cfgadm usb0/4.7 Ap_Id Type Receptacle Occupant Condition usb0/4.7 usb-storage connected configured ok

   The device is now available and visible to the system.

How to Logically Disconnect a USB Device Subtree

Use this procedure to disconnect a USB device subtree, which is the hierarchy (or tree) of devices below a hub.

Steps

1. Become superuser.

2. Remove a USB device subtree.

   # cfgadm -c disconnect -y usb0/4

3. Verify that the USB device subtree is disconnected.

   # cfgadm usb0/4 Ap_Id Type Receptacle Occupant Condition usb0/4 unknown disconnected unconfigured ok

How to Reset a USB Device

If a USB device behaves erratically, use the cfgadm command to reset the device, which logically removes and recreates the device.

Steps

1. Become superuser.

2. Make sure the device is not in use.

3. Reset the device.

   # cfgadm -x usb_reset -y usb0/4.7

4. Verify that the device is connected.

   # cfgadm usb0/4.7 Ap_Id Type Receptacle Occupant Condition usb0/4.7 usb-storage connected configured ok

How to Change the Default Configuration of a Multi-Configuration USB Device

Keep the following in mind when working with multi-configuration USB devices:

• A USB device configuration defines how a device presents itself to the operating system. This is different from system device configurations discussed in other cfgadm sections.

• Some USB devices support multiple configurations, but only one configuration can be active at a time.

• Multi-configuration devices can be identified by examining the cfgadm -lv output. Nconfigs will be greater than 1.

• The default USB configuration is configuration 1. The current configuration is reflected in cfgadm -lv output as Config.

• Changes to the default configuration will persist across reboots, hot-removes, and reconfiguration of the device, as long as it is reconnected to the same port.

Steps

1. Make sure the device is not in use.

2. Change the default USB configuration.

   For example:

   # cfgadm -x usb_config -o config=2 usb0/4 Setting the device: /devices/pci@1f,0/usb@c,3:4 to USB configuration 2 This operation will suspend activity on the USB device Continue (yes/no)? yes

3. Verify the device change.

   For example:

   # cfgadm -lv usb0/4 Ap_Id Receptacle Occupant Condition Information When Type Busy Phys_Id usb0/4 connected unconfigured ok Mfg: Sun 2000 Product: USB-B0B0 aka Robotech With 6 EPPS High Clk Mode NConfigs: 7 Config: 2 : EVAL Board Setup unavailable usb-device n /devices/pci@1f,0/usb@c,3:4

   Config now shows 2.