m5stack_core/board/mod.rs
1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! Board-level bring-up: pin wiring ([`cores3::Board`]/[`fire27::Board`]),
3//! display + SD shared-bus sequences ([`spi2`], [`display`]), and bring-up
4//! orchestration across drivers.
5
6#[cfg(feature = "cores3")]
7pub mod cores3;
8#[cfg(feature = "cores3")]
9pub use cores3::usb_powered;
10/// What [`usb_powered`] fails with on this board: its PMIC's error.
11#[cfg(feature = "cores3")]
12pub type PmicError = crate::driver::axp2101::Axp2101Error;
13#[cfg(feature = "display")]
14pub mod display;
15#[cfg(feature = "fire27")]
16pub mod fire27;
17#[cfg(feature = "fire27")]
18pub use fire27::usb_powered;
19/// What [`usb_powered`] fails with on this board: its PMIC's error.
20#[cfg(feature = "fire27")]
21pub type PmicError = crate::driver::ip5306::Ip5306Error;
22#[cfg(feature = "multicore")]
23mod multicore;
24#[cfg(feature = "multicore")]
25pub use multicore::run_app_core;
26#[cfg(any(feature = "cores3", feature = "fire27"))]
27pub mod rmt;
28pub mod spi2;
29
30use esp_hal::{
31 peripherals::{
32 AES, CPU_CTRL, FLASH, FROM_CPU_INTR2, FROM_CPU_INTR3, LPWR, Peripherals, RTC_TIMER,
33 },
34 timer::AnyTimer,
35};
36
37/// On-board display resolution — a *board fact*, independent of the `display`
38/// driver feature, defined exactly once per target here. Every subsystem that
39/// needs it (the [`display`] panel builder, [`crate::io::input_caps`]) reads
40/// these rather than re-stating the numbers.
41#[cfg(feature = "cores3")]
42pub const SCREEN_W: u16 = 320;
43#[cfg(feature = "cores3")]
44pub const SCREEN_H: u16 = 240;
45#[cfg(feature = "fire27")]
46pub const SCREEN_W: u16 = 320;
47#[cfg(feature = "fire27")]
48pub const SCREEN_H: u16 = 240;
49
50/// Initialise esp-hal at max CPU clock. Heap setup stays with the app
51/// (sizing is application policy).
52///
53/// Paints the main stack first, while no interrupt is routed, so
54/// [`crate::stack::main_stack_margin`] can report its high-water.
55pub fn init() -> Peripherals {
56 crate::stack::paint_main_stack();
57 esp_hal::init(esp_hal::Config::default().with_cpu_clock(esp_hal::clock::CpuClock::max()))
58}
59
60/// Chip-level (board-independent) system resources: executor timers, software
61/// interrupts, the second core, and the RTC domain (e.g. the production RWDT,
62/// [`crate::io::watchdog`]).
63pub struct SystemResources<'a> {
64 pub sw_int: SoftwareInterrupts<'a>,
65 pub timer0_0: AnyTimer<'a>,
66 pub timer0_1: AnyTimer<'a>,
67 pub timer1_0: AnyTimer<'a>,
68 pub timer1_1: AnyTimer<'a>,
69 pub cpu_ctrl: CPU_CTRL<'a>,
70 /// RTC peripheral — RTC domain registers (reset reason, RTC-fast memory).
71 pub lpwr: LPWR<'a>,
72 /// Internal SPI flash — what `esp_hal::flash::Flash::new` takes, so a
73 /// consumer can persist settings in its own partition.
74 ///
75 /// Handed out rather than kept because the BSP has no opinion about what
76 /// belongs in flash. Note the cost that comes with it: on a dual-core part
77 /// an erase requires the other core to stop fetching from flash, so a write
78 /// parks it for tens of milliseconds. That is the caller's problem to
79 /// schedule, and it is why this is a peripheral rather than a convenience
80 /// method.
81 pub flash: FLASH<'a>,
82 /// AES accelerator — one 16-byte block per `encrypt`/`decrypt` call.
83 ///
84 /// No board wiring, handed out like [`Self::flash`]: a consumer that
85 /// decrypts on a hot path wants it instead of a software cipher, which on
86 /// xtensa is kilobytes of code plus a key schedule per message.
87 pub aes: AES<'a>,
88 /// RTC timer singleton — what `Rtc::new` takes as of esp-hal 1.2, which
89 /// split it out of `LPWR`. Handed out separately because the two are now
90 /// distinct peripherals: a consumer arming the production RWDT
91 /// ([`crate::io::watchdog`]) needs THIS, while `lpwr` still covers the
92 /// RTC-domain registers. Before 1.2 `Rtc::new(lpwr)` covered both, so a
93 /// board that only exposed `lpwr` silently stopped being able to build an
94 /// `Rtc` at all.
95 pub rtc_timer: RTC_TIMER<'a>,
96}
97
98/// The chip's two `FROM_CPU_INTRn` singletons the HAL leaves to applications,
99/// grouped so [`SystemResources`] stays a list of subsystems rather than a flat
100/// pile of peripherals. esp-hal reserves `FROM_CPU_INTR0` and `FROM_CPU_INTR1`
101/// for task switching and inter-core calls.
102///
103/// `InterruptExecutor::new` (hence `run_app_core`) takes either.
104pub struct SoftwareInterrupts<'a> {
105 pub intr2: FROM_CPU_INTR2<'a>,
106 pub intr3: FROM_CPU_INTR3<'a>,
107}