Merge branch 'master' of https://github.com/embassy-rs/embassy into rtos-trace

13 files changed, 53 insertions, 43 deletions

diff --git a/docs/antora.yml b/docs/antora.yml
index 807c97c3f..9a00fa820 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -1,4 +1,4 @@
-name: embassy
+name: ROOT
 title: Embassy
 version: dev
 nav:
diff --git a/docs/modules/ROOT/examples/basic/Cargo.toml b/docs/modules/ROOT/examples/basic/Cargo.toml
index 59e1a437a..ae124a871 100644
--- a/docs/modules/ROOT/examples/basic/Cargo.toml
+++ b/docs/modules/ROOT/examples/basic/Cargo.toml
@@ -6,6 +6,7 @@ version = "0.1.0"
 
 [dependencies]
 embassy-executor = { version = "0.1.0", path = "../../../../../embassy-executor", features = ["defmt", "nightly"] }
+embassy-time = { version = "0.1.0", path = "../../../../../embassy-time", features = ["defmt", "nightly"] }
 embassy-nrf = { version = "0.1.0", path = "../../../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote", "nightly"] }
 
 defmt = "0.3"
diff --git a/docs/modules/ROOT/examples/basic/src/main.rs b/docs/modules/ROOT/examples/basic/src/main.rs
index cec39fd91..04170db55 100644
--- a/docs/modules/ROOT/examples/basic/src/main.rs
+++ b/docs/modules/ROOT/examples/basic/src/main.rs
@@ -3,11 +3,10 @@
 #![feature(type_alias_impl_trait)]
 
 use defmt::*;
-use embassy_executor::executor::Spawner;
-use embassy_executor::time::{Duration, Timer};
+use embassy_executor::Spawner;
 use embassy_nrf::gpio::{Level, Output, OutputDrive};
 use embassy_nrf::peripherals::P0_13;
-use embassy_nrf::Peripherals;
+use embassy_time::{Duration, Timer};
 use {defmt_rtt as _, panic_probe as _}; // global logger
 
 #[embassy_executor::task]
@@ -21,7 +20,9 @@ async fn blinker(mut led: Output<'static, P0_13>, interval: Duration) {
 }
 
 #[embassy_executor::main]
