Chapter 7 Using USB Devices (Overview)

This chapter provides an overview of Universal Serial Bus (USB) devices in the Solaris environment.

This is a list of the overview information in this chapter.

• What's New in USB Devices?

• Overview of USB Devices

• About USB in the Solaris Environment

For step-by-step instructions on using USB devices in the Solaris environment, see Chapter 8, Using USB Devices (Tasks).

For general information about dynamic reconfiguration and hot-plugging, see Chapter 6, Dynamically Configuring Devices (Tasks).

For information on configuring USB printers, see What’s New in Printing? in System Administration Guide: Advanced Administration.

What's New in USB Devices?

The following sections describe USB device enhancements in this Solaris release.

USB Dual Framework

The USBA framework, found in the Solaris 9 12/03 release, was originally developed for USB 1.1 devices. A new framework, called USBA 1.0, was created to meet more demanding requirements of USB 2.0 devices. The framework operates USB 1.1 devices as well. This Solaris release provides both frameworks, hence the name dual framework. The purpose of the dual framework is to facilitate a smoother transition from the original framework to the newer framework. The original USBA framework operates devices connected to a system's USB 1.1 ports, while the new USBA 1.0 framework operates devices connected to a system's USB 2.0 ports. All Sun motherboard ports are USB 1.1 ports, while most PCI card ports support USB 2.0.

For specific details on the how the USB dual framework works, go to http://www.sun.com/desktop/whitepapers.html.

USB Framework Compatibility Issues

A driver written for one USB framework will not work on the other USB framework. Most Sun-supplied USB drivers provide versions for both frameworks.

Compatibility problems might occur if you attempt to plug a USB device into a port, directed by a framework that does not recognize a proper driver for that device because the driver is incompatible. When a framework tries to attach a framework-incompatible driver for a device, you will see console messages similar to the following:

The driver for device binding name is not for USBA1.0

This message will appear, for example, when a device operated by a non-Sun driver, which is compatible with USBA 1.0 framework, is plugged into a port supported by the original USBA framework. The USBA 1.0 framework recognizes the device and tries to map the correct driver, but the driver is rejected because it is incompatible with the framework operating the port.

For information on identifying your USB framework configuration, see How to Display USB Device Information (prtconf).

Solaris Support for USB Devices

The following table describes Solaris support for USB 1.1 and USB 2.0 devices:

*This is not the Solaris 8 releases, but the Solaris 8 HW releases, starting with the Solaris 8 HW 5/03 release. The patch number for the USB dual framework found in the Solaris 8 HW 5/03 release is 109896.

In the Solaris 9 9/04 release only, USB 1.1 devices will operate on USB 2.0 hubs that are connected to 2.0 ports.

The following table provides a summary of USB support on Sun SPARC hardware:

For information about PCI cards verified on the Solaris release, go to: http://www.sun.com/io_technologies/usb.html

Sun Microsystems platforms that provide support for USB devices include the following:

• SPARC based systems with OHCI host controllers that support USB 1.1 provide low- and full-speed devices:

  • Sun Blade^TM systems that run the Solaris 8 or 9 releases.

  • Netra^TM X 1/T1 and some Sun Fire^TM systems that run the Solaris 9 release.

• SPARC based systems with OHCI and EHCI host controllers, such as the Sun Blade 1500 or 2500 systems, provide high-speed support for USB 2.0 devices and low- and full-speed support for USB 1.1 devices. Systems include any PCI-based sun4u system that run the Solaris 8 HW 5/03 release or Solaris 9 4/04 release, including the systems listed above when they are equipped with a USB 2.0 PCI card.

• x86 based systems that run the Solaris 8 or 9 x86 Platform Edition with UHCI host controllers provide USB 1.1 support.

For additional USB support information, see Overview of USB Devices.

SPARC: USB 2.0 Features

This Solaris release includes the following USB 2.0 features:

• Better performance – Increased data throughput for devices connected to USB 2.0 controllers, up to 40 times faster than USB 1.1 devices.

  You will be able to take advantage of the high-speed USB protocol when accessing high-speed mass storage devices, such as DVDs and hard drives.

• Compatibility – Backward compatibility with 1.0 and 1.1 devices and drivers so that you can use the same cables, connectors, and software interfaces.

For a description of USB devices and terminology, see Overview of USB Devices.

USB 2.0 Device Features and Compatibility Issues

USB 2.0 devices are defined as high-speed devices that follow the USB 2.0 specification. You can refer to the USB 2.0 specification at http://www.usb.org.

