Tools > Create Watchpoint
Defines or modifies an unconditional data watchpoint, or a conditional data watchpoint.
NOTE: TotalView supports only modify watchpoints. That is, TotalView triggers the watchpoint only if your program modifies the memory location. If the same value is written back to the location, the watchpoint does not trigger.
When a watchpoint triggers, the thread’s PC points to the instruction after the instruction that caused the watchpoint to trigger. In some cases, where a memory store instruction is the last instruction in the source line, the PC will point to the source line after the source line that contains the triggering instruction.
If TotalView displays a question asking if you really want to set a watchpoint on non-global memory, it is telling you that the memory is contained within memory that can change for reasons other than the program changing a variable’s value. For example, you may be setting a watchpoint on stack memory. When the routine on the stack is popped, it will probably be overwritten by a new stack frame, and this change will have nothing to do with your program changing a value.
This message isn’t telling you not to do this. Instead, TotalView is making you aware that change could occur for other reasons.
Platform Restrictions
The number of watchpoints, their size, and alignment restrictions differ from platform to platform. (This is because TotalView relies on the operating system and its hardware to implement data watchpoints.)
NOTE: Watchpoints are not available on Macintosh computers running OS X, and IBM PowerPC computers running Linux Power.
The following list describes constraints that are unique to each platform:
Computer | Constraints |
|---|---|
IBM AIX | You can create one watchpoint on AIX 4.3.3.0-2 (AIX 4.3R) or later systems running 64-bit chips. These are Power3 and Power4 systems. (AIX 4.3R is available as APAR IY06844.) A watchpoint cannot be longer than 8 bytes, and you must align it within an 8-byte boundary. |
Linux x86 (32-bit) | You can create up to four watchpoints and each must be 1, 2, or 4 bytes in length, and a memory address must be aligned for the byte length. That is, you must align a 4-byte watchpoint on a 4-byte address boundary, and you must align 2-byte watchpoint on a 2-byte boundary, and so on. |
Linux x-86-64 (AMD and Intel) | You can create up to four watchpoints and each must be 1, 2, 4, or 8 bytes in length, and a memory address must be aligned for the byte length. For example, you must align a 4-byte watchpoint on a 4-byte address boundary. |
Linux ARM64 | TotalView supports watchpoints for ARMv8 processors using the hardware’s debug watchpoint registers. You can typically create up to four watchpoints (although some processors may have different limits, allowing from 2 to 16 watchpoints, or none at all). Each must be 1, 2, 4, or 8 bytes in length, and the watched memory address must be aligned for the byte length. Watchpoints cannot overlap. |
Solaris SPARC | TotalView supports watchpoints on Solaris 2.6 or later operating systems. These operating systems let you create hundreds of watchpoints, and there are no alignment or size constraints. However, watchpoints can’t overlap. |
Typically, a debugging session does not use many watchpoints. In most cases, only one memory location at a time is being monitored. So, restrictions on the number of values you can watch are seldom an issue.
Watchpoint Commands
 |
Watchpoint type
Lets you indicate if the watchpoint is conditional or unconditional.
Unconditional
Tells TotalView to trigger the watchpoint whenever the memory location’s value is modified. You can tell TotalView that it should also stop the thread’s process or control group when the thread is stopped. Unconditional watchpoints are discussed below.
Conditional
Tells TotalView that, after a memory location is modified, it should evaluate the condition. Conditional watchpoints are discussed below.
Address
The first (or lowest) memory address to watch. Depending on the platform, this address may need to be aligned to a multiple of the Byte Size field. If you edit the address of an existing watchpoint, TotalView alters the watchpoint so it will watch this new memory location and reassigns the watchpoint’s action point ID.
Byte Size
The number of bytes that TotalView should watch. Normally, this amount is the size of the variable. However, some architectures limit the amount of memory that can be watched. In other cases, you may want TotalView to monitor a few locations in an array. For information on architectural limitations, see “Platform Restrictions”.
Enable watchpoint
If selected, TotalView makes this watchpoint active. (If a watchpoint is inactive, TotalView ignores changes to the watched memory locations.)
Plant in share group
If selected, TotalView creates a watchpoint for each thread in the share group. Some architectures place limits on the size and number of watchpoints. See “Platform Restrictions” for more information.
Unconditional Watchpoints
The only control unique to unconditional watchpoints is When Hit, Stop, which tells TotalView what should be stopped when a watched location changes. While TotalView always stops the executing Thread (the thread of interest), it also stops either the thread of interest's control Group or all threads in the thread of interest's Process.
Conditional Watchpoints
Using the following controls, you can create a watchpoint that triggers only when the condition you specify occurs.
 |
Type for $newval/$oldval
If you will be placing the value stored at the memory location into a variable (using $newval and $oldval), you must define the variable’s data by using a scalar type, such as int, integer, float, real, or char. You cannot use aggregate types such as arrays and structures.
If the size of the watched location matches the size of the data type entered here, TotalView interprets the $oldval and $newval information as the variable’s type. If you are watching an entire array, the watched location can be larger than the size of this type.
Expression
Enter a code fragment. The expression is compiled into interpreted code that is executed each time the watchpoint triggers. These points can be used to implement countdown and conditional watchpoints. For additional information, see Setting Action Points of the TotalView User Guide.
C++, C, or Fortran
Indicates the programming language in which you wrote the expression.
The Classic TotalView User Guide contains additional information on watchpoints.
NOTE: You can create compiled conditional watchpoints when you running programs on an IBM AIX computer. When watchpoints are compiled, they are evaluated by the process rather than having to be evaluated in TotalView main, where all evaluations are single-threaded and must be sent from separately executing processes.
