xref: /linux/rust/kernel/miscdevice.rs (revision 25489a4f556414445d342951615178368ee45cde)
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 
11 use 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 };
23 use core::{marker::PhantomData, mem::MaybeUninit, pin::Pin};
24 
25 /// Options for creating a misc device.
26 #[derive(Copy, Clone)]
27 pub struct MiscDeviceOptions {
28     /// The name of the miscdevice.
29     pub name: &'static CStr,
30 }
31 
32 impl 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)]
51 pub 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`.
59 unsafe 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.
62 unsafe impl<T> Sync for MiscDeviceRegistration<T> {}
63 
64 impl<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]
100 impl<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]
109 pub 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.
181 struct MiscdeviceVTable<T: MiscDevice>(PhantomData<T>);
182 
183 impl<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