Pyromaniac

Introduction

System requests ("SysRqs") are Pyromaniac's interface for inspecting and controlling the emulated RISC OS environment from outside the normal * command/SWI path - reading registers and memory, pausing and stepping execution, managing breakpoints/watchpoints/tracepoints, reading and writing files, injecting keyboard/mouse input, querying configuration, and more. They are how every debugging tool in this repository (the GDB/ LLDB stub, pyro_debug.py, the MCP server) and the desktop UI itself talk to a running Pyromaniac instance.

A sysrq is a plain text command name, plus zero or more text arguments, and always produces a reply - a boolean, a string, a list, or a dictionary, depending on the command. There is no separate "no reply" case: even a command whose main purpose is an action (debug-pause, nvram-clear) still replies, usually with True or an error string.

If a handler raises an exception instead of replying itself (for example a RISCOSSyntheticError because the requested operation isn't available in the current configuration, such as screensave under the null graphics implementation), the dispatcher catches it rather than letting it propagate into the emulation main loop, and replies with {'error': '<ExceptionClassName>: <message>'} - the same error-key-holds-a-message-or-None convention already used by handlers that report their own errors.

Command naming and grouping

Most commands are named <subsystem>-<verb> (memory-read-bytes, watchpoints-add), grouping related commands under a common prefix. screensave is old enough, or general enough, that it was never given a subsystem prefix; it is listed under the subsystem it conceptually belongs to in the reference below.

The subsystem prefixes currently in use:

A few commands only exist once a particular PyModule has been loaded and initialised - clipboard-* (the ClipboardHolder module, part of the Select desktop environment), econet-* (the Econet module), internet-sockets (the Internet module), timers-list (a timer driver such as TimerManager), and tasks-info (the experimental PyromaniacWimpDebug module, disabled by default). These are marked below; every other command is always available. Likewise, iicid809-finger only has any effect once an id809 internal IIC device has been configured, iicssd1306-info/iicssd1306-read only once an ssd1306 device has been configured, and iicst25dv-field only once a st25dv16k/st25dv16ksys internal IIC device has been configured (see iicinternal.devices). Similarly, ui-* commands only exist while the WxWidgets graphics implementation (graphics.implementation=wx) is active, and only for the lifetime of its main window - they let a test drive the desktop UI (opening the file explorer, a hex dump window, and so on) through the same code paths a real click would use, without needing a genuinely interactive session.

How sysrqs are processed

Sending a sysrq doesn't call straight into the emulator: it is queued, and only actually serviced when Pyromaniac's emulation loop reaches its own periodic check for queued requests - normally many times a second while RISC OS code is running. Most commands are answered so quickly this is invisible, but a few are asynchronous by design (debug-pause, debug-step, and anything that halts execution) - they reply immediately to acknowledge the request, and the effect (RISC OS code actually stopping) only shows up once the emulation loop reaches that point, which callers discover by polling debug-status.

This also means a sysrq sent while nothing is actively running RISC OS code (the instance sitting idle between commands) will not be serviced until something drains the queue - pyro_server.py's persistent-server mode does this itself while idle, which is why it (rather than a one-shot pyro.py invocation) is normally used for interactive debugging sessions.

Starting and using sysrqs

The raw sysrq socket

The most direct way to reach sysrqs is the built-in line-based TCP server:

$ scripts/pyro-server --config sysrqserver.enable=true

(pyro.py --config sysrqserver.enable=true ... works too, for a one-shot invocation, but has nothing left running to connect to once the command finishes - a persistent pyro_server.py/pyro-server instance is the usual choice.)

Connect with any line-oriented client - nc localhost 8809, telnet localhost 8809, or similar:

$ nc localhost 8809
Pyro> regs-list
R0: 0
R1: 0
...
cpsr: 1610613011
Pyro> memory-read-bytes 8000 4
'\x00\x01\x02\x03'
Pyro> watchpoints-add ff8 break
True
Pyro> help
Commands:
  ambs-info
  ambs-read-bytes
  ...
Pyro> quit

Each line is <command> [arguments...], with shell-style quoting for an argument containing spaces (sysvars-set MyVar$Test "Hello World"). Two pseudo-commands are handled client-side rather than being real sysrqs: help lists every currently-registered command name (reflecting whichever PyModules happen to be loaded), and quit closes the connection.

Replies are formatted for human reading, not as a machine-readable encoding: a dictionary reply is shown as one key: value line per entry, a list/tuple reply as one value per line, a string reply as itself, and anything else via its Python repr() - all consistently across every client built on this server (the raw socket, pyro_debug.py, and the GDB/LLDB stub's monitor command all share the same formatting code, so the same command looks the same wherever you run it from).

Other ways to reach sysrqs

• scripts/pyro-debug/pyro_debug.py - an interactive CLI wrapper around the raw socket above, adding readline history/tab-completion and short debugger-style aliases (b, c, s, bt) for the sysrqs used most often. See docs/PYRODEBUG.md.
• The Pyromaniac MCP server (scripts/pyro-mcp/pyro_mcp.py) - exposes a curated set of riscos_debug_*/riscos_backtrace tools, built on a subset of the debugging-related sysrqs, for AI agent tool integration. Not every sysrq has a dedicated MCP tool; anything else can still be reached over the raw socket against the same instance if  sysrqserver.enable is also turned on. See docs/PYROMCP.md.
• The GDB/LLDB stub's monitor/qRcmd - monitor <sysrq> [args...] from an attached gdb or lldb session reaches the exact same dispatch as the raw socket, including sysrqs with no dedicated GDB/ LLDB verb of their own (monitor debug-backtrace, monitor debug-trace-log), plus a couple of convenience aliases (monitor where <address> for memory-describe, monitor find <pattern> for  memory-find-names). See docs/GDB.md.
• Directly from Python code inside Pyromaniac - ro.sysrq(name, timeout=..., args=[...]) sends a request and waits for the reply, the same way every client above does under the surface; used by test harnesses and other in-process tooling that doesn't want to go via a socket at all.

Command reference table

Command reference

Addresses are given in hexadecimal, optionally with a leading & (8000 and &8000 are equivalent) - the same convention RISC OS itself uses. Arguments in [square brackets] are optional.

ambs (Application space management)

ambs-info

Lists every Application Memory Block (AMB) - the memory areas backing RISC OS's per-application address space.

Returns: a list of dictionaries, one per AMB: id, name, size, address, maxsize, mapped (bool), current (bool - whether this is the AMB currently mapped into the application address space).

ambs-read-bytes <ambid> [<address> <size>]

Reads bytes from within an AMB. ambid may be -1 (or &FFFFFFFF) to mean the currently-mapped AMB; if address/size are omitted, the whole AMB is read.

Returns: the bytes read, as a byte string; False if ambid is unknown or the requested region falls outside the AMB.

ambs-read-words <ambid> [<address> <size>]

As ambs-read-bytes, but returns 32-bit words instead of individual bytes.

Returns: a list of words; False on the same errors as ambs-read-bytes.

debug (Debugging and execution control)

debug-list

Lists Pyromaniac's internal debug/trace flags (not RISC OS state) and whether each is currently enabled - the same flags debug-toggle/ debug-enable/debug-disable control.

Returns: a dictionary of flag name to boolean state.

debug-toggle <name>

Toggles one debug/trace flag.

Returns: the flag's new state (True/False), or None if name isn't a recognised flag.

debug-enable <name>

Enables one debug/trace flag.

Returns: the flag's previous state.

debug-disable <name>

Disables one debug/trace flag.

Returns: the flag's previous state.

debug-pause

Requests that RISC OS code execution pause for debugging. Asynchronous: the pause takes effect the next time the emulation loop reaches its check for one, which may be after the reply has already been sent. While paused, sysrqs (including debug-resume) continue to be serviced.

Returns: True.

debug-resume

Resumes execution after debug-pause, or after a break-tagged watchpoint/tracepoint/switrap halted execution. If the halt was caused by a watchpoint or an address-based tracepoint, that watchpoint/ tracepoint is automatically removed as part of resuming (otherwise it would immediately re-trigger on the same access forever) - re-add it to arm it again for the next hit.

Returns: True.

debug-step <mode> [count]

Single-steps one or more instructions. mode is into (every instruction is stepped, including the first instruction of any real ARM code a SWI invokes) or over (a whole SWI call runs as a single atomic step). count (default 1) takes that many steps in one request. Asynchronous, like debug-pause - poll debug-status to find out when the step(s) have finished.

Returns: True, or an error string if mode/count is invalid.

debug-status

Reports whether RISC OS code execution is currently paused, and why. Always answerable, including while paused.

Returns: a dictionary: paused (bool), reason ('user', 'watchpoint', 'tracepoint', 'switrap', 'step', or None), pc (the current program counter), info (a dictionary with more detail on the pause cause, or None).

debug-backtrace

Reports a C-style backtrace of the current call stack, using the frame-pointer chain. Only available when the current state looks like a C-style stack frame (a C module in SVC mode, or USR mode).

Returns: a dictionary: available (bool), lines (list of text lines, empty if unavailable).

debug-trace-log [count]

Reports the most recently captured trace output lines (an in-memory ring buffer, independent of where trace output is actually being sent). If count is given, only that many of the most recent lines are returned.

Returns: a dictionary: lines (list of text lines), dropped (count of older lines discarded because the buffer filled up).

debug-trace-clear

Clears the captured trace output buffer used by debug-trace-log.

Returns: True.

clipboard (ClipboardHolder data - needs the ClipboardHolder module)

clipboard-info

Reports the filetype and size of the current clipboard contents, without transferring the data itself.

Returns: a dictionary: filetype, size.

clipboard-read [filetype]

Reads the current clipboard contents. filetype (hex) requests that specific type; if omitted, any available type is returned.

Returns: a dictionary: filetype, data.

clipboard-write <filetype> <data>

Replaces the clipboard contents with data, tagged with filetype (hex).

Returns: True, or an error string.

config (Pyromaniac configuration)

config-list

Lists every configuration option and its current value.

Returns: a dictionary keyed by <group>.<option>, value the formatted option value.

config-set <group.option> <value>

Sets a configuration option.

Returns: True, or an error string if the option or value is invalid.

dynamicareas (Dynamic Area memory management)

dynamicareas-info

Lists the Dynamic Areas currently present.

Returns: a list of dictionaries, one per Dynamic Area: number, address, size, maxsize, name, flags.

econet (Econet module - needs the Econet module)

econet-info

Reports the selected transport, local net and station, the null transport's configured send effect, and counts of open receive/transmit and retained completed operations.

Returns: a dictionary containing implementation, local_net, local_station, send_effect, open_receives, open_transmits, and completed_operations.

econet-inject-packet <port> <flag> <station> <net> <hexdata>

Injects an incoming packet for testing and debugging. Numeric arguments may be decimal or use RISC OS & hexadecimal notation. hexdata is an even-length sequence of hexadecimal byte pairs. The first eligible open receive is selected using exact-address matches before wildcard matches and FIFO order within each group.

Returns: a dictionary containing matched, handle, status, accepted, and overrun. Invalid arguments return an error dictionary.

econet-operations

Lists live operations followed by retained completed or abandoned operations in creation order. Payload data is limited to a hexadecimal preview; enable the econet-packets debug flag when full packet data is required.

Returns: a list of stable rows containing sequence, kind, state, handle, status, port, operation, peer, buffer, capacity, transferred, flag, count, delay, preview, and truncated.

fs (Filing system)

fs-file-read <filename>

Reads a file's contents.

Returns: a dictionary: error (None on success, else a message), data (the file content as text).

fs-file-write <filename> <base64-data>

Writes a file's contents. The data is given base64-encoded, since the sysrq transport is line-based text with no shell-style quoting and cannot carry arbitrary binary/whitespace-containing content as a bare argument.

Returns: a dictionary: error (None on success, else a message).

fs-file-mkdir <dirname>

Creates a directory.

Returns: a dictionary: error (None on success, else a message).

fs-file-delete <filename>

Deletes a file or directory.

Returns: a dictionary: error (None on success, else a message).

fs-file-rename <source> <destination>

Renames/moves a file.

Returns: a dictionary: error (None on success, else a message).

fs-file-list <dirname>

Enumerates the objects in a directory.

Returns: a dictionary keyed by leafname, each entry a dictionary: name, loadaddr, execaddr, length, attr, objtype, filetype, epochtime (decoded from the load/exec timestamp where applicable, else None).

fs-filehandles

Lists currently open file handles.

Returns: a dictionary: min, max (the file handle range), and handles - a list of dictionaries (inthandle, exthandle, ptr, filename, extent, allocated, allow_read, allow_write, modified, directory), one per open handle.

fs-statistics

Reports filing system usage statistics.

Returns: a dictionary: enable (whether statistics collection is on), headers, statistics.

graphics (Graphics and VDU)

screensave <filename>

Saves a screenshot to a native host file (not a RISC OS path).

Returns: True, or False if no filename was given.

graphics-info

Reports the current graphics/VDU state.

Returns: a dictionary with two sections - display (width, height, xeigfactor, yeigfactor, log2bpp, mode, palette - properties that change on a mode change) and context (window, origin, positions, foreground, background - properties that change continuously as graphics operations happen).

iicid809 (Internal ID809 IIC device's simulated presented finger)

iicid809-finger <identity|off>

Simulates a finger (an arbitrary opaque identity label, matching an id809 internal IIC device's enroll configuration, see riscos.pymods.driver.iicimp.iicinternal.id809) being presented to, or removed from (off), an emulated ID809 fingerprint sensor, so that enrol/verify/search/identify driver code can be exercised. Requires an id809 device to have been configured.

Returns: True.

iicssd1306 (Internal SSD1306 IIC display controller)

iicssd1306-info <address>

Reports the configured dimensions and current controller state for the internal SSD1306 at eight-bit IIC address <address> (for example, &78). This is host-only inspection: it does not add a guest-visible IIC read-back operation.

Returns: a dictionary: address, width, height, addressing_mode, column_start, column_end, column, page_start, page_end, page, display_on, entire_display_on, inverse, contrast, start_line, segment_remap, com_scan_reverse, multiplex_ratio, display_offset, display_clock, precharge, com_pins, vcomh, charge_pump, scroll_active; or an error entry if no matching controller is configured.

iicssd1306-read <address> [<offset> <size>]

Reads GDDRAM from the internal SSD1306 at eight-bit IIC address <address>. offset and size are hexadecimal byte values and default to the complete &400-byte controller GDDRAM. Data is ordered by page, then column.

Returns: a dictionary: address, offset, size, data (a hexadecimal string); or an error entry for an unknown controller or an out-of-range GDDRAM range.

iicst25dv (Internal ST25DV16K IIC device's simulated RF field)

iicst25dv-field <on|off>

Simulates the RF field appearing or disappearing over an emulated ST25DV16K (st25dv16k/st25dv16ksys internal IIC devices, see riscos.pymods.driver.iicimp.iicinternal.st25dv16k), so that driver code polling GPO/IT_STS_Dyn/EH_CTRL_Dyn can be exercised. Requires at least one of those devices to have been configured and used once.

Returns: True.

input (Synthetic keyboard/mouse input)

input-keyboard-string <text>

Injects a text string into the keyboard buffer, re-encoded from UTF-8 into RISC OS's current alphabet.

Returns: True.

input-keyboard-flush

Flushes the keyboard buffer.

Returns: True.

input-keyboard-bytes <value> [value...]

Injects raw bytes into the keyboard buffer. Each argument is either a number (a single byte value) or a quoted string (its characters, encoded into the current alphabet).

Returns: True, or False if any argument couldn't be parsed.

input-mouse-move <x> <y>

Moves the mouse pointer to a screen position, in OS units.

Returns: True.

input-mouse-click <x> <y> <button>

Moves the pointer to <x>, <y> and clicks (press then release) <button>, one of select, menu or adjust.

Returns: True, or False if <button> isn't recognised.

internet (Internet module - needs the Internet module)

internet-sockets

Lists open network sockets, in the same form as *InetStat.

Returns: a list of socket information dictionaries, or None if the Internet module's socket table isn't available.

irq (Hardware IRQ control)

irq-trigger <number>

Triggers a hardware IRQ.

Returns: a dictionary: error (None on success, else a message).

irq-enable <number>

Enables a hardware IRQ.

Returns: a dictionary: error (None on success, else a message).

irq-disable <number>

Disables a hardware IRQ.

Returns: a dictionary: error (None on success, else a message).

irq-state <number>

Reports the state of one IRQ.

Returns: a dictionary: number, name, enabled (bool), triggered (bool), count; or {'error': ...} if number is invalid.

irq-list

Lists every IRQ and its state.

Returns: a dictionary: error (None on success), data (a list of the same per-IRQ dictionaries irq-state returns).

memory (Logical memory access)

memory-read-bytes <address> <size>

Reads memory as raw bytes.

Returns: the bytes read, as a byte string; False on an invalid address/size or unmapped memory.

memory-read-words <address> <size>

Reads memory as 32-bit words.

Returns: a list of words; False on the same errors as memory-read-bytes.

memory-write-bytes <address> <hex-data>

Writes memory. The data is given as a hexadecimal-encoded byte string (the same encoding GDB's M packet uses), since the sysrq transport is line-based text and cannot carry arbitrary binary content as a bare argument.

Returns: True, or an error string.

memory-dump-bytes <address> <size>

Reads memory and formats it as a traditional byte-width hex dump (address, hex bytes, ASCII).

Returns: the formatted dump as text; False on error.

memory-dump-words <address> <size>

As memory-dump-bytes, but formatted as a word-width hex dump.

Returns: the formatted dump as text; False on error.

memory-disassemble <address> <size>

Disassembles size bytes of memory from address, with live register/ memory value annotation and function-signature detection where available.

Returns: the disassembly as text; False on error, or if no disassembler is available.

memory-describe <address> [relative]

Describes the Dynamic Area, module, and (where known) function that address falls within - the same lookup RISC OS uses internally for data abort messages. If relative is given as a truthy value (1, true or yes), the description also includes the function name plus offset, found by scanning backwards for an APCS function-name signature.

Returns: a dictionary (low, high, description), or None if the address isn't within any known region.

memory-find-names <pattern>

Finds symbol names matching a pattern - a bare fnmatch-style pattern (OS_*), or a qualified module:<module>:<pattern>, area:<area-name>:<pattern> or @:<pattern> form.

Returns: a list of <address>:<name> strings.

modules (Relocatable module system)

modules-info

Lists every loaded relocatable module.

Returns: a list of dictionaries, one per module: address, size, name, version, help, swi_base, swi_prefix, swi_names.

nvram (NVRAM configuration bytes)

nvram-info

Reports the current NVRAM contents.

Returns: a dictionary: data - a dictionary of byte index to value, for every NVRAM byte.

nvram-clear

Clears NVRAM to all zeros.

Returns: True.

nvram-write-byte <index> <value>

Writes one NVRAM byte. value is masked to 8 bits.

Returns: True on success.

nvram-read-byte <index>

Reads one NVRAM byte.

Returns: the byte value (0-255); -1 if index is out of range.

regs (ARM register access)

regs-list

Reads the whole ARM register file.

Returns: a dictionary: R0..R15, cpsr, spsr.

regs-set <register> <value>

Sets one ARM register. register is r0-r15 (the r prefix is optional), cpsr or spsr. value is hexadecimal, with or without a leading &.

Returns: True, or an error string if register/value is invalid.

switraps (SWI trap management)

switraps-list

Lists the SWI traps currently configured.

Returns: a list of <swi>:<actions> strings (<swi> as a hex number or name, <actions> a +-separated list - see "Actions" below).

switraps-add <swi> [actions]

Adds a SWI trap for <swi> (a hex SWI number, or a SWI name/prefix), optionally with a +-separated list of actions (default report).

Returns: True, or an error string.

switraps-remove <swi>

Removes a SWI trap (<swi> must match exactly how it was added).

Returns: True, or an error string.

system (Whole-system control)

system-reboot

Performs a warm reboot of RISC OS, the same as *Reboot would trigger. Replies before doing so.

Returns: True, before the reboot takes effect.

system-terminate [message]

Ends the Pyromaniac process. Replies before doing so, so the caller sees a response.

Returns: True, before the process exits with message (or a default message) as the reason.

sysvars (System variables)

sysvars-info

Lists every system variable.

Returns: a list of dictionaries, one per variable (sorted by name): name, type, typename, value, description.

sysvars-set <name> <value>

Sets a system variable's value.

Returns: True.

sysvars-get <name>

Reads a system variable's value.

Returns: a dictionary: name, type, typename, value, description.

tasks (Wimp task information - needs the PyromaniacWimpDebug module)

tasks-info

Lists the Wimp tasks currently tracked by PyromaniacWimpDebug.

Returns: a list of dictionaries, one per task: task_handle, name, size.

tickers (Ticker/software timer list)

tickers-statistics

Reports statistics about the ticker system.

Returns: a dictionary of ticker system statistics.

tickers-list

Lists every registered ticker.

Returns: a list of dictionaries, one per ticker: description, delay (seconds until it next fires), retrigger (repeat interval, or None for a one-shot ticker), and address (if the ticker's target isn't itself a Python callable).

timers (Hardware timer state - needs a timer driver module)

timers-list

Lists the hardware timers managed by the active timer driver (e.g. TimerManager).

Returns: a dictionary: error (None on success), data (a list of per-timer dictionaries: number, enabled, triggered, period, ...).

timings (Pyromaniac's internal performance timings)

timings-info

Reports Pyromaniac's own internal performance timings (SWI dispatch, emulation, callbacks, timers) - only populated for the categories currently enabled via the timings.* configuration options.

Returns: a nested dictionary: swi-breakdown (per-SWI call counts/ timing), swi-timings, emulation-timings, non-emulation-timings, callback-timings, timer-timings (each a summary: calls, total-time, average-time).

timings-reset

Clears all collected timing statistics.

Returns: True.

tracepoints (Execution tracepoint management)

tracepoints-list

Lists the tracepoints currently configured.

Returns: a list of <value>:<actions> strings (<value> an address or function pattern, <actions> a +-separated list - see "Actions" below).

tracepoints-add <address-or-pattern> [actions]

Adds a tracepoint at an address (hex) or function pattern, optionally with a +-separated list of actions (default report).

Returns: True, or an error string.

tracepoints-remove <address-or-pattern>

Removes a tracepoint (must match exactly how it was added).

Returns: True, or an error string.

vectors (RISC OS vector claim inspection)

vectors-info

Lists every RISC OS vector and its claimants.

Returns: a dictionary: error (None on success), data - a list of per-vector dictionaries (number, name, nclaimants, claims - a list of {address, workspace} and/or {function, file} entries describing each claimant).

watchpoints (Memory watchpoint management)

watchpoints-list

Lists the watchpoints currently configured.

Returns: a list of <address>:<actions> strings (<actions> a +-separated list - see "Actions" below).

watchpoints-add <address> [actions] [watch_type]

Adds a watchpoint at <address> (hex), optionally with a +-separated list of actions (default report). watch_type (yes, read or write) overrides which accesses fire it; if not given, this defaults to write when break is one of the actions, or yes (read and write) otherwise.

Returns: True, or an error string.

watchpoints-remove <address>

Removes a watchpoint.

Returns: True, or an error string.

Actions

watchpoints-add, tracepoints-add and switraps-add all accept an optional +-separated list of actions, describing what happens when the watchpoint/tracepoint/trap fires. The two in everyday use are report (the default: log it) and break (halt execution, as debug-pause does, reported via debug-status with the matching reason) - combine them (report+break) to do both. As noted under debug-resume above, a break-tagged watchpoint or address-based tracepoint is automatically removed once it fires and is resumed past, to avoid it immediately re-triggering on the same access forever - add it again (watchpoints-add/tracepoints-add) to arm it for the next hit. A break-tagged SWI trap has no such disarm-on-resume behaviour, since resuming past a SWI call is forward progress rather than an instant repeat - it keeps firing on every further call to that SWI until explicitly removed.