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 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 book/en/archive/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. -- 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 +++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 book/en/archive/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}} +``` -- cgit v1.2.3