Some of the USB devices that are supported on SPARC based and x86 based systems in this Solaris release are as follows:

• Mass storage devices – CD-RWs, hard disks, DVD, digital cameras, Zip, diskettes, and tape drives

• Keyboard, mouse devices, speakers and microphones

• Audio devices

For a full listing of USB devices that have been verified on the Solaris release, go to:

http://www.sun.com/io_technologies/usb.html

Additional storage devices might work by modifying the scsa2usb.conf file. For more information, see the scsa2usb(7D) man page.

Solaris USB 2.0 device support includes the following features:

• Increased USB bus speed from 12 Mbps to 480 Mbps. This increase means devices that support the USB 2.0 specification can run significantly faster than their USB 1.1 counterparts, when they are connected to a USB 2.0 port.

  A USB 2.0 port is defined on SPARC systems as follows:

  • A port on a USB 2.0 PCI card

  • A port on a USB 2.0 hub that is connected to USB 2.0 port

• USB 2.0 is Solaris Ready on all PCI-based SPARC platforms. A USB 2.0 PCI card is needed to provide USB 2.0 ports. For a list of USB 2.0 PCI cards that have been verified for the Solaris release, go to http://www.sun.com/io_technologies/usb.html.

• USB 1.1 devices work as they have in the past, even if you have both USB 1.1 and USB 2.0 devices on the same system.

• While USB 2.0 devices operate on a USB 1.x port, their performance is significantly better when connected to a USB 2.0 port.

• A USB 2.0 host controller has one high-speed Enhanced Host Controller (EHCI) and one or more low- or full-speed OpenHCI Host Controller (OHCI) embedded controllers. Devices connected to a USB 2.0 port are dynamically assigned to either an EHCI or OHCI controller, depending on whether or not they support USB 2.0.

  ---

  Note –

  USB 2.0 storage devices connected to a port on a USB 2.0 PCI card, and that were used with a prior Solaris release in the same hardware configuration, can change device names after upgrading to this release. This change occurs because these devices are now seen as USB 2.0 devices and are taken over by the EHCI controller. The controller number, w in /dev/[r]dsk/cwtxdysz, is changed for these devices.

  ---

For more information on USB 2.0 device support, see the ehci(7D) and usba(7D) man pages.

USB 2.0 Cables

• Maximum cable length supported is 5 meters.

• Do not use cable extenders. For best results, use a self-powered hub to extend cable length.

• For more information, go to http://www.usb.org/channel/training/warning/

Bus-Powered Devices

Bus-powered hubs use power from the USB bus to which they are connected, to power devices connected to them. Special care must be taken to not overload these hubs, since the power these hubs offer to their downstream devices is limited.

• Do not cascade bus-powered hubs. For example, do not connect one bus-powered hub to another bus-powered hub.

• Avoid connecting bus-powered devices to bus-powered hubs, except for low-speed, low-power devices, such as keyboards or mice. Connecting high-powered devices such as disks, speakers, or microphones to a bus-powered hub could cause power-shortages for all devices connected to that hub. This scenario could cause these devices to behave unpredictably.

USB Mass Storage Devices

All USB storage devices in this Solaris release are now accessed as removable media devices. This change has the following advantages:

• USB storage devices with standard MS-DOS or Windows (FAT) file systems are now supported.

• You can use the user-friendly rmformat command instead of the format command to format and partition all USB storage devices. If the functionality of the format command is needed, use the format -e command.

• You can use the fdisk command if you need to do fdisk-style partitioning.

• Non-root users can now access USB storage devices, since the root-privileged mount command is no longer needed. The device is automatically mounted by vold and is available under the /rmdisk directory. If a new device is connected while the system is down, do a reconfiguration boot with the boot -r command so that vold recognizes the device. Note that vold does not automatically recognize a hot-plugged device. If a new device is connected while the system is up, restart vold. For more information, refer to the vold(1M) and scsa2usb(7D) man pages.

• Disks with FAT file systems can be mounted and accessed. For example:

  mount -F pcfs /dev/dsk/c2t0d0s0:c /mnt

• All USB storage devices are now power managed, except for those that support LOG SENSE pages. Devices with LOG SENSE pages are usually SCSI drives connected through a USB-to-SCSI bridge device. In previous Solaris releases, some USB storage devices were not power managed because they were not seen as removable media.

