E.7 USB Device Configuration
| | |
| ||
| ||
USB device configuration is as simple as adding some text lines to SYS$USER_CONFIG.DAT; it is also simple to do wrong.
You perform USB configuration with the same files that you use to configure device controllers for OpenVMS: SYS$CONFIG.DAT and SYS$USER_CONFIG.DAT. Both files are located in the SYS$SYSTEM: directory. As you might expect, user-written drivers add their configuration records to SYS$USER_CONFIG.DAT; OpenVMS does not modify the contents – even across O/S upgrades.
The contents of the files are evaluated: SYS$USER_CONFIG.DAT is evaluated first, and SYS$CONFIG.DAT second, allowing a user-written configuration record to supersede a system-supplied record.
USB is different from normal OpenVMS device configuration in several respects:
The devices are not classic bus-based controllers, but, rather, devices connected to a peripheral bus.
You can attach and remove devices at will, even at runtime. which requires USB drivers to be loaded on the fly as well as made offline on the fly.
Simple vendor/device identification matching, which is performed for other buses, is not sufficient to determine which driver to load for a USB device.
USB device drivers are part of a larger “stack” of drivers; the controller port driver, the HUB driver, or the HID driver are involved in aspects of configuration and operation of the device. A USB device driver is a pseudo-driver in the sense that it does not directly talk to the device, but passes messages to other drivers that can talk to the USB bus and send messages to and receive messages from USB devices.
The USB protocol was developed to allow device-to-driver matching to be done on multiple levels, depending on the type of device and the needs of the driver.
Device discovery is asynchronous on the USB bus, and it is not feasible to poll the bus to find devices. Instead, devices are configured in response to an event from a HUB device indicating that it has a new device to report. HUBs are both external devices that provide additional slots, and a Root HUB is built onto the controller to which the initial USB connections are attached.
You can attach and remove devices at will, even at runtime. which requires USB drivers to be loaded on the fly as well as made offline on the fly.
The UGDRIVER is the basis of a “generic” driver. It is the functional equivalent of the SCSI GKDRIVER for USB devices; it implements simple logic that takes care of USB housekeeping and allows a user to read and write raw data packets to the USB device.
The Basics of Configuration describes how to (configure UGDRIVER to a specific device or a specific class of devices), and how to make sure that UGDRIVER does not interfere with the configuration of other devices and their drivers.
USB devices include the device itself and one or more Interfaces. Most devices present a single interface. An interface can be serviced by a single driver, or by multiple drivers. A single driver can also service multiple interfaces. Though this procedure seems complex, for the typical USB device, there is only one interface.
When a new device is discovered by a HUB, the HUB driver collects information about the device and sends a message to the USB Configuration Manager (UCM), which is a background process that hibernates, waiting to service configuration events. UCM is the code that knows how to perform device-to -driver matching and how to load device drivers. UCM also maintains an on-disk database of device-to-driver mappings that it previously performed and made permanent (persistent). This database allows a device always to obtain the same OpenVMS device name each time it is plugged in.
The HUB driver collects information about the device and its interfaces, and then requests UCM to attempt to configure and load a device driver for it. The HUB driver does this in the following methods:
First it tries to configure the device as a “DEVICE,” the simplest type of configuration; it ignores the interface information. Devices can be identified by vendor_id, product_id, revision, device_class, device_subclass, and device_protocol.
If a driver is not successfully configured, then the HUB driver asks UCM to try to configure the device as an “INTERFACE”—for each interface the device presents (which is usually only one). Interfaces are identified by vendor_id, product_id, revision, interface_class, interface_subclass, and interface_protocol. The vendor and product ID codes and revision value are inherited from the device.
| |
| |
| |
 | NOTE: This discussion excludes Human Interface Devices. These devices involve human interaction—such as a mouse, keyboard, joystick, simulator, tablet, or game pad—and are handled by a special HID driver. HID devices are identified by a two-byte value of Usage Page and Usage Type; these values are combined into a 16-bit value “TAG,” and device- driver matching is performed by searching for a matching TAG value. The UG driver can be used to talk to a HID device, but it cannot be loaded using the HID Usage Page/Type values. A second generic HID driver is needed for that purpose. |
