Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! Miscdevice support.//!//! C headers: [`include/linux/miscdevice.h`](srctree/include/linux/miscdevice.h).//!//! Reference: <https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html>
use crate::{ bindings, device::Device, error::{ to_result, VTABLE_DEFAULT_ERROR, // }, fs::{ File, Kiocb, // }, iov::{ IovIterDest, IovIterSource, // }, mm::virt::VmaNew, prelude::*, seq_file::SeqFile, types::{ ForeignOwnable, Opaque, // },};use core::marker::PhantomData;
/// Options for creating a misc device.#[derive(Copy, Clone)]pub struct MiscDeviceOptions { /// The name of the miscdevice. pub name: &'static CStr,}
impl MiscDeviceOptions { /// Create a raw `struct miscdev` ready for registration. pub const fn into_raw<T: MiscDevice>(self) -> bindings::miscdevice { let mut result: bindings::miscdevice = pin_init::zeroed(); result.minor = bindings::MISC_DYNAMIC_MINOR as ffi::c_int; result.name = crate::str::as_char_ptr_in_const_context(self.name); result.fops = MiscdeviceVTable::<T>::build(); result }}
/// A registration of a miscdevice.////// # Invariants////// - `inner` contains a `struct miscdevice` that is registered using/// `misc_register()`./// - This registration remains valid for the entire lifetime of the/// [`MiscDeviceRegistration`] instance./// - Deregistration occurs exactly once in [`Drop`] via `misc_deregister()`./// - `inner` wraps a valid, pinned `miscdevice` created using/// [`MiscDeviceOptions::into_raw`].#[repr(transparent)]#[pin_data(PinnedDrop)]pub struct MiscDeviceRegistration<T> { #[pin] inner: Opaque<bindings::miscdevice>, _t: PhantomData<T>,}
// SAFETY: It is allowed to call `misc_deregister` on a different thread from where you called// `misc_register`.unsafe impl<T> Send for MiscDeviceRegistration<T> {}// SAFETY: All `&self` methods on this type are written to ensure that it is safe to call them in// parallel.unsafe impl<T> Sync for MiscDeviceRegistration<T> {}
impl<T: MiscDevice> MiscDeviceRegistration<T> { /// Register a misc device. pub fn register(opts: MiscDeviceOptions) -> impl PinInit<Self, Error> { try_pin_init!(Self { inner <- Opaque::try_ffi_init(move |slot: *mut bindings::miscdevice| { // SAFETY: The initializer can write to the provided `slot`. unsafe { slot.write(opts.into_raw::<T>()) };
// SAFETY: We just wrote the misc device options to the slot. The miscdevice will // get unregistered before `slot` is deallocated because the memory is pinned and // the destructor of this type deallocates the memory. // INVARIANT: If this returns `Ok(())`, then the `slot` will contain a registered // misc device. to_result(unsafe { bindings::misc_register(slot) }) }), _t: PhantomData, }) }
/// Returns a raw pointer to the misc device. pub fn as_raw(&self) -> *mut bindings::miscdevice { self.inner.get() }
/// Access the `this_device` field. pub fn device(&self) -> &Device { // SAFETY: This can only be called after a successful register(), which always // initialises `this_device` with a valid device. Furthermore, the signature of this // function tells the borrow-checker that the `&Device` reference must not outlive the // `&MiscDeviceRegistration<T>` used to obtain it, so the last use of the reference must be // before the underlying `struct miscdevice` is destroyed. unsafe { Device::from_raw((*self.as_raw()).this_device) } }}
#[pinned_drop]impl<T> PinnedDrop for MiscDeviceRegistration<T> { fn drop(self: Pin<&mut Self>) { // SAFETY: We know that the device is registered by the type invariants. unsafe { bindings::misc_deregister(self.inner.get()) }; }}
/// Trait implemented by the private data of an open misc device.#[vtable]pub trait MiscDevice: Sized { /// What kind of pointer should `Self` be wrapped in. type Ptr: ForeignOwnable + Send + Sync;
/// Called when the misc device is opened. /// /// The returned pointer will be stored as the private data for the file. fn open(_file: &File, _misc: &MiscDeviceRegistration<Self>) -> Result<Self::Ptr>;
/// Called when the misc device is released. fn release(device: Self::Ptr, _file: &File) { drop(device); }
/// Handle for mmap. /// /// This function is invoked when a user space process invokes the `mmap` system call on /// `file`. The function is a callback that is part of the VMA initializer. The kernel will do /// initial setup of the VMA before calling this function. The function can then interact with /// the VMA initialization by calling methods of `vma`. If the function does not return an /// error, the kernel will complete initialization of the VMA according to the properties of /// `vma`. fn mmap( _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _file: &File, _vma: &VmaNew, ) -> Result { build_error!(VTABLE_DEFAULT_ERROR) }
/// Read from this miscdevice. fn read_iter(_kiocb: Kiocb<'_, Self::Ptr>, _iov: &mut IovIterDest<'_>) -> Result<usize> { build_error!(VTABLE_DEFAULT_ERROR) }
/// Write to this miscdevice. fn write_iter(_kiocb: Kiocb<'_, Self::Ptr>, _iov: &mut IovIterSource<'_>) -> Result<usize> { build_error!(VTABLE_DEFAULT_ERROR) }
/// Handler for ioctls. /// /// The `cmd` argument is usually manipulated using the utilities in [`kernel::ioctl`]. /// /// [`kernel::ioctl`]: mod@crate::ioctl fn ioctl( _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _file: &File, _cmd: u32, _arg: usize, ) -> Result<isize> { build_error!(VTABLE_DEFAULT_ERROR) }
/// Handler for ioctls. /// /// Used for 32-bit userspace on 64-bit platforms. /// /// This method is optional and only needs to be provided if the ioctl relies on structures /// that have different layout on 32-bit and 64-bit userspace. If no implementation is /// provided, then `compat_ptr_ioctl` will be used instead. #[cfg(CONFIG_COMPAT)] fn compat_ioctl( _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _file: &File, _cmd: u32, _arg: usize, ) -> Result<isize> { build_error!(VTABLE_DEFAULT_ERROR) }
/// Show info for this fd. fn show_fdinfo( _device: <Self::Ptr as ForeignOwnable>::Borrowed<'_>, _m: &SeqFile, _file: &File, ) { build_error!(VTABLE_DEFAULT_ERROR) }}
/// A vtable for the file operations of a Rust miscdevice.struct MiscdeviceVTable<T: MiscDevice>(PhantomData<T>);
impl<T: MiscDevice> MiscdeviceVTable<T> { /// # Safety /// /// `file` and `inode` must be the file and inode for a file that is undergoing initialization. /// The file must be associated with a `MiscDeviceRegistration<T>`. unsafe extern "C" fn open(inode: *mut bindings::inode, raw_file: *mut bindings::file) -> c_int { // SAFETY: The pointers are valid and for a file being opened. let ret = unsafe { bindings::generic_file_open(inode, raw_file) }; if ret != 0 { return ret; }
// SAFETY: The open call of a file can access the private data. let misc_ptr = unsafe { (*raw_file).private_data };
// SAFETY: This is a miscdevice, so `misc_open()` set the private data to a pointer to the // associated `struct miscdevice` before calling into this method. Furthermore, // `misc_open()` ensures that the miscdevice can't be unregistered and freed during this // call to `fops_open`. let misc = unsafe { &*misc_ptr.cast::<MiscDeviceRegistration<T>>() };
// SAFETY: // * This underlying file is valid for (much longer than) the duration of `T::open`. // * There is no active fdget_pos region on the file on this thread. let file = unsafe { File::from_raw_file(raw_file) };
let ptr = match T::open(file, misc) { Ok(ptr) => ptr, Err(err) => return err.to_errno(), };
// This overwrites the private data with the value specified by the user, changing the type // of this file's private data. All future accesses to the private data is performed by // other fops_* methods in this file, which all correctly cast the private data to the new // type. // // SAFETY: The open call of a file can access the private data. unsafe { (*raw_file).private_data = ptr.into_foreign() };
0 }
/// # Safety /// /// `file` and `inode` must be the file and inode for a file that is being released. The file /// must be associated with a `MiscDeviceRegistration<T>`. unsafe extern "C" fn release(_inode: *mut bindings::inode, file: *mut bindings::file) -> c_int { // SAFETY: The release call of a file owns the private data. let private = unsafe { (*file).private_data }; // SAFETY: The release call of a file owns the private data. let ptr = unsafe { <T::Ptr as ForeignOwnable>::from_foreign(private) };
// SAFETY: // * The file is valid for the duration of this call. // * There is no active fdget_pos region on the file on this thread. T::release(ptr, unsafe { File::from_raw_file(file) });
0 }
/// # Safety /// /// `kiocb` must be correspond to a valid file that is associated with a /// `MiscDeviceRegistration<T>`. `iter` must be a valid `struct iov_iter` for writing. unsafe extern "C" fn read_iter( kiocb: *mut bindings::kiocb, iter: *mut bindings::iov_iter, ) -> isize { // SAFETY: The caller provides a valid `struct kiocb` associated with a // `MiscDeviceRegistration<T>` file. let kiocb = unsafe { Kiocb::from_raw(kiocb) }; // SAFETY: This is a valid `struct iov_iter` for writing. let iov = unsafe { IovIterDest::from_raw(iter) };
match T::read_iter(kiocb, iov) { Ok(res) => res as isize, Err(err) => err.to_errno() as isize, } }
/// # Safety /// /// `kiocb` must be correspond to a valid file that is associated with a /// `MiscDeviceRegistration<T>`. `iter` must be a valid `struct iov_iter` for writing. unsafe extern "C" fn write_iter( kiocb: *mut bindings::kiocb, iter: *mut bindings::iov_iter, ) -> isize { // SAFETY: The caller provides a valid `struct kiocb` associated with a // `MiscDeviceRegistration<T>` file. let kiocb = unsafe { Kiocb::from_raw(kiocb) }; // SAFETY: This is a valid `struct iov_iter` for reading. let iov = unsafe { IovIterSource::from_raw(iter) };
match T::write_iter(kiocb, iov) { Ok(res) => res as isize, Err(err) => err.to_errno() as isize, } }
/// # Safety /// /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`. /// `vma` must be a vma that is currently being mmap'ed with this file. unsafe extern "C" fn mmap( file: *mut bindings::file, vma: *mut bindings::vm_area_struct, ) -> c_int { // SAFETY: The mmap call of a file can access the private data. let private = unsafe { (*file).private_data }; // SAFETY: This is a Rust Miscdevice, so we call `into_foreign` in `open` and // `from_foreign` in `release`, and `fops_mmap` is guaranteed to be called between those // two operations. let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private.cast()) }; // SAFETY: The caller provides a vma that is undergoing initial VMA setup. let area = unsafe { VmaNew::from_raw(vma) }; // SAFETY: // * The file is valid for the duration of this call. // * There is no active fdget_pos region on the file on this thread. let file = unsafe { File::from_raw_file(file) };
match T::mmap(device, file, area) { Ok(()) => 0, Err(err) => err.to_errno(), } }
/// # Safety /// /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`. unsafe extern "C" fn ioctl(file: *mut bindings::file, cmd: c_uint, arg: c_ulong) -> c_long { // SAFETY: The ioctl call of a file can access the private data. let private = unsafe { (*file).private_data }; // SAFETY: Ioctl calls can borrow the private data of the file. let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
// SAFETY: // * The file is valid for the duration of this call. // * There is no active fdget_pos region on the file on this thread. let file = unsafe { File::from_raw_file(file) };
match T::ioctl(device, file, cmd, arg) { Ok(ret) => ret as c_long, Err(err) => err.to_errno() as c_long, } }
/// # Safety /// /// `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`. #[cfg(CONFIG_COMPAT)] unsafe extern "C" fn compat_ioctl( file: *mut bindings::file, cmd: c_uint, arg: c_ulong, ) -> c_long { // SAFETY: The compat ioctl call of a file can access the private data. let private = unsafe { (*file).private_data }; // SAFETY: Ioctl calls can borrow the private data of the file. let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) };
// SAFETY: // * The file is valid for the duration of this call. // * There is no active fdget_pos region on the file on this thread. let file = unsafe { File::from_raw_file(file) };
match T::compat_ioctl(device, file, cmd, arg) { Ok(ret) => ret as c_long, Err(err) => err.to_errno() as c_long, } }
/// # Safety /// /// - `file` must be a valid file that is associated with a `MiscDeviceRegistration<T>`. /// - `seq_file` must be a valid `struct seq_file` that we can write to. unsafe extern "C" fn show_fdinfo(seq_file: *mut bindings::seq_file, file: *mut bindings::file) { // SAFETY: The release call of a file owns the private data. let private = unsafe { (*file).private_data }; // SAFETY: Ioctl calls can borrow the private data of the file. let device = unsafe { <T::Ptr as ForeignOwnable>::borrow(private) }; // SAFETY: // * The file is valid for the duration of this call. // * There is no active fdget_pos region on the file on this thread. let file = unsafe { File::from_raw_file(file) }; // SAFETY: The caller ensures that the pointer is valid and exclusive for the duration in // which this method is called. let m = unsafe { SeqFile::from_raw(seq_file) };
T::show_fdinfo(device, m, file); }
const VTABLE: bindings::file_operations = bindings::file_operations { open: Some(Self::open), release: Some(Self::release), mmap: if T::HAS_MMAP { Some(Self::mmap) } else { None }, read_iter: if T::HAS_READ_ITER { Some(Self::read_iter) } else { None }, write_iter: if T::HAS_WRITE_ITER { Some(Self::write_iter) } else { None }, unlocked_ioctl: if T::HAS_IOCTL { Some(Self::ioctl) } else { None }, #[cfg(CONFIG_COMPAT)] compat_ioctl: if T::HAS_COMPAT_IOCTL { Some(Self::compat_ioctl) } else if T::HAS_IOCTL { bindings::compat_ptr_ioctl } else { None }, show_fdinfo: if T::HAS_SHOW_FDINFO { Some(Self::show_fdinfo) } else { None }, ..pin_init::zeroed() };
const fn build() -> &'static bindings::file_operations { &Self::VTABLE }}