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 upon Self (with the exception of write_buffer in our case). This is to allow types like Vec, this restriction doesn't apply to Self::Target.

• The location is only guaranteed to be stable for the duration of Self, that means that Self 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 of mem::forget and the Rust language itself. Those APIs must also bound to 'static and not only WriteBuffer/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 Deref targets used by the blanket DmaReadBuffer impl.
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 'static invariant.
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 'static invariant.
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 DerefMut targets used by the blanket DmaWriteBuffer impl.