[−][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.
If your API also needs a 'static
bound, prefer the use of StaticReadBuffer and
StaticWriteBuffer. They are a stricter version that requires a 'static
lifetime invariant,
while also allowing end users to unsafely bypass it.
If you are not sure which version of the traits you should be bounding to in your DMA implementations, prefer the "Static" versions, they are sound for a bigger number of techniques that deal with DMA.
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 |
StaticReadBuffer | Trait for buffers that can be given to DMA for reading. This is a more strict version of
ReadBuffer, if you are not sure about which one to use on your safe
API, prefer this one. This trait also allows end users to unsafely bypass the |
StaticWriteBuffer | Trait for buffers that can be given to DMA for writing. This is a more strict version of
WriteBuffer, if you are not sure about which one to use on your safe
API, prefer this one. This trait also allows end users to unsafely bypass the |
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 |