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}