scry-dosbox-x: reference

This page is for a rule that several tools share. It holds the list of tools, the fields every reply carries, and those rules.

Each tool has its own entry, with arguments, reply and example, on its family's page under docs/reference/; a family is a group of tools. To install, see the README.

Each example is a call of the example session: one session on Bricks, a game this repository builds, kept whole in docs/reference/tour/TRANSCRIPT.md.

A path in an example that starts with ./ stands for the folder of your clone, and $TMPDIR for your temporary folder. Write the whole path in your own call: a relative one is refused.

Index

The session

A session is one DOSBox-X that start launches, stopped at its debugger, and the server keeps until close.

Files the debugger writes

memdump, trace and interrupt_vectors have the debugger write a file in the emulator's working folder, which is your project. A file already there is reported and left alone, never deleted, and a dangling link counts as a file. A dump that fails after the debugger wrote removes its own file.

The orange edge of the window

While a session is live the emulator's window has an orange edge, so a person at the computer knows it is in use. It is bright while a call that can change the program is in progress, and dim otherwise, even over a program resume left running. Once send_mouse has moved the program's pointer, an orange pointer marks it.

The emulator draws both after a frame is handed to capture, so no capture shows them and no tool that reads the screen sees them.

The tools: Session.

What every reply carries

Every reply has the same outer fields, whichever tool answers, so you read any answer the same way.

What each one is for:

The session block

session closes every reply. It says alive (the emulator is up), running (the program runs, not stopped at the debugger) and altered.

altered says something wrote to the machine. A write is allowed, and every later reply then says altered: true: a measurement on a forced value does not describe the program's own run. On a DOSBox-X built without heavy debugging, a code breakpoint is an INT 3 byte in memory, so setting one counts.

running is never a guess. When a resume got no answer, the server reads the state again. If that fails too, running is {"available": false, "why": "..."}, never true for a stopped machine.

A warning appears only while it holds:

A refusal

A refused call answers status: INVALID with code and message, and its context in plain fields beside them, such as last_stop.

A field that could not be read is {"available": false, "why": "..."} where its value would be; no reply carries a null. Every tool publishes its reply's shape as outputSchema, and its description says when a field comes only in some cases.

One name for each thing

How a wait ends

A tool that waits answers status: ok with a verdict:

A call that could not finish is a refusal with no verdict: wait_stopped, not_settled or session_broken.

seconds is more than zero and at most 600. resume's seconds and every settle_seconds, a sequence's wait for a stop, also take 0: no wait. The ceiling is there because no other tool answers during a wait, status included.

A long wait, and a cancelled call

A long wait reports progress about once a second, as MCP progress notifications.

A cancelled call answers nothing, since the protocol sends no response to one. It ends at the next check of its wait, as its own time limit would end it. Cancelling a step cancels its whole sequence.

The next reply says what it left, once, in summary and in cancelled: tool, after_s, left and earlier, the cancelled calls not yet reported. A call cancelled while it waited its turn did nothing and leaves no record.

End What the cancel leaves Tools
stop The program stopped by BREAK, as stop leaves it, and read in the next reply's last_stop. A run_to removes its own breakpoints. A trace's open CPU log is closed and kept as trace-cancelled-<n>.trace in the captures folder, else the working folder. stop, run_to, run_for, trace, screen_wait, record, audio_record, perform
kill The emulator closed. A close cancelled half-way still finishes. start, close
none The program as the call found it. build_check, status, log, log_wait, registers, read_memory, disassemble, call_stack, memdump, find, scan, debug, set_register, write, resume, wait, step, state_write, snapshot, state_list, breakpoint_interrupt, regpoint_add, symbols_load, symbols_find, comment_write, comment_list, machine_map, interrupt_vectors, palette, screen_view, screen_signature, screen_map_write, screen_map_find, series_capture, image_compare, audio_compare, breakpoint_at, declaration_list, declaration_clear, watch_add, send_keys, send_mouse, captures, capture_frame, perform_export, drive, port, pic, a20, guest_file, window, promote

