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 device::Device,
14 error::{to_result, Error, Result, VTABLE_DEFAULT_ERROR},
15 ffi::{c_int, c_long, c_uint, c_ulong},
16 fs::File,
17 mm::virt::VmaNew,
18 prelude::*,
19 seq_file::SeqFile,
20 str::CStr,
21 types::{ForeignOwnable, Opaque},
22};
23use core::{marker::PhantomData, mem::MaybeUninit, pin::Pin};
24
25/// Options for creating a misc device.
26#[derive(Copy, Clone)]
27pub struct MiscDeviceOptions {
28 /// The name of the miscdevice.
29 pub name: &'static CStr,
30}
31
32impl MiscDeviceOptions {
33 /// Create a raw `struct miscdev` ready for registration.
34 pub const fn into_raw<T: MiscDevice>(self) -> bindings::miscdevice {
35 // SAFETY: All zeros is valid for this C type.
36 let mut result: bindings::miscdevice = unsafe { MaybeUninit::zeroed().assume_init() };
37 result.minor = bindings::MISC_DYNAMIC_MINOR as _;
38 result.name = self.name.as_char_ptr();
39 result.fops = MiscdeviceVTable::<T>::build();
40 result
41 }
42}
43
44/// A registration of a miscdevice.
45///
46/// # Invariants
47///
48/// `inner` is a registered misc device.
49#[repr(transparent)]
50#[pin_data(PinnedDrop)]
51pub struct MiscDeviceRegistration<T> {
52 #[pin]
53 inner: Opaque<bindings::miscdevice>,
54 _t: PhantomData<T>,
55}
56
57// SAFETY: It is allowed to call `misc_deregister` on a different thread from where you called
58// `misc_register`.
59unsafe impl<T> Send for MiscDeviceRegistration<T> {}
60// SAFETY: All `&self` methods on this type are written to ensure that it is safe to call them in
61// parallel.
62unsafe impl<T> Sync for MiscDeviceRegistration<T> {}
63
64impl<T: MiscDevice> MiscDeviceRegistration<T> {
65 /// Register a misc device.
66 pub fn register(opts: MiscDeviceOptions) -> impl PinInit<Self, Error> {
67 try_pin_init!(Self {
68 inner <- Opaque::try_ffi_init(move |slot: *mut bindings::miscdevice| {
69 // SAFETY: The initializer can write to the provided `slot`.
70 unsafe { slot.write(opts.into_raw::<T>()) };
71
72 // SAFETY: We just wrote the misc device options to the slot. The miscdevice will
73 // get unregistered before `slot` is deallocated because the memory is pinned and
74 // the destructor of this type deallocates the memory.
75 // INVARIANT: If this returns `Ok(())`, then the `slot` will contain a registered
76 // misc device.
77 to_result(unsafe { bindings::misc_register(slot) })
78 }),
79 _t: PhantomData,
80 })
81 }
82
83 /// Returns a raw pointer to the misc device.
84 pub fn as_raw(&self) -> *mut bindings::miscdevice {
85 self.inner.get()
86 }
87
88 /// Access the `this_device` field.
89 pub fn device(&self) -> &Device {
90 // SAFETY: This can only be called after a successful register(), which always
91 // initialises `this_device` with a valid device. Furthermore, the signature of this
92 // function tells the borrow-checker that the `&Device` reference must not outlive the
93 // `&MiscDeviceRegistration<T>` used to obtain it, so the last use of the reference must be
94 // before the underlying `struct miscdevice` is destroyed.
95 unsafe { Device::as_ref((*self.as_raw()).this_device) }
96 }
97}
98
99#[pinned_drop]
100impl<T> PinnedDrop for MiscDeviceRegistration<T> {
101 fn drop(self: Pin<&mut Self>) {
102 // SAFETY: We know that the device is registered by the type invariants.
103 unsafe { bindings::misc_deregister(self.inner.get()) };
104 }
105}
106
107/// Trait implemented by the private data of an open misc device.
108#[vtable]
109pub trait MiscDevice: Sized {
110 /// What kind of pointer should `Self` be wrapped in.
111 type Ptr: ForeignOwnable + Send + Sync;
112
113 /// Called when the misc device is opened.
114 ///
115 /// The returned pointer will be stored as the private data for the file.
116 fn open(_file: &File, _misc: &MiscDeviceRegistration<Self>) -> Result<Self::Ptr>;
117
118 /// Called when the misc device is released.
119 fn release(device: Self::Ptr, _file: &File) {
120 drop(device);
121 }
122
123 /// Handle for mmap.
124 ///
125 /// This function is invoked when a user space process invokes the `mmap` system call on
126 /// `file`. The function is a callback that is part of the VMA initializer. The kernel will do
127 /// initial setup of the VMA before calling this function. The function can then interact with
128 /// the VMA initialization by calling methods of `vma`. If the function does not return an
129 /// error, the kernel will complete initialization of the VMA according to the properties of
130 /// `vma`.
131 fn mmap(
132 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
133 _file: &File,
134 _vma: &VmaNew,
135 ) -> Result {
136 build_error!(VTABLE_DEFAULT_ERROR)
137 }
138
139 /// Handler for ioctls.
140 ///
141 /// The `cmd` argument is usually manipulated using the utilities in [`kernel::ioctl`].
142 ///
143 /// [`kernel::ioctl`]: mod@crate::ioctl
144 fn ioctl(
145 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
146 _file: &File,
147 _cmd: u32,
148 _arg: usize,
149 ) -> Result<isize> {
150 build_error!(VTABLE_DEFAULT_ERROR)
151 }
152
153 /// Handler for ioctls.
154 ///
155 /// Used for 32-bit userspace on 64-bit platforms.
156 ///
157 /// This method is optional and only needs to be provided if the ioctl relies on structures
158 /// that have different layout on 32-bit and 64-bit userspace. If no implementation is
159 /// provided, then `compat_ptr_ioctl` will be used instead.
160 #[cfg(CONFIG_COMPAT)]
161 fn compat_ioctl(
162 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
163 _file: &File,
164 _cmd: u32,
165 _arg: usize,
166 ) -> Result<isize> {
167 build_error!(VTABLE_DEFAULT_ERROR)
168 }
169
170 /// Show info for this fd.
171 fn show_fdinfo(
172 _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>,
173 _m: &SeqFile,
174 _file: &File,
175 ) {
176 build_error!(VTABLE_DEFAULT_ERROR)
177 }
178}
179
180/// A vtable for the file operations of a Rust miscdevice.
181struct MiscdeviceVTable<T: MiscDevice>(PhantomData<T>);
182
183impl<T: MiscDevice> MiscdeviceVTable<T> {
184 /// # Safety
185 ///
186 /// `file` and `inode` must be the file and inode for a file that is undergoing initialization.
187 /// The file must be associated with a `MiscDeviceRegistration<T>`.
188 unsafe extern "C" fn open(inode: *mut bindings::inode, raw_file: *mut bindings::file) -> c_int {
189 // SAFETY: The pointers are valid and for a file being opened.
190 let ret = unsafe { bindings::generic_file_open(inode, raw_file) };
191 if ret != 0 {
192 return ret;
193 }
194
195 // SAFETY: The open call of a file can access the private data.
196 let misc_ptr = unsafe { (*raw_file).private_data };
197
198 // SAFETY: This is a miscdevice, so `misc_open()` set the private data to a pointer to the
199 // associated `struct miscdevice` before calling into this method. Furthermore,
200 // `misc_open()` ensures that the miscdevice can't be unregistered and freed during this
201 // call to `fops_open`.
202 let misc = unsafe { &*misc_ptr.cast::<MiscDeviceRegistration<T>>() };
203
204 // SAFETY:
205 // * This underlying file is valid for (much longer than) the duration of `T::open`.
206 // * There is no active fdget_pos region on the file on this thread.
207 let file = unsafe { File::from_raw_file(raw_file) };
208
209 let ptr = match T::open(file, misc) {
210 Ok(ptr) => ptr,
211 Err(err) => return err.to_errno(),
212 };
213
214 // This overwrites the private data with the value specified by the user, changing the type
215 // of this file's private data. All future accesses to the private data is performed by
216 // other fops_* methods in this file, which all correctly cast the private data to the new
217 // type.
218 //
219 // SAFETY: The open call of a file can access the private data.
220 unsafe { (*raw_file).private_data = ptr.into_foreign().cast() };
221
222 0
223 }
224
225 /// # Safety
226 ///
227 /// `file` and `inode` must be the file and inode for a file that is being released. The file
228 /// must be associated with a `MiscDeviceRegistration<T>`.
229 unsafe extern "C" fn release(_inode: *mut bindings::inode, file: *mut bindings::file) -> c_int {
230 // SAFETY: The release call of a file owns the private data.
231 let private = unsafe { (*file).private_data }.cast();
232 // SAFETY: The release call of a file owns the private data.
233 let ptr = unsafe { <T::Ptr as ForeignOwnable>::from_foreign(private) };
234
235 // SAFETY:
236 // * The file is valid for the duration of this call.
237 // * There is no active fdget_pos region on the file on this thread.
238 T::release(ptr, unsafe { File::from_raw_file(file) });
239
240 0
241 }
242
243 /// # Safety
244 ///
245 /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
246 /// `vma` must be a vma that is currently being mmap'ed with this file.
247 unsafe extern "C" fn mmap(
248 file: *mut bindings::file,
249 vma: *mut bindings::vm_area_struct,
250 ) -> c_int {
251 // SAFETY: The mmap call of a file can access the private data.
252 let private = unsafe { (*file).private_data };
253 // SAFETY: This is a Rust Miscdevice, so we call `into_foreign` in `open` and
254 // `from_foreign` in `release`, and `fops_mmap` is guaranteed to be called between those
255 // two operations.
256 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private.cast()) };
257 // SAFETY: The caller provides a vma that is undergoing initial VMA setup.
258 let area = unsafe { VmaNew::from_raw(vma) };
259 // SAFETY:
260 // * The file is valid for the duration of this call.
261 // * There is no active fdget_pos region on the file on this thread.
262 let file = unsafe { File::from_raw_file(file) };
263
264 match T::mmap(device, file, area) {
265 Ok(()) => 0,
266 Err(err) => err.to_errno(),
267 }
268 }
269
270 /// # Safety
271 ///
272 /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
273 unsafe extern "C" fn ioctl(file: *mut bindings::file, cmd: c_uint, arg: c_ulong) -> c_long {
274 // SAFETY: The ioctl call of a file can access the private data.
275 let private = unsafe { (*file).private_data }.cast();
276 // SAFETY: Ioctl calls can borrow the private data of the file.
277 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
278
279 // SAFETY:
280 // * The file is valid for the duration of this call.
281 // * There is no active fdget_pos region on the file on this thread.
282 let file = unsafe { File::from_raw_file(file) };
283
284 match T::ioctl(device, file, cmd, arg) {
285 Ok(ret) => ret as c_long,
286 Err(err) => err.to_errno() as c_long,
287 }
288 }
289
290 /// # Safety
291 ///
292 /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
293 #[cfg(CONFIG_COMPAT)]
294 unsafe extern "C" fn compat_ioctl(
295 file: *mut bindings::file,
296 cmd: c_uint,
297 arg: c_ulong,
298 ) -> c_long {
299 // SAFETY: The compat ioctl call of a file can access the private data.
300 let private = unsafe { (*file).private_data }.cast();
301 // SAFETY: Ioctl calls can borrow the private data of the file.
302 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
303
304 // SAFETY:
305 // * The file is valid for the duration of this call.
306 // * There is no active fdget_pos region on the file on this thread.
307 let file = unsafe { File::from_raw_file(file) };
308
309 match T::compat_ioctl(device, file, cmd, arg) {
310 Ok(ret) => ret as c_long,
311 Err(err) => err.to_errno() as c_long,
312 }
313 }
314
315 /// # Safety
316 ///
317 /// - `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`.
318 /// - `seq_file` must be a valid `struct seq_file` that we can write to.
319 unsafe extern "C" fn show_fdinfo(seq_file: *mut bindings::seq_file, file: *mut bindings::file) {
320 // SAFETY: The release call of a file owns the private data.
321 let private = unsafe { (*file).private_data }.cast();
322 // SAFETY: Ioctl calls can borrow the private data of the file.
323 let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
324 // SAFETY:
325 // * The file is valid for the duration of this call.
326 // * There is no active fdget_pos region on the file on this thread.
327 let file = unsafe { File::from_raw_file(file) };
328 // SAFETY: The caller ensures that the pointer is valid and exclusive for the duration in
329 // which this method is called.
330 let m = unsafe { SeqFile::from_raw(seq_file) };
331
332 T::show_fdinfo(device, m, file);
333 }
334
335 const VTABLE: bindings::file_operations = bindings::file_operations {
336 open: Some(Self::open),
337 release: Some(Self::release),
338 mmap: if T::HAS_MMAP { Some(Self::mmap) } else { None },
339 unlocked_ioctl: if T::HAS_IOCTL {
340 Some(Self::ioctl)
341 } else {
342 None
343 },
344 #[cfg(CONFIG_COMPAT)]
345 compat_ioctl: if T::HAS_COMPAT_IOCTL {
346 Some(Self::compat_ioctl)
347 } else if T::HAS_IOCTL {
348 Some(bindings::compat_ptr_ioctl)
349 } else {
350 None
351 },
352 show_fdinfo: if T::HAS_SHOW_FDINFO {
353 Some(Self::show_fdinfo)
354 } else {
355 None
356 },
357 // SAFETY: All zeros is a valid value for `bindings::file_operations`.
358 ..unsafe { MaybeUninit::zeroed().assume_init() }
359 };
360
361 const fn build() -> &'static bindings::file_operations {
362 &Self::VTABLE
363 }
364}
365

source code of linux/rust/kernel/miscdevice.rs

Morty Proxy This is a proxified and sanitized view of the page, visit original site.