Skip to main content

esp_hal/interrupt/
mod.rs

1//! # Interrupt support
2//!
3//! This module contains code to configure and handle peripheral interrupts.
4//!
5//! ## Overview
6//!
7//! Peripheral interrupt requests are not handled by the CPU directly. Instead, they are routed
8//! through the interrupt matrix, which maps peripheral interrupts to CPU interrupts. There are
9//! more peripheral interrupt signals than CPU interrupts, and multiple peripheral interrupts can
10//! be routed to the same CPU interrupt. A set of CPU interrupts are configured to run a default
11//! handler routine, which polls the interrupt controller and calls the appropriate handlers for the
12//! pending peripheral interrupts.
13//!
14//! This default handler implements interrupt nesting - meaning a higher [`Priority`] interrupt can
15//! preempt a lower priority interrupt handler. The number of priorities is a chip-specific detail.
16//!
17//! ## Usage
18//!
19//! Peripheral drivers manage interrupts for you. Where appropriate, a `set_interrupt_handler`
20//! function is provided to register a function that handles interrupts at a chosen priority
21//! level. Interrupt handler functions need to be marked by the [`#[handler]`][crate::handler]
22//! attribute. These drivers also provide `listen` and `unlisten` functions that control whether an
23//! interrupt will be generated for the matching event or not. For more information and examples,
24//! consult the documentation of the specific peripheral drivers.
25//!
26//! If you are writing your own peripheral driver, you will need to first register interrupt
27//! handlers using the [peripheral singletons'][crate::peripherals::I2C0] `bind_X_interrupt`
28//! functions. You can use the matching `enable` and `disable` functions to control the peripheral
29//! interrupt in the interrupt matrix, or you can, depending on the peripheral, set or clear the
30//! appropriate enable bits in the `int_ena` register.
31//!
32//! ## Software Interrupts
33//!
34//! The [`software`] module implements software interrupts using peripheral interrupt signals.
35#![cfg_attr(
36    multi_core,
37    doc = "Those signals can also carry cross-core communication."
38)]
39#![cfg_attr(
40    multi_core,
41    doc = "
42## Inter-Processor Call (IPC)
43
44The [`ipc`] module queues requests on a CPU, and raises the IPC interrupt of that CPU.
45"
46)]
47#![cfg_attr(
48    all(feature = "rt", multi_core, xtensa),
49    doc = "The HAL reserves `FROM_CPU_INTR0` and `FROM_CPU_INTR1` for this path."
50)]
51#![cfg_attr(
52    all(feature = "rt", single_core, context_switch_source = "from_cpu"),
53    doc = "The HAL reserves `FROM_CPU_INTR0` to switch tasks."
54)]
55#![cfg_attr(
56    all(feature = "rt", context_switch_source = "software0"),
57    doc = "
58## Context Switching
59
60The HAL defines the `Software0` interrupt handler, and switches tasks in that interrupt.
61"
62)]
63
64use crate::{peripherals::Interrupt, system::Cpu};
65
66cfg_select! {
67    esp32 => {
68        use crate::peripherals::{DPORT as INTERRUPT_CORE0, DPORT as INTERRUPT_CORE1};
69    }
70    _ => {
71        use crate::peripherals::INTERRUPT_CORE0;
72        #[cfg(multi_core)]
73        use crate::peripherals::INTERRUPT_CORE1;
74    }
75}
76
77#[cfg_attr(riscv, path = "riscv.rs")]
78#[cfg_attr(xtensa, path = "xtensa.rs")]
79mod arch;
80pub use arch::*;
81
82use crate::pac;
83
84unstable_module! {
85    pub mod software;
86
87    #[cfg(multi_core)]
88    pub mod ipc;
89
90    #[cfg(feature = "rt")]
91    #[doc(hidden)]
92    pub mod __rtos_implementation;
93}
94
95#[cfg(feature = "rt")]
96#[unsafe(no_mangle)]
97extern "C" fn EspDefaultHandler() {
98    panic!("Unhandled interrupt on {:?}", crate::system::Cpu::current());
99}
100
101/// Default (unhandled) interrupt handler
102#[instability::unstable]
103pub const DEFAULT_INTERRUPT_HANDLER: InterruptHandler = InterruptHandler::new(
104    {
105        unsafe extern "C" {
106            fn EspDefaultHandler();
107        }
108
109        unsafe {
110            core::mem::transmute::<unsafe extern "C" fn(), extern "C" fn()>(EspDefaultHandler)
111        }
112    },
113    Priority::min(),
114);
115
116/// Trait implemented by drivers that support registering an
117/// [`InterruptHandler`].
118#[instability::unstable]
119pub trait InterruptConfigurable: crate::private::Sealed {
120    #[doc = cfg_select! {
121        multi_core => "Registers an interrupt handler for the peripheral on the current core.",
122        _ => "Registers an interrupt handler for the peripheral.",
123    }]
124    #[doc = ""]
125    /// Replaces any previously registered interrupt handlers. Some peripherals
126    /// offer a shared interrupt handler for multiple purposes. The caller must
127    /// honor this constraint.
128    ///
129    /// The default/unhandled interrupt handler can be restored with
130    /// [`DEFAULT_INTERRUPT_HANDLER`].
131    fn set_interrupt_handler(&mut self, handler: InterruptHandler);
132}
133
134/// Represents an ISR callback function.
135#[derive(Copy, Clone, Debug)]
136#[cfg_attr(feature = "defmt", derive(defmt::Format))]
137#[instability::unstable]
138pub struct IsrCallback {
139    f: extern "C" fn(),
140}
141
142impl IsrCallback {
143    /// Creates a new callback from the callback function.
144    pub fn new(f: extern "C" fn()) -> Self {
145        // a valid fn pointer is non zero
146        Self { f }
147    }
148
149    /// Returns the address of the callback.
150    pub fn address(self) -> usize {
151        self.f as usize
152    }
153
154    /// The callback function.
155    ///
156    /// This is aligned and can be called.
157    pub fn callback(self) -> extern "C" fn() {
158        self.f
159    }
160}
161
162impl PartialEq for IsrCallback {
163    fn eq(&self, other: &Self) -> bool {
164        core::ptr::fn_addr_eq(self.callback(), other.callback())
165    }
166}
167
168/// An interrupt handler.
169#[cfg_attr(
170    multi_core,
171    doc = r"
172
173**Note**: Interrupts are handled on the core they were setup on. If a driver is initialized
174on core 0, and moved to core 1, core 0 will still handle the interrupt."
175)]
176#[derive(Copy, Clone, Debug)]
177#[cfg_attr(feature = "defmt", derive(defmt::Format))]
178#[instability::unstable]
179pub struct InterruptHandler {
180    f: extern "C" fn(),
181    prio: Priority,
182}
183
184impl InterruptHandler {
185    /// Creates a new [`InterruptHandler`] which will call the given function at
186    /// the given priority.
187    pub const fn new(f: extern "C" fn(), prio: Priority) -> Self {
188        Self { f, prio }
189    }
190
191    /// The Isr callback.
192    #[inline]
193    pub fn handler(&self) -> IsrCallback {
194        IsrCallback::new(self.f)
195    }
196
197    /// Returns the priority used when registering the interrupt.
198    #[inline]
199    pub fn priority(&self) -> Priority {
200        self.prio
201    }
202}
203
204const STATUS_WORDS: usize = property!("interrupts.status_registers");
205
206/// Representation of peripheral-interrupt status bits.
207#[derive(Clone, Copy, Default, Debug)]
208#[instability::unstable]
209pub struct InterruptStatus {
210    // Every set bit names a variant of `Interrupt`.
211    status: [u32; STATUS_WORDS],
212}
213
214impl InterruptStatus {
215    /// Returns the status of a particular peripheral interrupt.
216    #[instability::unstable]
217    #[inline]
218    pub fn is_pending(interrupt: Interrupt) -> bool {
219        let word = (interrupt as usize) / 32;
220        let bit = (interrupt as usize) % 32;
221        let mut status_word = 0;
222        for cpu in Cpu::all() {
223            status_word |= Self::interrupt_status_word(cpu, word);
224        }
225        (status_word & (1 << bit)) != 0
226    }
227
228    #[inline]
229    fn interrupt_status_word(cpu: Cpu, word: usize) -> u32 {
230        match cpu {
231            Cpu::ProCpu => {
232                cfg_select! {
233                    esp32p4 => {
234                        if word == 4 {
235                            // Discontiguous, cannot be part of the standard status array
236                            return INTERRUPT_CORE0::regs().core_0_intr_status4().read().bits();
237                        }
238                    }
239                    _ => {}
240                }
241
242                INTERRUPT_CORE0::regs()
243                    .core_0_intr_status(word)
244                    .read()
245                    .bits()
246            }
247            #[cfg(multi_core)]
248            Cpu::AppCpu => {
249                cfg_select! {
250                    esp32p4 => {
251                        if word == 4 {
252                            // Discontiguous, cannot be part of the standard status array
253                            return INTERRUPT_CORE1::regs().core_1_intr_status4().read().bits();
254                        }
255                    }
256                    _ => {}
257                }
258
259                INTERRUPT_CORE1::regs()
260                    .core_1_intr_status(word)
261                    .read()
262                    .bits()
263            }
264        }
265    }
266
267    /// Returns the status of peripheral interrupts.
268    ///
269    /// A status bit with no [`Interrupt`] variant reads as clear.
270    #[instability::unstable]
271    pub fn current() -> InterruptStatus {
272        let cpu = Cpu::current();
273        InterruptStatus {
274            // `Interrupt::MASK` and the status registers can have different word counts.
275            status: core::array::from_fn(|word| {
276                Self::interrupt_status_word(cpu, word)
277                    & Interrupt::MASK.get(word).copied().unwrap_or(0)
278            }),
279        }
280    }
281
282    /// Is the given interrupt bit set.
283    #[instability::unstable]
284    pub fn is_set(&self, interrupt: u8) -> bool {
285        (self.status[interrupt as usize / 32] & (1 << (interrupt % 32))) != 0
286    }
287
288    /// Sets the given interrupt status bit.
289    #[instability::unstable]
290    pub fn set(&mut self, interrupt: Interrupt) {
291        let interrupt = interrupt as usize;
292        self.status[interrupt / 32] |= 1 << (interrupt % 32);
293    }
294
295    /// Returns an iterator over the set interrupt status bits.
296    #[instability::unstable]
297    pub fn iterator(&self) -> InterruptStatusIterator {
298        InterruptStatusIterator {
299            status: *self,
300            idx: 0,
301        }
302    }
303}
304
305/// Iterator over set interrupt status bits
306#[derive(Debug, Clone)]
307#[instability::unstable]
308pub struct InterruptStatusIterator {
309    status: InterruptStatus,
310    idx: usize,
311}
312
313impl Iterator for InterruptStatusIterator {
314    type Item = Interrupt;
315
316    #[inline(always)]
317    fn next(&mut self) -> Option<Self::Item> {
318        for i in self.idx..STATUS_WORDS {
319            if self.status.status[i] != 0 {
320                let bit = self.status.status[i].trailing_zeros();
321                self.status.status[i] ^= 1 << bit;
322                self.idx = i;
323                let nr = (bit + 32 * i as u32) as u16;
324                // SAFETY: every set bit in `InterruptStatus` names a variant of `Interrupt`.
325                return Some(unsafe { core::mem::transmute::<u16, Interrupt>(nr) });
326            }
327        }
328        self.idx = usize::MAX;
329        None
330    }
331}
332
333// Peripheral interrupt API.
334
335fn vector_entry(interrupt: Interrupt) -> &'static pac::Vector {
336    unsafe extern "Rust" {
337        #[cfg(xtensa)]
338        static __INTERRUPTS: pac::Vector;
339        #[cfg(riscv)]
340        static __EXTERNAL_INTERRUPTS: pac::Vector;
341    }
342
343    // SAFETY: Interrupt numbers are guaranteed to be valid and in range because we use the
344    // Interrupt enum, which is generated from the list of valid peripheral interrupts in the PAC.
345    unsafe {
346        cfg_select! {
347            xtensa => (&__INTERRUPTS as *const pac::Vector)
348                .add(interrupt as usize)
349                .as_ref_unchecked(),
350            riscv => (&__EXTERNAL_INTERRUPTS as *const pac::Vector)
351                .add(interrupt as usize)
352                .as_ref_unchecked(),
353            _ => {
354                compile_error!("Unsupported architecture");
355            }
356        }
357    }
358}
359
360/// Returns the currently bound interrupt handler.
361#[instability::unstable]
362pub fn bound_handler(interrupt: Interrupt) -> Option<IsrCallback> {
363    unsafe {
364        let vector = vector_entry(interrupt);
365
366        let addr = vector._handler;
367        if addr as usize == 0 {
368            return None;
369        }
370
371        Some(IsrCallback::new(core::mem::transmute::<
372            unsafe extern "C" fn(),
373            extern "C" fn(),
374        >(addr)))
375    }
376}
377
378/// Binds the given handler to a peripheral interrupt.
379///
380/// The interrupt handler will be enabled at the specified priority level.
381///
382/// The interrupt handler will be called on the core where it is registered.
383/// Only one interrupt handler can be bound to a peripheral interrupt.
384#[instability::unstable]
385pub fn bind_handler(interrupt: Interrupt, handler: InterruptHandler) {
386    bind_vector(interrupt, handler);
387    enable(interrupt, handler.priority());
388}
389
390/// Binds `handler` to `interrupt` without enabling the peripheral interrupt.
391pub(crate) fn bind_vector(interrupt: Interrupt, handler: InterruptHandler) {
392    unsafe {
393        let vector = vector_entry(interrupt);
394        let ptr = (&raw const vector._handler).cast::<usize>().cast_mut();
395
396        #[cfg(all(riscv, write_vec_table_monitoring))]
397        if crate::soc::trap_section_protected() {
398            crate::debugger::DEBUGGER_LOCK.lock(|| {
399                let wp = crate::debugger::clear_watchpoint(1);
400                ptr.write_volatile(handler.handler().address());
401                crate::debugger::restore_watchpoint(1, wp);
402            });
403            return;
404        }
405
406        ptr.write_volatile(handler.handler().address());
407    }
408}
409
410/// Enables a peripheral interrupt at a given priority, using vectored CPU interrupts.
411///
412/// Interrupts must still be enabled globally for interrupts to be serviced.
413///
414/// Internally maps the interrupt to the appropriate CPU interrupt
415/// for the specified priority level.
416#[inline]
417#[instability::unstable]
418pub fn enable(interrupt: Interrupt, level: Priority) {
419    enable_on_cpu(Cpu::current(), interrupt, level);
420}
421
422pub(crate) fn enable_on_cpu(cpu: Cpu, interrupt: Interrupt, level: Priority) {
423    let cpu_interrupt = priority_to_cpu_interrupt(interrupt, level);
424    map_raw(cpu, interrupt, cpu_interrupt as u32);
425}
426
427/// Disables the given peripheral interrupt.
428///
429/// Internally maps the interrupt to a disabled CPU interrupt.
430#[inline]
431#[instability::unstable]
432pub fn disable(core: Cpu, interrupt: Interrupt) {
433    map_raw(core, interrupt, DISABLED_CPU_INTERRUPT)
434}
435
436pub(super) fn map_raw(core: Cpu, interrupt: Interrupt, cpu_interrupt: u32) {
437    match core {
438        Cpu::ProCpu => {
439            INTERRUPT_CORE0::regs()
440                .core_0_intr_map(interrupt as usize)
441                .modify(|_, w| unsafe { w.map().bits(cpu_interrupt as u8) });
442        }
443        #[cfg(multi_core)]
444        Cpu::AppCpu => {
445            INTERRUPT_CORE1::regs()
446                .core_1_intr_map(interrupt as usize)
447                .modify(|_, w| unsafe { w.map().bits(cpu_interrupt as u8) });
448        }
449    }
450}
451
452/// Returns the CPU interrupt assigned to peripheral interrupt.
453#[cfg(all(feature = "rt", gpio_driver_supported))]
454pub(crate) fn mapped_to(cpu: Cpu, interrupt: Interrupt) -> Option<CpuInterrupt> {
455    mapped_to_raw(cpu, interrupt as u32)
456}
457
458#[cfg(feature = "rt")]
459#[crate::ram]
460pub(crate) fn mapped_to_raw(cpu: Cpu, interrupt: u32) -> Option<CpuInterrupt> {
461    let cpu_intr = match cpu {
462        Cpu::ProCpu => INTERRUPT_CORE0::regs()
463            .core_0_intr_map(interrupt as usize)
464            .read()
465            .map()
466            .bits() as u32,
467        #[cfg(multi_core)]
468        Cpu::AppCpu => INTERRUPT_CORE1::regs()
469            .core_1_intr_map(interrupt as usize)
470            .read()
471            .map()
472            .bits() as u32,
473    };
474    CpuInterrupt::from_u32(cpu_intr)
475}
476
477/// Represents the priority level of running code.
478///
479/// Interrupts at or below this level are masked.
480#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
481#[cfg_attr(feature = "defmt", derive(defmt::Format))]
482#[non_exhaustive]
483pub enum RunLevel {
484    /// Thread mode.
485    ///
486    /// This is the lowest level. No interrupts are masked by the run level.
487    ThreadMode,
488
489    /// An elevated level, usually an interrupt handler's.
490    Interrupt(ElevatedRunLevel),
491}
492
493impl RunLevel {
494    #[procmacros::doc_replace]
495    /// Returns the current run level.
496    ///
497    /// # Examples
498    ///
499    /// ```rust, no_run
500    /// # {before_snippet}
501    /// use esp_hal::interrupt::RunLevel;
502    ///
503    /// let level = RunLevel::current();
504    /// println!("Current run level: {:?}", level);
505    /// # {after_snippet}
506    /// ```
507    #[inline]
508    pub fn current() -> Self {
509        let raw = current_raw_runlevel();
510        unwrap!(Self::try_from_u32(raw))
511    }
512
513    /// Changes the current run level to the specified level and returns the previous level.
514    ///
515    /// # Safety
516    ///
517    /// Must only be used to raise the run level and to restore it to a previous
518    /// value. Must not be used to arbitrarily lower the run level.
519    #[inline]
520    #[instability::unstable]
521    pub unsafe fn change(to: Self) -> Self {
522        unsafe { change_current_runlevel(to) }
523    }
524
525    #[procmacros::doc_replace]
526    /// Returns whether the run level indicates thread mode.
527    ///
528    /// Thread mode means the CPU is not executing an interrupt handler.
529    ///
530    /// # Examples
531    ///
532    /// ```rust, no_run
533    /// # {before_snippet}
534    /// use esp_hal::interrupt::RunLevel;
535    ///
536    /// let level = RunLevel::current();
537    ///
538    /// if level.is_thread() {
539    ///     println!("Running in thread mode");
540    /// } else {
541    ///     println!("Running in an interrupt handler");
542    /// }
543    /// # {after_snippet}
544    /// ```
545    #[inline]
546    pub fn is_thread(&self) -> bool {
547        matches!(self, RunLevel::ThreadMode)
548    }
549
550    pub(crate) fn try_from_u32(priority: u32) -> Result<Self, PriorityError> {
551        if priority == 0 {
552            Ok(RunLevel::ThreadMode)
553        } else {
554            ElevatedRunLevel::try_from_u32(priority).map(RunLevel::Interrupt)
555        }
556    }
557}
558
559impl PartialEq<ElevatedRunLevel> for RunLevel {
560    fn eq(&self, other: &ElevatedRunLevel) -> bool {
561        *self == RunLevel::Interrupt(*other)
562    }
563}
564
565impl PartialEq<Priority> for RunLevel {
566    fn eq(&self, other: &Priority) -> bool {
567        let runlevel = ElevatedRunLevel::from(*other);
568        *self == RunLevel::Interrupt(runlevel)
569    }
570}
571
572impl From<RunLevel> for u32 {
573    fn from(level: RunLevel) -> Self {
574        match level {
575            RunLevel::ThreadMode => 0,
576            RunLevel::Interrupt(priority) => priority as u32,
577        }
578    }
579}
580
581/// Priority Level Error.
582#[derive(Copy, Clone, Debug, PartialEq, Eq)]
583#[cfg_attr(feature = "defmt", derive(defmt::Format))]
584#[instability::unstable]
585pub enum PriorityError {
586    /// The priority is not valid.
587    InvalidInterruptPriority,
588}
589
590#[instability::unstable]
591impl TryFrom<u32> for RunLevel {
592    type Error = PriorityError;
593
594    fn try_from(priority: u32) -> Result<Self, Self::Error> {
595        Self::try_from_u32(priority)
596    }
597}
598
599#[cfg(feature = "rt")]
600pub(crate) fn setup_interrupts() {
601    // disable all known peripheral interrupts
602    for peripheral_interrupt in 0..255 {
603        crate::peripherals::Interrupt::try_from(peripheral_interrupt)
604            .map(|intr| {
605                #[cfg(multi_core)]
606                disable(Cpu::AppCpu, intr);
607                disable(Cpu::ProCpu, intr);
608            })
609            .ok();
610    }
611
612    unsafe { crate::interrupt::init_vectoring() };
613}
614
615#[inline(always)]
616#[cfg(feature = "rt")]
617fn should_handle(core: Cpu, interrupt_nr: u32, level: u32) -> bool {
618    if let Some(cpu_interrupt) = crate::interrupt::mapped_to_raw(core, interrupt_nr)
619        && cpu_interrupt.is_vectored()
620        && cpu_interrupt.level() == level
621    {
622        true
623    } else {
624        false
625    }
626}