Text of rust.docs.kernel.org › src › kernel › serdev.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

serdev.rs - source

Skip to main content kernel/ serdev.rs 1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Abstractions for the serial device bus. 4 //! 5 //! C header: [`include/linux/serdev.h`](srctree/include/linux/serdev.h) 6 7 use crate ::{ 8 acpi , 9 device , 10 driver , 11 error::{ 12 from_result , 13 to_result , 14 VTABLE_DEFAULT_ERROR , // 15 }, 16 new_mutex , 17 of , 18 prelude :: * , 19 sync::{ 20 aref::AlwaysRefCounted , 21 Mutex , // 22 }, 23 time::Jiffies , 24 types::{ 25 Opaque , 26 ScopeGuard , // 27 }, // 28 }; 29 30 use core::{ 31 cell::UnsafeCell , 32 marker::PhantomData , 33 mem::{ offset_of , MaybeUninit }, 34 ptr::NonNull , // 35 }; 36 37 /// Parity bit to use with a serial device.

38 #[repr(u32)] 39 pub enum Parity { 40 /// No parity bit. 41 None = bindings::serdev_parity_SERDEV_PARITY_NONE, 42 /// Even partiy. 43 Even = bindings::serdev_parity_SERDEV_PARITY_EVEN, 44 /// Odd parity. 45 Odd = bindings::serdev_parity_SERDEV_PARITY_ODD, 46 } 47 48 /// An adapter for the registration of serial device bus device drivers. 49 pub struct Adapter <T: Driver >(T); 50 51 // SAFETY: 52 // - `bindings::serdev_device_driver` is a C type declared as `repr(C)`.

53 // - `PrivateData<'bound, T>` is the type of the driver's device private data. 54 // - `struct serdev_device_driver` embeds a `struct device_driver`. 55 // - `DEVICE_DRIVER_OFFSET` is the correct byte offset to the embedded `struct device_driver`. 56 unsafe impl <T: Driver > driver::DriverLayout for Adapter <T> { 57 type DriverType = bindings::serdev_device_driver; 58 type DriverData< 'bound > = PrivateData < 'bound , T>; 59 const DEVICE_DRIVER_OFFSET: usize = core::mem::offset_of! ( Self ::DriverType, driver); 60 } 61 62 // SAFETY: A call to `unregister` for a given instance of `DriverType` is guaranteed to be valid if 63 // a preceding call to `register` has been successful.

64 unsafe impl <T: Driver > driver::RegistrationOps for Adapter <T> { 65 unsafe fn register( 66 sdrv: & Opaque < Self ::DriverType>, 67 name: & 'static CStr , 68 module: & 'static ThisModule , 69 ) -> Result { 70 let of_table = match T:: OF_ID_TABLE { 71 Some (table) => table . as_ptr (), 72 None => core::ptr:: null (), 73 }; 74 75 let acpi_table = match T:: ACPI_ID_TABLE { 76 Some (table) => table . as_ptr (), 77 None => core::ptr:: null (), 78 }; 79 80 // SAFETY: It's safe to set the fields of `struct serdev_device_driver` on initialization.

81 unsafe { 82 ( * sdrv . get ()).driver.name = name . as_char_ptr (); 83 ( * sdrv . get ()).probe = Some ( Self :: probe_callback ); 84 ( * sdrv . get ()).remove = Some ( Self :: remove_callback ); 85 ( * sdrv . get ()).driver.of_match_table = of_table ; 86 ( * sdrv . get ()).driver.acpi_match_table = acpi_table ; 87 } 88 89 // SAFETY: `sdrv` is guaranteed to be a valid `DriverType`. 90 to_result ( unsafe { bindings::__serdev_device_driver_register( sdrv . get (), module . as_ptr ()) }) 91 } 92 93 unsafe fn unregister(sdrv: & Opaque < Self ::DriverType>) { 94 // SAFETY: `sdrv` is guaranteed to be a valid `DriverType`.

95 unsafe { bindings::serdev_device_driver_unregister( sdrv . get ()) }; 96 } 97 } 98 99 #[doc(hidden)] 100 #[pin_data(PinnedDrop)] 101 pub struct PrivateData< 'bound , T: Driver > { 102 sdev: & 'bound Device <device:: Bound >, 103 #[pin] 104 driver: UnsafeCell < MaybeUninit <T::Data< 'bound >>>, 105 open: UnsafeCell < bool >, 106 /// Whether `receive_buf_callback` is allowed to call `Driver::receive`. 107 /// 108 /// If locked, the receive_buf_callback will be blocked on data reception.

109 /// This is the case while the driver is being probed or while [`PrivateData`] is being dropped. 110 /// This is necessary, because we need to open the serdev device before the driver has been 111 /// probed in order to allow it to be configured, which allows `receive_buf_callback` to be 112 /// called. Thus we need to block data until probe completes and the driver data becomes 113 /// initialized. 114 /// 115 /// If unlocked and true, the receive_buf_callback will forward the data to 116 /// `Driver::receive`.

