<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML
><HEAD
><TITLE
>usb_match_id</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="The Linux Kernel API"
HREF="book1.html"><LINK
REL="UP"
TITLE="USB Devices"
HREF="c12300.html"><LINK
REL="PREVIOUS"
TITLE="usb_deregister_bus"
HREF="r12462.html"><LINK
REL="NEXT"
TITLE="usb_alloc_urb"
HREF="r12548.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Linux Kernel API</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="r12462.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r12548.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="AEN12488"
></A
><SPAN
CLASS="phrase"
><SPAN
CLASS="PHRASE"
>usb_match_id</SPAN
></SPAN
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN12492"
></A
><H2
>Name</H2
>usb_match_id -- find first usb_device_id matching device or interface
</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN12495"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN12497"
></A
><P
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>const struct usb_device_id * <TT
CLASS="FUNCTION"
>usb_match_id </TT
></CODE
>(struct usb_device * <TT
CLASS="PARAMETER"
><I
>dev</I
></TT
>, struct usb_interface * <TT
CLASS="PARAMETER"
><I
>interface</I
></TT
>, const struct usb_device_id * <TT
CLASS="PARAMETER"
><I
>id</I
></TT
>);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12507"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="PARAMETER"
><I
>dev</I
></TT
></DT
><DD
><P
> the device whose descriptors are considered when matching
</P
></DD
><DT
><TT
CLASS="PARAMETER"
><I
>interface</I
></TT
></DT
><DD
><P
> the interface of interest
</P
></DD
><DT
><TT
CLASS="PARAMETER"
><I
>id</I
></TT
></DT
><DD
><P
> array of usb_device_id structures, terminated by zero entry
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12525"
></A
><H2
>Description</H2
><P
> 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 <SPAN
CLASS="QUOTE"
>"modules.usbmap"</SPAN
>, to support the driver loading
functionality of USB hotplugging.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12529"
></A
><H2
>What Matches</H2
><P
> </P
><P
> The <SPAN
CLASS="QUOTE"
>"match_flags"</SPAN
> 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.
</P
><P
> <SPAN
CLASS="QUOTE"
>"driver_info"</SPAN
> is normally used only by device drivers,
but you can create a wildcard <SPAN
CLASS="QUOTE"
>"matches anything"</SPAN
> usb_device_id
as a driver's <SPAN
CLASS="QUOTE"
>"modules.usbmap"</SPAN
> entry if you provide an id with
only a nonzero <SPAN
CLASS="QUOTE"
>"driver_info"</SPAN
> field. If you do this, the USB device
driver's <TT
CLASS="FUNCTION"
>probe</TT
> routine should use additional intelligence to
decide whether to bind to the specified interface.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12540"
></A
><H2
>What Makes Good usb_device_id Tables</H2
><P
> </P
><P
> 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.
</P
><P
> 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.
</P
><P
> 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.
</P
><P
> 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).
</P
><P
> 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.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="r12462.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="r12548.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><SPAN
CLASS="phrase"
><SPAN
CLASS="PHRASE"
>usb_deregister_bus</SPAN
></SPAN
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c12300.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><SPAN
CLASS="phrase"
><SPAN
CLASS="PHRASE"
>usb_alloc_urb</SPAN
></SPAN
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
