max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move EasyDMA documentation to module level

Browse Source
This commit is contained in:
Til Blechschmidt
2022-03-08 16:42:46 +01:00
parent 7540b44050
commit 63030bf998
4 changed files with 53 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
embassy-nrf/src/spim.rs
View File

@ -31,38 +31,7 @@ pub enum Error {
/// Interface for the SPIM peripheral using EasyDMA to offload the transmission and reception workload.
///
/// ## Data locality requirements
///
/// On nRF chips, EasyDMA requires the buffers to reside in RAM. However, Rust
/// slices will not always do so. Take the following example:
///
/// ```no_run
/// // As we pass a slice to the function whose contents will not ever change,
/// // the compiler writes it into the flash and thus the pointer to it will
/// // reference static memory. Since EasyDMA requires slices to reside in RAM,
/// // this function call will fail.
/// let result = spim.write_from_ram(&[1, 2, 3]);
/// assert_eq!(result, Error::DMABufferNotInDataMemory);
///
/// // The data is still static and located in flash. However, since we are assigning
/// // it to a variable, the compiler will load it into memory. Passing a reference to the
/// // variable will yield a pointer that references dynamic memory, thus making EasyDMA happy.
/// // This function call succeeds.
/// let data = [1, 2, 3];
/// let result = spim.write_from_ram(&data);
/// assert!(result.is_ok());
/// ```
///
/// Each function in this struct has a `_from_ram` variant and one without this suffix.
/// - Functions with the suffix (e.g. [`write_from_ram`](Spim::write_from_ram), [`transfer_from_ram`](Spim::transfer_from_ram)) will return an error if the passed slice does not reside in RAM.
/// - Functions without the suffix (e.g. [`write`](Spim::write), [`transfer`](Spim::transfer)) will check whether the data is in RAM and copy it into memory prior to transmission.
///
/// Since copying incurs a overhead, you are given the option to choose from `_from_ram` variants which will
/// fail and notify you, or the more convenient versions without the suffix which are potentially a little bit
/// more inefficient.
///
/// Note that the [`read`](Spim::read) and [`transfer_in_place`](Spim::transfer_in_place) methods do not have the corresponding `_from_ram` variants as
/// mutable slices always reside in RAM.
/// For more details about EasyDMA, consult the module documentation.
pub struct Spim<'d, T: Instance> {
phantom: PhantomData<&'d mut T>,
}
@ -325,7 +294,7 @@ impl<'d, T: Instance> Spim<'d, T> {
self.blocking_inner(read, write)
}
/// Same as [`blocking_transfer`](Spim::blocking_transfer) but will fail instead of copying data into RAM.
/// Same as [`blocking_transfer`](Spim::blocking_transfer) but will fail instead of copying data into RAM. Consult the module level documentation to learn more.
pub fn blocking_transfer_from_ram(
&mut self,
read: &mut [u8],
@ -346,7 +315,7 @@ impl<'d, T: Instance> Spim<'d, T> {
self.blocking_inner(&mut [], data)
}
/// Same as [`blocking_write`](Spim::blocking_write) but will fail instead of copying data into RAM.
/// Same as [`blocking_write`](Spim::blocking_write) but will fail instead of copying data into RAM. Consult the module level documentation to learn more.
pub fn blocking_write_from_ram(&mut self, data: &[u8]) -> Result<(), Error> {
self.blocking_inner(&mut [], data)
}
@ -362,7 +331,7 @@ impl<'d, T: Instance> Spim<'d, T> {
self.async_inner(read, write).await
}
/// Same as [`transfer`](Spim::transfer) but will fail instead of copying data into RAM.
/// Same as [`transfer`](Spim::transfer) but will fail instead of copying data into RAM. Consult the module level documentation to learn more.
pub async fn transfer_from_ram(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Error> {
self.async_inner_from_ram(read, write).await
}
@ -378,7 +347,7 @@ impl<'d, T: Instance> Spim<'d, T> {
self.async_inner(&mut [], data).await
}
/// Same as [`write`](Spim::write) but will fail instead of copying data into RAM.
/// Same as [`write`](Spim::write) but will fail instead of copying data into RAM. Consult the module level documentation to learn more.
pub async fn write_from_ram(&mut self, data: &[u8]) -> Result<(), Error> {
self.async_inner_from_ram(&mut [], data).await
}