Chapter 18 Managing USB Devices

This chapter on managing USB devices has been revised in the Solaris 8 4/01 software release. See the following sections for further information.

• Overview of USB Devices

• USB Printer Support

For general information about device management in Solaris, see “Managing Devices Topics” in the System Administration Guide, Volume 1.

For the most current man pages, use the man command. The Solaris 8 Update release man pages include new feature information that is not in the Solaris 8 Reference Manual Collection.

Overview of USB Devices

Universal Serial Bus (USB) was developed by the PC industry to provide a low-cost solution for attaching peripheral devices, such as keyboards, mouse devices, and printers, to a system.

USB connectors are designed to fit only one type of cable, one way. Devices can connect to hub devices, which connect several devices, including other hub devices. The primary design motivation for USB is to alleviate the need for multiple connector types for different devices, thereby reducing the clutter on the back panel of a system. Additional advantages of using USB devices are:

• USB devices are hot-pluggable. See Hot-Plugging USB Devices for more information.

• Supports a maximum of 126 devices in the Solaris environment.

• Supports a maximum of 12 Mbit/sec data transfer.

• Supports low speed (1.5 Mbit/sec) and full speed (12 Mbit/sec) devices.

• The bus can be easily extended by adding low-cost external hubs. Hubs can be connected to hubs to form a tree topology.

Sun Microsystems support for USB devices includes the following:

• Sun Blade^TM 100 and Sun Blade 1000 systems that run the Solaris 8 10/00 release provide USB device support.

• Sun Ray^TM systems also support USB devices.

• IA systems that run the Solaris 8 Intel Platform Edition provide USB support for keyboard and mouse devices, and for certain mass-storage devices, such as Zip drives. See scsa2usb(7D) for more information.

This table provides a listing of specific USB devices that are supported in the Solaris environment.

Commonly Used USB Acronyms

The following table describes the USB acronyms that are used in the Solaris environment. See http://www.usb.org for a complete description of USB components and acronyms.

USB Bus Description

The USB specification is openly available and free of royalties. The specification defines the electrical and mechanical interfaces of the bus and the connectors.

Figure 18–1 USB Physical Device Hierarchy

USB employs a topology in which hubs provide attachment points for USB devices. The host controller contains the root hub, which is the origin of all USB ports in the system. See USB Host Controller and Root Hub for more information about hubs.

The previous example shows a system with three active USB ports. The first USB port has a Zip drive that does not have an embedded hub, so you cannot attach additional devices. The second USB port has a hub with a Jaz drive and a composite keyboard/mouse device connected. One of the ports from the secondary hub has a keyboard with an embedded hub where the mouse is attached.

The device tree path name for some of the devices that are displayed in the previous example are listed in this table.

USB Devices and Drivers

The USB devices are divided into device classes. Each device class has a corresponding driver. Devices within a class are managed by the same device driver. However, the USB specification also allows for vendor-specific devices that are not part of a specific class. Devices with similar attributes and services are grouped.

The Human Interface Device (HID) class contains devices that are user controlled such as keyboards, mouse devices, and joysticks. The Communication Device class contains devices that connect to a telephone, such as modems or an ISDN interface. Other device classes include the Audio, Monitor, Printer, and Storage Device classes. Each USB device contains descriptors that reflect the class of the device. A device class specifies how its members should behave in configuration and data transfer. You can obtain additional class information from the http://www.usb.org site.

Solaris USB Architecture (USBA)

USB devices are represented as two levels of device tree nodes. A device node represents the entire USB device, and one or more child interface nodes represent the individual USB interfaces on the device. For special cases, the device and interface nodes are combined into a single combined node.

Driver binding is achieved by using the compatible name properties. Refer to 3.2.2.1 of the IEEE 1275 USB binding and Writing Device Drivers for more information. A driver can either bind to the entire device and control all the interfaces, or a driver can bind to just one interface, for example, a keyboard or mouse. If no vendor or class driver claims the entire device, a generic USB multi-interface driver is bound to the device-level node. This driver attempts to bind drivers to each interface by using compatible names properties, as defined in section 3.3.2.1 of the 1275 binding.

