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 7 use crate::{bindings, drm, error::Result, prelude::*, types::Opaque}; 8 use core::marker::PhantomData; 9 use core::pin::Pin; 10 11 /// Trait that must be implemented by DRM drivers to represent a DRM File (a client instance). 12 pub 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). open(device: &drm::Device<Self::Driver>) -> Result<Pin<KBox<Self>>>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)] 26 pub struct File<T: DriverFile>(Opaque<bindings::drm_file>, PhantomData<T>); 27 28 impl<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`. from_raw<'a>(ptr: *mut bindings::drm_file) -> &'a File<T>35 pub unsafe fn from_raw<'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 as_raw(&self) -> *mut bindings::drm_file40 pub(super) fn as_raw(&self) -> *mut bindings::drm_file { 41 self.0.get() 42 } 43 driver_priv(&self) -> *mut T44 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. inner(&self) -> Pin<&T>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`. open_callback( raw_dev: *mut bindings::drm_device, raw_file: *mut bindings::drm_file, ) -> core::ffi::c_int57 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::from_raw(raw_dev) }; 65 66 // SAFETY: `raw_file` is a valid pointer to a `struct drm_file`. 67 let file = unsafe { File::<T>::from_raw(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`. postclose_callback( _raw_dev: *mut bindings::drm_device, raw_file: *mut bindings::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>::from_raw(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 99 impl<T: DriverFile> super::private::Sealed for File<T> {} 100