Wild Card Matching

As shown in the previous section, the Common Class Specification details the exact nature of how the fields of the USB device and interface descriptor are used to match drivers. In some cases, however, it would be convenient to not have to create multiple I/O Kit personalities to specify different devices that are supported by a particular driver. For example, if you had to support a whole set of devices from a single vendor, you could just specify a personality that matched to all the product IDs for that vendor. If you then needed to trim the supported product IDs, you could use the probe method of the driver to deny matching to product IDs outside the range that the driver can support. That is the idea behind the concept of wild card matching.

In the tables above, you can substitute the asterisk * wild card character for any of the fields from the device or interface descriptor. The type of the property's value must be changed from <integer> to <string> when the wild card character is used as shown in Listing 3. The probe score will then be reduced by 1000 for each wild card that is specified. For example, a device driver matching on idProduct and idVendor will have a probe score of 90000. If a wild card is specified for the idProduct, the probe score will be reduced by 1000 to 89000. This means that a driver for the same device that does not have a wild card will out-match a wild card-enabled one.

Listing 3  Example wild card matching personality.

 <key>IOKitPersonalities</key>
        <dict>
                <key>WildCardMatching</key>
                <dict>
                        <key>CFBundleIdentifier</key>
                        <string>com.apple.dts.driver.HelloIOKit</string>
                        <key>IOClass</key>
                        <string>com_apple_dts_driver_HelloIOKit</string>
                        <key>IOProviderClass</key>
                        <string>IOUSBDevice</string>
                        <key>idProduct</key>
                        <string>*</string>
                        <key>idVendor</key>
                        <integer>1452</integer>
                </dict>
        </dict>

The idProduct property can also match against a specified range of product IDs without having to implement a probe method to weed out unwanted product IDs. This partial matching is done by specifying a numeric idProductMask property in the driver's matching personality in addition to the idProduct property. This mask will be bitwise ANDed with each candidate device's product ID before comparing it to the idProduct property.

Listing 4 shows how to specify a match on product IDs between 4752 (0x1290) and 4755 (0x1293). The value of the idProductMask property is 65532 (0xfffc). Thus, any product ID will be considered a match that, after being ANDed with 0xfffc, equals the idProduct property's value of 4752.

Listing 4  Example of using idProductMask to match a range of product IDs.

 <key>IOKitPersonalities</key>
        <dict>
                <key>WildCardMatching</key>
                <dict>
                        <key>CFBundleIdentifier</key>
                        <string>com.apple.dts.driver.HelloIOKit</string>
                        <key>IOClass</key>
                        <string>com_apple_dts_driver_HelloIOKit</string>
                        <key>IOProviderClass</key>
                        <string>IOUSBDevice</string>
                        <key>idProduct</key>
                        <integer>4752</integer>
                        <key>idProductMask</key>
                        <integer>65532</integer>
                        <key>idVendor</key>
                        <integer>1452</integer>
                </dict>
        </dict>