Merge #116

116: v0.4.0 r=japaric a=japaric



Co-authored-by: Jorge Aparicio <jorge@japaric.io>

.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

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
+- This crate now compiles on stable 1.31.
-  release.
 
 - [breaking-change] The `app!` macro has been transformed into an attribute. See
   the documentation for details.

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"
 

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

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`
+point to a *peripheral access crate* (PAC) generated using [`svd2rust`]
-attribute will expand into a suitable entry point so it's not required to use
+**v0.14.x**. The `app` attribute will expand into a suitable entry point so it's
-the [`cortex_m_rt::entry`] attribute.
+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

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
+2. Add a peripheral access crate (PAC) that was generated using [`svd2rust`]
-   board support crate that depends on one such device crate as a dependency.
+   **v0.14.x**, or a board support crate that depends on one such PAC as a
-   Make sure that the `rt` feature of the crate is enabled.
+   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
 ```
 

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
+timer queue* that applications can use to *schedule* software tasks to run at
-time in the future.
+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

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

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:}}

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")
     }

ci/script.sh

@@ -12,11 +12,17 @@ main() {
         esac
 
         cargo check --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
+            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
+    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
 
+                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 -
+                fi
             done
     esac
 }

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();
+    }
+};

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

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