.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "USB_MATCH_ID" "9" "17 July 2003" "" ""

.SH NAME
usb_match_id \- find first usb_device_id matching device or interface
.SH SYNOPSIS
.sp
\fB
.sp
const struct usb_device_id * usb_match_id  (struct usb_interface * \fIinterface\fB, const struct usb_device_id * \fIid\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIinterface\fB\fR
the interface of interest
.TP
\fB\fIid\fB\fR
array of usb_device_id structures, terminated by zero entry
.SH "DESCRIPTION"
.PP
usb_match_id searches an array of usb_device_id's and returns
the first one matching the device or interface, or null.
This is used when binding (or rebinding) a driver to an interface.
Most USB device drivers will use this indirectly, through the usb core,
but some layered driver frameworks use it directly.
These device tables are exported with MODULE_DEVICE_TABLE, through
modutils and ``modules.usbmap'', to support the driver loading
functionality of USB hotplugging.
.SH "WHAT MATCHES"
.PP
.PP
The ``match_flags'' element in a usb_device_id controls which
members are used.  If the corresponding bit is set, the
value in the device_id must match its corresponding member
in the device or interface descriptor, or else the device_id
does not match.
.PP
``driver_info'' is normally used only by device drivers,
but you can create a wildcard ``matches anything'' usb_device_id
as a driver's ``modules.usbmap'' entry if you provide an id with
only a nonzero ``driver_info'' field.  If you do this, the USB device
driver's \fBprobe\fR routine should use additional intelligence to
decide whether to bind to the specified interface.
.SH "WHAT MAKES GOOD USB_DEVICE_ID TABLES"
.PP
.PP
The match algorithm is very simple, so that intelligence in
driver selection must come from smart driver id records.
Unless you have good reasons to use another selection policy,
provide match elements only in related groups, and order match
specifiers from specific to general.  Use the macros provided
for that purpose if you can.
.PP
The most specific match specifiers use device descriptor
data.  These are commonly used with product-specific matches;
the USB_DEVICE macro lets you provide vendor and product IDs,
and you can also match against ranges of product revisions.
These are widely used for devices with application or vendor
specific bDeviceClass values.
.PP
Matches based on device class/subclass/protocol specifications
are slightly more general; use the USB_DEVICE_INFO macro, or
its siblings.  These are used with single-function devices
where bDeviceClass doesn't specify that each interface has
its own class. 
.PP
Matches based on interface class/subclass/protocol are the
most general; they let drivers bind to any interface on a
multiple-function device.  Use the USB_INTERFACE_INFO
macro, or its siblings, to match class-per-interface style 
devices (as recorded in bDeviceClass).
.PP
Within those groups, remember that not all combinations are
meaningful.  For example, don't give a product version range
without vendor and product IDs; or specify a protocol without
its associated class and subclass.
.SH "ABOUT THIS DOCUMENT"
.PP
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
.PP
For more details see the file COPYING in the source
distribution of Linux.
.PP
If you have comments on the formatting of this manpage, then please contact
Michael Still (mikal@stillhq.com).
.PP
This documentation was generated with kernel version 2.5.71.