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, Kiocb},
17
    iov::{IovIterDest, IovIterSource},
18
    mm::virt::VmaNew,
19
    prelude::*,
20
    seq_file::SeqFile,
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 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)]
57
pub 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`.
65
unsafe 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.
68
unsafe impl<T> Sync for MiscDeviceRegistration<T> {}
69

70
impl<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]
106
impl<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]
115
pub 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.
197
struct MiscdeviceVTable<T: MiscDevice>(PhantomData<T>);
198

199
impl<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
}
431

432