diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 8 | ||||
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 384 |
2 files changed, 384 insertions, 8 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 7e0d576..05f7f72 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,11 @@ +2001-03-21 Eli Zaretskii <eliz@is.elta.co.il> + + * gdbint.texinfo (Algorithms): New section "Watchpoints" and new + subsection "x86 Watchpoints". + (Target Architecture Definition): Document the macros + I386_USE_GENERIC_WATCHPOINTS and TARGET_HAS_HARDWARE_WATCHPOINTS. + (Native Debugging): Document I386_USE_GENERIC_WATCHPOINTS. + 2001-03-20 Andrew Cagney <ac131313@redhat.com> * gdbint.texinfo (Target Architecture Definition): Update diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index bf05fec..e374c3e 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -1,4 +1,4 @@ -\input texinfo +\input texinfo @c -*- texinfo -*- @setfilename gdbint.info @include gdb-cfg.texi @ifinfo @@ -292,7 +292,11 @@ for something to happen. Since they depend on hardware resources, hardware breakpoints may be limited in number; when the user asks for more, @value{GDBN} will -start trying to set software breakpoints. +start trying to set software breakpoints. (On some architectures, +notably the 32-bit x86 platforms, @value{GDBN} cannot alsways know +whether there's enough hardware resources to insert all the hardware +breakpoints and watchpoints. On those platforms, @value{GDBN} prints +an error message only when the program being debugged is continued.) @cindex software breakpoints Software breakpoints require @value{GDBN} to do somewhat more work. @@ -351,6 +355,357 @@ is target specific, you will need to define it in the appropriate @file{tm-@var{target}.h} file. Look in @file{tm-sun4os4.h} and @file{sparc-tdep.c} for examples of how to do this. +@section Watchpoints +@cindex watchpoints + +Watchpoints are a special kind of breakpoints (@pxref{Algorithms, +breakpoints}) which break when data is accessed rather than when some +instruction is executed. When you have data which changes without +your knowing what code does that, watchpoints are the silver bullet to +hunt down and kill such bugs. + +@cindex hardware watchpoints +@cindex software watchpoints +Watchpoints can be either hardware-assisted or not; the latter type is +known as ``software watchpoints.'' @value{GDBN} always uses +hardware-assisted watchpoints if they are available, and falls back on +software watchpoints otherwise. Typical situations where @value{GDBN} +will use software watchpoints are: + +@itemize @bullet +@item +The watched memory region is too large for the underlying hardware +watchpoint support. For example, each x86 debug register can watch up +to 4 bytes of memory, so trying to watch data structures whose size is +more than 16 bytes will cause @value{GDBN} to use software +watchpoints. + +@item +The value of the expression to be watched depends on data held in +registers (as opposed to memory). + +@item +Too many different watchpoints requested. (On some architectures, +this situation is impossible to detect until the debugged program is +resumed.) Note that x86 debug registers are used both for hardware +breakpoints and for watchpoints, so setting too many hardware +breakpoints might cause watchpoint insertion to fail. + +@item +No hardware-assisted watchpoints provided by the target +implementation. +@end itemize + +Software watchpoints are very slow, since @value{GDBN} needs to +single-step the program being debugged and test the value of the +watched expression(s) after each instruction. The rest of this +section is mostly irrelevant for software watchpoints. + +@value{GDBN} uses several macros and primitives to support hardware +watchpoints: + +@table @code +@findex TARGET_HAS_HARDWARE_WATCHPOINTS +@item TARGET_HAS_HARDWARE_WATCHPOINTS +If defined, the target supports hardware watchpoints. + +@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT +@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other}) +Return the number of hardware watchpoints of type @var{type} that are +possible to be set. The value is positive if @var{count} watchpoints +of this type can be set, zero if setting watchpoints of this type is +not supported, and negative if @var{count} is more than the maximum +number of watchpoints of type @var{type} that can be set. @var{other} +is non-zero if other types of watchpoints are currently enabled (there +are architectures which cannot set watchpoints of different types at +the same time). + +@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT +@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len}) +Return non-zero if hardware watchpoints can be used to watch a region +whose address is @var{addr} and whose length in bytes is @var{len}. + +@findex TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT +@item TARGET_REGION_SIZE_OK_FOR_HW_WATCHPOINT (@var{size}) +Return non-zero if hardware watchpoints can be used to watch a region +whose size is @var{size}. @value{GDBN} only uses this macro as a +fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not +defined. + +@findex TARGET_DISABLE_HW_WATCHPOINTS +@item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid}) +Disables watchpoints in the process identified by @var{pid}. This is +used, e.g., on HP-UX which provides operations to disable and enable +the page-level memory protection that implements hardware watchpoints +on that platform. + +@findex TARGET_ENABLE_HW_WATCHPOINTS +@item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid}) +Enables watchpoints in the process identified by @var{pid}. This is +used, e.g., on HP-UX which provides operations to disable and enable +the page-level memory protection that implements hardware watchpoints +on that platform. + +@findex TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT +@item TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (@var{pid},@var{start},@var{len}) +Some addresses may not be profitable to use hardware to watch, or may +be difficult to understand when the addressed object is out of scope, +and hence should not be watched with hardware watchpoints. On some +targets, this may have severe performance penalties, such that we +might as well use regular watchpoints, and save (possibly precious) +hardware watchpoints for other locations. + +@findex target_insert_watchpoint +@findex target_remove_watchpoint +@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type}) +@itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type}) +Insert or remove a hardware watchpoint starting at @var{addr}, for +@var{len} bytes. @var{type} is the watchpoint type, one of the +possible values of the enumerated data type @code{target_hw_bp_type}, +defined by @file{breakpoint.h} as follows: + +@example + enum target_hw_bp_type + @{ + hw_write = 0, /* Common (write) HW watchpoint */ + hw_read = 1, /* Read HW watchpoint */ + hw_access = 2, /* Access (read or write) HW watchpoint */ + hw_execute = 3 /* Execute HW breakpoint */ + @}; +@end example + +@noindent +These two macros should return 0 for success, non-zero for failure. + +@cindex insert or remove hardware breakpoint +@findex target_remove_hw_breakpoint +@findex target_insert_hw_breakpoint +@item target_remove_hw_breakpoint (@var{addr}, @var{shadow}) +@itemx target_insert_hw_breakpoint (@var{addr}, @var{shadow}) +Insert or remove a hardware-assisted breakpoint at address @var{addr}. +Returns zero for success, non-zero for failure. @var{shadow} is the +real contents of the byte where the breakpoint has been inserted; it +is generally not valid when hardware breakpoints are used, but since +no other code touches these values, the implementations of the above +two macros can use them for their internal purposes. + +@findex target_stopped_data_address +@item target_stopped_data_address () +If the inferior has some watchpoint that triggered, return the address +associated with that watchpoint. Otherwise, return zero. + +@findex DECR_PC_AFTER_HW_BREAK +@item DECR_PC_AFTER_HW_BREAK +If defined, @value{GDBN} decrements the program counter by the value +of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This +overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint +that breaks is a hardware-assisted breakpoint. + +@findex HAVE_STEPPABLE_WATCHPOINT +@item HAVE_STEPPABLE_WATCHPOINT +If defined to a non-zero value, it is not necessary to disable a +watchpoint to step over it. + +@findex HAVE_NONSTEPPABLE_WATCHPOINT +@item HAVE_NONSTEPPABLE_WATCHPOINT +If defined to a non-zero value, @value{GDBN} should disable a +watchpoint to step the inferior over it. + +@findex HAVE_CONTINUABLE_WATCHPOINT +@item HAVE_CONTINUABLE_WATCHPOINT +If defined to a non-zero value, it is possible to continue the +inferior after a watchpoint has been hit. + +@findex CANNOT_STEP_HW_WATCHPOINTS +@item CANNOT_STEP_HW_WATCHPOINTS +If this is defined to a non-zero value, @value{GDBN} will remove all +watchpoints before stepping the inferior. + +@findex STOPPED_BY_WATCHPOINT +@item STOPPED_BY_WATCHPOINT (@var{wait_status}) +Return non-zero if stopped by a watchpoint. @var{wait_status} is of +the type @code{struct target_waitstatus}, defined by @file{target.h}. +@end table + +@subsection x86 Watchpoints +@cindex x86 debug registers +@cindex watchpoints, on x86 + +The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug +registers designed to facilitate debugging. @value{GDBN} provides a +generic library of functions that x86-based ports can use to implement +support for watchpoints and hardware-assisted breakpoints. This +subsection documents the x86 watchpoint facilities in @value{GDBN}. + +To use the generic x86 watchpoint support, a port should do the +following: + +@itemize @bullet +@findex I386_USE_GENERIC_WATCHPOINTS +@item +Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the +target-dependent headers. + +@item +Include the @file{config/i386/nm-i386.h} header file @emph{after} +defining @code{I386_USE_GENERIC_WATCHPOINTS}. + +@item +Add @file{i386-nat.o} to the value of the Make variable +@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}) or +@code{TDEPFILES} (@pxref{Target Architecture Definition, TDEPFILES}). + +@item +Provide implementations for the @code{I386_DR_LOW_*} macros described +below. Typically, each macro should call a target-specific function +which does the real work. +@end itemize + +The x86 watchpoint support works by maintaining mirror images of the +debug registers. Values are copied between the mirror images and the +real debug registers via a set of macros which each target needs to +provide: + +@table @code +@findex I386_DR_LOW_SET_CONTROL +@item I386_DR_LOW_SET_CONTROL (@var{val}) +Set the Debug Control (DR7) register to the value @var{val}. + +@findex I386_DR_LOW_SET_ADDR +@item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr}) +Put the address @var{addr} into the debug register number @var{idx}. + +@findex I386_DR_LOW_RESET_ADDR +@item I386_DR_LOW_RESET_ADDR (@var{idx}) +Reset (i.e.@: zero out) the address stored in the debug register +number @var{idx}. + +@findex I386_DR_LOW_GET_STATUS +@item I386_DR_LOW_GET_STATUS +Return the value of the Debug Status (DR6) register. This value is +used immediately after it is returned by +@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status +register values. +@end table + +For each one of the 4 debug registers (whose indices are from 0 to 3) +that store addresses, a reference count is maintained by @value{GDBN}, +to allow sharing of debug registers by several watchpoints. This +allows users to define several watchpoints that watch the same +expression, but with different conditions and/or commands, without +wasting debug registers which are in short supply. @value{GDBN} +maintains the reference counts internally, targets don't have to do +anything to use this feature. + +The x86 debug registers can each watch a region that is 1, 2, or 4 +bytes long. The ia32 architecture requires that each watched region +be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte +region on 4-byte boundary. However, the x86 watchpoint support in +@value{GDBN} can watch unaligned regions and regions larger than 4 +bytes (up to 16 bytes) by allocating several debug registers to watch +a single region. This allocation of several registers per a watched +region is also done automatically without target code intervention. + +The generic x86 watchpoint support provides the following API for the +@value{GDBN}'s application code: + +@table @code +@findex i386_region_ok_for_watchpoint +@item i386_region_ok_for_watchpoint (@var{addr}, @var{len}) +The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call +this function. It counts the number of debug registers required to +watch a given region, and returns a non-zero value if that number is +less than 4, the number of debug registers available to x86 +processors. + +@findex i386_stopped_data_address +@item i386_stopped_data_address (void) +The macros @code{STOPPED_BY_WATCHPOINT} and +@code{target_stopped_data_address} are set to call this function. The +argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This +function examines the breakpoint condition bits in the DR6 Debug +Status register, as returned by the @code{I386_DR_LOW_GET_STATUS} +macro, and returns the address associated with the first bit that is +set in DR6. + +@findex i386_insert_watchpoint +@findex i386_remove_watchpoint +@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type}) +@itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type}) +Insert or remove a watchpoint. The macros +@code{target_insert_watchpoint} and @code{target_remove_watchpoint} +are set to call these functions. @code{i386_insert_watchpoint} first +looks for a debug register which is already set to watch the same +region for the same access types; if found, it just increments the +reference count of that debug register, thus implementing debug +register sharing between watchpoints. If no such register is found, +the function looks for a vacant debug register, sets its mirrorred +value to @var{addr}, sets the mirrorred value of DR7 Debug Control +register as appropriate for the @var{len} and @var{type} parameters, +and then passes the new values of the debug register and DR7 to the +inferior by calling @code{I386_DR_LOW_SET_ADDR} and +@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is +required to cover the given region, the above process is repeated for +each debug register. + +@code{i386_remove_watchpoint} does the opposite: it resets the address +in the mirrorred value of the debug register and its read/write and +length bits in the mirrorred value of DR7, then passes these new +values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and +@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several +watchpoints, each time a @code{i386_remove_watchpoint} is called, it +decrements the reference count, and only calls +@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when +the count goes to zero. + +@findex i386_insert_hw_breakpoint +@findex i386_remove_hw_breakpoint +@item i386_insert_hw_breakpoint (@var{addr}, @var{shadow} +@itemx i386_remove_hw_breakpoint (@var{addr}, @var{shadow}) +These functions insert and remove hardware-assisted breakpoints. The +macros @code{target_insert_hw_breakpoint} and +@code{target_remove_hw_breakpoint} are set to call these functions. +These functions work like @code{i386_insert_watchpoint} and +@code{i386_remove_watchpoint}, respectively, except that they set up +the debug registers to watch instruction execution, and each +hardware-assisted breakpoint always requires exactly one debug +register. + +@findex i386_stopped_by_hwbp +@item i386_stopped_by_hwbp (void) +This function returns non-zero if the inferior has some watchpoint or +hardware breakpoint that triggered. It works like +@code{i386_stopped_data_address}, except that it doesn't return the +address whose watchpoint triggered. + +@findex i386_cleanup_dregs +@item i386_cleanup_dregs (void) +This function clears all the reference counts, addresses, and control +bits in the mirror images of the debug registers. It doesn't affect +the actual debug registers in the inferior process. +@end table + +@noindent +@strong{Notes:} +@enumerate 1 +@item +x86 processors support setting watchpoints on I/O reads or writes. +However, since no target supports this (as of March 2001), and since +@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O +watchpoints, this feature is not yet available to @value{GDBN} running +on x86. + +@item +x86 processors can enable watchpoints locally, for the current task +only, or globally, for all the tasks. For each debug register, +there's a bit in the DR7 Debug Control register that determines +whether the associated address is watched locally or globally. The +current implementation of x86 watchpoint support in @value{GDBN} +always sets watchpoints to be locally enabled, since global +watchpoints might interfere with the underlying OS and are probably +unavailable in many platforms. +@end enumerate + @node User Interface @chapter User Interface @@ -375,7 +730,7 @@ to the @code{set_thread_cmd_list}. To add commands in general, use @code{add_cmd}. @code{add_com} adds to the main command list, and should be used for those commands. The usual place to add commands is in the @code{_initialize_@var{xyz}} routines at -the ends of most source files. +the ends of most source files. @cindex deprecating commands @findex deprecate_cmd @@ -1103,10 +1458,10 @@ The ordering of bytes in the host. This must be defined to be either @code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. @item INT_MAX -@item INT_MIN -@item LONG_MAX -@item UINT_MAX -@item ULONG_MAX +@itemx INT_MIN +@itemx LONG_MAX +@itemx UINT_MAX +@itemx ULONG_MAX Values for host-side constants. @item ISATTY @@ -1223,7 +1578,7 @@ Define this to indicate that @code{siginterrupt} is not available. Define if this is not in a system header file (typically, @file{unistd.h}). @item SEEK_CUR -@item SEEK_SET +@itemx SEEK_SET Define these to appropriate value for the system @code{lseek}, if not already defined. @@ -1991,6 +2346,10 @@ conditional should be eliminated (FIXME) and replaced by feature-specific macros. It was introduced in a haste and we are repenting at leisure. +@item I386_USE_GENERIC_WATCHPOINTS +An x86-based target can define this to use the generic x86 watchpoint +support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. + @item SYMBOLS_CAN_START_WITH_DOLLAR @findex SYMBOLS_CAN_START_WITH_DOLLAR Some systems have routines whose names start with @samp{$}. Giving this @@ -2467,6 +2826,11 @@ frame pointer in use at the code address @var{pc}. If virtual frame pointers are not used, a default definition simply returns @code{FP_REGNUM}, with an offset of zero. +@item TARGET_HAS_HARDWARE_WATCHPOINTS +If non-zero, the target has support for hardware-assisted +watchpoints. @xref{Algorithms, watchpoints}, for more details and +other related macros. + @item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type}) @findex USE_STRUCT_CONVENTION If defined, this must be an expression that is nonzero if a value of the @@ -2796,6 +3160,10 @@ assuming that we have just stopped at a longjmp breakpoint. It takes a @code{CORE_ADDR *} as argument, and stores the target PC value through this pointer. It examines the current state of the machine as needed. +@item I386_USE_GENERIC_WATCHPOINTS +An x86-based machine can define this to use the generic x86 watchpoint +support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}. + @item KERNEL_U_ADDR @findex KERNEL_U_ADDR Define this to the address of the @code{u} structure (the ``user |