rust/kernel/usb.rs - pub/scm/linux/kernel/git/phy/linux-phy - Git at Google

 // SPDX-License-Identifier: GPL-2.0
 // SPDX-FileCopyrightText: Copyright (C) 2025 Collabora Ltd.

 //! Abstractions for the USB bus.
 //!
 //! C header: [`include/linux/usb.h`](srctree/include/linux/usb.h)

 use crate::{
     bindings, device,
     device_id::{RawDeviceId, RawDeviceIdIndex},
     driver,
     error::{from_result, to_result, Result},
     prelude::*,
     str::CStr,
     types::{AlwaysRefCounted, Opaque},
     ThisModule,
 };
 use core::{marker::PhantomData, mem::MaybeUninit, ptr::NonNull};

 /// An adapter for the registration of USB drivers.
 pub struct Adapter<T: Driver>(T);

 // SAFETY: A call to `unregister` for a given instance of `RegType` is guaranteed to be valid if
 // a preceding call to `register` has been successful.
 unsafe impl<T: Driver + 'static> driver::RegistrationOps for Adapter<T> {
     type RegType = bindings::usb_driver;

     unsafe fn register(
         udrv: &Opaque<Self::RegType>,
         name: &'static CStr,
         module: &'static ThisModule,
     ) -> Result {
         // SAFETY: It's safe to set the fields of `struct usb_driver` on initialization.
         unsafe {
             (*udrv.get()).name = name.as_char_ptr();
             (*udrv.get()).probe = Some(Self::probe_callback);
             (*udrv.get()).disconnect = Some(Self::disconnect_callback);
             (*udrv.get()).id_table = T::ID_TABLE.as_ptr();
         }

         // SAFETY: `udrv` is guaranteed to be a valid `RegType`.
         to_result(unsafe {
             bindings::usb_register_driver(udrv.get(), module.0, name.as_char_ptr())
         })
     }

     unsafe fn unregister(udrv: &Opaque<Self::RegType>) {
         // SAFETY: `udrv` is guaranteed to be a valid `RegType`.
         unsafe { bindings::usb_deregister(udrv.get()) };
     }
 }

 impl<T: Driver + 'static> Adapter<T> {
     extern "C" fn probe_callback(
         intf: *mut bindings::usb_interface,
         id: *const bindings::usb_device_id,
     ) -> kernel::ffi::c_int {
         // SAFETY: The USB core only ever calls the probe callback with a valid pointer to a
         // `struct usb_interface` and `struct usb_device_id`.
         //
         // INVARIANT: `intf` is valid for the duration of `probe_callback()`.
         let intf = unsafe { &*intf.cast::<Interface<device::CoreInternal>>() };

         from_result(|| {
             // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct usb_device_id` and
             // does not add additional invariants, so it's safe to transmute.
             let id = unsafe { &*id.cast::<DeviceId>() };

             let info = T::ID_TABLE.info(id.index());
             let data = T::probe(intf, id, info)?;

             let dev: &device::Device<device::CoreInternal> = intf.as_ref();
             dev.set_drvdata(data);
             Ok(0)
         })
     }

     extern "C" fn disconnect_callback(intf: *mut bindings::usb_interface) {
         // SAFETY: The USB core only ever calls the disconnect callback with a valid pointer to a
         // `struct usb_interface`.
         //
         // INVARIANT: `intf` is valid for the duration of `disconnect_callback()`.
         let intf = unsafe { &*intf.cast::<Interface<device::CoreInternal>>() };

         let dev: &device::Device<device::CoreInternal> = intf.as_ref();

         // SAFETY: `disconnect_callback` is only ever called after a successful call to
         // `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called
         // and stored a `Pin<KBox<T>>`.
         let data = unsafe { dev.drvdata_obtain::<Pin<KBox<T>>>() };

         T::disconnect(intf, data.as_ref());
     }
 }

 /// Abstraction for the USB device ID structure, i.e. [`struct usb_device_id`].
 ///
 /// [`struct usb_device_id`]: https://docs.kernel.org/driver-api/basics.html#c.usb_device_id
 #[repr(transparent)]
 #[derive(Clone, Copy)]
 pub struct DeviceId(bindings::usb_device_id);

 impl DeviceId {
     /// Equivalent to C's `USB_DEVICE` macro.
     pub const fn from_id(vendor: u16, product: u16) -> Self {
         Self(bindings::usb_device_id {
             match_flags: bindings::USB_DEVICE_ID_MATCH_DEVICE as u16,
             idVendor: vendor,
             idProduct: product,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_VER` macro.
     pub const fn from_device_ver(vendor: u16, product: u16, bcd_lo: u16, bcd_hi: u16) -> Self {
         Self(bindings::usb_device_id {
             match_flags: bindings::USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION as u16,
             idVendor: vendor,
             idProduct: product,
             bcdDevice_lo: bcd_lo,
             bcdDevice_hi: bcd_hi,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_INFO` macro.
     pub const fn from_device_info(class: u8, subclass: u8, protocol: u8) -> Self {
         Self(bindings::usb_device_id {
             match_flags: bindings::USB_DEVICE_ID_MATCH_DEV_INFO as u16,
             bDeviceClass: class,
             bDeviceSubClass: subclass,
             bDeviceProtocol: protocol,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_INTERFACE_INFO` macro.
     pub const fn from_interface_info(class: u8, subclass: u8, protocol: u8) -> Self {
         Self(bindings::usb_device_id {
             match_flags: bindings::USB_DEVICE_ID_MATCH_INT_INFO as u16,
             bInterfaceClass: class,
             bInterfaceSubClass: subclass,
             bInterfaceProtocol: protocol,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_INTERFACE_CLASS` macro.
     pub const fn from_device_interface_class(vendor: u16, product: u16, class: u8) -> Self {
         Self(bindings::usb_device_id {
             match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
                 | bindings::USB_DEVICE_ID_MATCH_INT_CLASS) as u16,
             idVendor: vendor,
             idProduct: product,
             bInterfaceClass: class,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_INTERFACE_PROTOCOL` macro.
     pub const fn from_device_interface_protocol(vendor: u16, product: u16, protocol: u8) -> Self {
         Self(bindings::usb_device_id {
             match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
                 | bindings::USB_DEVICE_ID_MATCH_INT_PROTOCOL) as u16,
             idVendor: vendor,
             idProduct: product,
             bInterfaceProtocol: protocol,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_INTERFACE_NUMBER` macro.
     pub const fn from_device_interface_number(vendor: u16, product: u16, number: u8) -> Self {
         Self(bindings::usb_device_id {
             match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
                 | bindings::USB_DEVICE_ID_MATCH_INT_NUMBER) as u16,
             idVendor: vendor,
             idProduct: product,
             bInterfaceNumber: number,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }

     /// Equivalent to C's `USB_DEVICE_AND_INTERFACE_INFO` macro.
     pub const fn from_device_and_interface_info(
         vendor: u16,
         product: u16,
         class: u8,
         subclass: u8,
         protocol: u8,
     ) -> Self {
         Self(bindings::usb_device_id {
             match_flags: (bindings::USB_DEVICE_ID_MATCH_INT_INFO
                 | bindings::USB_DEVICE_ID_MATCH_DEVICE) as u16,
             idVendor: vendor,
             idProduct: product,
             bInterfaceClass: class,
             bInterfaceSubClass: subclass,
             bInterfaceProtocol: protocol,
             // SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
             ..unsafe { MaybeUninit::zeroed().assume_init() }
         })
     }
 }

 // SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `usb_device_id` and does not add
 // additional invariants, so it's safe to transmute to `RawType`.
 unsafe impl RawDeviceId for DeviceId {
     type RawType = bindings::usb_device_id;
 }

 // SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_info` field.
 unsafe impl RawDeviceIdIndex for DeviceId {
     const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::usb_device_id, driver_info);

     fn index(&self) -> usize {
         self.0.driver_info
     }
 }

 /// [`IdTable`](kernel::device_id::IdTable) type for USB.
 pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;

 /// Create a USB `IdTable` with its alias for modpost.
 #[macro_export]
 macro_rules! usb_device_table {
     ($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
         const $table_name: $crate::device_id::IdArray<
             $crate::usb::DeviceId,
             $id_info_type,
             { $table_data.len() },
         > = $crate::device_id::IdArray::new($table_data);

         $crate::module_device_table!("usb", $module_table_name, $table_name);
     };
 }

 /// The USB driver trait.
 ///
 /// # Examples
 ///
 ///```
 /// # use kernel::{bindings, device::Core, usb};
 /// use kernel::prelude::*;
 ///
 /// struct MyDriver;
 ///
 /// kernel::usb_device_table!(
 ///     USB_TABLE,
 ///     MODULE_USB_TABLE,
 ///     <MyDriver as usb::Driver>::IdInfo,
 ///     [
 ///         (usb::DeviceId::from_id(0x1234, 0x5678), ()),
 ///         (usb::DeviceId::from_id(0xabcd, 0xef01), ()),
 ///     ]
 /// );
 ///
 /// impl usb::Driver for MyDriver {
 ///     type IdInfo = ();
 ///     const ID_TABLE: usb::IdTable<Self::IdInfo> = &USB_TABLE;
 ///
 ///     fn probe(
 ///         _interface: &usb::Interface<Core>,
 ///         _id: &usb::DeviceId,
 ///         _info: &Self::IdInfo,
 ///     ) -> Result<Pin<KBox<Self>>> {
 ///         Err(ENODEV)
 ///     }
 ///
 ///     fn disconnect(_interface: &usb::Interface<Core>, _data: Pin<&Self>) {}
 /// }
 ///```
 pub trait Driver {
     /// The type holding information about each one of the device ids supported by the driver.
     type IdInfo: 'static;

     /// The table of device ids supported by the driver.
     const ID_TABLE: IdTable<Self::IdInfo>;

     /// USB driver probe.
     ///
     /// Called when a new USB interface is bound to this driver.
     /// Implementers should attempt to initialize the interface here.
     fn probe(
         interface: &Interface<device::Core>,
         id: &DeviceId,
         id_info: &Self::IdInfo,
     ) -> Result<Pin<KBox<Self>>>;

     /// USB driver disconnect.
     ///
     /// Called when the USB interface is about to be unbound from this driver.
     fn disconnect(interface: &Interface<device::Core>, data: Pin<&Self>);
 }

 /// A USB interface.
 ///
 /// This structure represents the Rust abstraction for a C [`struct usb_interface`].
 /// The implementation abstracts the usage of a C [`struct usb_interface`] passed
 /// in from the C side.
 ///
 /// # Invariants
 ///
 /// An [`Interface`] instance represents a valid [`struct usb_interface`] created
 /// by the C portion of the kernel.
 ///
 /// [`struct usb_interface`]: https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#c.usb_interface
 #[repr(transparent)]
 pub struct Interface<Ctx: device::DeviceContext = device::Normal>(
     Opaque<bindings::usb_interface>,
     PhantomData<Ctx>,
 );

 impl<Ctx: device::DeviceContext> Interface<Ctx> {
     fn as_raw(&self) -> *mut bindings::usb_interface {
         self.0.get()
     }
 }

 // SAFETY: `Interface` is a transparent wrapper of a type that doesn't depend on
 // `Interface`'s generic argument.
 kernel::impl_device_context_deref!(unsafe { Interface });
 kernel::impl_device_context_into_aref!(Interface);

 impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Interface<Ctx> {
     fn as_ref(&self) -> &device::Device<Ctx> {
         // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
         // `struct usb_interface`.
         let dev = unsafe { &raw mut ((*self.as_raw()).dev) };

         // SAFETY: `dev` points to a valid `struct device`.
         unsafe { device::Device::from_raw(dev) }
     }
 }

 impl<Ctx: device::DeviceContext> AsRef<Device> for Interface<Ctx> {
     fn as_ref(&self) -> &Device {
         // SAFETY: `self.as_raw()` is valid by the type invariants.
         let usb_dev = unsafe { bindings::interface_to_usbdev(self.as_raw()) };

         // SAFETY: For a valid `struct usb_interface` pointer, the above call to
         // `interface_to_usbdev()` guarantees to return a valid pointer to a `struct usb_device`.
         unsafe { &*(usb_dev.cast()) }
     }
 }

 // SAFETY: Instances of `Interface` are always reference-counted.
 unsafe impl AlwaysRefCounted for Interface {
     fn inc_ref(&self) {
         // SAFETY: The invariants of `Interface` guarantee that `self.as_raw()`
         // returns a valid `struct usb_interface` pointer, for which we will
         // acquire a new refcount.
         unsafe { bindings::usb_get_intf(self.as_raw()) };
     }

     unsafe fn dec_ref(obj: NonNull<Self>) {
         // SAFETY: The safety requirements guarantee that the refcount is non-zero.
         unsafe { bindings::usb_put_intf(obj.cast().as_ptr()) }
     }
 }

 // SAFETY: A `Interface` is always reference-counted and can be released from any thread.
 unsafe impl Send for Interface {}

 // SAFETY: It is safe to send a &Interface to another thread because we do not
 // allow any mutation through a shared reference.
 unsafe impl Sync for Interface {}

 /// A USB device.
 ///
 /// This structure represents the Rust abstraction for a C [`struct usb_device`].
 /// The implementation abstracts the usage of a C [`struct usb_device`] passed in
 /// from the C side.
 ///
 /// # Invariants
 ///
 /// A [`Device`] instance represents a valid [`struct usb_device`] created by the C portion of the
 /// kernel.
 ///
 /// [`struct usb_device`]: https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#c.usb_device
 #[repr(transparent)]
 struct Device<Ctx: device::DeviceContext = device::Normal>(
     Opaque<bindings::usb_device>,
     PhantomData<Ctx>,
 );

 impl<Ctx: device::DeviceContext> Device<Ctx> {
     fn as_raw(&self) -> *mut bindings::usb_device {
         self.0.get()
     }
 }

 // SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
 // argument.
 kernel::impl_device_context_deref!(unsafe { Device });
 kernel::impl_device_context_into_aref!(Device);

 // SAFETY: Instances of `Device` are always reference-counted.
 unsafe impl AlwaysRefCounted for Device {
     fn inc_ref(&self) {
         // SAFETY: The invariants of `Device` guarantee that `self.as_raw()`
         // returns a valid `struct usb_device` pointer, for which we will
         // acquire a new refcount.
         unsafe { bindings::usb_get_dev(self.as_raw()) };
     }

     unsafe fn dec_ref(obj: NonNull<Self>) {
         // SAFETY: The safety requirements guarantee that the refcount is non-zero.
         unsafe { bindings::usb_put_dev(obj.cast().as_ptr()) }
     }
 }

 impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
     fn as_ref(&self) -> &device::Device<Ctx> {
         // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
         // `struct usb_device`.
         let dev = unsafe { &raw mut ((*self.as_raw()).dev) };

         // SAFETY: `dev` points to a valid `struct device`.
         unsafe { device::Device::from_raw(dev) }
     }
 }

 // SAFETY: A `Device` is always reference-counted and can be released from any thread.
 unsafe impl Send for Device {}

 // SAFETY: It is safe to send a &Device to another thread because we do not
 // allow any mutation through a shared reference.
 unsafe impl Sync for Device {}

 /// Declares a kernel module that exposes a single USB driver.
 ///
 /// # Examples
 ///
 /// ```ignore
 /// module_usb_driver! {
 ///     type: MyDriver,
 ///     name: "Module name",
 ///     author: ["Author name"],
 ///     description: "Description",
 ///     license: "GPL v2",
 /// }
 /// ```
 #[macro_export]
 macro_rules! module_usb_driver {
     ($($f:tt)*) => {
         $crate::module_driver!(<T>, $crate::usb::Adapter<T>, { $($f)* });
     }
 }
	// SPDX-License-Identifier: GPL-2.0
	// SPDX-FileCopyrightText: Copyright (C) 2025 Collabora Ltd.

	//! Abstractions for the USB bus.
	//!
	//! C header: [`include/linux/usb.h`](srctree/include/linux/usb.h)

	use crate::{
	bindings, device,
	device_id::{RawDeviceId, RawDeviceIdIndex},
	driver,
	error::{from_result, to_result, Result},
	prelude::*,
	str::CStr,
	types::{AlwaysRefCounted, Opaque},
	ThisModule,
	};
	use core::{marker::PhantomData, mem::MaybeUninit, ptr::NonNull};

	/// An adapter for the registration of USB drivers.
	pub struct Adapter<T: Driver>(T);

	// SAFETY: A call to `unregister` for a given instance of `RegType` is guaranteed to be valid if
	// a preceding call to `register` has been successful.
	unsafe impl<T: Driver + 'static> driver::RegistrationOps for Adapter<T> {
	type RegType = bindings::usb_driver;

	unsafe fn register(
	udrv: &Opaque<Self::RegType>,
	name: &'static CStr,
	module: &'static ThisModule,
	) -> Result {
	// SAFETY: It's safe to set the fields of `struct usb_driver` on initialization.
	unsafe {
	(*udrv.get()).name = name.as_char_ptr();
	(*udrv.get()).probe = Some(Self::probe_callback);
	(*udrv.get()).disconnect = Some(Self::disconnect_callback);
	(*udrv.get()).id_table = T::ID_TABLE.as_ptr();
	}

	// SAFETY: `udrv` is guaranteed to be a valid `RegType`.
	to_result(unsafe {
	bindings::usb_register_driver(udrv.get(), module.0, name.as_char_ptr())
	})
	}

	unsafe fn unregister(udrv: &Opaque<Self::RegType>) {
	// SAFETY: `udrv` is guaranteed to be a valid `RegType`.
	unsafe { bindings::usb_deregister(udrv.get()) };
	}
	}

	impl<T: Driver + 'static> Adapter<T> {
	extern "C" fn probe_callback(
	intf: *mut bindings::usb_interface,
	id: *const bindings::usb_device_id,
	) -> kernel::ffi::c_int {
	// SAFETY: The USB core only ever calls the probe callback with a valid pointer to a
	// `struct usb_interface` and `struct usb_device_id`.
	//
	// INVARIANT: `intf` is valid for the duration of `probe_callback()`.
	let intf = unsafe { &*intf.cast::<Interface<device::CoreInternal>>() };

	from_result(\|\| {
	// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `struct usb_device_id` and
	// does not add additional invariants, so it's safe to transmute.
	let id = unsafe { &*id.cast::<DeviceId>() };

	let info = T::ID_TABLE.info(id.index());
	let data = T::probe(intf, id, info)?;

	let dev: &device::Device<device::CoreInternal> = intf.as_ref();
	dev.set_drvdata(data);
	Ok(0)
	})
	}

	extern "C" fn disconnect_callback(intf: *mut bindings::usb_interface) {
	// SAFETY: The USB core only ever calls the disconnect callback with a valid pointer to a
	// `struct usb_interface`.
	//
	// INVARIANT: `intf` is valid for the duration of `disconnect_callback()`.
	let intf = unsafe { &*intf.cast::<Interface<device::CoreInternal>>() };

	let dev: &device::Device<device::CoreInternal> = intf.as_ref();

	// SAFETY: `disconnect_callback` is only ever called after a successful call to
	// `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called
	// and stored a `Pin<KBox<T>>`.
	let data = unsafe { dev.drvdata_obtain::<Pin<KBox<T>>>() };

	T::disconnect(intf, data.as_ref());
	}
	}

	/// Abstraction for the USB device ID structure, i.e. [`struct usb_device_id`].
	///
	/// [`struct usb_device_id`]: https://docs.kernel.org/driver-api/basics.html#c.usb_device_id
	#[repr(transparent)]
	#[derive(Clone, Copy)]
	pub struct DeviceId(bindings::usb_device_id);

	impl DeviceId {
	/// Equivalent to C's `USB_DEVICE` macro.
	pub const fn from_id(vendor: u16, product: u16) -> Self {
	Self(bindings::usb_device_id {
	match_flags: bindings::USB_DEVICE_ID_MATCH_DEVICE as u16,
	idVendor: vendor,
	idProduct: product,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_VER` macro.
	pub const fn from_device_ver(vendor: u16, product: u16, bcd_lo: u16, bcd_hi: u16) -> Self {
	Self(bindings::usb_device_id {
	match_flags: bindings::USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION as u16,
	idVendor: vendor,
	idProduct: product,
	bcdDevice_lo: bcd_lo,
	bcdDevice_hi: bcd_hi,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_INFO` macro.
	pub const fn from_device_info(class: u8, subclass: u8, protocol: u8) -> Self {
	Self(bindings::usb_device_id {
	match_flags: bindings::USB_DEVICE_ID_MATCH_DEV_INFO as u16,
	bDeviceClass: class,
	bDeviceSubClass: subclass,
	bDeviceProtocol: protocol,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_INTERFACE_INFO` macro.
	pub const fn from_interface_info(class: u8, subclass: u8, protocol: u8) -> Self {
	Self(bindings::usb_device_id {
	match_flags: bindings::USB_DEVICE_ID_MATCH_INT_INFO as u16,
	bInterfaceClass: class,
	bInterfaceSubClass: subclass,
	bInterfaceProtocol: protocol,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_INTERFACE_CLASS` macro.
	pub const fn from_device_interface_class(vendor: u16, product: u16, class: u8) -> Self {
	Self(bindings::usb_device_id {
	match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
	\| bindings::USB_DEVICE_ID_MATCH_INT_CLASS) as u16,
	idVendor: vendor,
	idProduct: product,
	bInterfaceClass: class,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_INTERFACE_PROTOCOL` macro.
	pub const fn from_device_interface_protocol(vendor: u16, product: u16, protocol: u8) -> Self {
	Self(bindings::usb_device_id {
	match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
	\| bindings::USB_DEVICE_ID_MATCH_INT_PROTOCOL) as u16,
	idVendor: vendor,
	idProduct: product,
	bInterfaceProtocol: protocol,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_INTERFACE_NUMBER` macro.
	pub const fn from_device_interface_number(vendor: u16, product: u16, number: u8) -> Self {
	Self(bindings::usb_device_id {
	match_flags: (bindings::USB_DEVICE_ID_MATCH_DEVICE
	\| bindings::USB_DEVICE_ID_MATCH_INT_NUMBER) as u16,
	idVendor: vendor,
	idProduct: product,
	bInterfaceNumber: number,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}

	/// Equivalent to C's `USB_DEVICE_AND_INTERFACE_INFO` macro.
	pub const fn from_device_and_interface_info(
	vendor: u16,
	product: u16,
	class: u8,
	subclass: u8,
	protocol: u8,
	) -> Self {
	Self(bindings::usb_device_id {
	match_flags: (bindings::USB_DEVICE_ID_MATCH_INT_INFO
	\| bindings::USB_DEVICE_ID_MATCH_DEVICE) as u16,
	idVendor: vendor,
	idProduct: product,
	bInterfaceClass: class,
	bInterfaceSubClass: subclass,
	bInterfaceProtocol: protocol,
	// SAFETY: It is safe to use all zeroes for the other fields of `usb_device_id`.
	..unsafe { MaybeUninit::zeroed().assume_init() }
	})
	}
	}

	// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `usb_device_id` and does not add
	// additional invariants, so it's safe to transmute to `RawType`.
	unsafe impl RawDeviceId for DeviceId {
	type RawType = bindings::usb_device_id;
	}

	// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_info` field.
	unsafe impl RawDeviceIdIndex for DeviceId {
	const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::usb_device_id, driver_info);

	fn index(&self) -> usize {
	self.0.driver_info
	}
	}

	/// [`IdTable`](kernel::device_id::IdTable) type for USB.
	pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;

	/// Create a USB `IdTable` with its alias for modpost.
	#[macro_export]
	macro_rules! usb_device_table {
	($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
	const $table_name: $crate::device_id::IdArray<
	$crate::usb::DeviceId,
	$id_info_type,
	{ $table_data.len() },
	> = $crate::device_id::IdArray::new($table_data);

	$crate::module_device_table!("usb", $module_table_name, $table_name);
	};
	}

	/// The USB driver trait.
	///
	/// # Examples
	///
	///```
	/// # use kernel::{bindings, device::Core, usb};
	/// use kernel::prelude::*;
	///
	/// struct MyDriver;
	///
	/// kernel::usb_device_table!(
	/// USB_TABLE,
	/// MODULE_USB_TABLE,
	/// <MyDriver as usb::Driver>::IdInfo,
	/// [
	/// (usb::DeviceId::from_id(0x1234, 0x5678), ()),
	/// (usb::DeviceId::from_id(0xabcd, 0xef01), ()),
	/// ]
	/// );
	///
	/// impl usb::Driver for MyDriver {
	/// type IdInfo = ();
	/// const ID_TABLE: usb::IdTable<Self::IdInfo> = &USB_TABLE;
	///
	/// fn probe(
	/// _interface: &usb::Interface<Core>,
	/// _id: &usb::DeviceId,
	/// _info: &Self::IdInfo,
	/// ) -> Result<Pin<KBox<Self>>> {
	/// Err(ENODEV)
	/// }
	///
	/// fn disconnect(_interface: &usb::Interface<Core>, _data: Pin<&Self>) {}
	/// }
	///```
	pub trait Driver {
	/// The type holding information about each one of the device ids supported by the driver.
	type IdInfo: 'static;

	/// The table of device ids supported by the driver.
	const ID_TABLE: IdTable<Self::IdInfo>;

	/// USB driver probe.
	///
	/// Called when a new USB interface is bound to this driver.
	/// Implementers should attempt to initialize the interface here.
	fn probe(
	interface: &Interface<device::Core>,
	id: &DeviceId,
	id_info: &Self::IdInfo,
	) -> Result<Pin<KBox<Self>>>;

	/// USB driver disconnect.
	///
	/// Called when the USB interface is about to be unbound from this driver.
	fn disconnect(interface: &Interface<device::Core>, data: Pin<&Self>);
	}

	/// A USB interface.
	///
	/// This structure represents the Rust abstraction for a C [`struct usb_interface`].
	/// The implementation abstracts the usage of a C [`struct usb_interface`] passed
	/// in from the C side.
	///
	/// # Invariants
	///
	/// An [`Interface`] instance represents a valid [`struct usb_interface`] created
	/// by the C portion of the kernel.
	///
	/// [`struct usb_interface`]: https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#c.usb_interface
	#[repr(transparent)]
	pub struct Interface<Ctx: device::DeviceContext = device::Normal>(
	Opaque<bindings::usb_interface>,
	PhantomData<Ctx>,
	);

	impl<Ctx: device::DeviceContext> Interface<Ctx> {
	fn as_raw(&self) -> *mut bindings::usb_interface {
	self.0.get()
	}
	}

	// SAFETY: `Interface` is a transparent wrapper of a type that doesn't depend on
	// `Interface`'s generic argument.
	kernel::impl_device_context_deref!(unsafe { Interface });
	kernel::impl_device_context_into_aref!(Interface);

	impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Interface<Ctx> {
	fn as_ref(&self) -> &device::Device<Ctx> {
	// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
	// `struct usb_interface`.
	let dev = unsafe { &raw mut ((*self.as_raw()).dev) };

	// SAFETY: `dev` points to a valid `struct device`.
	unsafe { device::Device::from_raw(dev) }
	}
	}

	impl<Ctx: device::DeviceContext> AsRef<Device> for Interface<Ctx> {
	fn as_ref(&self) -> &Device {
	// SAFETY: `self.as_raw()` is valid by the type invariants.
	let usb_dev = unsafe { bindings::interface_to_usbdev(self.as_raw()) };

	// SAFETY: For a valid `struct usb_interface` pointer, the above call to
	// `interface_to_usbdev()` guarantees to return a valid pointer to a `struct usb_device`.
	unsafe { &*(usb_dev.cast()) }
	}
	}

	// SAFETY: Instances of `Interface` are always reference-counted.
	unsafe impl AlwaysRefCounted for Interface {
	fn inc_ref(&self) {
	// SAFETY: The invariants of `Interface` guarantee that `self.as_raw()`
	// returns a valid `struct usb_interface` pointer, for which we will
	// acquire a new refcount.
	unsafe { bindings::usb_get_intf(self.as_raw()) };
	}

	unsafe fn dec_ref(obj: NonNull<Self>) {
	// SAFETY: The safety requirements guarantee that the refcount is non-zero.
	unsafe { bindings::usb_put_intf(obj.cast().as_ptr()) }
	}
	}

	// SAFETY: A `Interface` is always reference-counted and can be released from any thread.
	unsafe impl Send for Interface {}

	// SAFETY: It is safe to send a &Interface to another thread because we do not
	// allow any mutation through a shared reference.
	unsafe impl Sync for Interface {}

	/// A USB device.
	///
	/// This structure represents the Rust abstraction for a C [`struct usb_device`].
	/// The implementation abstracts the usage of a C [`struct usb_device`] passed in
	/// from the C side.
	///
	/// # Invariants
	///
	/// A [`Device`] instance represents a valid [`struct usb_device`] created by the C portion of the
	/// kernel.
	///
	/// [`struct usb_device`]: https://www.kernel.org/doc/html/latest/driver-api/usb/usb.html#c.usb_device
	#[repr(transparent)]
	struct Device<Ctx: device::DeviceContext = device::Normal>(
	Opaque<bindings::usb_device>,
	PhantomData<Ctx>,
	);

	impl<Ctx: device::DeviceContext> Device<Ctx> {
	fn as_raw(&self) -> *mut bindings::usb_device {
	self.0.get()
	}
	}

	// SAFETY: `Device` is a transparent wrapper of a type that doesn't depend on `Device`'s generic
	// argument.
	kernel::impl_device_context_deref!(unsafe { Device });
	kernel::impl_device_context_into_aref!(Device);

	// SAFETY: Instances of `Device` are always reference-counted.
	unsafe impl AlwaysRefCounted for Device {
	fn inc_ref(&self) {
	// SAFETY: The invariants of `Device` guarantee that `self.as_raw()`
	// returns a valid `struct usb_device` pointer, for which we will
	// acquire a new refcount.
	unsafe { bindings::usb_get_dev(self.as_raw()) };
	}

	unsafe fn dec_ref(obj: NonNull<Self>) {
	// SAFETY: The safety requirements guarantee that the refcount is non-zero.
	unsafe { bindings::usb_put_dev(obj.cast().as_ptr()) }
	}
	}

	impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
	fn as_ref(&self) -> &device::Device<Ctx> {
	// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
	// `struct usb_device`.
	let dev = unsafe { &raw mut ((*self.as_raw()).dev) };

	// SAFETY: `dev` points to a valid `struct device`.
	unsafe { device::Device::from_raw(dev) }
	}
	}

	// SAFETY: A `Device` is always reference-counted and can be released from any thread.
	unsafe impl Send for Device {}

	// SAFETY: It is safe to send a &Device to another thread because we do not
	// allow any mutation through a shared reference.
	unsafe impl Sync for Device {}

	/// Declares a kernel module that exposes a single USB driver.
	///
	/// # Examples
	///
	/// ```ignore
	/// module_usb_driver! {
	/// type: MyDriver,
	/// name: "Module name",
	/// author: ["Author name"],
	/// description: "Description",
	/// license: "GPL v2",
	/// }
	/// ```
	#[macro_export]
	macro_rules! module_usb_driver {
	($($f:tt)*) => {
	$crate::module_driver!(<T>, $crate::usb::Adapter<T>, { $($f)* });
	}
	}