Figure 18–1 shows an example of a hub and printer as a compound device. Both the hub and the printer are enclosed in the same plastic case, but the hub and the printer have separate USB bus addresses. The same diagram shows an example of a composite device. The composite keyboard and controller are also enclosed in the same plastic case, but they have the same USB bus address. A cable connects the USB mouse to the composite keyboard/controller in this example.

The Solaris USB Architecture (USBA) adheres to the USB 1.0 and 1.1 specification plus Solaris driver requirements. The USBA model is similar to Sun Common SCSI Architecture (SCSA). The USBA is a thin layer that provides a generic USB transport-layer abstraction to the client driver.

The differences between SCSA and USBA are that the SCSA relies on .conf files to probe the bus, while USB hub drivers are self-probing nexus drivers.

About USB in the Solaris Environment

The following section describes specific information you should know about USB in the Solaris environment.

USB Keyboards and Mouse Devices

Keep only one USB keyboard and mouse on the system at all times because multiple USB keyboards and mouse devices are not supported in the Solaris environment. See the following items for specific details.

• A keyboard and mouse that are connected anywhere on the bus are configured as console keyboard and mouse. Booting the system is slower if the keyboard and mouse are not on the root hub.

• You can move a console keyboard and mouse to another hub at any time after a system reboot. You cannot move the console keyboard and mouse during a reboot or at the ok prompt. After you plug in the keyboard and mouse, they are fully functional again.

• SPARC only – The power key on a USB keyboard behaves differently than the one on the Sun Type–5 keyboard. On a USB keyboard, you can suspend or shut down the system by using the SUSPEND/SHUTDOWN key, but you cannot power-on the system.

• The left side of the keypad functionality is unavailable on non-Sun USB keyboards.

• Multiple keyboards are not supported:

  • The keyboards enumerate and are usable, but they are not plumbed as console keyboards.

  • The first keyboard that is probed at boot time becomes the console keyboard. The result of this probing might cause confusion if multiple keyboards are plugged in at boot time.

  • If you unplug the console keyboard, the next available USB keyboard doesn't become the console keyboard. The next hot-plugged keyboard becomes the console keyboard.

• Multiple mouse devices are not supported:

  • The mouse devices enumerate and are usable, but they are not plumbed as console mouse devices.

  • The first mouse that is probed at boot time becomes the console mouse. The result of this probing might cause confusion if you have multiple mouse devices plugged in at boot time.

  • If you unplug the console mouse, the next available USB mouse doesn't become the console mouse. The next hot-plugged mouse becomes the console mouse.

• If you have a non-Sun (third-party) composite keyboard with a PS/2 mouse, and it is the first one to be probed, it becomes the console keyboard/mouse even if the PS/2 mouse is not plugged in. This means another USB mouse plugged into the system cannot work because it is not configured as the console mouse.

• Only two-button and three-button mouse devices are supported. A wheel-on-wheel mouse acts like a plain-button mouse. A mouse with more than three buttons functions like a three–button mouse.

USB Host Controller and Root Hub

A USB hub is responsible for:

• Monitoring the insertion or removal of a device on its ports

• Power-managing individual devices on its ports

• Controlling power to its ports

The USB host controller has an embedded hub called the root hub. The ports that are visible at the back panel are the ports of the root hub. The USB host controller is responsible for:

• Directing the USB bus. Individual devices cannot arbitrate for the bus.

• Polling the devices by using a polling interval determined by the device. The device is assumed to have sufficient buffering to account for the time between the polls.

• Sending data between the USB host controller and its attached devices. Peer-to-peer communication is not supported.

USB Hub Devices

• Do not cascade hubs beyond four levels on either SPARC or IA systems. On SPARC systems, the Open Boot PROM (OBP) cannot reliably probe beyond four levels of devices.

