Chapter 7 Using USB Devices (Overview)

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

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 OS

For recent information about USB devices, go to the following site:

http://www.sun.com/io_technologies/usb/USB-Faq.html

For general information about USB devices, go to the following site:

http://developers.sun.com/solaris/developer/support/driver/usb.html

For step-by-step instructions on using USB devices in the Solaris OS, 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 System Administration Guide: Solaris Printing.

What's New in USB Devices?

The following section describes new USB features in the Solaris release.

• USB Interface Association Descriptor Support

• EHCI Isochronous Transfer Support

• Support for CDC ACM Devices

• Changed USB Device Hotpluggable Behavior

• USB Power Budgeting

• ZFS Support on USB Devices

• Support for Prolific and Keyspan Serial Adapters

• x86: Support for USB CDs and DVDs in GRUB-Based Booting

• USB Virtual Keyboard and Mouse Support

• vold Provides Awareness of Hot-Plugged USB Devices

USB Interface Association Descriptor Support

Solaris Express Developer Edition 5/07: A USB device node type, IA node, is created for Interface Association Descriptor (IAD) support. This feature means that a driver might support multiple interfaces for the same device, such as the video and audio interfaces of a webcam. If no driver is found for an IA node, a nexus driver, usb_ia, is bound to the IA node to create the interface nodes. For more information, see usb_ia(7D).

EHCI Isochronous Transfer Support

Solaris Express Developer Edition 5/07: USB EHCI host controller driver provides isochronous transfer support for USB 2.0 or high-speed isochronous devices. For more information, see usb_isoc_request(9S).

Support for CDC ACM Devices

Solaris Express Developer Edition 5/07: Support for CDC ACM devices is provided in this release. For more information, see USB Driver Enhancements.

Changed USB Device Hotpluggable Behavior

Solaris Express 6/06: This feature information has been revised in the Solaris Express 10/06 release.

This Solaris release introduces a new device attribute, hotpluggable, to identify those devices that can be connected or disconnected without rebooting the system and configured or unconfigured automatically without user intervention. All USB and 1394 devices are identified as hotpluggable devices to gain those benefits described in Using USB Mass Storage Devices. In addition, non-removable media USB and 1394 devices are no longer identified as removable-media devices and no longer have a removable-media attribute.

The changes are primarily made at the kernel level to improve support for non-removable media USB and 1394 devices, and improve the performance for those devices. However, theses changes do not impact the use of these devices. For example, the responsibility of mounting and unmounting these devices is controlled by rmvolmgr. From a user's perspective, the only visible changes are the hotpluggable and removable-media attributes of a device.

For more information, see USB and 1394 (FireWire) Support Enhancements.

ZFS Support on USB Devices

Solaris Express 6/06: This information has been revised in the Solaris Express 10/06 release.

You can create and mount ZFS file systems on USB mass storage devices. For information about using USB mass storage devices, see Using USB Mass Storage Devices.

For information about creating and mounting ZFS file systems, see zfs(1M) and zpool(1M).

Support for Prolific and Keyspan Serial Adapters

Solaris Express 1/06: Support for Prolific and Keyspan serial adapters is provided in this release. For more information, see USB Driver Enhancements.

USB Power Budgeting

Solaris Express 1/06: This Solaris release includes power budgeting of USB devices to better manage the power that is distributed to USB devices. Power budget control helps prevent over-current conditions from occurring and generally makes using USB devices safer. For more information about Solaris USB power budgeting limitations, see Bus-Powered Devices.

x86: Support for USB CDs and DVDs in GRUB-Based Booting

Solaris Express 6/05: You can use the following USB features in the GRUB-based booting environment:

• Installing from USB CD or DVD drives

• Booting from USB storage devices. You must install the Solaris release on the USB drive before you can boot from it.

For more information about GRUB-based booting, see Chapter 9, Shutting Down and Booting a System (Overview), in System Administration Guide: Basic Administration.

USB Virtual Keyboard and Mouse Support

Solaris Express 6/05: USB virtual keyboard and mouse support enables you to hook up multiple keyboards and multiple mice, where the set of keyboards or mice behave as one virtual keyboard or mouse. This means that the input of each physical device is coalesced into a single input stream. For example, if you type SHIFT on one keyboard and A on another, the character echoed is an uppercase A.

Also supported is the ability to add a USB keyboard or mouse to a laptop and have these devices work as one device with the laptop's PS/2 keyboard and pad.

