SCRYMAMEReferenceSessionstartAlso in DOSBox-X

MAMESession

start

Start MAME on a system, stopped at the debugger, after checking that it runs the program your reference image holds.

start(system="", rompath="", reference_rom="", symbols="", reference_addr=0, inipath="", boot_seconds=8.0, shared=false, display=null, size=null, background=null, boot_lua="", env=null, bases=null, reference_base=0, stub_port=0, state_dir="", throttle_from_frame=0, types="", cfg="", binary="", presence=true, view="", profile="")

Try it

On Gridlee, a free ROM from mamedev.org. The example session starts it for a person to watch, with seven symbols and a reference image of the program ROM at 0xa000.
Ask

Start Gridlee in a window I can watch without losing my keyboard, with these symbols, checked against this image at 0xa000.

Call
start(shared=true, background=true, display="<host>", system="gridlee",
    reference_rom="./tmp/demos/tour/gridlee.ref", reference_addr="0xa000", reference_base="0xa000",
    inipath="./tmp/demos/tour/gridlee-ini", state_dir="./tmp/demos/tour/gridlee-states", … 3 more)
Reply 7 of 35 fields
{
  "status": "ok",
  "system": "gridlee",
  "rom_check": "OK",
  "symbols_total": 7,
  "pc": "0x0000f000",
  "frame": 0,
  "kept": "1 saved for `promote`; start/gridlee: nothing this session r ... (166 characters)"
}

The check passed, seven symbols are loaded and the machine is stopped at 0x0000f000 on frame 0. kept says the arguments were saved as a start profile, for promote to write into a repository.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "system": "gridlee",
  "binary": "<volatile>",
  "binary_origin": "<volatile>",
  "version": "0.289 (unknown)",
  "pid": "<volatile>",
  "stub_port": "<volatile>",
  "scratch_dir": "<volatile>",
  "state_dir": "./tmp/demos/tour/gridlee-states",
  "cfg": {"available": false, "why": "no cfg was given, so MAME runs on its defaults"},
  "debugger": {
    "attached": "gdbstub",
    "note": "MAME runs with -debug under this stub. A capture taken at one of this session's stops can land a frame away from an autoboot golden taken by a frame notifier at the same count, in a scene that changes every frame: compare a live capture wit ... (255 characters)"
  },
  "errorlog_path": "<volatile>",
  "stdout_path": "<volatile>",
  "rom_check": "OK",
  "symbols_total": 7,
  "symbols_typed": 2,
  "symbols_format": "yaml",
  "symbols_by_class": {},
  "symbols_by_cpu": {":maincpu": 7},
  "registers": ["A", "B", "D", "X", "Y", "U", "... 4 more"],
  "pc": "0x0000f000",
  "frame": 0,
  "frame_symbol": "frame",
  "view": "native",
  "views": ["Screen 0 Standard (4:3)", "Screen 0 Pixel Aspect (16:15)", "Cocktail"],
  "background": true,
  "flags": "<volatile>",
  "boot_lua_path": "<volatile>",
  "presence": true,
  "machine": {
    "cpus": 1,
    "spaces": 1,
    "address_map": 14,
    "regions": 3,
    "shares": 3,
    "screens": 1,
    "rom_files": 13
  },
  "declarations": {
    "persistent": true,
    "path": "./tmp/demos/tour/gridlee-states/declarations.json",
    "key": "gridlee ./docs/reference/tour/gridlee-symbols.yaml",
    "held": 0,
    "fingerprint": "9ddedcc4d2bcbc14",
    "rearm": {"rearmed": [], "stale": [], "unresolved": [], "unarmable": [], "evaluated": []},
    "comments": {"rearmed": [], "stale": [], "unresolved": [], "unarmable": []}
  },
  "recommended_release": "0.289",
  "window": "<volatile>",
  "kept": "1 saved for `promote`; start/gridlee: nothing this session read names its repository: promote(dry_run=true, root=<the repository>) lists what an approval would create"
}

Arguments

