Subversion Repositories openrisc_2011-10-31

\input texinfo   @c -*- texinfo -*-

@setfilename gdbint.info

@include gdb-cfg.texi

@settitle @value{GDBN} Internals

@setchapternewpage off

@dircategory Software development

@direntry

* Gdb-Internals: (gdbint).      The GNU debugger's internals.

@end direntry

@copying

Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999,

2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010

Free Software Foundation, Inc.

Contributed by Cygnus Solutions.  Written by John Gilmore.

Second Edition by Stan Shebs.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with no

Invariant Sections, with no Front-Cover Texts, and with no Back-Cover

Texts.  A copy of the license is included in the section entitled ``GNU

Free Documentation License''.

@end copying

@ifnottex

This file documents the internals of the GNU debugger @value{GDBN}.

@insertcopying

@end ifnottex

@syncodeindex fn cp

@syncodeindex vr cp

@titlepage

@title @value{GDBN} Internals

@subtitle{A guide to the internals of the GNU debugger}

@author John Gilmore

@author Cygnus Solutions

@author Second Edition:

@author Stan Shebs

@author Cygnus Solutions

@page

@tex

\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$

\xdef\manvers{\$Revision$}  % For use in headers, footers too

{\parskip=0pt

\hfill Cygnus Solutions\par

\hfill \manvers\par

\hfill \TeX{}info \texinfoversion\par

}

@end tex

@vskip 0pt plus 1filll

@insertcopying

@end titlepage

@contents

@node Top

@c Perhaps this should be the title of the document (but only for info,

@c not for TeX).  Existing GNU manuals seem inconsistent on this point.

@top Scope of this Document

This document documents the internals of the GNU debugger, @value{GDBN}.  It

includes description of @value{GDBN}'s key algorithms and operations, as well

as the mechanisms that adapt @value{GDBN} to specific hosts and targets.

@menu

* Summary::

* Overall Structure::

* Algorithms::

* User Interface::

* libgdb::

* Values::

* Stack Frames::

* Symbol Handling::

* Language Support::

* Host Definition::

* Target Architecture Definition::

* Target Descriptions::

* Target Vector Definition::

* Native Debugging::

* Support Libraries::

* Coding::

* Porting GDB::

* Versions and Branches::

* Start of New Year Procedure::

* Releasing GDB::

* Testsuite::

* Hints::

* GDB Observers::  @value{GDBN} Currently available observers

* GNU Free Documentation License::  The license for this documentation

* Index::

@end menu

@node Summary

@chapter Summary

@menu

* Requirements::

* Contributors::

@end menu

@node Requirements

@section Requirements

@cindex requirements for @value{GDBN}

Before diving into the internals, you should understand the formal

requirements and other expectations for @value{GDBN}.  Although some

of these may seem obvious, there have been proposals for @value{GDBN}

that have run counter to these requirements.

First of all, @value{GDBN} is a debugger.  It's not designed to be a

front panel for embedded systems.  It's not a text editor.  It's not a

shell.  It's not a programming environment.

@value{GDBN} is an interactive tool.  Although a batch mode is

available, @value{GDBN}'s primary role is to interact with a human

programmer.

@value{GDBN} should be responsive to the user.  A programmer hot on

the trail of a nasty bug, and operating under a looming deadline, is

going to be very impatient of everything, including the response time

to debugger commands.

@value{GDBN} should be relatively permissive, such as for expressions.

While the compiler should be picky (or have the option to be made

picky), since source code lives for a long time usually, the

programmer doing debugging shouldn't be spending time figuring out to

mollify the debugger.

@value{GDBN} will be called upon to deal with really large programs.

Executable sizes of 50 to 100 megabytes occur regularly, and we've

heard reports of programs approaching 1 gigabyte in size.

@value{GDBN} should be able to run everywhere.  No other debugger is

available for even half as many configurations as @value{GDBN}

supports.

@node Contributors

@section Contributors

The first edition of this document was written by John Gilmore of

Cygnus Solutions. The current second edition was written by Stan Shebs

of Cygnus Solutions, who continues to update the manual.

Over the years, many others have made additions and changes to this

document. This section attempts to record the significant contributors

to that effort. One of the virtues of free software is that everyone

is free to contribute to it; with regret, we cannot actually

acknowledge everyone here.

@quotation

