Merge #224

224: Allow general exception / interrupt discovery in cortex-m-rt-macros r=korken89 a=mciantyre

We propose changes to the `cortex-m-rt-macros` crate that should help us use the macros independent of the `cortex-m-rt` runtime. The changes in this PR should be backwards compatible for all `cortex-m-rt` users, while expanding the utility of the macros beyond the cortex-m-rt repository.

In the [Teensy 4 libraries](https://github.com/mciantyre/teensy4-rs) we're developing, we've opted to create our own runtime crate, `teensy4-rt`. We require more support than what's available in `cortex-m-rt` to boot and take advantage of NXP iMXRT106x variants. Specifically, we have a unique start-up process, and a custom memory layout with tightly-couple memory (TCM) regions. As discussed in #164, the `cortex-m-rt` crate does not support custom memory layouts. To address the limitations and provide a faster proof-of-concept, we forked the `cortex-m-rt` crate, focusing on the runtime needs of our specific system.

Despite the fork, we strive for compatibility with the `cortex-m-rt` crate. Our eventual goal is to drop the `teensy4-rt` crate, and rely on a future version of the `cortex-m-rt` crate that supports our use-case. Compatibility means supporting the macros; just as the `cortex-m-rt` crate exports the macros, the `teensy4-rt` crate exports the same macros. By requiring that the macros maintain `extern crate cortex_m_rt` declarations, we assume that the `cortex_m_rt` crate is available. However, we don't believe this is a necessary requirement.

To take advantage of the `#[interrupt]` and `#[exception]` macros, a set of crates need to export two identifiers: `interrupt`, an enumeration of valid interrupt handlers; and `exception`, an enumeration of exceptions for the Cortex M variant. We have a precedent for this pattern, in that crates generated by `svd2rust` export the enumeration of valid interrupt handlers (provided the correct features are enabled) for discovery by the `#[interrupt]` macros. The PR proposes a similar strategy: export the `Exceptions` enumeration as `exception` (lower case) from the `cortex-m-rt` crate, so that exception variant discovery occurs the same as it does for interrupts.

After the rename, and with the removal of `extern crate cortex_m_rt` in the two macros, it doesn't matter where the `exception` or `interrupt` enums are defined. The changes let us define a similar `exception` enumeration in our `teensy4-rt` crate, which may be picked up by the `#[exception]` macro. We've shown this to be a successful strategy in the Teensy 4 Rust libraries, which are based on our fork of the macros crate.

We realize that the macros are a feature of the `cortex-m-rt` crate, not a library that others should directly depend on. Ideally, we rally around the `cortex-m-rt` crate, and keep the macros coupled to that implementation. But until we reach that point, having the macros defined without expectations of the `cortex-m-rt` crate lets us bring up new embedded targets faster while maintaining compatibility with the existing ecosystem.

Co-authored-by: Ian McIntyre <[email protected]>

Author: bors[bot]

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

@@ -173,7 +173,7 @@ pub fn entry(args: TokenStream, input: TokenStream) -> TokenStream {
 /// # Syntax
 ///
 /// ```
-/// # use cortex_m_rt_macros::exception;
+/// # use cortex_m_rt::exception;
 /// #[exception]
 /// fn SysTick() {
 ///     // ..
@@ -449,10 +449,8 @@ pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
             }));
             f.block.stmts = iter::once(
                 syn::parse2(quote! {{
-                    extern crate cortex_m_rt;
-
                     // check that this exception actually exists
-                    cortex_m_rt::Exception::#ident;
+                    exception::#ident;
                 }})
                 .unwrap(),
             )
@@ -619,8 +617,6 @@ pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
     }));
     f.block.stmts = iter::once(
         syn::parse2(quote! {{
-            extern crate cortex_m_rt;
-
             // Check that this interrupt actually exists
             interrupt::#ident;
         }})

cortex-m-rt/src/lib.rs

@@ -599,6 +599,8 @@ pub enum Exception {
     SysTick,
 }
 
+pub use self::Exception as exception;
+
 extern "C" {
     fn NonMaskableInt();