system string, default ""
The system to run, by MAME's short name. Required unless a start profile gives it.
rompath string, default ""
The folders that hold the system's ROMs, separated by ;. Required unless a start profile gives it.
reference_rom string, default ""
A binary image of the program you expect to be running, which the machine's memory is compared with. Required unless a start profile gives it.
symbols string or object, default ""
A symbol file, so an address can be given by name: a YAML file or the linker's five-column map. One path is the first cpu's; {cpu: path} gives one per cpu.
reference_addr integer or string, default 0
The address where 16 bytes of the machine are compared with the image: an integer or a 0x string. Left out, 0.
inipath string, default ""
The folders MAME reads its .ini files from, separated by ;. Left empty, MAME's own.
boot_seconds number (> 0, <= 600.0), default 8.0
How long to wait for MAME's debugger to answer, in seconds. Left out, 8.
shared boolean, default false
true when a person watches: a large window at real speed. Left out, a small window that runs unthrottled.
display integer, optional
Which display the window opens on, by the operating system's index. Needs shared=true; left out, 0, the main display.
size string, optional
The window's size as WIDTHxHEIGHT, in the host's unit. Needs shared=true; left out, the largest whole multiple of the screen that fits the display.
background boolean, optional
true opens the window behind your other windows and leaves the keyboard focus where it is; false opens it in front. Left out, behind unless shared.
boot_lua string, default ""
A Lua file MAME runs at boot, after the server's own script. It is a path, never Lua text.
env object, optional
Environment variables for MAME's own process, as {name: value}. They are there for what boot_lua reads.
bases object, optional
For a linker's map: the address each class other than CODE is based at, as 0x text or an integer, or rom. With per-cpu symbols, {cpu: {class: base}}.
reference_base integer or string, default 0
The address of the image's first byte. Left out, 0.
stub_port integer (>= 0, <= 65535), default 0
The TCP port of MAME's gdbstub, the remote-debugger connection this server uses. Left at 0, a free port is picked.
state_dir string, default ""
The folder for saved states, cfg/ and nvram/, which stays after close. Left empty, the session's temporary folder, deleted at close.
throttle_from_frame integer, default 0
Runs unthrottled until this frame and at real speed from it on, with either kind of window. Left at 0, the speed follows shared.
types string or object, default ""
A file of name: format lines, one per symbol whose value has a format. With per-cpu symbols, {cpu: file}.
cfg string, default ""
A .cfg file the server installs as the system's own before it boots. Left empty, MAME runs on its defaults.
binary string, default ""
The MAME to run: an executable, or a .app bundle holding one. Left empty, MAME_BINARY, else the mame on the PATH.
presence boolean, default true
Draws a border around the emulator's window while the session is open, brighter while a call runs the machine. false leaves it off.
view string, default ""
What snapshot and record draw. Left empty, the emulated screen at its own size; else one of MAME's layout views, named by how its name begins.
profile string, default ""
A start profile: a saved set of start arguments, by its name under .scry/start/ or by a path. It fills only the arguments the call leaves out.

What comes back

rom_check
OK when the 16 bytes read from the machine equal the image's. A start whose check fails is refused.
pc
Where the machine stands, stopped.
window
With shared, where the window is. Its front is true when no other application's window covers its centre; it does not mean the window has the keyboard focus.
profile
With a start profile: its name, its file, and supplied, the arguments it filled.
kept
Says that this start's arguments were saved as a start profile for promote, the tool that writes one into your repository's .scry/ folder.
start_retries
Present when MAME had to be launched more than once: what each earlier attempt left.
All 50 reply fields
  • activation (string)
  • asked_display (integer)
  • seen (object)
  • searched (array)
  • kept (string)
  • after_s (number)
  • alive (boolean)
  • background (boolean)
  • binary (string)
  • binary_origin (string)
  • boot_lua_path (string)
  • bundle (string)
  • cfg (object)
  • debugger (object)
  • declarations (object)
  • dial_attempts (array)
  • env (object)
  • error (string)
  • errorlog_path (string)
  • flags (array)
  • frame (integer or object)
  • frame_symbol (string or object)
  • machine (object)
  • pc (string)
  • phase (string)
  • pid (integer)
  • presence (boolean)
  • profile (object)
  • recommended_release (string)
  • registers (array)
  • reply (string)
  • rom_check (string)
  • scratch_dir (string)
  • start_retries (array)
  • state_dir (string)
  • stdout_kept (string)
  • stdout_path (string)
  • stdout_tail (string)
  • stub_port (integer)
  • symbols_by_class (object)
  • symbols_by_cpu (object)
  • symbols_format (string)
  • symbols_total (integer)
  • symbols_typed (integer)
  • system (string)
  • throttle_from_frame (integer)
  • version (string or object)
  • view (string or object)
  • views (array or object)
  • window (object)

