Merge #122

122: [RFC] `#[interrupt]` r=therealprof a=japaric

this PR adds an `interrupt` attribute that's similar to the existing `exception`
except that it's used to override device-specific interrupt handlers.

The other big difference is that `cortex_m_rt::interrupt` can't be directly
used; it must first be imported from a device crate, which re-exports
`cortex_m_rt::interrupt`. This is required to check at compile time that the
interrupt is valid for the target device.

Safe `static mut` variables can be used with `#[interrupt]` handlers. The syntax
is the same as `#[exception]`s.

More background information can be found in #109.

The companion svd2rust PR is rust-embedded/svd2rust#235

r? @rust-embedded/cortex-m

Co-authored-by: Jorge Aparicio <[email protected]>
Co-authored-by: Adam Greig <[email protected]>

Author: 3 people

cortex-m-rt/ci/script.sh

@@ -8,7 +8,7 @@ main() {
     if [ $TARGET = x86_64-unknown-linux-gnu ] && [ $TRAVIS_RUST_VERSION = nightly ]; then
         ( cd macros && cargo check && cargo test )
 
-        cargo test --test compiletest
+        cargo test --features device --test compiletest
     fi
 
     local examples=(

cortex-m-rt/macros/src/lib.rs

@@ -412,10 +412,10 @@ pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
                     let expr = var.expr;
 
                     quote!(
-                    static mut #ident_: #ty = #expr;
-                    #[allow(non_snake_case)]
-                    let #ident: &mut #ty = unsafe { &mut #ident_ };
-                )
+                        static mut #ident_: #ty = #expr;
+                        #[allow(non_snake_case)]
+                        let #ident: &mut #ty = unsafe { &mut #ident_ };
+                    )
                 }).collect::<Vec<_>>();
 
             quote!(
@@ -436,6 +436,146 @@ pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
     }
 }
 
+/// Attribute to declare an interrupt (AKA device-specific exception) handler
+///
+/// **IMPORTANT**: This attribute must be used on reachable items (i.e. there must be no private
+/// modules between the item and the root of the crate). If the item is in the root of the crate
+/// you'll be fine.
+///
+/// **NOTE**: This attribute is exposed by `cortex-m-rt` only when the `device` feature is enabled.
+/// However, that export is not meant to be used directly -- using it will result in a compilation
+/// error. You should instead use the device crate (usually generated using `svd2rust`) re-export of
+/// that attribute. You need to use the re-export to have the compiler check that the interrupt
+/// exists on the target device.
+///
+/// # Syntax
+///
+/// ``` ignore
+/// extern crate device;
+///
+/// // the attribute comes from the device crate not from cortex-m-rt
+/// use device::interrupt;
+///
+/// #[interrupt]
+/// fn USART1() {
+///     // ..
+/// }
+/// ```
+///
+/// where the name of the function must be one of the device interrupts.
+///
+/// # Usage
+///
+/// `#[interrupt] fn Name(..` overrides the default handler for the interrupt with the given `Name`.
+/// These handlers must have signature `[unsafe] fn() [-> !]`. It's possible to add state to these
+/// handlers by declaring `static mut` variables at the beginning of the body of the function. These
+/// variables will be safe to access from the function body.
+///
+/// If the interrupt handler has not been overridden it will be dispatched by the default exception
+/// handler (`DefaultHandler`).
+///
+/// # Properties
+///
+/// Interrupts handlers can only be called by the hardware. Other parts of the program can't refer
+/// to the interrupt handlers, much less invoke them as if they were functions.
+///
+/// `static mut` variables declared within an interrupt handler are safe to access and can be used
+/// to preserve state across invocations of the handler. The compiler can't prove this is safe so
+/// the attribute will help by making a transformation to the source code: for this reason a
+/// variable like `static mut FOO: u32` will become `let FOO: &mut u32;`.
+///
+/// # Examples
+///
+/// - Using state within an interrupt handler
+///
+/// ``` ignore
+/// extern crate device;
+///
+/// use device::interrupt;
+///
+/// #[interrupt]
+/// fn TIM2() {
+///     static mut COUNT: i32 = 0;
+///
+///     // `COUNT` is safe to access and has type `&mut i32`
+///     *COUNT += 1;
+///
+///     println!("{}", COUNT);
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
+    let f: ItemFn = syn::parse(input).expect("`#[interrupt]` must be applied to a function");
+
+    assert!(
+        args.to_string() == "",
+        "`interrupt` attribute must have no arguments"
+    );
+
+    let ident = f.ident;
+    let ident_s = ident.to_string();
+
+    // XXX should we blacklist other attributes?
+    let attrs = f.attrs;
+    let block = f.block;
+    let stmts = block.stmts;
+    let unsafety = f.unsafety;
+
+    assert!(
+        f.constness.is_none()
+            && f.vis == Visibility::Inherited
+            && f.abi.is_none()
+            && f.decl.inputs.is_empty()
+            && f.decl.generics.params.is_empty()
+            && f.decl.generics.where_clause.is_none()
+            && f.decl.variadic.is_none()
+            && match f.decl.output {
+                ReturnType::Default => true,
+                ReturnType::Type(_, ref ty) => match **ty {
+                    Type::Tuple(ref tuple) => tuple.elems.is_empty(),
+                    Type::Never(..) => true,
+                    _ => false,
+                },
+            },
+        "`#[interrupt]` functions must have signature `[unsafe] fn() [-> !]`"
+    );
+
+    let (statics, stmts) = extract_static_muts(stmts);
+
+    let vars = statics
+        .into_iter()
+        .map(|var| {
+            let ident = var.ident;
+            // `let` can't shadow a `static mut` so we must give the `static` a different
+            // name. We'll create a new name by appending an underscore to the original name
+            // of the `static`.
+            let mut ident_ = ident.to_string();
+            ident_.push('_');
+            let ident_ = Ident::new(&ident_, Span::call_site());
+            let ty = var.ty;
+            let expr = var.expr;
+
+            quote!(
+                static mut #ident_: #ty = #expr;
+                #[allow(non_snake_case)]
+                let #ident: &mut #ty = unsafe { &mut #ident_ };
+            )
+        }).collect::<Vec<_>>();
+
+    let hash = random_ident();
+    quote!(
+        #[export_name = #ident_s]
+        #(#attrs)*
+        pub #unsafety extern "C" fn #hash() {
+            interrupt::#ident;
+
+            #(#vars)*
+
+            #(#stmts)*
+        }
+    ).into()
+}
+
 /// Attribute to mark which function will be called at the beginning of the reset handler.
 ///
 /// **IMPORTANT**: This attribute must be used once in the dependency graph and must be used on a

