From 163edd7579222560caf6598cf8071f4201c277c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Thu, 1 Oct 2020 16:59:27 +0000 Subject: Start updating the book --- book/en/src/by-example/app.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) (limited to 'book/en/src/by-example') diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index 9a073ac..4262391 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -7,7 +7,7 @@ This is the smallest possible RTIC application: ``` All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute -must be applied to a `const` item that contains items. The `app` attribute has +must be applied to a `mod`-item. The `app` attribute has a mandatory `device` argument that takes a *path* as a value. This path must point to a *peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or newer. The `app` attribute will expand into a suitable entry @@ -17,16 +17,9 @@ point so it's not required to use the [`cortex_m_rt::entry`] attribute. [`svd2rust`]: https://crates.io/crates/svd2rust [`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html -> **ASIDE**: Some of you may be wondering why we are using a `const` item as a -> module and not a proper `mod` item. The reason is that using attributes on -> modules requires a feature gate, which requires a nightly toolchain. To make -> RTIC work on stable we use the `const` item instead. When more parts of macros -> 1.2 are stabilized we'll move from a `const` item to a `mod` item and -> eventually to a crate level attribute (`#![app]`). - ## `init` -Within the pseudo-module the `app` attribute expects to find an initialization +Within the `app` module the attribute expects to find an initialization function marked with the `init` attribute. This function must have signature `fn(init::Context) [-> init::LateResources]` (the return type is not always required). @@ -60,7 +53,7 @@ $ cargo run --example init ## `idle` A function marked with the `idle` attribute can optionally appear in the -pseudo-module. This function is used as the special *idle task* and must have +module. This function is used as the special *idle task* and must have signature `fn(idle::Context) - > !`. When present, the runtime will execute the `idle` task after `init`. Unlike -- cgit v1.2.3 From 9ca10b0d8c735a06a3a0a3623a7fc5d09b5e948c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Fri, 2 Oct 2020 09:33:28 +0000 Subject: Add migration to 0.6 along with updated documentation --- book/en/src/by-example/resources.md | 4 ++-- book/en/src/by-example/tasks.md | 4 ++-- book/en/src/by-example/tips.md | 4 ++-- book/en/src/by-example/types-send-sync.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) (limited to 'book/en/src/by-example') diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index b9e92d1..d63d135 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -4,11 +4,11 @@ The framework provides an abstraction to share data between any of the contexts we saw in the previous section (task handlers, `init` and `idle`): resources. Resources are data visible only to functions declared within the `#[app]` -pseudo-module. The framework gives the user complete control over which context +module. The framework gives the user complete control over which context can access which resource. All resources are declared as a single `struct` within the `#[app]` -pseudo-module. Each field in the structure corresponds to a different resource. +module. Each field in the structure corresponds to a different resource. Resources can optionally be given an initial value using the `#[init]` attribute. Resources that are not given an initial value are referred to as *late* resources and are covered in more detail in a follow-up section in this diff --git a/book/en/src/by-example/tasks.md b/book/en/src/by-example/tasks.md index d0b5acb..9fefd02 100644 --- a/book/en/src/by-example/tasks.md +++ b/book/en/src/by-example/tasks.md @@ -92,7 +92,7 @@ following snippet: ``` rust #[rtic::app(..)] -const APP: () = { +mod app { #[init(spawn = [foo, bar])] fn init(cx: init::Context) { cx.spawn.foo().unwrap(); @@ -113,5 +113,5 @@ const APP: () = { fn bar(cx: bar::Context, payload: i32) { // .. } -}; +} ``` diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index b191b9d..0b6555e 100644 --- a/book/en/src/by-example/tips.md +++ b/book/en/src/by-example/tips.md @@ -139,7 +139,7 @@ $ tail target/rtic-expansion.rs ``` rust #[doc = r" Implementation details"] -const APP: () = { +mod app { #[doc = r" Always include the device crate which contains the vector table"] use lm3s6965 as _; #[no_mangle] @@ -152,7 +152,7 @@ const APP: () = { rtic::export::wfi() } } -}; +} ``` Or, you can use the [`cargo-expand`] sub-command. This sub-command will expand diff --git a/book/en/src/by-example/types-send-sync.md b/book/en/src/by-example/types-send-sync.md index 41cd9ba..9cdb889 100644 --- a/book/en/src/by-example/types-send-sync.md +++ b/book/en/src/by-example/types-send-sync.md @@ -1,6 +1,6 @@ # Types, Send and Sync -Every function within the `APP` pseudo-module has a `Context` structure as its +Every function within the `app` module has a `Context` structure as its first parameter. All the fields of these structures have predictable, non-anonymous types so you can write plain functions that take them as arguments. -- cgit v1.2.3 From e6bc673621093c72f932cc38043c9fa951745450 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Fri, 2 Oct 2020 09:42:50 +0000 Subject: Clarify the need for resources-attribute --- book/en/src/by-example/resources.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'book/en/src/by-example') diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index d63d135..62efdc6 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -9,6 +9,8 @@ can access which resource. All resources are declared as a single `struct` within the `#[app]` module. Each field in the structure corresponds to a different resource. +The `struct` must be annotated with the following attribute: `#[resources]`. + Resources can optionally be given an initial value using the `#[init]` attribute. Resources that are not given an initial value are referred to as *late* resources and are covered in more detail in a follow-up section in this -- cgit v1.2.3 From f0f982facadab2da5d8cdaf214829a9e19f4249e Mon Sep 17 00:00:00 2001 From: Emil Fresk Date: Sat, 3 Oct 2020 15:30:15 +0200 Subject: Updated documentation to include the critical section token in init --- book/en/src/by-example/app.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'book/en/src/by-example') diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index 344cefc..23bff68 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -33,15 +33,16 @@ required). This initialization function will be the first part of the application to run. The `init` function will run *with interrupts disabled* and has exclusive access -to Cortex-M and, optionally, device specific peripherals through the `core` and -`device` fields of `init::Context`. +to Cortex-M where the `bare_metal::CriticalSection` token is available as `cs`. +And optionally, device specific peripherals through the `core` and `device` fields +of `init::Context`. `static mut` variables declared at the beginning of `init` will be transformed into `&'static mut` references that are safe to access. [`rtic::Peripherals`]: ../../api/rtic/struct.Peripherals.html -The example below shows the types of the `core` and `device` fields and +The example below shows the types of the `core`, `device` and `cs` fields, and showcases safe access to a `static mut` variable. The `device` field is only available when the `peripherals` argument is set to `true` (it defaults to `false`). -- cgit v1.2.3