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.
The Basics of Configuration
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.
Plugging In A New Device
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. |
|
| |
|
The Generic List
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:
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.
Device Configuration
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:
Match 2:
Generic Device Protocol must be 0
Match 3:
Generic Device Protocol must be 0
Match 4:
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
Match 5:
Generic Vendor ID must be 0
Generic Product ID must be 0
Generic Release Number must be 0
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:
Match 2:
Generic Interface Protocol must be 0
Match 3:
Interface Class must be 255
Match 4:
Interface Class must be 255
Generic Interface Protocol must be 0
Match 5:
Generic Vendor ID must be 0
Generic Product ID must not be 255
Match 6:
Generic Vendor ID must be 0
Interface Class must not be 255
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.
UCM> show event/since=today
Date Time Type Priority Component
--------------------------------------------------------------------------------
15-OCT-2005 13:23:14.54 DRIVER NORMAL HUBDRIVER
Message: Configured device UCM0 using driver SYS$HUBDRIVER:
15-OCT-2005 13:23:16.83 DRIVER NORMAL HUBDRIVER
Message: Configured device UCM0 using driver SYS$HUBDRIVER:
15-OCT-2005 13:25:05.27 DRIVER NORMAL HUBDRIVER
Message: Configured device HID0 using driver SYS$MOUDRIVER:
UCM>
|
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:
|
UCM> sho event/since=today/priority=informational
Date Time Type Priority Component
--------------------------------------------------------------------------------
15-OCT-2005 13:23:14.52 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x9/0x0
15-OCT-2005 13:23:14.52 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x9/0x0
15-OCT-2005 13:23:14.54 UNKNOWN INFORMATIONAL UCM DEVICE UCM0
Message: VENDOR_ID = 4113
PRODUCT_ID = 0
RELEASE_NUMBER = 0
BUS_NUMBER = 0
PATH = 0.0.0.0.0.0
DEVICE_CLASS = 9
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
NUMBER_OF_CONFIGURATIONS = 1
CONFIGURATION_NUMBER = 0.
15-OCT-2005 13:23:14.54 UCM INFORMATIONAL SYS$HUBDRIVER.EXE
Message: Loaded single instance class driver for UCM0.
15-OCT-2005 13:23:14.77 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x9/0x0
15-OCT-2005 13:23:16.83 UNKNOWN INFORMATIONAL UCM DEVICE UCM0
Message: VENDOR_ID = 1033
PRODUCT_ID = 89
RELEASE_NUMBER = 256
BUS_NUMBER = 1
PATH = 1.0.0.0.0.0
DEVICE_CLASS = 9
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
NUMBER_OF_CONFIGURATIONS = 1
CONFIGURATION_NUMBER = 0.
15-OCT-2005 13:23:16.83 UCM INFORMATIONAL SYS$HUBDRIVER.EXE
Message: Loaded single instance class driver for UCM0.
15-OCT-2005 13:25:04.94 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0
15-OCT-2005 13:25:04.94 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for InterfaceClass/InterfaceSubClass/Protocol = 0
x3/0x0/0x0
15-OCT-2005 13:25:04.99 UNKNOWN INFORMATIONAL UCM DEVICE HID0
Message: VENDOR_ID = 2250
PRODUCT_ID = 16
RELEASE_NUMBER = 261
BUS_NUMBER = 1
PATH = 1.2.0.0.0.0
DEVICE_CLASS = 0
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
CONFIGURATION_VALUE = 1
INTERFACE_NUMBER = 0
INTERFACE_PROTOCOL = 0
INTERFACE_CLASS = 3
INTERFACE_SUB_CLASS = 0
NUMBER_OF_CONFIGURATIONS = 1
MANUFACTURER_STRING = AIPTEK International Inc.
PRODUCT_STRING = USB Tablet Series Version 1.05
CONFIGURATION_NUMBER = 0
CURRENT_INTERFACE = 0.
15-OCT-2005 13:25:04.99 UCM INFORMATIONAL SYS$HIDDRIVER.EXE
Message: Loaded single instance class driver for HID0.
15-OCT-2005 13:25:05.00 DRIVER INFORMATIONAL HIDDRIVER
Message: Find a driver for usage page 0001 usage type 0002
15-OCT-2005 13:25:05.27 UNKNOWN INFORMATIONAL UCM DEVICE MOU
Message: BUS_NUMBER = 1
PATH = 1.2.0.0.0.0.HID_USAGE_DATA = 65538.
UCM>
|
|
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:
device = "CyberTablet 12000"
name = UG
driver = sys$ugdriver
begin_private
usb_config_type = interface
vendor_id = 2250
product_id = 16
begin_interface
interface_class = 3
interface_sub_class = 0
interface_protocol = 0
end_interface
end_private
end_device |
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:
|
$ UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> restart
Restart UCM Server? [N]: y
Waiting for UCM Server image to exit....
Waiting for UCM Server image to restart....
%USB-S-SRVRRESTART, Identification of new UCM Server is 0000021E
UCM> set log/new
UCM> show event
Date Time Type Priority Component
--------------------------------------------------------------------------------
15-OCT-2005 13:47:13.58 DECONFIGURED NORMAL HUBDRIVER
Message: Deconfiguring device on bus 1 at port 2 bus tier 2 usb address 3
15-OCT-2005 13:47:14.76 UCM NORMAL SYS$UGDRIVER.EXE
Message: Tentative device UGA0 proposed... auto-loading driver.
15-OCT-2005 13:47:14.78 UCM NORMAL UGA
Message: Auto-perm converting tentative device UGA0 into permanent device.
15-OCT-2005 13:47:14.88 DRIVER NORMAL HUBDRIVER
Message: Configured device UGA0 using driver SYS$UGDRIVER:
UCM>
|
The messages indicate that the device was loaded.
If you display INFORMATIONAL data, you see the following additional
information:
|
UCM> show event/priority=all
Date Time Type Priority Component
--------------------------------------------------------------------------------
15-OCT-2005 13:47:13.58 DECONFIGURED NORMAL HUBDRIVER
Message: Deconfiguring device on bus 1 at port 2 bus tier 2 usb address 3
15-OCT-2005 13:47:14.71 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0
15-OCT-2005 13:47:14.71 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for InterfaceClass/InterfaceSubClass/Protocol = 0x3/0x0/0x0
15-OCT-2005 13:47:14.76 UNKNOWN INFORMATIONAL UCM DEVICE UGA
Message: VENDOR_ID = 2250
PRODUCT_ID = 16
RELEASE_NUMBER = 261
BUS_NUMBER = 1
PATH = 1.2.0.0.0.0
DEVICE_CLASS = 0
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
CONFIGURATION_VALUE = 1
INTERFACE_NUMBER = 0
INTERFACE_PROTOCOL = 0
INTERFACE_CLASS = 3
INTERFACE_SUB_CLASS = 0
NUMBER_OF_CONFIGURATIONS = 1
MANUFACTURER_STRING = AIPTEK International Inc.
PRODUCT_STRING = USB Tablet Series Version 1.05
CONFIGURATION_NUMBER = 0
CURRENT_INTERFACE = 0.
15-OCT-2005 13:47:14.76 UCM NORMAL SYS$UGDRIVER.EXE
Message: Tentative device UGA0 proposed... auto-loading driver.
15-OCT-2005 13:47:14.78 UCM NORMAL UGA
Message: Auto-perm converting tentative device UGA0 into permanent device.
15-OCT-2005 13:47:14.88 DRIVER NORMAL HUBDRIVER
Message: Configured device UGA0 using driver SYS$UGDRIVER:
UCM>
|
|
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:
|
UCM> show event/priority=all
Date Time Type Priority Component
--------------------------------------------------------------------------------
15-OCT-2005 13:47:13.58 DECONFIGURED NORMAL HUBDRIVER
Message: Deconfiguring device on bus 1 at port 2 bus tier 2 usb address 3
15-OCT-2005 13:47:14.71 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0
15-OCT-2005 13:47:14.71 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for InterfaceClass/InterfaceSubClass/Protocol = 0x3/0x0/0x0
15-OCT-2005 13:47:14.76 UNKNOWN INFORMATIONAL UCM DEVICE UGA
Message: VENDOR_ID = 2250
PRODUCT_ID = 16
RELEASE_NUMBER = 261
BUS_NUMBER = 1
PATH = 1.2.0.0.0.0
DEVICE_CLASS = 0
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
CONFIGURATION_VALUE = 1
INTERFACE_NUMBER = 0
INTERFACE_PROTOCOL = 0
INTERFACE_CLASS = 3
INTERFACE_SUB_CLASS = 0
NUMBER_OF_CONFIGURATIONS = 1
MANUFACTURER_STRING = AIPTEK International Inc.
PRODUCT_STRING = USB Tablet Series Version 1.05
CONFIGURATION_NUMBER = 0
CURRENT_INTERFACE = 0.
15-OCT-2005 13:47:14.76 UCM NORMAL SYS$UGDRIVER.EXE
Message: Tentative device UGA0 proposed... auto-loading driver.
15-OCT-2005 13:47:14.78 UCM NORMAL UGA
Message: Auto-perm converting tentative device UGA0 into permanent device.
15-OCT-2005 13:47:14.88 DRIVER NORMAL HUBDRIVER
Message: Configured device UGA0 using driver SYS$UGDRIVER:
15-OCT-2005 14:16:46.55 DECONFIGURED NORMAL HUBDRIVER
Message: Deconfiguring device on bus 1 at port 2 bus tier 2 usb address 3
15-OCT-2005 14:16:49.46 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0
15-OCT-2005 14:16:49.46 DRIVER INFORMATIONAL HUBDRIVER
Message: Find a driver for InterfaceClass/InterfaceSubClass/Protocol = 0x3/0x0/0x0
15-OCT-2005 14:16:49.49 UNKNOWN INFORMATIONAL UCM DEVICE HID0
Message: VENDOR_ID = 1699
PRODUCT_ID = 13630
RELEASE_NUMBER = 256
BUS_NUMBER = 1
PATH = 1.2.0.0.0.0
DEVICE_CLASS = 0
DEVICE_SUB_CLASS = 0
DEVICE_PROTOCOL = 0
NUMBER_OF_INTERFACES = 1
CONFIGURATION_VALUE = 1
INTERFACE_NUMBER = 0
INTERFACE_PROTOCOL = 0
INTERFACE_CLASS = 3
INTERFACE_SUB_CLASS = 0
NUMBER_OF_CONFIGURATIONS = 1
MANUFACTURER_STRING = Saitek
PRODUCT_STRING = Cyborg evo Wireless
CONFIGURATION_NUMBER = 0
CURRENT_INTERFACE = 0.
15-OCT-2005 14:16:49.49 UCM INFORMATIONAL SYS$HIDDRIVER.EXE
Message: Loaded single instance class driver for HID0.
15-OCT-2005 14:16:49.50 DRIVER INFORMATIONAL HIDDRIVER
Message: Find a driver for usage page 0001 usage type 0005
15-OCT-2005 14:16:49.63 UNKNOWN INFORMATIONAL UCM DEVICE AGA
Message: BUS_NUMBER = 1
PATH = 1.2.0.0.0.0.HID_USAGE_DATA = 65541.
15-OCT-2005 14:16:49.63 UCM NORMAL SYS$AGDRIVER.EXE
Message: Tentative device AGA0 proposed... auto-loading driver.
15-OCT-2005 14:16:49.65 UCM NORMAL AGA
Message: Auto-perm converting tentative device AGA0 into permanent device.
15-OCT-2005 14:16:49.78 DRIVER NORMAL HUBDRIVER
Message: Configured device HID0 using driver SYS$AGDRIVERR:
UCM>
|
|
The following section describes the message reporting that the
device is tentative and is converted into a permanent device.
