====== MAME Debugger Watchpoint Commands ======


===== wpset =====

**Syntax:** ''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,writeval==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.


===== wpclear =====

**Syntax:** ''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.


===== wpdisable =====

**Syntax:** ''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.


===== wpenable =====

**Syntax:** ''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.


===== wplist =====

**Syntax:** ''wplist''

The wplist command lists all the current watchpoints, along with their index and any conditions or actions attached to them.


===== hotspot =====

**Syntax:** ''hotspot [<cpunum>,[<depth>[,<hits>]]]''

The //hotspot// command attempts to help locate hotspots in the code where speedup opportunities might be present. ''<cpunum>'', which defaults to the currently active CPU, specified which processor's memory to track. ''<depth>'', which defaults to ''64'', controls the depth of the search buffer. The search buffer tracks the last ''<depth>'' memory reads from unique PCs. The ''<hits>'' parameter, which defaults to ''250'', specifies the minimum number of hits to report.

The basic theory of operation is like this: each memory read is trapped by the debugger and logged in the search buffer according to the address which was read and the ''PC'' that executed the opcode. If the search buffer already contains a matching entry, that entry's count is incremented and the entry is moved to the top of the list. If the search buffer does not contain a matching entry, the entry from the bottom of the list is removed, and a new entry is created at the top with an initial count of ''1''. Entries which fall off the bottom are examined and if their count is larger than ''<hits>'', they are reported to the debugger console.

**Examples:**

  * ''hotspot 0,10'' -- Looks for hotspots on CPU 0 using a search buffer of 16 entries, reporting any entries which end up with 250 or more hits.
  * ''hotspot 1,40,#1000'' -- Looks for hotspots on CPU 1 using a search buffer of 64 entries, reporting any entries which end up with 1000 or more hits.