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;
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:
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.
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 (for example a PFS device) supports Microsoft descriptors, enum-usb provides the following additional information:
|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.|
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* NoMSString 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:
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.
Some devices don't support Microsoft-defined USB descriptors and will go haywire if queried for them. This option prevents queries from being made for these descriptors.
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:
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:
Device vid=05AC,did=12* NoMSString 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 statement for the Set user_spec_id option takes the form:
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 statement for the Set inc_user_spec_id option takes the form:
The rules for composing the Set inc_user_spec_id option statement are:
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.
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
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* NoMSString 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)")