the Interface Reference

Detailed Description

class_dev_iter_init - initialize class device iterator : class iterator to initialize wanna iterate over : the device to start iterating from, if any : device_type of the devices to iterate over, NULL for all

Initialize class iterator such that it iterates over devices of

class_for_each_device - device iterator 're iterating : the device to start with in the list, if any. : data for the callback

class_find_device - device iterator for locating a particular device 're iterating : Device to begin with : data for the match function : function to check device

This is similar to the class_for_each_dev() function above, but it returns a reference to a device that is 'found' for later use, as determined by the callback.

The callback should return 0 if the device doesn't match and non-zero if it does. If the callback returns non-zero, this function will return to the caller and not iterate over any more devices.

Note, you will need to drop the reference with put_device() after use.

to the device is incremented and a pointer to its device structure is returned. Otherwise, NULL is returned. A new search is initiated by passing NULL as the argument. Otherwise if is not NULL, searches continue from next device on the global list. The reference count for is always decremented if it is not NULL.

usb_match_id - find first usb_device_id matching device or interface interest : array of usb_device_id structures, terminated by zero entry

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

Note that an entry created by USB_INTERFACE_INFO won't match any interface if the device class is set to Vendor-Specific. This is deliberate; according to the USB spec the meanings of the interface class/subclass/protocol for these devices are also vendor-specific, and hence matching against a standard product class wouldn't work anyway. If you really want to use an interface-based match for such a device, create a match record that also specifies the vendor ID. (Unforunately there isn't a standard macro for creating records like this.)

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.

usb_set_interface - Makes a particular alternate setting be current : the device whose interface is being updated updated : the setting being chosen. Context: !in_interrupt ()

This is used to enable data transfers on interfaces that may not be enabled by default. Not all devices support such configurability. Only the driver bound to an interface may change its setting.

Within any given configuration, each interface may have several alternative settings. These are often used to control levels of bandwidth consumption. For example, the default setting for a high speed interrupt endpoint may not send more than 64 bytes per microframe, while interrupt transfers of up to 3KBytes per microframe are legal. Also, isochronous endpoints may never be part of an interface's default setting. To access such bandwidth, alternate interface settings must be made current.

Note that in the Linux USB subsystem, bandwidth associated with an endpoint in a given alternate setting is not reserved until an URB is submitted that needs that bandwidth. Some other operating systems allocate bandwidth early, when a configuration is chosen.

This call is synchronous, and may not be used in an interrupt context. Also, drivers must not change altsettings while urbs are scheduled for endpoints in that interface; all such urbs must first be completed (perhaps forced by unlinking).

Returns zero on success, or else the status code returned by the underlying usb_control_msg() call.

---

The documentation for this interface was generated from the following file:

• drivers/base/class.c