1#![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#[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#[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 fn set_interrupt_handler(&mut self, handler: InterruptHandler);
132}
133
134#[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 pub fn new(f: extern "C" fn()) -> Self {
145 Self { f }
147 }
148
149 pub fn address(self) -> usize {
151 self.f as usize
152 }
153
154 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#[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 pub const fn new(f: extern "C" fn(), prio: Priority) -> Self {
188 Self { f, prio }
189 }
190
191 #[inline]
193 pub fn handler(&self) -> IsrCallback {
194 IsrCallback::new(self.f)
195 }
196
197 #[inline]
199 pub fn priority(&self) -> Priority {
200 self.prio
201 }
202}
203
204const STATUS_WORDS: usize = property!("interrupts.status_registers");
205
206#[derive(Clone, Copy, Default, Debug)]
208#[instability::unstable]
209pub struct InterruptStatus {
210 status: [u32; STATUS_WORDS],
212}
213
214impl InterruptStatus {
215 #[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 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 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 #[instability::unstable]
271 pub fn current() -> InterruptStatus {
272 let cpu = Cpu::current();
273 InterruptStatus {
274 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 #[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 #[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 #[instability::unstable]
297 pub fn iterator(&self) -> InterruptStatusIterator {
298 InterruptStatusIterator {
299 status: *self,
300 idx: 0,
301 }
302 }
303}
304
305#[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 return Some(unsafe { core::mem::transmute::<u16, Interrupt>(nr) });
326 }
327 }
328 self.idx = usize::MAX;
329 None
330 }
331}
332
333fn 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 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#[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#[instability::unstable]
385pub fn bind_handler(interrupt: Interrupt, handler: InterruptHandler) {
386 bind_vector(interrupt, handler);
387 enable(interrupt, handler.priority());
388}
389
390pub(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#[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#[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#[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#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
481#[cfg_attr(feature = "defmt", derive(defmt::Format))]
482#[non_exhaustive]
483pub enum RunLevel {
484 ThreadMode,
488
489 Interrupt(ElevatedRunLevel),
491}
492
493impl RunLevel {
494 #[procmacros::doc_replace]
495 #[inline]
508 pub fn current() -> Self {
509 let raw = current_raw_runlevel();
510 unwrap!(Self::try_from_u32(raw))
511 }
512
513 #[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 #[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#[derive(Copy, Clone, Debug, PartialEq, Eq)]
583#[cfg_attr(feature = "defmt", derive(defmt::Format))]
584#[instability::unstable]
585pub enum PriorityError {
586 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 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}