SCRYDOSBox-XReferenceMachinemachine_mapAlso in MAME

DOSBox-XMachine

machine_map

Get the layout of the DOS machine at this stop: its memory blocks, device drivers, extended memory handles and the cpu's control registers.

machine_map(sections=null, dest="")

Try it

On Bricks, the game this repository builds, stopped at its play screen.
Ask

List the blocks of memory DOS holds right now.

Call
machine_map(sections=["mcbs"])
Reply 4 of 10 fields
{
  "cpu_mode": "real",
  "counts": {"mcbs": 9},
  "sources": {"mcbs": ["DOS MCBS"]},
  "truncated": false
}

In real mode the debugger's DOS MCBS listing gave 9 memory blocks, and none was cut from the reply. Their rows are too long to show here: the whole reply, below, has them.

The whole reply
JSON
{
  "summary": "machine_map (real): 9 mcbs, left out: devs, kern, xms, ems, ems_pages, bios_mem, callbacks, emu_mem, machine, control, vga (see `omitted`)",
  "status": "ok",
  "cpu_mode": "real",
  "mcbs": [
    {
      "memory": "conventional",
      "mcb_seg": "0450",
      "size_bytes": 10992,
      "psp_seg": "0008",
      "notes": "DOS",
      "filename": "\"\u0005"
    },
    {
      "memory": "conventional",
      "mcb_seg": "0700",
      "size_bytes": 2464,
      "psp_seg": "0701",
      "filename": "COMMAND"
    },
    {
      "memory": "conventional",
      "mcb_seg": "079B",
      "size_bytes": 720,
      "psp_seg": "0701",
      "filename": "COMMAND"
    },
    {
      "memory": "conventional",
      "mcb_seg": "07C9",
      "size_bytes": 1168,
      "psp_seg": "0814",
      "filename": "SCRY"
    },
    {
      "memory": "conventional",
      "mcb_seg": "0813",
      "size_bytes": 2048,
      "psp_seg": "0814",
      "filename": "SCRY"
    },
    {
      "memory": "conventional",
      "mcb_seg": "0894",
      "size_bytes": 1168,
      "psp_seg": "08DF",
      "filename": "BRICKS"
    },
    "... 3 more"
  ],
  "counts": {"mcbs": 9},
  "sources": {"mcbs": ["DOS MCBS"]},
  "coverage_note": "read from the debugger's own listings at this stop. `gdt` and `ldt` are absent: the cpu is in real mode, where the debugger reads the interrupt vector table as descriptors. `paging` is absent: paging is off",
  "truncated": false,
  "omitted": ["devs", "kern", "xms", "ems", "ems_pages", "bios_mem", "... 5 more"],
  "how": "sections=[...] names the sections to read; dest=<absolute path> writes every section read whole"
}

Arguments

sections array of one of "mcbs", "devs", "kern", "xms", "ems", "ems_pages", "bios_mem", "callbacks", "emu_mem", "machine", "control", "gdt", "ldt", "paging", "vga", optional
Which sections to read. Left out, all of them but bios_mem, callbacks, paging and vga.
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

cpu_mode
real, protected or paged, read from the control register cr0. It decides which sections exist.
mcbs
DOS's chain of memory blocks, one row each: memory, mcb_seg, size_bytes, psp_seg, notes, filename.
coverage_note
Why each absent section is absent: the mode has none, or the debugger's listing could not be read.
sources
For each section, the debugger command its rows came from.
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.
All 21 reply fields
  • bios_mem (array)
  • callbacks (array)
  • control (object)
  • counts (object)
  • coverage_note (string)
  • cpu_mode (string or object)
  • devs (array)
  • ems (array)
  • ems_pages (array)
  • emu_mem (object)
  • gdt (array)
  • kern (array)
  • ldt (array)
  • machine (string)
  • mcbs (array)
  • paging (array)
  • path (string)
  • sources (object)
  • truncated (boolean)
  • vga (object)
  • xms (array)

What it refuses

Why it works this way

Each section is one listing of the debugger, read whole. A section the debugger refused, or printed in a form the server does not know, is absent, never partial. A chain of memory blocks with one block skipped would read as the whole chain.

Which sections exist depends on the cpu mode. In real mode gdt and ldt are absent, because there the debugger reads the interrupt vector table as descriptors; paging exists only with paging on.

cpu_mode comes from cr0, which cannot tell virtual 8086 mode from protected mode. At such a stop it says protected where the stop's own reply and status say VM86.

More on why
  • mcbs: a free block has a psp_seg of 0000 and keeps in filename the old name DOS left there.
  • The chain in mcbs is checked by its sizes, each block right after the one before; a chain that fails is absent.
  • devs: header, attr, strat, intr, name.
  • kern: seg, size_bytes, what.
  • xms: handle, status, location, size_bytes.
  • ems: handle, addr, size_bytes, name. ems_pages: handle, page, start, end.
  • bios_mem: start, end, status, what. callbacks: number, desc.
  • control: cr0, cr2, cr3, cpl, eflags, vm, iopl, nt, gdtr, idt, tr, ldtr.
  • gdt and ldt: selector, base, limit, type, dpl, p, a, r, b, g.
  • paging: runs of pages next to each other in linear and physical memory with the same flags: start, end, phy, flags, d, a.
  • vga: mode, crtc, seq, gc, ac, dac, draw.
  • emu_mem holds the emulator's memory listing, a key per line; machine is the emulated machine's name.
  • Each listing is one exchange with the debugger. omitted and how name the sections of this mode that were not read.
  • When the listing behind control cannot be read, cpu_mode is unavailable and gdt, ldt and paging are absent.
The contract your client receives
Text
What the DOS machine is at this stop: one section per debugger listing. `sections` left
out reads the DOS machine, `control` (the control registers, the flags and the
descriptor-table and task registers) and, in protected mode, `gdt` and `ldt` (the tables'
rows); `bios_mem`, `callbacks`, `vga`, `paging` only when named. `dest` (absolute or `~`-led,
new) writes every row of the sections read as JSON. Writes nothing to the guest.

Reply: `cpu_mode`, one key per section read as rows, `counts`, `truncated` (cut at
400 rows), `sources`, `coverage_note` (why a section is absent), `path` (with
`dest`). Refused: bad `sections` or an existing `dest` (`bad_argument`); a running guest
(`not_stopped`).

Reference: REFERENCE.md, Reading and writing.
Tools