Struct DmaSubSliceMut 

pub struct DmaSubSliceMut<'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 DmaSubSliceMut over a SubSliceMut ensures that all prior Rust writes to the active range of this slice are observable by any DMA operations initiated through an MMIO write operation, where that MMIO write is performed after constructing the DmaSubSliceMut. 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 DmaSubSliceMut must exist for the entire duration of the DMA operation. Users must never drop a DmaSubSliceMut 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 DmaSubSliceMut, 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> DmaSubSliceMut<'a, T>

pub fn new_static( sub_slice: SubSliceMut<'static, T>, fence: impl DmaFence, ) -> DmaSubSliceMut<'static, T>

Create a DmaSubSliceMut from a SubSliceMut with 'static lifetime.

pub unsafe fn new( sub_slice_mut: SubSliceMut<'_, T>, fence: impl DmaFence, ) -> DmaSubSliceMut<'_, T>

Create a DmaSubSliceMut from a SubSliceMut.

Safety

Callers must ensure to not drop the returned DmaSubSliceMut. 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 first element of the active range of the wrapped SubSliceMut.

pub fn len(&self) -> usize

Returns the length of the active range of the wrapped SubSliceMut.

pub unsafe fn take(self, fence: impl DmaFence) -> SubSliceMut<'a, T>

Recover the original SubSliceMut used to construct this DmaSubSliceMut object.

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 DmaSubSliceMut<'a, T>

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

Formats the value using the given formatter.