From e18d6737212fe9a2a606cef210c64bf45ecc925c Mon Sep 17 00:00:00 2001 From: Dario Nieuwenhuis Date: Thu, 11 Jan 2024 21:23:07 +0100 Subject: [PATCH] More readme fixes. --- embassy-nrf/README.md | 16 +++++++++++++--- embassy-rp/README.md | 24 +++++++++++++++++++++--- embassy-stm32/README.md | 19 ++++++++++++++++--- 3 files changed, 50 insertions(+), 9 deletions(-) diff --git a/embassy-nrf/README.md b/embassy-nrf/README.md index 1ead96b2c..50662749d 100644 --- a/embassy-nrf/README.md +++ b/embassy-nrf/README.md @@ -4,7 +4,7 @@ HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so ra 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. +complete operations in low power mode 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. @@ -18,16 +18,26 @@ The `embassy-nrf` HAL supports most variants of the nRF family: * nRF53 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf5340)) * nRF91 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf9160)) -Most peripherals are supported. +Most peripherals are supported. To check what's available, make sure to pick the MCU you're targeting in the top menu in the [documentation](https://docs.embassy.dev/embassy-nrf). + +For MCUs with TrustZone support, both Secure (S) and Non-Secure (NS) modes are supported. Running in Secure mode +allows running Rust code without a SPM or TF-M binary, saving flash space and simplifying development. ## Time driver -If the `time` feature is enabled, the HAL uses the RTC peripheral as a global time driver for [embassy-time](https://crates.io/crates/embassy-time), with a tick rate of 32768 Hz. +If the `time-driver-rtc1` feature is enabled, the HAL uses the RTC peripheral as a global time driver for [embassy-time](https://crates.io/crates/embassy-time), with a tick rate of 32768 Hz. ## Embedded-hal The `embassy-nrf` HAL implements the traits from [embedded-hal](https://crates.io/crates/embedded-hal) (v0.2 and 1.0) and [embedded-hal-async](https://crates.io/crates/embedded-hal-async), as well as [embedded-io](https://crates.io/crates/embedded-io) and [embedded-io-async](https://crates.io/crates/embedded-io-async). +## Interoperability + +This crate can run on any executor. + +Optionally, some features requiring [`embassy-time`](https://crates.io/crates/embassy-time) can be activated with the `time` feature. If you enable it, +you must link an `embassy-time` driver in your project. + ## EasyDMA considerations On nRF chips, peripherals can use the so called EasyDMA feature to offload the task of interacting diff --git a/embassy-rp/README.md b/embassy-rp/README.md index 1d14eca52..8cf7da994 100644 --- a/embassy-rp/README.md +++ b/embassy-rp/README.md @@ -2,8 +2,26 @@ HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. -The Embassy RP HAL targets the Raspberry Pi 2040 family of hardware. The HAL implements both blocking and async APIs +The embassy-rp HAL targets the Raspberry Pi RP2040 microcontroller. 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. +complete operations in low power mode 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. +* [embassy-rp on crates.io](https://crates.io/crates/embassy-rp) +* [Documentation](https://docs.embassy.dev/embassy-rp/) +* [Source](https://github.com/embassy-rs/embassy/tree/main/embassy-rp) +* [Examples](https://github.com/embassy-rs/embassy/tree/main/examples/rp/src/bin) + +## `embassy-time` time driver + +If the `time-driver` feature is enabled, the HAL uses the TIMER peripheral as a global time driver for [embassy-time](https://crates.io/crates/embassy-time), with a tick rate of 1MHz. + +## Embedded-hal + +The `embassy-rp` HAL implements the traits from [embedded-hal](https://crates.io/crates/embedded-hal) (v0.2 and 1.0) and [embedded-hal-async](https://crates.io/crates/embedded-hal-async), as well as [embedded-io](https://crates.io/crates/embedded-io) and [embedded-io-async](https://crates.io/crates/embedded-io-async). + +## Interoperability + +This crate can run on any executor. + +Optionally, some features requiring [`embassy-time`](https://crates.io/crates/embassy-time) can be activated with the `time` feature. If you enable it, +you must link an `embassy-time` driver in your project. diff --git a/embassy-stm32/README.md b/embassy-stm32/README.md index 23c1bf967..e9ae455a4 100644 --- a/embassy-stm32/README.md +++ b/embassy-stm32/README.md @@ -19,7 +19,20 @@ In practice, this works as follows: Be aware that, while embassy-stm32 strives to consistently support all peripherals across all chips, this approach can lead to slightly different APIs and capabilities being available on different families. Check the [documentation](https://docs.embassy.dev/embassy-stm32/) for the specific chip you’re using to confirm exactly what’s available. -## embassy-time Time Driver -If the `time` feature is enabled, embassy-stm32 provides a time driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-*` features, or let embassy pick with `time-driver-any`. +## Embedded-hal -embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes. \ No newline at end of file +The `embassy-stm32` HAL implements the traits from [embedded-hal](https://crates.io/crates/embedded-hal) (v0.2 and 1.0) and [embedded-hal-async](https://crates.io/crates/embedded-hal-async), as well as [embedded-io](https://crates.io/crates/embedded-io) and [embedded-io-async](https://crates.io/crates/embedded-io-async). + +## `embassy-time` time driver +If a `time-driver-*` feature is enabled, embassy-stm32 provides a time driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-tim*` features, or let embassy pick with `time-driver-any`. + +embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes. + +## Interoperability + +This crate can run on any executor. + +Optionally, some features requiring [`embassy-time`](https://crates.io/crates/embassy-time) can be activated with the `time` feature. If you enable it, +you must link an `embassy-time` driver in your project. + +The `low-power` feature integrates specifically with `embassy-executor`, it can't be ued on other executors for now.