In addition, support for barcode readers is provided by the virtual keyboard and mouse feature.

For more information, refer to virtualkm(7D).

vold Provides Awareness of Hot-Plugged USB Devices

Solaris Express 12/06: The vold features are removed in this release. For information about managing removable media with vold in the Solaris 10 releases, see System Administration Guide: Devices and File Systems.

For information about new removable media management services in the Solaris Express release, see Changes and Improvements to Removable Media Management.

Solaris Express 6/05: The removable media manager (vold) is now hotplug aware. There is no need to restart this daemon to mount a USB mass storage device that has been hot-inserted. However, for some devices, it might still be necessary to manually mount the devices as vold is not always successful. In the case where vold fails to automatically mount a USB device, stop vold, like this:

# /etc/init.d/volmgt stop

For information about manually mounting a USB mass storage device, see How to Mount or Unmount a USB Mass Storage Device.

Solaris Support for USB Devices

Use the following table to identify Solaris support information for specific USB 1.1 and USB 2.0 devices.

Notes:

• Only USB 1.x audio devices are supported. No USB 2.0 audio devices are supported.

• A USB 1.x audio device that is connected to a USB 2.0 hub, which is connected to a USB 2.0 port, can be used in the Solaris 10 and Solaris Express releases only. For more information, see usb_ac(7D) and usb_as(7D).

• Devices that are not supported by a USB driver might have libusb applications such as gphoto2, gtkam, and pilotlink. For more information, refer to /usr/sfw/share/doc/libusb/libusb.txt.

• Solaris 8 and Solaris 9 releases – For USB dual framework issues, refer to the following site:

  http://www.sun.com/io_technologies/usb/USB-Faq.html

For task information associated with mass storage devices, see Chapter 8, Using USB Devices (Tasks).

For more information about ugen, see USB Driver Enhancements.

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, in 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.

For more information, see usba(7D) or go to the following site:

http://www.usb.org

Commonly Used USB Acronyms

The following table describes the USB acronyms that are used in the Solaris OS. 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 Hubs.

Figure 7–1 USB Physical Device Hierarchy

Figure 7–1 shows a system with three active USB ports. The first USB port connects a USB memory stick. 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 here.

Memory stick

/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. 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 the following devices:

• Keyboards

• Mouse devices

• Joysticks

The Communication Device class includes the following devices:

• Modems

• Ethernet adapters

Other device classes include the following classes:

• Audio

• Monitor

• Printer

• Storage Device

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

For more information about USB devices supported in the Solaris release, see usb(7D).

USB Driver Enhancements

The following USB driver enhancements are included.

• USB CDC ACM device support – The acm driver can work with devices that are compliant with the USB Communication Class Device specification's Abstract Control Model and some PCMCIA cards that have modem capabilities.

  The pppd daemon can access these devices through the /dev/term/[0~9]* entries. For more information, see pppd(1M).

  For more information, see usbsacm(7D).

• 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.

  • The driver supports control, bulk, and interrupt (in and out) transfers.

  Starting in the Solaris 10 6/06 release, the ugen driver no longer needs to bind explicitly to a device. By default, usb_mid binds to devices that lack a class driver and exports a ugen interface that works with libusb. For example, you can plug in a USB camera that is not a mass-storage device and use a libusb application to access it. In addition, both scsa2usb and usbprn drivers export ugen interfaces and libusb applications can be used on these classes of devices directly.

  For more information, refer to ugen(7D).

• USB serial driver support

  • Digi Edgeport USB support – The Edgeport USB driver only works with Edgeport devices and not with other USB serial 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 the following sites:

    • http://www.digi.com

    • http://www.sun.com/io

  • Keyspan – The Keyspan USB serial driver only works with Keyspan devices, which currently supports the USA-19HS and USA-49WLC models.

    For more information, see usbsksp(7D).

  • Prolific – The Prolific USB serial driver only works with devices based on the PL2303 chipset.

    For more information, see usbsprl(7D).

  For more information about the USB to serial devices support, go to the following site:

  http://www.sun.com/io_technologies/usb/USB-Faq.html

• Documentation and binary support for user-written kernel and userland drivers – For up-to-date information on USB driver development, go to:

  • http://www.sun.com/io_technologies/usb/USB-Faq.html

  • http://developers.sun.com/solaris/developer/support/driver/usb.html

  • Chapter 21, USB Drivers, in Writing Device Drivers

  • Appendix C, Making a Device Driver 64-Bit Ready, in Writing Device Drivers

  • Device Driver Tutorial

  • Intro(7), Intro(9F), and Intro(9S)

  • http://developers.sun.com/prodtech/solaris/driverdev/reference/codesamples/usb_security/index.html

