Configuration files

USB matching rules

The USB matching rules in the configuration files tell the USB launcher service how to process specific types of devices when they're attached through a USB port.

The matching rules specify device properties (vendor ID, device ID, USB class, etc.) that the service compares against the device descriptors provided by the USB server. When the service finds a rule with properties matching those of a newly attached device, it executes the commands listed in that rule.

Matching rule levels

When an outer (more general) rule matches a device, the USB launcher service compares the inner (more specific) rules in a depth-first search order. You can omit some or all of the inner rules if you don't need to match any descriptors at those levels. For rules at the same level, the service applies the rule listed earliest. You can verify the search order by calling show_config() at the end of your configuration file.

Matching rule arguments

device(vid, did, rev_low, rev_high)
device(vid, did, rev_low)
device(vid, did)
device()

product(vid, did_low, did_high)
product(vid, did_low)
product(vid)
product()

configuration(num)
configuration()

interface(num_low, num_high)
interface(num)
interface()

class(class, subclass, protocol)
class(class, subclass)
class(class)
class()

ms_desc(compatibleID, subcompatibleID, vendorID)
ms_desc(compatibleID, subcompatibleID)
ms_desc(compatibleID)
ms_desc()

The device specification example below shows three levels of matching rules. The driver command line is enclosed in double quotes and prefixed with the driver keyword. The names of macro variables in this command line are the same as the attribute names in PPS device information objects.

device(vid, did, rev_low, rev_high) {
    configuration(1) {
        class(class, subclass, protocol) {
            driver"io-fs-media -dxxx,device=$(busno):$(devno):$(interface)";
        };
    };
};

Variables

USB_CLASS_HID = 0x03
    USB_HID_SUBCLASS_NONE = 0x00
        USB_HID_PROTOCOL_NONE = 0x00
        USB_HID_PROTOCOL_KEYBOARD = 0x01
        USB_HID_PROTOCOL_MOUSE = 0x02
    USB_HID_SUBCLASS_BOOTINTERFACE = 0x01

device(0x2996, 0x0123) { 
    class(USB_CLASS_HID) {
        driver"io-hid -dusb verbose=3 priority=$(hid_drvr_prio)\z
                upath=/dev/usb/io-usb-otg &"
    };
}

Note that variables can be defined within a rule and used in the driver commands. When searching for variable definitions, the service searches from the innermost to the outermost scope.

Flags

You can use flags to change the range of devices matched and the actions subsequently performed.

Ignore flag

At the device level, the Ignore flag tells the USB launcher service to ignore the device by not attaching to it or reading its descriptors. Here, no PPS objects are published and no driver is launched.

device(0x0e0f, 0x0003) {
    Ignore;  -- don't even attach to this device
}

Because it performs the Ignore check before attaching to the device, the USB launcher service doesn't have any device descriptors to match against. As a result, it can look at only the vendor ID and device ID supplied by the server when the device was physically attached to the target system. Therefore, the device rule can't be made more specific about ignoring devices with certain revisions.

For rules at inner levels, the service performs the Ignore check after retrieving device descriptors, so you can make these rules more specific. At any inner level, the Ignore flag stops the service from launching a driver and from matching the device with any subsequent rules.

product(0x05AC) {
    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
        driver"io-audio -dipod busno=$(busno),devno=$(devno),\z
                cap_name=ipod-$(busno)-$(devno)";
    };
    class(USB_CLASS_HID) {
        driver"io-fs-media -dipod,$(IPOD_OPTS)";
    };
    class(USB_CLASS_MASS_STORAGE) {
        Ignore;
    };
};

Default flag

configuration(1) {
    Default;
    driver"io-fs-media -dipod,$(IPOD_OPTS)";
}

Never flag

The Never flag means no device is matched, which lets you temporarily disable a rule. The device can match another rule specified later in the configuration file and have an alternative driver launched.

Always flag

device() {
    class(8) {
        Always;
        start"echo this is busno=$(busno) devno=$(devno) inserted";
     };
};

Multiple interface classes

product(0x05AC, 0x1200, 0x12FF) {
    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
        driver"io-audio -dipod busno=$(busno),devno=$(devno),\z
               cap_name=ipod-$(busno)-$(devno)";
    };
    class(USB_CLASS_HID) {
        driver"io-fs-media -dipod,transport=usb:busno=$(busno):\z
               devno=$(devno):audio=/dev/snd/ipod-$(busno)-$(devno),\z
               darates=+8000:11025:12000:16000:22050:24000,\z
               playback,acp=i2c:addr=0x11:path=/dev/i2c99,\z
               fnames=short,config=/etc/mm/ipod.cfg";
    };
    class(USB_CLASS_MASS_STORAGE) {
        Never;
    };
};

foreach rule

char_devices = {
    device(0x0557, 0x2008);  -- ATEN_232A/GUC_232A
    device(0x2478, 0x2008);  -- TRIPP LITE U2009-000-R
    device(0x9710, 0x7720);  -- MOSCHIP 7720
    device(0x0403, 0x6001);  -- FTDI 8U232AM
    device(0x1199, 0x0120);  -- Sierra AirCard U595
    device(0x0681, 0x0040);  -- Siemens HC25
    device(0x1bc7, 0x1003);  -- Telit UC864E
    device(0x067b, 0x2303);  -- Prolific
}

foreach (char_devices) {
    driver" devc-serusb -d vid=$(vendor_id),did=$(product_id),\z
            busno=$(busno),devno=$(devno)";
}

The foreach rule also works with rules of inner scopes such as configuration or interface.

driver versus start functions

device() {
    class(USB_CLASS_MASS_STORAGE) {
        driver"devb-umass $(DISK_OPTS) $(UMASS_OPTS),\z
                vid=$(vendor_id),did=$(product_id),busno=$(busno),\z
                devno=$(devno),interface=$(interface)";
    };
};

device() {
    class(USB_CLASS_MASS_STORAGE) {
        start"echo Device busno=$(busno) devno=$(devno) inserted";
        removal"echo Device busno=$(busno) devno=$(devno) removed";
    };
};