• Do not cascade bus-powered hubs. This means you cannot plug a bus-powered hub into another bus-powered hub. A bus-powered hub does not have its own power supply. A USB diskette device derives all its power from the bus and might not work on a bus-powered hub.

USB Storage Devices

Removable mass storage devices such as USB Zip, Jaz, Clik!, SmartMedia, CompactFlash, and ORB are supported, starting with the Solaris 8 10/00 release. See scsa2usb(7D) for a complete list of devices that are supported in the Solaris environment.

These devices can be managed with or without volume management. See vold(1M) for information on managing devices with volume management.

Managing USB Mass Storage Devices With vold Running

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

You must include the /usr/dt/man in your MANPATH variable to display the man pages listed in this section. You must also have /usr/dt/bin 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 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. See rmmount.conf(4) or vold.conf(4) for details on how to configure removable storage devices.

The following procedures describe how to manage USB mass storage devices with volume management. The device nodes are created under the /vol/dev directory. See scsa2usb(7D) for more information. The following procedures also describe how to add or remove hot-pluggable USB mass storage devices. Hot-plugging a device means the device is added or removed without shutting down the operating system or powering off the system.

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

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

   $ eject -n . . . rmdisk0 -> /vol/dev/rdsk/c4t0d0/clik40 (Generic USB storage) cdrom0 -> /vol/dev/rdsk/c0t6d0/audio_cd (Generic CD device) zip1 -> /vol/dev/rdsk/c2t0d0/fat32 (USB Zip device) zip0 -> /vol/dev/rdsk/c1t0d0/zip100 (USB Zip device) jaz0 -> /vol/dev/rdsk/c3t0d0/jaz1gb (USB Jaz device)

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

   $ volrmmount -i device-alias

   This example mounts a USB Jaz drive under /rmdisk/jaz0.

   $ volrmmount -i jaz0

3. Unmount a USB mass storage device.

   $ volrmmount -e device-alias

   This example unmounts a USB Zip drive from /rmdisk/zip0.

   $ volrmmount -e zip0

4. 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 it is not unmounted already. The command also terminates any active applications that access the device.

   ---

How to Remove a Hot-Pluggable USB Mass Storage Device With vold Running

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

1. Unmount the device.

   $ volrmmount -e zip0

2. (Optional) Stop any active applications that are using the device.

3. Eject the device.

   $ 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 Add a Hot-Pluggable USB Mass Storage Device With vold Running

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

1. Insert the USB mass storage device.

2. Restart vold.

   # pkill -HUP vold

3. Verify the device has been added.

   $ ls device-alias

Managing USB Mass Storage Devices Without vold Running

You can use USB mass storage devices without the volume manager (vold) running. Here are two ways to avoid using the volume manager.

• Stop vold by issuing this command.

  # /etc/init.d/volmgt stop

• Keep vold running, but do not register the USB mass storage devices with it. 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

  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 or Jaz removable devices are in the system, vold registration for these devices would be disabled as well.

  ---

  See vold.conf(4) for details.

The following procedures describe how to manage USB mass storage devices without vold(1M) running. The device nodes are created under the /dev/rdsk directory for character devices and under the /dev/dsk directory for block devices. See scsa2usb(7D) for details.

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

1. Become superuser.

2. Mount a USB mass storage device.

   # mount -F fs-type /dev/dsk/cntndnsn /mount-point

   This command might fail it the device is read only. Use the following command for CD-ROM devices.

   # mount -F fs-type -o ro /dev/dsk/cntndnsn /mount-point

   For example:

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

3. Unmount a USB mass storage device.

   # umount /mount-point

4. Eject the device.

   # eject /dev/[r]dsk/cntndnsn

How to Remove a Hot-Pluggable USB Mass Storage Device Without vold Running

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

1. Become superuser.

2. Remove the hot-pluggable USB device.

   1. Unmount the device.

      # umount /mount-point

   2. (Optional) Stop any active applications that are using the device.

   3. Remove the device.

