Struct DriverFence 

pub struct DriverFence<'a, T: Send + Sync + FenceContextOps> { /* private fields */ }

A synchronization primitive mainly for GPU drivers.

The Rust DMA fence implementation has a dualistic design: DriverFences are the producer-side, intended to be always owned by only one party. That party has the monopoly on signaling the fence.

A Fence is the counterpart for consumers. Thus, Fences are always refcounted and can be shared with an arbitrary number of parties, including userspace. A Fence can only be used for actions such as checking the fence’s status or for registering callbacks on it.

Once the associated DriverFence signals, all FenceCallbackRegistrations registered on a Fence will be executed.

A Fence can arbitrarily outlive its DriverFence and the FenceContext. Signaling a DriverFence decouples it from its Fences.

It is crucial that a DriverFence always correctly represents the state of the associated job on the hardware. Especially, it is strictly necessary that the owner ensures that all DriverFences eventually get signaled. As a last resort, a DriverFence will signal itself if it drops unsignaled and print a warning.

This design intends to implement the [bindings::dma_fence_ops] in such a way that the driver-data necessary to implement the callback’s functionality resides in the FenceContext. Thus, a DriverFence contains a reference to the context, which can be accessed in the callbacks. The implementation, therefore, ensures that a DriverFence cannot outlive its FenceContext. Unfortunately, this can be circumvented under certain circumstances in Rust (e.g., usage of core::mem::forget).

In the unlikely case of such violations, a panic is thrown.

Examples

use kernel::{
    dma_buf::{
        DriverFence,
        FenceContext,
        FenceContextOps,
        FenceCallback,
        FenceCallbackRegistration,
    },
    str::CString,
    sync::aref::ARef, //
};
use core::fmt::Display;

struct CallbackData { }

impl FenceCallback for CallbackData {
    fn on_signal(&mut self) {
        pr_info!("DmaFence callback executed.\n");
    }
}

#[pin_data]
struct FenceContextData {}

impl FenceContextData {
    fn new() -> impl PinInit<Self> {
        pin_init!(Self {})
    }
}

impl FenceContextOps for FenceContextData {
    type FenceDataType = FenceData;
}

let fctx_data = FenceContextData::new();


let mut fctx = KBox::pin_init(
    FenceContext::new(0, c"dummy_driver", c"dummy_timeline", fctx_data),
    GFP_KERNEL
)?;

struct FenceData {
    data: CString,
}

let fence_data = FenceData { data: c"dummy_data".try_into()? };

let fence_alloc = fctx.new_fence_allocation(fence_data)?;
let mut fence = fence_alloc.new_fence();

let cb_data = CallbackData { };
let waiting_fence = ARef::from(fence.as_fence());
let cb_reg = FenceCallbackRegistration::new(&waiting_fence, cb_data);
let cb_reg = KBox::pin_init(cb_reg, GFP_KERNEL)?;

// TODO signalling guards
assert_eq!(waiting_fence.is_signaled(), false);
fence.signal(Ok(()));
assert_eq!(waiting_fence.is_signaled(), true);

Ok::<(), Error>(())

Implementations

impl<'a, T: Send + Sync + FenceContextOps> DriverFence<'a, T>

pub fn as_fence(&self) -> &Fence

Return the underlying Fence.

pub fn signal(self, res: Result)

Signal the fence. This will invoke all registered callbacks.

Trait Implementations

impl<'a, T: Send + Sync + FenceContextOps> Deref for DriverFence<'a, T>

type Target = <T as FenceContextOps>::FenceDataType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a, T: Send + Sync + FenceContextOps> Drop for DriverFence<'a, T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: Send + Sync + FenceContextOps> ForeignOwnable for DriverFence<'_, T>

const FOREIGN_ALIGN: usize

The alignment of pointers returned by into_foreign.

type Borrowed<'a> = DriverFenceBorrow<'a, T> where Self: 'a

Type used to immutably borrow a value that is currently foreign-owned.

type BorrowedMut<'a> = DriverFenceBorrow<'a, T> where Self: 'a

Type used to mutably borrow a value that is currently foreign-owned.

fn into_foreign(self) -> *mut c_void

Converts a Rust-owned object to a foreign-owned one.

unsafe fn from_foreign(ptr: *mut c_void) -> Self

Converts a foreign-owned object back to a Rust-owned one.

unsafe fn borrow<'a>(ptr: *mut c_void) -> Self::Borrowed<'a>

where Self: 'a,

Borrows a foreign-owned object immutably.

unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Self::BorrowedMut<'a>

where Self: 'a,

Borrows a foreign-owned object mutably.

unsafe fn try_from_foreign(ptr: *mut c_void) -> Option<Self>

Tries to convert a foreign-owned object back to a Rust-owned one.

impl<'a, T: Send + Sync + FenceContextOps> Send for DriverFence<'a, T>

impl<'a, T: Send + Sync + FenceContextOps> Sync for DriverFence<'a, T>