Allow general exception / interrupt discovery in cortex-m-rt-macros

[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 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.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @korken89 (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[therealprof]

Sounds good to me, can you please squash this PR into a single commit?

[mciantyre]

Thanks! I think the git history should be cleaned up now.

[therealprof]

LGTM

[korken89]

bors r+

[bors]

Build succeeded

• continuous-integration/travis-ci/push

[adamgreig]

@mciantyre, have you subsequently managed to use cortex-m-rt directly, without needing your own teensy4-rt? I wonder if this change can be adapted to fix #342.

[mciantyre]

Thanks for checking in. Yes, we're directly using cortex-m-rt nowadays. You're free to revert or change this PR however necessary. Sorry for the trouble!

[adamgreig]

No trouble, glad to hear you were able to get teensy stuff working with cortex-m-rt!