How to Add a Hot-Pluggable USB Mass Storage Device Without vold Running

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

1. Add a hot-pluggable USB device into the USB port.

2. Verify the USB device has been added.

   $ ls /dev/rdsk/cntndnsn

SPARC: Creating Data on or Extracting Data From a USB CD

You can use the cdrw command to create and extract data from audio CDs. The cdrw command is available on the Software Supplement for the Solaris 8 Operating Environment 1/01 CD.

• SCSI, ATAPI, and USB CD devices are supported. Currently, the only CD-RW device supported by Sun is the Sony Spress USB CD-RW.

• The CD-R or CD-RW drive must be MMC compliant.

See the cdrw man page in the Solaris on Sun Hardware Reference Manual Supplement for information on using this command.

How to Prepare for Creating Data on or Extracting Data From a USB CD

The cdrw command works with or without vold running. See the cdrw(1) and mkisofs(1M) man pages for more information.

1. Insert a CD into the CD-RW device.

   The CD can be any CD that the device can read.

2. Check that the CD-RW drive is connected properly by listing the device.

   # cdrw -l Node | Connected Device | Device type ----------------------+--------------------------------+----------------- /dev/rdsk/c0t0d0s2 | SONY CD-RW CRX120E 1.0k | CD Reader/Writer

3. (Optional) If you do not see the drive in the list, you might have to do a reconfiguration boot so that the system recognizes the device.

   # touch /reconfigure # init 6

SPARC Only: USB Power Management

If the system has enabled power management, the USB framework makes a best effort to power-manage all devices. Power-managing a USB device means the hub driver suspends the port to which the device is connected. The device might or might not support remote wakeup. If the device supports remote wakeup, it wakes up the hub it is connected to, depending on the event, such as moving the mouse. The host system could also wake the device if an application sends an I/O to it.

All HID (keyboard, mouse, and so forth), hub, and storage devices are power-managed by default if they support the remote wakeup capability. A USB printer is power-managed only between two print jobs.

When you power-manage to reduce power consumption, USB leaf devices are powered down first, and after some delay, the parent hub is powered down. When all devices that are connected to this hub's ports are powered down, the hub is powered down after some delay. To achieve the most efficient power management, do not cascade many hubs.

Hot-Plugging USB Devices

When you plug in a USB device, the device is immediately seen in the system's device hierarchy, as displayed in the prtconf(1M) 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. To recover from accidentally removing a busy USB device, do the following:

1. Plug the original device into the same port.

2. Stop the application that is using the device.

3. Remove the device.

The USB port remains unusable until the original device has been plugged in again. If the device is no longer available, the port remains unusable until the next reboot.

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.

USB Cables

Never use USB cable extenders that are available in the market. Always use a hub with longer cables to connect devices. Always use fully rated (12 Mbit/sec) 20/28 AWG cables for connecting USB devices.

USB Printer Support

You can use Solaris Print Manager to set up a USB printer that is attached to a SPARC system with USB ports, starting with the Solaris 8 10/00 release. You can also set up USB printers on IA systems, starting with the Solaris 8 04/01 release.

The new logical device names for USB printers are:

/dev/printers/[0...N]*  

Therefore, when you add a USB printer to a printer server, select one of these devices for a USB printer under Printer Port on the Add New Attached Printer screen. See the System Administration Guide, Volume 2 for more information on using Solaris Print Manager to set up printers.

Although the new Solaris USB printer driver supports all USB printer-class compliant printers, a list of recommended PostScript^TM printers is in the usbprn(7D) man page.

The usbprn driver is compliant with non-PostScript printers that utilize third-party PostScript conversion packages like GhostScript. You can obtain conversion packages from the Solaris 8 Software Companion CD, available at http://www.sun.com/software/solaris/binaries/package.html.

Refer to the Notes and Diagnostics sections of the usbprn(7D) man page for information and cautions about hot-plugging USB printers.