SCRYDOSBox-XReferenceMachinemachine_mapAlso in MAME
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
List the blocks of memory DOS holds right now.
machine_map(sections=["mcbs"]){
"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
{
"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,pagingandvga. - 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,protectedorpaged, read from the control registercr0. 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
truewhen a section had more than 400 rows and its list was cut;destgets 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
- An empty
sections, a name that is no section, or adestthat already exists (bad_argument). - A program that is running: the listings are read at a stop (
not_stopped). - A listing longer than the debugger hands back in one reply: it would come back cut (
unexpected_answer).
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 apsp_segof0000and keeps infilenamethe old name DOS left there.- The chain in
mcbsis 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.gdtandldt: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_memholds the emulator's memory listing, a key per line;machineis the emulated machine's name.- Each listing is one exchange with the debugger.
omittedandhowname the sections of this mode that were not read. - When the listing behind
controlcannot be read,cpu_modeis unavailable andgdt,ldtandpagingare absent.
Related tools
The contract your client receives
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.