The EHCI, OHCI, and UHCI Drivers

Features of the EHCI driver include:

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

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

• The USB 2.0 chip has one EHCI controller and one or more OHCI or UHCI controllers.

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

Use the prtconf command output to identify whether your system supports USB 1.1 or USB 2.0 devices. For example:

# prtconf  -D | egrep "ehci|ohci|uhci"

If your prtconf output identifies an EHCI controller, your system supports USB 2.0 devices.

If your prtconf output identifies an OHCI or UHCI controller, your system supports USB 1.1 devices.

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 and is part of the Solaris Device Driver Interface (DDI). The USBA model is similar to Sun Common SCSI Architecture (SCSA). As the following figure shows, 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 OS

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

USB 2.0 Features

The following USB 2.0 features are included:

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

  You can take advantage of the high-speed USB protocol when accessing high-speed USB devices, such as DVDs and hard disks.

• Backward Compatibility – 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.

To identify the speed of your USB device in the Solaris 10 releases, check the /var/adm/messages file for messages similar to the following:

Dec 13 17:05:57 mysystem usba: [ID 912658 kern.info] USB 2.0 device
(usb50d,249) operating at hi speed (USB 2.x) on USB 2.0 external hub:
storage@4, scsa2usb0 at bus address 4

Here are some of the USB devices that are supported in this Solaris release:

• Mass storage devices, such as CD-RWs, hard disks, DVDs, digital cameras, diskettes, tape drives, memory sticks, and multi-format card readers

• Keyboards and mouse devices

• Audio devices, such as speakers and microphones

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 scsa2usb(7D).

Solaris USB 2.0 device support includes the following features:

• Increased USB bus speed from 12 Mbyte/sec to 480 Mbyte/sec. 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 might be one of the following possibilities:

  • 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

  • A port on a SPARC or x86 computer motherboard

  A USB 2.0 PCI card might be needed for older SPARC platforms.

• 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 they are connected to a USB 2.0 port.

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

  ---

  Note –

  USB 2.0 storage devices that are 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.

  Also note that the speed of a USB device is limited to what the parent port can support. For example, if a USB 2.0 external hub is followed by a USB 1.x hub and a USB 2.0 device downstream, devices that are connected to the USB 2.0 external hub run at full speed and not high speed.

  ---

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

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, because the power these hubs offer to their downstream devices is limited.

Starting in the Solaris Express release, power budgeting is implemented for USB devices. This feature has the following limitations:

• Cascading two bus-powered hubs is prohibited.

• Each bus-powered hub is allowed a maximum of 100 mA only for each port.

• Only self-powered or low bus-powered devices are allowed to connect to a bus-powered hub. High bus-powered devices are denied the connection. Some hubs or devices can report a false power source, such that the connection might be unpredictable.

USB Keyboards and Mouse Devices

Keep the following issues in mind when using USB keyboards and mouse devices:

• Do not move the keyboard and mouse during a reboot or at the ok prompt on a SPARC system. You can move the 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.

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

• SPARC – Keep the following issues in mind when using USB keyboards and mouse devices on SPARC systems:

  • 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. However, you cannot use that key to power up the system.

  • Before the boot process finishes, the OpenBoot PROM (OBP) limits keyboard and mouse devices to the motherboard root hub ports only.

  • USB keyboard and mouse devices cannot be used simultaneously with Sun Type 3, 4, or 5 keyboards on legacy SPARC systems, such as the Ultra 80.

• For information about multiple keyboard and mouse device support, see virtualkm(7D).

USB Wheel Mouse Support

Starting in the Solaris 9 9/04 release, the following wheel mouse features are supported:

• 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, Firefox, and GNOME applications support wheel mouse scrolling. However, other applications might not support wheel mouse scrolling.

USB Host Controller and Hubs

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 systems 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 be denied connection to bus-powered hubs or might drain the hub of power for other devices. An example of such a device is a USB diskette device.

SPARC: USB Power Management

Suspending and resuming 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 devices (keyboard, mouse, hub, and storage devices), hub devices, 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 managed 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.

For information about using the SUSPEND/SHUTDOWN key on SPARC systems, see USB Keyboards and Mouse Devices.

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.

• The 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/about/faq/ans5