SCRYMAMEReferenceCommentscomment_listAlso in DOSBox-X

MAMEComments

comment_list

List every saved comment, or one cpu's, each with its address and whether MAME's disassembly shows it.

comment_list(cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset, right after the comment of the entry below was added.
Ask

Which comments are saved for this game?

Call
comment_list()
Reply 5 of 7 fields
{
  "summary": "comment_list: 1 comment",
  "status": "ok",
  "comments_total": 1,
  "truncated": false,
  "cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}

One comment is saved, and truncated is false: the reply lists every one. No cpu was named, so the rows are every cpu's.

The whole reply
JSON
{
  "summary": "comment_list: 1 comment",
  "status": "ok",
  "comments": [
    {
      "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"
    }
  ],
  "comments_total": 1,
  "truncated": false,
  "declarations": {"persistent": true, "path": "./tmp/demos/tour/gridlee-states/declarations.json"},
  "cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}

Arguments

cpu string, default ""
Lists this cpu's comments only. Left empty, every cpu's.

What comes back

comments
The comments this reply shows. Each row has ref, text, addr once resolved, state, and why when it is not shown.
comments_total
How many comments are saved, listed or not.
truncated
true when there are more comments than the reply lists. comment_write(method="save") writes them all.
declarations
The saved breakpoints file the comments live in: its path, and persistent, false when they last only this session.
All 5 reply fields
  • comments (array)
  • comments_total (integer)
  • cpu (string or object)
  • declarations (object)
  • truncated (boolean)

What it refuses

Why it works this way

It reads the saved comments and asks the machine nothing, so it answers while the program runs.

MAME also ties a comment to a checksum of the instruction bytes under it. Code that moves in RAM hides its comment in MAME's disassembly, while the comment stays saved.

More on why

What state says of a comment:

  • armed: MAME's disassembly shows it.

  • unarmable: saved but not shown. why says the reason.

  • unresolved: its symbol is not in this build.

  • stale: a raw address saved over another build.

  • Each row also carries by, cpu, created_at, origin, inherited and age_s, as a saved breakpoint's row does.

  • A rebuild can bring several comments to one address. All are kept: MAME's disassembly shows the first it can, and each other reads unarmable.

  • A field with nothing to give is an object: available is false and why says the reason, as cpu when none was named.

  • While the machine runs the reply adds last_stop.

The contract your client receives
Text
Every comment of the store, or `cpu`'s. Answers on a running machine too.

Reply: `comments` (each `ref`, `text`, `addr`, `state`; at most 24),
`comments_total`, `truncated`, `declarations`, `cpu`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools