More content

2 files changed, 35 insertions, 3 deletions

diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
index d56cb5e1d..53aaa3d7d 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -3,8 +3,6 @@
 So you've got one of the xref:examples.adoc[examples] running, but what now? Let's go through a simple Embassy application for the nRF52 DK to understand it better.
 
 
-== The Cargo.toml
-
 == The main
 
 === Rust Nightly
@@ -73,3 +71,16 @@ What happens when the `blinker` task have been spawned and main returns? Well, t
 . Runs the executor spawning the main task
 
 There is also a way to run the executor without using the macro, in which case you have to create the `Executor` instance yourself.
+
+== The Cargo.toml
+
+The project definition needs to contain the embassy dependencies:
+
+[source,toml]
+----
+include::example$examples/nrf/Cargo.toml[lines="9..11"]
+----
+
+Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).
+
+In this particular case, the nrf52840 chip is selected, and the RTC1 peripheral is used as the time driver.
diff --git a/docs/modules/ROOT/pages/stm32.adoc b/docs/modules/ROOT/pages/stm32.adoc
index 328f69e2a..3d1fbfc8f 100644
--- a/docs/modules/ROOT/pages/stm32.adoc
+++ b/docs/modules/ROOT/pages/stm32.adoc
@@ -1,3 +1,24 @@
 = Embassy STM32 HAL
 
-TODO
+The link:https://github.com/embassy-rs/embassy/tree/master/embassy-stm32[Embassy STM32 HAL] is based on the `stm32-metapac` project.
+
+== The infinite variant problem
+
+STM32 microcontrollers comes in many families and flavors, and supporting all of them is a big undertaking. Embassy has taken advantage of the fact
+that the STM32 peripheral versions are shared across chip families. Instead of re-implementing the SPI
+peripheral for every STM32 chip family, embassy have a single SPI implementation that depends on
+code-generated register types that are identical for STM32 families with the same version of a given peripheral.
+
+=== The metapac
+
+The `stm32-metapac` module uses pre-generated chip and register definitions for STM32 chip families to generate register types. This is done at compile time based on Cargo feataure flags.
+
+The chip and register definitions are located in a separate module, `stm32-data`, which is modified whenever a bug is found in the definitions, or when adding support for new chip families.
+
+=== The HAL
+
+The `embassy-stm32` module contains the HAL implementation for all STM32 families. The implementation uses automatically derived feature flags to support the correct version of a given peripheral for a given chip family.
+
+== Timer driver
+
+The STM32 timer driver operates at 32768 Hz by default.