Subversion Repositories openrisc_2011-10-31

This is gdbint.info, produced by makeinfo version 4.8 from

../.././gdb/doc/gdbint.texinfo.

INFO-DIR-SECTION Software development

START-INFO-DIR-ENTRY

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

END-INFO-DIR-ENTRY

   This file documents the internals of the GNU debugger GDB.

Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000,

2001,    2002, 2003, 2004, 2005, 2006    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".

File: gdbint.info,  Node: Top,  Next: Requirements,  Up: (dir)

Scope of this Document

**********************

This document documents the internals of the GNU debugger, GDB.  It

includes description of GDB's key algorithms and operations, as well as

the mechanisms that adapt GDB to specific hosts and targets.

* Menu:

* Requirements::

* Overall Structure::

* Algorithms::

* User Interface::

* libgdb::

* 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::  GDB Currently available observers

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

* Index::

File: gdbint.info,  Node: Requirements,  Next: Overall Structure,  Prev: Top,  Up: Top

1 Requirements

**************

Before diving into the internals, you should understand the formal

requirements and other expectations for GDB.  Although some of these

may seem obvious, there have been proposals for GDB that have run

counter to these requirements.

   First of all, GDB 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.

   GDB is an interactive tool.  Although a batch mode is available,

GDB's primary role is to interact with a human programmer.

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

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

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

   GDB should be able to run everywhere.  No other debugger is

available for even half as many configurations as GDB supports.

File: gdbint.info,  Node: Overall Structure,  Next: Algorithms,  Prev: Requirements,  Up: Top

2 Overall Structure

*******************

GDB consists of three major subsystems: user interface, symbol handling

(the "symbol side"), and target system handling (the "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.

2.1 The Symbol Side

===================

The symbolic side of GDB can be thought of as "everything you can do in

GDB without having a live program running".  For instance, you can look

at the types of variables, and evaluate many kinds of expressions.

2.2 The Target Side

===================

The target side of GDB 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, GDB will use symbolic info to present addresses

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

way.

2.3 Configurations

==================

"Host" refers to attributes of the system where GDB runs.  "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

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

   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, doing a fork to start the

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

registers in the `upage', running `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 `#include'

files that are only available on the host system.  Core file handling

and `setjmp' handling are two common cases.

   When you want to make GDB work "native" on a particular machine, you

have to include all three kinds of information.

2.4 Source Tree Structure

=========================

The GDB 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, `stabsread.c' reads stabs, `dwarf2read.c' reads

DWARF 2, etc.

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

common substrings.  For example, `*-thread.c' files deal with debugging

threads on various platforms; `*read.c' files deal with reading various

kinds of symbol and object files; `inf*.c' files deal with direct

control of the "inferior program" (GDB parlance for the program being

debugged).

   There are several dozens of files in the `*-tdep.c' family.  `tdep'

stands for "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 GDB configuration

(sometimes two, closely related).

   Similarly, there are many `*-nat.c' files, each one for native

debugging on a specific system (e.g., `sparc-linux-nat.c' is for native

debugging of Sparc machines running the Linux kernel).

   The few subdirectories of the source tree are:

`cli'

     Code that implements "CLI", the GDB Command-Line Interpreter.

     *Note Command Interpreter: User Interface.

`gdbserver'

     Code for the GDB remote server.

`gdbtk'

     Code for Insight, the GDB TK-based GUI front-end.

`mi'

     The "GDB/MI", the GDB Machine Interface interpreter.

`signals'

     Target signal translation code.

`tui'

     Code for "TUI", the GDB Text-mode full-screen User Interface.

     *Note TUI: User Interface.

File: gdbint.info,  Node: Algorithms,  Next: User Interface,  Prev: Overall Structure,  Up: Top

3 Algorithms

************

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

3.1 Frames

==========

A frame is a construct that GDB uses to keep track of calling and

called functions.

   GDB's frame model, a fresh design, was implemented with the need to

support DWARF's Call Frame Information in mind.  In fact, the term

"unwind" is taken directly from that specification.  Developers wishing

to learn more about unwinders, are encouraged to read the DWARF

specification.

   GDB's model is that you find a frame's registers by "unwinding" them