• Applications might work differently with USB mass storage devices. Keep the following issues in mind when using applications with USB storage devices:

  • Applications might make incorrect assumptions about the size of the media since only smaller devices like diskettes and Zip drives were removable previously.

  • Requests by applications to eject media on devices where this would be inapplicable, such as a hard drive, will succeed and do nothing.

  • If you prefer the behavior in previous Solaris releases where not all USB mass storage were treated as removable media devices, then you can force the old behavior by updating the /kernel/drv/scsa2usb.conf file.

For more information on using USB mass storage devices, see the scsa2usb(7D) man page.

Troubleshooting Tips for USB Mass Storage Devices

Keep the following tips in mind if you have problems adding or removing a USB mass storage device.

• If USB devices are added or removed when the system is down, you must perform a reconfiguration boot.

  ok boot -r

  If you have problems accessing a device that was connected while the system is running, try the following command:

  # devfsadm

• Do not move devices around if the system has been powered down by a suspend operation. For more information, see SPARC: USB Power Management.

• If a device has been hot removed while in use by applications and is no longer available, then stop the applications. Use the prtconf command to see whether the device node has been removed.

SPARC: USB Driver Enhancements

This section describes USB driver enhancements in this Solaris release.

• New generic USB driver – USB devices can now be accessed and manipulated by applications using standard UNIX® read(2) and write(2) system calls, and without writing a special kernel driver. Additional features include:

  • Applications have access to raw device data and device status.

  • Supports control, bulk, and interrupt (in and out) transfers.

  For more information, refer to the ugen(7D) man page and the USB DDK at: http://developers.sun.com/solaris/developer/support/driver/usb.html

• Digi Edgeport USB support – Provides support for several Digi Edgeport USB to serial port converter devices.

  • New devices are accessed as /dev/term/[0-9]* and /dev/cua/[0-9]*.

  • USB serial ports are usable as any other serial port would be, except that they cannot serve as a local serial console. The fact that their data is run through a USB port is transparent to the user.

  For more information, see usbser_edge(7D), or go to http://www.digi.com and http://www.sun.com/io.

• Documentation and binary support for user-written kernel and userland drivers – A Solaris USB Driver Development Kit (DDK) is available. For up-to-date information on USB driver development, including information on the DDK, go to: http://developers.sun.com/solaris/developer/support/driver/usb.html

The EHCI and OHCI Drivers

Features of the EHCI driver include:

• Complies with enhanced host controller interface that supports USB 2.0.

• Supports high-speed control, bulk, and interrupt transfers.

• Currently, there is no support for high-speed isochronous transactions. For example, USB 2.0 audio devices are not supported.

If there are USB 2.0 and USB 1.x devices on the system, the EHCI and OHCI drivers hand-off device control depending upon the type of device that is connected to the system.

• The USB 2.0 PCI card has one EHCI controller and one or more OHCI controllers.

• A USB 1.1 device is dynamically assigned to the OHCI controller when it is plugged in. A USB 2.0 device is dynamically assigned to the EHCI controller when it is plugged in.

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. The primary design motivation for USB was to alleviate the need for multiple connector types for different devices. This design reduces the clutter on the back panel of a system.

Devices connect to USB ports on external USB hubs, or on a root hub that is located on the computer itself. Since hubs have several ports, several branches of a device tree can stem from a hub.

This table lists 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. For a complete description of USB components and acronyms, go to http://www.usb.org.

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.

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. For more information about hubs, see USB Host Controller and Root Hub.

Figure 7–1 USB Physical Device Hierarchy

Figure 7–1 shows a system with three active USB ports. The first USB port connects a Zip drive. The second USB port connects an external hub, which in turn, connects a cdrw device and a composite keyboard/mouse device. As a composite device, this keyboard contains a USB controller, which operates both the keyboard and an attached mouse. The keyboard and the mouse share a common USB bus address because they are directed by the same USB controller.

Figure 7–1 also shows an example of a hub and a printer as a compound device. The hub is an external hub that is enclosed in the same casing as the printer. The printer is permanently connected to the hub. The hub and printer have separate USB bus addresses.

The device tree path name for some of the devices that are displayed in Figure 7–1 are listed in this table.

Zip drive

/pci@1f,4000/usb@5/storage@1

Keyboard

/pci@1f,4000/usb@5/hub@2/device@1/keyboard@0

Mouse

/pci@1f,4000/usb@5/hub@2/device@1/mouse@1

cdrw device

/pci@1f,4000/usb@5/hub@2/storage@3

Printer

