//! # Interrupt support

//!

//! This module contains code to configure and handle peripheral interrupts.

//!

//! ## Overview

//!

//! Peripheral interrupt requests are not handled by the CPU directly. Instead, they are routed

//! through the interrupt matrix, which maps peripheral interrupts to CPU interrupts. There are

//! more peripheral interrupt signals than CPU interrupts, and multiple peripheral interrupts can

//! be routed to the same CPU interrupt. A set of CPU interrupts are configured to run a default

//! handler routine, which polls the interrupt controller and calls the appropriate handlers for the

//! pending peripheral interrupts.

//!

//! This default handler implements interrupt nesting - meaning a higher [`Priority`] interrupt can

//! preempt a lower priority interrupt handler. The number of priorities is a chip-specific detail.

//!

//! ## Usage

//!

//! Peripheral drivers manage interrupts for you. Where appropriate, a `set_interrupt_handler`

//! function is provided to register a function that handles interrupts at a chosen priority

//! level. Interrupt handler functions need to be marked by the [`#[handler]`][crate::handler]

//! attribute. These drivers also provide `listen` and `unlisten` functions that control whether an

//! interrupt will be generated for the matching event or not. For more information and examples,

//! consult the documentation of the specific peripheral drivers.

//!

//! If you are writing your own peripheral driver, you will need to first register interrupt

//! handlers using the [peripheral singletons'][crate::peripherals::I2C0] `bind_X_interrupt`

//! functions. You can use the matching `enable` and `disable` functions to control the peripheral

//! interrupt in the interrupt matrix, or you can, depending on the peripheral, set or clear the

//! appropriate enable bits in the `int_ena` register.

//!

//! ## Software Interrupts

//!

//! The [`software`] module implements software interrupts using peripheral interrupt signals.

#![cfg_attr(

    multi_core,

    doc = "Those signals can also carry cross-core communication."

)]

#![cfg_attr(

    all(feature = "rt", multi_core),

    doc = "

## Inter-Processor Call (IPC)

The [`ipc`] module posts a function to a CPU, and raises the IPC interrupt of that CPU.

"

)]

#![cfg_attr(

    all(feature = "rt", multi_core, xtensa),

    doc = "The HAL reserves `FROM_CPU_INTR0` and `FROM_CPU_INTR1` for this path."

)]

#![cfg_attr(

    all(feature = "rt", single_core, context_switch_source = "from_cpu"),

    doc = "The HAL reserves `FROM_CPU_INTR0` to switch tasks."

)]

#![cfg_attr(

    all(feature = "rt", context_switch_source = "software0"),

    doc = "

## Context Switching

The HAL defines the `Software0` interrupt handler, and switches tasks in that interrupt.

"

)]

use crate::{peripherals::Interrupt, system::Cpu};

cfg_select! {

    esp32 => {

        use crate::peripherals::{DPORT as INTERRUPT_CORE0, DPORT as INTERRUPT_CORE1};

    }

    _ => {

        use crate::peripherals::INTERRUPT_CORE0;

        #[cfg(multi_core)]

        use crate::peripherals::INTERRUPT_CORE1;

    }

}

#[cfg_attr(riscv, path = "riscv.rs")]

#[cfg_attr(xtensa, path = "xtensa.rs")]

mod arch;

pub use arch::*;

use crate::pac;

unstable_module! {

    pub mod software;

    #[cfg(all(feature = "rt", multi_core))]

    pub mod ipc;

    #[cfg(feature = "rt")]

    #[doc(hidden)]

    pub mod __rtos_implementation;

}

#[cfg(feature = "rt")]

#[unsafe(no_mangle)]

}

/// Default (unhandled) interrupt handler

#[instability::unstable]

pub const DEFAULT_INTERRUPT_HANDLER: InterruptHandler = InterruptHandler::new(

    {

        unsafe extern "C" {

            fn EspDefaultHandler();

        }

        unsafe {

            core::mem::transmute::<unsafe extern "C" fn(), extern "C" fn()>(EspDefaultHandler)

        }

    },

    Priority::min(),

);

/// Trait implemented by drivers that support registering an

/// [`InterruptHandler`].

#[instability::unstable]

pub trait InterruptConfigurable: crate::private::Sealed {

    #[doc = cfg_select! {

        multi_core => "Registers an interrupt handler for the peripheral on the current core.",

