diff options
Diffstat (limited to 'docs/source')
-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 |