Provided by: linux-doc-2.6.15_2.6.15-23.39_all bug

NAME

       usb_match_id - find first usb_device_id matching device or interface

SYNOPSIS

       const struct usb_device_id * usb_match_id  (struct usb_interface * interface,
                                                       const struct usb_device_id * id);

ARGUMENTS

       interface
              the interface of interest

       id     array of usb_device_id structures, terminated by zero entry

DESCRIPTION

       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.

WHAT MATCHES

       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.

        ‘‘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  probe
       routine should use additional intelligence to decide whether to bind to
       the specified interface.

WHAT MAKES GOOD USB_DEVICE_ID TABLES

       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.

       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.

       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.

       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).

       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.