Merge branch 'master' into spawn_experiment

book/en/src/by-example/app.md

@@ -7,11 +7,14 @@ This is the smallest possible RTIC application:
 ```
 
 All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute
-must be applied to a `mod`-item. The `app` attribute has
+must be applied to a `mod`-item. The `app` attribute has a mandatory `device`
-a mandatory `device` argument that takes a *path* as a value. This path must
+argument that takes a *path* as a value. This must be a full path pointing to a
-point to a *peripheral access crate* (PAC) generated using [`svd2rust`]
+*peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or
-**v0.14.x** or newer. The `app` attribute will expand into a suitable entry
+newer. More details can be found in the [Starting a new project](./new.md)
-point so it's not required to use the [`cortex_m_rt::entry`] attribute.
+section.
+
+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_rtic_macros/attr.app.html
 [`svd2rust`]: https://crates.io/crates/svd2rust

book/en/src/by-example/new.md

@@ -52,7 +52,23 @@ $ curl \
     > src/main.rs
 ```
 
-That example depends on the `panic-semihosting` crate:
+The `init` example uses the `lm3s6965` device. Remember to adjust the `device`
+argument in the app macro attribute to match the path of your PAC crate, if
+different, and add peripherals or other arguments if needed. Although aliases
+can be used, this needs to be a full path (from the crate root). For many
+devices, it is common for the HAL implementation crate (aliased as `hal`) or
+Board Support crate to re-export the PAC as `pac`, leading to a pattern similar
+to the below:
+
+```rust
+use abcd123_hal as hal;
+//...
+
+#[rtic::app(device = crate::hal::pac, peripherals = true, monotonic = rtic::cyccnt::CYCCNT)]
+mod app { /*...*/ }
+```
+
+The `init` example also depends on the `panic-semihosting` crate:
 
 ``` console
 $ cargo add panic-semihosting

examples/t-schedule-core-stable.rs

@@ -0,0 +1,28 @@
+//! [compile-pass] Check `schedule` code generation
+
+#![deny(unsafe_code)]
+#![deny(warnings)]
+#![no_main]
+#![no_std]
+
+use panic_halt as _;
+
+#[rtic::app(device = lm3s6965, monotonic = rtic::cyccnt::CYCCNT)]
+mod app {
+    #[init]
+    fn init(c: init::Context) -> init::LateResources {
+        let _c: rtic::Peripherals = c.core;
+
+        init::LateResources {}
+    }
+
+    #[task]
+    fn some_task(_: some_task::Context) {}
+
+    // RTIC requires that unused interrupts are declared in an extern block when
+    // using software tasks; these free interrupts will be used to dispatch the
+    // software tasks.
+    extern "C" {
+        fn SSI0();
+    }
+}

macros/src/codegen.rs

@@ -135,7 +135,7 @@ pub fn app(app: &App, analysis: &Analysis, extra: &Extra) -> TokenStream2 {
         /// Implementation details
         mod #name {
             /// Always include the device crate which contains the vector table
-            use #device as _;
+            use #device as you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml;
             #(#imports)*
             #(#user_imports)*
 

macros/src/codegen/pre_init.rs

@@ -49,14 +49,14 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
         let interrupt = util::interrupt_ident();
         stmts.push(quote!(
             core.NVIC.set_priority(
-                #device::#interrupt::#name,
+                you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#interrupt::#name,
                 rtic::export::logical2hw(#priority, #nvic_prio_bits),
             );
         ));
 
         // NOTE unmask the interrupt *after* setting its priority: changing the priority of a pended
         // interrupt is implementation defined
-        stmts.push(quote!(rtic::export::NVIC::unmask(#device::#interrupt::#name);));
+        stmts.push(quote!(rtic::export::NVIC::unmask(you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#interrupt::#name);));
     }
 
     // Set exception priorities

macros/src/codegen/timer_queue.rs

@@ -62,7 +62,6 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
 
         // Timer queue handler
         {
-            let device = extra.device;
             let arms = app
                 .software_tasks
                 .iter()
@@ -76,7 +75,7 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec<TokenStream
 
                     let pend = {
                         quote!(
-                            rtic::pend(#device::#enum_::#interrupt);
+                            rtic::pend(you_must_enable_the_rt_feature_for_the_pac_in_your_cargo_toml::#enum_::#interrupt);
                         )
                     };
 

macros/src/codegen/util.rs

@@ -83,7 +83,7 @@ pub fn instants_ident(task: &Ident) -> Ident {
 
 pub fn interrupt_ident() -> Ident {
     let span = Span::call_site();
-    Ident::new("Interrupt", span)
+    Ident::new("interrupt", span)
 }
 
 /// Whether `name` is an exception with configurable priority

ui/single/locals-cfg.stderr

@@ -33,9 +33,3 @@ error: duplicate lang item in crate `panic_halt` (which `$CRATE` depends on): `p
   = note: the lang item is first defined in crate `std` (which `$CRATE` depends on)
   = note: first definition in `std` loaded from /usr/share/rust/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-f14aca24435a5414.rlib
   = note: second definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-33949299fdfa2375.rmeta
-
-error: duplicate lang item in crate `panic_semihosting`: `panic_impl`.
-  |
-  = note: the lang item is first defined in crate `panic_halt` (which `$CRATE` depends on)
-  = note: first definition in `panic_halt` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_halt-33949299fdfa2375.rmeta
-  = note: second definition in `panic_semihosting` loaded from $DIR/target/tests/target/x86_64-unknown-linux-gnu/debug/deps/libpanic_semihosting-f97442f9ee5cfc78.rmeta