summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/debugger/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/debugger/index.rst')
-rw-r--r--docs/source/debugger/index.rst364
1 files changed, 350 insertions, 14 deletions
diff --git a/docs/source/debugger/index.rst b/docs/source/debugger/index.rst
index fb8f3abe3fe..639a1d1d535 100644
--- a/docs/source/debugger/index.rst
+++ b/docs/source/debugger/index.rst
@@ -1,18 +1,354 @@
+.. _debugger:
+
MAME Debugger
--------------------
+=============
+
+.. contents:: :local:
+
+
+.. _debugger-intro:
+
+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.
+
+Use the ``-debug`` command line option to start MAME with the debugger
+activated. By default, pressing the tilde (**~**) during emulation
+breaks into the debugger.
+
+The exact appearance of the debugger depends on your operating system
+and the options MAME was built with. All variants of the debugger
+provide a multi-window interface for viewing the contents of memory and
+disassembled code.
-This section covers the built-in MAME debugger, which is invoked with the -debug switch on the command line.
+The debugger console window is a special window that shows the contents
+of CPU registers and disassembled code around the current program
+counter address, and provides a command-line interface to most of the
+debugging functionality.
+
+
+.. _debugger-sections-list:
+
+Debugger commands
+-----------------
+
+Debugger commands are described in the sections below. You can also
+type **help <topic>** in the debugger console, where **<topic>** is the
+name of a command, to see documentation directly in MAME.
.. toctree::
- :titlesonly:
-
- general
- memory
- execution
- breakpoint
- watchpoint
- registerpoints
- annotation
- cheats
- image
- expressions
+ :titlesonly:
+
+ general
+ memory
+ execution
+ breakpoint
+ watchpoint
+ registerpoints
+ annotation
+ cheats
+ image
+
+
+.. _debugger-devicespec:
+
+Specifying devices and address spaces
+-------------------------------------
+
+Many debugger commands accept parameters specifying which device to
+operate on. If a device is not specified explicitly, the CPU currently
+visible in the debugger is used. Devices can be specified by tag, or by
+CPU number:
+
+* Tags are the colon-separated paths that MAME uses to identify devices
+ within a system. You see them in options for configuring slot
+ devices, in debugger disassembly and memory viewer source lists, and
+ various other places within MAME’s UI.
+* CPU numbers are monotonically incrementing numbers that the debugger
+ assigns to CPU-like devices within a system, starting at zero. The
+ **cpunum** symbol holds the CPU number for the currently visible CPU
+ in the debugger (you can see it by entering the command
+ **print cpunum** in the debugger console).
+
+If a tag starts with a caret (**^**) or dot (**.**), it is interpreted
+relative to the CPU currently visible in the debugger, otherwise it is
+interpreted relative to the root machine device. If a device argument
+is ambiguously valid as both a tag and a CPU number, it will be
+interpreted as a tag.
+
+Examples:
+
+``maincpu``
+ The device with the absolute tag ``:maincpu``.
+``^melodypsg``
+ The sibling device of the visible CPU with the tag ``melodypsg``.
+``.:adc``
+ The child device of the visible CPU with the tag ``adc``.
+``2``
+ The third CPU-like device in the system (zero-based index).
+
+Commands that operate on memory extend this by allowing the device tag
+or CPU number to be optionally followed by an address space identifier.
+Address space identifiers are tag-like strings. You can see them in
+debugger memory viewer source lists. If the address space identifier is
+omitted, a default address space will be used. Usually, this is the
+address space that appears first for the device. Many commands have
+variants with **d**, **i** and **o** (data, I/O and opcodes) suffixes
+that default to the address spaces at indices 1, 2 and 3, respectively,
+as these have special significance for CPU-like devices.
+
+In ambiguous cases, the default address space of a child device will be
+used rather than a specific address space.
+
+Examples:
+
+``ram``
+ The default address space of the device with the absolute tag
+ ``:ram``, or the ``ram`` space of the visible CPU.
+``.:io``
+ The default address space of the child device of the visible CPU
+ with the tag ``io``, or the ``io`` space of the visible CPU.
+``:program``
+ The default address space of the device with the absolute tag
+ ``:program``, or the ``program`` space of the root machine device.
+``^vdp``
+ The default address space of the sibling device of the visible CPU
+ with the tag ``vdp``.
+``^:data``
+ The default address space of the sibling device of the visible CPU
+ with the tag ``data``, or the ``data`` space of the parent device
+ of the visible CPU.
+``1:rom``
+ The default address space of the child device of the second CPU in
+ the system (zero-based index) with the tag ``rom``, or the ``rom``
+ space of the second CPU in the system.
+``2``
+ The default address space of the third CPU-like device in the system
+ (zero-based index).
+
+If a command takes an emulated memory address as a parameter, the
+address may optionally be followed by an address space specification, as
+described above.
+
+Examples:
+
+``0220``
+ Address 0220 in the default address space for the visible CPU.
+``0378:io``
+ Address 0378 in the default address space of the device with the
+ absolute tag ``:io``, or the ``io`` space of the visible CPU.
+``1234:.:rom``
+ Address 1234 in the default address space of the child device of the
+ visible CPU with the tag ``:rom``, or the ``rom`` space of the
+ visible CPU.
+``1260:^vdp``
+ Address 1260 in the default address space of the sibling device of
+ the visible CPU with the tag ``vdp``.
+``8008:^:data``
+ Address 8008 in the default address space of the sibling device of
+ the visible CPU with the tag ``data``, or the ``data`` space of the
+ parent device of the visible CPU.
+``9660::ram``
+ Address 9660 in the default address space of the device with the
+ absolute tag ``:ram``, or the ``ram`` space of the root machine
+ device.
+
+The examples here include a lot of corner cases, but in general the
+debugger should take the most likely meaning for a device or address
+space specification.
+
+
+.. _debugger-expressions:
+
+Debugger expression syntax
+--------------------------
+
+Expressions can be used anywhere a numeric or Boolean parameter is
+expected. The syntax for expressions is similar to a subset of C-style
+expression syntax, with full operator precedence and parentheses. There
+are a few operators missing (notably the ternary conditional operator),
+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!
+ 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:
+
+* All numbers are unsigned 64-bit values. In particular, this means
+ negative numbers are not possible.
+* The logical conjunction and disjunction operators ``&&`` and ``||`` do
+ not have short-circuit properties – both sides of the expression are
+ always evaluated.
+
+
+Numbers
+~~~~~~~
+
+Literal numbers are prefixed according to their bases:
+
+* Hexadecimal (base-16) with ``$`` or ``0x``
+* Decimal (base-10) with ``#``
+* Octal (base-8) with ``0o``
+* Binary (base-2) with ``0b``
+* Unprefixed numbers are hexadecimal (base-16).
+
+Examples:
+
+* ``123`` is 123 hexadecimal (291 decimal)
+* ``$123`` is 123 hexadecimal (291 decimal)
+* ``0x123`` is 123 hexadecimal (291 decimal)
+* ``#123`` is 123 decimal
+* ``0o123`` is 123 octal (83 decimal)
+* ``0b1001`` is is 1001 binary (9 decimal)
+* ``0b123`` is invalid
+
+
+Boolean values
+~~~~~~~~~~~~~~
+
+Any expression that evaluates to a number can be used where a Boolean
+value is required. Zero is treated as false, and all non-zero values
+are treated as true. Additionally, the string ``true`` is treated as
+true, and the string ``false`` is treated as false.
+
+An empty string may be supplied as an argument for Boolean parameters to
+debugger commands to use the default value, even when subsequent
+parameters are specified.
+
+
+Memory accesses
+~~~~~~~~~~~~~~~
+
+The memory access prefix operators allow reading from and writing to
+emulated address spaces. The memory prefix operators specify the
+access size and whether side effects are disabled, and may optionally be
+preceded by an address space specification. The supported access sizes
+and side effect modes are as follows:
+
+* ``b`` specifies an 8-bit access (byte)
+* ``w`` specifies a 16-bit access (word)
+* ``d`` specifies a 32-bit access (double word)
+* ``q`` specifies a 64-bit access (quadruple word)
+* ``@`` suppress side effects
+* ``!`` do not suppress side effects
+
+The size may optionally be preceded by an access type specification:
+
+* ``p`` or ``lp`` specifies a logical address defaulting to space 0
+ (program)
+* ``d`` or ``ld`` specifies a logical address defaulting to space 1
+ (data)
+* ``i`` or ``li`` specifies a logical address defaulting to space 1
+ (I/O)
+* ``3`` or ``l3`` specifies a logical address defaulting to space 1
+ (opcodes)
+* ``pp`` specifies a physical address defaulting to space 0 (program)
+* ``pd`` specifies a physical address defaulting to space 1 (data)
+* ``pi`` specifies a physical address defaulting to space 1 (I/O)
+* ``p3`` specifies a physical address defaulting to space 1 (opcodes)
+* ``r`` specifies direct read/write pointer access defaulting to space 0
+ (program)
+* ``o`` specifies direct read/write pointer access defaulting to space 3
+ (opcodes)
+* ``m`` specifies a memory region
+
+Finally, this may be preceded by a tag and/or address space name
+followed by a dot (``.``).
+
+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
+ CPU while suppressing side effects
+``b!<addr>``
+ Refers to the byte at **<addr>** in the program space of the visible
+ 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
+ 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,
+ 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,
+ respectively.
+
+Adding access types gives additional possibilities:
+
+``dw@300``
+ Refers to the word at 300 in the data space of the visible CPU while
+ suppressing side effects
+``id@400``
+ Refers to the double word at 400 in the I/O space of the visible 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
+``rw@<addr>``
+ Refers to the word at address **<addr>** in the program space of the
+ visible CPU using direct read/write pointer access
+
+If we want to access an address space of a device other than the visible
+CPU, an address space beyond the first four indices, or a memory region,
+we need to include a tag or name:
+
+``ramport.b@<addr>``
+ Refers to the byte at address **<addr>** in the ``ramport`` space of
+ the current CPU
+``audiocpu.dw@<addr>``
+ Refers to the word at address **<addr>** in the data space of the
+ CPU with absolute tag ``:audiocpu``
+``maincpu:status.b@<addr>``
+ Refers to the byte at address **<addr>** in the ``status`` space of
+ the CPU with the absolute tag ``:maincpu``
+``monitor.mb@78``
+ Refers to the byte at 78 in the memory region with the absolute tag
+ ``:monitor``
+
+Some combinations are not useful. For example physical and logical
+addresses are equivalent for some CPUs, and direct read/write pointer
+accesses never have side effects. Accessing a memory region (``m``
+access type) requires a tag to be specified.
+
+Memory accesses can be used as both lvalues and rvalues, so you can write
+``b@100 = ff`` to store a byte in memory.