[−][src]Crate embedded_dma
Traits to aid the correct use of buffers in DMA abstractions.
This library provides the ReadBuffer
and WriteBuffer
unsafe traits to be used as bounds to
buffers types used in DMA operations.
There are some subtleties to the extent of the guarantees provided by these traits, all of these subtleties are properly documented in the safety requirements in this crate. However, as a measure of redundancy, some are listed below:
-
The traits only guarantee a stable location while no
&mut self
methods are called uponSelf
(with the exception ofwrite_buffer
in our case). This is to allow types likeVec
, this restriction doesn't apply toSelf::Target
. -
The location is only guaranteed to be stable for the duration of
Self
, that means thatSelf
doesn't need to be'static
, i.e.&'a [u8]
is valid. This can be a bit subtle for most DMA abstractions, because they almost always require'static
, given the intrinsics ofmem::forget
and the Rust language itself. Those APIs must also bound to'static
and not onlyWriteBuffer
/ReadBuffer
. The reason we don't require'static
in the traits themselves is because it would block implementations that can deal with stack allocated buffers, like APIs that use closures to prevent memory corruption.
The above list is not exhaustive, for a complete set of requirements and guarantees, the documentation of each trait and method should be analyzed.
Traits
ReadBuffer | Trait for buffers that can be given to DMA for reading. |
ReadTarget | Trait for |
Word | Trait for DMA word types used by the blanket DMA buffer impls. |
WriteBuffer | Trait for buffers that can be given to DMA for writing. |
WriteTarget | Trait for |