        _ => "Registers an interrupt handler for the peripheral.",

    }]

    #[doc = ""]

    /// Replaces any previously registered interrupt handlers. Some peripherals

    /// offer a shared interrupt handler for multiple purposes. The caller must

    /// honor this constraint.

    ///

    /// The default/unhandled interrupt handler can be restored with

    /// [`DEFAULT_INTERRUPT_HANDLER`].

    fn set_interrupt_handler(&mut self, handler: InterruptHandler);

}

/// Represents an ISR callback function.

#[derive(Copy, Clone, Debug)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[instability::unstable]

pub struct IsrCallback {

    f: extern "C" fn(),

}

impl IsrCallback {

    /// Creates a new callback from the callback function.

    pub fn new(f: extern "C" fn()) -> Self {

        // a valid fn pointer is non zero

        Self { f }

    }

    /// Returns the address of the callback.

    pub fn address(self) -> usize {

        self.f as usize

    }

    /// The callback function.

    ///

    /// This is aligned and can be called.

    pub fn callback(self) -> extern "C" fn() {

        self.f

    }

}

impl PartialEq for IsrCallback {

    fn eq(&self, other: &Self) -> bool {

        core::ptr::fn_addr_eq(self.callback(), other.callback())

    }

}

/// An interrupt handler.

#[cfg_attr(

    multi_core,

    doc = r"

**Note**: Interrupts are handled on the core they were setup on. If a driver is initialized

on core 0, and moved to core 1, core 0 will still handle the interrupt."

)]

#[derive(Copy, Clone, Debug)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[instability::unstable]

pub struct InterruptHandler {

    f: extern "C" fn(),

    prio: Priority,

}

impl InterruptHandler {

    /// Creates a new [`InterruptHandler`] which will call the given function at

    /// the given priority.

    pub const fn new(f: extern "C" fn(), prio: Priority) -> Self {

        Self { f, prio }

    }

    /// The Isr callback.

    #[inline]

    pub fn handler(&self) -> IsrCallback {

        IsrCallback::new(self.f)

    }

    /// Returns the priority used when registering the interrupt.

    #[inline]

    pub fn priority(&self) -> Priority {

        self.prio

    }

}

const STATUS_WORDS: usize = property!("interrupts.status_registers");

/// Representation of peripheral-interrupt status bits.

#[derive(Clone, Copy, Default, Debug)]

#[instability::unstable]

pub struct InterruptStatus {

    status: [u32; STATUS_WORDS],

}

impl InterruptStatus {

    /// Returns the status of a particular peripheral interrupt.

    #[instability::unstable]

    #[inline]

    pub fn is_pending(interrupt: Interrupt) -> bool {

        let word = (interrupt as usize) / 32;

        let bit = (interrupt as usize) % 32;

        let mut status_word = 0;

        for cpu in Cpu::all() {

            status_word |= Self::interrupt_status_word(cpu, word);

        }

        (status_word & (1 << bit)) != 0

    }

    #[inline]

    fn interrupt_status_word(cpu: Cpu, word: usize) -> u32 {

        match cpu {

            Cpu::ProCpu => {

                cfg_select! {

                    esp32p4 => {

                        if word == 4 {

                            // Discontiguous, cannot be part of the standard status array

                            return INTERRUPT_CORE0::regs().core_0_intr_status4().read().bits();

                        }

                    }

                    _ => {}

                }

                INTERRUPT_CORE0::regs()

                    .core_0_intr_status(word)

                    .read()

                    .bits()

            }

            #[cfg(multi_core)]

            Cpu::AppCpu => {

                cfg_select! {

                    esp32p4 => {

                        if word == 4 {

                            // Discontiguous, cannot be part of the standard status array

                            return INTERRUPT_CORE1::regs().core_1_intr_status4().read().bits();

                        }

                    }

                    _ => {}

                }

                INTERRUPT_CORE1::regs()

                    .core_1_intr_status(word)

                    .read()

                    .bits()

            }

        }

    }

    /// Returns the status of peripheral interrupts.

    #[instability::unstable]

    pub fn current() -> InterruptStatus {

        let cpu = Cpu::current();

        InterruptStatus {

            status: core::array::from_fn(|word| Self::interrupt_status_word(cpu, word)),

        }

    }

    /// Is the given interrupt bit set.

    #[instability::unstable]

    pub fn is_set(&self, interrupt: u8) -> bool {

        (self.status[interrupt as usize / 32] & (1 << (interrupt % 32))) != 0

    }

    /// Sets the given interrupt status bit.

    #[instability::unstable]

    pub fn set(&mut self, interrupt: u8) {

        self.status[interrupt as usize / 32] |= 1 << (interrupt % 32);

    }

    /// Returns an iterator over the set interrupt status bits.

    #[instability::unstable]

