diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/gdb/Set-Watchpoints.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gdb/Set-Watchpoints.html')
| -rw-r--r-- | share/doc/gdb/Set-Watchpoints.html | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/share/doc/gdb/Set-Watchpoints.html b/share/doc/gdb/Set-Watchpoints.html new file mode 100644 index 0000000..585d032 --- /dev/null +++ b/share/doc/gdb/Set-Watchpoints.html @@ -0,0 +1,315 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs +Free Documentation", with the Front-Cover Texts being "A GNU Manual," +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Debugging with GDB: Set Watchpoints</title> + +<meta name="description" content="Debugging with GDB: Set Watchpoints"> +<meta name="keywords" content="Debugging with GDB: Set Watchpoints"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints"> +<link href="Set-Catchpoints.html#Set-Catchpoints" rel="next" title="Set Catchpoints"> +<link href="Set-Breaks.html#Set-Breaks" rel="previous" title="Set Breaks"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Set-Watchpoints"></a> +<div class="header"> +<p> +Next: <a href="Set-Catchpoints.html#Set-Catchpoints" accesskey="n" rel="next">Set Catchpoints</a>, Previous: <a href="Set-Breaks.html#Set-Breaks" accesskey="p" rel="previous">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Setting-Watchpoints"></a> +<h4 class="subsection">5.1.2 Setting Watchpoints</h4> + +<a name="index-setting-watchpoints"></a> +<p>You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. (This is sometimes called a <em>data breakpoint</em>.) +The expression may be as simple as the value of a single variable, or +as complex as many variables combined by operators. Examples include: +</p> +<ul> +<li> A reference to the value of a single variable. + +</li><li> An address cast to an appropriate data type. For example, +‘<samp>*(int *)0x12345678</samp>’ will watch a 4-byte region at the specified +address (assuming an <code>int</code> occupies 4 bytes). + +</li><li> An arbitrarily complex expression, such as ‘<samp>a*b + c/d</samp>’. The +expression can use any operators valid in the program’s native +language (see <a href="Languages.html#Languages">Languages</a>). +</li></ul> + +<p>You can set a watchpoint on an expression even if the expression can +not be evaluated yet. For instance, you can set a watchpoint on +‘<samp>*global_ptr</samp>’ before ‘<samp>global_ptr</samp>’ is initialized. +<small>GDB</small> will stop when your program sets ‘<samp>global_ptr</samp>’ and +the expression produces a valid value. If the expression becomes +valid in some other way than changing a variable (e.g. if the memory +pointed to by ‘<samp>*global_ptr</samp>’ becomes readable as the result of a +<code>malloc</code> call), <small>GDB</small> may not stop until the next time +the expression changes. +</p> +<a name="index-software-watchpoints"></a> +<a name="index-hardware-watchpoints"></a> +<p>Depending on your system, watchpoints may be implemented in software or +hardware. <small>GDB</small> does software watchpointing by single-stepping your +program and testing the variable’s value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) +</p> +<p>On some systems, such as most PowerPC or x86-based targets, +<small>GDB</small> includes support for hardware watchpoints, which do not +slow down the running of your program. +</p> +<dl compact="compact"> +<dd><a name="index-watch"></a> +</dd> +<dt><code>watch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span> <span class="roman">[</span>task <var>task-id</var><span class="roman">]</span></code></dt> +<dd><p>Set a watchpoint for an expression. <small>GDB</small> will break when the +expression <var>expr</var> is written into by the program and its value +changes. The simplest (and the most popular) use of this command is +to watch the value of a single variable: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) watch foo +</pre></div> + +<p>If the command includes a <code><span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span></code> +argument, <small>GDB</small> breaks only when the thread identified by +<var>thread-id</var> changes the value of <var>expr</var>. If any other threads +change the value of <var>expr</var>, <small>GDB</small> will not break. Note +that watchpoints restricted to a single thread in this way only work +with Hardware Watchpoints. +</p> +<p>Similarly, if the <code>task</code> argument is given, then the watchpoint +will be specific to the indicated Ada task (see <a href="Ada-Tasks.html#Ada-Tasks">Ada Tasks</a>). +</p> +<p>Ordinarily a watchpoint respects the scope of variables in <var>expr</var> +(see below). The <code>-location</code> argument tells <small>GDB</small> to +instead watch the memory referred to by <var>expr</var>. In this case, +<small>GDB</small> will evaluate <var>expr</var>, take the address of the result, +and watch the memory at that address. The type of the result is used +to determine the size of the watched memory. If the expression’s +result does not have an address, then <small>GDB</small> will print an +error. +</p> +<p>The <code><span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code> argument allows creation +of masked watchpoints, if the current architecture supports this +feature (e.g., PowerPC Embedded architecture, see <a href="PowerPC-Embedded.html#PowerPC-Embedded">PowerPC Embedded</a>.) A <em>masked watchpoint</em> specifies a mask in addition +to an address to watch. The mask specifies that some bits of an address +(the bits which are reset in the mask) should be ignored when matching +the address accessed by the inferior against the watchpoint address. +Thus, a masked watchpoint watches many addresses simultaneously—those +addresses whose unmasked bits are identical to the unmasked bits in the +watchpoint address. The <code>mask</code> argument implies <code>-location</code>. +Examples: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) watch foo mask 0xffff00ff +(gdb) watch *0xdeadbeef mask 0xffffff00 +</pre></div> + +<a name="index-rwatch"></a> +</dd> +<dt><code>rwatch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code></dt> +<dd><p>Set a watchpoint that will break when the value of <var>expr</var> is read +by the program. +</p> +<a name="index-awatch"></a> +</dd> +<dt><code>awatch <span class="roman">[</span>-l<span class="roman">|</span>-location<span class="roman">]</span> <var>expr</var> <span class="roman">[</span>thread <var>thread-id</var><span class="roman">]</span> <span class="roman">[</span>mask <var>maskvalue</var><span class="roman">]</span></code></dt> +<dd><p>Set a watchpoint that will break when <var>expr</var> is either read from +or written into by the program. +</p> +<a name="index-info-watchpoints-_005blist_2026_005d"></a> +</dd> +<dt><code>info watchpoints <span class="roman">[</span><var>list</var>…<span class="roman">]</span></code></dt> +<dd><p>This command prints a list of watchpoints, using the same format as +<code>info break</code> (see <a href="Set-Breaks.html#Set-Breaks">Set Breaks</a>). +</p></dd> +</dl> + +<p>If you watch for a change in a numerically entered address you need to +dereference it, as the address itself is just a constant number which will +never change. <small>GDB</small> refuses to create a watchpoint that watches +a never-changing value: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) watch 0x600850 +Cannot watch constant value 0x600850. +(gdb) watch *(int *) 0x600850 +Watchpoint 1: *(int *) 6293584 +</pre></div> + +<p><small>GDB</small> sets a <em>hardware watchpoint</em> if possible. Hardware +watchpoints execute very quickly, and the debugger reports a change in +value at the exact instruction where the change occurs. If <small>GDB</small> +cannot set a hardware watchpoint, it sets a software watchpoint, which +executes more slowly and reports the change in value at the next +<em>statement</em>, not the instruction, after the change occurs. +</p> +<a name="index-use-only-software-watchpoints"></a> +<p>You can force <small>GDB</small> to use only software watchpoints with the +<kbd>set can-use-hw-watchpoints 0</kbd> command. With this variable set to +zero, <small>GDB</small> will never try to use hardware watchpoints, even if +the underlying system supports them. (Note that hardware-assisted +watchpoints that were set <em>before</em> setting +<code>can-use-hw-watchpoints</code> to zero will still use the hardware +mechanism of watching expression values.) +</p> +<dl compact="compact"> +<dt><code>set can-use-hw-watchpoints</code></dt> +<dd><a name="index-set-can_002duse_002dhw_002dwatchpoints"></a> +<p>Set whether or not to use hardware watchpoints. +</p> +</dd> +<dt><code>show can-use-hw-watchpoints</code></dt> +<dd><a name="index-show-can_002duse_002dhw_002dwatchpoints"></a> +<p>Show the current mode of using hardware watchpoints. +</p></dd> +</dl> + +<p>For remote targets, you can restrict the number of hardware +watchpoints <small>GDB</small> will use, see <a href="Remote-Configuration.html#set-remote-hardware_002dbreakpoint_002dlimit">set remote hardware-breakpoint-limit</a>. +</p> +<p>When you issue the <code>watch</code> command, <small>GDB</small> reports +</p> +<div class="smallexample"> +<pre class="smallexample">Hardware watchpoint <var>num</var>: <var>expr</var> +</pre></div> + +<p>if it was able to set a hardware watchpoint. +</p> +<p>Currently, the <code>awatch</code> and <code>rwatch</code> commands can only set +hardware watchpoints, because accesses to data that don’t change the +value of the watched expression cannot be detected without examining +every instruction as it is being executed, and <small>GDB</small> does not do +that currently. If <small>GDB</small> finds that it is unable to set a +hardware breakpoint with the <code>awatch</code> or <code>rwatch</code> command, it +will print a message like this: +</p> +<div class="smallexample"> +<pre class="smallexample">Expression cannot be implemented with read/access watchpoint. +</pre></div> + +<p>Sometimes, <small>GDB</small> cannot set a hardware watchpoint because the +data type of the watched expression is wider than what a hardware +watchpoint on the target machine can handle. For example, some systems +can only watch regions that are up to 4 bytes wide; on such systems you +cannot set hardware watchpoints for an expression that yields a +double-precision floating-point number (which is typically 8 bytes +wide). As a work-around, it might be possible to break the large region +into a series of smaller ones and watch them with separate watchpoints. +</p> +<p>If you set too many hardware watchpoints, <small>GDB</small> might be unable +to insert all of them when you resume the execution of your program. +Since the precise number of active watchpoints is unknown until such +time as the program is about to be resumed, <small>GDB</small> might not be +able to warn you about this when you set the watchpoints, and the +warning will be printed only when the program is resumed: +</p> +<div class="smallexample"> +<pre class="smallexample">Hardware watchpoint <var>num</var>: Could not insert watchpoint +</pre></div> + +<p>If this happens, delete or disable some of the watchpoints. +</p> +<p>Watching complex expressions that reference many variables can also +exhaust the resources available for hardware-assisted watchpoints. +That’s because <small>GDB</small> needs to watch every variable in the +expression with separately allocated resources. +</p> +<p>If you call a function interactively using <code>print</code> or <code>call</code>, +any watchpoints you have set will be inactive until <small>GDB</small> reaches another +kind of breakpoint or the call completes. +</p> +<p><small>GDB</small> automatically deletes watchpoints that watch local +(automatic) variables, or expressions that involve such variables, when +they go out of scope, that is, when the execution leaves the block in +which these variables were defined. In particular, when the program +being debugged terminates, <em>all</em> local variables go out of scope, +and so only watchpoints that watch global variables remain set. If you +rerun the program, you will need to set all such watchpoints again. One +way of doing that would be to set a code breakpoint at the entry to the +<code>main</code> function and when it breaks, set all the watchpoints. +</p> +<a name="index-watchpoints-and-threads"></a> +<a name="index-threads-and-watchpoints"></a> +<p>In multi-threaded programs, watchpoints will detect changes to the +watched expression from every thread. +</p> +<blockquote> +<p><em>Warning:</em> In multi-threaded programs, software watchpoints +have only limited usefulness. If <small>GDB</small> creates a software +watchpoint, it can only watch the value of an expression <em>in a +single thread</em>. If you are confident that the expression can only +change due to the current thread’s activity (and if you are also +confident that no other thread can become current), then you can use +software watchpoints as usual. However, <small>GDB</small> may not notice +when a non-current thread’s activity changes the expression. (Hardware +watchpoints, in contrast, watch an expression in all threads.) +</p></blockquote> + +<p>See <a href="Remote-Configuration.html#set-remote-hardware_002dwatchpoint_002dlimit">set remote hardware-watchpoint-limit</a>. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Set-Catchpoints.html#Set-Catchpoints" accesskey="n" rel="next">Set Catchpoints</a>, Previous: <a href="Set-Breaks.html#Set-Breaks" accesskey="p" rel="previous">Set Breaks</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |