From e3603d1d0531a4593c4c75863fc77162813cf34f Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Fri, 5 May 2023 18:58:06 +0200 Subject: Rename deprecated to archive --- book/en/archive/by_example/monotonic.md | 64 +++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 book/en/archive/by_example/monotonic.md (limited to 'book/en/archive/by_example') diff --git a/book/en/archive/by_example/monotonic.md b/book/en/archive/by_example/monotonic.md new file mode 100644 index 0000000..0ed4340 --- /dev/null +++ b/book/en/archive/by_example/monotonic.md @@ -0,0 +1,64 @@ +# Monotonic & spawn_{at/after} + +The understanding of time is an important concept in embedded systems, and to be able to run tasks +based on time is essential. The framework provides the static methods +`task::spawn_after(/* duration */)` and `task::spawn_at(/* specific time instant */)`. +`spawn_after` is more commonly used, but in cases where it's needed to have spawns happen +without drift or to a fixed baseline `spawn_at` is available. + +The `#[monotonic]` attribute, applied to a type alias definition, exists to support this. +This type alias must point to a type which implements the [`rtic_monotonic::Monotonic`] trait. +This is generally some timer which handles the timing of the system. +One or more monotonics can coexist in the same system, for example a slow timer that wakes the +system from sleep and another which purpose is for fine grained scheduling while the +system is awake. + +[`rtic_monotonic::Monotonic`]: https://docs.rs/rtic-monotonic + +The attribute has one required parameter and two optional parameters, `binds`, `default` and +`priority` respectively. +The required parameter, `binds = InterruptName`, associates an interrupt vector to the timer's +interrupt, while `default = true` enables a shorthand API when spawning and accessing +time (`monotonics::now()` vs `monotonics::MyMono::now()`), and `priority` sets the priority +of the interrupt vector. + +> The default `priority` is the **maximum priority** of the system. +> If your system has a high priority task with tight scheduling requirements, +> it might be desirable to demote the `monotonic` task to a lower priority +> to reduce scheduling jitter for the high priority task. +> This however might introduce jitter and delays into scheduling via the `monotonic`, +> making it a trade-off. + +The monotonics are initialized in `#[init]` and returned within the `init::Monotonic( ... )` tuple. +This activates the monotonics making it possible to use them. + +See the following example: + +``` rust,noplayground +{{#include ../../../../examples/schedule.rs}} +``` + +``` console +$ cargo run --target thumbv7m-none-eabi --example schedule +{{#include ../../../../ci/expected/schedule.run}} +``` + +A key requirement of a Monotonic is that it must deal gracefully with +hardware timer overruns. + +## Canceling or rescheduling a scheduled task + +Tasks spawned using `task::spawn_after` and `task::spawn_at` returns a `SpawnHandle`, +which allows canceling or rescheduling of the task scheduled to run in the future. + +If `cancel` or `reschedule_at`/`reschedule_after` returns an `Err` it means that the operation was +too late and that the task is already sent for execution. The following example shows this in action: + +``` rust,noplayground +{{#include ../../../../examples/cancel-reschedule.rs}} +``` + +``` console +$ cargo run --target thumbv7m-none-eabi --example cancel-reschedule +{{#include ../../../../ci/expected/cancel-reschedule.run}} +``` -- cgit v1.2.3 From 03b16a3a2d83af9b520fa5b5bad3ba76155f594d Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Fri, 5 May 2023 19:20:57 +0200 Subject: Archive app_task.md --- book/en/archive/by_example/app_task.md | 23 +++++++++++++++++++++++ book/en/src/by-example/app_task.md | 23 ----------------------- 2 files changed, 23 insertions(+), 23 deletions(-) create mode 100644 book/en/archive/by_example/app_task.md delete mode 100644 book/en/src/by-example/app_task.md (limited to 'book/en/archive/by_example') diff --git a/book/en/archive/by_example/app_task.md b/book/en/archive/by_example/app_task.md new file mode 100644 index 0000000..b2731f6 --- /dev/null +++ b/book/en/archive/by_example/app_task.md @@ -0,0 +1,23 @@ + + +# Defining tasks with `#[task]` + +Tasks, defined with `#[task]`, are the main mechanism of getting work done in RTIC. + +Tasks can + +* Be spawned (now or in the future, also by themselves) +* Receive messages (passing messages between tasks) +* Be prioritized, allowing preemptive multitasking +* Optionally bind to a hardware interrupt + +RTIC makes a distinction between “software tasks” and “hardware tasks”. + +*Hardware tasks* are tasks that are bound to a specific interrupt vector in the MCU while software tasks are not. + +This means that if a hardware task is bound to, lets say, a UART RX interrupt, the task will be run every +time that interrupt triggers, usually when a character is received. + +*Software tasks* are explicitly spawned in a task, either immediately or using the Monotonic timer mechanism. + +In the coming pages we will explore both tasks and the different options available. diff --git a/book/en/src/by-example/app_task.md b/book/en/src/by-example/app_task.md deleted file mode 100644 index b2731f6..0000000 --- a/book/en/src/by-example/app_task.md +++ /dev/null @@ -1,23 +0,0 @@ - - -# Defining tasks with `#[task]` - -Tasks, defined with `#[task]`, are the main mechanism of getting work done in RTIC. - -Tasks can - -* Be spawned (now or in the future, also by themselves) -* Receive messages (passing messages between tasks) -* Be prioritized, allowing preemptive multitasking -* Optionally bind to a hardware interrupt - -RTIC makes a distinction between “software tasks” and “hardware tasks”. - -*Hardware tasks* are tasks that are bound to a specific interrupt vector in the MCU while software tasks are not. - -This means that if a hardware task is bound to, lets say, a UART RX interrupt, the task will be run every -time that interrupt triggers, usually when a character is received. - -*Software tasks* are explicitly spawned in a task, either immediately or using the Monotonic timer mechanism. - -In the coming pages we will explore both tasks and the different options available. -- cgit v1.2.3 From 4b3bf59215d682e9473ca66545a1f7c2acbccbfe Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Sat, 20 May 2023 11:24:03 +0200 Subject: Move some more stuff to the archive, update this link --- book/en/archive/by_example/tips/from_ram.md | 45 +++++++++++++++++++++++++++++ book/en/src/SUMMARY.md | 2 -- book/en/src/by-example/tips/from_ram.md | 45 ----------------------------- book/en/src/by-example/tips/indirection.md | 2 +- 4 files changed, 46 insertions(+), 48 deletions(-) create mode 100644 book/en/archive/by_example/tips/from_ram.md delete mode 100644 book/en/src/by-example/tips/from_ram.md (limited to 'book/en/archive/by_example') diff --git a/book/en/archive/by_example/tips/from_ram.md b/book/en/archive/by_example/tips/from_ram.md new file mode 100644 index 0000000..a153139 --- /dev/null +++ b/book/en/archive/by_example/tips/from_ram.md @@ -0,0 +1,45 @@ +# Running tasks from RAM + +The main goal of moving the specification of RTIC applications to attributes in RTIC 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. + +> **IMPORTANT**: In general, the `link_section`, `export_name` and `no_mangle` attributes are powerful but also easy to misuse. Incorrectly using any of these attributes can cause undefined behavior; you should always prefer to use safe, higher level attributes around them like `cortex-m-rt`'s `interrupt` and `exception` attributes. +> +> In the particular case of RAM functions there's no safe abstraction for it in `cortex-m-rt` v0.6.5 but there's an [RFC] for adding a `ramfunc` attribute in a future release. + +[RFC]: https://github.com/rust-embedded/cortex-m-rt/pull/100 + +The example below shows how to place the higher priority task, `bar`, in RAM. + +``` rust,noplayground +{{#include ../../../../../rtic/examples/ramfunc.rs}} +``` + +Running this program produces the expected output. + +``` console +$ cargo run --target thumbv7m-none-eabi --example ramfunc +``` + +``` console +{{#include ../../../../../rtic/ci/expected/ramfunc.run}} +``` + +One can look at the output of `cargo-nm` to confirm that `bar` ended in RAM +(`0x2000_0000`), whereas `foo` ended in Flash (`0x0000_0000`). + +``` console +$ cargo nm --example ramfunc --release | grep ' foo::' +``` + +``` console +{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.foo}} +``` + +``` console +$ cargo nm --example ramfunc --target thumbv7m-none-eabi --release | grep '*bar::' +``` + +``` console +{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.bar}} +``` diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index baeb036..e8c8ee6 100644 --- a/book/en/src/SUMMARY.md +++ b/book/en/src/SUMMARY.md @@ -21,8 +21,6 @@ - [Avoid copies when message passing](./by-example/tips/indirection.md) - [`'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) - [Awesome RTIC examples](./awesome_rtic.md) diff --git a/book/en/src/by-example/tips/from_ram.md b/book/en/src/by-example/tips/from_ram.md deleted file mode 100644 index a153139..0000000 --- a/book/en/src/by-example/tips/from_ram.md +++ /dev/null @@ -1,45 +0,0 @@ -# Running tasks from RAM - -The main goal of moving the specification of RTIC applications to attributes in RTIC 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. - -> **IMPORTANT**: In general, the `link_section`, `export_name` and `no_mangle` attributes are powerful but also easy to misuse. Incorrectly using any of these attributes can cause undefined behavior; you should always prefer to use safe, higher level attributes around them like `cortex-m-rt`'s `interrupt` and `exception` attributes. -> -> In the particular case of RAM functions there's no safe abstraction for it in `cortex-m-rt` v0.6.5 but there's an [RFC] for adding a `ramfunc` attribute in a future release. - -[RFC]: https://github.com/rust-embedded/cortex-m-rt/pull/100 - -The example below shows how to place the higher priority task, `bar`, in RAM. - -``` rust,noplayground -{{#include ../../../../../rtic/examples/ramfunc.rs}} -``` - -Running this program produces the expected output. - -``` console -$ cargo run --target thumbv7m-none-eabi --example ramfunc -``` - -``` console -{{#include ../../../../../rtic/ci/expected/ramfunc.run}} -``` - -One can look at the output of `cargo-nm` to confirm that `bar` ended in RAM -(`0x2000_0000`), whereas `foo` ended in Flash (`0x0000_0000`). - -``` console -$ cargo nm --example ramfunc --release | grep ' foo::' -``` - -``` console -{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.foo}} -``` - -``` console -$ cargo nm --example ramfunc --target thumbv7m-none-eabi --release | grep '*bar::' -``` - -``` console -{{#include ../../../../../rtic/ci/expected/ramfunc.run.grep.bar}} -``` diff --git a/book/en/src/by-example/tips/indirection.md b/book/en/src/by-example/tips/indirection.md index 58b3bde..aa68190 100644 --- a/book/en/src/by-example/tips/indirection.md +++ b/book/en/src/by-example/tips/indirection.md @@ -7,7 +7,7 @@ Indirection can minimize message passing overhead: instead of sending the buffer One can use a global memory allocator to achieve indirection (`alloc::Box`, `alloc::Rc`, etc.), which requires using the nightly channel as of Rust v1.37.0, or one can use a statically allocated memory pool like [`heapless::Pool`]. -[`heapless::Pool`]: https://docs.rs/heapless/0.5.0/heapless/pool/index.html +[`heapless::Pool`]: https://docs.rs/heapless/latest/heapless/pool/index.html As this example of approach goes completely outside of RTIC resource model with shared and local the program would rely on the correctness of the memory allocator, in this case `heapless::pool`. -- cgit v1.2.3