-async fn main(spawner: Spawner, p: Peripherals) {
+async fn main(spawner: Spawner) {
+    let p = embassy_nrf::init(Default::default());
+
     let led = Output::new(p.P0_13, Level::Low, OutputDrive::Standard);
     unwrap!(spawner.spawn(blinker(led, Duration::from_millis(300))));
 }
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
index b944a7994..8df632240 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
+++ b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
@@ -2,14 +2,14 @@
 #![no_main]
 #![feature(type_alias_impl_trait)]
 
-use embassy_executor::executor::Spawner;
+use embassy_executor::Spawner;
 use embassy_stm32::exti::ExtiInput;
 use embassy_stm32::gpio::{Input, Level, Output, Pull, Speed};
-use embassy_stm32::Peripherals;
 use {defmt_rtt as _, panic_probe as _};
 
 #[embassy_executor::main]
-async fn main(_s: Spawner, p: Peripherals) {
+async fn main(_spawner: Spawner) {
+    let p = embassy_stm32::init(Default::default());
     let mut led = Output::new(p.PB14, Level::Low, Speed::VeryHigh);
     let mut button = ExtiInput::new(Input::new(p.PC13, Pull::Up), p.EXTI13);
 
diff --git a/docs/modules/ROOT/images/bootloader_flash.png b/docs/modules/ROOT/images/bootloader_flash.png
new file mode 100644
index 000000000..635783b05
--- /dev/null
+++ b/docs/modules/ROOT/images/bootloader_flash.png
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index a45da1958..86f2996f1 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1,10 +1,10 @@
-* xref:runtime.adoc[Runtime]
-* xref:traits.adoc[APIs]
-* xref:hal.adoc[Hardware Abstraction Layer]
-** xref:nrf.adoc[nRF]
-** xref:stm32.adoc[STM32]
-* xref:bootloader.adoc[Bootloader]
 * xref:getting_started.adoc[Getting started]
 ** xref:basic_application.adoc[Basic application]
 ** xref:layer_by_layer.adoc[Layer by Layer]
+* xref:runtime.adoc[Executor]
+* xref:hal.adoc[HAL]
+** xref:nrf.adoc[nRF]
+** xref:stm32.adoc[STM32]
+* xref:bootloader.adoc[Bootloader]
+
 * xref:examples.adoc[Examples]
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
index a8875aa93..4dc4a6359 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -21,7 +21,7 @@ Then, what follows are some declarations on how to deal with panics and faults.
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="5..6"]
+include::example$basic/src/main.rs[lines="11..12"]
 ----
 
 === Task declaration
@@ -30,7 +30,7 @@ After a bit of import declaration, the tasks run by the application should be de
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="18..27"]
+include::example$basic/src/main.rs[lines="13..22"]
 ----
 
 An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking.
@@ -39,32 +39,32 @@ NOTE: Notice that there is no busy waiting going on in this task. It is using th
 
 === Main
 
-The main entry point of an Embassy application is defined using the `#[embassy::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
+The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
 
-The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type holds all peripherals that the application may use. In this case, we want to configure one of the pins as a GPIO output driving the LED:
+The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type comes from the HAL and holds all peripherals that the application may use. In this case, we want to configure one of the pins as a GPIO output driving the LED:
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="28..-1"]
+include::example$basic/src/main.rs[lines="23..-1"]
 ----
 
-`#[embassy::main]` takes an optional `config` paramter specifying a function that returns an instance of HAL's `Config` struct. For example:
+`#[embassy_executor::main]` takes an optional `config` parameter specifying a function that returns an instance of HAL's `Config` struct. For example:
 
 ```rust
 fn embassy_config() -> embassy_nrf::config::Config {
     embassy_nrf::config::Config::default()
 }
 
-#[embassy::main(config = "embassy_config()")]
-async fn main(_spawner: embassy::executor::Spawner, p: embassy_nrf::Peripherals) {
+#[embassy_executor::main(config = "embassy_config()")]
+async fn main(_spawner: Spawner, p: embassy_nrf::Peripherals) {
     // ...
 }
 ```
 
 What happens when the `blinker` task have been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy::main]` macro. The macro does the following:
 
-. Creates an Embassy Executor instance
-. Initializes the microcontroller to get the `Peripherals`
+. Creates an Embassy Executor
+. Initializes the microcontroller HAL to get the `Peripherals`
 . Defines a main task for the entry point
 . Runs the executor spawning the main task
 
diff --git a/docs/modules/ROOT/pages/bootloader.adoc b/docs/modules/ROOT/pages/bootloader.adoc
index 3df2daf51..ae92e9d5d 100644
--- a/docs/modules/ROOT/pages/bootloader.adoc
+++ b/docs/modules/ROOT/pages/bootloader.adoc
@@ -20,7 +20,10 @@ In general, the bootloader works on any platform that implements the `embedded-s
 
 == Design
 
-The bootloader divides the storage into 4 main partitions, configured by a linker script:
+image::bootloader_flash.png[Bootloader flash layout]
+
+The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader
+instance or via linker scripts:
 
 * BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash.
 * ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. This partition is only written to by the bootloader.
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index 23102b3b5..f3492a3d0 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -46,15 +46,13 @@ You can run an example by opening a terminal and entering the following commands
 [source, bash]
 ----
 cd examples/nrf
-DEFMT_LOG=info cargo run --bin blinky --release
+cargo run --bin blinky --release
 ----
 
-IMPORTANT: The DEFMT_LOG environment variable controls the example log verbosity. If you do not specify it, you will not see anything logged to the console.
-
 == Whats next?
 
 Congratulations, you have your first Embassy application running! Here are some alternatives on where to go from here:
 