    pub fn iterator(&self) -> InterruptStatusIterator {

        InterruptStatusIterator {

            status: *self,

            idx: 0,

        }

    }

}

/// Iterator over set interrupt status bits

#[derive(Debug, Clone)]

#[instability::unstable]

pub struct InterruptStatusIterator {

    status: InterruptStatus,

    idx: usize,

}

impl Iterator for InterruptStatusIterator {

    type Item = u8;

    fn next(&mut self) -> Option<Self::Item> {

        for i in self.idx..STATUS_WORDS {

                let bit = self.status.status[i].trailing_zeros();

            }

        }

        self.idx = usize::MAX;

        None

    }

}

// Peripheral interrupt API.

fn vector_entry(interrupt: Interrupt) -> &'static pac::Vector {

    unsafe extern "Rust" {

        #[cfg(xtensa)]

        static __INTERRUPTS: pac::Vector;

        #[cfg(riscv)]

        static __EXTERNAL_INTERRUPTS: pac::Vector;

    }

    // SAFETY: Interrupt numbers are guaranteed to be valid and in range because we use the

    // Interrupt enum, which is generated from the list of valid peripheral interrupts in the PAC.

    unsafe {

        cfg_select! {

            xtensa => (&__INTERRUPTS as *const pac::Vector)

                .add(interrupt as usize)

                .as_ref_unchecked(),

            riscv => (&__EXTERNAL_INTERRUPTS as *const pac::Vector)

                .add(interrupt as usize)

                .as_ref_unchecked(),

            _ => {

                compile_error!("Unsupported architecture");

            }

        }

    }

}

/// Returns the currently bound interrupt handler.

#[instability::unstable]

pub fn bound_handler(interrupt: Interrupt) -> Option<IsrCallback> {

    unsafe {

        let vector = vector_entry(interrupt);

        if addr as usize == 0 {

            return None;

        }

        Some(IsrCallback::new(core::mem::transmute::<

            unsafe extern "C" fn(),

            extern "C" fn(),

        >(addr)))

    }

}

/// Binds the given handler to a peripheral interrupt.

///

/// The interrupt handler will be enabled at the specified priority level.

///

/// The interrupt handler will be called on the core where it is registered.

/// Only one interrupt handler can be bound to a peripheral interrupt.

#[instability::unstable]

    bind_vector(interrupt, handler);

    enable(interrupt, handler.priority());

/// Binds `handler` to `interrupt` without enabling the peripheral interrupt.

pub(crate) fn bind_vector(interrupt: Interrupt, handler: InterruptHandler) {

    unsafe {

        let vector = vector_entry(interrupt);

        let ptr = (&raw const vector._handler).cast::<usize>().cast_mut();

        #[cfg(all(riscv, write_vec_table_monitoring))]

        if crate::soc::trap_section_protected() {

            crate::debugger::DEBUGGER_LOCK.lock(|| {

                let wp = crate::debugger::clear_watchpoint(1);

                ptr.write_volatile(handler.handler().address());

                crate::debugger::restore_watchpoint(1, wp);

            });

            return;

        }

        ptr.write_volatile(handler.handler().address());

    }

}

/// Enables a peripheral interrupt at a given priority, using vectored CPU interrupts.

///

/// Interrupts must still be enabled globally for interrupts to be serviced.

///

/// Internally maps the interrupt to the appropriate CPU interrupt

/// for the specified priority level.

#[inline]

#[instability::unstable]

pub fn enable(interrupt: Interrupt, level: Priority) {

}

    let cpu_interrupt = priority_to_cpu_interrupt(interrupt, level);

    map_raw(cpu, interrupt, cpu_interrupt as u32);

/// Disables the given peripheral interrupt.

///

/// Internally maps the interrupt to a disabled CPU interrupt.

#[inline]

#[instability::unstable]

pub fn disable(core: Cpu, interrupt: Interrupt) {

}

    match core {

        Cpu::ProCpu => {

            INTERRUPT_CORE0::regs()

                .core_0_intr_map(interrupt as usize)

                .modify(|_, w| unsafe { w.map().bits(cpu_interrupt as u8) });

        }

        #[cfg(multi_core)]

        Cpu::AppCpu => {

            INTERRUPT_CORE1::regs()

                .core_1_intr_map(interrupt as usize)

                .modify(|_, w| unsafe { w.map().bits(cpu_interrupt as u8) });

        }

    }

/// Returns the CPU interrupt assigned to peripheral interrupt.

#[cfg(all(feature = "rt", gpio_driver_supported))]