| |
| |
| |
UCM now has the device information it needs to match to a device driver. To do this, it examines the Generic list. It has created this list by reading the SYS$USER_CONFIG.DAT file and the SYS$CONFIG.DAT file, searching for records that contain a private section with a USB_CONFIG_TYPE record.
The records in the file are simple; each record starts with a DEVICE keyword and ends with an END_DEVICE keyword. USB records are pseudo-devices in the sense that they provide no ADAPTER type and do not have a conventional device ID. Instead, using the BEGIN_PRIVATE and END_PRIVATE construct, they provide USB-specific information. Within this private data area, each line starts with a USB keyword.
The following table lists the USB keywords:
| Keyword | Description |
| USB_CONFIG_TYPE | Tells UCM how the driver is to be configured – as a DEVICE, INTERFACE or TAG method. |
| USB_CLASS_DRIVER | Used for specialized drivers that are class drivers for other USB drivers such as the HID driver. You do not need to use it. The values are SINGLE_INSTANCE and MULTIPLE_INSTANCE. |
| VENDOR_ID | Vendor ID |
| PRODUCT_ID | Product ID |
| RELEASE_NUMBER | Revision number |
| DEVICE_CLASS | The device class code |
| DEVICE_SUB_CLASS | Device subclass |
| DEVICE_PROTOCOL | Device protocol |
| BEGIN_INTERFACE | Starts an interface definition. (There can be multiple interface definitions.) |
| INTERFACE_CLASS | Interface class |
| INTERFACE_SUB_CLASS | Interface subclass |
| INTERFACE_PROTOCOL | Interface protocol |
| END_INTERFACE | Ends an interface definition. |
| HID_USAGE_DATA | The Usage Page/Type TAG for HID devices |
| USAGE_TAG | An alternate TAG type used by HID-like drivers for performing TAG lookups; for example, the EDGEPORT Serial Multiplexer uses this. |
| USB_LOGGING | Used to enable some extra logging (not available to normal drivers – used by CLASS drivers) |
In addition, the standard DEVICE and DRIVER keywords must be included outside the BEGIN_PRIVATE and END_PRIVATE section, telling UCM the device name and driver name to use for the device.
UCM parses this data into a data structure and creates an in-memory Generic list of all the USB devices that are in the files. The queue is in the same order as the devices appear in the file, and the SYS$USER_CONFIG.DAT records come before the SYS$CONFIG.DAT records.
The data in this list is used to match against the configuration request that the HUB driver makes. The matching process can be considered complex.
In device configuration, the hub driver asks UCM to configure the device by device, not by interface or tag.
| |
| |
| |
| NOTE: In general, drivers do not use device configuration; rather, they use interface configuration. The most common use of device configuration is to load special device classes such as hub devices. For a general driver, the only practical use of device configuration is to force the loading of a specific device driver, regardless of any other configuration records that might otherwise match. |
| |
| |
| |
The match logic for a device that has not been connected to the system before is not a simple comparison of all the fields in search of a match. The reason is that a driver (and its configuration record) can match a variety of devices; this is a generic driver. Alternatively, you might have a vendor-specific driver.
The driver class code can be 0-255, and 255 can have special meanings: If the device code is zero, the device present has no device class, no subclass, and no protocol; all of these fields are 0. If the class is 255 (0xFF), the protocol is vendor-specific and must match the vendor ID.
A set of tests determines whether a generic record matches the configuration request. The tests are not all equal: A“priority” is assigned to each test. All the generic records are scanned. A record that matches is compared against the previous match; if the new match has a greater priority, it is used. If no records have matched, a zero is used. This matching means the following:
Higher priority matches win over lower ones.
Duplicate matches of the same priority ignore subsequent matches.
In this manner, records are created so that drivers are selected from more specific to less specific. The following tests are in order of priority—from best match to worst match. When only a field is included, both the configuration request and the generic list entry field must match. When a generic field must be 0 (because omitting the field in the device record in the file sets it to zero), the request field is ignored.
Match 1:
Vendor ID
Product ID
Release Number
Device Class
Device Subclass
Device Protocol
Match 2:
Vendor ID
Product ID
Release Number
Device Class
Device Subclass
Generic Device Protocol must be 0
Match 3:
Vendor ID
Product ID
Release Number
Generic Device Protocol must be 0
Match 4:
Vendor ID
Product ID
Generic Record Release Number must be 0
Generic Device Protocol must be 0
Match 5:
Generic Vendor ID must be 0
Generic Product ID must be 0
Generic Release Number must be 0
Device Class (not 255)
Device Subclass
Device Protocol
Match 5:
Generic Vendor ID must be 0
Generic Product ID must be 0
Generic Release Number must be 0
Device Class (not 255)
Device Subclass
The matching tests show that an entry that is fully qualified always matches before a more generic one.
Note that there is no explicit testing for a Device Class of 0 because the standard requires that devices with a class field of 0 have the subclass and protocol set to 0. The preceding tests handle classes of 0 correctly.
All tests in which the device class cannot be 255 require that the generic record contain no vendor ID (and, by implication, no product ID and no Release Number). This allows the hub record, for example, which has no vendor or product IDs, to match against all devices with a class code of 9. However, a user record that provides only the vendor and product IDs claims a device with a class code of 9 over the generic hub record.
The tests might be tuned to provide a finer granularity, but, in general, the current tests provide all the control a user might need for configuring a device.
Interface Configuration
An interface configuration means that the hub driver asks UCM to configure the device by interface—not by device or tag. The match logic for a device interface that has not been connected to the system before is not simply a comparison of all the fields looking for a match, because you can have an interface driver (and a configuration record for it) that can match a variety of devices; this is a generic driver. However, you might have a vendor-specific driver.
The interface class code can be 0 through 255. The value 255 has a unique meaning: If the class is 255 (0xFF), the interface is vendor-specific and must match the vendor ID.
A set of tests determines if a generic record matches the configuration request. The tests are not all equal – a “priority” is assigned to each test, and all the generic records are scanned. A record that matches is compared against the previous match (or against zero if no matches are found). If the new match has a greater priority, it is used. This matching means the following:
Higher priority matches win over lower ones.
Duplicate matches of the same priority ignore subsequent matches.
In this manner of matching, records can be created so that drivers are selected from more specific to less specific. The following tests are in order of priority—from best match to worst match. When only one field is given, both the configuration request and the generic list entry field must match. When a generic field must be 0 (because omitting the field in the device record in the file sets it to 0), the request field is ignored.
Match 1:
Vendor ID
Product ID
Interface Class
Interface Subclass
Interface Protocol
Match 2:
Vendor ID
Product ID
Interface Class
Interface Subclass
Generic Interface Protocol must be 0
Match 3:
Vendor ID
Interface Class must be 255
Interface Subclass
Interface Protocol
Match 4:
Vendor ID
Interface Class must be 255
Interface Subclass
Generic Interface Protocol must be 0
Match 5:
Generic Vendor ID must be 0
Generic Product ID must not be 255
Interface Subclass
Interface Protocol
Match 6:
Generic Vendor ID must be 0
Interface Class must not be 255
Interface Subclass
Just as in device matching, the order is from strongest match to weakest match, from more specific to less specific, from vendor-specific to generic.
Example E-1 Configuring a Device to Obtain Device Information
As an example, you might find an inexpensive tablet on the Internet and want to write a driver for it. First, you must configure the device to obtain its device information, so you must plug it in. Using the UCM command SHOW EVENT, you can look at events on the USB bus.
|
|
|
This example shows the events from today. The first two are HUB devices; the last event, however, is your device. To obtain more information, ask for INFORMATIONAL events:
|
|
|
This display provides more information. The last section shows the device, which uses an Interface Class of 3, the class that causes the Human Interface Driver (HID) to claim it.
To configure your driver (UGDRIVER), assume that you want to handle only this device (because the generic Interface driver for this class is HID) and currently no way exists to provide user-written HID drivers.
Edit SYS$USER_CONFIG.DAT to add the following record:
|
|
|
This new record indicates that if a device has the vendor code of 2250, and product ID of 16, and Interface Class of 3, and Protocol and Subclass of 0, load the UGDRIVER and call the device UG.
All numbers came from the event information. You must include a vendor and product code because you do not want other devices, such as a generic mouse or some other vendor’s tablet, to use your driver.
You then must reload the database for UCM by using the RELOAD or RESTART command. The difference between the two commands is that a RESTART (besides reading in new configuration data) also removes any in-memory structures that might have been built by earlier device events.
In this case, you create a MOU0 (USB MOUSE) device; MOU0, by default, is never saved as a permanent device (see the description of permanent devices). To reduce the amount of information in the event file, you must reset it, then you unplug the device and plug it back in as shown in the following example:
|
|
|
The messages indicate that the device was loaded.
If you display INFORMATIONAL data, you see the following additional information:
|
|
|
The most significant part of the device configuration is that it does not interfere with other devices with the same interface class; for example, the joystick also uses class 3, subclass 0, and protocol 0. However, if you plug in a joystick, it correctly uses the HID driver, which uses the generic match for Interface Class 3 to load the joystick driver (AGDRIVER), as shown in the following example:
|
|
|
The following section describes the message reporting that the device is tentative and is converted into a permanent device.