Three tools of the last row still do something. A cancelled state_write ends at the emulator's next answer: a save removes its file, and a load counts as a write. Input sent to a stopped machine runs it frame by frame, and a cancel leaves it stopped with the input sent so far in.

The tools: every one in the Index.

Names for addresses

An address argument, ref in most tools, is a symbol of your program or a SEG:OFF, whatever mode the CPU is in.

Addresses in a reply

A segmented address is SSSS:OOOOOOOO, under seg_off, or address in a stop's instruction. A linear one is addr: 0x and eight digits. pc is segmented, with cpu_mode beside it.

A ref you give is matched and saved in upper case, as SSSS:OOOO up to FFFF and SSSS:OOOOOOOO past it: 814:10b is 0814:010B. One spelling stays the debugger's own, a breakpoint as its BPLIST shows it: run_to's target, a row's entry.

The tools: Names.

Breakpoints and watches

The server saves each breakpoint, watch and registerpoint as you asked for it, and sets it again in later sessions.

A registerpoint is a stop when a condition on the registers comes true.

What is saved between sessions

The tools: Breakpoints, Comments.

Running and stopping

The program is either stopped at the debugger or running, and the debugger reads the machine only while it is stopped.

start leaves it stopped. A running program stops at a breakpoint set before it was resumed, or at stop. The server invents no stop, and never gives memory it read earlier as a current value.

While it runs, a tool that reads the machine refuses not_stopped, with last_stop and answers_while_running. These answer:

A tool that answers may still refuse one of its modes while the program runs: its entry says which.

What you ask for while it runs is applied at the next stop, before anything is read. Until then a breakpoint answers pending, and the lists answer from what the server holds, with debugger_read: false. The reply that meets the stop says applied_on_stop.

A stop nobody waited for is reported once, in stopped_on_its_own, by the first tool that finds the program stopped.

What a stop returns

Every reply that ends at a stop carries the same readings:

cause names the saved breakpoint at that address, the registerpoint, a run_to's own target, your stop, or the time limit or frame a run ended at. Otherwise it says it cannot tell: a debugger row has no hit flag, and a memory watch stops just past the instruction that wrote.

e9 is cut to a limit, and its how gives the log call that reads the rest. Without start's logfile there are no lines.

A trace says which routines ran

trace gives each executed address a linear address, where the CPU mode allows one, and the nearest symbol at or below it. The symbol table has no sizes. So code above the last symbol gets no name, unless the table also lists the data after the code, as nm does.

A log line that says its own CPU mode is read in that mode. The others are read in the mode the stop shows at both ends of the trace. A line whose code segment cannot be read gets no linear address, and note says so.

A trace whose stop never comes is interrupted where it stood, and what its log holds up to there is returned. A log the machine closed first is refused, since its lines are not what ran.

The tools: Run.

Reading and writing

A tool that reads needs the program stopped and answers narrowly, so what comes back is the answer and little else.

The tools: Read, Write, Scan, and machine_map and interrupt_vectors on Machine.

The log

log and log_wait search one log of the session by pattern: what the program wrote, what the emulator wrote, or the DOS calls the program made.

The tools: Machine for log and log_wait.

The machine's hardware

port, pic and a20 type the debugger's own IN and OUT, PIC and A20 commands, to read and drive the hardware under a program.

The tools: Hardware.

Files inside DOS

A DOS program hands a result back as a file on a mounted drive, and the server tells you whether this run wrote it.

start(guest_files=[...]) notes each file's size, time and hash before the emulator boots, and guest_file and close then say what the program left. A file from an earlier run passes any "is it there" test, so one that did not change is unchanged and refused. Only new bytes or a new time make it written.

The check reads your computer's file. A file the program still holds open may lack its bytes, because the emulator keeps them until DOS closes it.

The tools: Files for guest_file.

Several calls as one

