cortex_m_interrupt/
lib.rs

1#![doc = include_str!("../README.md")]
2#![cfg_attr(feature = "unstable-doc-cfg", feature(doc_cfg))]
3#![cfg_attr(not(test), no_std)]
4
5// Re-exports
6pub use cortex_m;
7pub use cortex_m_rt::DefaultHandler_;
8
9/// Return an instance of an unnameable struct that implements [`NvicInterruptRegistration`], which
10/// is bound to the interrupt specified by `interrupt` with logical priority `priority`.
11///
12/// `interrupt` must name an enum variant of an enum that implements [`InterruptNumber`] with _at least_ 2 path segments.
13///
14/// For instance, `Interrupt::EXTI15_10` (where `Interrupt` implements [`InterruptNumber`]) is allowed,
15/// but `EXTI15_10` by itself, even if imported using `use Interrupt::EXTI15_10`, is not.
16///
17/// The returned struct has the following features:
18/// * Calling `register` more than once for the same `Interrupt` panics.
19/// * The bound interrupt will be masked in the NVIC before configuring the occupation of the registration, and
20/// unmasked after.
21/// * The the amount of available NVIC priority bits is determined runtime.
22///
23/// # Logical priority
24///
25/// A logical priority with a lower value has a lower priority level. This means that the logical priority
26/// `1` has the lowest priority level, while logical priority `2^N` (where `N = <available priority bits on platform>`)
27/// has the highest priority level. A logical priority of `0` is not allowed, and a logical priority greater than `2^N` panics
28/// at runtime.
29///
30/// # Usage
31///
32/// ```rust,ignore
33/// use cortex_m_interrupt::take_nvic_interrupt;
34///
35/// // The value returned by `take_nvic_interrupt` will
36/// // always `impl cortex_m_interrupt::NvicInterruptRegistration`.
37/// let registration = take_nvic_interrupt!(interrupt, priority);
38///
39/// ```
40///
41/// ```rust,no_run
42/// // For example, using stm32f1xx hal:
43/// use stm32f1xx_hal::pac::interrupt;
44/// let registration = cortex_m_interrupt::take_nvic_interrupt!(interrupt::EXTI15_10, 7);
45/// ```
46///
47/// [`InterruptNumber`]: cortex_m::interrupt::InterruptNumber
48/// [`Interrupt::EXTI15_10`]: stm32f1xx_hal::pac::interrupt::EXTI15_10
49pub use cortex_m_interrupt_macro::take_nvic_interrupt;
50
51/// Return an instance of an unnameable struct that implements [`ExceptionRegistration`], which
52/// is bound to the exception specified by `exception`.
53///
54/// `exception` may be any of the variants of [`Exception`] (from [`cortex_m`]), except
55/// for [`Exception::HardFault`]
56///
57/// The returned struct has the following features:
58/// * Calling `register` more than once for the same [`Exception`] panics.
59///
60/// # Usage
61///
62/// ```rust,ignore
63/// use cortex_m_interrupt::take_exception;
64///
65/// // The value returned by `take_exception` will
66/// // always `impl cortex_m_interrupt::ExceptionRegistration`.
67/// let registration = take_exception!(exception);
68/// ```
69///
70/// ```rust,no_run
71/// // For example:
72/// let registration = cortex_m_interrupt::take_exception!(SysTick);
73/// ```
74///
75/// [`Exception`]: cortex_m::peripheral::scb::Exception
76/// [`Exception::HardFault`]: cortex_m::peripheral::scb::Exception::HardFault
77pub use cortex_m_interrupt_macro::take_exception;
78
79mod exception;
80pub use exception::ExceptionRegistration;
81
82mod nvic;
83pub use nvic::{determine_prio_bits, logical2hw, NvicInterruptRegistration};
84
85/// An interrupt registration, whose occupation can be configured.
86///
87/// Creating an implementor of [`InterruptRegistration`] can be done using the
88/// [`take_nvic_interrupt`] or [`take_exception`] macros.
89pub trait InterruptRegistration {
90    /// Occupy this registration with `f`.
91    ///
92    /// Calling `register` more than once for the same interrupt will panic.
93    fn occupy(self, f: fn());
94}
cortex_m_interrupt/lib.rs

cortex_m_interrupt/
lib.rs