cortex-m-rt/src/lib.rs

@@ -394,6 +394,8 @@ extern crate r0;
 use core::fmt;
 use core::sync::atomic::{self, Ordering};
 
+#[cfg(feature = "device")]
+pub use macros::interrupt;
 pub use macros::{entry, exception, pre_init};
 
 #[export_name = "error: cortex-m-rt appears more than once in the dependency graph"]
@@ -674,7 +676,7 @@ pub static __EXCEPTIONS: [Vector; 14] = [
 
 // If we are not targeting a specific device we bind all the potential device specific interrupts
 // to the default handler
-#[cfg(all(not(feature = "device"), not(armv6m)))]
+#[cfg(all(any(not(feature = "device"), test), not(armv6m)))]
 #[doc(hidden)]
 #[link_section = ".vector_table.interrupts"]
 #[no_mangle]

cortex-m-rt/tests/compile-fail/interrupt-args.rs

@@ -0,0 +1,20 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+}
+
+#[interrupt(true)] //~ ERROR custom attribute panicked
+//~^ HELP `interrupt` attribute must have no arguments
+fn USART1() {}

cortex-m-rt/tests/compile-fail/interrupt-bad-signature-1.rs

@@ -0,0 +1,20 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+}
+
+#[interrupt] //~ ERROR custom attribute panicked
+//~^ HELP `#[interrupt]` functions must have signature `[unsafe] fn() [-> !]`
+fn USART1(undef: i32) {}

cortex-m-rt/tests/compile-fail/interrupt-bad-signature-2.rs

@@ -0,0 +1,22 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+}
+
+#[interrupt] //~ ERROR custom attribute panicked
+//~^ HELP `#[interrupt]` functions must have signature `[unsafe] fn() [-> !]`
+fn USART1() -> i32 {
+    0
+}

cortex-m-rt/tests/compile-fail/interrupt-invalid.rs

@@ -0,0 +1,21 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+}
+
+// NOTE this looks a bit better when using a device crate:
+// "no variant named `foo` found for type `stm32f30x::Interrupt` in the current scope"
+#[interrupt] //~ ERROR no variant named `foo` found for type `interrupt` in the current scope
+fn foo() {}

cortex-m-rt/tests/compile-fail/interrupt-not-reexported.rs

@@ -0,0 +1,15 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+#[interrupt] //~ ERROR failed to resolve. Use of undeclared type or module `interrupt`
+fn USART1() {}

cortex-m-rt/tests/compile-fail/interrupt-soundness.rs

@@ -0,0 +1,33 @@
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+    USART2,
+}
+
+#[interrupt]
+fn USART1() {
+    static mut COUNT: u64 = 0;
+
+    if *COUNT % 2 == 0 {
+        *COUNT += 1;
+    } else {
+        *COUNT *= 2;
+    }
+}
+
+#[interrupt]
+fn USART2() {
+    USART1(); //~ ERROR cannot find function `USART1` in this scope
+}

cortex-m-rt/tests/compile-fail/interrupt-twice.rs

@@ -0,0 +1,31 @@
+#![allow(non_camel_case_types)]
+#![no_main]
+#![no_std]
+
+extern crate cortex_m_rt;
+extern crate panic_halt;
+
+use cortex_m_rt::{entry, interrupt};
+
+#[entry]
+fn foo() -> ! {
+    loop {}
+}
+
+enum interrupt {
+    USART1,
+}
+
+#[interrupt]
+fn USART1() {}
+
+pub mod reachable {
+    use cortex_m_rt::interrupt;
+
+    enum interrupt {
+        USART1,
+    }
+
+    #[interrupt] //~ ERROR symbol `USART1` is already defined
+    fn USART1() {}
+}