Logging

Logging

The firmware has a deferred, lock-free logger designed so that logging never blocks the USB timing-critical path. Producers on either core do almost nothing; the actual byte output happens later, on the owning core.

In a release build the whole thing is compiled out to zero cost (see below), so these notes are about the logging (default) build.

Pipeline

LOG_*(cat, ...)  →  orb_log front end  →  dlog SPSC ring (per core)
                                              │
                                    dlog_drain() on core0 (from the housekeep task)
                                              ├──→ debug UART (uart1)
                                              └──→ usb_log ring ──→ USB-stick LOG.TXT (core1, FatFs)

• Front end (orb_log.cpp): snapshots the timestamp + core id, runtime-gates on a per-category level table, renders one line [sec.frac][LEVEL][C#][CAT] msg, and publishes it with a single ring write (batch publish, drop-on-full — it never spins).
• Transport (dlog.cpp): one 16 KiB SPSC ring per core. core1's ring is a genuine single producer; core0's is multi-producer, so a write masks core0's own interrupts briefly (IrqGuard) — never a cross-core spinlock. core0 is the sole drainer of both rings (from the housekeep task).
• USB-stick sink (usb_log.cpp): strips ANSI color into a 32 KiB ring; core1 (which owns the USB host stack) does the FatFs append to LOG.TXT on the stick, f_sync'd ~1×/s.

Using it

Macros, gated at compile time by ORB_LOG_LEVEL (orb_log.h):

LOG_ERR(CAT_DEV,  "send failed: %d", rc);
LOG_WARN(CAT_RECOV, "controller silent");
LOG_INFO(CAT_SYS, "starting main process");
LOG_DBG(CAT_DRUM, "NOTE OFF: %d", lane);
LOG_TRC(CAT_WIRE, "...");
LOG_HEXDUMP(CAT_HOST, LOG_LEVEL_DEBUG, buf, len);

• Levels: NONE < ERROR < WARN < INFO < DEBUG < TRACE.
• Categories (CAT_SYS/HOST/DEV/DRUM/MIDI/RECOV/USBLOG/TUSB/WIRE) can be re-leveled at runtime via orb::log::set_cat_level(...).

Reading the output

• Debug UART — uart1, TX GPIO24 / RX GPIO25, 115200 baud. scripts/uart.sh reads the captured log (and applies color host-side).
• USB stick — plug a FAT drive into the hub; the log streams to LOG.TXT. Useful for tests away from the debug probe. A [USBLOG] stick mounted … line confirms it came up.

Build-time control

Option	Effect
ORB_DEBUG=OFF	Compiles logging out entirely. orb_debug.h forces the level floor to NONE, so every LOG_* expands to ((void)0) (args unevaluated) and magic_enum reflection is dropped. This is what the release preset ships.
ORB_LOG_LEVEL=<lvl>	Compile-time floor (default DEBUG; release uses WARN).
ORB_LOG_COLOR=ON	Bake ANSI color into the UART stream (default off; color is applied host-side instead).

See the build-time feature gates.