SCRYMAMEReferenceTimelinepalette_log
palette_log
Find which code set a pen's colour on a board whose palette cannot be read back, by logging every write to its palette ports.
palette_log(palette_port, pen=null, limit=16, clear=false, arm=false)
Try it
Start logging every write to this board's palette ports, so I can ask later which code set a pen.
palette_log(palette_port="ramdac", arm=true){
"summary": "palette_log ramdac: armed, installed when the console next reads a line",
"protocol": "ramdac",
"index_port": "0x00720001",
"data_port": "0x00720003",
"installed": false,
"pending": true
}The log is armed on the two ports of the entry ramdac, an index port and a data port. It is not installed yet (pending): that happens when the console next reads a line, and it records from there.
The whole reply
{
"summary": "palette_log ramdac: armed, installed when the console next reads a line",
"status": "ok",
"palette_port": "ramdac",
"palette": "palette",
"cpu": ":maincpu",
"space": "program",
"protocol": "ramdac",
"index_port": "0x00720001",
"data_port": "0x00720003",
"order": "rgb",
"component_bits": 8,
"pen_range": [0, 255],
"armed_now": true,
"tally_id": "ramdac_720001_1_720003",
"installed": false,
"pending": true,
"lines_ahead": 0,
"call": "MAME_MCP_LUA_END#15",
"note": "the tap is installed when the console next reads a line (a step, the next frame emulated, or a debugger command on a stub that refreshes after one) and counts from there; the survey of the stop after that reads it back",
"not_proved": ["palette_ports.ramdac"]
}Arguments
- palette_port string, required
- The name of an entry under
palette_portsin the loadedgfx.yaml. - pen integer or string, optional
- Show this pen alone: its state and the rows that wrote it. Left out, the reply lists the writers of every pen.
- limit integer (>= 0, <= 256), default
16 - How many of the newest rows the reply shows, 0 to 256. Left out, 16.
- clear boolean, default
false trueremoves the log.- arm boolean, default
false truestarts the log. Without it the call reads the log, and never starts one.
What comes back
- installed
falseon the call that arms it. The log is installed when the console next reads a line, at a step or the next frame run, and records from there.- state
- Once armed:
loggedwhen there is a table to read. Otherwiseno_dump_yet,install_failedorinstall_lost, withwhy. - writes_total
- Every write the log saw.
unsynced_writeslanded while the device's index was not known, anddesyncscounts the times it was lost. - setters
- Without
pen, the first 32 writers, most pens first:pc,symbol,written_by, how manypens_setandwhich.setters_pathholds them all. - pen_state
- With
pen: itscolor, whether it iscomplete, itscomponents, itswrites_totaland thelastwrite. - rows
- The newest
limitrows in order, each withn,frame,pc,written_by, the screenline,time_s, and thepen,component,valueandcolorit left.
All 46 reply fields
across(array)armed_now(boolean)call(string)callback_errors(object)cleared(boolean)component_bits(integer)cpu(string)cpus_with_io(array)data_port(string)desyncs(integer)frame_as_of(integer)index_port(string)index_writes(integer)install_resent(integer)installed(boolean)lines_ahead(integer)not_proved(array)order(string)overflow_rows(integer)palette(string)palette_port(string)palette_ports(array)partial_writes(integer)pen_range(array)pen_state(object)pending(boolean)pens_written(array)protocol(string)removal(string)rows(array)rows_cut(boolean)rows_kept(integer)rows_max(integer)rows_path(string)sees_reset_and_load(boolean)setters(array)setters_path(string or object)setters_total(integer)space(string)state(string)superseded(boolean)synced_at_start(boolean)tally_id(string)unsynced_writes(integer)why(string)writes_total(integer)
What it refuses
- No manifest loaded, or a read with no log armed; the message gives the call that arms it (
needs_call). - A
palette_portthe manifest does not have (unknown_ref). - A
penthe entry does not set (bad_argument). armwithclear, orpenorlimitwith either (bad_argument).- A log armed from an entry the manifest has since changed: clear it and arm it again (
needs_call).
Why it works this way
A RAMDAC takes an index on one port and the colour's components one after another on a second port, so a data write names no pen. Which pen it landed on is known only by following the device from its last index write, which the log does inside MAME with the rule of MAME's own ramdac_device.
Until the first index write after arming, a reset or a state load, the index is not known. A write then counts in unsynced_writes and is given to no pen, because a guessed index is a plausible wrong pen.
written_by is guest for the program, or debugger for a write made while the machine stood in the debugger, whose pc is where the machine stood and not a writer. Rows carry the screen line being drawn and time_s, so a palette write in the middle of a frame can be ordered against another cpu's captured writes.
More on why
A stop asked for from outside is requested before the cpu reaches the instruction it stops at, so the program's last instruction still counts as guest. Every call of this tool answers while the program runs.
The other two protocols put a whole colour in one word, read little-endian from the port up to the end of its bus word. A big-endian bus, or an index port inside the data port's bus word, fails when the log is installed (install_failed).
latch: a data word with a bit of index_flag_mask set sets the index to its low bits; any other word is the indexed pen's colour, written whole. A write to index_port merges into the index under its mask. While the index is unknown, only a write covering every index bit makes it known.
sequence: each data write merges into the stored word of the pen at the current offset, under its mask. Any write to index_port's bus word sets the offset back to 0.
A driver that zeroes that offset as its video starts leaves a log armed right after start knowing it (synced_at_start). Armed anywhere else, the log waits for a write a game may never make again.
In both, a pen has a colour only once every colour bit of its word has been seen written. A write that merges into bits the log never saw counts in partial_writes, and the pen has no colour until they are.
A row of an index write carries index, and one of a whole-colour write word and mask. A row that landed on no pen says unsynced; one where the index was lost says desync and why.
A log whose callbacks raised carries callback_errors, with their count and the first error, and a pen with no write logged then says one may have been missed. A log whose periodic write to disk keeps failing shows its last finished table, and why gives the error.
Related tools
The contract your client receives
Who set this pen's colour, on a board whose colour RAM is write-only: every write to the
ports of the loaded manifest's `palette_port`, placed on its pen by the device's law.
`arm=True` arms the log; without it a call reads it; `clear=True` removes it. `pen` shows
that pen alone, `limit` the newest rows. Answers while running. Rows are capped at
100000, the rest counted.
Reply: `palette_port`, `protocol`, `armed_now`, `installed` (unless `clear`), `state`
(once armed), `writes_total`, `unsynced_writes`, `desyncs`, `rows_path` (once the log has
dumped). Without `pen`: `setters` (each `pc`, `symbol`,
`written_by`; the first 32). With `pen`: `pen_state`, `rows`.
`needs_call`: no manifest, entry or armed log; `bad_argument`: a pen it does not set.
Reference: REFERENCE.md, Input and the screen.