@emph{Plea:} This section has only been added relatively recently (four

years after publication of the second edition). Additions to this

section are particularly welcome.  If you or your friends (or enemies,

to be evenhanded) have been unfairly omitted from this list, we would

like to add your names!

@end quotation

A document such as this relies on being kept up to date by numerous

small updates by contributing engineers as they make changes to the

code base. The file @file{ChangeLog} in the @value{GDBN} distribution

approximates a blow-by-blow account. The most prolific contributors to

this important, but low profile task are Andrew Cagney (responsible

for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim

Blandy and Eli Zaretskii.

Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting

watchpoints.

Jeremy Bennett updated the sections on initializing a new architecture

and register representation, and added the section on Frame Interpretation.

@node Overall Structure

@chapter Overall Structure

@value{GDBN} consists of three major subsystems: user interface,

symbol handling (the @dfn{symbol side}), and target system handling (the

@dfn{target side}).

The user interface consists of several actual interfaces, plus

supporting code.

The symbol side consists of object file readers, debugging info

interpreters, symbol table management, source language expression

parsing, type and value printing.

The target side consists of execution control, stack frame analysis, and

physical target manipulation.

The target side/symbol side division is not formal, and there are a

number of exceptions.  For instance, core file support involves symbolic

elements (the basic core file reader is in BFD) and target elements (it

supplies the contents of memory and the values of registers).  Instead,

this division is useful for understanding how the minor subsystems

should fit together.

@section The Symbol Side

The symbolic side of @value{GDBN} can be thought of as ``everything

you can do in @value{GDBN} without having a live program running''.

For instance, you can look at the types of variables, and evaluate

many kinds of expressions.

@section The Target Side

The target side of @value{GDBN} is the ``bits and bytes manipulator''.

Although it may make reference to symbolic info here and there, most

of the target side will run with only a stripped executable

available---or even no executable at all, in remote debugging cases.

Operations such as disassembly, stack frame crawls, and register

display, are able to work with no symbolic info at all.  In some cases,

such as disassembly, @value{GDBN} will use symbolic info to present addresses

relative to symbols rather than as raw numbers, but it will work either

way.

@section Configurations

@cindex host

@cindex target

@dfn{Host} refers to attributes of the system where @value{GDBN} runs.

@dfn{Target} refers to the system where the program being debugged

executes.  In most cases they are the same machine, in which case a

third type of @dfn{Native} attributes come into play.

Defines and include files needed to build on the host are host

support.  Examples are tty support, system defined types, host byte

order, host float format.  These are all calculated by @code{autoconf}

when the debugger is built.

Defines and information needed to handle the target format are target

dependent.  Examples are the stack frame format, instruction set,

breakpoint instruction, registers, and how to set up and tear down the stack

to call a function.

Information that is only needed when the host and target are the same,

is native dependent.  One example is Unix child process support; if the

host and target are not the same, calling @code{fork} to start the target

process is a bad idea.  The various macros needed for finding the

registers in the @code{upage}, running @code{ptrace}, and such are all

in the native-dependent files.

Another example of native-dependent code is support for features that

are really part of the target environment, but which require

@code{#include} files that are only available on the host system.  Core

file handling and @code{setjmp} handling are two common cases.

When you want to make @value{GDBN} work as the traditional native debugger

on a system, you will need to supply both target and native information.

@section Source Tree Structure

@cindex @value{GDBN} source tree structure

The @value{GDBN} source directory has a mostly flat structure---there

are only a few subdirectories.  A file's name usually gives a hint as

to what it does; for example, @file{stabsread.c} reads stabs,

@file{dwarf2read.c} reads @sc{DWARF 2}, etc.

Files that are related to some common task have names that share

common substrings.  For example, @file{*-thread.c} files deal with

debugging threads on various platforms; @file{*read.c} files deal with

reading various kinds of symbol and object files; @file{inf*.c} files

deal with direct control of the @dfn{inferior program} (@value{GDBN}

parlance for the program being debugged).

There are several dozens of files in the @file{*-tdep.c} family.

@samp{tdep} stands for @dfn{target-dependent code}---each of these

files implements debug support for a specific target architecture

(sparc, mips, etc).  Usually, only one of these will be used in a

specific @value{GDBN} configuration (sometimes two, closely related).

Similarly, there are many @file{*-nat.c} files, each one for native

debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for

native debugging of Sparc machines running the Linux kernel).

The few subdirectories of the source tree are:

@table @file

@item cli

Code that implements @dfn{CLI}, the @value{GDBN} Command-Line

Interpreter.  @xref{User Interface, Command Interpreter}.

@item gdbserver

Code for the @value{GDBN} remote server.

@item gdbtk

Code for Insight, the @value{GDBN} TK-based GUI front-end.

@item mi

The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.

@item signals

Target signal translation code.

@item tui

Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User

Interface.  @xref{User Interface, TUI}.

@end table

@node Algorithms

@chapter Algorithms

@cindex algorithms

@value{GDBN} uses a number of debugging-specific algorithms.  They are

often not very complicated, but get lost in the thicket of special

cases and real-world issues.  This chapter describes the basic

algorithms and mentions some of the specific target definitions that

they use.

@section Prologue Analysis

@cindex prologue analysis

@cindex call frame information

@cindex CFI (call frame information)

To produce a backtrace and allow the user to manipulate older frames'

variables and arguments, @value{GDBN} needs to find the base addresses

of older frames, and discover where those frames' registers have been

saved.  Since a frame's ``callee-saves'' registers get saved by

younger frames if and when they're reused, a frame's registers may be

scattered unpredictably across younger frames.  This means that

changing the value of a register-allocated variable in an older frame

may actually entail writing to a save slot in some younger frame.

Modern versions of GCC emit Dwarf call frame information (``CFI''),

which describes how to find frame base addresses and saved registers.

But CFI is not always available, so as a fallback @value{GDBN} uses a

technique called @dfn{prologue analysis} to find frame sizes and saved

registers.  A prologue analyzer disassembles the function's machine

code starting from its entry point, and looks for instructions that

allocate frame space, save the stack pointer in a frame pointer

register, save registers, and so on.  Obviously, this can't be done

accurately in general, but it's tractable to do well enough to be very

helpful.  Prologue analysis predates the GNU toolchain's support for

CFI; at one time, prologue analysis was the only mechanism

@value{GDBN} used for stack unwinding at all, when the function

calling conventions didn't specify a fixed frame layout.

In the olden days, function prologues were generated by hand-written,

target-specific code in GCC, and treated as opaque and untouchable by

optimizers.  Looking at this code, it was usually straightforward to

write a prologue analyzer for @value{GDBN} that would accurately

understand all the prologues GCC would generate.  However, over time

GCC became more aggressive about instruction scheduling, and began to

understand more about the semantics of the prologue instructions

themselves; in response, @value{GDBN}'s analyzers became more complex

and fragile.  Keeping the prologue analyzers working as GCC (and the

instruction sets themselves) evolved became a substantial task.

@cindex @file{prologue-value.c}

@cindex abstract interpretation of function prologues

@cindex pseudo-evaluation of function prologues

To try to address this problem, the code in @file{prologue-value.h}

and @file{prologue-value.c} provides a general framework for writing

prologue analyzers that are simpler and more robust than ad-hoc

analyzers.  When we analyze a prologue using the prologue-value

framework, we're really doing ``abstract interpretation'' or

``pseudo-evaluation'': running the function's code in simulation, but

using conservative approximations of the values registers and memory

would hold when the code actually runs.  For example, if our function

starts with the instruction:

@example

addi r1, 42     # add 42 to r1

@end example

@noindent

we don't know exactly what value will be in @code{r1} after executing

this instruction, but we do know it'll be 42 greater than its original

value.

If we then see an instruction like:

@example

addi r1, 22     # add 22 to r1

@end example

@noindent

we still don't know what @code{r1's} value is, but again, we can say

