From fc6343b65c79b287ba1884514698e59f87a3d47d Mon Sep 17 00:00:00 2001 From: perlindgren Date: Wed, 1 Feb 2023 22:37:42 +0100 Subject: [PATCH] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks for all suggestions, awesome! Co-authored-by: Henrik Tjäder --- book/en/src/by-example/channel.md | 8 ++++---- book/en/src/preface.md | 12 ++++++------ book/en/src/rtic_vs.md | 4 +++- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/book/en/src/by-example/channel.md b/book/en/src/by-example/channel.md index 1f9510aa22..c020870aac 100644 --- a/book/en/src/by-example/channel.md +++ b/book/en/src/by-example/channel.md @@ -58,9 +58,9 @@ $ cargo run --target thumbv7m-none-eabi --example async-channel --features test- {{#include ../../../../rtic/ci/expected/async-channel.run}} ``` -Also sender endpoint can be awaited. In case there the channel capacity has not been reached, `await` the sender can progress immediately, while in the case the capacity is reached, the sender is blocked until there is free space in the queue. In this way data is never lost. +Also sender endpoint can be awaited. In case the channel capacity has not yet been reached, `await`-ing the sender can progress immediately, while in the case the capacity is reached, the sender is blocked until there is free space in the queue. In this way data is never lost. -In the below example the `CAPACITY` has been reduced to 1, forcing sender tasks to wait until the data in the channel has been received. +In the following example the `CAPACITY` has been reduced to 1, forcing sender tasks to wait until the data in the channel has been received. ``` rust {{#include ../../../../rtic/examples/async-channel-done.rs}} @@ -77,7 +77,7 @@ $ cargo run --target thumbv7m-none-eabi --example async-channel-done --features ## Error handling -In case all senders have been dropped `await` on an empty receiver channel results in an error. This allows to gracefully implement different types of shutdown operations. +In case all senders have been dropped `await`-ing on an empty receiver channel results in an error. This allows to gracefully implement different types of shutdown operations. ``` rust {{#include ../../../../rtic/examples/async-channel-no-sender.rs}} @@ -91,7 +91,7 @@ $ cargo run --target thumbv7m-none-eabi --example async-channel-no-sender --feat {{#include ../../../../rtic/ci/expected/async-channel-no-sender.run}} ``` -Similarly, `await` on a send channel results in an error in case the receiver has been dropped. This allows to gracefully implement application level error handling. +Similarly, `await`-ing on a send channel results in an error in case the receiver has been dropped. This allows to gracefully implement application level error handling. The resulting error returns the data back to the sender, allowing the sender to take appropriate action (e.g., storing the data to later retry sending it). diff --git a/book/en/src/preface.md b/book/en/src/preface.md index c6638abd7c..6b859a28ab 100644 --- a/book/en/src/preface.md +++ b/book/en/src/preface.md @@ -16,7 +16,7 @@ This book contains user level documentation for the Real-Time Interrupt-driven C -This is the documentation of v2.0.x (pre-release) of RTIC 2. +This is the documentation for RTIC v2.x. ## RTIC - The Past, current and Future @@ -27,11 +27,11 @@ The RTIC framework takes the outset from real-time systems research at Luleå Un [Timber]: https://timber-lang.org/ [RTFM-SRP]: https://www.diva-portal.org/smash/get/diva2:1005680/FULLTEXT01.pdf [RTFM-core]: https://ltu.diva-portal.org/smash/get/diva2:1013248/FULLTEXT01.pdf -[AbstractTimer]: https://ltu.diva-portal.org/smash/get/diva2:1013030/FULLTEXT01.pdf +[Abstract Timer]: https://ltu.diva-portal.org/smash/get/diva2:1013030/FULLTEXT01.pdf ## Stack Resource Policy based Scheduling -Stack Resource Policy (SRP) based concurrency and resource management is at heart of the RTIC framework. The [SRP] model itself extends on [Priority Inheritance Protocols], and provides a set of outstanding properties for single core scheduling. To name a few: +[Stack Resource Policy (SRP)][SRP] based concurrency and resource management is at heart of the RTIC framework. The SRP model itself extends on [Priority Inheritance Protocols], and provides a set of outstanding properties for single core scheduling. To name a few: - preemptive deadlock and race-free scheduling - resource efficiency @@ -68,7 +68,7 @@ graph LR ## RTIC the hardware accelerated real-time scheduler -SRP itself is compatible both to dynamic and static priority scheduling. For the implementation of RTIC we leverage on the underlying hardware for accelerated static priority scheduling. +SRP itself is compatible with both dynamic and static priority scheduling. For the implementation of RTIC we leverage on the underlying hardware for accelerated static priority scheduling. In the case of the `ARM Cortex-M` architecture, each interrupt vector entry `v[i]` is associated a function pointer (`v[i].fn`), and a static priority (`v[i].priority`), an enabled- (`v[i].enabled`) and a pending-bit (`v[i].pending`). @@ -84,7 +84,7 @@ The SPR model for single-core static scheduling on the other hand states that a The similarities are striking and it is not by chance/luck/coincidence. The hardware was cleverly designed with real-time scheduling in mind. -In order to map the SRP scheduling onto the hardware we need to have a closer look on the system ceiling (𝜫). Under SRP 𝜫 is computed as the maximum priority ceiling of the currently held resources, and will thus change dynamically during the system operation. +In order to map the SRP scheduling onto the hardware we need to take a closer look at the system ceiling (𝜫). Under SRP 𝜫 is computed as the maximum priority ceiling of the currently held resources, and will thus change dynamically during the system operation. ## Example @@ -99,7 +99,7 @@ The mapping of static priority SRP based scheduling to the Cortex M hardware is ## Example -For the running example, a snapshot of the ARM Cortex M [NVIC] may have the following configuration (after task `A` has been pended for execution.) +For the running example, a snapshot of the ARM Cortex M [Nested Vectored Interrupt Controller (NVIC)][NVIC] may have the following configuration (after task `A` has been pended for execution.) | Index | Fn | Priority | Enabled | Pended | | ----- | --- | -------- | ------- | ------ | diff --git a/book/en/src/rtic_vs.md b/book/en/src/rtic_vs.md index 2f8c8d5856..454b2391ea 100644 --- a/book/en/src/rtic_vs.md +++ b/book/en/src/rtic_vs.md @@ -10,7 +10,9 @@ It provides a minimal set of required mechanisms for safe sharing of mutable res 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: -"An OS kernel, verified or not, does not automatically make a system secure. In fact, any system, no matter how secure, can be used in insecure ways." +"An OS kernel, verified or not, does not automatically make a system secure. In fact, any system, no matter how secure, can be used in insecure ways." - [seL4 FAQ][sel4faq] + +[sel4faq]: https://docs.sel4.systems/projects/sel4/frequently-asked-questions.html [seL4]: https://sel4.systems/