Text of rust.docs.kernel.org › src › kernel › dma_buf › dma_fence.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

dma_fence.rs - source

Skip to main content kernel/dma_buf/ dma_fence.rs 1 // SPDX-License-Identifier: GPL-2.0 2 /* 3 * Copyright (C) 2025-2026 Red Hat Inc. 4 * Author: Philipp Stanner <pstanner@redhat.com> 5 */ 6 7 //! DMA Fence support. 8 //! 9 //! Reference: <https://docs.kernel.org/driver-api/dma-buf.html#c.dma_fence> 10 //! 11 //! header: [`include/linux/dma-fence.h`](srctree/include/linux/dma-fence.h) 12 13 use crate ::{ 14 alloc::AllocError , 15 bindings, 16 container_of , 17 error::to_result , 18 prelude :: * , 19 types::ForeignOwnable , 20 types::Opaque , // 21 }; 22 23 use core::{ 24 marker::PhantomData , 25 mem::ManuallyDrop , 26 ops::Deref , 27 ptr , 28 ptr::{ 29 drop_in_place , 30 NonNull , // 31 }, // 32 }; 33 34 use kernel::{ 35 str::CString , 36 sync::{ 37 aref::{ 38 ARef , 39 AlwaysRefCounted , // 40 }, 41 atomic::{ 42 Atomic , 43 Relaxed , // 44 }, 45 rcu::rcu_barrier , // 46 }, // 47 }; 48 49 /// VTable for dma_fence backend_ops callbacks.

50 // 51 // Mandatory dma_fence backend_ops are implemented implicitly through 52 // [`FenceContext`]. Additional ones shall get implemented on this trait. 53 pub trait FenceContextOps { 54 /// The generic payload data for [`DriverFence`]s created on this fctx. 55 type FenceDataType: Send + Sync ; 56 } 57 58 /// A dma-fence context. A fence context takes care of associating related fences 59 /// with each other, providing each with raising sequence numbers and a common 60 /// identifier.

61 #[pin_data(PinnedDrop)] 62 pub struct FenceContext <T: FenceContextOps + Send + Sync > { 63 /// The fence context number. 64 nr: u64 , 65 /// The sequence number for the next fence created. 66 seqno: Atomic < u64 >, 67 // The name parameters can be accessed by the dma_fence backend_ops. UAF 68 // errors are prevented by the `call_rcu()` in `drop_driver_fence_data()`. 69 /// The name of the driver this FenceContext's fences belong to.

70 driver_name: CString , 71 /// The name of the timeline this FenceContext's fences belong to. 72 timeline_name: CString , 73 /// The number of all unsignaled fences on this context. 74 // Used to prevent bugs due to forgotten fences. 75 // 76 // The lifetime on `DriverFence`s should typically prevent this from 77 // happening. 78 // 79 // However, we cannot fully guarantee in Rust that `DriverFence`s will not 80 // be forgotten, e.g., through `core::mem::forget()`.

This could circumvent 81 // the lifetime which intends to enforce that all fences disappear before 82 // their context. 83 nr_of_unsignaled_fences: Atomic < usize >, 84 /// The user's data. 85 #[pin] 86 data: T, 87 } 88 89 impl < 'a , T: Send + Sync + FenceContextOps > FenceContext <T> { 90 // This can later be extended as a vtable in case other parties need support 91 // for the more "exotic" callbacks. 92 const OPS: bindings::dma_fence_ops = bindings::dma_fence_ops { 93 get_driver_name: Some ( Self :: get_driver_name ), 94 get_timeline_name: Some ( Self :: get_timeline_name ), 95 enable_signaling: None , 96 signaled: None , 97 // Deprecated.

98 wait: None , 99 // Must never be implemented for these abstractions. 100 release: None , 101 set_deadline: None , 102 }; 103 104 /// Create a new `FenceContext`. 105 pub fn new<E>( 106 initial_seqno: u64 , 107 driver_name: & CStr , 108 timeline_name: & CStr , 109 data: impl PinInit <T, E>, 110 ) -> impl PinInit < Self , Error > 111 where 112 Error : From <E>, 113 { 114 let driver_name = CString :: try_from ( driver_name ); 115 let timeline_name = CString :: try_from ( timeline_name ); 116 try_pin_init! ( Self { 117 // SAFETY: `dma_fence_context_alloc()` merely works on a global 118 // atomic.

