![]() |
![]() |
![]() |
![]() |
Enumerate devices on the USB bus
enum-usb [options] enum-usb [options,]validate
ARM, PowerPC, SH, x86
Options for enum-usb are separated by commas, with no whitespaces. They include:
This description of enum-usb includes the following sections;
enum-usb is a bus-enumerator program spawned by enum-devices to handle USB-specific aspects of device enumeration.
enum-usb 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.
enum-usb provides enum-devices the following information about interfaces on a USB device:
See the enum-usb configuration file's Set for additional information that enum-usb can provide to enum-devices.
If the device supports Microsoft descriptors (for example a PFS device) enum-usb provides the following additional information:
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:
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:
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.
#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
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:
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:
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. |
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.
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.
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:
![]() |
|
The Set option allows you to specify a custom string to be passed to enum-devices. This string can be:
There are currently two defined custom tags that enum-usb can pass to enum-devices:
Set statements in the enum-usb configuration file must be specified as follows:
For example:
Device vid=05AC,did=12* Config class=01 Set usr_spec_id=AppleIPODwithDigitalAudio Config class=08 Set usr_spec_id=AppleIPODUMASSmode
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:
The statment 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:
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:
For example, behavior with the sample configuration inc_usr_spec_id=/fs/ipod is as follows:
![]() |
|
The statment 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:
This section provides basic information useful for using enum-devices with enum-usb. For a complete description of enum-devices configuration file format, see enum-devices in the Neutrino Utilities Reference.
Matching behavior for enum-devices is based on the “number of matches” in the enum-devices configuration file device statement. A secondary device statement may be created by placing a period (“.”) in front of the match field.
This method for matching devices with entries in the enum-devices configuration file can sometimes result in “ambiguities”: a specified device that matches more than one entry in the enum-devices configuration file, rendering it impossible for the enumerator to select the preferred driver for the device.
For example, with a device fully specified as:
vend=1922,dev=1234,busno=0,devno=1, rev=100,msven=fe,mscomp=MTP,mssubcomp=0
and with the following in the enum-devices configuration file:
device(usb, vend=1922,dev=1234) device(usb, class=08,proto=00)
the specified device matches both the entries in the configuration file.
This ambiguity can be removed by either extending the match criteria for the preferred driver:
device(usb, vend=1922,dev=1234,class=08)
or by making one of the matching fields secondary; that is, by giving it a lower precedence that the other fields:
device(usb, .class=08,proto=00)
A “catch all” (an action that matches any device) is produced by simply entering the bus type for the device. For example:
device(usb) echo("No match found for device ven=$(ven), dev=$(dev), class=$(class), busno=$(busno), devno=$(devno), cfg=$(cfg), iface=$(iface), msven=$(msven), mscomp=$(mscomp), mssubcomp=$(mssubcomp)" )
The order of precedence for enum-devices configuration files is determined by one or both of the following criteria:
If files are added to an enumeration directory after the enumeration utility has been started, the enumerator picks up these files and assigns them a higher precedence than currently existing files.
Given the complexity associated with adding and removing files and directories during processing, QNX recommends that you:
The enum-devices configuration file is typically takes the following format:
/enum common /devices default net mass char /include usb-class /overrides mass
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 accesed by both enum-devices and enum-usb, as follows:
all config(include) config(overrides) config(devices) enumerator(usb)
Below is a sample enum-usb command line start up that specifies the path to the configuration file and sets the interface maximum:
# enum-usb cfg_filepath=/etc/enum-usb-custom.conf,iface_tbl_size=32
In this example 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
# 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)")
enum-devices, io-fs-media, iofs-ipod.so, iofs-pfs.so, iofs-ser-ipod.so, iofs-usb-ipod.so, mme
![]() |
![]() |
![]() |
![]() |