from the next younger frame.  That is, `get_frame_register' which

returns the value of a register in frame #1 (the next-to-youngest

frame), is implemented by calling frame #0's `frame_register_unwind'

(the youngest frame).  But then the obvious question is: how do you

access the registers of the youngest frame itself?

   To answer this question, GDB has the "sentinel" frame, the "-1st"

frame.  Unwinding registers from the sentinel frame gives you the

current values of the youngest real frame's registers.  If F is a

sentinel frame, then `get_frame_type (F) == SENTINEL_FRAME'.

3.2 Prologue Analysis

=====================

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

variables and arguments, GDB 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 GDB uses a technique

called "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 GDB 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 GDB 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, GDB's analyzers became more complex and fragile.  Keeping the

prologue analyzers working as GCC (and the instruction sets themselves)

evolved became a substantial task.

   To try to address this problem, the code in `prologue-value.h' and

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

     addi r1, 42     # add 42 to r1

   we don't know exactly what value will be in `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:

     addi r1, 22     # add 22 to r1

   we still don't know what `r1's' value is, but again, we can say it

is now 64 greater than its original value.

   If the next instruction were:

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

   then we can say that `r2's' value is now the original value of `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:

     mov (fp+4), r2

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

holds the original value of `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 `r1' after the

instruction:

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

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

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

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

   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 GDB port.  So it's worthwhile to look

for an approach that will be easier to understand and maintain.  In the

approach described above:

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

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

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

   The file `prologue-value.h' contains detailed comments explaining

the framework and how to use it.

3.3 Breakpoint Handling

=======================

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.

   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 "program counter") ever matches a value in a breakpoint

registers, the CPU raises an exception and reports it to GDB.

   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 GDB's point of view they work the same; GDB 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, GDB will start trying

to set software breakpoints.  (On some architectures, notably the

32-bit x86 platforms, GDB cannot always know whether there's enough

hardware resources to insert all the hardware breakpoints and

watchpoints.  On those platforms, GDB prints an error message only when

the program being debugged is continued.)

   Software breakpoints require GDB to do somewhat more work.  The

basic theory is that GDB 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, GDB will take the exception

and stop the program.  When the user says to continue, GDB 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.

   The basic definition of the software breakpoint is the macro

`BREAKPOINT'.

   Basic breakpoint object handling is in `breakpoint.c'.  However,

much of the interesting breakpoint action is in `infrun.c'.

`target_remove_breakpoint (BP_TGT)'

`target_insert_breakpoint (BP_TGT)'

     Insert or remove a software breakpoint at address

     `BP_TGT->placed_address'.  Returns zero for success, non-zero for

     failure.  On input, BP_TGT contains the address of the breakpoint,

     and is otherwise initialized to zero.  The fields of the `struct

     bp_target_info' pointed to by BP_TGT are updated to contain other

     information about the breakpoint on output.  The field

     `placed_address' may be updated if the breakpoint was placed at a

     related address; the field `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 `shadow_len' is the length of memory

     cached in `shadow_contents', if any; and the field `placed_size'

     is optionally set and used by the target, if it could differ from

     `shadow_len'.

     For example, the remote target `Z0' packet does not require

     shadowing memory, so `shadow_len' is left at zero.  However, the

     length reported by `gdbarch_breakpoint_from_pc' is cached in

     `placed_size', so that a matching `z0' packet can be used to

     remove the breakpoint.

`target_remove_hw_breakpoint (BP_TGT)'

`target_insert_hw_breakpoint (BP_TGT)'

     Insert or remove a hardware-assisted breakpoint at address

     `BP_TGT->placed_address'.  Returns zero for success, non-zero for

     failure.  See `target_insert_breakpoint' for a description of the

     `struct bp_target_info' pointed to by BP_TGT; the

     `shadow_contents' and `shadow_len' members are not used for

     hardware breakpoints, but `placed_size' may be.

3.4 Single Stepping

===================

3.5 Signal Handling

===================

3.6 Thread Handling

===================

3.7 Inferior Function Calls

===========================

3.8 Longjmp Support

===================

GDB has support for figuring out that the target is doing a `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 `maint info breakpoint' command.

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

`gdbarch_get_longjmp_target', which will examine the `jmp_buf'

