kernel/drm/
file.rs

1// SPDX-License-Identifier: GPL-2.0 OR MIT
2
3//! DRM File objects.
4//!
5//! C header: [`include/linux/drm/drm_file.h`](srctree/include/linux/drm/drm_file.h)
6
7use crate::{bindings, drm, error::Result, prelude::*, types::Opaque};
8use core::marker::PhantomData;
9use core::pin::Pin;
10
11/// Trait that must be implemented by DRM drivers to represent a DRM File (a client instance).
12pub trait DriverFile {
13    /// The parent `Driver` implementation for this `DriverFile`.
14    type Driver: drm::Driver;
15
16    /// Open a new file (called when a client opens the DRM device).
17    fn open(device: &drm::Device<Self::Driver>) -> Result<Pin<KBox<Self>>>;
18}
19
20/// An open DRM File.
21///
22/// # Invariants
23///
24/// `self.0` is a valid instance of a `struct drm_file`.
25#[repr(transparent)]
26pub struct File<T: DriverFile>(Opaque<bindings::drm_file>, PhantomData<T>);
27
28impl<T: DriverFile> File<T> {
29    #[doc(hidden)]
30    /// Not intended to be called externally, except via declare_drm_ioctls!()
31    ///
32    /// # Safety
33    ///
34    /// `raw_file` must be a valid pointer to an open `struct drm_file`, opened through `T::open`.
35    pub unsafe fn as_ref<'a>(ptr: *mut bindings::drm_file) -> &'a File<T> {
36        // SAFETY: `raw_file` is valid by the safety requirements of this function.
37        unsafe { &*ptr.cast() }
38    }
39
40    pub(super) fn as_raw(&self) -> *mut bindings::drm_file {
41        self.0.get()
42    }
43
44    fn driver_priv(&self) -> *mut T {
45        // SAFETY: By the type invariants of `Self`, `self.as_raw()` is always valid.
46        unsafe { (*self.as_raw()).driver_priv }.cast()
47    }
48
49    /// Return a pinned reference to the driver file structure.
50    pub fn inner(&self) -> Pin<&T> {
51        // SAFETY: By the type invariant the pointer `self.as_raw()` points to a valid and opened
52        // `struct drm_file`, hence `driver_priv` has been properly initialized by `open_callback`.
53        unsafe { Pin::new_unchecked(&*(self.driver_priv())) }
54    }
55
56    /// The open callback of a `struct drm_file`.
57    pub(crate) extern "C" fn open_callback(
58        raw_dev: *mut bindings::drm_device,
59        raw_file: *mut bindings::drm_file,
60    ) -> core::ffi::c_int {
61        // SAFETY: A callback from `struct drm_driver::open` guarantees that
62        // - `raw_dev` is valid pointer to a `struct drm_device`,
63        // - the corresponding `struct drm_device` has been registered.
64        let drm = unsafe { drm::Device::as_ref(raw_dev) };
65
66        // SAFETY: `raw_file` is a valid pointer to a `struct drm_file`.
67        let file = unsafe { File::<T>::as_ref(raw_file) };
68
69        let inner = match T::open(drm) {
70            Err(e) => {
71                return e.to_errno();
72            }
73            Ok(i) => i,
74        };
75
76        // SAFETY: This pointer is treated as pinned, and the Drop guarantee is upheld in
77        // `postclose_callback()`.
78        let driver_priv = KBox::into_raw(unsafe { Pin::into_inner_unchecked(inner) });
79
80        // SAFETY: By the type invariants of `Self`, `self.as_raw()` is always valid.
81        unsafe { (*file.as_raw()).driver_priv = driver_priv.cast() };
82
83        0
84    }
85
86    /// The postclose callback of a `struct drm_file`.
87    pub(crate) extern "C" fn postclose_callback(
88        _raw_dev: *mut bindings::drm_device,
89        raw_file: *mut bindings::drm_file,
90    ) {
91        // SAFETY: This reference won't escape this function
92        let file = unsafe { File::<T>::as_ref(raw_file) };
93
94        // SAFETY: `file.driver_priv` has been created in `open_callback` through `KBox::into_raw`.
95        let _ = unsafe { KBox::from_raw(file.driver_priv()) };
96    }
97}
98
99impl<T: DriverFile> super::private::Sealed for File<T> {}
kernel/drm/file.rs

kernel/drm/
file.rs
