kernel/
device_id.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Generic implementation of device IDs.
4//!
5//! Each bus / subsystem that matches device and driver through a bus / subsystem specific ID is
6//! expected to implement [`RawDeviceId`].
7
8use core::mem::MaybeUninit;
9
10/// Marker trait to indicate a Rust device ID type represents a corresponding C device ID type.
11///
12/// This is meant to be implemented by buses/subsystems so that they can use [`IdTable`] to
13/// guarantee (at compile-time) zero-termination of device id tables provided by drivers.
14///
15/// # Safety
16///
17/// Implementers must ensure that `Self` is layout-compatible with [`RawDeviceId::RawType`];
18/// i.e. it's safe to transmute to `RawDeviceId`.
19///
20/// This requirement is needed so `IdArray::new` can convert `Self` to `RawType` when building
21/// the ID table.
22///
23/// Ideally, this should be achieved using a const function that does conversion instead of
24/// transmute; however, const trait functions relies on `const_trait_impl` unstable feature,
25/// which is broken/gone in Rust 1.73.
26pub unsafe trait RawDeviceId {
27    /// The raw type that holds the device id.
28    ///
29    /// Id tables created from [`Self`] are going to hold this type in its zero-terminated array.
30    type RawType: Copy;
31}
32
33/// Extension trait for [`RawDeviceId`] for devices that embed an index or context value.
34///
35/// This is typically used when the device ID struct includes a field like `driver_data`
36/// that is used to store a pointer-sized value (e.g., an index or context pointer).
37///
38/// # Safety
39///
40/// Implementers must ensure that `DRIVER_DATA_OFFSET` is the correct offset (in bytes) to
41/// the context/data field (e.g., the `driver_data` field) within the raw device ID structure.
42/// This field must be correctly sized to hold a `usize`.
43///
44/// Ideally, the data should be added during `Self` to `RawType` conversion,
45/// but there's currently no way to do it when using traits in const.
46pub unsafe trait RawDeviceIdIndex: RawDeviceId {
47    /// The offset (in bytes) to the context/data field in the raw device ID.
48    const DRIVER_DATA_OFFSET: usize;
49
50    /// The index stored at `DRIVER_DATA_OFFSET` of the implementor of the [`RawDeviceIdIndex`]
51    /// trait.
52    fn index(&self) -> usize;
53}
54
55/// A zero-terminated device id array.
56#[repr(C)]
57pub struct RawIdArray<T: RawDeviceId, const N: usize> {
58    ids: [T::RawType; N],
59    sentinel: MaybeUninit<T::RawType>,
60}
61
62impl<T: RawDeviceId, const N: usize> RawIdArray<T, N> {
63    #[doc(hidden)]
64    pub const fn size(&self) -> usize {
65        core::mem::size_of::<Self>()
66    }
67}
68
69/// A zero-terminated device id array, followed by context data.
70#[repr(C)]
71pub struct IdArray<T: RawDeviceId, U, const N: usize> {
72    raw_ids: RawIdArray<T, N>,
73    id_infos: [U; N],
74}
75
76impl<T: RawDeviceId, U, const N: usize> IdArray<T, U, N> {
77    /// Creates a new instance of the array.
78    ///
79    /// The contents are derived from the given identifiers and context information.
80    ///
81    /// # Safety
82    ///
83    /// `data_offset` as `None` is always safe.
84    /// If `data_offset` is `Some(data_offset)`, then:
85    /// - `data_offset` must be the correct offset (in bytes) to the context/data field
86    ///   (e.g., the `driver_data` field) within the raw device ID structure.
87    /// - The field at `data_offset` must be correctly sized to hold a `usize`.
88    const unsafe fn build(ids: [(T, U); N], data_offset: Option<usize>) -> Self {
89        let mut raw_ids = [const { MaybeUninit::<T::RawType>::uninit() }; N];
90        let mut infos = [const { MaybeUninit::uninit() }; N];
91
92        let mut i = 0usize;
93        while i < N {
94            // SAFETY: by the safety requirement of `RawDeviceId`, we're guaranteed that `T` is
95            // layout-wise compatible with `RawType`.
96            raw_ids[i] = unsafe { core::mem::transmute_copy(&ids[i].0) };
97            if let Some(data_offset) = data_offset {
98                // SAFETY: by the safety requirement of this function, this would be effectively
99                // `raw_ids[i].driver_data = i;`.
100                unsafe {
101                    raw_ids[i]
102                        .as_mut_ptr()
103                        .byte_add(data_offset)
104                        .cast::<usize>()
105                        .write(i);
106                }
107            }
108
109            // SAFETY: this is effectively a move: `infos[i] = ids[i].1`. We make a copy here but
110            // later forget `ids`.
111            infos[i] = MaybeUninit::new(unsafe { core::ptr::read(&ids[i].1) });
112            i += 1;
113        }
114
115        core::mem::forget(ids);
116
117        Self {
118            raw_ids: RawIdArray {
119                // SAFETY: this is effectively `array_assume_init`, which is unstable, so we use
120                // `transmute_copy` instead. We have initialized all elements of `raw_ids` so this
121                // `array_assume_init` is safe.
122                ids: unsafe { core::mem::transmute_copy(&raw_ids) },
123                sentinel: MaybeUninit::zeroed(),
124            },
125            // SAFETY: We have initialized all elements of `infos` so this `array_assume_init` is
126            // safe.
127            id_infos: unsafe { core::mem::transmute_copy(&infos) },
128        }
129    }
130
131    /// Creates a new instance of the array without writing index values.
132    ///
133    /// The contents are derived from the given identifiers and context information.
134    /// If the device implements [`RawDeviceIdIndex`], consider using [`IdArray::new`] instead.
135    pub const fn new_without_index(ids: [(T, U); N]) -> Self {
136        // SAFETY: Calling `Self::build` with `offset = None` is always safe,
137        // because no raw memory writes are performed in this case.
138        unsafe { Self::build(ids, None) }
139    }
140
141    /// Reference to the contained [`RawIdArray`].
142    pub const fn raw_ids(&self) -> &RawIdArray<T, N> {
143        &self.raw_ids
144    }
145}
146
147impl<T: RawDeviceId + RawDeviceIdIndex, U, const N: usize> IdArray<T, U, N> {
148    /// Creates a new instance of the array.
149    ///
150    /// The contents are derived from the given identifiers and context information.
151    pub const fn new(ids: [(T, U); N]) -> Self {
152        // SAFETY: by the safety requirement of `RawDeviceIdIndex`,
153        // `T::DRIVER_DATA_OFFSET` is guaranteed to be the correct offset (in bytes) to
154        // a field within `T::RawType`.
155        unsafe { Self::build(ids, Some(T::DRIVER_DATA_OFFSET)) }
156    }
157}
158
159/// A device id table.
160///
161/// This trait is only implemented by `IdArray`.
162///
163/// The purpose of this trait is to allow `&'static dyn IdArray<T, U>` to be in context when `N` in
164/// `IdArray` doesn't matter.
165pub trait IdTable<T: RawDeviceId, U> {
166    /// Obtain the pointer to the ID table.
167    fn as_ptr(&self) -> *const T::RawType;
168
169    /// Obtain the pointer to the bus specific device ID from an index.
170    fn id(&self, index: usize) -> &T::RawType;
171
172    /// Obtain the pointer to the driver-specific information from an index.
173    fn info(&self, index: usize) -> &U;
174}
175
176impl<T: RawDeviceId, U, const N: usize> IdTable<T, U> for IdArray<T, U, N> {
177    fn as_ptr(&self) -> *const T::RawType {
178        // This cannot be `self.ids.as_ptr()`, as the return pointer must have correct provenance
179        // to access the sentinel.
180        core::ptr::from_ref(self).cast()
181    }
182
183    fn id(&self, index: usize) -> &T::RawType {
184        &self.raw_ids.ids[index]
185    }
186
187    fn info(&self, index: usize) -> &U {
188        &self.id_infos[index]
189    }
190}
191
192/// Create device table alias for modpost.
193#[macro_export]
194macro_rules! module_device_table {
195    ($table_type: literal, $module_table_name:ident, $table_name:ident) => {
196        #[rustfmt::skip]
197        #[export_name =
198            concat!("__mod_device_table__", $table_type,
199                    "__", module_path!(),
200                    "_", line!(),
201                    "_", stringify!($table_name))
202        ]
203        static $module_table_name: [::core::mem::MaybeUninit<u8>; $table_name.raw_ids().size()] =
204            unsafe { ::core::mem::transmute_copy($table_name.raw_ids()) };
205    };
206}