Struct DmaSliceMut 

pub struct DmaSliceMut<'a, T: ImmutableFromIntoBytes> { /* private fields */ }

A mutable buffer that can be safely used for DMA operations that read or write the buffer’s contents.

The buffer can be a slice of any type which implements ImmutableFromIntoBytes, such as u8 or u32.

Use with DMA

Creating a DmaSliceMut over a mutable Rust slice ensures that all prior Rust writes to this slice are observable by any DMA operations initiated through an MMIO write operation, where that MMIO write is performed after constructing the DmaSliceMut. All writes by the DMA operation will be observable by Rust when calling take after the DMA operation is finished.

This struct uses a DmaFence implementation to ensure that all prior writes to slice are exposed to any DMA operations initiated by an MMIO read or write operation after this function returns, and which finish before calling take.

Safety Considerations

Users must eventually call take to retrieve the underlying buffer. The DmaSliceMut must exist for the entire duration of the DMA operation. Users must never drop a DmaSliceMut with a non-'static lifetime, as this could provide access to the underlying buffer without guaranteeing that the DMA operation has finished, and without issuing a DMA memory fence to ensure that writes by the DMA operation are visible to Rust.

take must only be called after the DMA operation has been observed to be complete through an explicit memory or MMIO read. Callers must ensure that the hardware will not perform any further writes to the buffer at the point where take is called.

Callers must further ensure that they start DMA operations through a memory or MMIO write only after constructing the DmaSliceMut, and only in the memory region described by as_mut_ptr and len.

Users are responsible to ensure that, after the DMA operation completes and before calling take, every element in the underlying slice represents a well-initialized and valid instance of its type (with the exception of padding bytes). Concretely, all elements in the slice must meet the requirements of the ImmutableFromIntoBytes trait. See the zerocopy crate for a more in-depth explanation of these requirements.

Implementations

impl<'a, T: ImmutableFromIntoBytes> DmaSliceMut<'a, T>

pub fn new_static( slice: &'static mut [T], fence: impl DmaFence, ) -> DmaSliceMut<'static, T>

Create a DmaSliceMut from a static mutable slice.

pub unsafe fn new(slice: &mut [T], fence: impl DmaFence) -> DmaSliceMut<'_, T>

Create a DmaSliceMut from a mutable slice.

Safety

Callers must ensure to not drop the returned DmaSliceMut. This could provide access to the underlying buffer without guaranteeing that the DMA operation has finished. Users must eventually call take to retrieve the underlying buffer.

pub fn as_mut_ptr(&self) -> *mut T

Returns the pointer to the start of the slice.

pub fn len(&self) -> usize

Returns the length of the slice.

pub unsafe fn take(self, fence: impl DmaFence) -> &'a mut [T]

Recover the original mutable slice.

The caller MUST ensure the hardware DMA will no longer write to the buffer.

Safety

Callers must guarantee no hardware DMA have access to the buffer before calling take(). All DMA operations must have completed before calling this function and the caller must ensure no future operations will occur using the underlying buffer.

Trait Implementations

impl<'a, T: Debug + ImmutableFromIntoBytes> Debug for DmaSliceMut<'a, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.