structure and extract the longjmp target address.  Since `jmp_buf' is

target specific, you will need to define it in the appropriate

`tm-TARGET.h' file.  Look in `tm-sun4os4.h' and `sparc-tdep.c' for

examples of how to do this.

3.9 Watchpoints

===============

Watchpoints are a special kind of breakpoints (*note breakpoints:

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

   Watchpoints can be either hardware-assisted or not; the latter type

is known as "software watchpoints."  GDB always uses hardware-assisted

watchpoints if they are available, and falls back on software

watchpoints otherwise.  Typical situations where GDB will use software

watchpoints are:

   * 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 GDB to use software

     watchpoints.

   * The value of the expression to be watched depends on data held in

     registers (as opposed to memory).

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

   * No hardware-assisted watchpoints provided by the target

     implementation.

   Software watchpoints are very slow, since GDB 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, GDB tries to establish, among other

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

first uses `STOPPED_BY_WATCHPOINT' to see if any watchpoint was hit.

If not, all watchpoint checking is skipped.

   Then GDB calls `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, GDB

compares the address returned by this method with each watched memory

address in each active watchpoint.  For data-read and data-access

watchpoints, GDB announces every watchpoint that watches the triggered

address as being hit.  For this reason, data-read and data-access

watchpoints _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, GDB

considers only those watchpoints which match that address; otherwise,

GDB considers all data-write watchpoints.  For each data-write

watchpoint that GDB 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.

   GDB uses several macros and primitives to support hardware

watchpoints:

`TARGET_HAS_HARDWARE_WATCHPOINTS'

     If defined, the target supports hardware watchpoints.

`TARGET_CAN_USE_HARDWARE_WATCHPOINT (TYPE, COUNT, OTHER)'

     Return the number of hardware watchpoints of type TYPE that are

     possible to be set.  The value is positive if COUNT watchpoints of

     this type can be set, zero if setting watchpoints of this type is

     not supported, and negative if COUNT is more than the maximum

     number of watchpoints of type TYPE that can be set.  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).

`TARGET_REGION_OK_FOR_HW_WATCHPOINT (ADDR, LEN)'

     Return non-zero if hardware watchpoints can be used to watch a

     region whose address is ADDR and whose length in bytes is LEN.

`target_insert_watchpoint (ADDR, LEN, TYPE)'

`target_remove_watchpoint (ADDR, LEN, TYPE)'

     Insert or remove a hardware watchpoint starting at ADDR, for LEN

     bytes.  TYPE is the watchpoint type, one of the possible values of

     the enumerated data type `target_hw_bp_type', defined by

     `breakpoint.h' as follows:

           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 */

             };

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

`target_stopped_data_address (ADDR_P)'

     If the inferior has some watchpoint that triggered, place the

     address associated with the watchpoint at the location pointed to

     by 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 GDB uses it to improve

     handling of those also.

     GDB will only call this method once per watchpoint stop,

     immediately after calling `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.

`HAVE_STEPPABLE_WATCHPOINT'

     If defined to a non-zero value, it is not necessary to disable a

     watchpoint to step over it.    Like

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

`int gdbarch_have_nonsteppable_watchpoint (GDBARCH)'

     If it returns a non-zero value, GDB 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.

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

`CANNOT_STEP_HW_WATCHPOINTS'

     If this is defined to a non-zero value, GDB will remove all

     watchpoints before stepping the inferior.

`STOPPED_BY_WATCHPOINT (WAIT_STATUS)'

     Return non-zero if stopped by a watchpoint.  WAIT_STATUS is of the

     type `struct target_waitstatus', defined by `target.h'.  Normally,

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

     `to_stopped_by_watchpoint' member of the structure (of the type

     `target_ops', defined on `target.h') that describes the

     target-specific operations; `to_stopped_by_watchpoint' ignores the

     WAIT_STATUS argument.

     GDB does not require the non-zero value returned by

     `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".

3.9.1 Watchpoints and Threads

-----------------------------

GDB only supports process-wide watchpoints, which trigger in all

threads.  GDB 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 GNU/Linux native targets, this is

accomplished by using `ALL_LWPS' in `target_insert_watchpoint' and

`target_remove_watchpoint' and by using `linux_set_new_thread' to

