mirror of
https://github.com/embassy-rs/embassy.git
synced 2024-11-29 02:02:28 +00:00
46 lines
3.0 KiB
Markdown
46 lines
3.0 KiB
Markdown
# Embassy nRF HAL
|
|
|
|
HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed.
|
|
|
|
The Embassy nRF HAL targets the Nordic Semiconductor nRF family of hardware. The HAL implements both blocking and async APIs
|
|
for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
|
|
complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
|
|
|
|
NOTE: The Embassy HALs can be used both for non-async and async operations. For async, you can choose which runtime you want to use.
|
|
|
|
## EasyDMA considerations
|
|
|
|
On nRF chips, peripherals can use the so called EasyDMA feature to offload the task of interacting
|
|
with peripherals. It takes care of sending/receiving data over a variety of bus protocols (TWI/I2C, UART, SPI).
|
|
However, EasyDMA requires the buffers used to transmit and receive data to reside in RAM. Unfortunately, Rust
|
|
slices will not always do so. The following example using the SPI peripheral shows a common situation where this might happen:
|
|
|
|
```rust,ignore
|
|
// 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, Err(Error::BufferNotInRAM));
|
|
|
|
// 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 peripheral struct which uses EasyDMA ([`Spim`](spim::Spim), [`Uarte`](uarte::Uarte), [`Twim`](twim::Twim)) has two variants of their mutating functions:
|
|
- Functions with the suffix (e.g. [`write_from_ram`](spim::Spim::write_from_ram), [`transfer_from_ram`](spim::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::Spim::write), [`transfer`](spim::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. Be aware that this overhead is not only in terms of instruction count but also in terms of memory usage
|
|
as the methods without the suffix will be allocating a statically sized buffer (up to 512 bytes for the nRF52840).
|
|
|
|
Note that the methods that read data like [`read`](spim::Spim::read) and [`transfer_in_place`](spim::Spim::transfer_in_place) do not have the corresponding `_from_ram` variants as
|
|
mutable slices always reside in RAM.
|