//! pardes, as ESP32-P4 firmware: the reset entry, the heap, the clock, the trap handler and the //! loop. //! //! There is no operating system under this. `_start` is the reset entry the second-stage bootloader //! jumps to, and this file is the entire platform: a heap, a millisecond clock, and UART0. //! //! ## Why the firmware root is in the editor's repository //! //! It was written in the `05-zig-p4` toolchain repository, next to the SoC support it uses, and it //! moved here because everything in it is a statement about the EDITOR. The heap span it hands over //! is the number that decides how large a grid the board can drive; `input_chunk` is sized against //! what applying one keystroke costs in `src/pardes.zig`; the loop's shape - read, chunk, tick, //! render only when dirty - is this editor's loop and no one else's; and the `-Dprof` attribution //! exists to answer "where did the 34 ms of a keystroke go" about this program. A firmware root that //! specific to one application belongs beside it. //! //! What stayed behind is everything a second application would also want, and none of it is //! duplicated here: the SoC and HAL, the translate-c register layer, the coalescing heap, `std.Io` //! for this chip, the app descriptor, the generated linker script, the image builder, the flasher //! and the interactive console. The sibling `05-zig-p4` build supplies them; this file imports //! exactly four of its modules - `soc`, `hal`, `heap` and `config` - plus two sibling files, //! `uart.zig` and `input_rescue.zig`, which are the editor's own. //! //! ## Where the editor is //! //! On the far side of a C ABI, still, and that is a choice rather than a leftover. `src/esp32p4.zig` in //! this same repository is compiled as ONE freestanding object (`b.addObject`, rooted at that file) //! and linked in beside this one; the `extern` declarations below are the near side of that seam. //! //! Importing `esp32p4.zig` as a module instead would be shorter to write and worse in every way that //! matters. It would drag the core's whole module graph - vaxis, the themes, the allocator tiers - //! into this root, which is the compilation that must stay small enough to reason about. It would //! give the firmware two ways to reach the editor. And above all it would make the OBJECT path a //! second arrangement, tested separately: that path is what `05-zig-p4 -Dpardes -Dpardes-obj=...` //! builds, it is what every measurement in that repository's `experiments/` was taken through, and //! it is the firmware build path. Its externs link against that object file. //! The reasons the seam is a file at all - a nested `build.zig.zon` dependency broke every build in //! the toolchain repository - are recorded in `src/esp32p4.zig:8-15` and `05-zig-p4/build.zig:238-260`. //! //! Who owns which symbol: `src/esp32p4.zig` exports all eight `pardes_esp32p4_*` functions and nothing else. //! This file exports `_start`, `zig_main`, `trapEntry` and `trapReport`. `esp_app_desc` belongs to //! neither and comes from the toolchain's own appdesc object, which the link adds unconditionally. //! `abi_version` below is the one constant both sides spell, and its counterpart is //! `src/esp32p4.zig:98` - one repository now, so a bump is two lines in one diff rather than two commits //! in two trees. //! //! The seam is deliberately **bytes in, bytes out**. Everything that needs to know what a cell is - //! vaxis, the ANSI encoder, the input parser, the capability handshake - lives on the far side, //! next to the vaxis it is built against. What crosses is a byte stream in each direction, which is //! exactly what a serial line is, so this file has no opinion about terminals at all. //! //! ## Where the memory is //! //! Measured on this die by the toolchain's `examples/memprobe.zig`, not read off a datasheet, and //! written down once in the generated linker script (`05-zig-p4/build.zig:1572,1579,1584-1585`): //! //! 0x4FF00000..0x4FF3F000 252 KiB `l2mem`: .data/.bss/.stack are linked into this //! 0x4FF3F000..0x4FF40000 4 KiB mask ROM .data/.bss - untouchable, ets_printf needs it //! 0x4FF40000..0x4FFA0000 384 KiB `l2high`: handed to the editor as its entire heap //! 0x4FFA0000..0x4FFC0000 128 KiB NOT memory - the L2 cache lives here //! //! That last line is why the heap is 384 KiB and not the 512 KiB an earlier version of this comment //! claimed. The first probe wrote a pattern and read it back one page at a time and reported the //! whole upper 512 KiB as RAM, because a store followed immediately by a load of the SAME address //! returns the stored value whether the backing store is real, an address mirror, or merely a dirty //! cache line. Writing every page before reading any page separates the three, and the top 128 KiB //! then failed; handing them to an allocator hung the heap on its first free-list walk. ESP-IDF's //! own arithmetic agrees exactly: SRAM_HIGH_SIZE = 0x80000 - CONFIG_CACHE_L2_CACHE_SIZE, with the //! Kconfig default of 128 KiB. //! //! The span arrives as `__heap_start`/`__heap_end` from that script, so those addresses are written //! down in exactly one place. The editor owns it outright: it is passed in at init and this file //! never allocates from it. //! //! PSRAM is not used. The board has 32 MB fitted and it would make all of this comfortable, but //! ESP-IDF's own ESP32-P4 implementation runs past a thousand lines - MPLL, MSPI clocking, pin //! drive and DQS, CS timing, mode registers, a connectivity check, and an entire timing-calibration //! subsystem - and the mask ROM offers only MMU mapping, no device init. Touching it untrained //! faults and hangs the core, which `examples/memprobe.zig` demonstrates on purpose. const std = @import("std"); const soc = @import("soc"); const config = @import("config"); /// `-Dprof`: time the two phases of a keystroke on the board and print the cycle counts. A /// diagnostic, not a feature - see the loop. const prof = config.prof; /// Every byte this loop has taken off the UART, for `-Dprof`. Ground truth for "did the burst /// arrive", which a screen reconstruction cannot answer: a character can be missing from the screen /// because it never arrived, because the editor never applied it, or because the viewport does not /// show that column. var rx_total: u32 = 0; /// How many input bytes to hand the editor before draining the receiver again. Chosen against the /// FIFO rather than against the editor: applying one keystroke was measured at 44 us on an empty /// line and 63 us at 640 characters, so eight of them is at most ~0.5 ms in which nothing empties /// the receiver, against a 128-byte FIFO that holds 11 ms of wire at 115200. Twenty times the margin /// needed, and it costs nothing on the wire because one render still happens per loop iteration. const input_chunk = 8; const hal = @import("hal"); const heapmod = @import("heap"); const uart = @import("uart.zig"); // ------------------------------------------------------------------------------------- the ABI // Eight functions, all `callconv(.c)`, all implemented in the linked object - `src/esp32p4.zig` in this // repository, compiled for the same target and exporting exactly these names. This is the complete // interface between this board and the editor, and it is deliberately bytes-and-memory only: the // editor never learns what a UART is, and this file never learns what a cell is. // // The declarations below are a SECOND spelling of the signatures in `src/esp32p4.zig:100-127,259-...`, // and that duplication is what a C ABI is: each side declares the wire independently, which is // precisely why `abi_version` has to be checked. Sharing a Zig type between them would mean sharing // a module, which would mean the core in this compilation - see the header. /// How the editor emits bytes. Called with finished runs of ANSI, many times per frame. const WriteFn = *const fn (ctx: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void; /// The board's pads, offered to the editor. Optional on the wire so a firmware with nothing to /// toggle passes null and the `Gpio` word reports that rather than the object guessing. const GpioFn = *const fn (ctx: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool; /// This board's allocator, handed across as plain function pointers. `log2_align` is a log2 value, /// which is exactly how `std.mem.Alignment` represents itself, so neither side needs a conversion /// table. /// /// The memory belongs to THIS side: only the firmware knows that the heap is the 384 KiB at /// 0x4FF40000, that the 128 KiB above it is L2 cache, and that PSRAM is untrained. The editor gets /// an allocator, not an address range. const Allocator = extern struct { ctx: ?*anyopaque, alloc: *const fn (ctx: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8, resize: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool, free: *const fn (ctx: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void, }; /// The one number both sides must agree on. Linkers do not type-check C symbols, so a signature /// that drifts on one side of this seam links cleanly and then corrupts the stack; checking this /// before calling anything else turns that into a refusal to boot. const abi_version: u32 = 2; extern fn pardes_esp32p4_abi_version() callconv(.c) u32; /// Hand over the allocator and the output sink, and state the initial window size. Returns 0, or a /// small non-zero code this file can only report. extern fn pardes_esp32p4_init( alloc: *const Allocator, write: WriteFn, gpio: ?GpioFn, ctx: ?*anyopaque, cols: u16, rows: u16, ) callconv(.c) u32; /// Raw bytes off the wire: keystrokes, capability-query replies, and the host bridge's in-band /// resize reports. The editor parses all three; this file distinguishes none of them. extern fn pardes_esp32p4_input(ptr: [*]const u8, len: usize) callconv(.c) void; /// Advance time. Separate from `input` because animations and timeouts must progress on a wire /// where nothing is arriving. extern fn pardes_esp32p4_tick(now_ms: u64) callconv(.c) void; /// Emit one frame through the write callback. Returns 0 or an error code. extern fn pardes_esp32p4_render() callconv(.c) u32; /// Is there anything to draw - a dirty surface or a running animation? Asked every iteration so a /// quiet editor costs no bytes on a 115200-baud link. extern fn pardes_esp32p4_wants_frame() callconv(.c) bool; /// Has the user asked to leave? There is nowhere to go, so this only stops the loop. extern fn pardes_esp32p4_quit() callconv(.c) bool; /// The last frame's three stages in CPU cycles: the copy of pardes's Surface into vaxis's grid, /// vaxis's own diff-and-emit, and the push into the UART. Only meaningful under `-Dprof`; the /// editor object always exports it, and it costs two CSR reads per stage. extern fn pardes_esp32p4_frame_prof(copy: *u64, render: *u64, flush: *u64) callconv(.c) void; // ------------------------------------------------------------------------------------ the sink /// The write callback handed to `pardes_esp32p4_init`. No context is needed - there is one UART. fn writeOut(_: ?*anyopaque, ptr: [*]const u8, len: usize) callconv(.c) void { uart.write(ptr[0..len]); } /// Flip one pad and report the level before and after. The editor's `Gpio` word calls this; the /// editor has no register of its own for it, deliberately. /// /// THIS IS WHY THE SEAM IS HERE. A toggle is not a write to GPIO_OUT: `configureOutput` points the /// pad's IO MUX at the GPIO function, routes the GPIO matrix's output to it, sets the drive strength /// and input buffer and clears the pulls, and only then enables the driver - four register files, /// indexed by a per-pin table. That code already exists in the toolchain package's `src/hal/gpio.zig`, /// it is the same call that package's `src/main.zig` blinks with, and its register numbers are /// checked against ESP-IDF's own headers by `zig build diff` there. A second copy inside the editor /// object would be a second copy under no test. /// /// `getDrivenLevel` rather than `getLevel`: the answer is the level this board is DRIVING, which is /// defined for every pin. The pad's own level is what the outside world says, and on an unconnected /// header pin that is noise. The input buffer is enabled anyway, so `Peek` of GPIO_IN_REG shows the /// pad for anyone who wants to compare the two. fn gpioToggle(_: ?*anyopaque, pin: u16, was: *u8, now: *u8) callconv(.c) bool { if (pin > hal.gpio.max_pin) return false; const p: u8 = @intCast(pin); hal.gpio.configureOutput(p, .{ .readback = true }); const before = hal.gpio.getDrivenLevel(p); if (before == 1) hal.gpio.setLow(p) else hal.gpio.setHigh(p); was.* = before; now.* = hal.gpio.getDrivenLevel(p); return true; } // ------------------------------------------------------------------------------------- the heap /// The span the linker script hands over, from `l2high`'s ORIGIN and LENGTH. /// /// Reached with `@extern`, NOT with `extern const __heap_start: anyopaque` plus /// `@intFromPtr`/`@ptrFromInt`. That spelling was here first and it was silently wrong: declaring a /// linker symbol as an `anyopaque` OBJECT gives the optimiser a zero-sized object, so a pointer /// derived from its address carries provenance for zero bytes, and ordinary (non-volatile) stores /// through it are dead code it may drop. The toolchain's `examples/heapcheck.zig` caught it on the /// die - the allocator's first block header read back as `size=2988759312 next=0xffffffff`-not, and /// the free list walk never terminated. A `[*]u8` from `@extern` has no size to lose. const heap_start = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_start" }); const heap_end = @extern([*]align(heapmod.Heap.granule) u8, .{ .name = "__heap_end" }); fn heapSpan() []align(heapmod.Heap.granule) u8 { return heap_start[0 .. @intFromPtr(heap_end) - @intFromPtr(heap_start)]; } /// The one heap. A K&R coalescing free list over that span, validated on this die by the toolchain's /// `examples/heapcheck.zig`: 512 blocks fill and free back to a single 393,216-byte block, a holed /// arena still satisfies a 4 KiB request, and 20,000 random operations drain back to one block. var gpa_heap: heapmod.Heap = undefined; // The four C forwarders the editor is handed. `log2_align` round-trips through // `std.mem.Alignment`, whose representation IS the log2 value. fn cAlloc(_: ?*anyopaque, len: usize, log2_align: u8) callconv(.c) ?[*]u8 { const a = gpa_heap.allocator(); return a.vtable.alloc(a.ptr, len, @enumFromInt(log2_align), @returnAddress()); } fn cResize(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8, new_len: usize) callconv(.c) bool { const a = gpa_heap.allocator(); return a.vtable.resize(a.ptr, ptr[0..len], @enumFromInt(log2_align), new_len, @returnAddress()); } fn cFree(_: ?*anyopaque, ptr: [*]u8, len: usize, log2_align: u8) callconv(.c) void { const a = gpa_heap.allocator(); a.vtable.free(a.ptr, ptr[0..len], @enumFromInt(log2_align), @returnAddress()); } const editor_allocator: Allocator = .{ .ctx = null, .alloc = cAlloc, .resize = cResize, .free = cFree, }; // ------------------------------------------------------------------------------------ the clock /// Milliseconds since boot, off the systimer - a 16 MHz counter (the toolchain package's /// `src/hal/systimer.zig:31`), which is the cheapest trustworthy clock on this chip. `read` returns /// null if the unit is not running, in which case time simply does not advance and the editor stops /// animating; that is a better failure than a clock that jumps. fn nowMs() u64 { const us = hal.systimer.micros(.unit0) orelse return 0; return us / 1000; } // ------------------------------------------------------------------------------------- the loop export fn zig_main() noreturn { // FIRST, before a single byte of `.rodata` is touched - which means before the marker below, // because that marker IS a string literal in flash and would read as machine code without this. soc.flushFlashCache(); const heap = heapSpan(); soc.rom.print("\r\nMARK B3 rom.print heap 0x%08x..0x%08x %u KiB\r\n", .{ @as(u32, @intFromPtr(heap.ptr)), @as(u32, @intFromPtr(heap.ptr)) + @as(u32, @intCast(heap.len)), @as(u32, @intCast(heap.len / 1024)), }); // The CPU clock, before anything is timed against it. The bootloader leaves 90 MHz and the // CPLL is already at 360, so this is a divider change that disturbs neither UART0 (XTAL) nor // the systimer (XTAL/2.5) nor the flash interface (SPLL). See the toolchain package's // `src/hal/clkrst.zig:setCpuFreq`. if (config.cpu_mhz != 90) hal.clkrst.setCpuFreq(switch (config.cpu_mhz) { 180 => .mhz180, 360 => .mhz360, else => .mhz90, }); const rwdt_was_armed = hal.rwdt.disable(); hal.systimer.init(); _ = rwdt_was_armed; const their_abi = pardes_esp32p4_abi_version(); if (their_abi != abi_version) { uart.write("MARK PARDES_ABI_MISMATCH\r\n"); while (true) {} } gpa_heap = heapmod.Heap.init(heap); _ = uart.drainInput(); // Ask for more than any grid this board will ever render, so the SHELL's own ceiling is what // governs - it clamps to `-Desp32p4-cols`/`-Desp32p4-rows` and reports the result. Naming 80x24 here made // the firmware a second opinion about the geometry, which is one opinion too many. const rc = pardes_esp32p4_init(&editor_allocator, writeOut, gpioToggle, null, 255, 255); if (rc != 0) { soc.rom.print("MARK PARDES_INIT_FAIL rc=%u\r\n", .{rc}); const s = gpa_heap.stats(); soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ s.free, s.largest_free, s.free_blocks, }); while (true) {} } // The HEAP, after the editor has taken what it needs. This is the number that decides how large // a grid the board can drive, so it is printed on every boot rather than only on failure: a // geometry that fits with 2 KB to spare and one that fits with 80 KB are not the same answer, // and the difference is invisible from the host otherwise. { const s = gpa_heap.stats(); soc.rom.print("MARK PARDES_HEAP free=%u largest=%u blocks=%u\r\n", .{ s.free, s.largest_free, s.free_blocks, }); } // The CPU clock, measured rather than assumed. Every cycle count this firmware reports is // divided by it somewhere, and the toolchain's `src/io/chip.zig` records it as "a measured // ~90 MHz" that nothing here reconfigures - so it is worth printing rather than remembering. The // systimer is XTAL/2.5 = 16 MHz and is NOT derived from the CPU clock // (`src/hal/systimer.zig:31`, `clk_tree_defs.h:196-198`), which is exactly what makes it a valid // reference for measuring it. if (prof) { const t_start = hal.systimer.micros(.unit0) orelse 0; const c_start = soc.cycles(); // 50 ms is long enough that the systimer's 16 MHz granularity and the loop's own overhead // are both noise, and short enough to be invisible in a boot. while ((hal.systimer.micros(.unit0) orelse 0) -% t_start < 50_000) {} const elapsed_us = (hal.systimer.micros(.unit0) orelse 0) -% t_start; const elapsed_cy = soc.cycles() - c_start; soc.rom.print("MARK CPU_HZ cycles=%u us=%u khz=%u\r\n", .{ @as(u32, @intCast(elapsed_cy)), @as(u32, @intCast(elapsed_us)), @as(u32, @intCast(if (elapsed_us > 0) elapsed_cy * 1000 / elapsed_us else 0)), }); } soc.rom.print("MARK PARDES_READY\r\n", .{}); var in: [256]u8 = undefined; while (!pardes_esp32p4_quit()) { // ATTRIBUTION. The host can time a keystroke's round trip but cannot see what the firmware // spent it on, and the two candidates - parsing and editing, versus rendering - want // opposite fixes. `soc.cycles()` is the unprivileged cycle counter, so this costs two CSR // reads per phase and quantises at one cycle, which is four orders of magnitude below the // milliseconds being attributed. Gated on `prof` so the shipping build carries none of it. const n = uart.read(&in); rx_total +%= @intCast(n); var input_cy: u64 = 0; if (n > 0) { const t0 = if (prof) soc.cycles() else 0; // IN CHUNKS, rescuing the receiver between them. Applying a keystroke is not free and // gets dearer as the line grows - measured at 44 us on an empty line and 63 us at 640 // characters - so handing over a full 128-byte batch is up to 8 ms in which nothing // drains the receiver, against a FIFO that holds only 11 ms of wire. A 600-byte paste // lost 93 bytes to exactly that window even with the transmitter's own rescue in place. // // Splitting a burst at an arbitrary byte is safe: `pardes_esp32p4_input` keeps whatever it // could not parse, which is how it already survives an escape sequence split across two // UART reads. One render still happens per loop iteration, so this costs no extra wire. var off: usize = 0; while (off < n) { const chunk = @min(input_chunk, n - off); pardes_esp32p4_input(in[off..].ptr, chunk); off += chunk; if (off < n) uart.rescueNow(); } if (prof) input_cy = soc.cycles() - t0; } pardes_esp32p4_tick(nowMs()); // Only when there is something to show. On a link this slow an unconditional repaint per // iteration would saturate the wire and starve input. if (pardes_esp32p4_wants_frame()) { const t0 = if (prof) soc.cycles() else 0; const err = pardes_esp32p4_render(); if (err != 0) soc.rom.print("MARK PARDES_RENDER_FAIL rc=%u\r\n", .{err}); if (prof) { const render_cy = soc.cycles() - t0; // A SECOND render with nothing changed since the first. It splits the cost in two: // whatever this still costs is the price of walking and diffing the whole editor // state, paid regardless of output, while the difference between the two is the // price of the change itself. `wants_frame` is false now, so this only happens // under -Dprof and never on a shipping build. const t1 = soc.cycles(); _ = pardes_esp32p4_render(); const idle_cy = soc.cycles() - t1; // Reported in cycles, not microseconds: the divisor is the CPU clock, which this // firmware does not set and has only ever measured, so converting here would bake a // guess into the data. The toolchain's `experiments/` divides by the clock it // measured. var copy_cy: u64 = 0; var vx_cy: u64 = 0; var flush_cy: u64 = 0; pardes_esp32p4_frame_prof(©_cy, &vx_cy, &flush_cy); soc.rom.print("PROF in=%u render=%u idle=%u copy=%u vaxis=%u flush=%u rx=%u rxdrop=%u txdrop=%u\r\n", .{ @as(u32, @intCast(input_cy)), @as(u32, @intCast(render_cy)), @as(u32, @intCast(idle_cy)), @as(u32, @intCast(copy_cy)), @as(u32, @intCast(vx_cy)), @as(u32, @intCast(flush_cy)), rx_total, uart.inputDropped(), uart.dropped, }); } } } soc.rom.print("\r\nMARK PARDES_QUIT\r\n", .{}); while (true) {} } // ------------------------------------------------------------------------------------ the trap /// A trap handler, because the absence of one is why this port has been guessing. /// /// The mask ROM prints "Guru Meditation" for a trap only while ITS handler is still installed; /// anything this image does that replaces or outgrows that path fails silently instead, and a silent /// fault is indistinguishable from an infinite loop over a serial line. This one reports the three /// registers that name the fault and then stops, using the direct-FIFO writer so it shares nothing /// with the editor's buffered output. /// /// `mtvec` is set in DIRECT mode (low two bits zero), so every trap and every interrupt lands on /// `trapEntry` regardless of cause - which is what a diagnostic wants. export fn trapEntry() linksection(".text.entry") callconv(.naked) noreturn { asm volatile ("j trapReport"); } export fn trapReport() noreturn { const mcause = asm volatile ("csrr %[o], mcause" : [o] "=r" (-> u32), ); const mepc = asm volatile ("csrr %[o], mepc" : [o] "=r" (-> u32), ); const mtval = asm volatile ("csrr %[o], mtval" : [o] "=r" (-> u32), ); uart.write("\r\nMARK TRAP mcause="); uart.dumpWord(mcause); uart.write("MARK TRAP mepc="); uart.dumpWord(mepc); uart.write("MARK TRAP mtval="); uart.dumpWord(mtval); uart.write("MARK TRAP dropped="); uart.dumpWord(uart.dropped); while (true) {} } // --------------------------------------------------------------------------- the root's own duties // // These are the FIRMWARE root's declarations, and they are not the same set as `src/esp32p4.zig`'s: that // file is the root of its own object and carries its own `std_options` and `panic` for the core's // half of the image. Two roots, two instantiations of std, one per compilation unit - which is // exactly what the object seam buys, and why a panic in the core prints `PARDES_CORE_PANIC` through // the write callback while a panic here prints `PARDES_PANIC` through the mask ROM. /// `page_size_min`/`max`: the board has no MMU and no pages, but std derives allocator alignment /// from these. 4 KiB is the ESP32-P4's cache and DMA granularity. /// /// `logFn` is not cosmetic. std's default log implementation reaches `std.debug_io`, which /// instantiates `std.Io.Threaded` - a thread pool, `getrandom`, `IOV_MAX`, `mremap` - none of which /// exist here, and one `log.warn` from anywhere is enough to drag all of it into the image. pub const std_options: std.Options = .{ .page_size_min = 4096, .page_size_max = 4096, .logFn = logFn, }; fn logFn( comptime level: std.log.Level, comptime scope: @EnumLiteral(), comptime fmt: []const u8, args: anytype, ) void { var buf: [256]u8 = undefined; const line = std.fmt.bufPrint(&buf, "\r\n[" ++ level.asText() ++ "/" ++ @tagName(scope) ++ "] " ++ fmt ++ "\r\n", args) catch "\r\n[log overflow]\r\n"; uart.write(line); } pub const panic = std.debug.FullPanic(panicImpl); fn panicImpl(msg: []const u8, first_trace_addr: ?usize) noreturn { // The fixed text goes out through the ROM deliberately: a panic may BE the console writer // failing, and `ets_printf` shares nothing with `uart.write` except the FIFO itself. // // The MESSAGE does not, and that is a correction rather than a preference. `msg` is a Zig SLICE // and `%s` reads until a NUL, so handing `msg.ptr` to printf prints the message and then // whatever happens to sit after it in memory until a zero byte turns up. Literals get away with // it; std's own panics do not, because they are formatted into a buffer - "index out of bounds: // index 5, len 3" - and carry no terminator. `uart.write` takes a length. soc.rom.print("\r\nMARK PARDES_PANIC ", .{}); uart.write(msg); // The address is what makes it actionable: addr2line against the ELF in zig-out turns it into a // source line, and without it a panic message names a KIND of failure with no way to find which // one of them happened. Zero when the caller had no return address to give. soc.rom.print("\r\nMARK PARDES_PANIC_AT 0x%08x\r\n", .{@as(u32, @truncate(first_trace_addr orelse 0))}); while (true) {} } /// Reset entry. The bootloader hands over with an unspecified stack pointer and the FPU off, so: /// enable the F extension (`mstatus.FS`, which ESP-IDF only ever turns on lazily from a trap handler /// this image does not have), establish a stack, clear `.bss`, and call into Zig. /// /// The cache invalidate that this image also needs is the FIRST thing `zig_main` does, not something /// done here. Hand-written `la t0, Cache_Invalidate_All` against an absolute linker symbol computed /// a PC-relative target and jumped into nowhere (measured: PC=0x88b5d788 with the argument stranded /// in a2); Zig generates the addressing for an `extern fn` correctly, and `zig_main` runs before any /// `.rodata` is touched anyway. export fn _start() linksection(".text.entry") callconv(.naked) noreturn { asm volatile ( \\ li t0, 1 << 13 \\ csrs mstatus, t0 \\ la sp, __stack_top \\ mv fp, sp \\ la t0, trapEntry \\ csrw mtvec, t0 \\ la t0, __bss_start \\ la t1, __bss_end \\ bgeu t0, t1, 2f \\1: \\ sw zero, 0(t0) \\ addi t0, t0, 4 \\ bltu t0, t1, 1b \\2: \\ j zig_main ); }