Merge #176

176:  implement RFCs 147 and 155, fix #141, etc. r=japaric a=japaric

This PR:

- Implements RFC 147: "all functions must be safe"

- Implements RFC 155: "explicit Context parameter"

- Implements the pending breaking change #141: reject assign syntax in `init`
  (which was used to initialize late resources)

- Refactors code generation to make it more readable -- there are no more random
  identifiers in the output -- and align it with the book description of RTFM
  internals (see PR #175).

- Makes the framework hard depend on `core::mem::MaybeUninit` and thus will
  require nightly until that API is stabilized.

- Fixes a ceiling analysis bug where the priority of the system timer was not
  considered in the analysis (TODO backport this into the v0.4.x branch).

- Shrinks the size of all the internal queues by turning `AtomicUsize` indices
  into `AtomicU8`s.

- Removes the integration with `owned_singleton`.

closes #141
closes #147
closes #155

Additionally:

- This changes CI to push v0.5.x docs to
  https://japaric.github.io/rtfm5/book/en/ -- we need to do this because our
  official docs are hosted on https://japaric.github.io/cortex-m-rtfm and we
  need to keep them on v0.4.x until we release v0.5.0

- I propose that we use the master branch to develop the upcoming v0.5.0.

- I have created a branch v0.4.x for backports; new v0.4.x releases will come
  from that branch.

r? @korken89 @texitoi, sorry for doing all the impl work in a single commit --
I know that makes things harder to review for you.

Suggestions for compile-pass and compile-fail tests are welcome


Co-authored-by: Jorge Aparicio <jorge@japaric.io>

1 files changed, 27 insertions, 5 deletions

diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md
index c0bfc56..79b9d71 100644
--- a/book/en/src/by-example/tips.md
+++ b/book/en/src/by-example/tips.md
@@ -24,8 +24,8 @@ of tasks.
 
 You can use conditional compilation (`#[cfg]`) on resources (`static [mut]`
 items) and tasks (`fn` items). The effect of using `#[cfg]` attributes is that
-the resource / task will *not* be injected into the prelude of tasks that use
-them (see `resources`, `spawn` and `schedule`) if the condition doesn't hold.
+the resource / task will *not* be available through the corresponding `Context`
+`struct` if the condition doesn't hold.
 
 The example below logs a message whenever the `foo` task is spawned, but only if
 the program has been compiled using the `dev` profile.
@@ -37,7 +37,7 @@ the program has been compiled using the `dev` profile.
 ## Running tasks from RAM
 
 The main goal of moving the specification of RTFM applications to attributes in
-RTFM v0.4.x was to allow inter-operation with other attributes. For example, the
+RTFM v0.4.0 was to allow inter-operation with other attributes. For example, the
 `link_section` attribute can be applied to tasks to place them in RAM; this can
 improve performance in some cases.
 
@@ -78,8 +78,6 @@ $ cargo nm --example ramfunc --release | grep ' bar::'
 
 ## `binds`
 
-**NOTE**: Requires RTFM ~0.4.2
-
 You can give hardware tasks more task-like names using the `binds` argument: you
 name the function as you wish and specify the name of the interrupt / exception
 in the `binds` argument. Types like `Spawn` will be placed in a module named
@@ -91,3 +89,27 @@ after the function, not the interrupt / exception. Example below:
 ``` console
 $ cargo run --example binds
 {{#include ../../../../ci/expected/binds.run}}```
+
+## Indirection for faster message passing
+
+Message passing always involves copying the payload from the sender into a
+static variable and then from the static variable into the receiver. Thus
+sending a large buffer, like a `[u8; 128]`, as a message involves two expensive
+`memcpy`s. To minimize the message passing overhead one can use indirection:
+instead of sending the buffer by value, one can send an owning pointer into the
+buffer.
+
+One can use a global allocator to achieve indirection (`alloc::Box`,
+`alloc::Rc`, etc.), which requires using the nightly channel as of Rust v1.34.0,
+or one can use a statically allocated memory pool like [`heapless::Pool`].
+
+[`heapless::Pool`]: https://docs.rs/heapless/0.4.3/heapless/pool/index.html
+
+Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
+
+``` rust
+{{#include ../../../../examples/pool.rs}}
+```
+``` console
+$ cargo run --example binds
+{{#include ../../../../ci/expected/pool.run}}```