projects/linux·blob uaccess-cleanups · refs

588 lines · 22.0 KiB

1// SPDX-License-Identifier: GPL-2.0 OR MIT
2
3//! DRM device.
4//!
5//! C header: [`include/drm/drm_device.h`](srctree/include/drm/drm_device.h)
6
7use crate::{
8 alloc::allocator::Kmalloc,
9 bindings,
10 device,
11 drm::{
12 self,
13 driver::AllocImpl,
14 private::Sealed, //
15 },
16 error::from_err_ptr,
17 prelude::*,
18 sync::aref::{
19 ARef,
20 AlwaysRefCounted, //
21 },
22 types::{
23 NotThreadSafe,
24 Opaque, //
25 },
26 workqueue::{
27 HasDelayedWork,
28 HasWork,
29 Work,
30 WorkItem, //
31 }, //
32};
33use core::{
34 alloc::Layout,
35 cell::UnsafeCell,
36 marker::PhantomData,
37 mem,
38 ops::Deref,
39 ptr::{
40 self,
41 NonNull, //
42 },
43};
44
45#[cfg(CONFIG_DRM_LEGACY)]
46macro_rules! drm_legacy_fields {
47 ( $($field:ident: $val:expr),* $(,)? ) => {
48 bindings::drm_driver {
49 $( $field: $val ),*,
50 firstopen: None,
51 preclose: None,
52 dma_ioctl: None,
53 dma_quiescent: None,
54 context_dtor: None,
55 irq_handler: None,
56 irq_preinstall: None,
57 irq_postinstall: None,
58 irq_uninstall: None,
59 get_vblank_counter: None,
60 enable_vblank: None,
61 disable_vblank: None,
62 dev_priv_size: 0,
63 }
64 }
65}
66
67#[cfg(not(CONFIG_DRM_LEGACY))]
68macro_rules! drm_legacy_fields {
69 ( $($field:ident: $val:expr),* $(,)? ) => {
70 bindings::drm_driver {
71 $( $field: $val ),*
72 }
73 }
74}
75
76/// A trait implemented by all possible contexts a [`Device`] can be used in.
77///
78/// A [`Device`] can be in one of the following contexts:
79///
80/// - [`Normal`]: The general-purpose, reference-counted context. A [`Device`] in this context may
81/// or may not be registered with userspace.
82/// - [`Ioctl`]: The device has been registered with userspace at some point; used in ioctl
83/// dispatch context.
84/// - [`Registered`]: The device is currently registered with userspace and the parent bus device
85/// is bound.
86///
87/// Both `Device<T, Ioctl>` and `Device<T, Registered>` dereference to `Device<T>` ([`Normal`]),
88/// so any method available on a [`Normal`] device is also available in the other contexts.
89pub trait DeviceContext: Sealed + Send + Sync + 'static {}
90
91/// The general-purpose, reference-counted [`DeviceContext`].
92///
93/// A [`Device`] in this context may or may not be registered with userspace. This context is used
94/// for reference-counted device handles and during device setup via [`UnregisteredDevice`].
95///
96/// [`AlwaysRefCounted`] is only implemented for `Device<T, Normal>`, making this the required
97/// context for [`ARef`]-based device handles.
98pub struct Normal;
99
100impl Sealed for Normal {}
101impl DeviceContext for Normal {}
102
103/// The [`DeviceContext`] of a [`Device`] that is currently registered with userspace.
104///
105/// A [`Device`] in this context is guaranteed to be registered and its parent bus device is
106/// guaranteed to be bound. This is enforced at runtime by [`RegistrationGuard`], which holds a
107/// `drm_dev_enter()` / `drm_dev_exit()` SRCU critical section.
108///
109/// # Invariants
110///
111/// The parent bus device is bound for the duration of any reference to a `Device<T, Registered>`.
112pub struct Registered;
113
114impl Sealed for Registered {}
115impl DeviceContext for Registered {}
116
117/// The [`DeviceContext`] of a [`Device`] that has been registered with userspace previously.
118///
119/// A [`Device`] in this context has been registered at some point, but may be concurrently
120/// unregistering or already unregistered. `drm_dev_enter()` can guard against this, ensuring the
121/// device remains registered for the duration of the critical section.
122///
123/// # Invariants
124///
125/// A [`Device`] in this context has been registered with userspace via `drm_dev_register()` at
126/// some point.
127pub struct Ioctl;
128
129impl Sealed for Ioctl {}
130impl DeviceContext for Ioctl {}
131
132/// A [`Device`] which is known at compile-time to be unregistered with userspace.
133///
134/// This type allows performing operations which are only safe to do before userspace registration,
135/// and can be used to create a [`Registration`](drm::driver::Registration) once the driver is ready
136/// to register the device with userspace.
137///
138/// Since DRM device initialization must be single-threaded, this object is not thread-safe.
139///
140/// # Invariants
141///
142/// The device in `self.0` is guaranteed to be a newly created [`Device`] that has not yet been
143/// registered with userspace until this type is dropped.
144pub struct UnregisteredDevice<T: drm::Driver>(ARef<Device<T, Normal>>, NotThreadSafe);
145
146impl<T: drm::Driver> Deref for UnregisteredDevice<T> {
147 type Target = Device<T, Normal>;
148
149 fn deref(&self) -> &Self::Target {
150 &self.0
151 }
152}
153
154impl<T: drm::Driver> UnregisteredDevice<T> {
155 const fn compute_features() -> u32 {
156 let mut features = drm::driver::FEAT_GEM;
157
158 if T::FEAT_RENDER {
159 features |= drm::driver::FEAT_RENDER;
160 }
161
162 features
163 }
164
165 const VTABLE: bindings::drm_driver = drm_legacy_fields! {
166 load: None,
167 open: Some(drm::File::<T::File>::open_callback),
168 postclose: Some(drm::File::<T::File>::postclose_callback),
169 unload: None,
170 release: Some(Device::<T>::release),
171 master_set: None,
172 master_drop: None,
173 debugfs_init: None,
174
175 gem_create_object: T::Object::ALLOC_OPS.gem_create_object,
176 prime_handle_to_fd: T::Object::ALLOC_OPS.prime_handle_to_fd,
177 prime_fd_to_handle: T::Object::ALLOC_OPS.prime_fd_to_handle,
178 gem_prime_import: T::Object::ALLOC_OPS.gem_prime_import,
179 gem_prime_import_sg_table: T::Object::ALLOC_OPS.gem_prime_import_sg_table,
180 dumb_create: T::Object::ALLOC_OPS.dumb_create,
181 dumb_map_offset: T::Object::ALLOC_OPS.dumb_map_offset,
182
183 show_fdinfo: None,
184 fbdev_probe: None,
185
186 major: T::INFO.major,
187 minor: T::INFO.minor,
188 patchlevel: T::INFO.patchlevel,
189 name: crate::str::as_char_ptr_in_const_context(T::INFO.name).cast_mut(),
190 desc: crate::str::as_char_ptr_in_const_context(T::INFO.desc).cast_mut(),
191
192 driver_features: Self::compute_features(),
193 ioctls: T::IOCTLS.as_ptr(),
194 num_ioctls: T::IOCTLS.len() as i32,
195 fops: &Self::GEM_FOPS,
196 };
197
198 const GEM_FOPS: bindings::file_operations =
199 drm::gem::create_fops(crate::module::this_module::<T::OwnerModule>().as_ptr());
200
201 /// Create a new `UnregisteredDevice` for a `drm::Driver`.
202 ///
203 /// This can be used to create a [`Registration`](kernel::drm::Registration).
204 pub fn new(
205 dev: &T::ParentDevice<device::Bound>,
206 data: impl PinInit<T::Data, Error>,
207 ) -> Result<Self> {
208 // `__drm_dev_alloc` uses `kmalloc()` to allocate memory, hence ensure a `kmalloc()`
209 // compatible `Layout`.
210 let layout = Kmalloc::aligned_layout(Layout::new::<Device<T, Normal>>());
211
212 // Use a temporary vtable without a `release` callback until `data` is initialized, so
213 // init failure can release the DRM device without dropping uninitialized fields.
214 let alloc_vtable = bindings::drm_driver {
215 release: None,
216 ..Self::VTABLE
217 };
218
219 // SAFETY:
220 // - `alloc_vtable` reference remains valid until no longer used,
221 // - `dev` is valid by its type invarants,
222 let raw_drm: *mut Device<T, Normal> = unsafe {
223 bindings::__drm_dev_alloc(
224 dev.as_ref().as_raw(),
225 &alloc_vtable,
226 layout.size(),
227 mem::offset_of!(Device<T, Normal>, dev),
228 )
229 }
230 .cast();
231 let raw_drm = NonNull::new(from_err_ptr(raw_drm)?).ok_or(ENOMEM)?;
232
233 // SAFETY: `raw_drm` is a valid pointer to `Self`, given that `__drm_dev_alloc` was
234 // successful.
235 let drm_dev = unsafe { Device::into_drm_device(raw_drm) };
236
237 // SAFETY: `raw_drm` is a valid pointer to `Self`.
238 let raw_data = unsafe { ptr::addr_of_mut!((*raw_drm.as_ptr()).data) };
239
240 // SAFETY:
241 // - `raw_data` is a valid pointer to uninitialized memory.
242 // - `raw_data` will not move until it is dropped.
243 unsafe { pin_init::raw_try_init(raw_data, data) }.inspect_err(|_| {
244 // SAFETY: `__drm_dev_alloc()` was successful, hence `drm_dev` must be valid and the
245 // refcount must be non-zero.
246 unsafe { bindings::drm_dev_put(drm_dev) };
247 })?;
248
249 // SAFETY: `drm_dev` is still private to this function.
250 unsafe { (*drm_dev).driver = const { &Self::VTABLE } };
251
252 // SAFETY: `raw_drm` is valid; no concurrent access before registration.
253 unsafe { (*raw_drm.as_ptr()).registration_data = UnsafeCell::new(NonNull::dangling()) };
254
255 // SAFETY: The reference count is one, and now we take ownership of that reference as a
256 // `drm::Device`.
257 // INVARIANT: We just created the device above, but have yet to call `drm_dev_register`.
258 // `Self` cannot be copied or sent to another thread - ensuring that `drm_dev_register`
259 // won't be called during its lifetime and that the device is unregistered.
260 Ok(Self(unsafe { ARef::from_raw(raw_drm) }, NotThreadSafe))
261 }
262}
263
264/// A typed DRM device with a specific [`drm::Driver`] implementation and [`DeviceContext`].
265///
266/// A device in the [`Registered`] context is currently registered with userspace and its parent
267/// bus device is bound. The [`Normal`] context is the general-purpose, reference-counted context.
268///
269/// # Invariants
270///
271/// * `self.dev` is a valid instance of a `struct device`.
272/// * The data layout of `Self` remains the same across all implementations of `C`.
273/// * Any invariants for `C` also apply.
274#[repr(C)]
275pub struct Device<T: drm::Driver, C: DeviceContext = Normal> {
276 dev: Opaque<bindings::drm_device>,
277 data: T::Data,
278 pub(super) registration_data: UnsafeCell<NonNull<T::RegistrationData<'static>>>,
279 _ctx: PhantomData<C>,
280}
281
282impl<T: drm::Driver, C: DeviceContext> Device<T, C> {
283 pub(crate) fn as_raw(&self) -> *mut bindings::drm_device {
284 self.dev.get()
285 }
286
287 /// # Safety
288 ///
289 /// `ptr` must be a valid pointer to a `struct device` embedded in `Self`.
290 unsafe fn from_drm_device(ptr: *const bindings::drm_device) -> *mut Self {
291 // SAFETY: By the safety requirements of this function `ptr` is a valid pointer to a
292 // `struct drm_device` embedded in `Self`.
293 unsafe { crate::container_of!(Opaque::cast_from(ptr), Self, dev) }.cast_mut()
294 }
295
296 /// # Safety
297 ///
298 /// `ptr` must be a valid pointer to `Self`.
299 unsafe fn into_drm_device(ptr: NonNull<Self>) -> *mut bindings::drm_device {
300 // SAFETY: By the safety requirements of this function, `ptr` is a valid pointer to `Self`.
301 unsafe { &raw mut (*ptr.as_ptr()).dev }.cast()
302 }
303
304 /// Not intended to be called externally, except via declare_drm_ioctls!()
305 ///
306 /// # Safety
307 ///
308 /// * Callers must ensure that `ptr` is valid, non-null, and has a non-zero reference count,
309 /// i.e. it must be ensured that the reference count of the C `struct drm_device` `ptr` points
310 /// to can't drop to zero, for the duration of this function call and the entire duration when
311 /// the returned reference exists.
312 /// * Additionally, callers must ensure that the `struct device`, `ptr` is pointing to, is
313 /// embedded in `Self`.
314 /// * Callers promise that any type invariants of `C` will be upheld.
315 #[doc(hidden)]
316 pub unsafe fn from_raw<'a>(ptr: *const bindings::drm_device) -> &'a Self {
317 // SAFETY: By the safety requirements of this function `ptr` is a valid pointer to a
318 // `struct drm_device` embedded in `Self`.
319 let ptr = unsafe { Self::from_drm_device(ptr) };
320
321 // SAFETY: `ptr` is valid by the safety requirements of this function.
322 unsafe { &*ptr.cast() }
323 }
324
325 extern "C" fn release(ptr: *mut bindings::drm_device) {
326 // SAFETY: `ptr` is a valid pointer to a `struct drm_device` and embedded in `Self`.
327 let this = unsafe { Self::from_drm_device(ptr) };
328
329 // SAFETY:
330 // - When `release` runs it is guaranteed that there is no further access to `this`.
331 // - `this` is valid for dropping.
332 unsafe { core::ptr::drop_in_place(this) };
333 }
334
335 /// Change the [`DeviceContext`] for a [`Device`].
336 ///
337 /// # Safety
338 ///
339 /// The caller promises that `self` fulfills all of the guarantees provided by the given
340 /// [`DeviceContext`].
341 pub(crate) unsafe fn assume_ctx<NewCtx: DeviceContext>(&self) -> &Device<T, NewCtx> {
342 // SAFETY: The data layout is identical via our type invariants.
343 unsafe { mem::transmute(self) }
344 }
345}
346
347impl<T: drm::Driver> Device<T, Ioctl> {
348 /// Guard against the parent bus device being unbound.
349 ///
350 /// Returns a [`RegistrationGuard`] if the device has not been unplugged, [`None`] otherwise.
351 ///
352 /// While [`RegistrationGuard`] is held the parent device is guaranteed to be bound.
353 #[must_use]
354 pub fn registration_guard(&self) -> Option<RegistrationGuard<'_, T>> {
355 let mut idx: i32 = 0;
356 // SAFETY: `self.as_raw()` is a valid pointer to a `struct drm_device`.
357 if unsafe { bindings::drm_dev_enter(self.as_raw(), &mut idx) } {
358 // INVARIANT:
359 // - `idx` is the SRCU index from the successful `drm_dev_enter()` above.
360 // - The parent bus device is bound: `drm_dev_enter()` succeeded, meaning
361 // `drm_dev_unplug()` has not completed; since it is only called from
362 // `Registration::drop()` during parent unbind, the parent is still bound.
363 Some(RegistrationGuard {
364 // SAFETY: See INVARIANT above; the `Registered` context invariant holds.
365 dev: unsafe { self.assume_ctx() },
366 idx,
367 _not_send: NotThreadSafe,
368 })
369 } else {
370 None
371 }
372 }
373}
374
375/// A guard proving the DRM device is registered and the parent bus device is bound.
376///
377/// The guard dereferences to [`Device<T, Registered>`], providing access to the DRM device with
378/// the guarantee that the parent bus device is bound for the entire duration of the critical
379/// section.
380///
381/// Internally this is backed by a `drm_dev_enter()` / `drm_dev_exit()` SRCU critical section.
382///
383/// # Invariants
384///
385/// - `idx` is the SRCU read lock index returned by a successful `drm_dev_enter()` call.
386/// - The parent bus device of `dev` is bound for the lifetime of this guard.
387#[must_use]
388pub struct RegistrationGuard<'a, T: drm::Driver> {
389 dev: &'a Device<T, Registered>,
390 idx: i32,
391 _not_send: NotThreadSafe,
392}
393
394impl<T: drm::Driver> Device<T, Registered> {
395 /// Returns a reference to the registration data with lifetime shortened from `'static`.
396 ///
397 /// # Safety
398 ///
399 /// The returned reference must not be exposed to code that can choose a concrete lifetime for
400 /// it, as that would be unsound for types that are invariant over their lifetime parameter
401 /// (e.g. it must be passed through an HRTB-bounded closure).
402 #[inline]
403 unsafe fn registration_data_unchecked(&self) -> &T::RegistrationData<'_> {
404 // SAFETY:
405 // - `Registered` guarantees the parent bus device is bound, hence the pointer is valid.
406 // - The pointer cast from `Of<'static>` to `Of<'_>` is layout-compatible since lifetimes
407 // are erased at runtime.
408 // - Caller guarantees the reference is only used behind an HRTB, making the lifetime
409 // shortening sound regardless of variance.
410 unsafe { (*self.registration_data.get()).cast::<_>().as_ref() }
411 }
412
413 /// Access the registration data through a closure, with the lifetime tied to the closure
414 /// scope.
415 ///
416 /// The data is owned by [`Registration`](drm::Registration) and is guaranteed to remain valid
417 /// as long as the device is registered, since [`Registration`](drm::Registration)'s `drop`
418 /// calls `drm_dev_unplug()` which waits for all `drm_dev_enter()` critical sections to
419 /// complete.
420 #[inline]
421 pub fn registration_data_with<R, F>(&self, f: F) -> R
422 where
423 F: for<'a> FnOnce(&'a T::RegistrationData<'a>) -> R,
424 {
425 // SAFETY: `Registered` guarantees the device is registered and the parent bus device is
426 // bound. The closure's HRTB `for<'a>` prevents the caller from smuggling in references
427 // with a concrete short lifetime, satisfying the lifetime requirement of
428 // `registration_data_unchecked`.
429 f(unsafe { self.registration_data_unchecked() })
430 }
431}
432
433impl<T: drm::Driver> Deref for RegistrationGuard<'_, T> {
434 type Target = Device<T, Registered>;
435
436 #[inline]
437 fn deref(&self) -> &Self::Target {
438 self.dev
439 }
440}
441
442impl<T: drm::Driver> Drop for RegistrationGuard<'_, T> {
443 #[inline]
444 fn drop(&mut self) {
445 // SAFETY: `self.idx` was returned by a successful `drm_dev_enter()` call, as guaranteed
446 // by the type invariants of `RegistrationGuard`.
447 unsafe { bindings::drm_dev_exit(self.idx) };
448 }
449}
450
451impl<T: drm::Driver> Deref for Device<T> {
452 type Target = T::Data;
453
454 fn deref(&self) -> &Self::Target {
455 &self.data
456 }
457}
458
459impl<T: drm::Driver> Deref for Device<T, Registered> {
460 type Target = Device<T>;
461
462 #[inline]
463 fn deref(&self) -> &Self::Target {
464 // SAFETY: The caller holds a `Device<T, Registered>`, which guarantees all invariants
465 // of the weaker `Normal` context.
466 unsafe { self.assume_ctx() }
467 }
468}
469
470impl<T: drm::Driver> Deref for Device<T, Ioctl> {
471 type Target = Device<T>;
472
473 #[inline]
474 fn deref(&self) -> &Self::Target {
475 // SAFETY: The caller holds a `Device<T, Ioctl>`, which guarantees all invariants
476 // of the weaker `Normal` context.
477 unsafe { self.assume_ctx() }
478 }
479}
480
481// SAFETY: DRM device objects are always reference counted and the get/put functions
482// satisfy the requirements.
483unsafe impl<T: drm::Driver> AlwaysRefCounted for Device<T> {
484 fn inc_ref(&self) {
485 // SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
486 unsafe { bindings::drm_dev_get(self.as_raw()) };
487 }
488
489 unsafe fn dec_ref(obj: NonNull<Self>) {
490 // SAFETY: `obj` is a valid pointer to `Self`.
491 let drm_dev = unsafe { Self::into_drm_device(obj) };
492
493 // SAFETY: The safety requirements guarantee that the refcount is non-zero.
494 unsafe { bindings::drm_dev_put(drm_dev) };
495 }
496}
497
498impl<T: drm::Driver> AsRef<T::ParentDevice<device::Normal>> for Device<T> {
499 fn as_ref(&self) -> &T::ParentDevice<device::Normal> {
500 // SAFETY: `bindings::drm_device::dev` is valid as long as the DRM device itself is valid,
501 // which is guaranteed by the type invariant.
502 let dev = unsafe { device::Device::from_raw((*self.as_raw()).dev) };
503
504 // SAFETY: The DRM device was constructed in `UnregisteredDevice::new()` with a parent
505 // device of type `T::ParentDevice`, hence `dev` is contained in a `T::ParentDevice`.
506 unsafe { device::AsBusDevice::from_device(dev) }
507 }
508}
509
510impl<T: drm::Driver> AsRef<T::ParentDevice<device::Bound>> for Device<T, Registered> {
511 #[inline]
512 fn as_ref(&self) -> &T::ParentDevice<device::Bound> {
513 let dev = (**self).as_ref().as_ref();
514
515 // SAFETY: A `Device<T, Registered>` guarantees that the parent device is bound.
516 let dev = unsafe { dev.as_bound() };
517
518 // SAFETY: The DRM device was constructed in `UnregisteredDevice::new()` with a parent
519 // device of type `T::ParentDevice`, hence `dev` is contained in a `T::ParentDevice`.
520 unsafe { device::AsBusDevice::from_device(dev) }
521 }
522}
523
524// SAFETY: A `drm::Device` can be released from any thread.
525unsafe impl<T: drm::Driver, C: DeviceContext> Send for Device<T, C> {}
526
527// SAFETY: A `drm::Device` can be shared among threads because all immutable methods are protected
528// by the synchronization in `struct drm_device`.
529unsafe impl<T: drm::Driver, C: DeviceContext> Sync for Device<T, C> {}
530
531impl<T: drm::Driver, const ID: u64> WorkItem<ID> for Device<T>
532where
533 T::Data: WorkItem<ID, Pointer = ARef<Self>>,
534 T::Data: HasWork<Self, ID>,
535{
536 type Pointer = ARef<Self>;
537
538 fn run(ptr: ARef<Self>) {
539 T::Data::run(ptr);
540 }
541}
542
543// SAFETY:
544//
545// - `raw_get_work` and `work_container_of` return valid pointers by relying on
546// `T::Data::raw_get_work` and `container_of`. In particular, `T::Data` is
547// stored inline in `drm::Device`, so the `container_of` call is valid.
548//
549// - The two methods are true inverses of each other: given `ptr: *mut
550// Device<T, C>`, `raw_get_work` will return a `*mut Work<Device<T, C>, ID>` through
551// `T::Data::raw_get_work` and given a `ptr: *mut Work<Device<T, C>, ID>`,
552// `work_container_of` will return a `*mut Device<T, C>` through `container_of`.
553unsafe impl<T, C, const ID: u64> HasWork<Self, ID> for Device<T, C>
554where
555 T: drm::Driver,
556 T::Data: HasWork<Self, ID>,
557 C: DeviceContext,
558{
559 unsafe fn raw_get_work(ptr: *mut Self) -> *mut Work<Self, ID> {
560 // SAFETY: The caller promises that `ptr` points to a valid `Device<T, C>`.
561 let data_ptr = unsafe { &raw mut (*ptr).data };
562
563 // SAFETY: `data_ptr` is a valid pointer to `T::Data`.
564 unsafe { T::Data::raw_get_work(data_ptr) }
565 }
566
567 unsafe fn work_container_of(ptr: *mut Work<Self, ID>) -> *mut Self {
568 // SAFETY: The caller promises that `ptr` points at a `Work` field in
569 // `T::Data`.
570 let data_ptr = unsafe { T::Data::work_container_of(ptr) };
571
572 // SAFETY: `T::Data` is stored as the `data` field in `Device<T, C>`.
573 unsafe { crate::container_of!(data_ptr, Self, data) }
574 }
575}
576
577// SAFETY: Our `HasWork<T, ID>` implementation returns a `work_struct` that is
578// stored in the `work` field of a `delayed_work` with the same access rules as
579// the `work_struct` owing to the bound on `T::Data: HasDelayedWork<Device<T, C>,
580// ID>`, which requires that `T::Data::raw_get_work` return a `work_struct` that
581// is inside a `delayed_work`.
582unsafe impl<T, C, const ID: u64> HasDelayedWork<Self, ID> for Device<T, C>
583where
584 T: drm::Driver,
585 T::Data: HasDelayedWork<Self, ID>,
586 C: DeviceContext,
587{
588}