SCRYMAMEReferenceCommentscomment_writeAlso in DOSBox-X

MAMEComments

comment_write

Change the saved comments: add or delete one, or save them all to a file and load them back.

comment_write(method, ref="", text="", cpu="", dest="", path="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset with the example session's symbol file loaded, which names the coin routine count_coin.
Ask

Leave a note on the coin routine: a coin increments the credits, then the BCD copy.

Call
comment_write(method="add", ref="count_coin", text="a coin: INC credits, then the BCD copy")
Reply 4 of 6 fields
{
  "summary": "comment_write add: count_coin at :maincpu 0x0000b583, stored, persistent",
  "status": "ok",
  "replaced_comments": [],
  "cpu": ":maincpu"
}

The comment is saved on count_coin, which is 0xb583 on the main cpu, in a file that outlasts the session. Nothing was there before, so replaced_comments is empty.

The whole reply
JSON
{
  "summary": "comment_write add: count_coin at :maincpu 0x0000b583, stored, persistent",
  "status": "ok",
  "comment": {
    "ref": "count_coin",
    "by": "symbol",
    "cpu": ":maincpu",
    "created_at": "<volatile>",
    "origin": "<volatile>",
    "inherited": false,
    "age_s": "<volatile>",
    "text": "a coin: INC credits, then the BCD copy",
    "addr": "0x0000b583",
    "state": "armed"
  },
  "replaced_comments": [],
  "declarations": {"persistent": true, "path": "./tmp/demos/tour/gridlee-states/declarations.json"},
  "cpu": ":maincpu"
}

The four methods

method what it does
add Puts text on ref. A comment already there is replaced.
delete Removes the comment at ref.
save Writes every comment to the file dest.
load Reads the comment file at path into the saved comments, all or nothing.

Arguments

method one of "add", "delete", "save", "load", required
add, delete, save or load, as above.
ref string, default ""
For add and delete: a symbol or a 0x address.
text string, default ""
For add: one printable line, at most 237 UTF-8 bytes.
cpu string, default ""
For add and delete: the cpu whose code is commented. Left empty, the one the debugger is showing.
dest string, default ""
For save: the file to write, an absolute or ~-led path. A comment file already there is replaced; any other file is refused.
path string, default ""
For load: the comment file to read, an absolute path.

What comes back

comment
add: the comment as saved, a row as comment_list gives it.
replaced_comments
add and load: the comments whose text was replaced, as they were.
deleted
delete: the comment removed.
dropped_comments
save: comments only the replaced file held, each by ref and cpu. They are gone from the file.
added
load: how many comments are new. unchanged counts those already saved with the same text, parsed the rows read.
held_in_memory
true when the saved breakpoints file could not be written: the change lasts until close.
All 15 reply fields
  • added (integer)
  • comment (object)
  • comments_total (integer)
  • declarations (object)
  • deleted (object)
  • dropped_comments (array)
  • dropped_total (integer)
  • parsed (integer)
  • path (string)
  • replaced_comments (array)
  • replaced_total (integer)
  • truncated (boolean)
  • unchanged (integer)
  • cpu (string)
  • held_in_memory (boolean)

What it refuses

Why it works this way

The change is saved first, and MAME's disassembly is fed after. If the session breaks in between, the message says so, and the next start feeds the saved comments again.

One address shows one comment. An add where one exists replaces its text and keeps its ref, so a comment made by symbol keeps following its symbol.

save and load are how a project keeps its comments under version control beside its symbol file. load is all or nothing, and the file wins where both comment an address.

More on why
  • A comment's state is armed once MAME's disassembly shows it. unresolved names a symbol this build lacks: the comment stays saved and is shown once a build has it.

  • The file has no build column, so a raw address loaded into another build is trusted. Comment by symbol what must survive a rebuild.

  • A rebuild can bring several comments to one address. An add, delete or load there reaches the one whose ref it spells, else the one MAME's disassembly shows.

  • A stale comment made the other way, by symbol where yours is by address or the reverse, is reached only by its own spelling.

  • save's dest is in a folder that exists, and its path holds no comma, semicolon, quote, space, bracket or control character.

  • MAME's console cannot carry a text holding " or ending in \: it is saved and reads unarmable. If it replaces one that was shown, the old text is cleared.

  • A delete over instruction bytes that changed since leaves MAME holding the old text, hidden, until close.

  • A file with two comments a rebuild put at one address loads both, so what save writes of them reads back.

  • MAME writes its own comment files into a folder inside the session's temporary folder, so nothing deleted here comes back from them.

  • comments_total, dropped_total and replaced_total count the whole lists; truncated says a list was cut. declarations names the saved breakpoints file, as in comment_list.

  • The file save writes is UTF-8 with no byte order mark, and its lines end in LF.

  • Line 1 is exactly # comments v1: ref<TAB>cpu<TAB>created_at<TAB>text, and each row after it holds those four columns.

  • Rows are sorted by cpu, then by ref, so a diff shows only what changed.

  • cpu is the cpu's absolute tag, and created_at reads YYYY-MM-DDTHH:MM:SS+00:00.

The contract your client receives
Text
Change the store's comments.

`add`: `text` (one printable line, at most 237 UTF-8 bytes) on `ref`,
a symbol or a linear `0x` address, of `cpu` (default the visible one); a second there
replaces it.
Reply: `comment`, `replaced_comments`, `declarations`, `cpu`, `note`.

`delete`: the comment at `ref`. Reply: `deleted`, `declarations`, `cpu`, `note`.

`save`: every comment to `dest`, an absolute or `~`-led path, replacing a comment file
there (rows only it held in `dropped_comments`); any other file is refused; answers on a
running machine. Reply: `path`, `comments_total`, `dropped_comments`, `dropped_total`,
`truncated`, `note`.

`load`: the comment file at `path`, all or nothing, the file winning. Reply: `path`,
`parsed`, `added`, `replaced_comments`, `replaced_total`, `truncated`, `unchanged`,
`comments_total`, `declarations`, `note`.

`add`, `delete` and `load` need the machine stopped. Refused: an argument the method
does not take, a misshapen `ref` or `text`, an unknown `ref` (`unknown_ref`), a `save`
`dest` that is the declaration store's file (compared without regard to case, on any
volume), an unwritable store (`host_failed`, `held_in_memory`).

Reference: REFERENCE.md, Breakpoints and watches.
Tools