convert from antora to asciidoctor

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/pages/stm32.adoc b/docs/pages/stm32.adoc
new file mode 100644
index 000000000..7bfc0592b
--- /dev/null
+++ b/docs/pages/stm32.adoc
@@ -0,0 +1,24 @@
+= Embassy STM32 HAL
+
+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 come 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 has 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 feature 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.