Skip to main content

m5stack_core/io/
console.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! Async buffered serial console for both targets — byte-level ring buffer
3//! with **overwrite-on-full** semantics. The producer (`log!()` / [`send_line`])
4//! is O(1) and NEVER blocks the caller: never spins, never awaits, never
5//! creates back-pressure. On full, the **oldest** bytes are overwritten so the
6//! lines fired *just before* a failure survive (those are the informative ones).
7//!
8//! A single [`drain_task`] pulls contiguous slices from the ring and writes
9//! them via the target's async TX sink (`write_all().await` parks on the
10//! TX-done IRQ when the FIFO is full — no busy-spin). Producers signal the
11//! drain after every write; the drain awaits the signal when the ring is empty.
12//!
13//! Per-target seam (hardware): the sink types + [`setup`] (build + split the
14//! peripheral) + [`imp::boot_panic_write`]. fire27 = UART0 @ 1 Mbaud; cores3 =
15//! USB-Serial-JTAG CDC. `setup` does NOT make the fire27 TX async — `into_async()`
16//! binds the IRQ to the *calling* core, so the binary does it from `main` (PRO).
17//!
18//! Data records (the firmware's `:cat` dump, CSV mirror) go through
19//! [`send_record`], whole and of any length up to the ring. Like [`send_line`]
20//! and unlike `log!()`, it is **back-pressuring**:
21//! it awaits ring space before writing, so a fast read-back self-paces to the TX
22//! drain rate. That is lossless only because the log path *sheds* rather than
23//! overwrites — reserving space does not protect bytes already queued, and while
24//! it did overwrite, a concurrent `log!()` cut dump records in half.
25
26use core::cell::{RefCell, UnsafeCell};
27use core::fmt::Write as _;
28use core::sync::atomic::{AtomicBool, AtomicU32, Ordering};
29
30use embassy_sync::blocking_mutex::Mutex as BlockingMutex;
31use embassy_sync::signal::Signal;
32#[cfg(feature = "console-serial")]
33use embedded_io_async::Write as _;
34use esp_hal::ram;
35use esp_hal::system::Cpu;
36use esp_sync::RawMutex;
37use heapless::String;
38
39use super::console_line::{self, LINE_CAP};
40use super::console_ring::{RING_SIZE, Ring};
41#[cfg(feature = "console-serial")]
42pub use super::console_tap::Tap;
43#[cfg(feature = "console-serial")]
44use super::console_tap::TapSlot;
45
46#[cfg(all(feature = "fire27", feature = "console-serial"))]
47mod imp {
48    use esp_hal::{
49        Async, Blocking,
50        gpio::AnyPin,
51        peripherals::UART0,
52        uart::{Config, Uart, UartRx, UartTx},
53    };
54
55    /// RX half → `serial_cmd`; TX (blocking) → made async by the binary at
56    /// drain-spawn (`into_async` binds the IRQ to the calling = PRO core).
57    pub type ConsoleRx<'d> = UartRx<'d, Blocking>;
58    pub type ConsoleTx<'d> = UartTx<'d, Blocking>;
59    /// The drain task's sink — the TX after the binary's `into_async()`.
60    pub type ConsoleTxAsync<'d> = UartTx<'d, Async>;
61
62    /// Build UART0 @ 1 Mbaud and split. Run early (before radio bring-up); HIL-
63    /// confirmed safe with the async console (see memory fire27-uart-async-corrected).
64    pub fn setup(
65        uart: UART0<'static>,
66        tx_pin: AnyPin<'static>,
67        rx_pin: AnyPin<'static>,
68    ) -> (ConsoleRx<'static>, ConsoleTx<'static>) {
69        Uart::new(uart, Config::default().with_baudrate(1_000_000))
70            .expect("UART0 console init")
71            .with_tx(tx_pin)
72            .with_rx(rx_pin)
73            .split()
74    }
75
76    /// The peripheral bundle [`super::install`] needs to bring the console up:
77    /// UART0 + its TX/RX pins (Fire27 console is UART0 @ 1 Mbaud).
78    pub struct SerialResources {
79        pub uart: UART0<'static>,
80        pub tx_pin: AnyPin<'static>,
81        pub rx_pin: AnyPin<'static>,
82    }
83
84    /// Build the console, returning the RX half (for `serial_cmd`) and the async
85    /// TX sink the drain task writes. `into_async()` binds the TX-done IRQ to the
86    /// calling core, so [`super::install`] must run on the core that owns the
87    /// drain task (main / PRO).
88    pub fn install_serial(res: SerialResources) -> (ConsoleRx<'static>, ConsoleTxAsync<'static>) {
89        let (rx, tx) = setup(res.uart, res.tx_pin, res.rx_pin);
90        (rx, tx.into_async())
91    }
92
93    // Raw UART0 TX-FIFO writer (panic only). Spins for FIFO room with a
94    // bounded budget per byte: the panic message MUST get out — a dropped
95    // [PANIC] line turns a clean panic into a silent "wedge" (cost a long
96    // stack-overflow hunt on cores3). The bound keeps a dead/unclocked UART
97    // from hanging the panic loop forever. Used by `on_panic` to synchronously
98    // flush the ring after the async drain is gone (or never started). NEVER
99    // call from steady-state code — `log!()` / `send_line` go through the ring.
100    const UART0_FIFO_REG: *mut u32 = 0x3FF4_0000 as *mut u32;
101    const UART0_STATUS_REG: *const u32 = 0x3FF4_001C as *const u32;
102    const TX_FIFO_DEPTH: u32 = 128;
103    /// ~a few ms at CPU speed — plenty for one byte at 1 Mbaud.
104    const PANIC_SPIN_PER_BYTE: u32 = 1_000_000;
105
106    pub fn boot_panic_write(bytes: &[u8]) {
107        for &b in bytes {
108            let mut budget = PANIC_SPIN_PER_BYTE;
109            while unsafe { (UART0_STATUS_REG.read_volatile() >> 16) & 0xFF } >= TX_FIFO_DEPTH - 2 {
110                budget -= 1;
111                if budget == 0 {
112                    return; // UART dead — give up rather than hang the panic
113                }
114                core::hint::spin_loop();
115            }
116            unsafe { UART0_FIFO_REG.write_volatile(b as u32) };
117        }
118    }
119}
120
121#[cfg(all(feature = "cores3", feature = "console-serial"))]
122mod imp {
123    use esp_hal::{
124        Async,
125        peripherals::USB_DEVICE,
126        usb::usb_serial_jtag::{UsbSerialJtag, UsbSerialJtagRx, UsbSerialJtagTx},
127    };
128
129    /// RX half → `serial_cmd` (async poller); TX half → the drain task.
130    pub type ConsoleRx<'d> = UsbSerialJtagRx<'d, Async>;
131    pub type ConsoleTx<'d> = UsbSerialJtagTx<'d, Async>;
132    /// The drain task's sink — the split TX is already async on cores3.
133    pub type ConsoleTxAsync<'d> = UsbSerialJtagTx<'d, Async>;
134
135    /// Build the USB-Serial-JTAG console and split. `into_async()` here binds the
136    /// IRQ to whatever core calls this — the binary calls it from main.
137    pub fn setup(usb: USB_DEVICE<'static>) -> (ConsoleRx<'static>, ConsoleTx<'static>) {
138        UsbSerialJtag::new(usb).into_async().split()
139    }
140
141    /// The peripheral bundle [`super::install`] needs: just the USB-Serial-JTAG
142    /// device (the CoreS3 console is the native CDC port — no probe needed, R7).
143    pub struct SerialResources {
144        pub usb: USB_DEVICE<'static>,
145    }
146
147    /// Build the console, returning the RX half (for `serial_cmd`) and the async
148    /// TX sink the drain task writes. The split TX is already async on CoreS3.
149    pub fn install_serial(res: SerialResources) -> (ConsoleRx<'static>, ConsoleTxAsync<'static>) {
150        setup(res.usb)
151    }
152
153    // Raw SERIAL_JTAG EP1 FIFO writer (panic only). Spins for FIFO room with
154    // a bounded budget per fill: the panic message MUST get out — the old
155    // drop-on-full policy lost the [PANIC] line whenever the ring held more
156    // than one 64-byte EP buffer of pre-panic context, turning every panic
157    // into a silent "wedge" (cost a long stack-overflow hunt). The bound
158    // keeps an unplugged USB host from hanging the panic loop forever.
159    const SERIAL_JTAG_FIFO_REG: *mut u32 = 0x6003_8000 as *mut u32;
160    const SERIAL_JTAG_CONF_REG: *mut u32 = 0x6003_8004 as *mut u32;
161    /// ~tens of ms at CPU speed — the host polls the 64-byte EP every USB
162    /// micro-frame, so a live host clears the FIFO well within this.
163    const PANIC_SPIN_PER_FILL: u32 = 5_000_000;
164
165    #[inline]
166    fn fifo_full() -> bool {
167        unsafe { SERIAL_JTAG_CONF_REG.read_volatile() & 0b010 == 0 }
168    }
169
170    pub fn boot_panic_write(bytes: &[u8]) {
171        for &b in bytes {
172            if fifo_full() {
173                // Hand the queued bytes to the host, then wait (bounded) for
174                // room. No host within the budget → give up, don't hang.
175                unsafe { SERIAL_JTAG_CONF_REG.write_volatile(0b001) }; // flush (wr_done)
176                let mut budget = PANIC_SPIN_PER_FILL;
177                while fifo_full() {
178                    budget -= 1;
179                    if budget == 0 {
180                        return;
181                    }
182                    core::hint::spin_loop();
183                }
184            }
185            unsafe { SERIAL_JTAG_FIFO_REG.write_volatile(b as u32) };
186        }
187        unsafe { SERIAL_JTAG_CONF_REG.write_volatile(0b001) }; // flush (wr_done)
188    }
189}
190
191#[cfg(feature = "console-serial")]
192pub use imp::{ConsoleRx, ConsoleTx, ConsoleTxAsync, SerialResources, setup};
193#[cfg(feature = "console-serial")]
194use imp::{boot_panic_write, install_serial};
195
196/// Serial-free build (R9): the transport is compiled out, so this type is
197/// uninhabited and [`Config::serial`] can only ever be `None`.
198#[cfg(not(feature = "console-serial"))]
199pub enum SerialResources {}
200
201// ---- byte-level ring buffer (target-agnostic) ----
202
203/// The ring + its own lock so any task on any core can write safely. Lock
204/// scope is per-op (at most two memcpys + a few indices) — never held across an
205/// `.await`, never spans more than one record. Not the global critical
206/// section: a console write must not stall the other core's unrelated work.
207static RING: BlockingMutex<RawMutex, RefCell<Ring>> = BlockingMutex::new(RefCell::new(Ring::new()));
208
209/// The registered second reader of what the drain writes.
210#[cfg(feature = "console-serial")]
211static TAP: TapSlot<RawMutex> = TapSlot::new();
212
213/// Registers `tap` to receive everything the drain writes to the transmitter,
214/// from the drain's next read on. Bytes the drain wrote before are not replayed.
215#[cfg(feature = "console-serial")]
216pub fn set_tap(tap: &'static dyn Tap) {
217    TAP.set(tap);
218}
219
220/// Producer signal — woken after every ring write so the drain can resume
221/// when the ring was empty. Idempotent (multiple signals before a wait =
222/// one wait wakes); the drain reads everything it can per wakeup.
223static DRAIN_SIGNAL: Signal<RawMutex, ()> = Signal::new();
224
225/// Drain → producer signal — raised after every drain read so a *back-pressuring*
226/// producer ([`send_line`], the HIL `:cat` dump) can wake and retry once the ring
227/// has freed space. The non-blocking hot log path ([`push_line`]) ignores it.
228static SPACE_SIGNAL: Signal<RawMutex, ()> = Signal::new();
229
230// ---- per-context line buffers: no line is ever on a caller's stack ----
231
232/// A buffer one context at a time may hold. A logger call reaches every stack
233/// on the board, interrupt handlers' included, so a line held there costs each
234/// of them [`LINE_CAP`]; these buffers are static instead.
235struct Claimed<T> {
236    /// Set by the context holding `buf`. Found set: a `Display` that logs, or a
237    /// higher interrupt level preempting one that holds it.
238    busy: AtomicBool,
239    buf: UnsafeCell<T>,
240}
241
242// SAFETY: `buf` is only touched by the context that set `busy`.
243unsafe impl<T: Send> Sync for Claimed<T> {}
244
245impl<T> Claimed<T> {
246    const fn new(buf: T) -> Self {
247        Self {
248            busy: AtomicBool::new(false),
249            buf: UnsafeCell::new(buf),
250        }
251    }
252
253    /// `f` on the buffer, or `None` if another context holds it.
254    fn with<R>(&self, f: impl FnOnce(&mut T) -> R) -> Option<R> {
255        if self.busy.swap(true, Ordering::Acquire) {
256            return None;
257        }
258        // SAFETY: `busy` was clear, so no other context holds the buffer.
259        let r = f(unsafe { &mut *self.buf.get() });
260        self.busy.store(false, Ordering::Release);
261        Some(r)
262    }
263}
264
265/// One context's line, formatted before it is copied into the ring.
266type Slot = Claimed<String<LINE_CAP>>;
267
268/// Thread context and level-1 handlers: one line per core, because a thread
269/// masks level 1 while it formats, so neither can take the line from the other.
270static LOW: [Slot; Cpu::COUNT] = [const { Slot::new(String::new()) }; Cpu::COUNT];
271/// Every higher level, a critical section's included: a level that preempts
272/// one formatting here finds the line taken.
273static HIGH: [Slot; Cpu::COUNT] = [const { Slot::new(String::new()) }; Cpu::COUNT];
274
275/// Written in place of a line whose context found its buffer taken.
276pub const NESTED_MARK: &str = "[CONSOLE-NESTED]\r\n";
277static NESTED: AtomicU32 = AtomicU32::new(0);
278
279/// Lines replaced by [`NESTED_MARK`] since boot.
280pub fn nested_lines() -> u32 {
281    NESTED.load(Ordering::Relaxed)
282}
283
284/// `f` on the calling context's line buffer, or `None` if it is taken.
285fn with_line<R>(f: impl FnOnce(&mut String<LINE_CAP>) -> R) -> Option<R> {
286    let core = Cpu::current() as usize;
287    let ps: u32;
288    // SAFETY: reads PS, touches no memory.
289    unsafe { core::arch::asm!("rsr.ps {0}", out(reg) ps, options(nomem, nostack)) };
290    match ps & 0xF {
291        0 => {
292            let saved: u32;
293            // SAFETY: raises the level to 1 and restores PS as it was: no
294            // task switch and no level-1 handler while this thread formats.
295            unsafe { core::arch::asm!("rsil {0}, 1", out(reg) saved, options(nomem, nostack)) };
296            let r = LOW[core].with(f);
297            unsafe {
298                core::arch::asm!("wsr.ps {0}", "rsync", in(reg) saved, options(nomem, nostack))
299            };
300            r
301        }
302        1 => LOW[core].with(f),
303        _ => HIGH[core].with(f),
304    }
305}
306
307/// Format + push a line into the ring, signal the drain. O(1) on the caller
308/// side: brief CS for the memcpy + an idempotent signal. **Non-blocking** —
309/// on full the oldest bytes are overwritten (protects time-critical producers).
310fn push_line(level: &str, args: core::fmt::Arguments<'_>) {
311    let now = embassy_time::Instant::now();
312    let pushed = with_line(|line| {
313        console_line::format_into(line, now.as_secs(), now.as_millis(), level, args);
314        RING.lock(|r| r.borrow_mut().write_line(line.as_bytes()));
315    });
316    if pushed.is_none() {
317        NESTED.fetch_add(1, Ordering::Relaxed);
318        RING.lock(|r| r.borrow_mut().write_line(NESTED_MARK.as_bytes()));
319    }
320    DRAIN_SIGNAL.signal(());
321}
322
323struct ConsoleLogger;
324
325/// Filter spec supplied by the application at [`init`] — the console is the
326/// `log` backend and implements the mechanism, the app owns the policy.
327/// `env_logger` syntax: `info,sdspi=debug`; the longest matching
328/// `target=level` directive wins, a bare level is the default.
329///
330/// Held as a raw pointer pair, not behind a mutex: `enabled` runs on EVERY
331/// log macro that passes `log`'s own atomic gate, and taking a critical
332/// section there to read a `&'static str` would cost more than the filtering.
333/// Written once in `init` before any task logs; reads are relaxed and see
334/// either null (pre-init, treated as the default) or the final value.
335static SPEC_PTR: core::sync::atomic::AtomicUsize = core::sync::atomic::AtomicUsize::new(0);
336static SPEC_LEN: core::sync::atomic::AtomicUsize = core::sync::atomic::AtomicUsize::new(0);
337/// Level of the spec's bare directive — the common case, answered without
338/// touching the spec string at all.
339static DEFAULT_LEVEL: core::sync::atomic::AtomicU8 = core::sync::atomic::AtomicU8::new(3);
340/// Whether any `target=level` directive exists. When none do (production
341/// `"info"`), `enabled` is one relaxed load and a compare, as it was before
342/// per-module filtering existed.
343static HAS_DIRECTIVES: core::sync::atomic::AtomicBool = core::sync::atomic::AtomicBool::new(false);
344
345fn spec() -> &'static str {
346    use core::sync::atomic::Ordering::Relaxed;
347    let ptr = SPEC_PTR.load(Relaxed) as *const u8;
348    if ptr.is_null() {
349        return "info";
350    }
351    // SAFETY: written once in `init` from a `&'static str`; never mutated.
352    unsafe {
353        core::str::from_utf8_unchecked(core::slice::from_raw_parts(ptr, SPEC_LEN.load(Relaxed)))
354    }
355}
356
357fn level_from_u8(v: u8) -> log::LevelFilter {
358    match v {
359        0 => log::LevelFilter::Off,
360        1 => log::LevelFilter::Error,
361        2 => log::LevelFilter::Warn,
362        3 => log::LevelFilter::Info,
363        4 => log::LevelFilter::Debug,
364        _ => log::LevelFilter::Trace,
365    }
366}
367
368fn level_of(s: &str) -> Option<log::LevelFilter> {
369    match s.as_bytes() {
370        b"off" => Some(log::LevelFilter::Off),
371        b"error" => Some(log::LevelFilter::Error),
372        b"warn" => Some(log::LevelFilter::Warn),
373        b"info" => Some(log::LevelFilter::Info),
374        b"debug" => Some(log::LevelFilter::Debug),
375        b"trace" => Some(log::LevelFilter::Trace),
376        _ => None,
377    }
378}
379
380fn filter_for(target: &str) -> log::LevelFilter {
381    let spec = spec();
382    let mut best = log::LevelFilter::Info;
383    let mut best_len = 0;
384    for directive in spec.split(',') {
385        match directive.split_once('=') {
386            None => {
387                if best_len == 0 {
388                    best = level_of(directive.trim()).unwrap_or(log::LevelFilter::Info);
389                }
390            }
391            Some((prefix, level)) => {
392                let prefix = prefix.trim();
393                if target.starts_with(prefix)
394                    && prefix.len() > best_len
395                    && let Some(l) = level_of(level.trim())
396                {
397                    best = l;
398                    best_len = prefix.len();
399                }
400            }
401        }
402    }
403    best
404}
405
406impl log::Log for ConsoleLogger {
407    fn enabled(&self, meta: &log::Metadata) -> bool {
408        use core::sync::atomic::Ordering::Relaxed;
409        // Fast path, and the only one production takes: anything at or above
410        // the default level passes without looking at the spec.
411        if meta.level() <= level_from_u8(DEFAULT_LEVEL.load(Relaxed)) {
412            return true;
413        }
414        // Below the default, and no per-target directive can raise it.
415        if !HAS_DIRECTIVES.load(Relaxed) {
416            return false;
417        }
418        meta.level() <= filter_for(meta.target())
419    }
420
421    fn log(&self, record: &log::Record) {
422        if !self.enabled(record.metadata()) {
423            return;
424        }
425        // Format level as a string so the column width matches the prior layout
426        // exactly (existing log scrapers depend on it).
427        let lvl = match record.level() {
428            log::Level::Error => "ERROR",
429            log::Level::Warn => "WARN ",
430            log::Level::Info => "INFO ",
431            log::Level::Debug => "DEBUG",
432            log::Level::Trace => "TRACE",
433        };
434        push_line(lvl, *record.args());
435    }
436
437    fn flush(&self) {}
438}
439
440static LOGGER: ConsoleLogger = ConsoleLogger;
441
442/// Register the console as the global `log` backend. Call once, early. The
443/// ring is statically initialised, so producers can write immediately —
444/// pre-[`drain_task`] writes simply accumulate in the ring and are flushed
445/// once the drain runs.
446/// `spec` is an `env_logger`-style filter (`info,sdspi=debug`), typically the
447/// app's `ESP_LOG` read at the APP's compile time — the console previously
448/// hardcoded Info here, which silently discarded every `module=debug`
449/// directive from the day esp-println (whose logger parsed `ESP_LOG`) was
450/// dropped.
451pub fn init(spec: &'static str) {
452    use core::sync::atomic::Ordering::Relaxed;
453    SPEC_LEN.store(spec.len(), Relaxed);
454    SPEC_PTR.store(spec.as_ptr() as usize, Relaxed);
455    let mut default = log::LevelFilter::Info;
456    let mut directives = false;
457    for directive in spec.split(',') {
458        match directive.split_once('=') {
459            None => default = level_of(directive.trim()).unwrap_or(default),
460            Some(_) => directives = true,
461        }
462    }
463    DEFAULT_LEVEL.store(default as u8, Relaxed);
464    HAS_DIRECTIVES.store(directives, Relaxed);
465    // Global gate = the most verbose level any directive asks for; per-target
466    // narrowing happens in `enabled`.
467    let mut max = log::LevelFilter::Info;
468    for directive in spec.split(',') {
469        let level = directive
470            .split_once('=')
471            .map(|(_, l)| l)
472            .unwrap_or(directive);
473        if let Some(l) = level_of(level.trim())
474            && l > max
475        {
476            max = l;
477        }
478    }
479    let _ = log::set_logger(&LOGGER);
480    log::set_max_level(max);
481    // Liveness self-test: one debug!-level line, enabled by a directive in the
482    // HIL builds' filter spec. The debug channel was once dead for 11 weeks
483    // with nothing anywhere failing; the harness asserts this marker at boot,
484    // so a dead filter now fails every HIL run instead of no test ever.
485    log::debug!("{} spec={}", markers::DBG_SELFTEST, spec);
486}
487
488/// Stable, greppable log markers that the HIL `detect_crash` contract keys on.
489/// Treat these as part of the public contract — do not reword without updating
490/// the test harness.
491pub mod markers {
492    /// Emitted by [`super::on_panic`] before halt.
493    pub const PANIC: &str = "[PANIC]";
494    /// Emitted at `debug!` level by [`super::init`] — proves the level filter
495    /// passes debug when a directive asks for it. HIL asserts it at boot.
496    pub const DBG_SELFTEST: &str = "[dbg-selftest]";
497    /// Prefix of the drain's ring-overrun marker (` <n>B]` follows).
498    pub const CONSOLE_DROP: &str = "[CONSOLE-DROP";
499    /// Prefix of the drain's shed-line marker (` <n>B]` follows). Distinct from
500    /// [`CONSOLE_DROP`] on purpose: a shed line is bounded, intended loss, while
501    /// an overwrite means a queued record was cut. A gate should treat them
502    /// differently, and one literal for both makes that impossible.
503    ///
504    /// The split exists because the alternative was tried: the counter was kept
505    /// shared so downstream greps would not break, and that stability is exactly
506    /// what moved the meaning of `[CONSOLE-DROP` underneath a consumer's gate
507    /// without changing a byte of the string it matched. Stability of a name is
508    /// not stability of a contract — when what a marker asserts changes, the
509    /// marker has to change with it.
510    pub const CONSOLE_SHED: &str = "[CONSOLE-SHED";
511    /// Ends a log line cut at the line buffer (see [`super::console_line`]).
512    /// The kept part is real; what followed it is gone.
513    pub const CONSOLE_TRUNC: &str = "[CONSOLE-TRUNC]";
514    /// Logged once at boot when a previous-run panic breadcrumb is read back.
515    pub const PREV_PANIC: &str = "[bc] previous panic";
516    /// Logged once at boot by [`super::install`] (the `app-desc` feature) —
517    /// project name, version (or the `identity`-enforced git mark), and an
518    /// `app_elf_sha256` prefix.
519    pub const IDENTITY: &str = "identity:";
520}
521
522/// Console install configuration. `serial: None` is the production backstop —
523/// the log backend is registered (so `log!` is a cheap no-op into the ring) but
524/// no transport is brought up and no drain task runs, leaving zero serial
525/// surface. `Some(_)` brings up the chip's native transport (UART0 on Fire27,
526/// USB-Serial-JTAG CDC on CoreS3) and spawns the drain.
527pub struct Config {
528    /// The chip's serial peripheral bundle, or `None` for a serial-free build.
529    pub serial: Option<SerialResources>,
530    /// `env_logger`-style filter spec (`info,module=debug`) — the app's
531    /// policy, typically its `ESP_LOG` read at the app's compile time.
532    pub filter: &'static str,
533}
534
535/// What [`install`] hands back: the console RX half, when a transport was
536/// brought up, to be handed to `serial_cmd` (bidirectional on one port, R7).
537/// In a serial-free build (`console-serial` off, R9) it carries no transport.
538pub struct Console {
539    /// `Some` iff `Config::serial` was `Some`. Hand to the serial-command reader.
540    #[cfg(feature = "console-serial")]
541    pub rx: Option<ConsoleRx<'static>>,
542}
543
544/// One-call console bring-up: register the `log` backend with `cfg.filter` and,
545/// when `cfg.serial` is `Some`, build the chip's transport + spawn the single
546/// [`drain_task`]. Replaces the hand-wired `init()` + `setup()` + drain-spawn
547/// sequence in every binary. Call once from main (the core that owns the drain;
548/// Fire27's TX `into_async()` binds the IRQ to the calling core).
549///
550/// Returns a [`Console`] whose `rx` (when present) goes to the serial-command
551/// reader so log TX and command RX share the one port (R7).
552pub fn install(spawner: embassy_executor::Spawner, cfg: Config) -> Console {
553    init(cfg.filter);
554    let console = {
555        #[cfg(feature = "console-serial")]
556        {
557            let rx = cfg.serial.map(|res| {
558                let (rx, tx) = install_serial(res);
559                crate::must_spawn!(spawner, drain_task(tx));
560                rx
561            });
562            Console { rx }
563        }
564        // R9 serial-free: backend registered above; no transport, no drain task.
565        #[cfg(not(feature = "console-serial"))]
566        {
567            let _ = &spawner;
568            // SerialResources is uninhabited here.
569            if let Some(res) = cfg.serial {
570                match res {}
571            }
572            Console {}
573        }
574    };
575    // As early as possible: the first BSP-emitted log line, right after the
576    // backend (and transport, if any) are up. See markers::IDENTITY.
577    #[cfg(feature = "app-desc")]
578    crate::log_boot_identity();
579    console
580}
581
582/// Compatibility no-op. The prior design switched producers from a blocking
583/// writer to an async queue here; with the ring buffer the producer path is
584/// the same in every phase (boot and steady-state both write to the ring),
585/// so there's nothing to switch. Kept so binaries don't have to change in
586/// this commit — can be removed once both binaries stop calling it.
587pub fn enable_async() {}
588
589/// Back-pressuring line sink — the **R10 injection point**. A control crate must
590/// not depend on this BSP directly; instead it defines its own `LineSink`-style
591/// trait and the *binary* injects a ~5-line newtype whose `send_line` forwards
592/// here (the trait stays consumer-side, so neither BSP nor control crate depends
593/// on the other). This is also the bulk-dump path for the HIL `:cat` CSV.
594///
595/// Bulk-dump emit (HIL `:cat` CSV read-back) — **back-pressuring**. AWAITS
596/// until the ring has room for the whole line before writing, then signals the
597/// drain, so a fast `:cat` dump self-paces to the TX drain rate instead of
598/// overflowing the ~4 KB ring. Safe because the dump runs on a non-time-critical
599/// task and can tolerate await latency; the `log!()` path does NOT use this.
600///
601/// Lossless against concurrent logging, but only because [`Ring::write_line`]
602/// sheds a line that does not fit rather than overwriting the oldest. Reserving
603/// space is not on its own enough: the reservation covers the moment of writing,
604/// and these bytes are then the *oldest* in the ring, so an overwriting producer
605/// destroys them first. That cut `:cat` lines in half on fire27, where 1 Mbaud
606/// UART0 drains slower than the hot path fills. A panic still overwrites, by
607/// design.
608pub async fn send_line(args: core::fmt::Arguments<'_>) {
609    let now = embassy_time::Instant::now();
610    loop {
611        // Formatted afresh on each try, so no line waits in this future. Only a
612        // WHOLE line is written — a partial write would still overwrite-on-full
613        // and corrupt the dump. LINE_CAP < RING_SIZE, so it always fits once
614        // the drain has caught up.
615        let wrote = with_line(|line| {
616            console_line::format_into(line, now.as_secs(), now.as_millis(), "INFO ", args);
617            RING.lock(|r| {
618                let mut r = r.borrow_mut();
619                let fits = r.free() >= line.len();
620                if fits {
621                    r.write(line.as_bytes());
622                }
623                fits
624            })
625        });
626        match wrote {
627            Some(true) => {
628                DRAIN_SIGNAL.signal(());
629                return;
630            }
631            // A task cannot preempt itself, so only a re-entrant `Display`
632            // finds the line taken; the line is lost, and says so.
633            None => {
634                NESTED.fetch_add(1, Ordering::Relaxed);
635                RING.lock(|r| r.borrow_mut().write_line(NESTED_MARK.as_bytes()));
636                DRAIN_SIGNAL.signal(());
637                return;
638            }
639            Some(false) => {}
640        }
641        // Ring full — wait for the drain to free space, then retry. (No lost
642        // wakeup: SPACE_SIGNAL latches, so a signal between the check above and
643        // this wait still wakes us.)
644        SPACE_SIGNAL.wait().await;
645    }
646}
647
648/// Why [`send_record`] refused a record. Nothing was written.
649#[derive(Clone, Copy, Debug, PartialEq, Eq)]
650pub enum RecordError {
651    /// Header + text + CRLF exceed the ring, so it could never fit whole.
652    TooLong(usize),
653    /// The text holds a CR or LF and would read as several lines.
654    LineBreak,
655}
656
657/// One whole line of any length up to the ring, back-pressured like
658/// [`send_line`]: for data records (CSV rows, file dumps) that must arrive
659/// complete. No line buffer — header, `text` and CRLF go into the ring in one
660/// critical section once there is room for all of it, so no other line can
661/// land inside the record and nothing is truncated.
662pub async fn send_record(text: &str) -> Result<(), RecordError> {
663    if text.bytes().any(|b| b == b'\r' || b == b'\n') {
664        return Err(RecordError::LineBreak);
665    }
666    let now = embassy_time::Instant::now();
667    // The header is rebuilt for each try, so no copy of it waits in this future.
668    let head = || console_line::header(now.as_secs(), now.as_millis(), "INFO ");
669    let len = head().len() + text.len() + 2;
670    if len > RING_SIZE {
671        return Err(RecordError::TooLong(len));
672    }
673    loop {
674        let wrote = {
675            let head = head();
676            RING.lock(|r| {
677                let mut r = r.borrow_mut();
678                if r.free() >= len {
679                    r.write(head.as_bytes());
680                    r.write(text.as_bytes());
681                    r.write(b"\r\n");
682                    true
683                } else {
684                    false
685                }
686            })
687        };
688        if wrote {
689            DRAIN_SIGNAL.signal(());
690            return Ok(());
691        }
692        // As in `send_line`: SPACE_SIGNAL latches, so no lost wakeup.
693        SPACE_SIGNAL.wait().await;
694    }
695}
696
697/// The single console writer: pulls contiguous slices from the ring and
698/// writes them via the target's async TX sink. `write_all().await` parks on
699/// the TX-done IRQ when the FIFO is full — no spin, no interrupts-off, no
700/// cross-core contention. When the ring is empty, awaits [`DRAIN_SIGNAL`]
701/// (woken by every producer write). Spawn once from the binary's main
702/// (fire27: pass `tx.into_async()`; cores3: the split TX is already async).
703#[cfg(feature = "console-serial")]
704#[embassy_executor::task]
705pub async fn drain_task(mut tx: ConsoleTxAsync<'static>) {
706    // Per-iteration scratch. 256 B on the task stack is fine; the loop runs
707    // again immediately to drain whatever didn't fit.
708    let mut scratch = [0u8; 256];
709    // Overflow-marker rate-limit state (see below).
710    let mut drop_accum: u32 = 0;
711    let mut shed_accum: u32 = 0;
712    // Markers bypass the ring so they cannot themselves be overwritten, but that
713    // put them at an arbitrary CHUNK boundary — which splices them through a
714    // record that spans two chunks. Every byte survives, yet a reader sees a
715    // truncated line and an orphan tail. Emit only when TX is at a line start.
716    let mut at_line_start = true;
717    let mut last_drop_report = embassy_time::Instant::now();
718    loop {
719        // In one lock: a shed gap the reader has reached, the next slice (which
720        // stops at the following gap), and any overwrite count.
721        let (n, dropped, shed) = RING.lock(|r| {
722            let mut r = r.borrow_mut();
723            let shed = r.take_shed();
724            let n = r.read_and_consume(&mut scratch);
725            (n, r.take_dropped(), shed)
726        });
727        drop_accum = drop_accum.saturating_add(dropped);
728        shed_accum = shed_accum.saturating_add(shed);
729        // Surface a ring overrun as a LOUD, greppable marker so dropped bytes
730        // never masquerade as a clean gap (the silent loss that made
731        // `log_interval`'s read-back fail; host can grep `[CONSOLE-DROP`).
732        //
733        // RATE-LIMITED + coalesced: the marker is written by the drain straight
734        // to TX (bypassing the ring, so it costs no ring space and can't itself
735        // be overwritten), but it still shares TX bandwidth + drain time with
736        // the data it's preserving. Emitting it every 256-B chunk under a
737        // sustained log storm would steal drain throughput and AMPLIFY the
738        // overrun (more drops → more markers → slower drain). So emit at most
739        // ~4×/s with the accumulated byte count, plus an immediate flush the
740        // moment the ring drains (episode end). Never blocks/back-pressures
741        // producers — it only delays the drain slightly, now bounded.
742        if drop_accum > 0 && at_line_start {
743            let now = embassy_time::Instant::now();
744            if n == 0 || (now - last_drop_report).as_millis() >= 250 {
745                let mut mark: String<48> = String::new();
746                let _ = write!(mark, "\r\n[CONSOLE-DROP {}B]\r\n", drop_accum);
747                TAP.feed(mark.as_bytes());
748                let _ = tx.write_all(mark.as_bytes()).await;
749                drop_accum = 0;
750                last_drop_report = now;
751            }
752        }
753        // Shed lines get their OWN literal: bounded, intended loss, not an
754        // overwrite. Not rate-limited: the ring hands it over at the gap, one per
755        // shed episode, and delaying it would print it past the loss it marks.
756        if shed_accum > 0 && at_line_start {
757            let mut mark: String<48> = String::new();
758            let _ = write!(mark, "\r\n[CONSOLE-SHED {}B]\r\n", shed_accum);
759            TAP.feed(mark.as_bytes());
760            let _ = tx.write_all(mark.as_bytes()).await;
761            shed_accum = 0;
762        }
763        if n == 0 {
764            DRAIN_SIGNAL.wait().await;
765            continue;
766        }
767        // Freed `n` bytes — wake any back-pressuring producer (the :cat dump).
768        SPACE_SIGNAL.signal(());
769        // Write outside the lock — `.await` is NEVER inside the ring CS.
770        at_line_start = scratch[n - 1] == b'\n';
771        TAP.feed(&scratch[..n]);
772        let _ = tx.write_all(&scratch[..n]).await;
773    }
774}
775
776// ---- RTC-persistent panic breadcrumb (R8) ----
777
778/// Marks a written crumb, distinguishing a real breadcrumb from uninitialised
779/// RTC RAM after a cold boot / power cycle.
780const CRUMB_MAGIC: u32 = 0x6D35_C0DE;
781
782// Breadcrumb word layout in the RTC-fast persistent array.
783const CRUMB_MAGIC_IDX: usize = 0;
784const CRUMB_REASON_IDX: usize = 1;
785const CRUMB_FILE_PTR_IDX: usize = 2;
786const CRUMB_FILE_LEN_IDX: usize = 3;
787
788/// Breadcrumb in RTC-fast RAM as `[magic, reason, file_ptr, file_len]`.
789/// `#[ram(unstable(rtc_fast, persistent))]` keeps it out of the data-init that
790/// runs on a watchdog/software reset, so it survives the RWDT recovery that
791/// follows a panic — exactly the window R8 needs. A `[u32; 4]` (not a struct)
792/// because esp-hal's persistent section requires `Persistable`, which is
793/// implemented for primitive arrays; `usize` is 32-bit on these chips, so the
794/// `.rodata` file-`&str` pointer + length fit in a `u32` each. The pointer is
795/// valid to reconstruct because the crumb only survives a *warm* reset of the
796/// *same* firmware image.
797#[ram(unstable(rtc_fast, persistent))]
798static mut PANIC_CRUMB: [u32; 4] = [0; 4];
799
800/// A panic breadcrumb recovered from the previous run: `location` is the panic
801/// file, `reason` a 32-bit digest of the panic message.
802pub struct PanicCrumb {
803    pub location: &'static str,
804    pub reason: u32,
805}
806
807/// FNV-1a 32-bit digest of the panic message — the R8 "reason-digest".
808fn reason_digest(s: &str) -> u32 {
809    let mut h: u32 = 0x811c_9dc5;
810    for &b in s.as_bytes() {
811        h ^= b as u32;
812        h = h.wrapping_mul(0x0100_0193);
813    }
814    h
815}
816
817/// Record the panic breadcrumb (file location + message digest) in
818/// RTC-persistent RAM before halting. Called by [`on_panic`].
819fn write_panic_crumb(info: &core::panic::PanicInfo<'_>, msg: &str) {
820    let (file_ptr, file_len) = info
821        .location()
822        .map(|l| (l.file().as_ptr() as usize, l.file().len()))
823        .unwrap_or((0, 0));
824    let mut crumb = [0u32; 4];
825    crumb[CRUMB_MAGIC_IDX] = CRUMB_MAGIC;
826    crumb[CRUMB_REASON_IDX] = reason_digest(msg);
827    crumb[CRUMB_FILE_PTR_IDX] = file_ptr as u32;
828    crumb[CRUMB_FILE_LEN_IDX] = file_len as u32;
829    // SAFETY: panic context is single-threaded and terminal; the only other
830    // access is `take_panic_breadcrumb` at boot before any task runs.
831    unsafe { core::ptr::addr_of_mut!(PANIC_CRUMB).write(crumb) };
832}
833
834/// Read and clear the previous run's panic breadcrumb, if any. Call **once** at
835/// boot, before [`install`], and log the result (the [`markers::PREV_PANIC`]
836/// line) — that read-back is the cross-transport fault contract (R8), identical
837/// on both targets. Returns `None` on a clean boot or once the crumb is taken.
838pub fn take_panic_breadcrumb() -> Option<PanicCrumb> {
839    // SAFETY: called once at boot before any task runs — no concurrent access.
840    unsafe {
841        let ptr = core::ptr::addr_of_mut!(PANIC_CRUMB);
842        let c = ptr.read();
843        if c[CRUMB_MAGIC_IDX] != CRUMB_MAGIC {
844            return None;
845        }
846        (*ptr)[CRUMB_MAGIC_IDX] = 0; // clear in place → reported exactly once
847        let file_ptr = c[CRUMB_FILE_PTR_IDX] as usize;
848        let location = if file_ptr != 0 {
849            core::str::from_utf8_unchecked(core::slice::from_raw_parts(
850                file_ptr as *const u8,
851                c[CRUMB_FILE_LEN_IDX] as usize,
852            ))
853        } else {
854            "?"
855        };
856        Some(PanicCrumb {
857            location,
858            reason: c[CRUMB_REASON_IDX],
859        })
860    }
861}
862
863/// Shared message-only panic handler for both targets. Pushes the panic info
864/// into the ring (alongside the pre-panic context that's already there), then
865/// **synchronously drains the ring** via the raw FIFO poker — the async drain
866/// task is gone (or never started) so it can't service the ring for us. After
867/// the drain, halts so the fault stays visible. No stack walk: message-only
868/// on both targets (deliberate, symmetric), which is why neither `esp-backtrace`
869/// nor `esp-println` is pulled in. The binary's `#[panic_handler]` is a
870/// one-line wrapper around this.
871pub fn on_panic(info: &core::panic::PanicInfo<'_>) -> ! {
872    // Push the panic into the ring. Producer-side is unchanged from any
873    // normal log: brief CS, no await.
874    // The first panic owns the line and the breadcrumb. A second, on the other
875    // core or raised inside the first one's formatting, keeps both and only
876    // helps drain.
877    let _ = PANIC_LINE.with(|line| {
878        line.clear();
879        let _ = write!(line, "\r\n[PANIC] {}\r\n", info);
880        // R8: record the breadcrumb (location + message digest) in RTC-persistent
881        // RAM BEFORE any best-effort transport print — the crumb is the contract; a
882        // CDC/UART flush that can't complete post-halt must not gate it.
883        write_panic_crumb(info, line.as_str());
884        RING.lock(|r| r.borrow_mut().write(line.as_bytes()));
885    });
886
887    // Best-effort transport print: synchronously drain the ring via
888    // `boot_panic_write` (the async drain task is gone/never-started). It emits
889    // no `[CONSOLE-DROP`: the marker comes from that task, which is dead here.
890    // So the overwrite above is invisible downstream, and the marker stays a
891    // pure defect signal — it cannot be produced by the one path allowed to
892    // overwrite. Compiled
893    // out in a serial-free build (R9) — the RTC breadcrumb above is the contract;
894    // here we just halt and let the RWDT recover.
895    #[cfg(feature = "console-serial")]
896    let _ = PANIC_CHUNK.with(|chunk| {
897        loop {
898            let n = RING.lock(|r| r.borrow_mut().read_and_consume(chunk));
899            if n == 0 {
900                break;
901            }
902            boot_panic_write(&chunk[..n]);
903        }
904    });
905    halt()
906}
907
908/// The panic's line: never on the panicking stack.
909static PANIC_LINE: Slot = Slot::new(String::new());
910/// The panic drain's chunk, apart from the line so a nested panic can drain.
911#[cfg(feature = "console-serial")]
912static PANIC_CHUNK: Claimed<[u8; 64]> = Claimed::new([0; 64]);
913
914fn halt() -> ! {
915    loop {
916        core::sync::atomic::compiler_fence(core::sync::atomic::Ordering::SeqCst);
917    }
918}