summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/debugger/watchpoint.rst
blob: 0f4bd12902f16d216c15d9c804cab18a8f70e2b2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
.. _debugger-watchpoints-list:

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

:ref:`debugger-command-wpset`
    sets memory access watchpoints
:ref:`debugger-command-wpclear`
    clears watchpoints
:ref:`debugger-command-wpdisable`
    disables watchpoints
:ref:`debugger-command-wpenable`
    enables enables watchpoints
:ref:`debugger-command-wplist`
    lists watchpoints

Watchpoints halt execution and activate the debugger when a CPU accesses
a location in a particular memory range.


.. _debugger-command-wpset:

wpset
-----

**wp[{d|i|o}][set] <address>[:<space>],<length>,<type>[,<condition>[,<action>]]**

Sets a new watchpoint starting at the specified **<address>** and
extending for **<length>**.  The range of the watchpoint is
**<address>** through **<address>+<length>-1**, inclusive.  The
**<address>** may optionally be followed by a CPU and/or address space
(see :ref:`debugger-devicespec` for details).  If an address space is
not specified, the command suffix sets the address space: ``wpset``
defaults to the first address space exposed by the CPU, ``wpdset``
defaults to the space with index 1 (data), ``wpiset`` defaults to the
space with index 2 (I/O), and ``wposet`` defaults to the space with
index 3 (opcodes).  The **<type>** parameter specifies the access types
to trap on – it can be one of three values: ``r`` for read accesses,
``w`` for write accesses, or ``rw`` for both read and write accesses.

The optional **<condition>** parameter lets you specify an expression
that will be evaluated each time the watchpoint is triggered.  If the
result of the expression is true (non-zero), the watchpoint will halt
execution; otherwise, execution will continue with no notification.  The
optional **<action>** parameter provides a command to be executed
whenever the watchpoint is triggered 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 ``wpset`` command itself.

Each watchpoint that is set is assigned a numeric index which can be
used to refer to it in other watchpoint commands.  Watchpoint indices
are unique throughout a session.

To make **<condition>** expressions more useful, two variables are
available: for all watchpoints, the variable **wpaddr** is set to the
access address that triggered the watchpoint; for write watchpoints, the
variable **wpdata** is set to the data being written.

Examples:

``wp 1234,6,rw``
    Set a watchpoint for the visible CPU that will halt execution
    whenever a read or write to the first address space occurs in the
    address range 1234-1239, inclusive.
``wp 23456:data,a,w,wpdata == 1``
    Set a watchpoint for the visible CPU that will halt execution
    whenever a write to the ``data`` space occurs in the address range
    23456-2345f and the data written is equal to 1.
``wp 3456:maincpu,20,r,1,{ printf "Read @ %08X\n",wpaddr ; g }``
    Set a watchpoint for the CPU with the absolute tag path ``:maincpu``
    that will halt execution whenever a read from the first address
    space occurs in the address range 3456-3475.  When this happens,
    print **Read @ <wpaddr>** to the debugger console and resume
    execution.
``temp0 = 0 ; wp 45678,1,w,wpdata==f0,{ temp0++ ; g }``
    Set a watchpoint for the visible CPU that will halt execution
    whenever a write to the first address space occurs at address 45678
    where the value being written is equal to f0.  When this happens,
    increment the variable **temp0** and resume execution.

Back to :ref:`debugger-watchpoints-list`


.. _debugger-command-wpclear:

wpclear
-------

**wpclear [<wpnum>[,…]]**

Clear watchpoints.  If **<wpnum>** is specified, the watchpoints
referred to will be cleared.  If **<wpnum>** is not specified, all
watchpoints will be cleared.

Examples:

``wpclear 3``
    Clear the watchpoint with index 3.
``wpclear``
    Clear all watchpoints.

Back to :ref:`debugger-watchpoints-list`


.. _debugger-command-wpdisable:

wpdisable
---------

**wpdisable [<wpnum>[,…]]**

Disable watchpoints.  If **<wpnum>** is specified, the watchpoints
referred to will be disabled.  If **<wpnum>** is not specified, all
watchpoints will be disabled.

Note that disabling a watchpoint does not delete it, it just temporarily
marks the watchpoint as inactive.  Disabled watchpoints will not cause
execution to halt, their associated condition expressions will not be
evaluated, and their associated commands will not be executed.

Examples:

``wpdisable 3``
    Disable the watchpoint with index 3.
``wpdisable``
    Disable all watchpoints.

Back to :ref:`debugger-watchpoints-list`


.. _debugger-command-wpenable:

wpenable
--------

**wpenable [<wpnum>[,…]]**

Enable watchpoints.  If **<wpnum>** is specified, the watchpoints
referred to will be enabled.  If **<wpnum>** is not specified, all
watchpoints will be enabled.

Examples:

``wpenable 3``
    Enable the watchpoint with index 3.
``wpenable``
    Enable all watchpoints.

Back to :ref:`debugger-watchpoints-list`


.. _debugger-command-wplist:

wplist
------

**wplist [<CPU>]**

List current watchpoints, along with their indices and any associated
conditions or actions.  If no **<CPU>** is specified, watchpoints for
all CPUs in the system will be listed; if a **<CPU>** is specified, only
watchpoints 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:

``wplist``
    List all watchpoints.
``wplist .``
    List all watchpoints for the visible CPU.
``wplist maincpu``
    List all watchpoints for the CPU with the absolute tag path
    ``:maincpu``.

Back to :ref:`debugger-watchpoints-list`