More on traits and notes on time

2 files changed, 17 insertions, 6 deletions

diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/modules/ROOT/pages/runtime.adoc
index 39cf2545e..2970bd59e 100644
--- a/docs/modules/ROOT/pages/runtime.adoc
+++ b/docs/modules/ROOT/pages/runtime.adoc
@@ -1,6 +1,8 @@
 = Embassy runtime
 
-The Embassy executor is an async/await executor designed for embedded usage.
+The Embassy runtime is an async/await executor designed for embedded usage along with support functionality for interrupts and timers.
+
+== Features
 
 * No `alloc`, no heap needed. Task are statically allocated.
 * No "fixed capacity" data structures, executor works with 1 or 1000 tasks without needing config/tuning.
@@ -26,3 +28,11 @@ Interrupts are a common way for peripherals to signal completion of some operati
 The peripheral HAL then (4) ensures that interrupt signals are routed to to the peripheral and updating the peripheral state with the results of the operation. The executor is then (5) notified that the task should be polled, which it will do.
 
 image::embassy_irq.png[Interrupt handling]
+
+== Time
+
+Embassy features an internal timer queue enabled by the `time` feature flag. When enabled, Embassy assumes a time `Driver` implementation existing for the platform. Embassy provides time drivers for the nRF, STM32, RPi Pico, WASM and Std platforms.
+
+The timer driver implementations for the embedded platforms support a fixed number of alarms that can be set, which is normally the number of tasks you expect wanting to use the timer at the same time.
+
+NOTE: If you do not require timers in your application, not enabling the `time` feature can save some CPU cycles and reduce power usage.
diff --git a/docs/modules/ROOT/pages/traits.adoc b/docs/modules/ROOT/pages/traits.adoc
index 39e714127..96f3e88bb 100644
--- a/docs/modules/ROOT/pages/traits.adoc
+++ b/docs/modules/ROOT/pages/traits.adoc
@@ -1,8 +1,9 @@
 = Embassy Traits
 
-Embassy provides a set of traits and types specifically designed for `async` usage.
+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`.
-* `embassy::traits::flash`: Flash device trait.
-* `embassy::time`: `Clock` and `Alarm` traits. Std-like `Duration` and `Instant`.
-* More traits for SPI, I2C, UART async HAL coming soon.
+* `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::traits`: Async traits for Flash, SPI, I2C, UART, RNG, GPIO and more.
+* `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`.