SCRYMAMEReferenceMachinemachine_mapAlso in DOSBox-X

MAMEMachine

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

On Gridlee, a free ROM from mamedev.org, stopped at reset, right after start.
Ask

What is this board made of: its cpu, its ROMs, its RAM, its screen?

Call
machine_map()
Reply 2 of 17 fields
{
  "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
JSON
{
  "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_map and symbol_coverage to 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 name type, name, clock_hz and the names of its spaces.
address_map
One row per entry of a cpu's memory map: cpu, space, index, start, end, and the share or region behind it.
sources
For each section, where its rows came from: live (the running machine), -listxml (MAME's own description of it) or symbols (your symbol table).
counts
How many rows each section has in full, so a list cut short shows.
truncated
true when a section had more than 400 rows and its list was cut; dest gets 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

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: also region_offset beside a region, and the entry's own mirror and address_mask when not zero. A share or region carries the tag shares and regions list it under.
  • regions and shares: 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, with class, cpu, span (from, length), symbols and base. It is empty when the table has no classes.
  • cpu leaves 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 -listxml fails, rom_files, the clocks and the rotation are empty and note quotes why.
  • frame_symbol names the machine's frame counter, unavailable on a board with none. omitted and how name the sections left out and how to ask for them.
The contract your client receives
Text
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.
Tools