SCRYMAMEReferenceMachinemachine_mapAlso in DOSBox-X
machine_map
Get the layout of the machine: its cpus and their address spaces, the address map, memory regions and shares, screens and ROM files.
machine_map(cpu="", sections=null, dest="")
Try it
start.What is this board made of: its cpu, its ROMs, its RAM, its screen?
machine_map(){
"regions": [
{"tag": ":gfx1", "size": 16384, "bytewidth": 1, "endianness": "little"},
{"tag": ":maincpu", "size": 65536, "bytewidth": 1, "endianness": "big"},
{"tag": ":proms", "size": 6144, "bytewidth": 1, "endianness": "little"}
],
"shares": [
{"tag": ":nvram", "size": 256, "bytewidth": 1, "endianness": "big"},
{"tag": ":spriteram", "size": 2048, "bytewidth": 1, "endianness": "big"},
{"tag": ":videoram", "size": 30720, "bytewidth": 1, "endianness": "big"}
]
}regions are the ROMs MAME loaded and shares the blocks of RAM the board's devices share, each with its size in bytes. The sprite RAM is 2048 bytes.
The whole reply
{
"summary": "machine_map: 1 cpu, 1 space, 14 address map entries, 3 regions, 3 shares, 1 screen, left out: rom_files (see `omitted`)",
"status": "ok",
"cpus": [
{
"cpu": ":maincpu",
"name": "MC6809 (legacy)",
"clock_hz": 1250000,
"type": "m6809",
"spaces": ["program"]
}
],
"spaces": [
{
"cpu": ":maincpu",
"space": "program",
"data_width_bits": 8,
"endianness": "big",
"entries": 14,
"address_mask": "0x0000ffff"
}
],
"address_map": [
{
"cpu": ":maincpu",
"space": "program",
"index": 1,
"start": "0x00000000",
"end": "0x000007ff",
"share": ":spriteram"
},
{
"cpu": ":maincpu",
"space": "program",
"index": 2,
"start": "0x00000800",
"end": "0x00007fff",
"share": ":videoram"
},
{"cpu": ":maincpu", "space": "program", "index": 3, "start": "0x00009000", "end": "0x00009000"},
{"cpu": ":maincpu", "space": "program", "index": 4, "start": "0x00009200", "end": "0x00009200"},
{"cpu": ":maincpu", "space": "program", "index": 5, "start": "0x00009380", "end": "0x00009380"},
{"cpu": ":maincpu", "space": "program", "index": 6, "start": "0x00009500", "end": "0x00009501"},
"... 8 more"
],
"regions": [
{"tag": ":gfx1", "size": 16384, "bytewidth": 1, "endianness": "little"},
{"tag": ":maincpu", "size": 65536, "bytewidth": 1, "endianness": "big"},
{"tag": ":proms", "size": 6144, "bytewidth": 1, "endianness": "little"}
],
"shares": [
{"tag": ":nvram", "size": 256, "bytewidth": 1, "endianness": "big"},
{"tag": ":spriteram", "size": 2048, "bytewidth": 1, "endianness": "big"},
{"tag": ":videoram", "size": 30720, "bytewidth": 1, "endianness": "big"}
],
"screens": [
{
"tag": ":screen",
"width": 256,
"height": 240,
"refresh_hz": 59.185606,
"rotation": 0,
"type": "raster"
}
],
"symbol_coverage": [],
"counts": {
"cpus": 1,
"spaces": 1,
"address_map": 14,
"regions": 3,
"shares": 3,
"screens": 1,
"symbol_coverage": 0
},
"truncated": false,
"sources": {
"cpus": ["live", "-listxml"],
"spaces": ["live"],
"address_map": ["live"],
"regions": ["live"],
"shares": ["live"],
"screens": ["live", "-listxml"],
"symbol_coverage": ["symbols"]
},
"note": "the address map is the map of the machine's EXECUTING devices, which is what MAME gives a debugger: a device that only exposes an address space of its own is not in it, though its shares and regions are; the map reported is the STATICALLY C ... (844 characters)",
"omitted": ["rom_files"],
"how": "sections=[...] names the sections to read; dest=<absolute path> writes every section read whole",
"frame_symbol": "frame",
"cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}Arguments
- cpu string, default
"" - The tag of one cpu, to narrow
cpus,spaces,address_mapandsymbol_coverageto it. Left empty, every cpu's rows come back. - sections array of one of
"cpus","spaces","address_map","regions","shares","screens","rom_files","symbol_coverage", optional - Which sections to read. Left out, all of them but
rom_files. - dest string, default
"" - A file to write every row of the sections read, as JSON: an absolute or
~path that does not exist yet. Left empty, no file is written.
What comes back
- cpus
- One row per cpu: its tag
cpu, MAME's short nametype,name,clock_hzand the names of itsspaces. - address_map
- One row per entry of a cpu's memory map:
cpu,space,index,start,end, and theshareorregionbehind it. - sources
- For each section, where its rows came from:
live(the running machine),-listxml(MAME's own description of it) orsymbols(your symbol table). - counts
- How many rows each section has in full, so a list cut short shows.
- truncated
truewhen a section had more than 400 rows and its list was cut;destgets them all.- path
- With
dest, the file that was written.
All 14 reply fields
address_map(array)counts(object)cpu(string or object)cpus(array)frame_symbol(string or object)path(string)regions(array)rom_files(array)screens(array)shares(array)sources(object)spaces(array)symbol_coverage(array)truncated(boolean)
What it refuses
- An empty
sections, a name that is no section, or adestthat already exists (bad_argument). - A tag that names no cpu; the message lists the ones the machine has (
unknown_ref). - A call with no session open (
no_session). - A session that broke and has to be closed (
session_broken).
Why it works this way
The map is read once, while start boots the machine, so asking costs nothing and it answers while the program runs. It is the machine as start found it: nothing reads it again, even after the emulator has died.
Two sources fill it, because neither has everything. MAME's -listxml, run on this session's own binary, alone knows a clock, a screen's rotation and a ROM file's checksums. The running machine alone knows the shares, the region sizes, the address map and a cpu's type.
Where the two disagree the field carries the running machine's value, and note names both. A field neither source has is absent, never null or guessed.
More on why
The address map covers the devices that execute, the ones MAME gives a debugger. It is the map as wired: a banked range answers for whichever bank is selected at the time.
spaces:cpu,space,data_width_bits,endianness,entries,address_mask.address_map: alsoregion_offsetbeside aregion, and the entry's ownmirrorandaddress_maskwhen not zero. Ashareorregioncarries the tagsharesandregionslist it under.regionsandshares:tag,size,bytewidth,endianness.screens:tag,width,height,refresh_hz,rotation,type.rom_files:name,size,crc,sha1,dump_status,region,offset. It is left out by default because it answers a ROM audit, not a debugging question.symbol_coverage: one row per class of each cpu's symbol table, withclass,cpu,span(from,length),symbolsandbase. It is empty when the table has no classes.cpuleaves the regions, shares, screens and ROM files whole: they are the board's, and a shorter list would say the other cpu's ROMs do not exist.- When
-listxmlfails,rom_files, the clocks and the rotation are empty andnotequotes why. frame_symbolnames the machine's frame counter, unavailable on a board with none.omittedandhowname the sections left out and how to ask for them.
Related tools
The contract your client receives
What the machine is: its cpus and spaces, address map, regions, shares, screens and ROM
files. Cached at `start()`, free; answered on a running machine.
Arguments: `cpu`, a tag in either spelling, narrows `cpus`, `spaces`, `address_map` and
`symbol_coverage`. `sections` picks sections; left out, all but `rom_files`. `dest`
(absolute or `~`-led, new) writes every row of the sections read as JSON.
Refused: an empty or unknown `sections`, or an existing `dest` (`bad_argument`); an unknown
tag (`unknown_ref`); no machine (`no_session`); a broken session (`session_broken`).
Reply: `cpus`, `spaces`, `address_map`, `regions`, `shares`, `screens`, `rom_files`,
`symbol_coverage`, `counts`, `truncated` (lists cut to 400 rows; `dest` holds all),
`sources`,
`path` (with `dest`), `note`, `frame_symbol`. A field no source backs is absent.
Reference: REFERENCE.md, Reading and writing.