diff options
author | 2021-10-15 09:42:35 +1100 | |
---|---|---|
committer | 2021-10-15 10:12:56 +1100 | |
commit | 22bc3486c3ef8f2230e99daf49785a89ac8a1182 (patch) | |
tree | 4f10f7386b7b0a32c9d560395399e8b7632df34c /docs/source/debugger/index.rst | |
parent | 3e8763bea5a93f3139204fcb8a0c74c2ac364af5 (diff) |
More user experience improvements:
frontend: Made it possible to cancel a media audit while it's in
progress. Also made the media audit multi-threaded so it's faster.
frontend: Made the DIP switches in the DIP switch preview clickable.
frontend: Made the system and software selection menus leave focus on
the same system when clearing the search rather than jumping to the
first item. Also fixed a couple of bugs in the logic for keeping the
selected item visible.
frontend: Fixed a few places that weren't showing localised system
names.
frontend: Made UI Cancel clear a search in the file manager the same way
it does on the system and sofware selection menus.
frontend: Made it possible for plugin menus to handle UI Cancel more
naturally, backing up to the previous plugin menu rather than dropping
straight back to the list of plugins. Updated the autofire, cheat and
cheatfind plugins, and fixed a few other issues in the cheatfind plugin.
debugger: Made the mount and unmount commands accept instance names as
well as brief instance names. Also updated another page of debugger
documentation.
Diffstat (limited to 'docs/source/debugger/index.rst')
-rw-r--r-- | docs/source/debugger/index.rst | 93 |
1 files changed, 64 insertions, 29 deletions
diff --git a/docs/source/debugger/index.rst b/docs/source/debugger/index.rst index c7503e8d678..0730a607688 100644 --- a/docs/source/debugger/index.rst +++ b/docs/source/debugger/index.rst @@ -11,10 +11,10 @@ MAME Debugger Introduction ------------ -MAME includes an interactive low-level debugger that target the emulated -system. This can be a useful tool for diagnosing emulation issues, -developing software to run on vintage systems, creating cheats, ROM -hacking, or just looking at how software works. +MAME includes an interactive low-level debugger that targets the +emulated system. This can be a useful tool for diagnosing emulation +issues, developing software to run on vintage systems, creating cheats, +ROM hacking, or just investigating how software works. Use the ``-debug`` command line option to start MAME with the debugger activated. By default, pressing the tilde (**~**) during emulation @@ -176,36 +176,36 @@ and a few new ones (memory accessors). The table below lists all the operators, ordered from highest to lowest precedence: -( ) +``(`` ``)`` Standard parentheses -++ -- +``++`` ``--`` Postfix increment/decrement -++ -- ~ ! - + b@ w@ d@ q@ b! w! d! q! +``++`` ``--`` ``~`` ``!`` ``-`` ``+`` ``b@`` ``w@`` ``d@`` ``q@`` ``b!`` ``w!`` ``d!`` ``q!`` Prefix increment/decrement, binary complement, logical complement, unary identity/negation, memory access -\* / % +``*`` ``/`` ``%`` Multiplication, division, modulo -\+ - +``+`` ``-`` Addition, subtraction -<< >> +``<<`` ``>>`` Bitwise left/right shift -< <= > >= +``< ``<=`` ``>`` ``>=`` Less than, less than or equal, greater than, greater than or equal -== != +``==`` ``!=`` Equal, not equal -\& +``&`` Bitwise intersection (and) -\^ +``^`` Bitwise exclusive or -\| +``|`` Bitwise union (or) -\&& +``&&`` Logical conjunction (and) -\|| +``||`` Logical disjunction (or) -= \*= /= %= += -= <<= >>= &= \|= ^= +``=`` ``*=`` ``/=`` ``%=`` ``+=`` ``-=`` ``<<=`` ``>>=`` ``&=`` ``|=`` ``^=`` Assignment and modifying assignment -\, +``,`` Separate terms, function parameters Major differences from C expression semantics: @@ -268,6 +268,38 @@ and side effect modes are as follows: * ``@`` suppress side effects * ``!`` do not suppress side effects +Suppressing side effects of a read access yields the value reading from +address would, with no further effects. For example reading a mailbox +with side effects disabled will not clear the pending flag, and reading +a FIFO with side effects disabled will not remove an item. + +For write accesses, suppressing side effects doesn’t change behaviour in +most cases – you want to see the effects of writing to a location. +However, there are some exceptions where it is useful to separate +multiple effects of a write access. For example: + +* Some registers need to be written in sequence to avoid race + conditions. The debugger can issue multiple writes at the same point + in emulated time, so these race conditions cannot be avoided + trivially. For example writing to the MC68HC05 output compare + register high byte (OCRH) inhibits compare until the output compare + register low byte (OCRL) is written to prevent race conditions. + Since the debugger can write to both locations at the same instant + from the emulated machine’s point of view, the race condition is not + usually relevant. It’s more error-prone if you can accidentally set + hidden state when all you really want to do is change the value, so + writing to OCRH with side effects suppressed does not inhibit compare, + it just changes the value in the output compare register. +* Writing to some registers has multiple effects that may be useful to + separate for debugging purposes. Using the MC68HC05 as an example + again, writing to OCRL changes the value in the output compare + register, and also clears the output compare flag (OCF) and enables + compare if it was previously inhibited by writing to OCRH. Writing to + OCRL with side effects disable just changes the value in the register + without clearing OCF or enabling compare, since it’s useful for + debugging purposes. Writing to OCRL with side effects enabled has the + additional effects. + The size may optionally be preceded by an access type specification: * ``p`` or ``lp`` specifies a logical address defaulting to space 0 @@ -295,40 +327,40 @@ That may seem like a lot to digest, so let’s look at the simplest examples: ``b@<addr>`` - Refers to the byte at **<addr>** in the program space of the visible + Refers to the byte at **<addr>** in the program space of the current CPU while suppressing side effects ``b!<addr>`` - Refers to the byte at **<addr>** in the program space of the visible + Refers to the byte at **<addr>** in the program space of the current CPU, *not* suppressing side effects such as reading a mailbox clearing the pending flag, or reading a FIFO removing an item ``w@<addr>`` and ``w!<addr>`` - Refer to the word at **<addr>** in the program space of the visible + Refer to the word at **<addr>** in the program space of the current CPU, suppressing or not suppressing side effects, respectively. ``d@<addr>`` and ``d!<addr>`` Refer to the double word at **<addr>** in the program space of the - visible CPU, suppressing or not suppressing side effects, + current CPU, suppressing or not suppressing side effects, respectively. ``q@<addr>`` and ``q!<addr>`` Refer to the quadruple word at **<addr>** in the program space of - the visible CPU, suppressing or not suppressing side effects, + the current CPU, suppressing or not suppressing side effects, respectively. Adding access types gives additional possibilities: ``dw@300`` - Refers to the word at 300 in the data space of the visible CPU while + Refers to the word at 300 in the data space of the current CPU while suppressing side effects ``id@400`` - Refers to the double word at 400 in the I/O space of the visible CPU + Refers to the double word at 400 in the I/O space of the current CPU CPU while suppressing side effects ``ppd!<addr>`` Refers to the double word at physical address **<addr>** in the - program space of the visible CPU while not suppressing side effects + program space of the current CPU while not suppressing side effects ``rw@<addr>`` Refers to the word at address **<addr>** in the program space of the - visible CPU using direct read/write pointer access + current CPU using direct read/write pointer access -If we want to access an address space of a device other than the visible +If we want to access an address space of a device other than the current CPU, an address space beyond the first four indices, or a memory region, we need to include a tag or name: @@ -344,6 +376,9 @@ we need to include a tag or name: ``monitor.mb@78`` Refers to the byte at 78 in the memory region with the absolute tag ``:monitor`` +``..md@202`` + Refers to the double word at address 202 in the memory region with + the same tag path as the current CPU. Some combinations are not useful. For example physical and logical addresses are equivalent for some CPUs, and direct read/write pointer |