Loading...
Note: File does not exist in v3.15.
1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! Miscdevice support.
6//!
7//! C headers: [`include/linux/miscdevice.h`](srctree/include/linux/miscdevice.h).
8//!
9//! Reference: <https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html>
10
11use crate::{
12 bindings,
13 error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
14 ffi::{c_int, c_long, c_uint, c_ulong},
15 prelude::*,
16 str::CStr,
17 types::{ForeignOwnable, Opaque},
18};
19use core::{marker::PhantomData, mem::MaybeUninit, pin::Pin};
20
21/// Options for creating a misc device.
22#[derive(Copy, Clone)]
23pub struct MiscDeviceOptions {
24 /// The name of the miscdevice.
25 pub name: &'static CStr,
26}
27
28impl MiscDeviceOptions {
29 /// Create a raw `struct miscdev` ready for registration.
30 pub const fn into_raw<T: MiscDevice>(self) -> bindings::miscdevice {
31 // SAFETY: All zeros is valid for this C type.
32 let mut result: bindings::miscdevice = unsafe { MaybeUninit::zeroed().assume_init() };
33 result.minor = bindings::MISC_DYNAMIC_MINOR as _;
34 result.name = self.name.as_char_ptr();
35 result.fops = create_vtable::<T>();
36 result
37 }
38}
39
40/// A registration of a miscdevice.
41///
42/// # Invariants
43///
44/// `inner` is a registered misc device.
45#[repr(transparent)]
46#[pin_data(PinnedDrop)]
47pub struct MiscDeviceRegistration<T> {
48 #[pin]
49 inner: Opaque<bindings::miscdevice>,
50 _t: PhantomData<T>,
51}
52
53// SAFETY: It is allowed to call `misc_deregister` on a different thread from where you called
54// `misc_register`.
55unsafe impl<T> Send for MiscDeviceRegistration<T> {}
56// SAFETY: All `&self` methods on this type are written to ensure that it is safe to call them in
57// parallel.
58unsafe impl<T> Sync for MiscDeviceRegistration<T> {}
59
60impl<T: MiscDevice> MiscDeviceRegistration<T> {
61 /// Register a misc device.
62 pub fn register(opts: MiscDeviceOptions) -> impl PinInit<Self, Error> {
63 try_pin_init!(Self {
64 inner <- Opaque::try_ffi_init(move |slot: *mut bindings::miscdevice| {
65 // SAFETY: The initializer can write to the provided `slot`.
66 unsafe { slot.write(opts.into_raw::<T>()) };
67
68 // SAFETY: We just wrote the misc device options to the slot. The miscdevice will
69 // get unregistered before `slot` is deallocated because the memory is pinned and
70 // the destructor of this type deallocates the memory.
71 // INVARIANT: If this returns `Ok(())`, then the `slot` will contain a registered
72 // misc device.
73 to_result(unsafe { bindings::misc_register(slot) })
74 }),
75 _t: PhantomData,
76 })
77 }
78
79 /// Returns a raw pointer to the misc device.
80 pub fn as_raw(&self) -> *mut bindings::miscdevice {
81 self.inner.get()
82 }
83}
84
85#[pinned_drop]
86impl<T> PinnedDrop for MiscDeviceRegistration<T> {
87 fn drop(self: Pin<&mut Self>) {
88 // SAFETY: We know that the device is registered by the type invariants.
89 unsafe { bindings::misc_deregister(self.inner.get()) };
90 }
91}
92
93/// Trait implemented by the private data of an open misc device.
94#[vtable]
95pub trait MiscDevice {
96 /// What kind of pointer should `Self` be wrapped in.
97 type Ptr: ForeignOwnable + Send + Sync;
98
99 /// Called when the misc device is opened.
100 ///
101 /// The returned pointer will be stored as the private data for the file.
102 fn open() -> Result<Self::Ptr>;
103
104 /// Called when the misc device is released.
105 fn release(device: Self::Ptr) {
106 drop(device);
107 }
108
109 /// Handler for ioctls.
110 ///
111 /// The `cmd` argument is usually manipulated using the utilties in [`kernel::ioctl`].
112 ///
113 /// [`kernel::ioctl`]: mod@crate::ioctl
114 fn ioctl(
115 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
116 _cmd: u32,
117 _arg: usize,
118 ) -> Result<isize> {
119 kernel::build_error(VTABLE_DEFAULT_ERROR)
120 }
121
122 /// Handler for ioctls.
123 ///
124 /// Used for 32-bit userspace on 64-bit platforms.
125 ///
126 /// This method is optional and only needs to be provided if the ioctl relies on structures
127 /// that have different layout on 32-bit and 64-bit userspace. If no implementation is
128 /// provided, then `compat_ptr_ioctl` will be used instead.
129 #[cfg(CONFIG_COMPAT)]
130 fn compat_ioctl(
131 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
132 _cmd: u32,
133 _arg: usize,
134 ) -> Result<isize> {
135 kernel::build_error(VTABLE_DEFAULT_ERROR)
136 }
137}
138
139const fn create_vtable<T: MiscDevice>() -> &'static bindings::file_operations {
140 const fn maybe_fn<T: Copy>(check: bool, func: T) -> Option<T> {
141 if check {
142 Some(func)
143 } else {
144 None
145 }
146 }
147
148 struct VtableHelper<T: MiscDevice> {
149 _t: PhantomData<T>,
150 }
151 impl<T: MiscDevice> VtableHelper<T> {
152 const VTABLE: bindings::file_operations = bindings::file_operations {
153 open: Some(fops_open::<T>),
154 release: Some(fops_release::<T>),
155 unlocked_ioctl: maybe_fn(T::HAS_IOCTL, fops_ioctl::<T>),
156 #[cfg(CONFIG_COMPAT)]
157 compat_ioctl: if T::HAS_COMPAT_IOCTL {
158 Some(fops_compat_ioctl::<T>)
159 } else if T::HAS_IOCTL {
160 Some(bindings::compat_ptr_ioctl)
161 } else {
162 None
163 },
164 // SAFETY: All zeros is a valid value for `bindings::file_operations`.
165 ..unsafe { MaybeUninit::zeroed().assume_init() }
166 };
167 }
168
169 &VtableHelper::<T>::VTABLE
170}
171
172/// # Safety
173///
174/// `file` and `inode` must be the file and inode for a file that is undergoing initialization.
175/// The file must be associated with a `MiscDeviceRegistration<T>`.
176unsafe extern "C" fn fops_open<T: MiscDevice>(
177 inode: *mut bindings::inode,
178 file: *mut bindings::file,
179) -> c_int {
180 // SAFETY: The pointers are valid and for a file being opened.
181 let ret = unsafe { bindings::generic_file_open(inode, file) };
182 if ret != 0 {
183 return ret;
184 }
185
186 let ptr = match T::open() {
187 Ok(ptr) => ptr,
188 Err(err) => return err.to_errno(),
189 };
190
191 // SAFETY: The open call of a file owns the private data.
192 unsafe { (*file).private_data = ptr.into_foreign().cast_mut() };
193
194 0
195}
196
197/// # Safety
198///
199/// `file` and `inode` must be the file and inode for a file that is being released. The file must
200/// be associated with a `MiscDeviceRegistration<T>`.
201unsafe extern "C" fn fops_release<T: MiscDevice>(
202 _inode: *mut bindings::inode,
203 file: *mut bindings::file,
204) -> c_int {
205 // SAFETY: The release call of a file owns the private data.
206 let private = unsafe { (*file).private_data };
207 // SAFETY: The release call of a file owns the private data.
208 let ptr = unsafe { <T::Ptr as ForeignOwnable>::from_foreign(private) };
209
210 T::release(ptr);
211
212 0
213}
214
215/// # Safety
216///
217/// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
218unsafe extern "C" fn fops_ioctl<T: MiscDevice>(
219 file: *mut bindings::file,
220 cmd: c_uint,
221 arg: c_ulong,
222) -> c_long {
223 // SAFETY: The ioctl call of a file can access the private data.
224 let private = unsafe { (*file).private_data };
225 // SAFETY: Ioctl calls can borrow the private data of the file.
226 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
227
228 match T::ioctl(device, cmd, arg) {
229 Ok(ret) => ret as c_long,
230 Err(err) => err.to_errno() as c_long,
231 }
232}
233
234/// # Safety
235///
236/// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
237#[cfg(CONFIG_COMPAT)]
238unsafe extern "C" fn fops_compat_ioctl<T: MiscDevice>(
239 file: *mut bindings::file,
240 cmd: c_uint,
241 arg: c_ulong,
242) -> c_long {
243 // SAFETY: The compat ioctl call of a file can access the private data.
244 let private = unsafe { (*file).private_data };
245 // SAFETY: Ioctl calls can borrow the private data of the file.
246 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
247
248 match T::compat_ioctl(device, cmd, arg) {
249 Ok(ret) => ret as c_long,
250 Err(err) => err.to_errno() as c_long,
251 }
252}