projects/linux·blob v6.19 · refs

430 lines · 16.3 KiB

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