From 06c1e2f9b47b5bc9de049e1e1edfed27d8dd2c58 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Sun, 16 Dec 2018 19:34:16 +0100 Subject: note that the timer queue is not supported on ARMv6-M --- book/src/preface.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'book/src') diff --git a/book/src/preface.md b/book/src/preface.md index c041ef5..fe4ad62 100644 --- a/book/src/preface.md +++ b/book/src/preface.md @@ -7,6 +7,6 @@ This book contains user level documentation for the Real Time For the Masses (RTFM) framework. The API reference can be found [here](../api/rtfm/index.html). -{{#include ../../README.md:5:53}} +{{#include ../../README.md:5:55}} -{{#include ../../README.md:59:}} +{{#include ../../README.md:61:}} -- cgit v1.2.3 From 34e74f4bb36b0866be94c9bfdb41c11270b448a7 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Sun, 16 Dec 2018 20:56:57 +0100 Subject: book: add an example of conditional compilation of resources and tasks --- book/src/by-example/tips.md | 14 ++++++++++++ ci/script.sh | 2 ++ examples/cfg.rs | 54 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 examples/cfg.rs (limited to 'book/src') diff --git a/book/src/by-example/tips.md b/book/src/by-example/tips.md index c163328..5057c80 100644 --- a/book/src/by-example/tips.md +++ b/book/src/by-example/tips.md @@ -20,6 +20,20 @@ rewrite code. If you consistently use `lock`s to access the data behind shared resources then your code will continue to compile when you change the priority of tasks. +## Conditional compilation + +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 example below logs a message whenever the `foo` task is spawned, but only if +the program has been compiled using the `dev` profile. + +``` rust +{{#include ../../../examples/cfg.rs}} +``` + ## Running tasks from RAM The main goal of moving the specification of RTFM applications to attributes in diff --git a/ci/script.sh b/ci/script.sh index 0244c58..27229a5 100644 --- a/ci/script.sh +++ b/ci/script.sh @@ -68,6 +68,8 @@ main() { generics ramfunc + + cfg ) for ex in ${exs[@]}; do diff --git a/examples/cfg.rs b/examples/cfg.rs new file mode 100644 index 0000000..3f4ca90 --- /dev/null +++ b/examples/cfg.rs @@ -0,0 +1,54 @@ +//! examples/cfg.rs + +#![deny(unsafe_code)] +#![deny(warnings)] +#![no_main] +#![no_std] + +extern crate panic_semihosting; + +#[cfg(debug_assertions)] +use cortex_m_semihosting::hprintln; +use rtfm::app; + +#[app(device = lm3s6965)] +const APP: () = { + #[cfg(debug_assertions)] // <- `true` when using the `dev` profile + static mut COUNT: u32 = 0; + + #[init] + fn init() { + // .. + } + + #[task(priority = 3, resources = [COUNT], spawn = [log])] + fn foo() { + #[cfg(debug_assertions)] + { + *resources.COUNT += 1; + + spawn.log(*resources.COUNT).ok(); + } + + // this wouldn't compile in `release` mode + // *resources.COUNT += 1; + + // .. + } + + #[cfg(debug_assertions)] + #[task] + fn log(n: u32) { + hprintln!( + "foo has been called {} time{}", + n, + if n == 1 { "" } else { "s" } + ) + .ok(); + } + + extern "C" { + fn UART0(); + fn UART1(); + } +}; -- cgit v1.2.3 From d98f6c9a61267abe00a827ac6c668b50b2bac714 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Sun, 16 Dec 2018 21:19:19 +0100 Subject: v0.4.0 --- Cargo.toml | 4 ++-- README.md | 9 --------- book/src/by-example/app.md | 6 +++--- book/src/by-example/new.md | 10 +++++----- book/src/preface.md | 4 ++-- macros/Cargo.toml | 2 +- 6 files changed, 13 insertions(+), 22 deletions(-) (limited to 'book/src') diff --git a/Cargo.toml b/Cargo.toml index 6b67c2a..d96923b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -12,7 +12,7 @@ license = "MIT OR Apache-2.0" name = "cortex-m-rtfm" readme = "README.md" repository = "https://github.com/japaric/cortex-m-rtfm" -version = "0.4.0-beta.3" +version = "0.4.0" [lib] name = "rtfm" @@ -36,7 +36,7 @@ required-features = ["timer-queue"] [dependencies] cortex-m = "0.5.8" cortex-m-rt = "0.6.7" -cortex-m-rtfm-macros = { path = "macros", version = "0.4.0-beta.3" } +cortex-m-rtfm-macros = { path = "macros", version = "0.4.0" } heapless = "0.4.1" owned-singleton = "0.1.0" diff --git a/README.md b/README.md index 367a992..2aec29c 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,6 @@ A concurrency framework for building real time systems. -**IMPORTANT** This crate is currently in pre-release (beta) state . We reserve -the right to make breaking changes in the syntax or to patch memory safety holes -before the v0.4.0 release, which is planned for 2018-12-07. When v0.4.0 is -released *all the pre-releases will be yanked*. If you run into a panic message -or an unhelpful error message (e.g. misleading span), or if something doesn't -behave the way you expect please open [an issue]! - -[an issue]: https://github.com/japaric/cortex-m-rtfm/issues - ## Features - **Tasks** as the unit of concurrency [^1]. Tasks can be *event triggered* diff --git a/book/src/by-example/app.md b/book/src/by-example/app.md index ae0f4b8..26aa03f 100644 --- a/book/src/by-example/app.md +++ b/book/src/by-example/app.md @@ -9,9 +9,9 @@ This is the smallest possible RTFM application: All RTFM 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 *device* crate generated using [`svd2rust`] **v0.14.x**. The `app` -attribute will expand into a suitable entry point so it's not required to use -the [`cortex_m_rt::entry`] attribute. +point to a *peripheral access crate* (PAC) generated using [`svd2rust`] +**v0.14.x**. 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 [`svd2rust`]: https://crates.io/crates/svd2rust diff --git a/book/src/by-example/new.md b/book/src/by-example/new.md index b6c4643..b7d18a7 100644 --- a/book/src/by-example/new.md +++ b/book/src/by-example/new.md @@ -16,9 +16,9 @@ $ cargo generate \ $ # follow the rest of the instructions ``` -2. Add a device crate that was generated using [`svd2rust`] **v0.14.x**, or a - board support crate that depends on one such device crate as a dependency. - Make sure that the `rt` feature of the crate is enabled. +2. Add a peripheral access crate (PAC) that was generated using [`svd2rust`] + **v0.14.x**, or a board support crate that depends on one such PAC as a + dependency. Make sure that the `rt` feature of the crate is enabled. [`svd2rust`]: https://crates.io/crates/svd2rust @@ -40,7 +40,7 @@ $ rm memory.x build.rs `timer-queue` feature. ``` console -$ cargo add cortex-m-rtfm --allow-prerelease --upgrade=none +$ cargo add cortex-m-rtfm ``` 4. Write your RTFM application. @@ -49,7 +49,7 @@ Here I'll use the `init` example from the `cortex-m-rtfm` crate. ``` console $ curl \ - -L https://github.com/japaric/cortex-m-rtfm/raw/v0.4.0-beta.1/examples/init.rs \ + -L https://github.com/japaric/cortex-m-rtfm/raw/v0.4.0/examples/init.rs \ > src/main.rs ``` diff --git a/book/src/preface.md b/book/src/preface.md index fe4ad62..e64a996 100644 --- a/book/src/preface.md +++ b/book/src/preface.md @@ -7,6 +7,6 @@ This book contains user level documentation for the Real Time For the Masses (RTFM) framework. The API reference can be found [here](../api/rtfm/index.html). -{{#include ../../README.md:5:55}} +{{#include ../../README.md:5:46}} -{{#include ../../README.md:61:}} +{{#include ../../README.md:52:}} diff --git a/macros/Cargo.toml b/macros/Cargo.toml index 4c4b734..b35ca1d 100644 --- a/macros/Cargo.toml +++ b/macros/Cargo.toml @@ -9,7 +9,7 @@ license = "MIT OR Apache-2.0" name = "cortex-m-rtfm-macros" readme = "../README.md" repository = "https://github.com/japaric/cortex-m-rtfm" -version = "0.4.0-beta.3" +version = "0.4.0" [lib] proc-macro = true -- cgit v1.2.3 From 5b032243e63e230c504d52ad85d4f275adf1d58d Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Sun, 16 Dec 2018 21:24:10 +0100 Subject: book: add some notes about the timer queue --- book/src/by-example/timer-queue.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'book/src') diff --git a/book/src/by-example/timer-queue.md b/book/src/by-example/timer-queue.md index a9c3622..f8066c2 100644 --- a/book/src/by-example/timer-queue.md +++ b/book/src/by-example/timer-queue.md @@ -1,8 +1,16 @@ # Timer queue When the `timer-queue` feature is enabled the RTFM framework includes a *global -timer queue* that applications can use to *schedule* software tasks to run some -time in the future. +timer queue* that applications can use to *schedule* software tasks to run at +some time in the future. + +> **NOTE**: The timer-queue feature can't be enabled when the target is +> `thumbv6m-none-eabi` because there's no timer queue support for ARMv6-M. This +> may change in the future. + +> **NOTE**: When the `timer-queue` feature is enabled you will *not* be able to +> use the `SysTick` exception as a hardware task because the runtime uses it to +> implement the global timer queue. To be able to schedule a software task the name of the task must appear in the `schedule` argument of the context attribute. When scheduling a task the -- cgit v1.2.3