summaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
-rw-r--r--docs/source/debugger/annotation.rst103
-rw-r--r--docs/source/debugger/breakpoint.rst128
-rw-r--r--docs/source/debugger/cheats.rst267
-rw-r--r--docs/source/debugger/execution.rst360
-rw-r--r--docs/source/debugger/expressions.rst36
-rw-r--r--docs/source/debugger/general.rst389
-rw-r--r--docs/source/debugger/image.rst63
-rw-r--r--docs/source/debugger/index.rst18
-rw-r--r--docs/source/debugger/memory.rst168
-rw-r--r--docs/source/debugger/registerpoints.rst120
-rw-r--r--docs/source/debugger/watchpoint.rst128
-rw-r--r--docs/source/index.rst1
12 files changed, 1781 insertions, 0 deletions
diff --git a/docs/source/debugger/annotation.rst b/docs/source/debugger/annotation.rst
new file mode 100644
index 00000000000..6ada5497000
--- /dev/null
+++ b/docs/source/debugger/annotation.rst
@@ -0,0 +1,103 @@
+.. _debugger-annotation-list:
+
+Code Annotation Debugger Commands
+=================================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-comadd` -- adds a comment to the disassembled code at given address
+| :ref:`debugger-command-comdelete` -- removes a comment from the given address
+| :ref:`debugger-command-comsave` -- save the current comments to a file
+| :ref:`debugger-command-comlist` -- print currently available comments from file
+| :ref:`debugger-command-commit` -- gives a bulk comadd then comsave command
+
+
+ .. _debugger-command-comadd:
+
+Comadd
+------
+
+| **comadd[//] <address>,<comment>**
+|
+| Adds a string <comment> to the disassembled code at <address>. The shortcut for this command is simply '//'
+|
+| Examples:
+|
+| comadd 0, hello world.
+|
+| Adds the comment 'hello world.' to the code at address 0x0
+|
+| // 10, undocumented opcode!
+|
+| Adds the comment 'undocumented opcode!' to the code at address 0x10
+
+
+ .. _debugger-command-comdelete:
+
+Comdelete
+---------
+
+| **comdelete**
+|
+| Deletes the comment at the specified memory offset. The comment which is deleted is in the currently active memory bank.
+|
+| Examples:
+|
+| comdelete 10
+|
+| Deletes the comment at code address 0x10 (using the current memory bank settings)
+
+
+ .. _debugger-command-comsave:
+
+Comsave
+-------
+
+| **comsave**
+|
+| Saves the working comments to the driver's XML comment file.
+|
+| Examples:
+|
+| comsave
+|
+| Saves the comments to the driver's comment file
+
+
+ .. _debugger-command-comlist:
+
+Comlist
+-------
+
+| **comlist**
+|
+| Prints the currently available comment file in human readable form in debugger output window.
+|
+| Examples:
+|
+| comlist
+|
+| Shows currently available comments.
+
+
+ .. _debugger-command-commit:
+
+Commit
+------
+
+| **commit[/*] <address>,<comment>**
+|
+| Adds a string <comment> to the disassembled code at <address> then saves to file. Basically same as comadd + comsave via a single line.
+| The shortcut for this command is simply \'\/\*\'
+|
+| Examples:
+|
+| commit 0, hello world.
+|
+| Adds the comment 'hello world.' to the code at address 0x0
+|
+| /* 10, undocumented opcode!
+|
+| Adds the comment 'undocumented opcode!' to the code at address 0x10
+
diff --git a/docs/source/debugger/breakpoint.rst b/docs/source/debugger/breakpoint.rst
new file mode 100644
index 00000000000..2ed0f11743d
--- /dev/null
+++ b/docs/source/debugger/breakpoint.rst
@@ -0,0 +1,128 @@
+.. _debugger-breakpoint-list:
+
+Breakpoint Debugger Commands
+============================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-bpset` -- sets breakpoint at <address>
+| :ref:`debugger-command-bpclear` -- clears a given breakpoint or all if no <bpnum> specified
+| :ref:`debugger-command-bpdisable` -- disables a given breakpoint or all if no <bpnum> specified
+| :ref:`debugger-command-bpenable` -- enables a given breakpoint or all if no <bpnum> specified
+| :ref:`debugger-command-bplist` -- lists all the breakpoints
+
+
+ .. _debugger-command-bpset:
+
+Bpset
+-----
+
+| **bp[set] <address>[,<condition>[,<action>]]**
+|
+| Sets a new execution breakpoint at the specified <address>.
+| The optional <condition> parameter lets you specify an expression that will be evaluated each time the breakpoint is hit. If the result of the expression is true (non-zero), the breakpoint will actually halt execution; otherwise, execution will continue with no notification.
+| The optional <action> parameter provides a command that is executed whenever the breakpoint is hit and the <condition> is true. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the bpset command itself. Each breakpoint that is set is assigned an index which can be used in other breakpoint commands to reference this breakpoint.
+|
+| Examples:
+|
+| bp 1234
+|
+| Set a breakpoint that will halt execution whenever the PC is equal to 1234.
+|
+| bp 23456,a0 == 0 && a1 == 0
+|
+| Set a breakpoint that will halt execution whenever the PC is equal to 23456 AND the expression (a0 == 0 && a1 == 0) is true.
+|
+| bp 3456,1,{printf "A0=%08X\n",a0; g}
+|
+| Set a breakpoint that will halt execution whenever the PC is equal to 3456. When this happens, print A0=<a0val> and continue executing.
+|
+| bp 45678,a0==100,{a0 = ff; g}
+|
+| Set a breakpoint that will halt execution whenever the PC is equal to 45678 AND the expression (a0 == 100) is true. When that happens, set a0 to ff and resume execution.
+|
+| temp0 = 0; bp 567890,++temp0 >= 10
+|
+| Set a breakpoint that will halt execution whenever the PC is equal to 567890 AND the expression (++temp0 >= 10) is true. This effectively breaks only after the breakpoint has been hit 16 times.
+|
+| Back to :ref:`debugger-breakpoint-list`
+
+
+ .. _debugger-command-bpclear:
+
+Bpclear
+-------
+
+| **bpclear [<bpnum>]**
+|
+| The bpclear command clears a breakpoint. If <bpnum> is specified, only the requested breakpoint is cleared, otherwise all breakpoints are cleared.
+|
+| Examples:
+|
+| bpclear 3
+|
+| Clear breakpoint index 3.
+|
+| bpclear
+|
+| Clear all breakpoints.
+|
+| Back to :ref:`debugger-breakpoint-list`
+
+
+ .. _debugger-command-bpdisable:
+
+Bpdisable
+---------
+
+| **bpdisable [<bpnum>]**
+|
+| The bpdisable command disables a breakpoint. If <bpnum> is specified, only the requested breakpoint is disabled, otherwise all breakpoints are disabled. Note that disabling a breakpoint does not delete it, it just temporarily marks the breakpoint as inactive.
+|
+| Examples:
+|
+| bpdisable 3
+|
+| Disable breakpoint index 3.
+|
+| bpdisable
+|
+| Disable all breakpoints.
+|
+| Back to :ref:`debugger-breakpoint-list`
+
+
+ .. _debugger-command-bpenable:
+
+Bpenable
+--------
+
+| **bpenable [<bpnum>]**
+|
+| The bpenable command enables a breakpoint. If <bpnum> is specified, only the requested breakpoint is enabled, otherwise all breakpoints are enabled.
+|
+| Examples:
+|
+| bpenable 3
+|
+| Enable breakpoint index 3.
+|
+| bpenable
+|
+| Enable all breakpoints.
+|
+| Back to :ref:`debugger-breakpoint-list`
+
+
+ .. _debugger-command-bplist:
+
+Bplist
+------
+
+| **bplist**
+|
+| The bplist command lists all the current breakpoints, along with their index and any conditions or actions attached to them.
+|
+| Back to :ref:`debugger-breakpoint-list`
+
diff --git a/docs/source/debugger/cheats.rst b/docs/source/debugger/cheats.rst
new file mode 100644
index 00000000000..a1af04cf457
--- /dev/null
+++ b/docs/source/debugger/cheats.rst
@@ -0,0 +1,267 @@
+.. _debugger-cheats-list:
+
+Cheat Debugger Commands
+=======================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-cheatinit` -- initialize the cheat search to the selected memory area
+| :ref:`debugger-command-cheatrange` -- add to the cheat search the selected memory area
+| :ref:`debugger-command-cheatnext` -- continue cheat search comparing with the last value
+| :ref:`debugger-command-cheatnextf` -- continue cheat search comparing with the first value
+| :ref:`debugger-command-cheatlist` -- show the list of cheat search matches or save them to <filename>
+| :ref:`debugger-command-cheatundo` -- undo the last cheat search (state only)
+
+ .. _debugger-command-cheatinit:
+
+Cheatinit
+---------
+
+| **cheatinit [<sign><width><swap>,[<address>,<length>[,<cpu>]]]**
+|
+| The cheatinit command initializes the cheat search to the selected memory area.
+|
+| If no parameter is specified the cheat search is initialized to all changeable memory of the main cpu.
+|
+| <sign> can be s(signed) or u(unsigned)
+| <width> can be b(8 bit), w(16 bit), d(32 bit) or q(64 bit)
+| <swap> append s for swapped search
+|
+| Examples:
+|
+| cheatinit ub,0x1000,0x10
+|
+| Initialize the cheat search from 0x1000 to 0x1010 of the first CPU.
+|
+| cheatinit sw,0x2000,0x1000,1
+|
+| Initialize the cheat search with width of 2 byte in signed mode from 0x2000 to 0x3000 of the second CPU.
+|
+| cheatinit uds,0x0000,0x1000
+|
+| Initialize the cheat search with width of 4 byte swapped from 0x0000 to 0x1000.
+|
+| Back to :ref:`debugger-cheats-list`
+
+
+ .. _debugger-command-cheatrange:
+
+Cheatrange
+----------
+
+| **cheatrange <address>,<length>**
+|
+| The cheatrange command adds the selected memory area to the cheat search.
+|
+| Before using cheatrange it is necessary to initialize the cheat search with cheatinit.
+|
+| Examples:
+|
+| cheatrange 0x1000,0x10
+|
+| Add the bytes from 0x1000 to 0x1010 to the cheat search.
+|
+| Back to :ref:`debugger-cheats-list`
+
+
+ .. _debugger-command-cheatnext:
+
+Cheatnext
+---------
+
+| **cheatnext <condition>[,<comparisonvalue>]**
+|
+| The cheatnext command will make comparisons with the last search matches.
+|
+| Possible <condition>:
+|
+| **all**
+|
+| No <comparisonvalue> needed.
+|
+| Use to update the last value without changing the current matches.
+|
+| **equal [eq]**
+|
+| Without <comparisonvalue> search for all bytes that are equal to the last search.
+| With <comparisonvalue> search for all bytes that are equal to the <comparisonvalue>.
+|
+| **notequal [ne]**
+|
+| Without <comparisonvalue> search for all bytes that are not equal to the last search.
+| With <comparisonvalue> search for all bytes that are not equal to the <comparisonvalue>.
+|
+| **decrease [de, +]**
+|
+| Without <comparisonvalue> search for all bytes that have decreased since the last search.
+| With <comparisonvalue> search for all bytes that have decreased by the <comparisonvalue> since the last search.
+|
+| **increase [in, -]**
+|
+| Without <comparisonvalue> search for all bytes that have increased since the last search.
+| With <comparisonvalue> search for all bytes that have increased by the <comparisonvalue> since the last search.
+|
+| **decreaseorequal [deeq]**
+|
+| No <comparisonvalue> needed.
+|
+| Search for all bytes that have decreased or have same value since the last search.
+|
+| **increaseorequal [ineq]**
+|
+| No <comparisonvalue> needed.
+|
+| Search for all bytes that have decreased or have same value since the last search.
+|
+| **smallerof [lt]**
+|
+| Without <comparisonvalue> this condition is invalid
+| With <comparisonvalue> search for all bytes that are smaller than the <comparisonvalue>.
+|
+| **greaterof [gt]**
+|
+| Without <comparisonvalue> this condition is invalid
+| With <comparisonvalue> search for all bytes that are larger than the <comparisonvalue>.
+|
+| **changedby [ch, ~]**
+|
+| Without <comparisonvalue> this condition is invalid
+| With <comparisonvalue> search for all bytes that have changed by the <comparisonvalue> since the last search.
+|
+|
+| Examples:
+|
+| cheatnext increase
+|
+| Search for all bytes that have increased since the last search.
+|
+| cheatnext decrease, 1
+|
+| Search for all bytes that have decreased by 1 since the last search.
+|
+| Back to :ref:`debugger-cheats-list`
+
+
+ .. _debugger-command-cheatnextf:
+
+Cheatnextf
+----------
+
+| **cheatnextf <condition>[,<comparisonvalue>]**
+|
+| The cheatnextf command will make comparisons with the initial search.
+|
+| Possible <condition>:
+|
+| **all**
+|
+| No <comparisonvalue> needed.
+|
+| Use to update the last value without changing the current matches.
+|
+| **equal [eq]**
+|
+| Without <comparisonvalue> search for all bytes that are equal to the initial search.
+| With <comparisonvalue> search for all bytes that are equal to the <comparisonvalue>.
+|
+| **notequal [ne]**
+|
+| Without <comparisonvalue> search for all bytes that are not equal to the initial search.
+| With <comparisonvalue> search for all bytes that are not equal to the <comparisonvalue>.
+|
+| **decrease [de, +]**
+|
+| Without <comparisonvalue> search for all bytes that have decreased since the initial search.
+| With <comparisonvalue> search for all bytes that have decreased by the <comparisonvalue> since the initial search.
+|
+| **increase [in, -]**
+|
+| Without <comparisonvalue> search for all bytes that have increased since the initial search.
+|
+| With <comparisonvalue> search for all bytes that have increased by the <comparisonvalue> since the initial search.
+|
+| **decreaseorequal [deeq]**
+|
+| No <comparisonvalue> needed.
+|
+| Search for all bytes that have decreased or have same value since the initial search.
+|
+| **increaseorequal [ineq]**
+|
+| No <comparisonvalue> needed.
+|
+| Search for all bytes that have decreased or have same value since the initial search.
+|
+| **smallerof [lt]**
+|
+| Without <comparisonvalue> this condition is invalid.
+| With <comparisonvalue> search for all bytes that are smaller than the <comparisonvalue>.
+|
+| **greaterof [gt]**
+|
+| Without <comparisonvalue> this condition is invalid.
+| With <comparisonvalue> search for all bytes that are larger than the <comparisonvalue>.
+|
+| **changedby [ch, ~]**
+|
+| Without <comparisonvalue> this condition is invalid
+| With <comparisonvalue> search for all bytes that have changed by the <comparisonvalue> since the initial search.
+|
+|
+| Examples:
+|
+| cheatnextf increase
+|
+| Search for all bytes that have increased since the initial search.
+|
+| cheatnextf decrease, 1
+|
+| Search for all bytes that have decreased by 1 since the initial search.
+|
+| Back to :ref:`debugger-cheats-list`
+
+
+ .. _debugger-command-cheatlist:
+
+Cheatlist
+---------
+
+| **cheatlist [<filename>]**
+|
+| Without <filename> show the list of matches in the debug console.
+| With <filename> save the list of matches in basic XML format to <filename>.
+|
+| Examples:
+|
+| cheatlist
+|
+| Show the current matches in the debug console.
+|
+| cheatlist cheat.txt
+|
+| Save the current matches in XML format to cheat.txt.
+|
+| Back to :ref:`debugger-cheats-list`
+
+
+ .. _debugger-command-cheatundo:
+
+Cheatundo
+---------
+
+| **cheatundo**
+|
+| Undo the results of the last search.
+|
+| The undo command has no effect on the last value.
+|
+|
+| Examples:
+|
+| cheatundo
+|
+| Undo the last search (state only).
+|
+| Back to :ref:`debugger-cheats-list`
+
diff --git a/docs/source/debugger/execution.rst b/docs/source/debugger/execution.rst
new file mode 100644
index 00000000000..ff9ca5f7bf7
--- /dev/null
+++ b/docs/source/debugger/execution.rst
@@ -0,0 +1,360 @@
+.. _debugger-execution-list:
+
+Execution Debugger Commands
+===========================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-step` -- single steps for <count> instructions (F11)
+| :ref:`debugger-command-over` -- single steps over <count> instructions (F10)
+| :ref:`debugger-command-out` -- single steps until the current subroutine/exception handler is exited (Shift-F11)
+| :ref:`debugger-command-go` -- resumes execution, sets temp breakpoint at <address> (F5)
+| :ref:`debugger-command-gint` -- resumes execution, setting temp breakpoint if <irqline> is taken (F7)
+| :ref:`debugger-command-gtime` -- resumes execution until the given delay has elapsed
+| :ref:`debugger-command-gvblank` -- resumes execution, setting temp breakpoint on the next VBLANK (F8)
+| :ref:`debugger-command-next` -- executes until the next CPU switch (F6)
+| :ref:`debugger-command-focus` -- focuses debugger only on <cpu>
+| :ref:`debugger-command-ignore` -- stops debugging on <cpu>
+| :ref:`debugger-command-observe` -- resumes debugging on <cpu>
+| :ref:`debugger-command-trace` -- trace the given CPU to a file (defaults to active CPU)
+| :ref:`debugger-command-traceover` -- trace the given CPU to a file, but skip subroutines (defaults to active CPU)
+| :ref:`debugger-command-traceflush` -- flushes all open trace files.
+
+
+ .. _debugger-command-step:
+
+Step
+----
+
+| **s[tep] [<count>=1]**
+|
+| The step command single steps one or more instructions in the currently executing CPU. By default, step executes one instruction each time it is issued. You can also tell step to step multiple instructions by including the optional <count> parameter.
+|
+| Examples:
+|
+| s
+|
+| Steps forward one instruction on the current CPU.
+|
+| step 4
+|
+| Steps forward four instructions on the current CPU.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-over:
+
+Over
+----
+
+| **o[ver] [<count>=1]**
+|
+| The over command single steps "over" one or more instructions in the currently executing CPU, stepping over subroutine calls and exception handler traps and counting them as a single instruction. Note that when stepping over a subroutine call, code may execute on other CPUs before the subroutine call completes. By default, over executes one instruction each time it is issued. You can also tell step to step multiple instructions by including the optional <count> parameter.
+|
+| Note that the step over functionality may not be implemented on all CPU types. If it is not implemented, then 'over' will behave exactly like 'step'.
+|
+| Examples:
+|
+| o
+|
+| Steps forward over one instruction on the current CPU.
+|
+| over 4
+|
+| Steps forward over four instructions on the current CPU.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-out:
+
+Out
+---
+
+| **out**
+|
+| The out command single steps until it encounters a return from subroutine or return from exception instruction. Note that because it detects return from exception conditions, if you attempt to step out of a subroutine and an interrupt/exception occurs before you hit the end, then you may stop prematurely at the end of the exception handler.
+|
+| Note that the step out functionality may not be implemented on all CPU types. If it is not implemented, then 'out' will behave exactly like 'step'.
+|
+| Examples:
+|
+| out
+|
+| Steps until the current subroutine or exception handler returns.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-go:
+
+Go
+--
+
+| **g[o] [<address>]**
+|
+| The go command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until you manually break in using the assigned key. The go command takes an optional <address> parameter which is a temporary unconditional breakpoint that is set before executing, and automatically removed when hit.
+|
+| Examples:
+|
+| g
+|
+| Resume execution until the next break/watchpoint or until a manual break.
+|
+| g 1234
+|
+| Resume execution, stopping at address 1234 unless something else stops us first.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-gvblank:
+
+Gvblank
+-------
+
+| **gv[blank]**
+|
+| The gvblank command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until the next VBLANK occurs in the emulator.
+|
+| Examples:
+|
+| gv
+|
+| Resume execution until the next break/watchpoint or until the next VBLANK.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-gint:
+
+Gint
+----
+
+| **gi[nt] [<irqline>]**
+|
+| The gint command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until an IRQ is asserted and acknowledged on the current CPU. You can specify <irqline> if you wish to stop execution only on a particular IRQ line being asserted and acknowledged. If <irqline> is omitted, then any IRQ line will stop execution.
+|
+| Examples:
+|
+| gi
+|
+| Resume execution until the next break/watchpoint or until any IRQ is asserted and acknowledged on the current CPU.
+|
+| gint 4
+|
+| Resume execution until the next break/watchpoint or until IRQ line 4 is asserted and acknowledged on the current CPU.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-gtime:
+
+Gtime
+-----
+
+| **gt[ime] <milliseconds>**
+|
+| The gtime command resumes execution of the current code. Control will not be returned to the debugger until a specified delay has elapsed. The delay is in milliseconds.
+|
+| Example:
+|
+| gtime #10000
+|
+| Resume execution for ten seconds
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-next:
+
+Next
+----
+
+| **n[ext]**
+|
+| The next command resumes execution and continues executing until the next time a different CPU is scheduled. Note that if you have used 'ignore' to ignore certain CPUs, you will not stop until a non-'ignore'd CPU is scheduled.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-focus:
+
+Focus
+-----
+
+| **focus <cpu>**
+|
+| Sets the debugger focus exclusively to the given <cpu>. This is equivalent to specifying 'ignore' on all other CPUs.
+|
+| Example:
+|
+| focus 1
+|
+| Focus exclusively CPU #1 while ignoring all other CPUs when using the debugger.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-ignore:
+
+Ignore
+------
+
+| **ignore [<cpu>[,<cpu>[,...]]]**
+|
+| Ignores the specified <cpu> in the debugger. This means that you won't ever see execution on that CPU, nor will you be able to set breakpoints on that CPU. To undo this change use the 'observe' command. You can specify multiple <cpu>s in a single command. Note also that you are not permitted to ignore all CPUs; at least one must be active at all times.
+|
+| Examples:
+|
+| ignore 1
+|
+| Ignore CPU #1 when using the debugger.
+|
+| ignore 2,3,4
+|
+| Ignore CPU #2, #3 and #4 when using the debugger.
+|
+| ignore
+|
+| List the CPUs that are currently ignored.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-observe:
+
+Observe
+-------
+
+| **observe [<cpu>[,<cpu>[,...]]]**
+|
+| Re-enables interaction with the specified <cpu> in the debugger. This command undoes the effects of the 'ignore' command. You can specify multiple <cpu>s in a single command.
+|
+| Examples:
+|
+| observe 1
+|
+| Stop ignoring CPU #1 when using the debugger.
+|
+| observe 2,3,4
+|
+| Stop ignoring CPU #2, #3 and #4 when using the debugger.
+|
+| observe
+|
+| List the CPUs that are currently observed.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-trace:
+
+Trace
+-----
+
+| **trace {<filename>|OFF}[,<cpu>[,[noloop|logerror][,<action>]]]**
+|
+| Starts or stops tracing of the execution of the specified <cpu>. If <cpu> is omitted, the currently active CPU is specified.
+|
+| When enabling tracing, specify the filename in the <filename> parameter. To disable tracing, substitute the keyword 'off' for <filename>.
+|
+| <detectloops> should be either true or false.
+|
+| If 'noloop' is omitted, the trace will have loops detected and condensed to a single line. If 'noloop' is specified, the trace will contain every opcode as it is executed.
+|
+| If 'logerror' is specified, logerror output will augment the trace. If you wish to log additional information on each trace, you can append an <action> parameter which is a command that is executed before each trace is logged. Generally, this is used to include a 'tracelog' command. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the trace command itself.
+|
+|
+| Examples:
+|
+| trace joust.tr
+|
+| Begin tracing the currently active CPU, logging output to joust.tr.
+|
+| trace dribling.tr,0
+|
+| Begin tracing the execution of CPU #0, logging output to dribling.tr.
+|
+| trace starswep.tr,0,noloop
+|
+| Begin tracing the execution of CPU #0, logging output to starswep.tr, with loop detection disabled.
+|
+| trace starswep.tr,0,logerror
+|
+| Begin tracing the execution of CPU #0, logging output (along with logerror output) to starswep.tr.
+|
+| trace starswep.tr,0,logerror|noloop
+|
+| Begin tracing the execution of CPU #0, logging output (along with logerror output) to starswep.tr, with loop detection disabled.
+|
+| trace >>pigskin.tr
+|
+| Begin tracing the currently active CPU, appending log output to pigskin.tr.
+|
+| trace off,0
+|
+| Turn off tracing on CPU #0.
+|
+| trace asteroid.tr,0,,{tracelog "A=%02X ",a}
+|
+| Begin tracing the execution of CPU #0, logging output to asteroid.tr. Before each line, output A=<aval> to the tracelog.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-traceover:
+
+Traceover
+---------
+
+| **traceover {<filename>|OFF}[,<cpu>[,<detectloops>[,<action>]]]**
+|
+| Starts or stops tracing of the execution of the specified <cpu>.
+|
+| When tracing reaches a subroutine or call, tracing will skip over the subroutine. The same algorithm is used as is used in the step over command. This means that traceover will not work properly when calls are recursive or the return address is not immediately following the call instruction.
+|
+| <detectloops> should be either true or false. If <detectloops> is *true or omitted*, the trace will have loops detected and condensed to a single line. If it is false, the trace will contain every opcode as it is executed.
+| If <cpu> is omitted, the currently active CPU is specified.
+| When enabling tracing, specify the filename in the <filename> parameter.
+| To disable tracing, substitute the keyword 'off' for <filename>.
+| If you wish to log additional information on each trace, you can append an <action> parameter which is a command that is executed before each trace is logged. Generally, this is used to include a 'tracelog' command. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the trace command itself.
+|
+|
+| Examples:
+|
+| traceover joust.tr
+|
+| Begin tracing the currently active CPU, logging output to joust.tr.
+|
+| traceover dribling.tr,0
+|
+| Begin tracing the execution of CPU #0, logging output to dribling.tr.
+|
+| traceover starswep.tr,0,false
+|
+| Begin tracing the execution of CPU #0, logging output to starswep.tr, with loop detection disabled.
+|
+| traceover off,0
+|
+| Turn off tracing on CPU #0.
+|
+| traceover asteroid.tr,0,true,{tracelog "A=%02X ",a}
+|
+| Begin tracing the execution of CPU #0, logging output to asteroid.tr. Before each line, output A=<aval> to the tracelog.
+|
+| Back to :ref:`debugger-execution-list`
+
+
+ .. _debugger-command-traceflush:
+
+Traceflush
+----------
+
+| **traceflush**
+|
+| Flushes all open trace files.
+|
+| Back to :ref:`debugger-execution-list`
diff --git a/docs/source/debugger/expressions.rst b/docs/source/debugger/expressions.rst
new file mode 100644
index 00000000000..4b7aeacb51a
--- /dev/null
+++ b/docs/source/debugger/expressions.rst
@@ -0,0 +1,36 @@
+.. _debugger-expressions-list:
+
+Debugger Expressions Guide
+==========================
+
+
+Expressions can be used anywhere a numeric parameter is expected. The syntax for expressions is very close to standard C-style syntax with full operator ordering and parentheses. There are a few operators missing (notably the trinary ? : operator), and a few new ones (memory accessors). The table below lists all the operators in their order, highest precedence operators first.
+
+|
+| ( ) : standard parentheses
+| ++ -- : postfix increment/decrement
+| ++ -- ~ ! - + b@ w@ d@ q@ : prefix inc/dec, binary NOT, logical NOT, unary +/-, memory access
+| * / % : multiply, divide, modulus
+| + - : add, subtract
+| << >> : shift left/right
+| < <= > >= : less than, less than or equal, greater than, greater than or equal
+| == != : equal, not equal
+| & : binary AND
+| ^ : binary XOR
+| | : binary OR
+| && : logical AND
+| || : logical OR
+| = \*= /= %= += -= <<= >>= &= \|= ^= : assignment
+| , : separate terms, function parameters
+|
+|
+
+
+Differences from C Behaviors
+----------------------------
+
+First, all math is performed on full 64-bit unsigned values, so things like a < 0 won't work as expected.
+Second, the logical operators && and || do not have short-circuit properties -- both halves are always evaluated.
+Finally, the new memory operators work like this:
+| b@<addr> refers to the byte read from <addr>.
+| Similarly, w@ refers to a word in memory, d@ refers to a dword in memory, and q@ refers to a qword in memory. The memory operators can be used as both lvalues and rvalues, so you can write b@100 = ff to store a byte in memory. By default these operators read from the program memory space, but you can override that by prefixing them with a 'd' or an 'i'. So dw@300 refers to data memory word at address 300 and id@400 refers to an I/O memory dword at address 400.
diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst
new file mode 100644
index 00000000000..33b60b9cc5a
--- /dev/null
+++ b/docs/source/debugger/general.rst
@@ -0,0 +1,389 @@
+.. _debugger-general-list:
+
+General Debugger Commands
+=========================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-do` -- evaluates the given expression
+| :ref:`debugger-command-symlist` -- lists registered symbols
+| :ref:`debugger-command-softreset` -- executes a soft reset
+| :ref:`debugger-command-hardreset` -- executes a hard reset
+| :ref:`debugger-command-print` -- prints one or more <item>s to the console
+| :ref:`debugger-command-printf` -- prints one or more <item>s to the console using <format>
+| :ref:`debugger-command-logerror` -- outputs one or more <item>s to the error.log
+| :ref:`debugger-command-tracelog` -- outputs one or more <item>s to the trace file using <format>
+| :ref:`debugger-command-tracesym` -- outputs one or more <item>s to the trace file
+| history -- outputs a brief history of visited opcodes (**to fix: help missing for this command**)
+| :ref:`debugger-command-trackpc` -- visually track visited opcodes [boolean to turn on and off, for the given cpu, clear]
+| :ref:`debugger-command-trackmem` -- record which PC writes to each memory address [boolean to turn on and off, clear]
+| :ref:`debugger-command-pcatmem` -- query which PC wrote to a given memory address for the current CPU
+| :ref:`debugger-command-rewind` -- go back in time by loading the most recent rewind state
+| :ref:`debugger-command-statesave` -- save a state file for the current driver
+| :ref:`debugger-command-stateload` -- load a state file for the current driver
+| :ref:`debugger-command-snap` -- save a screen snapshot.
+| :ref:`debugger-command-source` -- reads commands from <filename> and executes them one by one
+| :ref:`debugger-command-quit` -- exits MAME and the debugger
+
+
+ .. _debugger-command-do:
+
+Do
+--
+
+| **do <expression>**
+|
+| The do command simply evaluates the given <expression>. This is typically used to set or modify variables.
+|
+| Examples:
+|
+| do pc = 0
+|
+| Sets the register 'pc' to 0.
+|
+| Back to :ref:`debugger-general-list`
+
+ .. _debugger-command-symlist:
+
+Symlist
+-------
+
+| **symlist [<cpu>]**
+|
+| Lists registered symbols. If <cpu> is not specified, then symbols in the global symbol table are displayed; otherwise, the symbols for <cpu>'s specific CPU are displayed. Symbols are listed alphabetically. Read-only symbols are flagged with an asterisk.
+|
+| Examples:
+|
+| symlist
+|
+| Displays the global symbol table.
+|
+| symlist 2
+|
+| Displays the symbols specific to CPU #2.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-softreset:
+
+Softreset
+---------
+
+| **softreset**
+|
+| Executes a soft reset.
+|
+| Examples:
+|
+| softreset
+|
+| Executes a soft reset.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-hardreset:
+
+Hardreset
+---------
+
+| **hardreset**
+|
+| Executes a hard reset.
+|
+| Examples:
+|
+| hardreset
+|
+| Executes a hard reset.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-print:
+
+Print
+-----
+
+| **print <item>[,...]**
+|
+| The print command prints the results of one or more expressions to the debugger console as hexadecimal values.
+|
+| Examples:
+|
+| print pc
+|
+| Prints the value of 'pc' to the console as a hex number.
+|
+| print a,b,a+b
+|
+| Prints a, b, and the value of a+b to the console as hex numbers.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-printf:
+
+Printf
+------
+
+| **printf <format>[,<item>[,...]]**
+|
+| The printf command performs a C-style printf to the debugger console. Only a very limited set of formatting options are available:
+|
+| %[0][<n>]d -- prints <item> as a decimal value with optional digit count and zero-fill
+| %[0][<n>]x -- prints <item> as a hexadecimal value with optional digit count and zero-fill
+|
+| All remaining formatting options are ignored. Use %% together to output a % character. Multiple lines can be printed by embedding a \\n in the text.
+|
+| Examples:
+|
+| printf "PC=%04X",pc
+|
+| Prints PC=<pcval> where <pcval> is displayed in hexadecimal with 4 digits with zero-fill.
+|
+| printf "A=%d, B=%d\nC=%d",a,b,a+b
+|
+| Prints A=<aval>, B=<bval> on one line, and C=<a+bval> on a second line.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-logerror:
+
+Logerror
+--------
+
+| **logerror <format>[,<item>[,...]]**
+|
+| The logerror command performs a C-style printf to the error log. Only a very limited set of formatting options are available:
+|
+| %[0][<n>]d -- logs <item> as a decimal value with optional digit count and zero-fill
+| %[0][<n>]x -- logs <item> as a hexadecimal value with optional digit count and zero-fill
+|
+| All remaining formatting options are ignored. Use %% together to output a % character. Multiple lines can be printed by embedding a \\n in the text.
+|
+| Examples:
+|
+| logerror "PC=%04X",pc
+|
+| Logs PC=<pcval> where <pcval> is displayed in hexadecimal with 4 digits with zero-fill.
+|
+| logerror "A=%d, B=%d\nC=%d",a,b,a+b
+|
+| Logs A=<aval>, B=<bval> on one line, and C=<a+bval> on a second line.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-tracelog:
+
+Tracelog
+--------
+
+| **tracelog <format>[,<item>[,...]]**
+|
+| The tracelog command performs a C-style printf and routes the output to the currently open trace file (see the 'trace' command for details). If no file is currently open, tracelog does nothing. Only a very limited set of formatting options are available. See the :ref:`debugger-command-printf` help for details.
+|
+| Examples:
+|
+| tracelog "PC=%04X",pc
+|
+| Outputs PC=<pcval> where <pcval> is displayed in hexadecimal with 4 digits with zero-fill.
+|
+| printf "A=%d, B=%d\nC=%d",a,b,a+b
+|
+| Outputs A=<aval>, B=<bval> on one line, and C=<a+bval> on a second line.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-tracesym:
+
+Tracesym
+--------
+
+| **tracesym <item>[,...]**
+|
+| The tracesym command prints the specified symbols and routes the output to the currently open trace file (see the 'trace' command for details). If no file is currently open, tracesym does nothing.
+|
+| Examples:
+|
+| tracelog pc
+|
+| Outputs PC=<pcval> where <pcval> is displayed in the default format.
+|
+| printf a,b
+|
+| Outputs A=<aval>, B=<bval> on one line.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-trackpc:
+
+Trackpc
+-------
+
+| **trackpc [<bool>,<cpu>,<bool>]**
+|
+| The trackpc command displays which program counters have already been visited in all disassembler windows. The first boolean argument toggles the process on and off. The second argument is a cpu selector; if no cpu is specified, the current cpu is automatically selected. The third argument is a boolean denoting if the existing data should be cleared or not.
+|
+| Examples:
+|
+| trackpc 1
+|
+| Begin tracking the current cpu's pc.
+|
+| trackpc 1, 0, 1
+|
+| Continue tracking pc on cpu 0, but clear existing track info.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-trackmem:
+
+Trackmem
+--------
+
+| **trackmem [<bool>,<cpu>,<bool>]**
+|
+| The trackmem command logs the PC at each time a memory address is written to. The first boolean argument toggles the process on and off. The second argument is a cpu selector; if no cpu is specified, the current cpu is automatically selected. The third argument is a boolean denoting if the existing data should be cleared or not. Please refer to the pcatmem command for information on how to retrieve this data. Also, right clicking in a memory window will display the logged PC for the given address.
+|
+| Examples:
+|
+| trackmem
+|
+| Begin tracking the current CPU's pc.
+|
+| trackmem 1, 0, 1
+|
+| Continue tracking memory writes on cpu 0, but clear existing track info.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-pcatmem:
+
+Pcatmem
+-------
+
+| **pcatmem(p/d/i) <address>[,<cpu>]**
+|
+| **pcatmemp <address>[,<cpu>]** -- query which PC wrote to a given program memory address for the current CPU
+| **pcatmemd <address>[,<cpu>]** -- query which PC wrote to a given data memory address for the current CPU
+| **pcatmemi <address>[,<cpu>]** -- query which PC wrote to a given I/O memory address for the current CPU (you can also query this info by right clicking in a memory window)
+|
+| The pcatmem command returns which PC wrote to a given memory address for the current CPU. The first argument is the requested address. The second argument is a cpu selector; if no cpu is specified, the current cpu is automatically selected. Right clicking in a memory window will also display the logged PC for the given address.
+|
+| Examples:
+|
+| pcatmem 400000
+|
+| Print which PC wrote this CPU's memory location 0x400000.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-rewind:
+
+Rewind
+------
+
+| **rewind[rw]**
+|
+| The rewind command loads the most recent RAM-based state. Rewind states, when enabled, are saved when "step", "over", or "out" command gets executed, storing the machine state as of the moment before actually stepping. Consecutively loading rewind states can work like reverse execution. Depending on which steps forward were taken previously, the behavior can be similar to GDB's "reverse-stepi" or "reverse-next". All output for this command is currently echoed into the running machine window. Previous memory and PC tracking statistics are cleared, actual reverse execution does not occur.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-statesave:
+
+Statesave
+---------
+
+| **statesave[ss] <filename>**
+|
+| The statesave command creates a save state at this exact moment in time. The given state file gets written to the standard state directory (sta), and gets .sta added to it - no file extension necessary. All output for this command is currently echoed into the running machine window.
+|
+| Examples:
+|
+| statesave foo
+|
+| Writes file 'foo.sta' in the default state save directory.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-stateload:
+
+Stateload
+---------
+
+| **stateload[sl] <filename>**
+|
+| The stateload command retrieves a save state from disk. The given state file gets read from the standard state directory (sta), and gets .sta added to it - no file extension necessary. All output for this command is currently echoed into the running machine window. Previous memory and PC tracking statistics are cleared.
+|
+| Examples:
+|
+| stateload foo
+|
+| Reads file 'foo.sta' from the default state save directory.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-snap:
+
+Snap
+----
+
+| **snap [[<filename>], <scrnum>]**
+|
+| The snap command takes a snapshot of the current video display and saves it to the configured snapshot directory. If <filename> is specified explicitly, a single screenshot for <scrnum> is saved under the requested filename. If <filename> is omitted, all screens are saved using the same default rules as the "save snapshot" key in MAME proper.
+|
+| Examples:
+|
+| snap
+|
+| Takes a snapshot of the current video screen and saves to the next non-conflicting filename in the configured snapshot directory.
+|
+| snap shinobi
+|
+| Takes a snapshot of the current video screen and saves it as 'shinobi.png' in the configured snapshot directory.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-source:
+
+Source
+------
+
+| **source <filename>**
+|
+| The source command reads in a set of debugger commands from a file and executes them one by one, similar to a batch file.
+|
+| Examples:
+|
+| source break_and_trace.cmd
+|
+| Reads in debugger commands from break_and_trace.cmd and executes them.
+|
+| Back to :ref:`debugger-general-list`
+
+
+ .. _debugger-command-quit:
+
+Quit
+----
+
+| **quit**
+|
+| The quit command exits MAME immediately.
+|
+| Back to :ref:`debugger-general-list`
+
diff --git a/docs/source/debugger/image.rst b/docs/source/debugger/image.rst
new file mode 100644
index 00000000000..524bdd5c35a
--- /dev/null
+++ b/docs/source/debugger/image.rst
@@ -0,0 +1,63 @@
+.. _debugger-image-list:
+
+Image Debugger Commands
+=======================
+
+
+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:
+
+Images
+------
+
+| **images**
+|
+| Used to display list of available image devices.
+|
+| Examples:
+|
+| images
+|
+| Show list of devices and mounted files for current driver.
+
+
+ .. _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.
+
+
+ .. _debugger-command-unmount:
+
+Unmount
+-------
+
+| **unmount <device>**
+|
+| Unmounts file from image <device>.
+|
+| Examples:
+|
+| unmount cart
+|
+| Unmounts any file mounted on device named cart.
+
+
diff --git a/docs/source/debugger/index.rst b/docs/source/debugger/index.rst
new file mode 100644
index 00000000000..3d89733a37f
--- /dev/null
+++ b/docs/source/debugger/index.rst
@@ -0,0 +1,18 @@
+MAME Debugger
+-------------------
+
+This section covers the built-in MAME debugger
+
+.. toctree::
+ :titlesonly:
+
+ general
+ memory
+ execution
+ breakpoint
+ watchpoint
+ registerpoints
+ annotation
+ cheats
+ image
+ expressions
diff --git a/docs/source/debugger/memory.rst b/docs/source/debugger/memory.rst
new file mode 100644
index 00000000000..8696e6997c0
--- /dev/null
+++ b/docs/source/debugger/memory.rst
@@ -0,0 +1,168 @@
+.. _debugger-memory-list:
+
+Memory Debugger Commands
+========================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-dasm` -- disassemble to the given file
+| :ref:`debugger-command-find` -- search program memory, data memory, or I/O memory for data
+| :ref:`debugger-command-dump` -- dump program memory, data memory, or I/O memory as text
+| :ref:`debugger-command-save` -- save binary program, data, or I/O memory to the given file
+| :ref:`debugger-command-load` -- load binary program memory, data memory, or I/O memory from the given file
+| :ref:`debugger-command-map` -- map logical program, data, or I/O address to physical address and bank
+
+
+
+
+ .. _debugger-command-dasm:
+
+Dasm
+----
+
+| **dasm <filename>,<address>,<length>[,<opcodes>[,<cpu>]]**
+|
+| The dasm command disassembles program memory to the file specified in the <filename> parameter. <address> indicates the address of the start of disassembly, and <length> indicates how much memory to disassemble. The range <address> through <address>+<length>-1 inclusive will be output to the file. By default, the raw opcode data is output with each line. The optional <opcodes> parameter can be used to enable (1) or disable (0) this feature. Finally, you can disassemble code from another CPU by specifying the <cpu> parameter.
+|
+| Examples:
+|
+| dasm venture.asm,0,10000
+|
+| Disassembles addresses 0-ffff in the current CPU, including raw opcode data, to the file 'venture.asm'.
+|
+| dasm harddriv.asm,3000,1000,0,2
+|
+| Disassembles addresses 3000-3fff from CPU #2, with no raw opcode data, to the file 'harddriv.asm'.
+|
+| Back to :ref:`debugger-memory-list`
+
+
+ .. _debugger-command-find:
+
+Find
+----
+
+| **f[ind][{d|i}] <address>,<length>[,<data>[,...]]**
+|
+| The **find**/**findd**/**findi** commands search through memory for the specified sequence of data. 'find' will search program space memory, while 'findd' will search data space memory and 'findi' will search I/O space memory. <address> indicates the address to begin searching, and <length> indicates how much memory to search. <data> can either be a quoted string or a numeric value or expression or the wildcard character '?'. Strings by default imply a byte-sized search; non-string data is searched by default in the native word size of the CPU. To override the search size for non-strings, you can prefix the value with b. to force byte- sized search, w. for word-sized search, d. for dword-sized, and q. for qword-sized. Overrides are remembered, so if you want to search for a series of words, you need only to prefix the first value with a w. Note also that you can intermix sizes in order to perform more complex searches. The entire range <address> through <address>+<length>-1 inclusive will be searched for the sequence, and all occurrences will be displayed.
+|
+| Examples:
+|
+| find 0,10000,"HIGH SCORE",0
+|
+| Searches the address range 0-ffff in the current CPU for the string "HIGH SCORE" followed by a 0 byte.
+|
+| findd 3000,1000,w.abcd,4567
+|
+| Searches the data memory address range 3000-3fff for the word-sized value abcd followed by the word-sized value 4567.
+|
+| find 0,8000,"AAR",d.0,"BEN",w.0
+|
+| Searches the address range 0000-7fff for the string "AAR" followed by a dword-sized 0 followed by the string "BEN", followed by a word-sized 0.
+|
+| Back to :ref:`debugger-memory-list`
+
+
+ .. _debugger-command-dump:
+
+Dump
+----
+
+| **dump[{d|i}] <filename>,<address>,<length>[,<size>[,<ascii>[,<cpu>]]]**
+|
+| The **dump**/**dumpd**/**dumpi** commands dump memory to the text file specified in the <filename> parameter.
+| 'dump' will dump program space memory, while 'dumpd' will dump data space memory and 'dumpi' will dump I/O space memory.
+| <address> indicates the address of the start of dumping, and <length> indicates how much memory to dump. The range <address> through <address>+<length>-1 inclusive will be output to the file.
+| By default, the data will be output in byte format, unless the underlying address space is word/dword/qword-only. You can override this by specifying the <size> parameter, which can be used to group the data in 1, 2, 4 or 8-byte chunks.
+| The optional <ascii> parameter can be used to enable (1) or disable (0) the output of ASCII characters to the right of each line; by default, this is enabled.
+| Finally, you can dump memory from another CPU by specifying the <cpu> parameter.
+|
+|
+| Examples:
+|
+| dump venture.dmp,0,10000
+|
+| Dumps addresses 0-ffff in the current CPU in 1-byte chunks, including ASCII data, to the file 'venture.dmp'.
+|
+| dumpd harddriv.dmp,3000,1000,4,0,3
+|
+| Dumps data memory addresses 3000-3fff from CPU #3 in 4-byte chunks, with no ASCII data, to the file 'harddriv.dmp'.
+|
+| Back to :ref:`debugger-memory-list`
+
+
+ .. _debugger-command-save:
+
+Save
+----
+
+| **save[{d|i}] <filename>,<address>,<length>[,<cpu>]**
+|
+| The **save**/**saved**/**savei** commands save raw memory to the binary file specified in the <filename> parameter.
+| 'save' will save program space memory, while 'saved' will save data space memory and 'savei' will save I/O space memory.
+| <address> indicates the address of the start of saving, and <length> indicates how much memory to save. The range <address> through <address>+<length>-1 inclusive will be output to the file.
+| You can also save memory from another CPU by specifying the <cpu> parameter.
+|
+|
+| Examples:
+|
+| save venture.bin,0,10000
+|
+| Saves addresses 0-ffff in the current CPU to the binary file 'venture.bin'.
+|
+| saved harddriv.bin,3000,1000,3
+|
+| Saves data memory addresses 3000-3fff from CPU #3 to the binary file 'harddriv.bin'.
+|
+| Back to :ref:`debugger-memory-list`
+
+
+ .. _debugger-command-load:
+
+Load
+----
+
+| **load[{d|i}] <filename>,<address>[,<length>,<cpu>]**
+|
+| The **load**/**loadd**/**loadi** commands load raw memory from the binary file specified in the <filename> parameter.
+| 'load' will load program space memory, while 'loadd' will load data space memory and 'loadi' will load I/O space memory.
+| <address> indicates the address of the start of saving, and <length> indicates how much memory to load. The range <address> through <address>+<length>-1 inclusive will be read in from the file.
+| If you specify <length> = 0 or a length greater than the total length of the file it will load the entire contents of the file and no more.
+| You can also load memory from another CPU by specifying the <cpu> parameter.
+|
+| NOTE: This will only actually write memory that is possible to overwrite in the Memory Window
+|
+|
+| Examples:
+|
+| load venture.bin,0,10000
+|
+| Loads addresses 0-ffff in the current CPU from the binary file 'venture.bin'.
+|
+| loadd harddriv.bin,3000,1000,3
+|
+| Loads data memory addresses 3000-3fff from CPU #3 from the binary file 'harddriv.bin'.
+|
+| Back to :ref:`debugger-memory-list`
+
+
+ .. _debugger-command-map:
+
+Map
+---
+
+| **map[{d|i}] <address>**
+|
+| The map/mapd/mapi commands map a logical address in memory to the correct physical address, as well as specifying the bank.
+| 'map' will map program space memory, while 'mapd' will map data space memory and 'mapi' will map I/O space memory.
+|
+| Example:
+|
+| map 152d0
+|
+| Gives physical address and bank for logical address 152d0 in program memory
+|
+| Back to :ref:`debugger-memory-list`
+
+
diff --git a/docs/source/debugger/registerpoints.rst b/docs/source/debugger/registerpoints.rst
new file mode 100644
index 00000000000..e9be6e7d23c
--- /dev/null
+++ b/docs/source/debugger/registerpoints.rst
@@ -0,0 +1,120 @@
+.. _debugger-registerpoints-list:
+
+Registerpoints Debugger Commands
+================================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-rpset` -- sets a registerpoint to trigger on <condition>
+| :ref:`debugger-command-rpclear` -- clears a given registerpoint or all if no <rpnum> specified
+| :ref:`debugger-command-rpdisable` -- disabled a given registerpoint or all if no <rpnum> specified
+| :ref:`debugger-command-rpenable` -- enables a given registerpoint or all if no <rpnum> specified
+| :ref:`debugger-command-rplist` -- lists all the registerpoints
+
+
+
+ .. _debugger-command-rpset:
+
+Rpset
+-----
+
+| **rp[set] {<condition>}[,<action>]]**
+|
+| Sets a new registerpoint which will be triggered when <condition> is met. The condition must be specified between curly braces to prevent the condition from being evaluated as an assignment.
+| The optional <action> parameter provides a command that is executed whenever the registerpoint is hit. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the rpset command itself.
+| Each registerpoint that is set is assigned an index which can be used in other registerpoint commands to reference this registerpoint.
+|
+| Examples:
+|
+| rp {PC==0150}
+|
+| Set a registerpoint that will halt execution whenever the PC register equals 0x150.
+|
+| temp0=0; rp {PC==0150},{temp0++; g}
+|
+| Set a registerpoint that will increment the variable temp0 whenever the PC register equals 0x0150.
+|
+| rp {temp0==5}
+|
+| Set a registerpoint that will halt execution whenever the temp0 variable equals 5.
+|
+| Back to :ref:`debugger-registerpoints-list`
+
+
+ .. _debugger-command-rpclear:
+
+Rpclear
+-------
+
+| **rpclear [<rpnum>]**
+|
+| The rpclear command clears a registerpoint. If <rpnum> is specified, only the requested registerpoint is cleared, otherwise all registerpoints are cleared.
+|
+| Examples:
+|
+| rpclear 3
+|
+| Clear registerpoint index 3.
+|
+| rpclear
+|
+| Clear all registerpoints.
+|
+| Back to :ref:`debugger-registerpoints-list`
+
+
+ .. _debugger-command-rpdisable:
+
+Rpdisable
+---------
+
+| **rpdisable [<rpnum>]**
+|
+| The rpdisable command disables a registerpoint. If <rpnum> is specified, only the requested registerpoint is disabled, otherwise all registerpoints are disabled. Note that disabling a registerpoint does not delete it, it just temporarily marks the registerpoint as inactive.
+|
+| Examples:
+|
+| rpdisable 3
+|
+| Disable registerpoint index 3.
+|
+| rpdisable
+|
+| Disable all registerpoints.
+|
+| Back to :ref:`debugger-registerpoints-list`
+
+
+ .. _debugger-command-rpenable:
+
+Rpenable
+--------
+
+| **rpenable [<rpnum>]**
+|
+| The rpenable command enables a registerpoint. If <rpnum> is specified, only the requested registerpoint is enabled, otherwise all registerpoints are enabled.
+|
+| Examples:
+|
+| rpenable 3
+|
+| Enable registerpoint index 3.
+|
+| rpenable
+|
+| Enable all registerpoints.
+|
+| Back to :ref:`debugger-registerpoints-list`
+
+
+ .. _debugger-command-rplist:
+
+Rplist
+------
+
+| **rplist**
+|
+| The rplist command lists all the current registerpoints, along with their index and any actions attached to them.
+|
+| Back to :ref:`debugger-registerpoints-list`
diff --git a/docs/source/debugger/watchpoint.rst b/docs/source/debugger/watchpoint.rst
new file mode 100644
index 00000000000..12659a5b983
--- /dev/null
+++ b/docs/source/debugger/watchpoint.rst
@@ -0,0 +1,128 @@
+.. _debugger-watchpoints-list:
+
+Watchpoint Debugger Commands
+============================
+
+
+You can also type **help <command>** for further details on each command in the MAME Debugger interface.
+
+| :ref:`debugger-command-wpset` -- sets program, data, or I/O space watchpoint
+| :ref:`debugger-command-wpclear` -- clears a given watchpoint or all if no <wpnum> specified
+| :ref:`debugger-command-wpdisable` -- disables a given watchpoint or all if no <wpnum> specified
+| :ref:`debugger-command-wpenable` -- enables a given watchpoint or all if no <wpnum> specified
+| :ref:`debugger-command-wplist` -- lists all the watchpoints
+
+ .. _debugger-command-wpset:
+
+Wpset
+-----
+
+| **wp[{d|i}][set] <address>,<length>,<type>[,<condition>[,<action>]]**
+|
+| Sets a new watchpoint starting at the specified <address> and extending for <length>. The inclusive range of the watchpoint is <address> through <address> + <length> - 1.
+| The 'wpset' command sets a watchpoint on program memory; the 'wpdset' command sets a watchpoint on data memory; and the 'wpiset' sets a watchpoint on I/O memory.
+| The <type> parameter specifies which sort of accesses to trap on. It can be one of three values: 'r' for a read watchpoint 'w' for a write watchpoint, and 'rw' for a read/write watchpoint.
+|
+| The optional <condition> parameter lets you specify an expression that will be evaluated each time the watchpoint is hit. If the result of the expression is true (non-zero), the watchpoint will actually halt execution; otherwise, execution will continue with no notification.
+| The optional <action> parameter provides a command that is executed whenever the watchpoint is hit and the <condition> is true. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the wpset command itself.
+| Each watchpoint that is set is assigned an index which can be used in other watchpoint commands to reference this watchpoint.
+| In order to help <condition> expressions, two variables are available. For all watchpoints, the variable 'wpaddr' is set to the address that actually triggered the watchpoint. For write watchpoints, the variable 'wpdata' is set to the data that is being written.
+|
+| Examples:
+|
+| wp 1234,6,rw
+|
+| Set a watchpoint that will halt execution whenever a read or write occurs in the address range 1234-1239 inclusive.
+|
+| wp 23456,a,w,wpdata == 1
+|
+| Set a watchpoint that will halt execution whenever a write occurs in the address range 23456-2345f AND the data written is equal to 1.
+|
+| wp 3456,20,r,1,{printf "Read @ %08X\n",wpaddr; g}
+|
+| Set a watchpoint that will halt execution whenever a read occurs in the address range 3456-3475. When this happens, print Read @ <wpaddr> and continue executing.
+|
+| temp0 = 0; wp 45678,1,w,wpdata==f0,{temp0++; g}
+|
+| Set a watchpoint that will halt execution whenever a write occurs to the address 45678 AND the value being written is equal to f0. When that happens, increment the variable temp0 and resume execution.
+|
+| Back to :ref:`debugger-watchpoints-list`
+
+
+ .. _debugger-command-wpclear:
+
+Wpclear
+-------
+
+| **wpclear [<wpnum>]**
+|
+| The wpclear command clears a watchpoint. If <wpnum> is specified, only the requested watchpoint is cleared, otherwise all watchpoints are cleared.
+|
+| Examples:
+|
+| wpclear 3
+|
+| Clear watchpoint index 3.
+|
+| wpclear
+|
+| Clear all watchpoints.
+|
+| Back to :ref:`debugger-watchpoints-list`
+
+
+ .. _debugger-command-wpdisable:
+
+Wpdisable
+---------
+
+| **wpdisable [<wpnum>]**
+|
+| The wpdisable command disables a watchpoint. If <wpnum> is specified, only the requested watchpoint is disabled, otherwise all watchpoints are disabled. Note that disabling a watchpoint does not delete it, it just temporarily marks the watchpoint as inactive.
+|
+| Examples:
+|
+| wpdisable 3
+|
+| Disable watchpoint index 3.
+|
+| wpdisable
+|
+| Disable all watchpoints.
+|
+| Back to :ref:`debugger-watchpoints-list`
+
+
+ .. _debugger-command-wpenable:
+
+Wpenable
+--------
+
+| **wpenable [<wpnum>]**
+|
+| The wpenable command enables a watchpoint. If <wpnum> is specified, only the requested watchpoint is enabled, otherwise all watchpoints are enabled.
+|
+| Examples:
+|
+| wpenable 3
+|
+| Enable watchpoint index 3.
+|
+| wpenable
+|
+| Enable all watchpoints.
+|
+| Back to :ref:`debugger-watchpoints-list`
+
+
+ .. _debugger-command-wplist:
+
+Wplist
+------
+
+| **wplist**
+|
+| The wplist command lists all the current watchpoints, along with their index and any conditions or actions attached to them.
+|
+| Back to :ref:`debugger-watchpoints-list`
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 33d9188911b..4d31c42c873 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -18,6 +18,7 @@ MAME Documentation
commandline/index
advanced/index
+ debugger/index
tools/index
techspecs/index