kernel/drm/driver.rs
1// SPDX-License-Identifier: GPL-2.0 OR MIT
2
3//! DRM driver core.
4//!
5//! C header: [`include/drm/drm_drv.h`](srctree/include/drm/drm_drv.h)
6
7use crate::{
8 bindings,
9 device,
10 drm,
11 error::to_result,
12 prelude::*,
13 sync::aref::ARef, //
14};
15use core::ptr::NonNull;
16
17/// Driver use the GEM memory manager. This should be set for all modern drivers.
18pub(crate) const FEAT_GEM: u32 = bindings::drm_driver_feature_DRIVER_GEM;
19/// Driver supports render nodes, i.e.: /dev/dri/renderDXX devices.
20pub(crate) const FEAT_RENDER: u32 = bindings::drm_driver_feature_DRIVER_RENDER;
21
22/// Information data for a DRM Driver.
23pub struct DriverInfo {
24 /// Driver major version.
25 pub major: i32,
26 /// Driver minor version.
27 pub minor: i32,
28 /// Driver patchlevel version.
29 pub patchlevel: i32,
30 /// Driver name.
31 pub name: &'static CStr,
32 /// Driver description.
33 pub desc: &'static CStr,
34}
35
36/// Internal memory management operation set, normally created by memory managers (e.g. GEM).
37pub struct AllocOps {
38 pub(crate) gem_create_object: Option<
39 unsafe extern "C" fn(
40 dev: *mut bindings::drm_device,
41 size: usize,
42 ) -> *mut bindings::drm_gem_object,
43 >,
44 pub(crate) prime_handle_to_fd: Option<
45 unsafe extern "C" fn(
46 dev: *mut bindings::drm_device,
47 file_priv: *mut bindings::drm_file,
48 handle: u32,
49 flags: u32,
50 prime_fd: *mut core::ffi::c_int,
51 ) -> core::ffi::c_int,
52 >,
53 pub(crate) prime_fd_to_handle: Option<
54 unsafe extern "C" fn(
55 dev: *mut bindings::drm_device,
56 file_priv: *mut bindings::drm_file,
57 prime_fd: core::ffi::c_int,
58 handle: *mut u32,
59 ) -> core::ffi::c_int,
60 >,
61 pub(crate) gem_prime_import: Option<
62 unsafe extern "C" fn(
63 dev: *mut bindings::drm_device,
64 dma_buf: *mut bindings::dma_buf,
65 ) -> *mut bindings::drm_gem_object,
66 >,
67 pub(crate) gem_prime_import_sg_table: Option<
68 unsafe extern "C" fn(
69 dev: *mut bindings::drm_device,
70 attach: *mut bindings::dma_buf_attachment,
71 sgt: *mut bindings::sg_table,
72 ) -> *mut bindings::drm_gem_object,
73 >,
74 pub(crate) dumb_create: Option<
75 unsafe extern "C" fn(
76 file_priv: *mut bindings::drm_file,
77 dev: *mut bindings::drm_device,
78 args: *mut bindings::drm_mode_create_dumb,
79 ) -> core::ffi::c_int,
80 >,
81 pub(crate) dumb_map_offset: Option<
82 unsafe extern "C" fn(
83 file_priv: *mut bindings::drm_file,
84 dev: *mut bindings::drm_device,
85 handle: u32,
86 offset: *mut u64,
87 ) -> core::ffi::c_int,
88 >,
89}
90
91/// Trait for memory manager implementations. Implemented internally.
92pub trait AllocImpl: super::private::Sealed + drm::gem::IntoGEMObject {
93 /// The [`Driver`] implementation for this [`AllocImpl`].
94 type Driver: drm::Driver;
95
96 /// The C callback operations for this memory manager.
97 const ALLOC_OPS: AllocOps;
98}
99
100/// The DRM `Driver` trait.
101///
102/// This trait must be implemented by drivers in order to create a `struct drm_device` and `struct
103/// drm_driver` to be registered in the DRM subsystem.
104#[vtable]
105pub trait Driver {
106 /// Context data associated with the DRM driver
107 type Data: Sync + Send;
108
109 /// Data owned by the [`Registration`] and accessible within a
110 /// [`RegistrationGuard`](drm::RegistrationGuard) critical section via
111 /// [`Device::registration_data_with()`](drm::Device::registration_data_with).
112 ///
113 /// The lifetime parameter is tied to the [`Registration`] scope, which is enclosed in the
114 /// parent bus device binding scope but may be shorter.
115 type RegistrationData<'a>: Send + Sync + 'a;
116
117 /// The type used to manage memory for this driver.
118 type Object: AllocImpl;
119
120 /// The type used to represent a DRM File (client)
121 type File: drm::file::DriverFile;
122
123 /// The bus device type of the parent device that the DRM device is associated with.
124 type ParentDevice<Ctx: device::DeviceContext>: device::AsBusDevice<Ctx>;
125
126 /// Driver metadata
127 const INFO: DriverInfo;
128
129 /// IOCTL list. See `kernel::drm::ioctl::declare_drm_ioctls!{}`.
130 const IOCTLS: &'static [drm::ioctl::DrmIoctlDescriptor];
131
132 /// Sets the `DRIVER_RENDER` feature for this driver.
133 ///
134 /// When enabled, the driver exposes `/dev/dri/renderDXX` render nodes to
135 /// userspace. The render node is an alternate low-privilege way to access
136 /// the driver, which is enforced on a per-ioctl level. Userspace processes
137 /// that open the render node can only invoke ioctls explicitly listed as
138 /// usable from the render node (i.e. marked DRM_RENDER_ALLOW), whereas
139 /// userspace processes using the master node can invoke any ioctl.
140 const FEAT_RENDER: bool = false;
141}
142
143/// The registration type of a `drm::Device`.
144///
145/// Once the `Registration` structure is dropped, the device is unregistered.
146pub struct Registration<'a, T: Driver> {
147 drm: ARef<drm::Device<T>>,
148 _reg_data: Pin<KBox<T::RegistrationData<'a>>>,
149}
150
151impl<'a, T: Driver> Registration<'a, T> {
152 /// Register a new [`UnregisteredDevice`](drm::UnregisteredDevice) with userspace.
153 ///
154 /// # Safety
155 ///
156 /// The caller must not `mem::forget()` the returned [`Registration`] or otherwise prevent its
157 /// [`Drop`] implementation from running, since the registration data may contain borrowed
158 /// references that become invalid after `'a` ends.
159 pub unsafe fn new<E>(
160 dev: &'a device::Device<device::Bound>,
161 drm: drm::UnregisteredDevice<T>,
162 reg_data: impl PinInit<T::RegistrationData<'a>, E>,
163 flags: usize,
164 ) -> Result<Self>
165 where
166 Error: From<E>,
167 {
168 let parent = drm.as_ref();
169 if parent.as_ref().as_raw() != dev.as_raw() {
170 return Err(EINVAL);
171 }
172
173 let reg_data: Pin<KBox<T::RegistrationData<'a>>> = KBox::pin_init(reg_data, GFP_KERNEL)?;
174
175 // Store the registration data pointer in the device before registration, so that it is
176 // visible once ioctls can be called.
177 let ptr: NonNull<T::RegistrationData<'static>> =
178 NonNull::from(Pin::get_ref(reg_data.as_ref())).cast();
179
180 // SAFETY: No concurrent access; the device is not yet registered.
181 unsafe { *drm.registration_data.get() = ptr };
182
183 // SAFETY: `drm` is a valid, initialized but not yet registered DRM device.
184 let ret = unsafe { bindings::drm_dev_register(drm.as_raw(), flags) };
185 if let Err(e) = to_result(ret) {
186 // SAFETY: `drm_dev_register()` synchronizes SRCU on failure, so no concurrent
187 // access to `registration_data` is possible at this point.
188 unsafe { *drm.registration_data.get() = NonNull::dangling() };
189 return Err(e);
190 }
191
192 Ok(Self {
193 drm: (&*drm).into(),
194 _reg_data: reg_data,
195 })
196 }
197
198 /// Returns a reference to the `Device` instance for this registration.
199 pub fn device(&self) -> &drm::Device<T> {
200 &self.drm
201 }
202}
203
204// SAFETY: `Registration` doesn't offer any methods or access to fields when shared between
205// threads, hence it's safe to share it.
206unsafe impl<T: Driver> Sync for Registration<'_, T> {}
207
208// SAFETY: Registration with and unregistration from the DRM subsystem can happen from any thread.
209unsafe impl<T: Driver> Send for Registration<'_, T> {}
210
211impl<T: Driver> Drop for Registration<'_, T> {
212 fn drop(&mut self) {
213 // Use `drm_dev_unplug` rather than `drm_dev_unregister` to ensure that existing
214 // `drm_dev_enter()` critical sections complete before unregistration proceeds. This
215 // is required for the safety of `RegistrationGuard`, which relies on the SRCU barrier in
216 // `drm_dev_unplug()` to guarantee that the parent device is still bound within the
217 // critical section.
218 //
219 // SAFETY: Safe by the invariant of `ARef<drm::Device<T>>`. The existence of this
220 // `Registration` also guarantees that this `drm::Device` is actually registered.
221 unsafe { bindings::drm_dev_unplug(self.drm.as_raw()) };
222 // After drm_dev_unplug(), the SRCU barrier guarantees that all RegistrationGuard critical
223 // sections have completed, so no one holds a reference to reg_data anymore.
224 // reg_data is dropped here automatically.
225 }
226}