/pci@1f,4000/usb@5/hub@3/printer@1

USB Devices and Drivers

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

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 http://www.usb.org.

Solaris USB Architecture (USBA)

USB devices can be represented as two levels of device tree nodes. A device node represents the entire USB device. One or more child interface nodes represent the individual USB interfaces on the device.

Driver binding is achieved by using the compatible name properties. For more information, refer to 3.2.2.1 of the IEEE 1275 USB binding and Writing Device Drivers. A driver can either bind to the entire device and control all the interfaces, or can bind to just one interface. 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 IEEE 1275 binding specification.

The Solaris USB Architecture (USBA) adheres to the USB 1.1 and USB 2.0 specifications 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 client drivers, providing them with services that implement core generic USB functionality.

Figure 7–2 Solaris USB Architecture (USBA)

About USB in the Solaris Environment

This section describes information you should know about USB in the Solaris environment.

USB Keyboards and Mouse Devices

Only Sun USB keyboards and mouse devices are supported. System configurations with multiple USB keyboards and mouse devices might work, but are not supported in the Solaris environment. See the following items for details.

• A USB keyboard and mouse can be connected anywhere on the bus and can be configured as the console keyboard and mouse. Booting the system is slower if the keyboard and mouse are connected to an external hub.

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

• SPARC – The power key on a USB keyboard behaves differently than the power key 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 use that key to power up the system.

• The keys just to the left of the keypad do not function on third-party USB keyboards.

• Multiple keyboards are not supported:

  • Multiple 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 does not become the console keyboard. The next hot-plugged keyboard becomes the console keyboard.

• Multiple mouse devices are not supported:

  • Multiple 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 does not become the console mouse. The next hot-plugged mouse becomes the console mouse.

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

• Support for more than 3 buttons is available on USB or PS/2 mouse devices.

• Wheel mouse scrolling is available on a USB or PS/2 mouse device. This support means that rolling the wheel on a USB or a PS/2 mouse results in a scroll in the application or window under mouse focus. StarOffice^TM, Mozilla^TM, and GNOME applications support wheel mouse scrolling. However, other applications might not support wheel mouse scrolling.

USB Host Controller and Root Hub

A USB hub is responsible for the following:

• 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 system's back panel are the ports of the root hub. The USB host controller is responsible for the following:

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

• Polling the devices by using a polling interval that is 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 based or x86 based systems. On SPARC systems, the OpenBoot^TM PROM cannot reliably probe beyond four levels of devices.

• Do not plug a bus-powered hub into another bus-powered hub in a cascading style. A bus-powered hub does not have its own power supply.

• Do not connect a device that requires a large amount of power to a bus-powered hub. These devices might not work well on bus-powered hubs or might drain the hub of power for other devices. An example of such a device is a USB diskette device.

• This Solaris release does not support connecting a low- or full-speed device to a USB 2.0 hub that is connected to a USB 2.0 port on SPARC-based systems.

SPARC: USB Power Management

Suspending and resuming of USB devices is fully supported on SPARC systems. However, do not suspend a device that is busy and never remove a device when the system is powered off under a suspend shutdown.

The USB framework makes a best effort to power manage all devices on SPARC-based systems with power management enabled. Power managing a USB device means that the hub driver suspends the port to which the device is connected. Devices that support remote wake up can notify the system to wake up everything in the device's path, so that the device can be used. The host system could also wake up the device if an application sends an I/O to the device.

All HID (keyboard, mouse, speakers, microphones), hub, and storage devices are power-managed by default if they support remote wake up capability. A USB printer is power-managed only between two print jobs. Devices that are directed by the generic USB driver (UGEN) are power managed only when they are closed.

When power management is running to reduce power consumption, USB leaf devices are powered down first. After all devices that are connected to a 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.

Guidelines for USB Cables

Keep the following guidelines in mind when connecting USB cables:

• Always use USB 2.0 compliant, fully rated (480 Mbit/sec) 20/28 AWG cables for connecting USB 2.0 devices.

• Always use USB 1.0 compliant, fully rated (12 Mbit/sec) 20/28 AWG cables for connecting USB 1.0 or 1.1 devices. Use bus-powered hubs for low-speed devices only. Always use fully rated (12 Mbit/sec) 20/28 AWG cables for connecting USB devices.

• Maximum cable length that is supported is 5 meters.

• Do not use cable extenders. For best results, use a self-powered hub to extend cable length.

For more information, go to http://www.usb.org/channel/training/warning.