From 81b2043a235375a31468d562cea2a301d2bb9449 Mon Sep 17 00:00:00 2001 From: Ian McIntyre Date: Sat, 22 Feb 2025 13:04:40 -0500 Subject: Document workaround for registering exceptions Given the way this package abuses cortex-m-rt, it's not immediately obvious how to register a Cortex-M exception handler with the `#[exception]` macro. This commit documents and demonstrates the workaround I use. --- src/lib.rs | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'src') diff --git a/src/lib.rs b/src/lib.rs index fd42472..7ec6557 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,7 +19,7 @@ //! register exceptions, and interrupts. You should be familiar with specifing a linker //! script for your embedded project. //! -//! [cmrt]: https://docs.rs/cortex-m-rt/0.7.1/cortex_m_rt/ +//! [cmrt]: https://docs.rs/cortex-m-rt/0.7.3/cortex_m_rt/ //! //! # Dependencies //! @@ -122,7 +122,7 @@ //! //! # Feature flags //! -//! `imxrt-rt` supports the features available in `cortex-m-rt` version 0.7.2. If you enable a feature, +//! `imxrt-rt` supports the features available in `cortex-m-rt` version 0.7.3. If you enable a feature, //! you must enable it in both the `[dependencies]` and `[build-dependencies]` section of your package //! manifest. For example, if the `cortex-m-rt` `"device"` feature were needed, then enable this crate's //! `"device"` feature in both places. @@ -153,6 +153,27 @@ //! other mechanism for running code before `main()`. //! //! The implementation assumes all flash is FlexSPI. +//! +//! ## Using `#[exception]` to register exception handlers +//! +//! This section only applies to Cortex-M exception handlers, not device-specific +//! interrupt handlers. If you're not sure of the difference, consult the [`cortex-m-rt`][cmrt] +//! documentation. +//! +//! Given the way this crate (ab)uses `cortex-m-rt`, and given the way the `cortex-m-rt` +//! macros work, you may encounter issues using the `#[exception]` macro to register +//! exception handlers. Fortunately, today's workaround is simple. +//! +//! Within the package that registers the exception handler, add a direct dependency +//! on `cortex-m-rt` 0.7, similar to what's shown below. +//! +//! ```toml +//! [dependencies] +//! cortex-m-rt = "0.7" +//! ``` +//! +//! With this in place, your package should be able to use the `#[exception]` macro +//! exported by `imxrt-rt`. See the `imxrt-rt` package examples for a demonstration. #![cfg_attr(all(target_arch = "arm", target_os = "none"), no_std)] -- cgit v1.2.3