What it refuses

Why it works this way

Before it answers, start reads 16 bytes of the machine at reference_addr and compares them with reference_rom. If they differ, MAME is not running the program your addresses describe. The session is then closed, because one left open would answer the next call about another program.

shared says whether a person watches. Without it MAME opens a small window, unthrottled and behind your other windows, which window cannot report. With it the window opens on display, in front and at real speed; add background=true to watch without losing the keyboard focus.

A start profile is a file of start arguments, .scry/start/<name>.json in a repository, so a session starts with start(profile="<name>"). The call's own arguments win and the profile fills the rest. The .scry/ folder is looked for upwards from the server's working directory, then from rompath and binary.

More on why
you want arguments the window
Nobody watching shared=false, the default Small, unthrottled, behind. window refuses it as no_channel.
Somebody watching shared=true, with display and size if wanted On the display, in front, at real speed, confirmed in the host's window list.
Watching and keeping the keyboard focus shared=true, background=true The same, opened behind your other windows.

The window's size.

A watched window is the largest whole multiple of the machine's first screen that fits the display's usable area. The window's frame counts; the menu bar, Dock and taskbar do not. MAME draws the picture at the view's aspect and scales it by whole pixels, so it is letterboxed where the view's shape is not the screen's.

size wins over that fit, in the host's unit: points on macOS, real pixels on Windows. One that does not fit is refused, naming the usable size. One that is not a whole multiple of the screen is scaled unevenly, and the note says so.

start waits until the host lists the window on that display. A watched window is not supported on Linux. Do not select -video none yourself: on macOS it takes over the display.

background only chooses where the window opens. How the focus stays with you is the host's: on macOS the emulator starts as a background application, and on Windows no program may take the foreground while start launches. A click or ALT moves the focus as always.

Fast-forward to a late scene.

throttle_from_frame=N runs unthrottled to frame N, then at real speed, and logs MAME_MCP throttled from frame N. Waiting for that line with log_wait also restarts the span close measures average_speed over, so the speed is the real-speed part alone. It is fixed at launch; throttle switches the speed of an open session.

The boot.

  • A MAME that exits while start waits ends the wait at once, and the refusal gives its exit code.
  • One still alive when boot_seconds runs out is session_broken; stdout_kept is a saved copy of what it printed.
  • A crash by a signal before the debugger answers, or a port another process took first, is launched again a few times. start_retries lists the attempts.
  • An exit code (missing ROMs, an unknown system, a bad option) would come again, so it is refused at once.
  • A MAME that dies after start answered is never launched again.
  • An unknown system is refused in MAME's own words: after the launch, or before it on a shared start or with per-cpu symbols.
  • A gdbstub that does not describe the board's first cpu is no_channel: that MAME build cannot serve the board.
  • Another process listening on a stub_port you named is host_failed, naming its pid.
  • start connects once, after MAME prints its debugger banner. A build that never prints it costs every start its whole boot_seconds.

Symbols and files.

  • A symbol file belongs to one cpu, because each cpu runs its own program. With {cpu: path}, bases and types are per cpu too, and the single shape is refused.
  • symbols_total, symbols_typed, symbols_format and symbols_by_class describe the first cpu's file; symbols_by_cpu counts each.
  • boot_lua runs after the server's own boot script, so boot_lua_path is the combined script. One that calls manager.machine:exit() ends the machine under the session.
  • With state_dir empty, saved states, cfg/ and nvram/ live in the temporary folder scratch_dir names. Nothing is written into your project either way.
  • cfg is copied to where MAME reads it; your file is never touched. MAME reports a rejected .cfg on stderr only, so the server reads that and refuses the start.
  • A type: line under a YAML symbol, or a types line, says what the symbol is, so a watch needs no fmt. A pointer's type names what it points at.