Parameter `1` is the number of contexts we want to 119 // allocate. 120 nr: unsafe { bindings::dma_fence_context_alloc( 1 ) }, 121 seqno: Atomic::new(initial_seqno), 122 driver_name: driver_name ? , 123 timeline_name: timeline_name ? , 124 nr_of_unsignaled_fences: Atomic::new( 0 ), 125 data <- data, 126 }) 127 } 128 129 fn next_seqno( & self ) -> u64 { 130 self .seqno. fetch_add ( 1 , Relaxed ) 131 } 132 133 /// Allocate the memory for a [`DriverFence`] and already store `data` inside.

134 /// 135 /// This is needed because many times, creation of a [`DriverFence`] must not 136 /// fail, and allocating might deadlock in some situations. 137 /// 138 /// The `data` you pass here must not perform any operations that are illegal 139 /// in atomic context in its [`Drop`] implementation. 140 pub fn new_fence_allocation( 141 & self , 142 data: T::FenceDataType, 143 ) -> Result < DriverFenceAllocation < '_ , T>> { 144 let fence_data = DriverFenceData { 145 rcu_head: Default:: default (), 146 // `inner` remains uninitialized until a `DriverFence` takes over.

147 inner: Fence { 148 inner: Opaque :: uninit (), 149 }, 150 fctx: self , 151 data , 152 }; 153 154 // In order to support the C dma_fence callbacks, it is necessary for 155 // a `Fence` and a `DriverFence` to live in the same allocation, 156 // because the C backend passes a dma_fence, from which the driver most 157 // likely wants to be able to access its `data` in `DriverFence`. 158 // 159 // Hence, we need the manage the memory manually.

It will be freed by the 160 // C backend automatically once the refcount within `Fence` drops to 0. 161 let data = KBox::new(fence_data, GFP_KERNEL | __GFP_ZERO) ? ; 162 163 Ok ( DriverFenceAllocation { 164 data , 165 ops: & Self :: OPS , 166 }) 167 } 168 169 extern "C" fn get_driver_name(ptr: *mut bindings::dma_fence) -> *const c_char { 170 // SAFETY: The C backend only invokes this callback with `ptr` pointing 171 // to a valid, unsignaled `bindings::dma_fence`.

All fences created in 172 // this module always reside within `Fence` which always resides in a 173 // `DriverFenceData`, thus satisfying the function's safety 174 // requirements. 175 let fctx = unsafe { Self :: from_raw_fence ( ptr ) }; 176 177 fctx .driver_name. as_char_ptr () 178 } 179 180 extern "C" fn get_timeline_name(ptr: *mut bindings::dma_fence) -> *const c_char { 181 // SAFETY: The C backend only invokes this callback with `ptr` pointing 182 // to a valid, unsignaled `bindings::dma_fence`.

All fences created in 183 // this module always reside within `Fence` which always resides in a 184 // `DriverFenceData`, thus satisfying the function's safety 185 // requirements. 186 let fctx = unsafe { Self :: from_raw_fence ( ptr ) }; 187 188 fctx .timeline_name. as_char_ptr () 189 } 190 191 /// Create a [`FenceContext`] from an associated [`bindings::dma_fence`]. 192 /// 193 /// # Safety 194 /// 195 /// `ptr` must be a valid pointer to a [`bindings::dma_fence`] which resides 196 /// within a [`Fence`], which in turn resides in a [`DriverFenceData`].

197 unsafe fn from_raw_fence(ptr: *mut bindings::dma_fence) -> & 'a Self { 198 let opaque_fence = Opaque :: cast_from ( ptr ); 199 200 // SAFETY: Safe due to the function's overall safety requirements. 201 let fence_ptr = unsafe { container_of! (opaque_fence, Fence, inner) }; 202 203 // CAST: `DriverFenceData` is `repr(C)` and a `Fence` is its first member. 204 let fence_data_ptr: *const DriverFenceData < 'a , T> = fence_ptr . cast (); 205 206 // SAFETY: Safe because of the comments directly above.

207 let fence_data = unsafe { &* fence_data_ptr }; 208 209 fence_data .fctx 210 } 211 } 212 213 #[pinned_drop] 214 impl <T: FenceContextOps + Send + Sync > PinnedDrop for FenceContext <T> { 215 fn drop( self : Pin < &mut Self >) { 216 // Fence ops callbacks can be called on unsignaled fences. Since these 217 // callbacks can access the fence context and its data, it needs to be 218 // guaranteed that a context only drops after all associated 219 // `DriverFence`s have been dropped.

This is unlikely to occur, but 220 // would result in silent UAF. Throw a panic to prevent that. 221 // 222 // TODO: 223 // It would be better if the fence context signals all forgotten fences 224 // itself. To do so, it would keep a list of unsignaled fences. That 225 // list's members would have to be pre-allocated (see 226 // `FenceCallback::ne

The rest of this page is on the live site.