-* Read more about the xref:runtime.adoc[runtime].
+* Read more about the xref:runtime.adoc[executor].
 * Read more about the xref:hal.adoc[HAL].
 * Start xref:basic_application.adoc[writing your application].
diff --git a/docs/modules/ROOT/pages/hal.adoc b/docs/modules/ROOT/pages/hal.adoc
index 0b15e2fce..de4ab33be 100644
--- a/docs/modules/ROOT/pages/hal.adoc
+++ b/docs/modules/ROOT/pages/hal.adoc
@@ -1,9 +1,10 @@
 = Hardware Abstraction Layer (HAL)
 
-Embassy provides HAL's for several microcontroller families:
+Embassy provides HALs for several microcontroller families:
 
 * `embassy-nrf` for the nRF microcontrollers from Nordic Semiconductor
 * `embassy-stm32` for STM32 microcontrollers from ST Microelectronics
 * `embassy-rp` for the Raspberry Pi RP2040 microcontrollers
 
-These HALs implement async/await functionality for most peripherals while also implementing the async traits in Embassy.
+These HALs implement async/await functionality for most peripherals while also implementing the
+async traits in `embedded-hal-async`. You can also use these HALs with another executor.
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 9a14e465d..0a17c6739 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -15,6 +15,20 @@ In Rust, non-blocking operations can be implemented using async-await. Async-awa
 
 == What is Embassy?
 
-Embassy is an executor and a Hardware Access Layer (HAL). The executor is a scheduler that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API.
+The Embassy project consists of several crates that you can use together or independently:
 
-Embassy may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+* **Executor** - The link:https://docs.embassy.dev/embassy-executor/[embassy-executor] is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API. The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+
+* **Hardware Abstraction Layers** - HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.
+** link:https://docs.embassy.dev/embassy-stm32/[embassy-stm32], for all STM32 microcontroller families.
+** link:https://docs.embassy.dev/embassy-nrf/[embassy-nrf], for the Nordic Semiconductor nRF52, nRF53, nRF91 series.
+
+* **Networking** - The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently.
+
+* **Bluetooth** - The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
+
+* **LoRa** - link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on STM32WL wireless microcontrollers and Semtech SX127x transceivers.
+
+* **USB** - link:https://docs.embassy.dev/embassy-usb/[embassy-usb] implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own.
+
+* **Bootloader and DFU** - link:https://github.com/embassy-rs/embassy/tree/master/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.
diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/modules/ROOT/pages/runtime.adoc
index 0adaa21a0..a7d6a8d0c 100644
--- a/docs/modules/ROOT/pages/runtime.adoc
+++ b/docs/modules/ROOT/pages/runtime.adoc
@@ -1,6 +1,6 @@
-= Embassy runtime
+= Embassy executor
 
-The Embassy runtime is an async/await executor designed for embedded usage along with support functionality for interrupts and timers.
+The Embassy executor is an async/await executor designed for embedded usage along with support functionality for interrupts and timers.
 
 == Features
 
diff --git a/docs/modules/ROOT/pages/traits.adoc b/docs/modules/ROOT/pages/traits.adoc
deleted file mode 100644
index 38b8f2862..000000000
--- a/docs/modules/ROOT/pages/traits.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= Embassy Traits
-
-Embassy provides a set of traits and types specifically designed for `async` usage. Many of these futures will be upstreamed to the `embedded-hal` crate at some point in the future, probably when the required GAT (Generic Associated Types) feature is stabilized in Rust.
-
-* `embassy::io`: `AsyncBufRead`, `AsyncWrite`. Traits for byte-stream IO, essentially `no_std` compatible versions of `futures::io`. The primary reason for re-defining these traits is that the `futures::io` variant requires `std::io::Error`, which does not work in the `no_std` environment.
-* `embassy::time`: Time `Driver` trait that is implemented for different platforms. Time in Embassy is represented using the `Duration` and `Instant` types.
-
-These traits are implemented by the platform-specific crates, such as `embassy-nrf` or `embassy-stm32`.