What else the reply says.

  • version is the build's own -version line and recommended_release the MAME version this server is tested on. Another version starts with a note, never a refusal.
  • debugger.note: the machine runs under the debugger, so a capture at a stop can land one frame from a reference capture an autoboot script took at the same frame count.
  • machine holds counts only; machine_map has the rows. If MAME's -listxml fails, the start still works and the note says what is left empty.
  • frame_symbol is the name the frame counter answers to; a board with no screen has none (Run).
  • flags, env, view, background, binary_origin, errorlog_path and stdout_path say what the launch used, so a start can be told from another by its own reply.
  • presence is true while the border is drawn. A failure drawing it never changes another reply: presence, here and in status, turns available: false with a why.
The contract your client receives
Text
Start MAME with its gdbstub, parked STOPPED and checked against the reference image.

Paths are absolute or `~`-led: `rompath` and `inipath` `;`-separated directories, `state_dir`
a directory, the rest files. `binary` names a MAME executable or a `.app` bundle carrying
one: the bundle is launched through `open`, which makes it an application the host captures
as one, and the reply names it in `bundle`; its exit status is then not this server's to
know, and `close` answers `unavailable` for it. The check: `reference_rom`, `reference_addr`,
`reference_base` (the image's first byte).
`symbols`, `bases`, `types`: one value, or `{cpu: ...}` per cpu.
`shared=True`: somebody watches (a window of the largest whole multiple of the screen that
fits the display's usable area, drawn at the view's aspect, real speed); false, nobody
watches: a small window run flat out. `display`: the OS's
display index for that window, 0 (the main display) when omitted; `size`:
`WIDTHxHEIGHT` of the window in the host's unit, which wins over the fit (a size that is not a
whole multiple of the screen is scaled by whole pixels, unevenly, and the reply's `note` says
so). Both
need `shared=True` and are refused otherwise; `size` is also refused when it, with its frame,
exceeds the display's usable area, naming that size; a `display` past the host's count is
refused naming the count. The server waits for the window to be
listed on that display and answers `window`; a later `window` judges a stated size.
`background`: launch behind, keeping the caller's focus, or in front, either window; omitted
it is behind unless `shared`; somebody watching without losing their focus is `shared=True`
with `background=True`. `throttle_from_frame`: flat out until that frame, real speed after,
either window.
`boot_lua`: a harness file, not Lua text. `boot_seconds`: the wait for MAME's first prompt.
`env`: variables MAME's own process gets. `cfg`: a `.cfg` file the server installs as the
system's own before it boots, judged for what MAME would refuse in silence.

`profile`: a repository's run recipe (`.scry/start/<name>.json`) or a path to one. Its keys
are this tool's arguments and fill only what the call does not give; the reply's `profile`
block names it and what it filled. The store is looked for from the server's working
directory, then `rompath` and `binary`.

Refused before MAME boots: a live session (`session_live`), an unknown cpu, a class with no
base, `bases` beside a YAML file, a bad `types` line, a busy `stub_port`, a `reference_addr`
outside the image (a `shared` start first asks MAME `-listxml`, whose time comes before that
refusal), a `profile` that no directory above holds (the refusal names them).
A mismatch: `readback_refused`, closed. A window that never appears on the asked display:
`window_not_visible`, the session left live to `window` or `close`.

Reply: `system`, `pid`, `window` (`display`, `bounds`, `onscreen`, `front`, `fullscreen`, with
`shared`; `front` says no other application's window covers its centre, not that it has the keyboard focus), `stub_port`, `rom_check`, `pc`, `frame`, `start_retries`,
`recommended_release` (0.289), with a profile `profile` (`name`, `file`,
`supplied`), and `kept` when the recipe is complete and the draft holds it; another release
boots with a `note` saying so.

Reference: REFERENCE.md, The session.

presence: Draw an edge around the emulator's window while this session is open: dim while idle, bright while a call runs the machine. No capture of this server carries it.

view: What `snapshot` and `record` render through: empty, the emulated screen at its own size; else a layout view by prefix (`views` lists them, `view` says which was taken).
Tools