diff options
Diffstat (limited to 'book/en/src/by-example')
| -rw-r--r-- | book/en/src/by-example/app.md | 14 | ||||
| -rw-r--r-- | book/en/src/by-example/new.md | 12 | ||||
| -rw-r--r-- | book/en/src/by-example/resources.md | 6 | ||||
| -rw-r--r-- | book/en/src/by-example/tasks.md | 8 | ||||
| -rw-r--r-- | book/en/src/by-example/timer-queue.md | 8 | ||||
| -rw-r--r-- | book/en/src/by-example/tips.md | 32 | ||||
| -rw-r--r-- | book/en/src/by-example/types-send-sync.md | 4 |
7 files changed, 42 insertions, 42 deletions
diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index 2450c59..bff516d 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -1,26 +1,26 @@ # The `app` attribute -This is the smallest possible RTFM application: +This is the smallest possible RTIC application: ``` rust {{#include ../../../../examples/smallest.rs}} ``` -All RTFM applications use the [`app`] attribute (`#[app(..)]`). This attribute +All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute must be applied to a `const` item that contains items. 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 point so it's not required to use the [`cortex_m_rt::entry`] attribute. -[`app`]: ../../../api/cortex_m_rtfm_macros/attr.app.html +[`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html [`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 -> RTFM work on stable we use the `const` item instead. When more parts of macros +> 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]`). @@ -39,7 +39,7 @@ to Cortex-M and, optionally, device specific peripherals through the `core` and `static mut` variables declared at the beginning of `init` will be transformed into `&'static mut` references that are safe to access. -[`rtfm::Peripherals`]: ../../api/rtfm/struct.Peripherals.html +[`rtic::Peripherals`]: ../../api/rtic/struct.Peripherals.html The example below shows the types of the `core` and `device` fields and showcases safe access to a `static mut` variable. The `device` field is only @@ -106,9 +106,9 @@ mut` variables are safe to use within a hardware task. $ cargo run --example hardware {{#include ../../../../ci/expected/hardware.run}}``` -So far all the RTFM applications we have seen look no different than the +So far all the RTIC applications we have seen look no different than the applications one can write using only the `cortex-m-rt` crate. From this point -we start introducing features unique to RTFM. +we start introducing features unique to RTIC. ## Priorities diff --git a/book/en/src/by-example/new.md b/book/en/src/by-example/new.md index e4f7fd9..c0482b0 100644 --- a/book/en/src/by-example/new.md +++ b/book/en/src/by-example/new.md @@ -1,6 +1,6 @@ # Starting a new project -Now that you have learned about the main features of the RTFM framework you can +Now that you have learned about the main features of the RTIC framework you can try it out on your hardware by following these instructions. 1. Instantiate the [`cortex-m-quickstart`] template. @@ -36,19 +36,19 @@ $ cargo add lm3s6965 --vers 0.1.3 $ rm memory.x build.rs ``` -3. Add the `cortex-m-rtfm` crate as a dependency. +3. Add the `cortex-m-rtic` crate as a dependency. ``` console -$ cargo add cortex-m-rtfm --allow-prerelease +$ cargo add cortex-m-rtic --allow-prerelease ``` -4. Write your RTFM application. +4. Write your RTIC application. -Here I'll use the `init` example from the `cortex-m-rtfm` crate. +Here I'll use the `init` example from the `cortex-m-rtic` crate. ``` console $ curl \ - -L https://github.com/rtfm-rs/cortex-m-rtfm/raw/v0.5.0/examples/init.rs \ + -L https://github.com/rtic-rs/cortex-m-rtic/raw/v0.5.0/examples/init.rs \ > src/main.rs ``` diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md index db7630e..b9e92d1 100644 --- a/book/en/src/by-example/resources.md +++ b/book/en/src/by-example/resources.md @@ -46,8 +46,8 @@ instead of a reference. This resource proxy is a structure that implements the [`Mutex`] trait. The only method on this trait, [`lock`], runs its closure argument in a critical section. -[`Mutex`]: ../../../api/rtfm/trait.Mutex.html -[`lock`]: ../../../api/rtfm/trait.Mutex.html#method.lock +[`Mutex`]: ../../../api/rtic/trait.Mutex.html +[`lock`]: ../../../api/rtic/trait.Mutex.html#method.lock The critical section created by the `lock` API is based on dynamic priorities: it temporarily raises the dynamic priority of the context to a *ceiling* @@ -113,7 +113,7 @@ shared reference (`&-`) to the resource, limiting the operations it can perform on it, but where a shared reference is enough this approach reduces the number of required locks. -Note that in this release of RTFM it is not possible to request both exclusive +Note that in this release of RTIC it is not possible to request both exclusive access (`&mut-`) and shared access (`&-`) to the *same* resource from different tasks. Attempting to do so will result in a compile error. diff --git a/book/en/src/by-example/tasks.md b/book/en/src/by-example/tasks.md index 1c9302f..5978ca8 100644 --- a/book/en/src/by-example/tasks.md +++ b/book/en/src/by-example/tasks.md @@ -1,11 +1,11 @@ # Software tasks In addition to hardware tasks, which are invoked by the hardware in response to -hardware events, RTFM also supports *software* tasks which can be spawned by the +hardware events, RTIC also supports *software* tasks which can be spawned by the application from any execution context. Software tasks can also be assigned priorities and, under the hood, are -dispatched from interrupt handlers. RTFM requires that free interrupts are +dispatched from interrupt handlers. RTIC requires that free interrupts are declared in an `extern` block when using software tasks; some of these free interrupts will be used to dispatch the software tasks. An advantage of software tasks over hardware tasks is that many tasks can be mapped to a single interrupt @@ -45,7 +45,7 @@ $ cargo run --example message ## Capacity -RTFM does *not* perform any form of heap-based memory allocation. The memory +RTIC does *not* perform any form of heap-based memory allocation. The memory required to store messages is statically reserved. By default the framework minimizes the memory footprint of the application so each task has a message "capacity" of 1: meaning that at most one message can be posted to the task @@ -91,7 +91,7 @@ its message buffer will never be emptied. This situation is depicted in the following snippet: ``` rust -#[rtfm::app(..)] +#[rtic::app(..)] const APP: () = { #[init(spawn = [foo, bar])] fn init(cx: init::Context) { diff --git a/book/en/src/by-example/timer-queue.md b/book/en/src/by-example/timer-queue.md index 94d2281..482aebc 100644 --- a/book/en/src/by-example/timer-queue.md +++ b/book/en/src/by-example/timer-queue.md @@ -20,11 +20,11 @@ type (see [`core::time::Duration`]) and this `Duration` type must implement the integer. If the result of the conversion doesn't fit in a 32-bit number then the operation must return an error, any error type. -[`Monotonic`]: ../../../api/rtfm/trait.Monotonic.html +[`Monotonic`]: ../../../api/rtic/trait.Monotonic.html [std-instant]: https://doc.rust-lang.org/std/time/struct.Instant.html [`core::time::Duration`]: https://doc.rust-lang.org/core/time/struct.Duration.html -For ARMv7+ targets the `rtfm` crate provides a `Monotonic` implementation based +For ARMv7+ targets the `rtic` crate provides a `Monotonic` implementation based on the built-in CYCle CouNTer (CYCCNT). Note that this is a 32-bit timer clocked at the frequency of the CPU and as such it is not suitable for tracking time spans in the order of seconds. @@ -36,7 +36,7 @@ executed must be passed as the first argument of the `schedule` invocation. Additionally, the chosen `monotonic` timer must be configured and initialized during the `#[init]` phase. Note that this is *also* the case if you choose to -use the `CYCCNT` provided by the `cortex-m-rtfm` crate. +use the `CYCCNT` provided by the `cortex-m-rtic` crate. The example below schedules two tasks from `init`: `foo` and `bar`. `foo` is scheduled to run 8 million clock cycles in the future. Next, `bar` is scheduled @@ -61,7 +61,7 @@ console: When the `schedule` API is being used the runtime internally uses the `SysTick` interrupt handler and the system timer peripheral (`SYST`) so neither can be used by the application. This is accomplished by changing the type of -`init::Context.core` from `cortex_m::Peripherals` to `rtfm::Peripherals`. The +`init::Context.core` from `cortex_m::Peripherals` to `rtic::Peripherals`. The latter structure contains all the fields of the former minus the `SYST` one. ## Periodic tasks diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index b923ed0..ce9bba8 100644 --- a/book/en/src/by-example/tips.md +++ b/book/en/src/by-example/tips.md @@ -8,15 +8,15 @@ appear as *different* types in different contexts one cannot refactor a common operation that uses resources into a plain function; however, such refactor is possible using *generics*. -All resource proxies implement the `rtfm::Mutex` trait. On the other hand, +All resource proxies implement the `rtic::Mutex` trait. On the other hand, unique references (`&mut-`) do *not* implement this trait (due to limitations in -the trait system) but one can wrap these references in the [`rtfm::Exclusive`] +the trait system) but one can wrap these references in the [`rtic::Exclusive`] newtype which does implement the `Mutex` trait. With the help of this newtype one can write a generic function that operates on generic resources and call it from different tasks to perform some operation on the same set of resources. Here's one such example: -[`rtfm::Exclusive`]: ../../../api/rtfm/struct.Exclusive.html +[`rtic::Exclusive`]: ../../../api/rtic/struct.Exclusive.html ``` rust {{#include ../../../../examples/generics.rs}} @@ -51,8 +51,8 @@ $ cargo run --example cfg ## Running tasks from RAM -The main goal of moving the specification of RTFM applications to attributes in -RTFM v0.4.0 was to allow inter-operation with other attributes. For example, the +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. @@ -119,22 +119,22 @@ $ cargo run --example pool ## Inspecting the expanded code -`#[rtfm::app]` is a procedural macro that produces support code. If for some +`#[rtic::app]` is a procedural macro that produces support code. If for some reason you need to inspect the code generated by this macro you have two options: -You can inspect the file `rtfm-expansion.rs` inside the `target` directory. This -file contains the expansion of the `#[rtfm::app]` item (not your whole program!) -of the *last built* (via `cargo build` or `cargo check`) RTFM application. The +You can inspect the file `rtic-expansion.rs` inside the `target` directory. This +file contains the expansion of the `#[rtic::app]` item (not your whole program!) +of the *last built* (via `cargo build` or `cargo check`) RTIC application. The expanded code is not pretty printed by default so you'll want to run `rustfmt` over it before you read it. ``` console $ cargo build --example foo -$ rustfmt target/rtfm-expansion.rs +$ rustfmt target/rtic-expansion.rs -$ tail target/rtfm-expansion.rs +$ tail target/rtic-expansion.rs ``` ``` rust @@ -144,19 +144,19 @@ const APP: () = { use lm3s6965 as _; #[no_mangle] unsafe extern "C" fn main() -> ! { - rtfm::export::interrupt::disable(); - let mut core: rtfm::export::Peripherals = core::mem::transmute(()); + rtic::export::interrupt::disable(); + let mut core: rtic::export::Peripherals = core::mem::transmute(()); core.SCB.scr.modify(|r| r | 1 << 1); - rtfm::export::interrupt::enable(); + rtic::export::interrupt::enable(); loop { - rtfm::export::wfi() + rtic::export::wfi() } } }; ``` Or, you can use the [`cargo-expand`] subcommand. This subcommand will expand -*all* the macros, including the `#[rtfm::app]` attribute, and modules in your +*all* the macros, including the `#[rtic::app]` attribute, and modules in your crate and print the output to the console. [`cargo-expand`]: https://crates.io/crates/cargo-expand diff --git a/book/en/src/by-example/types-send-sync.md b/book/en/src/by-example/types-send-sync.md index fd344e3..41cd9ba 100644 --- a/book/en/src/by-example/types-send-sync.md +++ b/book/en/src/by-example/types-send-sync.md @@ -18,7 +18,7 @@ The example below shows the different types generates by the `app` attribute. ## `Send` [`Send`] is a marker trait for "types that can be transferred across thread -boundaries", according to its definition in `core`. In the context of RTFM the +boundaries", according to its definition in `core`. In the context of RTIC the `Send` trait is only required where it's possible to transfer a value between tasks that run at *different* priorities. This occurs in a few places: in message passing, in shared resources and in the initialization of late @@ -57,7 +57,7 @@ the `Send` trait. Similarly, [`Sync`] is a marker trait for "types for which it is safe to share references between threads", according to its definition in `core`. In the -context of RTFM the `Sync` trait is only required where it's possible for two, +context of RTIC the `Sync` trait is only required where it's possible for two, or more, tasks that run at different priorities and may get a shared reference (`&-`) to a resource. This only occurs with shared access (`&-`) resources. |