Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 1

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 1

Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 8

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 8

enum-usb

Enumerate devices on the USB bus

Syntax:

enum-usb [options]

enum-usb [options,]validate

Runs on:

Neutrino

Targets:

ARM, PowerPC, SH, x86

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

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:

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:


Caution: 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:

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.

Example 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:

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:

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.


Note: 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:


Note:
  • 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:

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

Composing Set option statements

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

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:

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:

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:

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


Note:
  • 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:

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:

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

enum-usb.conf

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

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)")

See also:

enum-devices, io-fs-media, iofs-ipod.so, iofs-pfs.so, iofs-ser-ipod.so, iofs-usb-ipod.so


Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 567

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/utilities/e/enum-usb.html on line 567