Add some docs on RTIC AND embassy

rtic-rs · bors · May 23, 2023 · Apr 22, 2023 · Apr 22, 2023 · Apr 22, 2023
commit 039c2b8bd440018531d79785c63bbfb74f0e686c
diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md
@@ -22,6 +22,7 @@
     - [`'static` super-powers](./by-example/tips/static_lifetimes.md)
     - [Inspecting generated code](./by-example/tips/view_code.md)
 - [RTIC vs. the world](./rtic_vs.md)
+- [RTIC and Embassy](./rtic_and_embassy.md)
 - [Awesome RTIC examples](./awesome_rtic.md)
 
 ---

diff --git a/book/en/src/rtic_and_embassy.md b/book/en/src/rtic_and_embassy.md
@@ -0,0 +1,17 @@
+# RTIC vs. Embassy
+
+## Differences

+Embassy provides both Hardware Abstraction Layers, and an executor/runtime, while RTIC aims to only provide an execution framework. For example, embassy provides `embassy-stm32` (a HAL), and `embassy-executor` (an executor). On the other hand, RTIC provides the framework in the form of [`rtic`], and the user is responsible for providing a PAC and HAL implementation (generally from the [`stm32-rs`] project).
+
+Additionally, RTIC aims to provide exclusive access to resources on as low a level of possible, ideally guarded by some form of hardware protection. This allows for access to hardware while not necessarily requiring locking mechanisms on the software level.
+
+## Mixing use of Embassy and RTIC
+
+Since most Embassy and RTIC libraries are runtime agnostic, many details from one project can be used in the other. For example, using [`rtic-monotonics`] in an `embassy-executor` powered project works, and using [`embassy-sync`] (though [`rtic-sync`] is recommended) in an RTIC project works.
+
+[`stm32-rs`]: https://github.com/stm32-rs
+[`rtic`]: https://docs.rs/rtic/latest/rtic/
+[`rtic-monotonics`]: https://docs.rs/rtic-monotonics/latest/rtic_monotonics/
+[`embassy-sync`]: https://docs.rs/embassy-sync/latest/embassy_sync/
+[`rtic-sync`]: https://docs.rs/rtic-sync/latest/rtic_sync/
diff --git a/book/en/src/rtic_vs.md b/book/en/src/rtic_vs.md
@@ -4,8 +4,6 @@ RTIC aims to provide the lowest level of abstraction needed for developing robus
 
 It provides a minimal set of required mechanisms for safe sharing of mutable resources among interrupts and asynchronously executing tasks. The scheduling primitives leverages on the underlying hardware for unparalleled performance and predictability, in effect RTIC provides in Rust terms a zero-cost abstraction to concurrent real-time programming.
 
-
-
 ## Comparison regarding safety and security
 
 Comparing RTIC to traditional a Real-Time Operating System (RTOS) is hard. Firstly, a traditional RTOS typically comes with no guarantees regarding system safety, even the most hardened kernels like the formally verified [seL4] kernel. Their claims to integrity, confidentiality, and availability regards only the kernel itself (under additional assumptions its configuration and environment). They even state: 
@@ -16,7 +14,7 @@ Comparing RTIC to traditional a Real-Time Operating System (RTOS) is hard. First
 
 [seL4]: https://sel4.systems/
 
-### Security by design 
+## Security by design 
 
 In the world of information security we commonly find:
 
@@ -30,4 +28,4 @@ Thus their claim is correct, security is completely out of hands for the OS, the
 
 RTIC on the other hand holds your back. The declarative system wide model gives you a static set of tasks and resources, with precise control over what data is shared and between which parties. Moreover, Rust as a programming language comes with strong properties regarding integrity (compile time aliasing, mutability and lifetime guarantees, together with ensured data validity).
 
-Using RTIC these properties propagate to the system wide model, without interference of other applications running. The RTIC kernel is internally infallible without any need of dynamically allocated data. 
+Using RTIC these properties propagate to the system wide model, without interference of other applications running. The RTIC kernel is internally infallible without any need of dynamically allocated data.