Provided by: kernel-doc-2.4.27_2.4.27-12_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_device *dev,
       struct usb_interface *interface, const struct usb_device_id *id);

ARGUMENTS

       dev          the device whose descriptors are considered when matching

       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.