perform runs a list of calls in order as one call, and drive runs one and then waits for a line of the program's log.

The tools: Sequences.

From a session to a test that replays itself

A session can be written out as a list of steps and played back later with no model, as a test.

Every session is recorded from the start that succeeds; the next start clears the recording and close keeps it. perform_export writes it as a document, and this command replays it from this repository:

Shell
$ uv run python -m scry_core.replay <document> [--binary PATH] [--transcript PATH]

A step that left the program at a new stop is compared by its regs and its frame. A replay gives the same values on a config with fixed cycles, cycles=fixed <n>; under cycles=max the program's clock follows your computer's. The document carries start's arguments as given, your paths included.

The tools: Sequences.

The .scry/ folder

A repository can keep how a session starts on its program in a .scry/ folder it tracks, so a session gives only what belongs to its own run.

A session writes nothing there by itself. It saves what it learned as drafts; promote shows them for review and writes the ones you approve. Paths in these files use placeholders, by this rule, so a file reads the same on any computer.

Each draft belongs to one repository: the one a call read it from, else the one of the current start. That is its profile's repository, or the one its program runs in, by cwd or else the conf's folder. Without root, promote writes a draft only there, never into another repository or the server's own clone.

The tools: Project.

Input and the screen

Input goes in inside the emulated machine and the screen is read from its video memory, so neither depends on your window, keyboard or mouse.

The tools: Input, Captures, Screen, and screen_wait on Run.

Media files

The tools that answer about pictures and sound give the cheapest answer that settles the question.

A fingerprint or a number comes first: "is it the same screen" is two strings compared, never two pictures sent. The whole picture comes last, only from a tool made to show one. A sound is never sent, only its measures.

A tool that fingerprints or compares a picture takes a crop, [x, y, width, height]. One that leaves the picture is refused, never padded, since padding compares pixels nobody drew. A recording is cut by a window in seconds instead.

The tools: Captures, Files, Screen.

Screen maps

A screen map is a file that names a program's screens and the areas of each, so you say "the play screen" instead of a picture and a coordinate.

Its format is on the Read page.

The tools: Read for screen_map_find and screen_map_write, Input for send_mouse.

Saved states

A saved state needs the debugger commands SAVESTATE and LOADSTATE, which a build may lack.

On a build without them both methods of state_write are refused no_channel, naming the command. Debugger commands lists what each command gives.

The tools: States.

The debugger connection

Every reading and every command goes to DOSBox-X's debugger over one connection, a request at a time, and the debugger's screen is never read.

Debugger commands

Some tools need a debugger command a build may lack. build_check and start list the ones a build has, in debugger_commands. A tool that needs a missing one is refused no_channel, naming it, before anything acts.

Command What it gives Needed by
RUNSTATE Whether the program is stopped, and the frame count behind each stop's frame and perform's until_frame run_to, run_for, trace, screen_wait, record, audio_record, step(mode="over"), resume with seconds, input to a stopped machine, any reading after a resume
STEPIN One instruction run step
SAVESTATE, LOADSTATE A saved state state_write
PRESENCE The orange edge the edge itself
BPIF A stop on a register condition regpoint_add
VGAMEMDUMP Video memory as the card holds it screen_view, screen_signature in a planar, unchained or linear mode
CAPTURE A sound or video capture between stops record, audio_record
TAP Reads and writes logged without stopping watch_add with mode count or capture
PORTINFO Which accesses of a port reach a device port
DOSTRACE Every INT 21h, into a file log and log_wait on dos, start(dos_calls=True)
PIC, A20 The interrupt controllers, the A20 line pic, a20
MEMDUMPLIN Memory by linear address reads by linear address, send_mouse in protected mode

Without RUNSTATE a session still starts. Every reading answers at the stop start leaves, and input, breakpoints and snapshot work. resume with no seconds lets the program run, saying nothing will tell when it stops; stop brings it back.

The tools: Write for debug, Session for build_check.