pub(crate) fn mapped_to(cpu: Cpu, interrupt: Interrupt) -> Option<CpuInterrupt> {

    mapped_to_raw(cpu, interrupt as u32)

}

#[cfg(feature = "rt")]

pub(crate) fn mapped_to_raw(cpu: Cpu, interrupt: u32) -> Option<CpuInterrupt> {

    let cpu_intr = match cpu {

        Cpu::ProCpu => INTERRUPT_CORE0::regs()

            .core_0_intr_map(interrupt as usize)

            .read()

            .map()

            .bits() as u32,

        #[cfg(multi_core)]

        Cpu::AppCpu => INTERRUPT_CORE1::regs()

            .core_1_intr_map(interrupt as usize)

            .read()

            .map()

            .bits() as u32,

    };

    CpuInterrupt::from_u32(cpu_intr)

}

/// Represents the priority level of running code.

///

/// Interrupts at or below this level are masked.

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[non_exhaustive]

pub enum RunLevel {

    /// Thread mode.

    ///

    /// This is the lowest level. No interrupts are masked by the run level.

    ThreadMode,

    /// An elevated level, usually an interrupt handler's.

    Interrupt(ElevatedRunLevel),

}

impl RunLevel {

    #[procmacros::doc_replace]

    /// Returns the current run level.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::interrupt::RunLevel;

    ///

    /// let level = RunLevel::current();

    /// println!("Current run level: {:?}", level);

    /// # {after_snippet}

    /// ```

    #[inline]

    pub fn current() -> Self {

    }

    /// Changes the current run level to the specified level and returns the previous level.

    ///

    /// # Safety

    ///

    /// Must only be used to raise the run level and to restore it to a previous

    /// value. Must not be used to arbitrarily lower the run level.

    #[inline]

    #[instability::unstable]

    pub unsafe fn change(to: Self) -> Self {

        unsafe { change_current_runlevel(to) }

    }

    #[procmacros::doc_replace]

    /// Returns whether the run level indicates thread mode.

    ///

    /// Thread mode means the CPU is not executing an interrupt handler.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::interrupt::RunLevel;

    ///

    /// let level = RunLevel::current();

    ///

    /// if level.is_thread() {

    ///     println!("Running in thread mode");

    /// } else {

    ///     println!("Running in an interrupt handler");

    /// }

    /// # {after_snippet}

    /// ```

    #[inline]

    pub fn is_thread(&self) -> bool {

        matches!(self, RunLevel::ThreadMode)

    }

            Ok(RunLevel::ThreadMode)

        } else {

            ElevatedRunLevel::try_from_u32(priority).map(RunLevel::Interrupt)

        }

}

impl PartialEq<ElevatedRunLevel> for RunLevel {

    fn eq(&self, other: &ElevatedRunLevel) -> bool {

        *self == RunLevel::Interrupt(*other)

    }

}

impl PartialEq<Priority> for RunLevel {

    fn eq(&self, other: &Priority) -> bool {

        let runlevel = ElevatedRunLevel::from(*other);

        *self == RunLevel::Interrupt(runlevel)

    }

}

impl From<RunLevel> for u32 {

    fn from(level: RunLevel) -> Self {

            RunLevel::ThreadMode => 0,

            RunLevel::Interrupt(priority) => priority as u32,

        }

    }

}

/// Priority Level Error.

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[instability::unstable]

pub enum PriorityError {

    /// The priority is not valid.

    InvalidInterruptPriority,

}

#[instability::unstable]

impl TryFrom<u32> for RunLevel {

    type Error = PriorityError;

    fn try_from(priority: u32) -> Result<Self, Self::Error> {

        Self::try_from_u32(priority)

    }

}

#[cfg(feature = "rt")]

pub(crate) fn setup_interrupts() {

    // disable all known peripheral interrupts

    for peripheral_interrupt in 0..255 {

        crate::peripherals::Interrupt::try_from(peripheral_interrupt)

            .map(|intr| {

                #[cfg(multi_core)]

                disable(Cpu::AppCpu, intr);

                disable(Cpu::ProCpu, intr);

            })

            .ok();

    }

    unsafe { crate::interrupt::init_vectoring() };

}

#[inline(always)]

#[cfg(feature = "rt")]

fn should_handle(core: Cpu, interrupt_nr: u32, level: u32) -> bool {

    if let Some(cpu_interrupt) = crate::interrupt::mapped_to_raw(core, interrupt_nr)

        && cpu_interrupt.is_vectored()

        && cpu_interrupt.level() == level

    {

        true

    } else {

        false

    }

}