`enum-usb`

Enumerate devices on the USB bus

Syntax:

enum-usb [options]

enum-usb [options,]validate

Options:

Options for enum-usb are separated by commas, with no whitespaces. They include:

cfg_file_path=pathname: pathname is the path to the enum-usb configuration file. Default is /etc/enum-usb.conf.
check_MS_desc: Query devices for Microsoft descriptor data. Default is off. See “Microsoft descriptors” below.
iface_tbl_size=size: size is the maximum number of interfaces enum-usb will manage at the same time. These interfaces can be on any number of devices. Default is 50 interfaces.
USB_mgr_pathname=pathname: pathname is the path to the USB resource manager. Default is /dev/io-usb/io-usb.
validate: Validate the configuration file. If this option is used, enum-usb will parse the configuration file, report any errors it encounters in the file, then exit.
verbose=level: Turn on verbose mode and output to stdout at the verbosity level specified by level. When using enum-usb in combination with enum-devices, you must also set the verbose options of enum-devices for verbose statements to be available at the console.

Description:

This description of enum-usb includes the following sections;

Overview
USB device information
Behavior when enumerating a single USB device
The enum-usb configuration file
Using enum-devices with enum-usb

Overview

The enum-usb utility is a bus-enumerator program spawned by enum-devices to handle USB-specific aspects of device enumeration.

Since enum-usb is spawned by enum-devices, enum-usb options are specified by the enumerator clause in the enum-devices configuration files. For example:

enumerator("usb verbose=10,cfg_file_path=/etc/enum-usb.conf")

The default configuration file for the enumerator clauses is /etc/system/enum/common.

The enum-usb utility scans the USB bus and writes a line describing each device found to standard output (stdout). The device enumerator manager enum-devices reads in the information from this stream and launch the drivers required to manage the devices via the enum-devices configuration files.

When a USB device is removed from the system, enum-usb reports this removal to enum-devices so that it can remove the drivers it launched for that device.

USB device information

enum-usb provides enum-devices the following information about interfaces on a USB device:

busno — the USB bus number
cfg — the USB configuration the device is using
class — the device or interface class
devno — the USB device number
did — the device ID
iface — the USB interface number
num_iface — the number of interfaces available for the selected USB device configuration
proto — the device or interface protocol
rev — the device version
subclass — the device or interface subclass
vid — the vendor ID

See the enum-usb configuration file's Set for additional information that enum-usb can provide to enum-devices.

Microsoft descriptors

If the device (for example a PFS device) supports Microsoft descriptors, enum-usb provides the following additional information:

mscomp — Microsoft compatible ID
msven — Microsoft vendor ID
mssubcomp — Microsoft subcompatible ID

For the Microsoft descriptor information to be present, you must enable the check_MS_desc option, but enabling the check_MS_desc option may cause some devices to become unresponsive. Disable this option unless you are using PFS devices or have other features dependent on Microsoft descriptor data enabled on your target.

Behavior when enumerating a single USB device

When enum-usb enumerates a single USB device, it may report more than one device to enum-devices. Behavior is defined by the USB device's device class, as follows:

class is other than zero (!=0): enum-usb considers that any interfaces present on the device cannot be used independently of the other interfaces on the device.; It reports one useable interface for this device, and expects that enum-devices will launch a single driver to manage the device and its interfaces.
class is vendor specific (0xFF): enum-usb considers that the device will be handled by a single driver that knows how to handle this vendor specific device. It reports one useable interface for this device.
class is interface specific (=0): enum-usb reports an event for every interface present for the current device configuration.; Each interface of this USB device can be managed independently of the other interfaces on the device and, therefore, enum-devices can be configured to launch a unique driver for every USB interface reported for the USB device.

The `enum-usb` configuration file

The enum-usb configuration file allows you to identify USB devices by vendor ID, device ID, and serial number in order to control how the device is enumerated by enum-usb. The default path and name of the configuration file is /etc/enum-usb.conf. You can use the -c at startup to specify another the configuration.

The configuration file uses the following options:

Device — start of a device configuration definition; see Device below.
Ignore — instruct enum-usb to ignore the USB device; see Ignore below.
Config — specify the USB device configuration; see Config below.
Set — specify a special tag to include in USB device reports to enum-devices; see Set below.