This is the normal state of operation. 117 /// 118 /// If unlocked and false, the receive_buf_callback will throw away the data. 119 /// This is only the case, if the serdev device is open and 120 /// - the driver returned an error in probe 121 /// or 122 /// - the driver data already has been dropped, because it was unbound. 123 #[pin] 124 active: Mutex < bool >, 125 } 126 127 #[pinned_drop] 128 impl <T: Driver > PinnedDrop for PrivateData < '_ , T> { 129 fn drop( self : Pin < &mut Self >) { 130 let mut active = self .active. lock (); 131 if * active { 132 // SAFETY: 133 // - We have exclusive access to `self.driver`.

134 // - `self.driver` is guaranteed to be initialized. 135 unsafe { ( * self .driver. get ()). assume_init_drop () }; 136 * active = false ; 137 } 138 drop ( active ); 139 140 // SAFETY: We have exclusive access to `self.open`. 141 if unsafe { * self .open. get () } { 142 // SAFETY: `self.sdev.as_raw()` is guaranteed to be a pointer to a valid 143 // `struct serdev_device`. 144 unsafe { bindings::serdev_device_close( self .sdev. as_raw ()) }; 145 } 146 } 147 } 148 149 impl <T: Driver > Adapter <T> { 150 const OPS: & 'static bindings::serdev_device_ops = & bindings::serdev_device_ops { 151 receive_buf: if T:: HAS_RECEIVE { 152 Some ( Self :: receive_buf_callback ) 153 } else { 154 None 155 }, 156 write_wakeup: Some (bindings::serdev_device_write_wakeup), 157 }; 158 159 extern "C" fn probe_callback(sdev: *mut bindings::serdev_device) -> kernel::ffi:: c_int { 160 // SAFETY: The serial device bus only ever calls the probe callback with a valid pointer to 161 // a `struct serdev_device`.

162 // 163 // INVARIANT: `sdev` is valid for the duration of `probe_callback()`. 164 let sdev = unsafe { &* sdev . cast ::< Device <device:: CoreInternal < '_ >>>() }; 165 // SAFETY: `sdev` matched data is of type `Self::IdInfo`. 166 let info = unsafe { < Self as driver::Adapter>:: id_info ( sdev . as_ref ()) }; 167 168 from_result (|| { 169 sdev.as_ref().set_drvdata( try_pin_init! (PrivateData::<T> { 170 sdev: &** sdev, 171 driver: MaybeUninit::<T::Data< '_ >>::zeroed().into(), 172 open: false .into(), 173 active <- new_mutex! ( false ), 174 })) ? ; 175 // SAFETY: We just set drvdata to `PrivateData<'_, T>`.

176 let private_data = unsafe { sdev . as_ref (). drvdata_borrow ::< PrivateData < '_ , T>>() }; 177 let private_data = ScopeGuard :: new_with_data ( private_data , | _ | { 178 // SAFETY: We just set drvdata to `PrivateData<'_, T>`. 179 drop ( unsafe { sdev . as_ref (). drvdata_obtain ::< PrivateData < '_ , T>>() }); 180 }); 181 let mut active = private_data .active. lock (); 182 183 // SAFETY: `sdev.as_raw()` is guaranteed to be a valid pointer to `serdev_device`.

184 unsafe { bindings::serdev_device_set_client_ops( sdev . as_raw (), Self :: OPS ) }; 185 186 // SAFETY: The serial device bus only ever calls the probe callback with a valid pointer 187 // to a `serdev_device`. 188 to_result( unsafe { bindings::serdev_device_open(sdev.as_raw()) }) ? ; 189 190 // SAFETY: We have exclusive access to `private_data.open`. 191 unsafe { * private_data .open. get () = true }; 192 193 let data = T:: probe ( sdev , info ); 194 195 // SAFETY: We have exclusive access to `private_data.driver`.

196 let driver = unsafe { &mut * private_data .driver. get () }; 197 // SAFETY: 198 // - `driver.as_mut_ptr()` is a valid pointer to uninitialized data. 199 // - `private_data.driver` is pinned. 200 let result = unsafe { pin_init:: raw_try_init ( driver . as_mut_ptr (), data ) }; 201 202 * active = result . is_ok (); 203 204 drop ( active ); 205 206 result . map (|()| { 207 private_data . dismiss (); 208 0 209 }) 210 }) 211 } 212 213 extern "C" fn remove_callback(sdev: *mut bindings::serdev_device) { 214 // SAFETY: The serial device bus only ever calls the remove callback with a valid pointer 215 // to a `struct serdev_device`.

216 // 217 // INVARIANT: `sdev` is valid for the duration of `remove_callback()`

The rest of this page is on the live site.