it is now 64 greater than its original value.

If the next instruction were:

@example

mov r2, r1      # set r2 to r1's value

@end example

@noindent

then we can say that @code{r2's} value is now the original value of

@code{r1} plus 64.

It's common for prologues to save registers on the stack, so we'll

need to track the values of stack frame slots, as well as the

registers.  So after an instruction like this:

@example

mov (fp+4), r2

@end example

@noindent

then we'd know that the stack slot four bytes above the frame pointer

holds the original value of @code{r1} plus 64.

And so on.

Of course, this can only go so far before it gets unreasonable.  If we

wanted to be able to say anything about the value of @code{r1} after

the instruction:

@example

xor r1, r3      # exclusive-or r1 and r3, place result in r1

@end example

@noindent

then things would get pretty complex.  But remember, we're just doing

a conservative approximation; if exclusive-or instructions aren't

relevant to prologues, we can just say @code{r1}'s value is now

``unknown''.  We can ignore things that are too complex, if that loss of

information is acceptable for our application.

So when we say ``conservative approximation'' here, what we mean is an

approximation that is either accurate, or marked ``unknown'', but

never inaccurate.

Using this framework, a prologue analyzer is simply an interpreter for

machine code, but one that uses conservative approximations for the

contents of registers and memory instead of actual values.  Starting

from the function's entry point, you simulate instructions up to the

current PC, or an instruction that you don't know how to simulate.

Now you can examine the state of the registers and stack slots you've

kept track of.

@itemize @bullet

@item

To see how large your stack frame is, just check the value of the

stack pointer register; if it's the original value of the SP

minus a constant, then that constant is the stack frame's size.

If the SP's value has been marked as ``unknown'', then that means

the prologue has done something too complex for us to track, and

we don't know the frame size.

@item

To see where we've saved the previous frame's registers, we just

search the values we've tracked --- stack slots, usually, but

registers, too, if you want --- for something equal to the register's

original value.  If the calling conventions suggest a standard place

to save a given register, then we can check there first, but really,

anything that will get us back the original value will probably work.

@end itemize

This does take some work.  But prologue analyzers aren't

quick-and-simple pattern patching to recognize a few fixed prologue

forms any more; they're big, hairy functions.  Along with inferior

function calls, prologue analysis accounts for a substantial portion

of the time needed to stabilize a @value{GDBN} port.  So it's

worthwhile to look for an approach that will be easier to understand

and maintain.  In the approach described above:

@itemize @bullet

@item

It's easier to see that the analyzer is correct: you just see

whether the analyzer properly (albeit conservatively) simulates

the effect of each instruction.

@item

It's easier to extend the analyzer: you can add support for new

instructions, and know that you haven't broken anything that

wasn't already broken before.

@item

It's orthogonal: to gather new information, you don't need to

complicate the code for each instruction.  As long as your domain

of conservative values is already detailed enough to tell you

what you need, then all the existing instruction simulations are

already gathering the right data for you.

@end itemize

The file @file{prologue-value.h} contains detailed comments explaining

the framework and how to use it.

@section Breakpoint Handling

@cindex breakpoints

In general, a breakpoint is a user-designated location in the program

where the user wants to regain control if program execution ever reaches

that location.

There are two main ways to implement breakpoints; either as ``hardware''

breakpoints or as ``software'' breakpoints.

@cindex hardware breakpoints

@cindex program counter

Hardware breakpoints are sometimes available as a builtin debugging

features with some chips.  Typically these work by having dedicated

register into which the breakpoint address may be stored.  If the PC

(shorthand for @dfn{program counter})

ever matches a value in a breakpoint registers, the CPU raises an

exception and reports it to @value{GDBN}.

Another possibility is when an emulator is in use; many emulators

include circuitry that watches the address lines coming out from the

processor, and force it to stop if the address matches a breakpoint's

address.

A third possibility is that the target already has the ability to do

breakpoints somehow; for instance, a ROM monitor may do its own

software breakpoints.  So although these are not literally ``hardware

breakpoints'', from @value{GDBN}'s point of view they work the same;

@value{GDBN} need not do anything more than set the breakpoint and wait

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.  (On some architectures,

notably the 32-bit x86 platforms, @value{GDBN} cannot always 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.

The basic theory is that @value{GDBN} will replace a program

instruction with a trap, illegal divide, or some other instruction

that will cause an exception, and then when it's encountered,

@value{GDBN} will take the exception and stop the program.  When the

user says to continue, @value{GDBN} will restore the original

instruction, single-step, re-insert the trap, and continue on.

Since it literally overwrites the program being tested, the program area

must be writable, so this technique won't work on programs in ROM.  It

can also distort the behavior of programs that examine themselves,

although such a situation would be highly unusual.

Also, the software breakpoint instruction should be the smallest size of

instruction, so it doesn't overwrite an instruction that might be a jump

target, and cause disaster when the program jumps into the middle of the

breakpoint instruction.  (Strictly speaking, the breakpoint must be no

larger than the smallest interval between instructions that may be jump

targets; perhaps there is an architecture where only even-numbered

instructions may jumped to.)  Note that it's possible for an instruction

set not to have any instructions usable for a software breakpoint,

although in practice only the ARC has failed to define such an

instruction.

Basic breakpoint object handling is in @file{breakpoint.c}.  However,

much of the interesting breakpoint action is in @file{infrun.c}.

@table @code

@cindex insert or remove software breakpoint

@findex target_remove_breakpoint

@findex target_insert_breakpoint

@item target_remove_breakpoint (@var{bp_tgt})

@itemx target_insert_breakpoint (@var{bp_tgt})

Insert or remove a software breakpoint at address

@code{@var{bp_tgt}->placed_address}.  Returns zero for success,

non-zero for failure.  On input, @var{bp_tgt} contains the address of the

breakpoint, and is otherwise initialized to zero.  The fields of the

@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated

to contain other information about the breakpoint on output.  The field

@code{placed_address} may be updated if the breakpoint was placed at a

related address; the field @code{shadow_contents} contains the real

contents of the bytes where the breakpoint has been inserted,

if reading memory would return the breakpoint instead of the

underlying memory; the field @code{shadow_len} is the length of

memory cached in @code{shadow_contents}, if any; and the field

@code{placed_size} is optionally set and used by the target, if

it could differ from @code{shadow_len}.

For example, the remote target @samp{Z0} packet does not require

shadowing memory, so @code{shadow_len} is left at zero.  However,

the length reported by @code{gdbarch_breakpoint_from_pc} is cached in

@code{placed_size}, so that a matching @samp{z0} packet can be

used to remove the breakpoint.

@cindex insert or remove hardware breakpoint

@findex target_remove_hw_breakpoint

@findex target_insert_hw_breakpoint

@item target_remove_hw_breakpoint (@var{bp_tgt})

@itemx target_insert_hw_breakpoint (@var{bp_tgt})

Insert or remove a hardware-assisted breakpoint at address

@code{@var{bp_tgt}->placed_address}.  Returns zero for success,

non-zero for failure.  See @code{target_insert_breakpoint} for

a description of the @code{struct bp_target_info} pointed to by

@var{bp_tgt}; the @code{shadow_contents} and

@code{shadow_len} members are not used for hardware breakpoints,

but @code{placed_size} may be.

@end table

@section Single Stepping

@section Signal Handling

@section Thread Handling

@section Inferior Function Calls

@section Longjmp Support

@cindex @code{longjmp} debugging

@value{GDBN} has support for figuring out that the target is doing a

@code{longjmp} and for stopping at the target of the jump, if we are

stepping.  This is done with a few specialized internal breakpoints,

which are visible in the output of the @samp{maint info breakpoint}

command.

@findex gdbarch_get_longjmp_target

To make this work, you need to define a function called

@code{gdbarch_get_longjmp_target}, which will examine the

@code{jmp_buf} structure and extract the @code{longjmp} target address.

Since @code{jmp_buf} is target specific and typically defined in a

target header not available to @value{GDBN}, you will need to

determine the offset of the PC manually and return that; many targets

define a @code{jb_pc_offset} field in the tdep structure to save the

value once calculated.

@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.

When the inferior stops, @value{GDBN} tries to establish, among other

possible reasons, whether it stopped due to a watchpoint being hit.

It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint

was hit.  If not, all watchpoint checking is skipped.

Then @value{GDBN} calls @code{target_stopped_data_address} exactly

once.  This method returns the address of the watchpoint which

triggered, if the target can determine it.  If the triggered address

is available, @value{GDBN} compares the address returned by this

method with each watched memory address in each active watchpoint.

For data-read and data-access watchpoints, @value{GDBN} announces

every watchpoint that watches the triggered address as being hit.

For this reason, data-read and data-access watchpoints

@emph{require} that the triggered address be available; if not, read

and access watchpoints will never be considered hit.  For data-write

watchpoints, if the triggered address is available, @value{GDBN}

considers only those watchpoints which match that address;

otherwise, @value{GDBN} considers all data-write watchpoints.  For

each data-write watchpoint that @value{GDBN} considers, it evaluates

the expression whose value is being watched, and tests whether the

watched value has changed.  Watchpoints whose watched values have

changed are announced as hit.

@c FIXME move these to the main lists of target/native defns

@value{GDBN} uses several macros and primitives to support hardware

watchpoints:

@table @code

@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}.

@cindex insert or remove hardware watchpoint

@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:

@smallexample

 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 smallexample

@noindent

These two macros should return 0 for success, non-zero for failure.

@findex target_stopped_data_address

@item target_stopped_data_address (@var{addr_p})

If the inferior has some watchpoint that triggered, place the address

associated with the watchpoint at the location pointed to by

@var{addr_p} and return non-zero.  Otherwise, return zero.  This

is required for data-read and data-access watchpoints.  It is

not required for data-write watchpoints, but @value{GDBN} uses

it to improve handling of those also.

@value{GDBN} will only call this method once per watchpoint stop,

immediately after calling @code{STOPPED_BY_WATCHPOINT}.  If the

target's watchpoint indication is sticky, i.e., stays set after

resuming, this method should clear it.  For instance, the x86 debug

control register has sticky triggered flags.

@findex target_watchpoint_addr_within_range

@item target_watchpoint_addr_within_range (@var{target}, @var{addr}, @var{start}, @var{length})

Check whether @var{addr} (as returned by @code{target_stopped_data_address})

lies within the hardware-defined watchpoint region described by

@var{start} and @var{length}.  This only needs to be provided if the

granularity of a watchpoint is greater than one byte, i.e., if the

watchpoint can also trigger on nearby addresses outside of the watched

region.

@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.  Like @code{gdbarch_have_nonsteppable_watchpoint},

this is usually set when watchpoints trigger at the instruction

which will perform an interesting read or write.  It should be

set if there is a temporary disable bit which allows the processor

to step over the interesting instruction without raising the

watchpoint exception again.

@findex gdbarch_have_nonsteppable_watchpoint

@item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch})

