From 40a30af10f05f6567f717e4d1004f7bae01b85a2 Mon Sep 17 00:00:00 2001 From: Vas Crabb Date: Mon, 18 Oct 2021 08:22:21 +1100 Subject: Still more user experience improvements: Changed the default mapping for UI select to not trigger on Alt+Enter fullscreen toggle. (Fullscreen toggle still doesn't work in menus - actually fixing that is complicated.) frontend: Made the about box wrap text properly, made the title and backtrack menu item always visible, and added a footer with the VCS revision. frontend: Don't highlight the favourites and info toolbar buttons if there's no selection (can happen if filters produce no results). Also made the info viewer appear even if no info is available - it's less confusing to see an empty menu than wonder why clicking the button does nothing. debugger: Added a register points view to the GUI debuggers, to go with the breakpoints and watchpoints views. debugger: Extended [brw]p(clear|(en|dis)able) commands to accept multiple arguments to perform the same action on multiple (break|watch|register)points at once. Also made rplist accept a CPU for showing a single CPU's register points ([bw]plist already support this). docs: Updated registerpoints debugger commands page, and updated other pages for latest extensions to syntax. --- docs/source/debugger/breakpoint.rst | 18 +-- docs/source/debugger/execution.rst | 4 +- docs/source/debugger/general.rst | 10 +- docs/source/debugger/memory.rst | 4 +- docs/source/debugger/registerpoints.rst | 212 ++++++++++++++++++-------------- docs/source/debugger/watchpoint.rst | 18 +-- 6 files changed, 146 insertions(+), 120 deletions(-) (limited to 'docs/source') diff --git a/docs/source/debugger/breakpoint.rst b/docs/source/debugger/breakpoint.rst index 1e61157c854..5dbf6c4effe 100644 --- a/docs/source/debugger/breakpoint.rst +++ b/docs/source/debugger/breakpoint.rst @@ -75,10 +75,10 @@ Back to :ref:`debugger-breakpoint-list` bpclear ------- -**bpclear []** +**bpclear [[,…]]** -Clear breakpoints. If **** is specified, the breakpoint it -refers to will be cleared. If **** is not specified, all +Clear breakpoints. If **** is specified, the breakpoints +referred to will be cleared. If **** is not specified, all breakpoints will be cleared. Examples: @@ -96,10 +96,10 @@ Back to :ref:`debugger-breakpoint-list` bpdisable --------- -**bpdisable []** +**bpdisable [[,…]]** -Disable breakpoints. If **** is specified, the breakpoint it -refers to will be disabled. If **** is not specified, all +Disable breakpoints. If **** is specified, the breakpoints +referred to will be disabled. If **** is not specified, all breakpoints will be disabled. Note that disabling a breakpoint does not delete it, it just temporarily @@ -122,10 +122,10 @@ Back to :ref:`debugger-breakpoint-list` bpenable -------- -**bpenable []** +**bpenable [[,…]]** -Enable breakpoints. If **** is specified, the breakpoint it -refers to will be enabled. If **** is not specified, all +Enable breakpoints. If **** is specified, the breakpoint +referred to will be enabled. If **** is not specified, all breakpoints will be enabled. Examples: diff --git a/docs/source/debugger/execution.rst b/docs/source/debugger/execution.rst index cfcfede1c87..8a99f52f85a 100644 --- a/docs/source/debugger/execution.rst +++ b/docs/source/debugger/execution.rst @@ -285,7 +285,7 @@ Back to :ref:`debugger-execution-list` ignore ------ -**ignore [[,[,...]]]** +**ignore [[,[,…]]]** Ignores the specified CPUs in the debugger. CPUs can be specified by tag or debugger CPU number (see :ref:`debugger-devicespec` for details). @@ -316,7 +316,7 @@ Back to :ref:`debugger-execution-list` observe ------- -**observe [[,[,...]]]** +**observe [[,[,…]]]** Allow interaction with the specified CPUs in the debugger. CPUs can be specified by tag or debugger CPU number (see :ref:`debugger-devicespec` diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst index 9d7d206117e..4edc1b413fb 100644 --- a/docs/source/debugger/general.rst +++ b/docs/source/debugger/general.rst @@ -159,7 +159,7 @@ Back to :ref:`debugger-general-list` print ----- -**print [,...]** +**print [,…]** The **print** command prints the results of one or more expressions to the debugger console as hexadecimal numbers. @@ -180,7 +180,7 @@ Back to :ref:`debugger-general-list` printf ------ -**printf [,[,...]]** +**printf [,[,…]]** Prints a C-style formatted message to the debugger console. Only a very limited subset of format specifiers and escape sequences are @@ -223,7 +223,7 @@ Back to :ref:`debugger-general-list` logerror -------- -**logerror [,[,...]]** +**logerror [,[,…]]** Prints a C-style formatted message to the error log. See :ref:`debugger-command-printf` for details about the limited set of @@ -246,7 +246,7 @@ Back to :ref:`debugger-general-list` tracelog -------- -**tracelog [,[,...]]** +**tracelog [,[,…]]** Prints a C-style formatted message to the currently open trace file (see :ref:`debugger-command-trace` for more information). If no trace file @@ -272,7 +272,7 @@ Back to :ref:`debugger-general-list` tracesym -------- -**tracesym [,...]** +**tracesym [,…]** Prints the specified symbols to the currently open trace file (see :ref:`debugger-command-trace` for more information). If no trace file diff --git a/docs/source/debugger/memory.rst b/docs/source/debugger/memory.rst index da3645a6d1e..9988d24551e 100644 --- a/docs/source/debugger/memory.rst +++ b/docs/source/debugger/memory.rst @@ -64,7 +64,7 @@ Back to :ref:`debugger-memory-list` find ---- -**f[ind][{d|i|o}]
[:],[,[,...]]** +**f[ind][{d|i|o}]
[:],[,[,…]]** Search through memory for the specified sequence of data. The **
** is the address to begin searching from, optionally @@ -113,7 +113,7 @@ Back to :ref:`debugger-memory-list` fill ---- -**fill[{d|i|o}]
[:],[,[,...]]** +**fill[{d|i|o}]
[:],[,[,…]]** Overwrite a block of memory with copies of the supplied data sequence. The **
** specifies the address to begin writing at, optionally diff --git a/docs/source/debugger/registerpoints.rst b/docs/source/debugger/registerpoints.rst index 355a31c29eb..e228208e600 100644 --- a/docs/source/debugger/registerpoints.rst +++ b/docs/source/debugger/registerpoints.rst @@ -1,120 +1,146 @@ .. _debugger-registerpoints-list: -Registerpoints Debugger Commands +Registerpoint Debugger Commands ================================ +:ref:`debugger-command-rpset` + sets a registerpoint to trigger on a condition +:ref:`debugger-command-rpclear` + clears registerpoints +:ref:`debugger-command-rpdisable` + disables a registerpoint +:ref:`debugger-command-rpenable` + enables registerpoints +:ref:`debugger-command-rplist` + lists registerpoints -You can also type **help ** for further details on each command in the MAME Debugger interface. -| :ref:`debugger-command-rpset` -- sets a registerpoint to trigger on -| :ref:`debugger-command-rpclear` -- clears a given registerpoint or all if no specified -| :ref:`debugger-command-rpdisable` -- disabled a given registerpoint or all if no specified -| :ref:`debugger-command-rpenable` -- enables a given registerpoint or all if no specified -| :ref:`debugger-command-rplist` -- lists all the registerpoints +.. _debugger-command-rpset: +rpset +----- +**rp[set] [,]** - .. _debugger-command-rpset: +Sets a new registerpoint which will be triggered when the expression +supplied as the **** evaluates to true (non-zero). Note that +the condition may need to be surrounded with braces ``{ }`` to prevent +it from being interpreted as an assignment. The optional **** +parameter provides a command to be executed whenever the registerpoint +is triggered. 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 ``rpset`` command itself. + +Each registerpoint that is set is assigned a numeric index which can be +used to refer to it in other registerpoint commands. Registerpoint +indices are unique throughout a session. + +Examples: + +``rp {PC==150}`` + Set a registerpoint that will halt execution whenever the **PC** + register equals 150. +``temp0=0; rp {PC==150},{temp0++; g}`` + Set a registerpoint that will increment the variable **temp0** + whenever the **PC** register equals 150. +``rp {temp0==5}`` + Set a registerpoint that will halt execution whenever the **temp0** + variable equals 5. + +Back to :ref:`debugger-registerpoints-list` -rpset ------ -| **rp[set] {}[,]]** -| -| Sets a new registerpoint which will be triggered when is met. The condition must be specified between curly braces to prevent the condition from being evaluated as an assignment. -| The optional 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: +.. _debugger-command-rpclear: rpclear ------- -| **rpclear []** -| -| The rpclear command clears a registerpoint. If 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: +**rpclear [,[,…]]** + +Clears registerpoints. If **** is specified, the registerpoints +referred to will be cleared. If **** is not specified, all +registerpoints will be cleared. + +Examples: + +``rpclear 3`` + Clear the registerpoint with index 3. +``rpclear`` + Clear all registerpoints. + +Back to :ref:`debugger-registerpoints-list` + + +.. _debugger-command-rpdisable: rpdisable --------- -| **rpdisable []** -| -| The rpdisable command disables a registerpoint. If 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: +**rpdisable [[,…]]** + +Disables registerpoints. If **** is specified, the +registerpoints referred to will be disabled. If **** is not +specified, all registerpoints will be disabled. + +Note that disabling a registerpoint does not delete it, it just +temporarily marks the registerpoint as inactive. Disabled +registerpoints will not cause execution to halt, their condition +expressions will not be evaluated, and their associated commands will +not be executed. + +Examples: + +``rpdisable 3`` + Disable the registerpoint with index 3. +``rpdisable`` + Disable all registerpoints. + +Back to :ref:`debugger-registerpoints-list` + + +.. _debugger-command-rpenable: rpenable -------- -| **rpenable []** -| -| The rpenable command enables a registerpoint. If 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: +**rpenable [[,…]]** + +Enables registerpoints. If **** is specified, the registerpoints +referred to will be enabled. If **** is not specified, all +registerpoints will be enabled. + +Examples: + +``rpenable 3`` + Enable the registerpoint with 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` +**rplist []** + +List current registerpoints, along with their indices and conditions, +and any associated actions actions. If no **** is specified, +registerpoints for all CPUs in the system will be listed; if a **** +is specified, only registerpoints for that CPU will be listed. The +**** can be specified by tag or by debugger CPU number (see +:ref:`debugger-devicespec` for details). + +Examples: + +``rplist`` + List all registerpoints. +``rplist .`` + List all registerpoints for the visible CPU. +``rplist maincpu`` + List all registerpoints for the CPU with the absolute tag path + ``:maincpu``. + +Back to :ref:`debugger-registerpoints-list` diff --git a/docs/source/debugger/watchpoint.rst b/docs/source/debugger/watchpoint.rst index d9270f13699..c34006f8a5f 100644 --- a/docs/source/debugger/watchpoint.rst +++ b/docs/source/debugger/watchpoint.rst @@ -83,10 +83,10 @@ Back to :ref:`debugger-watchpoints-list` wpclear ------- -**wpclear []** +**wpclear [[,…]]** -Clear watchpoints. If **** is specified, the watchpoint it -refers to will be cleared. If **** is not specified, all +Clear watchpoints. If **** is specified, the watchpoints +referred to will be cleared. If **** is not specified, all watchpoints will be cleared. Examples: @@ -104,10 +104,10 @@ Back to :ref:`debugger-watchpoints-list` wpdisable --------- -**wpdisable []** +**wpdisable [[,…]]** -Disable watchpoints. If **** is specified, the watchpoint it -refers to will be disabled. If **** is not specified, all +Disable watchpoints. If **** is specified, the watchpoints +referred to will be disabled. If **** is not specified, all watchpoints will be disabled. Note that disabling a watchpoint does not delete it, it just temporarily @@ -130,10 +130,10 @@ Back to :ref:`debugger-watchpoints-list` wpenable -------- -**wpenable []** +**wpenable [[,…]]** -Enable watchpoints. If **** is specified, the watchpoint it -refers to will be enabled. If **** is not specified, all +Enable watchpoints. If **** is specified, the watchpoints +referred to will be enabled. If **** is not specified, all watchpoints will be enabled. Examples: -- cgit v1.2.3-70-g09d2