summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/debugger/breakpoint.rst
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2021-10-14 08:00:04 +1100
committer Vas Crabb <vas@vastheman.com>2021-10-14 08:00:04 +1100
commit96ca1dbd965df08ed4ab1f23053690c9ce540f94 (patch)
tree7c357aa9efe72e7e9c8b6e7084cec9fa859e214a /docs/source/debugger/breakpoint.rst
parent75f9660fa29d3d68a522fa96dbc92ef02baff2b8 (diff)
More user experience improvements:
frontend: Allow clicking the adjuster arrows on menu items. This allows things like video options and DIP switches to be configured using a mouse only. Also fixed a bug preventing paging menus with a mouse if the first item scrolled off the bottom is not selectable. debugger: Allow wplist and bplist to accept a CPU argument to list breakpoints/watchpoints for a single CPU only. debugger: Fixed some corner cases in address space syntax in memory accesses, and allowed memory region accesses to use tags relative to the visible CPU. emu/softlist.cpp: Ignore notes elements when loading software lists. It's effectively a comment that isn't a comment syntactically, it's being used for things that are not useful to display in the internal UI, and it slows down startup. docs: Updated three more pages of debugger documentation. Also updated more of the built-in debugger help. minimaws: Fixed up schema for software list notes, made sofware list notes display initially collapsed.
Diffstat (limited to 'docs/source/debugger/breakpoint.rst')
-rw-r--r--docs/source/debugger/breakpoint.rst237
1 files changed, 137 insertions, 100 deletions
diff --git a/docs/source/debugger/breakpoint.rst b/docs/source/debugger/breakpoint.rst
index 7dede5475be..1e61157c854 100644
--- a/docs/source/debugger/breakpoint.rst
+++ b/docs/source/debugger/breakpoint.rst
@@ -3,126 +3,163 @@
Breakpoint Debugger Commands
============================
+:ref:`debugger-command-bpset`
+ sets a breakpoint at <address>
+:ref:`debugger-command-bpclear`
+ clears a specific breakpoint or all breakpoints
+:ref:`debugger-command-bpdisable`
+ disables a specific breakpoint or all breakpoints
+:ref:`debugger-command-bpenable`
+ enables a specific breakpoint or all breakpoints
+:ref:`debugger-command-bplist`
+ lists breakpoints
-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:
+.. _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:
+**bp[set] <address>[:<CPU>][,<condition>[,<action>]]**
+
+Sets a new execution breakpoint at the specified **<address>**. The
+**<address>** may optionally be followed by a colon and a tag or
+debugger CPU number to set a breakpoint for a specific CPU. If no CPU
+is specified, the breakpoint will be set for the CPU currently visible
+in the debugger.
+
+The optional **<condition>** parameter lets you specify an expression
+that will be evaluated each time the breakpoint address is hit. If the
+result of the expression is true (non-zero), the breakpoint will halt
+execution; otherwise, execution will continue with no notification. The
+optional **<action>** parameter provides a command to be executed
+whenever the breakpoint is hit and the **<condition>** is true. Note
+that you may need to surround the action with braces ``{ }`` to ensure
+commas and semicolons within the command are not interpreted in the
+context of the ``bpset`` command itself.
+
+Each breakpoint that is set is assigned a numeric index which can be
+used to refer to it in other breakpoint commands. Breakpoint indices
+are unique throughout a session.
+
+Examples:
+
+``bp 1234``
+ Set a breakpoint for the visible CPU that will halt execution
+ whenever the PC is equal to 1234.
+``bp 23456,a0 == 0 && a1 == 0``
+ Set a breakpoint for the visible CPU that will halt execution
+ whenever the PC is equal to 23456 *and* the expression
+ ``a0 == 0 && a1 == 0`` is true.
+``bp 3456:audiocpu,1,{ printf "A0=%08X\n",a0 ; g }``
+ Set a breakpoint for the CPU with the absolute tag path
+ ``:audiocpu`` that will halt execution whenever the PC is equal to
+ 3456. When this happens, print **A0=<a0val>** to the debugger
+ console and resume execution.
+``bp 45678:2,a0==100,{ a0 = ff ; g }``
+ Set a breakpoint on the third CPU in the system (zero-based index)
+ 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 for the visible CPU 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 sixteen 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:
+**bpclear [<bpnum>]**
+
+Clear breakpoints. If **<bpnum>** is specified, the breakpoint it
+refers to will be cleared. If **<bpnum>** is not specified, all
+breakpoints will be cleared.
+
+Examples:
+
+``bpclear 3``
+ Clear the breakpoint with 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:
+**bpdisable [<bpnum>]**
+
+Disable breakpoints. If **<bpnum>** is specified, the breakpoint it
+refers to will be disabled. If **<bpnum>** is not specified, all
+breakpoints will be disabled.
+
+Note that disabling a breakpoint does not delete it, it just temporarily
+marks the breakpoint as inactive. Disabled breakpoints will not cause
+execution to halt, their associated condition expressions will not be
+evaluated, and their associated commands will not be executed.
+
+Examples:
+
+``bpdisable 3``
+ Disable the breakpoint with 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:
+**bpenable [<bpnum>]**
+
+Enable breakpoints. If **<bpnum>** is specified, the breakpoint it
+refers to will be enabled. If **<bpnum>** is not specified, all
+breakpoints will be enabled.
+
+Examples:
+
+``bpenable 3``
+ Enable the breakpoint with 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`
+**bplist [<CPU>]**
+
+List current breakpoints, along with their indices and any associated
+conditions or actions. If no **<CPU>** is specified, breakpoints for
+all CPUs in the system will be listed; if a **<CPU>** is specified, only
+breakpoints for that CPU will be listed. The **<CPU>** can be specified
+by tag or by debugger CPU number (see :ref:`debugger-devicespec` for
+details).
+
+Examples:
+
+``bplist``
+ List all breakpoints.
+``bplist .``
+ List all breakpoints for the visible CPU.
+``bplist maincpu``
+ List all breakpoints for the CPU with the absolute tag path
+ ``:maincpu``.
+Back to :ref:`debugger-breakpoint-list`