diff --git a/.travis.yml b/.travis.yml index 2825a15b90..481f8fea88 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,15 +12,15 @@ matrix: if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - env: TARGET=x86_64-unknown-linux-gnu - rust: nightly-2018-12-06 + rust: nightly if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - env: TARGET=thumbv6m-none-eabi - rust: nightly-2018-12-06 + rust: nightly if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - env: TARGET=thumbv7m-none-eabi - rust: nightly-2018-12-06 + rust: nightly if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) before_install: set -e diff --git a/CHANGELOG.md b/CHANGELOG.md index e7fc88a48f..6b643f0a54 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,7 @@ This project adheres to [Semantic Versioning](http://semver.org/). ### Changed -- This crate now compiles on 1.31-beta and will compile on the stable 1.31 - release. +- This crate now compiles on stable 1.31. - [breaking-change] The `app!` macro has been transformed into an attribute. See the documentation for details. diff --git a/Cargo.toml b/Cargo.toml index 6b67c2a9e1..d96923b140 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 6c78e8bd7c..2aec29c687 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* @@ -40,7 +31,9 @@ behave the way you expect please open [an issue]! - **Highly efficient memory usage**: All the tasks share a single call stack and there's no hard dependency on a dynamic memory allocator. -- **All Cortex-M devices are fully supported**. +- **All Cortex-M devices are supported**. The core features of RTFM are + supported on all Cortex-M devices. The timer queue is currently only supported + on ARMv7-M devices. - This task model is amenable to known WCET (Worst Case Execution Time) analysis and scheduling analysis techniques. (Though we haven't yet developed Rust diff --git a/book/src/by-example/app.md b/book/src/by-example/app.md index ae0f4b8788..26aa03f617 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 b6c4643cfc..b7d18a77bc 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/by-example/timer-queue.md b/book/src/by-example/timer-queue.md index a9c3622dec..f8066c2b17 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 diff --git a/book/src/by-example/tips.md b/book/src/by-example/tips.md index c1633288ed..5057c80af4 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/book/src/preface.md b/book/src/preface.md index c041ef5fa9..e64a996f4a 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:46}} -{{#include ../../README.md:59:}} +{{#include ../../README.md:52:}} diff --git a/build.rs b/build.rs index b29f0bd681..2419b4eb84 100644 --- a/build.rs +++ b/build.rs @@ -3,6 +3,10 @@ use std::env; fn main() { let target = env::var("TARGET").unwrap(); + if target.starts_with("thumbv6m") { + println!("cargo:rustc-cfg=armv6m") + } + if target.starts_with("thumbv7m") | target.starts_with("thumbv7em") { println!("cargo:rustc-cfg=armv7m") } diff --git a/ci/script.sh b/ci/script.sh index 20394d5cdc..0244c58171 100644 --- a/ci/script.sh +++ b/ci/script.sh @@ -12,11 +12,17 @@ main() { esac cargo check --target $T - cargo check --features timer-queue --target $T + if [ $TARGET != thumbv6m-none-eabi ]; then + cargo check --features timer-queue --target $T + fi - if [ $TRAVIS_RUST_VERSION = beta ]; then + if [ $TRAVIS_RUST_VERSION != nightly ]; then rm -f .cargo/config - cargo doc --features timer-queue + if [ $TARGET != thumbv6m-none-eabi ]; then + cargo doc --features timer-queue + else + cargo doc + fi ( cd book && mdbook build ) local td=$(mktemp -d) @@ -33,7 +39,9 @@ main() { fi cargo check --target $T --examples - cargo check --features timer-queue --target $T --examples + if [ $TARGET != thumbv6m-none-eabi ]; then + cargo check --features timer-queue --target $T --examples + fi # run-pass tests case $T in @@ -76,11 +84,13 @@ main() { diff -u ci/expected/$ex.run - fi - cargo run --features timer-queue --example $ex --target $T | \ - diff -u ci/expected/$ex.run - + if [ $TARGET != thumbv6m-none-eabi ]; then + cargo run --features timer-queue --example $ex --target $T | \ + diff -u ci/expected/$ex.run - - cargo run --features timer-queue --example $ex --target $T --release | \ - diff -u ci/expected/$ex.run - + cargo run --features timer-queue --example $ex --target $T --release | \ + diff -u ci/expected/$ex.run - + fi done esac } diff --git a/examples/cfg.rs b/examples/cfg.rs new file mode 100644 index 0000000000..3f4ca90431 --- /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(); + } +}; diff --git a/macros/Cargo.toml b/macros/Cargo.toml index 4c4b734b23..b35ca1d893 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 diff --git a/src/lib.rs b/src/lib.rs index 213037b7e5..ba60078d7d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,6 +44,11 @@ pub mod export; #[cfg(feature = "timer-queue")] mod tq; +#[cfg(all(feature = "timer-queue", armv6m))] +compile_error!( + "The `timer-queue` feature is currently not supported on ARMv6-M (`thumbv6m-none-eabi`)" +); + /// Core peripherals /// /// This is `cortex_m::Peripherals` minus the peripherals that the RTFM runtime uses