If it returns a non-zero value, @value{GDBN} should disable a

watchpoint to step the inferior over it.  This is usually set when

watchpoints trigger at the instruction which will perform an

interesting read or write.

@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.  This is usually set

when watchpoints trigger at the instruction following an interesting

read or write.

@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}.

Normally, this macro is defined to invoke the function pointed to by

the @code{to_stopped_by_watchpoint} member of the structure (of the

type @code{target_ops}, defined on @file{target.h}) that describes the

target-specific operations; @code{to_stopped_by_watchpoint} ignores

the @var{wait_status} argument.

@value{GDBN} does not require the non-zero value returned by

@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot

determine for sure whether the inferior stopped due to a watchpoint,

it could return non-zero ``just in case''.

@end table

@subsection Watchpoints and Threads

@cindex watchpoints, with threads

@value{GDBN} only supports process-wide watchpoints, which trigger

in all threads.  @value{GDBN} uses the thread ID to make watchpoints

act as if they were thread-specific, but it cannot set hardware

watchpoints that only trigger in a specific thread.  Therefore, even

if the target supports threads, per-thread debug registers, and

watchpoints which only affect a single thread, it should set the

per-thread debug registers for all threads to the same value.  On

@sc{gnu}/Linux native targets, this is accomplished by using

@code{ALL_LWPS} in @code{target_insert_watchpoint} and

@code{target_remove_watchpoint} and by using

@code{linux_set_new_thread} to register a handler for newly created

threads.

@value{GDBN}'s @sc{gnu}/Linux support only reports a single event

at a time, although multiple events can trigger simultaneously for

multi-threaded programs.  When multiple events occur, @file{linux-nat.c}

queues subsequent events and returns them the next time the program

is resumed.  This means that @code{STOPPED_BY_WATCHPOINT} and

@code{target_stopped_data_address} only need to consult the current

thread's state---the thread indicated by @code{inferior_ptid}.  If

two threads have hit watchpoints simultaneously, those routines

will be called a second time for the second thread.

@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}.

(At present, the library functions read and write debug registers directly, and are

thus only available for native configurations.)

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}).

@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 (@var{addr_p})

The target function

@code{target_stopped_data_address} is set to call this function.

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_stopped_by_watchpoint

@item i386_stopped_by_watchpoint (void)

The macro @code{STOPPED_BY_WATCHPOINT}

is 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