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 | |
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')
-rw-r--r-- | docs/source/debugger/image.rst | 97 | ||||
-rw-r--r-- | docs/source/debugger/index.rst | 93 |
2 files changed, 121 insertions, 69 deletions
diff --git a/docs/source/debugger/image.rst b/docs/source/debugger/image.rst index d52c3ed3f43..f02388062a7 100644 --- a/docs/source/debugger/image.rst +++ b/docs/source/debugger/image.rst @@ -1,63 +1,80 @@ .. _debugger-image-list: -Image Debugger Commands -======================= +Media Image Debugger Commands +============================= +:ref:`debugger-command-images` + lists all image devices and mounted media images +:ref:`debugger-command-mount` + mounts a media image file to an image device +:ref:`debugger-command-unmount` + unmounts the media image from a device -You can also type **help <command>** for further details on each command in the MAME Debugger interface. -| :ref:`debugger-command-images` -- lists all image devices and mounted files -| :ref:`debugger-command-mount` -- mounts file to named device -| :ref:`debugger-command-unmount` -- unmounts file from named device - - - .. _debugger-command-images: +.. _debugger-command-images: images ------ -| **images** -| -| Used to display list of available image devices. -| -| Examples: -| -| images -| -| Show list of devices and mounted files for current driver. +**images** + +Lists the instance names for media images devices in the system and the +currently mounted media images, if any. Brief instance names, as +allowed for command line media options, are listed. Mounted software +list items are displayed as the list name, software item short name, and +part name, separated by colons; other mounted images are displayed as +file names. + +Example: +``images`` + Lists image device instance names and mounted media. - .. _debugger-command-mount: +Back to :ref:`debugger-image-list` + + +.. _debugger-command-mount: mount ----- -| **mount <device>,<filename>** -| -| Mount <filename> to image <device>. -| -| <filename> can be softlist item or full path to file. -| -| Examples: -| -| mount cart,aladdin -| -| Mounts softlist item aladdin on cart device. +**mount <instance>,<filename>** + +Mounts a file on a media device. The device may be specified by its +instance name or brief instance name, as allowed for command line media +options. +Some media devices allow software list items to be mounted using this +command by supplying the short name of the software list item in place +of a filename for the **<filename>** parameter. - .. _debugger-command-unmount: +Examples: + +``mount flop1,os1xutls.td0`` + Mount the file **os1xutls.td0** on the media device with instance + name **flop1**. +``mount cart,10yard`` + Mount the software list item with short name **10yard** on the media + device with instance name **cart**. + +Back to :ref:`debugger-image-list` + + +.. _debugger-command-unmount: unmount ------- -| **unmount <device>** -| -| Unmounts file from image <device>. -| -| Examples: -| -| unmount cart -| -| Unmounts any file mounted on device named cart. +**unmount <instance>** + +Unmounts the mounted media image (if any) from a device. The device may +be specified by its instance name or brief instance name, as allowed for +command line media options. + +Examples: +unmount cart + Unmounts any media image mounted on the device with instance name + **cart**. +Back to :ref:`debugger-image-list` 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 |