Rhai Scripting

A Rhai script attached to the debugger defines handlers for events in the machine, such as a breakpoint, a frame or a write to a port, and acts on them. A handler reads the machine’s state directly and returns ADP commands to run, so a whole debugging session can be one file instead of a shell loop.

fn on_breakpoint(id, pc) {
    if reg("i") != 0xBD { return "continue"; }
    log(`crash: sp=${reg("sp")} ix=${reg("ix")} @frame ${frame()}`);
    return ["state", "bt"];
}

Load a script at startup with --script FILE, or into a running session with the ADP command script load FILE. It works in a window, in a --headless server and in a --screenshot capture. The language itself is documented at rhai.rs.

Script lifecycle

The top level of a script runs once, when it loads. Each event then calls its handler, and only that handler. Variables declared at the top level with let keep their values across calls, so a counter or a flag set in one handler is there in the next.

A call is stopped after 5,000,000 operations, so a runaway loop cannot hang the emulator.

Handler results

A handler returns nothing, one ADP command as a string, or an array of them. The commands run in order once the handler returns.

fn on_menu_idle(pc) { return "enter"; }                    // launch the highlighted entry
fn on_frame(n) { if n == 1000 { return "savestate /tmp/f1000.bzst"; } }

Events

Every event fires at the instruction boundary that produced it, so the state a handler reads is the state at that moment. on_frame and on_menu_idle fire at frame boundaries.

Each event interrupts the frame to call its handler, so an event that fires thousands of times a frame slows the run in proportion. on_breakpoint on a tight loop is the usual case; pick an address reached a bounded number of times.

Watches

on_mem_write, on_io_read and on_io_write fire only for what a watch names, because memory and port traffic runs to thousands of accesses a frame.

watch_mem(0xBD00, 0xBE00);                 // an inclusive address range
watch_io(0xFFFD); watch_io(0xBFFD);        // ports accumulate
fn on_mem_write(addr, val, pc) { log(`${addr} = ${val} @pc ${pc}`); }

watch_mem holds one range, and a second call replaces the first. watch_io() with no port watches every port. A watch called in a handler applies from that point in the frame.

A handler with no watch never fires, and Bizmuth warns when the script loads. Filtering inside the handler does not reduce the cost, which is entering the handler at all. Measured over a 300-frame Next boot, against the same run with no script:

Event maps

The richer events pass one map, d, holding what was true when the event happened.

on_reti carries only d.pc and d.line. It fires for interrupt routines that end in RETI, which NextZXOS’s frame routine does not.

fn on_dma_xfer_start(d) {
    if d.dest_io != 0 && (d.dest & 0xFF) == 0x5B {
        log(`pattern upload to slot ${d.pattern_index / 256}, ${d.count} bytes @pc ${d.pc}`);
    }
}

Machine state

The ADP command script eval reads the live machine too. The top level of a script, which runs as it loads, has no machine attached, and the functions return -1 there.

An unknown name also returns -1 (false for flag), so reg, flag, dm and rompg log a warning listing the names they accept, once per name.

Ports

get_machine_state().port[addr] is what a read of the port would return, worked out without performing the read. The UART’s FIFO is not emptied, its error bits are not cleared, the SD card is not clocked and the DMA’s read sequence does not advance, so a program behaves the same whether or not a script is looking.

get_machine_state().portraw[addr] answers for the write-only paging ports $7FFD, $1FFD, $DFFD, $EFF7 and $BF3B, which have no read decode, so a guest reading one gets the open bus. portraw returns the value last written, in that port’s bit layout. It is what the program asked for, where slot(i) is the paging that resulted. A bit the hardware discards on write reads 0: $7FFD keeps all eight, $1FFD bits 0 to 2, $DFFD bits 0 to 3 and $EFF7 bits 2 and 3. For $BF3B the index is the last one latched, which the hardware does only in mode 0. Any other port answers -1.

Symbols and source lines

sym(NAME) returns a map. An unknown name gives an empty one, so using a field of it is an error rather than a plausible number.

⚠ mem(sym(x).addr) reads through the current paging, so it reads the symbol only while its page is mapped. For a symbol in a page that may be out, read pmem(sym(x).bank, sym(x).addr % 0x2000).

State handle

get_machine_state() returns a handle whose fields read the machine as they are used, so asking for .pc reads one register.

A handle is valid only inside the handler that made it. Kept in a global and read in a later event, it reads that event’s machine. Keep the values instead.

Actions

mouse and the esp_ functions queue, so several calls from a loop or a branch apply in order before the next frame. bt records history only while a script is loaded.

stop() ends the capture at the end of the current frame. The screenshot, --state-json, --savestate and the claims report are written from that frame, and a --video is padded to its declared length with it. Called from an event handler, the rest of the frame still runs, on_frame included. A second call does nothing, and a window or a --headless server ignores it. If on_frame(n) calls stop() when n is 612 in a 1000-frame run, the screenshot shows frame 612.

Examples

Count bytes received from the ESP and drop the fortieth:

let seen = 0;
watch_io(0x143B);
fn on_io_read(port, val) {
    seen += 1;
    if seen == 40 { esp_drop_next(); }
}

Drive the mouse from a capture and read the counter back:

fn on_frame(n) {
    if n >= 520 && n < 530 { mouse(4, 0, 0, 0); }
    if n == 530 { mouse(0, 0, 1, 0); }
    if n == 535 { log(`x=${get_machine_state().port[0xFBDF]}`); }
}

← Developer Guide