SCRYMAMEReferenceTimelinepalette_log

MAMETimeline

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

This tool needs a board that sets its colours through ports; Gridlee's are fixed in PROMs, and neither free program has such a board. The reply shown comes from a test program that is not distributed.
Ask

Start logging every write to this board's palette ports, so I can ask later which code set a pen.

Call
palette_log(palette_port="ramdac", arm=true)
Reply 6 of 20 fields
{
  "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
JSON
{
  "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_ports in the loaded gfx.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
true removes the log.
arm boolean, default false
true starts the log. Without it the call reads the log, and never starts one.

What comes back

installed
false on 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: logged when there is a table to read. Otherwise no_dump_yet, install_failed or install_lost, with why.
writes_total
Every write the log saw. unsynced_writes landed while the device's index was not known, and desyncs counts the times it was lost.
setters
Without pen, the first 32 writers, most pens first: pc, symbol, written_by, how many pens_set and which. setters_path holds them all.
pen_state
With pen: its color, whether it is complete, its components, its writes_total and the last write.
rows
The newest limit rows in order, each with n, frame, pc, written_by, the screen line, time_s, and the pen, component, value and color it 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

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.

The contract your client receives
Text
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.
Tools