Each option must be on its own, separate line. Commented lines begin with a number sign (“#”) and are ignored by enum-usb. Blank spaces are ignored.

Sample `enum-usb.conf` configuration file

#Specify the configuration to use for IPOD devices
Device vid=05AC,did=12*
	Config class=03
	Set usr_spec_id=AppleIpod

#Do not enumerate this device
Device vid=13FE,did=1D00
	Ignore

`Device`

The enum-usb configuration file Device option identifies the start of a device configuration definition. All options that follow a Device option in the configuration file are applied to that device, up to a new instance of the Device option.

The Device option identifies a USB device by its:

device ID (did)
vendor ID (vid)
serial number (ser)

The statement for the Device option takes the form:

Device [vid=v],[did=d],[ser=s]

The rules for composing the Device option statement are:

In the model above, vvvv, dddd and s represent the hexadecimal values to match, and s represents the serial number string.
The option statement must contain a least one parameter.
Parameters can be in any order, separated by commas.
If the device will be ignored, do not specify the serial ID (ser) parameter; see Ignore below.
The option statement supports wildcard matching (see fnmatch()), so you can match a range of devices. For example, did=05ac,vid=12*, would match a specific vendor and a range of devices, where 12* matches 1200 through 12FF.
If matching strings do not contain a wildcard, they must specify the vendor ID (vid) and the device ID (did) as four numerals, with leading zeros if necessary. The serial number is a string with a device specific format and length.

`Ignore`

The Ignore option instructs enum-usb to ignore the device and to not enumerate it.

This option is useful if you have a USB device for which a driver registers for the insertion event for the device itself and does not need to be launched by the enumerator. Instructing enum-usb to ignore this type of device, eliminates any possible conflict between the enumerator and the driver, which might both attempt to attach to the device at the same time.

If you want enum-usb to Ignore a device, the Device option identifying it should specify only the device ID and the vendor ID.

enum-usb ignores serial numbers defined in the Device option of ignored devices, because to obtain a device's serial number it must “attach” to the device, and attaching to an ignored device may create a conflict with a driver attempting to get exclusive access to the device.

`Config`

The Config option allows the user to specify which USB device configuration is used when the device to be enumerated supports multiple configurations.

If the Config option is not used, the enum-usb uses the first device configuration selected. If Config option is used but the specified configuration is not present on the device, enum-usb logs an error and does not enumerate the device.

When enum-usb encounters the specified device, it sets the USB device's configuration to either the number specified (Config num=x) by the Config option, or to the first configuration with an interface that matches the class and subclass combination specified by the Config option.

Multiple configuration selections

If a device supports multiple configurations or interfaces from generation to generation, in your enum-usb configuration file you can specify multiple Config option lines for each Device, in priority order. enum-usb uses the first Config option statement that matches the device for which it is listed.

Composing `Config` option statements

Statements for the Config option take the form:

Config [class=xx],[subclass=xx]

or:

Config num=x

The rules for composing Config option statements are:

In the model above, xx represents the hexadecimal values for the class and subclass to match, and x represents the configuration decimal value to match.
The option statement must contain a least one parameter.
The option statement can specify any of the following:
- only the class parameter
- only the subclass parameter
- both the class and the class parameter
The matching strings for class and subclass must be two numerals, with a leading zero if necessary.

When you specifying the configuration number, you are specifying the value reference number of the configuration, rather than its index. For example, if a device has two configurations, they may not be referred to as configuration one and configuration two. To determine the configuration value of a device configuration, refer to the output of the USB utility (usb -vv).
QNX recommends that you use the class and subclass parameters wherever possible, rather than a configuration number (num). For some devices, the environment in which they are used may affect which configurations they report. This device characteristic means that in different environments, the same configuration number may represent different configurations.
Use the configuration number parameter for the Config option only when you are certain that the configuration numbers you use will do not change — when you are certain that the numbers will always represent the same configurations, in all circumstances.

`Set`

The Set option allows you to specify a custom string to be passed to enum-devices. This string can be:

used to help enum-devices match a device to a specific enum-usbconfiguration
applied to an enum-devices configuration; for example, as an argument applied for launching a driver

There are currently two defined custom tags that enum-usb can pass to enum-devices:

user_spec_id — user-specified identifier
inc_user_spec_id — incrementing user-specified identifier

Composing `Set` option statements

Set statements in the enum-usb configuration file must be specified as follows:

If the Device section does not contain a Config statement, Set statements can be specified after the Device statement.
If configuration file includes Config statements, Set statements must be placed immediately following the Config statements to which they apply.

For example:

Device vid=05AC,did=12*

    Config class=01

        Set usr_spec_id=AppleIPODwithDigitalAudio

    Config class=08

        Set usr_spec_id=AppleIPODUMASSmode

user_spec_id

The Set user_spec_id option is useful for associating multiple devices, or a range of devices, with a single enum-devices configuration. It can be:

used to confirm matching criteria, and thus launch the same driver for all the associated devices
passed as an argument to the matched configuration, and thus represent a common system component comprised of several launched drivers

The statement for the Set user_spec_id option takes the form:

Set usr_spec_id=x

The rules for composing the Set user_spec_id option statement are:

In the model above, x represents a string with no white spaces.
The string length is limited to 40 characters.

inc_user_spec_id

The Set inc_user_spec_id option is useful for associating multiple devices, or a range of devices, while providing a device-unique incrementing suffix appended to the user supplied string. Because enum-devices configuration files do not support wildcards, this option can be used only as an argument passed to the matched configuration.

The suffix appended to the user-supplied string by this option:

is taken pulled from a shared pool
is reserved for the name provided
is released when the device is removed
is reusable after release
starts incrementing from zero

For example, behavior with the sample configuration inc_usr_spec_id=/fs/ipod is as follows:

When the first iPod is connected to the host system, all insertion events related to that device include the tag inc_usr_spec_id=/fs/ipod0.
When a second iPod is connected to the host system, all insertion events related to that device include the tag inc_usr_spec_id=/fs/ipod1, and so on for all further iPods connected to the system.
If the second iPod device is removed, the 1 suffix becomes free, and will be reused for the next iPod inserted.

If you want the device suffix to be incremented from zero for a device entry in your enum-usb configuration file (enum-usb.conf) instead of from a shared pool, you must use a unique inc_ usr_spec_id for that device entry in the configuration file.
If the inc_usr_spec_id value is a pathname, the basename is used to reserve the suffix: inc_usr_spec_id=/fs/ipod, for example, will share the suffix pool with inc_usr_spec_id=ipod.

The statement for the Set inc_user_spec_id option takes the form:

Set inc_usr_spec_id=x

The rules for composing the Set inc_user_spec_id option statement are:

In the model above, x represents a string with no white spaces.
The string length is limited to 1024 characters, including the appended suffix.

Using `enum-devices` with `enum-usb`

enum-devices launches enum-usb when it starts. To enable enum-devices to launch enum-usb, you must add enum-usb to the common file accessed by both enum-devices and enum-usb, as follows:

all
    config(include)
    config(overrides)
    config(devices)
    enumerator(usb)

For a complete description of the enum-devices configuration file format, as well as more information about how to use enum-devices, see enum-devices in the Neutrino Utilities Reference.

Examples:

Start enum-usb, specifying the path to the configuration file and setting the interface maximum:

# enum-usb cfg_file_path=/etc/enum-usb-custom.conf,iface_tbl_size=32

`enum-usb.conf`

In this sample implementation, we want enum-devices to launch a driver for an iPod, which has several different device IDs. Instead of a using a enum-devices configuration containing an entry for every vid and did combination, we pass up a user specified ID which represents the set of iPod devices.

#Specify the configuration to use for iPod devices
Device vid=05AC,did=12*
        Config class=03
        Set usr_spec_id=AppleIpod

`enum-devices` configuration file

# If the class is AUDIO and the subclass is STREAMING,
# and the AppleIpod string is present,
# launch io-audio.

device(usb, class=01, subclass=01, usr_spec_id=AppleIpod)
    driver(io-audio "-dipod busno=$(busno),devno=$(devno),
    cap_name=ipod-$(busno)-$(devno),
    ipod_mount=/fs/ipod-$(busno)-$(devno)")