register a handler for newly created threads.

   GDB's 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, `linux-nat.c' queues subsequent

events and returns them the next time the program is resumed.  This

means that `STOPPED_BY_WATCHPOINT' and `target_stopped_data_address'

only need to consult the current thread's state--the thread indicated

by `inferior_ptid'.  If two threads have hit watchpoints

simultaneously, those routines will be called a second time for the

second thread.

3.9.2 x86 Watchpoints

---------------------

The 32-bit Intel x86 (a.k.a. ia32) processors feature special debug

registers designed to facilitate debugging.  GDB 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 GDB.

   To use the generic x86 watchpoint support, a port should do the

following:

   * Define the macro `I386_USE_GENERIC_WATCHPOINTS' somewhere in the

     target-dependent headers.

   * Include the `config/i386/nm-i386.h' header file _after_ defining

     `I386_USE_GENERIC_WATCHPOINTS'.

   * Add `i386-nat.o' to the value of the Make variable `NATDEPFILES'

     (*note NATDEPFILES: Native Debugging.) or `TDEPFILES' (*note

     TDEPFILES: Target Architecture Definition.).

   * Provide implementations for the `I386_DR_LOW_*' macros described

     below.  Typically, each macro should call a target-specific

     function which does the real work.

   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:

`I386_DR_LOW_SET_CONTROL (VAL)'

     Set the Debug Control (DR7) register to the value VAL.

`I386_DR_LOW_SET_ADDR (IDX, ADDR)'

     Put the address ADDR into the debug register number IDX.

`I386_DR_LOW_RESET_ADDR (IDX)'

     Reset (i.e. zero out) the address stored in the debug register

     number IDX.

`I386_DR_LOW_GET_STATUS'

     Return the value of the Debug Status (DR6) register.  This value is

     used immediately after it is returned by `I386_DR_LOW_GET_STATUS',

     so as to support per-thread status register values.

   For each one of the 4 debug registers (whose indices are from 0 to 3)

that store addresses, a reference count is maintained by GDB, 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.  GDB 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 GDB 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

GDB's application code:

`i386_region_ok_for_watchpoint (ADDR, LEN)'

     The macro `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.

`i386_stopped_data_address (ADDR_P)'

     The target function `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

     `I386_DR_LOW_GET_STATUS' macro, and returns the address associated

     with the first bit that is set in DR6.

`i386_stopped_by_watchpoint (void)'

     The macro `STOPPED_BY_WATCHPOINT' is set to call this function.

     The argument passed to `STOPPED_BY_WATCHPOINT' is ignored.  This

     function examines the breakpoint condition bits in the DR6 Debug

     Status register, as returned by the `I386_DR_LOW_GET_STATUS'

     macro, and returns true if any bit is set.  Otherwise, false is

     returned.

`i386_insert_watchpoint (ADDR, LEN, TYPE)'

`i386_remove_watchpoint (ADDR, LEN, TYPE)'

     Insert or remove a watchpoint.  The macros

     `target_insert_watchpoint' and `target_remove_watchpoint' are set

     to call these functions.  `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 mirrored

     value to ADDR, sets the mirrored value of DR7 Debug Control

     register as appropriate for the LEN and TYPE parameters, and then

     passes the new values of the debug register and DR7 to the

     inferior by calling `I386_DR_LOW_SET_ADDR' and

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

     `i386_remove_watchpoint' does the opposite: it resets the address

     in the mirrored value of the debug register and its read/write and

     length bits in the mirrored value of DR7, then passes these new

     values to the inferior via `I386_DR_LOW_RESET_ADDR' and

     `I386_DR_LOW_SET_CONTROL'.  If a register is shared by several

     watchpoints, each time a `i386_remove_watchpoint' is called, it

     decrements the reference count, and only calls

     `I386_DR_LOW_RESET_ADDR' and `I386_DR_LOW_SET_CONTROL' when the

     count goes to zero.

`i386_insert_hw_breakpoint (BP_TGT)'

`i386_remove_hw_breakpoint (BP_TGT)'

     These functions insert and remove hardware-assisted breakpoints.

     The macros `target_insert_hw_breakpoint' and

     `target_remove_hw_breakpoint' are set to call these functions.

     The argument is a `struct bp_target_info *', as described in the

     documentation for `target_insert_breakpoint'.  These functions

     work like `i386_insert_watchpoint' and `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.

