Debugger: Proposed new behavior for `symlist` command

[Stevie-O]

The symlist command's current behavior makes symbol-discoverability more difficult than necessary (it certainly tripped me up).

Currently, symlist with no parameters displays only global symbols; to view the symbols for the current CPU you have to use symlist <cpu>.

I propose the following new behavior:

• symlist with no arguments displays all currently-available symbols: globals and those associated with the current CPU.
• symlist global (or somesuch, I'm open to the syntax) displays global symbols only.
• symlist -1 would also display global symbols; since symlist works with debugger variables (temp9=1; symlist temp9 will display symbols for CPU 1) this would preserve that property (it would actually make the command even more flexible, I'd think)

This offers the following benefits:

• It makes the behavior of symlist more convenient for users unfamiliar with the nuances of MAME's debugger -- one command to view all of the symbols available to them at once.
• It brings the behavior of symlist with no arguments closer to that of other commands that take an optional CPU specifier (e.g. trace): specifically, the behavior when no CPU is specified is to assume the current CPU/context

Some background:

When I was trying to understand the MAME debugger's behavior, I ran into some severe under-documentation issues. For example, there do not appear to be any symbols formally documented anywhere.

I got confused because, technically, the word "symbol" technically refers to an object's name -- it's called a "symbol" because it's an identifier used to represent the actual object (here, a storage location in memory).

With that in mind, the term "global symbols" becomes ambiguous, or at least misleading. I interpreted "global symbols" to mean "names available in all contexts" and "per-CPU symbols" to mean "names specific to a particular CPU".

I was surprised to note that there wasn't a "number of cycles executed" symbol for CPUs, when there was a "number of frames displayed" symbol. Eventually I happened to try "print cycles" and got an output (by the way, perhaps print should probably output a $ prefix, since it outputs in hex. It was really confusing when the sidebar says "cycles = 52" and print cycles outputs 34.)

Anyway, when cycles worked but didn't show up in symlist, I got confused. I located the place in the source code where the symbols were registered and got really confused:

mame/src/emu/debug/debugcpu.cpp

Line 61 in dc83375

/* add "wpaddr", "wpdata", "cycles", "cpunum", "logunmap" to the global symbol table */

mame/src/emu/debug/debugcpu.cpp

Line 1338 in dc83375

// add global symbol for cycles and totalcycles

add "wpaddr", "wpdata", "cycles", "cpunum", "logunmap" to the global symbol table

Well, wpaddr, wpdata, and cpunum are in the global symbol table, but cycles and logunmap weren't.

Eventually, I worked out that what the MAME debugger refers to as "global symbols" are not global names, but global variables. Since logunmap, cycles, totalcycles, lastinstructioncycles (now there's an awkward name), curpc, and probably several others are per-CPU values, they are not considered global by symlist (though the source code calls them that.)

[dave-br]

I agree with @Stevie-O that the cpu vs. global symbol tables are confusing, especially for beginners. I'd like to open a PR with a fix, but with a slightly simplified syntax than he suggested:

• symlist with no arguments displays all global and :maincpu symbols, with clear header text for each list.
• symlist <cpu> (no dash in the syntax to be consistent with other commands): Works as it currently does today, only displays symbols for specified CPU

The symlist command is an opportunity to introduce users to the idea of global vs. cpu symbols, so I'd also add helper text at the end of the output from the symlist (no arguments) form, like "To view the symbols for a particular CPU, try symlist <cpu>".

I don't think a symlist global form is all that helpful, and the symlist <cpu> form would only be used by users familiar with symbol tables (or who just did symlist (no arguments)), so showing the globals again for that form would get in the way of finding the output they explicitly requested.

Any objections?

[dave-br]

@Stevie-O : If no objections I'll be closing this as fixed with b39e684

er, actually I don't have permissions to do that. Perhaps you can. 🙂