usb_match_id(9)

💅 usb_match_id(9) — like, the Kernel API Manual bestie, we're doing this 🫶

okay so real talk, this page is usb_match_id from the Kernel API Manual and it is genuinely iconic for how much it does with so little.

---

✨ NAME ✨

usb_match_id — find the first usb_device_id that matches a device or an interface. that's it. that's the whole gig. slay.

---

🌸 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, aka the one you're vibe-checking 💅
• id — an array of usb_device_id structures, and it has to be terminated by a zero entry (do not forget the zero entry, bestie, it's how we know where the array ends 🎀)

---

👑 DESCRIPTION 👑

usb_match_id searches through an array of usb_device_id's and hands you back the first one that matches the device or the interface — or null if nothing hits. no match, no problem, you just get null.

this is what gets used when binding (or rebinding) a driver to an interface. most USB device drivers use it 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. iykyk.

⭐ what matches ⭐

the "match_flags" element in a usb_device_id controls which members are used. if the corresponding bit is set, then the value in the device_id must match its corresponding member in the device or interface descriptor — otherwise the device_id does not match. no exceptions, no partial credit.

"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 — literally, just provide an id with only a nonzero "driver_info" field. if you do that though, the USB device driver's probe routine should use additional intelligence to decide whether to bind to the specified interface. so like, you can do the wildcard thing, but you gotta be smart about it after. 🧚

💖 what makes good usb_device_id tables 💖

the match algorithm is very simple, so all the intelligence in driver selection has to 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. (use the macros. bestie. use the macros.)

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. very main character energy.

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

ngl this next bit is important: an entry created by USB_INTERFACE_INFO won't match any interface if the device class is set to Vendor-Specific. and that's deliberate, fr fr — according to the USB spec the meanings of the interface class/subclass/protocol for these devices are also vendor-specific, so 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.) 😭 yes, that's the original spelling right there, and no, i'm not fixing it, because facts are facts.

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. like, don't do that. 💀

---

🎀 RETURN 🎀

the first matching usb_device_id, or NULL. that's the whole return value, and honestly? we love a clean, unambiguous king.

---

🌈 SEE ALSO 🌈

kernel file ./drivers/usb/core/driver.c

usb_driver_claim_interface(9), usb_driver_release_interface(9), usb_register_device_driver(9), usb_deregister_device_driver(9), usb_register_driver(9), usb_deregister(9), usb_suspend_both(9), usb_resume_both(9), usb_enable_autosuspend(9), usb_disable_autosuspend(9), usb_autosuspend_device(9), usb_autoresume_device(9), usb_autopm_put_interface(9), usb_autopm_put_interface_async(9), usb_autopm_put_interface_no_suspend(9), usb_autopm_get_interface(9), usb_autopm_get_interface_async(9), usb_autopm_get_interface_no_resume(9)

---

💜 okay that's the whole page, go forth and match some ids 💜

shoutout to ./drivers/usb/core for housing all this, and to October 2026 for being the date this dropped. periodt. 🦋✨