`i386_stopped_by_hwbp (void)'

     This function returns non-zero if the inferior has some watchpoint

     or hardware breakpoint that triggered.  It works like

     `i386_stopped_data_address', except that it doesn't record the

     address whose watchpoint triggered.

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

*Notes:*

  1. x86 processors support setting watchpoints on I/O reads or writes.

     However, since no target supports this (as of March 2001), and

     since `enum target_hw_bp_type' doesn't even have an enumeration

     for I/O watchpoints, this feature is not yet available to GDB

     running on x86.

  2. 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 GDB always

     sets watchpoints to be locally enabled, since global watchpoints

     might interfere with the underlying OS and are probably

     unavailable in many platforms.

3.10 Checkpoints

================

In the abstract, a checkpoint is a point in the execution history of

the program, which the user may wish to return to at some later time.

   Internally, a checkpoint is a saved copy of the program state,

including whatever information is required in order to restore the

program to that state at a later time.  This can be expected to include

the state of registers and memory, and may include external state such

as the state of open files and devices.

   There are a number of ways in which checkpoints may be implemented

in gdb, e.g. as corefiles, as forked processes, and as some opaque

method implemented on the target side.

   A corefile can be used to save an image of target memory and register

state, which can in principle be restored later -- but corefiles do not

typically include information about external entities such as open

files.  Currently this method is not implemented in gdb.

   A forked process can save the state of user memory and registers, as

well as some subset of external (kernel) state.  This method is used to

implement checkpoints on Linux, and in principle might be used on other

systems.

   Some targets, e.g. simulators, might have their own built-in method

for saving checkpoints, and gdb might be able to take advantage of that

capability without necessarily knowing any details of how it is done.

3.11 Observing changes in GDB internals

=======================================

In order to function properly, several modules need to be notified when

some changes occur in the GDB internals.  Traditionally, these modules

have relied on several paradigms, the most common ones being hooks and

gdb-events.  Unfortunately, none of these paradigms was versatile

enough to become the standard notification mechanism in GDB.  The fact

that they only supported one "client" was also a strong limitation.

   A new paradigm, based on the Observer pattern of the `Design

Patterns' book, has therefore been implemented.  The goal was to provide

a new interface overcoming the issues with the notification mechanisms

previously available.  This new interface needed to be strongly typed,

easy to extend, and versatile enough to be used as the standard

interface when adding new notifications.

   See *Note GDB Observers:: for a brief description of the observers

currently implemented in GDB. The rationale for the current

implementation is also briefly discussed.

File: gdbint.info,  Node: User Interface,  Next: libgdb,  Prev: Algorithms,  Up: Top

4 User Interface

****************

GDB has several user interfaces.  Although the command-line interface

is the most common and most familiar, there are others.

4.1 Command Interpreter

=======================

The command interpreter in GDB is fairly simple.  It is designed to

allow for the set of commands to be augmented dynamically, and also has

a recursive subcommand capability, where the first argument to a

command may itself direct a lookup on a different command list.

   For instance, the `set' command just starts a lookup on the

`setlist' command list, while `set thread' recurses to the

`set_thread_cmd_list'.

   To add commands in general, use `add_cmd'.  `add_com' adds to the

main command list, and should be used for those commands.  The usual

place to add commands is in the `_initialize_XYZ' routines at the ends

of most source files.

   To add paired `set' and `show' commands, use `add_setshow_cmd' or

`add_setshow_cmd_full'.  The former is a slightly simpler interface

which is useful when you don't need to further modify the new command

structures, while the latter returns the new command structures for

manipulation.

   Before removing commands from the command set it is a good idea to

deprecate them for some time.  Use `deprecate_cmd' on commands or

aliases to set the deprecated flag.  `deprecate_cmd' takes a `struct

cmd_list_element' as it's first argument.  You can use the return value

from `add_com' or `add_cmd' to deprecate the command immediately after

it is created.

   The first time a command is used the user will be warned and offered

a replacement (if one exists). Note that the replacement string passed

to `deprecate_cmd' should be the full name of the command, i.e., the