SCRYMAMEReferenceSessionstartAlso in DOSBox-X
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
0xa000.Start Gridlee in a window I can watch without losing my keyboard, with these symbols, checked against this image at 0xa000.
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){
"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
{
"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
0xstring. Left out, 0. - inipath string, default
"" - The folders MAME reads its
.inifiles 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 truewhen 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. Needsshared=true; left out, the largest whole multiple of the screen that fits the display. - background boolean, optional
trueopens the window behind your other windows and leaves the keyboard focus where it is;falseopens it in front. Left out, behind unlessshared.- 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 whatboot_luareads. - bases object, optional
- For a linker's map: the address each class other than CODE is based at, as
0xtext or an integer, orrom. With per-cpusymbols,{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/andnvram/, which stays afterclose. Left empty, the session's temporary folder, deleted atclose. - 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: formatlines, one per symbol whose value has a format. With per-cpusymbols,{cpu: file}. - cfg string, default
"" - A
.cfgfile 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
.appbundle holding one. Left empty,MAME_BINARY, else themameon 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.
falseleaves it off. - view string, default
"" - What
snapshotandrecorddraw. 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
startarguments, by its name under.scry/start/or by a path. It fills only the arguments the call leaves out.
What comes back
- rom_check
OKwhen 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. Itsfrontistruewhen 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, itsfile, andsupplied, 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
- A session is already open (
session_live). - The 16 bytes differ from the image's; the session is closed (
readback_refused). system,rompathorreference_romgiven neither by the call nor by a start profile, a path that is not absolute, or a folder where a file is expected (bad_argument).- A
reference_addroutside the image, astub_portthat is not free, or acfgMAME would not read (bad_argument). - Per-cpu
symbols,basesortypesnaming a cpu the machine does not have (unknown_ref). - A class of a linker's map with no base,
basesbeside a YAML file, or a bad line intypes(bad_argument). - A
state_dirthat is the server's own folder for the saved breakpoints file, directly or through a link: a session with astate_dirkeeps its own (bad_argument). displayorsizewithoutshared=true, adisplaythe host does not have, or asizelarger than the display's usable area (bad_argument).- A
profilethat no.scry/folder searched holds;searchedlists them (bad_argument). - A window that never appears on the display asked for. The session stays open for
windoworclose(window_not_visible). - A MAME that exits or never answers during the boot (
session_broken).
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
startwaits ends the wait at once, and the refusal gives its exit code. - One still alive when
boot_secondsruns out issession_broken;stdout_keptis 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_retrieslists 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
startanswered is never launched again. - An unknown
systemis refused in MAME's own words: after the launch, or before it on asharedstart or with per-cpusymbols. - 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_portyou named ishost_failed, naming its pid. startconnects once, after MAME prints its debugger banner. A build that never prints it costs every start its wholeboot_seconds.
Symbols and files.
- A symbol file belongs to one cpu, because each cpu runs its own program. With
{cpu: path},basesandtypesare per cpu too, and the single shape is refused. symbols_total,symbols_typed,symbols_formatandsymbols_by_classdescribe the first cpu's file;symbols_by_cpucounts each.boot_luaruns after the server's own boot script, soboot_lua_pathis the combined script. One that callsmanager.machine:exit()ends the machine under the session.- With
state_dirempty, saved states,cfg/andnvram/live in the temporary folderscratch_dirnames. Nothing is written into your project either way. cfgis copied to where MAME reads it; your file is never touched. MAME reports a rejected.cfgon stderr only, so the server reads that and refuses the start.- A
type:line under a YAML symbol, or atypesline, says what the symbol is, so a watch needs nofmt. A pointer's type names what it points at.
What else the reply says.
versionis the build's own-versionline andrecommended_releasethe MAME version this server is tested on. Another version starts with anote, 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.machineholds counts only;machine_maphas the rows. If MAME's-listxmlfails, the start still works and thenotesays what is left empty.frame_symbolis the name the frame counter answers to; a board with no screen has none (Run).flags,env,view,background,binary_origin,errorlog_pathandstdout_pathsay what the launch used, so a start can be told from another by its own reply.presenceistruewhile the border is drawn. A failure drawing it never changes another reply:presence, here and instatus, turnsavailable: falsewith awhy.
Related tools
The contract your client receives
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).