projects/linux·blob v7.2 · refs

603 lines · 20.7 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! I2C Driver subsystem
4
5// I2C Driver abstractions.
6use crate::{
7 acpi,
8 container_of,
9 device,
10 device_id::{
11 RawDeviceId,
12 RawDeviceIdIndex, //
13 },
14 devres::Devres,
15 driver,
16 error::*,
17 of,
18 prelude::*,
19 sync::aref::{
20 ARef,
21 AlwaysRefCounted, //
22 },
23 types::Opaque, //
24};
25
26use core::{
27 marker::PhantomData,
28 mem::offset_of,
29 ptr::{
30 from_ref,
31 NonNull, //
32 }, //
33};
34
35/// An I2C device id table.
36#[repr(transparent)]
37#[derive(Clone, Copy)]
38pub struct DeviceId(bindings::i2c_device_id);
39
40impl DeviceId {
41 const I2C_NAME_SIZE: usize = 20;
42
43 /// Create a new device id from an I2C 'id' string.
44 #[inline(always)]
45 pub const fn new(id: &'static CStr) -> Self {
46 let src = id.to_bytes_with_nul();
47 build_assert!(src.len() <= Self::I2C_NAME_SIZE, "ID exceeds 20 bytes");
48 let mut i2c: bindings::i2c_device_id = pin_init::zeroed();
49 let mut i = 0;
50 while i < src.len() {
51 i2c.name[i] = src[i];
52 i += 1;
53 }
54
55 Self(i2c)
56 }
57}
58
59// SAFETY: `DeviceId` is a `#[repr(transparent)]` wrapper of `i2c_device_id` and does not add
60// additional invariants, so it's safe to transmute to `RawType`.
61unsafe impl RawDeviceId for DeviceId {
62 type RawType = bindings::i2c_device_id;
63}
64
65// SAFETY: `DRIVER_DATA_OFFSET` is the offset to the `driver_data` field.
66unsafe impl RawDeviceIdIndex for DeviceId {
67 const DRIVER_DATA_OFFSET: usize = core::mem::offset_of!(bindings::i2c_device_id, driver_data);
68
69 fn index(&self) -> usize {
70 self.0.driver_data
71 }
72}
73
74/// IdTable type for I2C
75pub type IdTable<T> = &'static dyn kernel::device_id::IdTable<DeviceId, T>;
76
77/// Create a I2C `IdTable` with its alias for modpost.
78#[macro_export]
79macro_rules! i2c_device_table {
80 ($table_name:ident, $module_table_name:ident, $id_info_type: ty, $table_data: expr) => {
81 const $table_name: $crate::device_id::IdArray<
82 $crate::i2c::DeviceId,
83 $id_info_type,
84 { $table_data.len() },
85 > = $crate::device_id::IdArray::new($table_data);
86
87 $crate::module_device_table!("i2c", $module_table_name, $table_name);
88 };
89}
90
91/// An adapter for the registration of I2C drivers.
92pub struct Adapter<T: Driver>(T);
93
94// SAFETY:
95// - `bindings::i2c_driver` is a C type declared as `repr(C)`.
96// - `T::Data` is the type of the driver's device private data.
97// - `struct i2c_driver` embeds a `struct device_driver`.
98// - `DEVICE_DRIVER_OFFSET` is the correct byte offset to the embedded `struct device_driver`.
99unsafe impl<T: Driver> driver::DriverLayout for Adapter<T> {
100 type DriverType = bindings::i2c_driver;
101 type DriverData<'bound> = T::Data<'bound>;
102 const DEVICE_DRIVER_OFFSET: usize = core::mem::offset_of!(Self::DriverType, driver);
103}
104
105// SAFETY: A call to `unregister` for a given instance of `DriverType` is guaranteed to be valid if
106// a preceding call to `register` has been successful.
107unsafe impl<T: Driver> driver::RegistrationOps for Adapter<T> {
108 unsafe fn register(
109 idrv: &Opaque<Self::DriverType>,
110 name: &'static CStr,
111 module: &'static ThisModule,
112 ) -> Result {
113 build_assert!(
114 T::ACPI_ID_TABLE.is_some() || T::OF_ID_TABLE.is_some() || T::I2C_ID_TABLE.is_some(),
115 "At least one of ACPI/OF/Legacy tables must be present when registering an i2c driver"
116 );
117
118 let i2c_table = match T::I2C_ID_TABLE {
119 Some(table) => table.as_ptr(),
120 None => core::ptr::null(),
121 };
122
123 let of_table = match T::OF_ID_TABLE {
124 Some(table) => table.as_ptr(),
125 None => core::ptr::null(),
126 };
127
128 let acpi_table = match T::ACPI_ID_TABLE {
129 Some(table) => table.as_ptr(),
130 None => core::ptr::null(),
131 };
132
133 // SAFETY: It's safe to set the fields of `struct i2c_client` on initialization.
134 unsafe {
135 (*idrv.get()).driver.name = name.as_char_ptr();
136 (*idrv.get()).probe = Some(Self::probe_callback);
137 (*idrv.get()).remove = Some(Self::remove_callback);
138 (*idrv.get()).shutdown = Some(Self::shutdown_callback);
139 (*idrv.get()).id_table = i2c_table;
140 (*idrv.get()).driver.of_match_table = of_table;
141 (*idrv.get()).driver.acpi_match_table = acpi_table;
142 }
143
144 // SAFETY: `idrv` is guaranteed to be a valid `DriverType`.
145 to_result(unsafe { bindings::i2c_register_driver(module.0, idrv.get()) })
146 }
147
148 unsafe fn unregister(idrv: &Opaque<Self::DriverType>) {
149 // SAFETY: `idrv` is guaranteed to be a valid `DriverType`.
150 unsafe { bindings::i2c_del_driver(idrv.get()) }
151 }
152}
153
154impl<T: Driver> Adapter<T> {
155 extern "C" fn probe_callback(idev: *mut bindings::i2c_client) -> kernel::ffi::c_int {
156 // SAFETY: The I2C bus only ever calls the probe callback with a valid pointer to a
157 // `struct i2c_client`.
158 //
159 // INVARIANT: `idev` is valid for the duration of `probe_callback()`.
160 let idev = unsafe { &*idev.cast::<I2cClient<device::CoreInternal<'_>>>() };
161
162 let info =
163 Self::i2c_id_info(idev).or_else(|| <Self as driver::Adapter>::id_info(idev.as_ref()));
164
165 from_result(|| {
166 let data = T::probe(idev, info);
167
168 idev.as_ref().set_drvdata(data)?;
169 Ok(0)
170 })
171 }
172
173 extern "C" fn remove_callback(idev: *mut bindings::i2c_client) {
174 // SAFETY: `idev` is a valid pointer to a `struct i2c_client`.
175 let idev = unsafe { &*idev.cast::<I2cClient<device::CoreInternal<'_>>>() };
176
177 // SAFETY: `remove_callback` is only ever called after a successful call to
178 // `probe_callback`, hence it's guaranteed that `I2cClient::set_drvdata()` has been called
179 // and stored a `Pin<KBox<T::Data<'_>>>`.
180 let data = unsafe { idev.as_ref().drvdata_borrow::<T::Data<'_>>() };
181
182 T::unbind(idev, data);
183 }
184
185 extern "C" fn shutdown_callback(idev: *mut bindings::i2c_client) {
186 // SAFETY: `shutdown_callback` is only ever called for a valid `idev`
187 let idev = unsafe { &*idev.cast::<I2cClient<device::CoreInternal<'_>>>() };
188
189 // SAFETY: `shutdown_callback` is only ever called after a successful call to
190 // `probe_callback`, hence it's guaranteed that `Device::set_drvdata()` has been called
191 // and stored a `Pin<KBox<T::Data<'_>>>`.
192 let data = unsafe { idev.as_ref().drvdata_borrow::<T::Data<'_>>() };
193
194 T::shutdown(idev, data);
195 }
196
197 /// The [`i2c::IdTable`] of the corresponding driver.
198 fn i2c_id_table() -> Option<IdTable<<Self as driver::Adapter>::IdInfo>> {
199 T::I2C_ID_TABLE
200 }
201
202 /// Returns the driver's private data from the matching entry in the [`i2c::IdTable`], if any.
203 ///
204 /// If this returns `None`, it means there is no match with an entry in the [`i2c::IdTable`].
205 fn i2c_id_info(dev: &I2cClient) -> Option<&'static <Self as driver::Adapter>::IdInfo> {
206 let table = Self::i2c_id_table()?;
207
208 // SAFETY:
209 // - `table` has static lifetime, hence it's valid for reads
210 // - `dev` is guaranteed to be valid while it's alive, and so is `dev.as_raw()`.
211 let raw_id = unsafe { bindings::i2c_match_id(table.as_ptr(), dev.as_raw()) };
212
213 if raw_id.is_null() {
214 return None;
215 }
216
217 // SAFETY: `DeviceId` is a `#[repr(transparent)` wrapper of `struct i2c_device_id` and
218 // does not add additional invariants, so it's safe to transmute.
219 let id = unsafe { &*raw_id.cast::<DeviceId>() };
220
221 Some(table.info(<DeviceId as RawDeviceIdIndex>::index(id)))
222 }
223}
224
225impl<T: Driver> driver::Adapter for Adapter<T> {
226 type IdInfo = T::IdInfo;
227
228 fn of_id_table() -> Option<of::IdTable<Self::IdInfo>> {
229 T::OF_ID_TABLE
230 }
231
232 fn acpi_id_table() -> Option<acpi::IdTable<Self::IdInfo>> {
233 T::ACPI_ID_TABLE
234 }
235}
236
237/// Declares a kernel module that exposes a single i2c driver.
238///
239/// # Examples
240///
241/// ```ignore
242/// kernel::module_i2c_driver! {
243/// type: MyDriver,
244/// name: "Module name",
245/// authors: ["Author name"],
246/// description: "Description",
247/// license: "GPL v2",
248/// }
249/// ```
250#[macro_export]
251macro_rules! module_i2c_driver {
252 ($($f:tt)*) => {
253 $crate::module_driver!(<T>, $crate::i2c::Adapter<T>, { $($f)* });
254 };
255}
256
257/// The i2c driver trait.
258///
259/// Drivers must implement this trait in order to get a i2c driver registered.
260///
261/// # Example
262///
263///```
264/// # use kernel::{acpi, bindings, device::Core, i2c, of};
265///
266/// struct MyDriver;
267///
268/// kernel::acpi_device_table!(
269/// ACPI_TABLE,
270/// MODULE_ACPI_TABLE,
271/// <MyDriver as i2c::Driver>::IdInfo,
272/// [
273/// (acpi::DeviceId::new(c"LNUXBEEF"), ())
274/// ]
275/// );
276///
277/// kernel::i2c_device_table!(
278/// I2C_TABLE,
279/// MODULE_I2C_TABLE,
280/// <MyDriver as i2c::Driver>::IdInfo,
281/// [
282/// (i2c::DeviceId::new(c"rust_driver_i2c"), ())
283/// ]
284/// );
285///
286/// kernel::of_device_table!(
287/// OF_TABLE,
288/// MODULE_OF_TABLE,
289/// <MyDriver as i2c::Driver>::IdInfo,
290/// [
291/// (of::DeviceId::new(c"test,device"), ())
292/// ]
293/// );
294///
295/// impl i2c::Driver for MyDriver {
296/// type IdInfo = ();
297/// type Data<'bound> = Self;
298/// const I2C_ID_TABLE: Option<i2c::IdTable<Self::IdInfo>> = Some(&I2C_TABLE);
299/// const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = Some(&OF_TABLE);
300/// const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = Some(&ACPI_TABLE);
301///
302/// fn probe<'bound>(
303/// _idev: &'bound i2c::I2cClient<Core<'_>>,
304/// _id_info: Option<&'bound Self::IdInfo>,
305/// ) -> impl PinInit<Self::Data<'bound>, Error> + 'bound {
306/// Err(ENODEV)
307/// }
308///
309/// fn shutdown<'bound>(
310/// _idev: &'bound i2c::I2cClient<Core<'_>>,
311/// this: Pin<&Self::Data<'bound>>,
312/// ) {
313/// }
314/// }
315///```
316pub trait Driver {
317 /// The type holding information about each device id supported by the driver.
318 // TODO: Use `associated_type_defaults` once stabilized:
319 //
320 // ```
321 // type IdInfo: 'static = ();
322 // ```
323 type IdInfo: 'static;
324
325 /// The type of the driver's bus device private data.
326 type Data<'bound>: Send + 'bound;
327
328 /// The table of device ids supported by the driver.
329 const I2C_ID_TABLE: Option<IdTable<Self::IdInfo>> = None;
330
331 /// The table of OF device ids supported by the driver.
332 const OF_ID_TABLE: Option<of::IdTable<Self::IdInfo>> = None;
333
334 /// The table of ACPI device ids supported by the driver.
335 const ACPI_ID_TABLE: Option<acpi::IdTable<Self::IdInfo>> = None;
336
337 /// I2C driver probe.
338 ///
339 /// Called when a new i2c client is added or discovered.
340 /// Implementers should attempt to initialize the client here.
341 fn probe<'bound>(
342 dev: &'bound I2cClient<device::Core<'_>>,
343 id_info: Option<&'bound Self::IdInfo>,
344 ) -> impl PinInit<Self::Data<'bound>, Error> + 'bound;
345
346 /// I2C driver shutdown.
347 ///
348 /// Called by the kernel during system reboot or power-off to allow the [`Driver`] to bring the
349 /// [`I2cClient`] into a safe state. Implementing this callback is optional.
350 ///
351 /// Typical actions include stopping transfers, disabling interrupts, or resetting the hardware
352 /// to prevent undesired behavior during shutdown.
353 ///
354 /// This callback is distinct from final resource cleanup, as the driver instance remains valid
355 /// after it returns. Any deallocation or teardown of driver-owned resources should instead be
356 /// handled in `Drop`.
357 fn shutdown<'bound>(dev: &'bound I2cClient<device::Core<'_>>, this: Pin<&Self::Data<'bound>>) {
358 let _ = (dev, this);
359 }
360
361 /// I2C driver unbind.
362 ///
363 /// Called when the [`I2cClient`] is unbound from its bound [`Driver`]. Implementing this
364 /// callback is optional.
365 ///
366 /// This callback serves as a place for drivers to perform teardown operations that require a
367 /// `&Device<Core>` or `&Device<Bound>` reference. For instance, drivers may try to perform I/O
368 /// operations to gracefully tear down the device.
369 ///
370 /// Otherwise, release operations for driver resources should be performed in `Drop`.
371 fn unbind<'bound>(dev: &'bound I2cClient<device::Core<'_>>, this: Pin<&Self::Data<'bound>>) {
372 let _ = (dev, this);
373 }
374}
375
376/// The i2c adapter representation.
377///
378/// This structure represents the Rust abstraction for a C `struct i2c_adapter`. The
379/// implementation abstracts the usage of an existing C `struct i2c_adapter` that
380/// gets passed from the C side
381///
382/// # Invariants
383///
384/// A [`I2cAdapter`] instance represents a valid `struct i2c_adapter` created by the C portion of
385/// the kernel.
386#[repr(transparent)]
387pub struct I2cAdapter<Ctx: device::DeviceContext = device::Normal>(
388 Opaque<bindings::i2c_adapter>,
389 PhantomData<Ctx>,
390);
391
392impl<Ctx: device::DeviceContext> I2cAdapter<Ctx> {
393 fn as_raw(&self) -> *mut bindings::i2c_adapter {
394 self.0.get()
395 }
396}
397
398impl I2cAdapter {
399 /// Returns the I2C Adapter index.
400 #[inline]
401 pub fn index(&self) -> i32 {
402 // SAFETY: `self.as_raw` is a valid pointer to a `struct i2c_adapter`.
403 unsafe { (*self.as_raw()).nr }
404 }
405
406 /// Gets pointer to an `i2c_adapter` by index.
407 pub fn get(index: i32) -> Result<ARef<Self>> {
408 // SAFETY: `index` must refer to a valid I2C adapter; the kernel
409 // guarantees that `i2c_get_adapter(index)` returns either a valid
410 // pointer or NULL. `NonNull::new` guarantees the correct check.
411 let adapter = NonNull::new(unsafe { bindings::i2c_get_adapter(index) }).ok_or(ENODEV)?;
412
413 // SAFETY: `adapter` is non-null and points to a live `i2c_adapter`.
414 // `I2cAdapter` is #[repr(transparent)], so this cast is valid.
415 // `i2c_get_adapter` returned the adapter with an incremented refcount, which we pass to
416 // the `ARef`.
417 Ok(unsafe { ARef::from_raw(adapter.cast::<I2cAdapter<device::Normal>>()) })
418 }
419}
420
421// SAFETY: `I2cAdapter` is a transparent wrapper of a type that doesn't depend on
422// `I2cAdapter`'s generic argument.
423kernel::impl_device_context_deref!(unsafe { I2cAdapter });
424kernel::impl_device_context_into_aref!(I2cAdapter);
425
426// SAFETY: Instances of `I2cAdapter` are always reference-counted.
427unsafe impl AlwaysRefCounted for I2cAdapter {
428 fn inc_ref(&self) {
429 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
430 unsafe { bindings::i2c_get_adapter(self.index()) };
431 }
432
433 unsafe fn dec_ref(obj: NonNull<Self>) {
434 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
435 unsafe { bindings::i2c_put_adapter(obj.as_ref().as_raw()) }
436 }
437}
438
439/// The i2c board info representation
440///
441/// This structure represents the Rust abstraction for a C `struct i2c_board_info` structure,
442/// which is used for manual I2C client creation.
443#[repr(transparent)]
444pub struct I2cBoardInfo(bindings::i2c_board_info);
445
446impl I2cBoardInfo {
447 const I2C_TYPE_SIZE: usize = 20;
448 /// Create a new [`I2cBoardInfo`] for a kernel driver.
449 #[inline(always)]
450 pub const fn new(type_: &'static CStr, addr: u16) -> Self {
451 let src = type_.to_bytes_with_nul();
452 build_assert!(src.len() <= Self::I2C_TYPE_SIZE, "Type exceeds 20 bytes");
453 let mut i2c_board_info: bindings::i2c_board_info = pin_init::zeroed();
454 let mut i: usize = 0;
455 while i < src.len() {
456 i2c_board_info.type_[i] = src[i];
457 i += 1;
458 }
459
460 i2c_board_info.addr = addr;
461 Self(i2c_board_info)
462 }
463
464 fn as_raw(&self) -> *const bindings::i2c_board_info {
465 from_ref(&self.0)
466 }
467}
468
469/// The i2c client representation.
470///
471/// This structure represents the Rust abstraction for a C `struct i2c_client`. The
472/// implementation abstracts the usage of an existing C `struct i2c_client` that
473/// gets passed from the C side
474///
475/// # Invariants
476///
477/// A [`I2cClient`] instance represents a valid `struct i2c_client` created by the C portion of
478/// the kernel.
479#[repr(transparent)]
480pub struct I2cClient<Ctx: device::DeviceContext = device::Normal>(
481 Opaque<bindings::i2c_client>,
482 PhantomData<Ctx>,
483);
484
485impl<Ctx: device::DeviceContext> I2cClient<Ctx> {
486 fn as_raw(&self) -> *mut bindings::i2c_client {
487 self.0.get()
488 }
489}
490
491// SAFETY: `I2cClient` is a transparent wrapper of `struct i2c_client`.
492// The offset is guaranteed to point to a valid device field inside `I2cClient`.
493unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for I2cClient<Ctx> {
494 const OFFSET: usize = offset_of!(bindings::i2c_client, dev);
495}
496
497// SAFETY: `I2cClient` is a transparent wrapper of a type that doesn't depend on
498// `I2cClient`'s generic argument.
499kernel::impl_device_context_deref!(unsafe { I2cClient });
500kernel::impl_device_context_into_aref!(I2cClient);
501
502// SAFETY: Instances of `I2cClient` are always reference-counted.
503unsafe impl AlwaysRefCounted for I2cClient {
504 fn inc_ref(&self) {
505 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
506 unsafe { bindings::get_device(self.as_ref().as_raw()) };
507 }
508
509 unsafe fn dec_ref(obj: NonNull<Self>) {
510 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
511 unsafe { bindings::put_device(&raw mut (*obj.as_ref().as_raw()).dev) }
512 }
513}
514
515impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for I2cClient<Ctx> {
516 fn as_ref(&self) -> &device::Device<Ctx> {
517 let raw = self.as_raw();
518 // SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
519 // `struct i2c_client`.
520 let dev = unsafe { &raw mut (*raw).dev };
521
522 // SAFETY: `dev` points to a valid `struct device`.
523 unsafe { device::Device::from_raw(dev) }
524 }
525}
526
527impl<Ctx: device::DeviceContext> TryFrom<&device::Device<Ctx>> for &I2cClient<Ctx> {
528 type Error = kernel::error::Error;
529
530 fn try_from(dev: &device::Device<Ctx>) -> Result<Self, Self::Error> {
531 // SAFETY: By the type invariant of `Device`, `dev.as_raw()` is a valid pointer to a
532 // `struct device`.
533 if unsafe { bindings::i2c_verify_client(dev.as_raw()).is_null() } {
534 return Err(EINVAL);
535 }
536
537 // SAFETY: We've just verified that the type of `dev` equals to
538 // `bindings::i2c_client_type`, hence `dev` must be embedded in a valid
539 // `struct i2c_client` as guaranteed by the corresponding C code.
540 let idev = unsafe { container_of!(dev.as_raw(), bindings::i2c_client, dev) };
541
542 // SAFETY: `idev` is a valid pointer to a `struct i2c_client`.
543 Ok(unsafe { &*idev.cast() })
544 }
545}
546
547// SAFETY: A `I2cClient` is always reference-counted and can be released from any thread.
548unsafe impl Send for I2cClient {}
549
550// SAFETY: `I2cClient` can be shared among threads because all methods of `I2cClient`
551// (i.e. `I2cClient<Normal>) are thread safe.
552unsafe impl Sync for I2cClient {}
553
554/// The registration of an i2c client device.
555///
556/// This type represents the registration of a [`struct i2c_client`]. When an instance of this
557/// type is dropped, its respective i2c client device will be unregistered from the system.
558///
559/// # Invariants
560///
561/// `self.0` always holds a valid pointer to an initialized and registered
562/// [`struct i2c_client`].
563#[repr(transparent)]
564pub struct Registration(NonNull<bindings::i2c_client>);
565
566impl Registration {
567 /// The C `i2c_new_client_device` function wrapper for manual I2C client creation.
568 pub fn new<'a>(
569 i2c_adapter: &I2cAdapter,
570 i2c_board_info: &I2cBoardInfo,
571 parent_dev: &'a device::Device<device::Bound>,
572 ) -> impl PinInit<Devres<Self>, Error> + 'a {
573 Devres::new(parent_dev, Self::try_new(i2c_adapter, i2c_board_info))
574 }
575
576 fn try_new(i2c_adapter: &I2cAdapter, i2c_board_info: &I2cBoardInfo) -> Result<Self> {
577 // SAFETY: the kernel guarantees that `i2c_new_client_device()` returns either a valid
578 // pointer or NULL. `from_err_ptr` separates errors. Following `NonNull::new`
579 // checks for NULL.
580 let raw_dev = from_err_ptr(unsafe {
581 bindings::i2c_new_client_device(i2c_adapter.as_raw(), i2c_board_info.as_raw())
582 })?;
583
584 let dev_ptr = NonNull::new(raw_dev).ok_or(ENODEV)?;
585
586 Ok(Self(dev_ptr))
587 }
588}
589
590impl Drop for Registration {
591 fn drop(&mut self) {
592 // SAFETY: `Drop` is only called for a valid `Registration`, which by invariant
593 // always contains a non-null pointer to an `i2c_client`.
594 unsafe { bindings::i2c_unregister_device(self.0.as_ptr()) }
595 }
596}
597
598// SAFETY: A `Registration` of a `struct i2c_client` can be released from any thread.
599unsafe impl Send for Registration {}
600
601// SAFETY: `Registration` offers no interior mutability (no mutation through &self
602// and no mutable access is exposed)
603unsafe impl Sync for Registration {}