1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>usb_match_id</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="The Linux-USB Host Side API"><link rel="up" href="usbcore.html" title="Chapter 5. USB Core APIs"><link rel="prev" href="API-usb-driver-release-interface.html" title="usb_driver_release_interface"><link rel="next" href="API-usb-register-device-driver.html" title="usb_register_device_driver"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">usb_match_id</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-usb-driver-release-interface.html">Prev</a> </td><th width="60%" align="center">Chapter 5. USB Core APIs</th><td width="20%" align="right"> <a accesskey="n" href="API-usb-register-device-driver.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-usb-match-id"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_match_id — 2 find first usb_device_id matching device or interface 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">const struct usb_device_id * <b class="fsfunc">usb_match_id </b>(</code></td><td>struct usb_interface * <var class="pdparam">interface</var>, </td></tr><tr><td> </td><td>const struct usb_device_id * <var class="pdparam">id</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1116340036"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>interface</code></em></span></dt><dd><p> 4 the interface of interest 5 </p></dd><dt><span class="term"><em class="parameter"><code>id</code></em></span></dt><dd><p> 6 array of usb_device_id structures, terminated by zero entry 7 </p></dd></dl></div></div><div class="refsect1"><a name="idp1116342644"></a><h2>Description</h2><p> 8 usb_match_id searches an array of usb_device_id's and returns 9 the first one matching the device or interface, or null. 10 This is used when binding (or rebinding) a driver to an interface. 11 Most USB device drivers will use this indirectly, through the usb core, 12 but some layered driver frameworks use it directly. 13 These device tables are exported with MODULE_DEVICE_TABLE, through 14 modutils, to support the driver loading functionality of USB hotplugging. 15</p></div><div class="refsect1"><a name="idp1116343700"></a><h2>Return</h2><p> 16 The first matching usb_device_id, or <code class="constant">NULL</code>. 17</p></div><div class="refsect1"><a name="idp1116344516"></a><h2>What Matches</h2><p> 18 </p><p> 19 20 The <span class="quote">“<span class="quote">match_flags</span>”</span> element in a usb_device_id controls which 21 members are used. If the corresponding bit is set, the 22 value in the device_id must match its corresponding member 23 in the device or interface descriptor, or else the device_id 24 does not match. 25 </p><p> 26 27 <span class="quote">“<span class="quote">driver_info</span>”</span> is normally used only by device drivers, 28 but you can create a wildcard <span class="quote">“<span class="quote">matches anything</span>”</span> usb_device_id 29 as a driver's <span class="quote">“<span class="quote">modules.usbmap</span>”</span> entry if you provide an id with 30 only a nonzero <span class="quote">“<span class="quote">driver_info</span>”</span> field. If you do this, the USB device 31 driver's <code class="function">probe</code> routine should use additional intelligence to 32 decide whether to bind to the specified interface. 33</p></div><div class="refsect1"><a name="idp1116347228"></a><h2>What Makes Good usb_device_id Tables</h2><p> 34 </p><p> 35 36 The match algorithm is very simple, so that intelligence in 37 driver selection must come from smart driver id records. 38 Unless you have good reasons to use another selection policy, 39 provide match elements only in related groups, and order match 40 specifiers from specific to general. Use the macros provided 41 for that purpose if you can. 42 </p><p> 43 44 The most specific match specifiers use device descriptor 45 data. These are commonly used with product-specific matches; 46 the USB_DEVICE macro lets you provide vendor and product IDs, 47 and you can also match against ranges of product revisions. 48 These are widely used for devices with application or vendor 49 specific bDeviceClass values. 50 </p><p> 51 52 Matches based on device class/subclass/protocol specifications 53 are slightly more general; use the USB_DEVICE_INFO macro, or 54 its siblings. These are used with single-function devices 55 where bDeviceClass doesn't specify that each interface has 56 its own class. 57 </p><p> 58 59 Matches based on interface class/subclass/protocol are the 60 most general; they let drivers bind to any interface on a 61 multiple-function device. Use the USB_INTERFACE_INFO 62 macro, or its siblings, to match class-per-interface style 63 devices (as recorded in bInterfaceClass). 64 </p><p> 65 66 Note that an entry created by USB_INTERFACE_INFO won't match 67 any interface if the device class is set to Vendor-Specific. 68 This is deliberate; according to the USB spec the meanings of 69 the interface class/subclass/protocol for these devices are also 70 vendor-specific, and hence matching against a standard product 71 class wouldn't work anyway. If you really want to use an 72 interface-based match for such a device, create a match record 73 that also specifies the vendor ID. (Unforunately there isn't a 74 standard macro for creating records like this.) 75 </p><p> 76 77 Within those groups, remember that not all combinations are 78 meaningful. For example, don't give a product version range 79 without vendor and product IDs; or specify a protocol without 80 its associated class and subclass. 81</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-usb-driver-release-interface.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="usbcore.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-usb-register-device-driver.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">usb_driver_release_interface</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">usb_register_device_driver</span></td></tr></table></div></body></html> 82