\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c
@c %**start of header
@copying
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2009 Free Software Foundation, Inc.
+Copyright (C) 1988-2010 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
@value{GDBN}
* Operating System Information:: Getting additional information from
the operating system
+* Trace File Format:: GDB trace file format
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
@itemx -x @var{file}
@cindex @code{--command}
@cindex @code{-x}
-Execute @value{GDBN} commands from file @var{file}. @xref{Command
-Files,, Command files}.
+Execute commands from file @var{file}. The contents of this file is
+evaluated exactly as the @code{source} command would.
+@xref{Command Files,, Command files}.
@item -eval-command @var{command}
@itemx -ex @var{command}
command files specified with @samp{-x} (and all commands from
initialization files, if not inhibited with @samp{-n}). Exit with
nonzero status if an error occurs in executing the @value{GDBN} commands
-in the command files.
+in the command files. Batch mode also disables pagination;
+@pxref{Screen Size} and acts as if @kbd{set confirm off} were in
+effect (@pxref{Messages/Warnings}).
Batch mode may be useful for running @value{GDBN} as a filter, for
example to download and run a program on another computer; in order to
@cindex @code{$_} and @code{info breakpoints}
@item info breakpoints @r{[}@var{n}@r{]}
@itemx info break @r{[}@var{n}@r{]}
-@itemx info watchpoints @r{[}@var{n}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument @var{n} means print information only
about the specified breakpoint (or watchpoint or catchpoint). For
@kindex info watchpoints @r{[}@var{n}@r{]}
@item info watchpoints
-This command prints a list of watchpoints, breakpoints, and catchpoints;
-it is the same as @code{info break} (@pxref{Set Breaks}).
+This command prints a list of watchpoints, using the same format as
+@code{info break} (@pxref{Set Breaks}).
@end table
@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
and @sc{gnu}/Linux.
@item syscall
-@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @r{...}
+@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
syscall is a mechanism for application programs to request a service
that you can @dfn{enable} it again later.
You disable and enable breakpoints, watchpoints, and catchpoints with
-the @code{enable} and @code{disable} commands, optionally specifying one
-or more breakpoint numbers as arguments. Use @code{info break} or
-@code{info watch} to print a list of breakpoints, watchpoints, and
-catchpoints if you do not know which numbers to use.
+the @code{enable} and @code{disable} commands, optionally specifying
+one or more breakpoint numbers as arguments. Use @code{info break} to
+print a list of all breakpoints, watchpoints, and catchpoints if you
+do not know which numbers to use.
Disabling and enabling a breakpoint that has multiple locations
affects all of its locations.
@table @code
@kindex commands
@kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{bnum}@r{]}
+@item commands @r{[}@var{range}@dots{}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
-Specify a list of commands for breakpoint number @var{bnum}. The commands
+Specify a list of commands for the given breakpoints. The commands
themselves appear on the following lines. Type a line containing just
@code{end} to terminate the commands.
To remove all commands from a breakpoint, type @code{commands} and
follow it immediately with @code{end}; that is, give no commands.
-With no @var{bnum} argument, @code{commands} refers to the last
-breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
-recently encountered).
+With no argument, @code{commands} refers to the last breakpoint,
+watchpoint, or catchpoint set (not to the breakpoint most recently
+encountered). If the most recent breakpoints were set with a single
+command, then the @code{commands} will apply to all the breakpoints
+set by that command. This applies to breakpoints set by
+@code{rbreak}, and also applies when a single @code{break} command
+creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous
+Expressions}).
@end table
Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
program.
You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before the
-breakpoint condition, like this:
+well; in this case, place @samp{thread @var{threadno}} before or
+after the breakpoint condition, like this:
@smallexample
(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
to the caller of that function, @emph{before} the function was called,
just as the normal @code{next} command would take you from the last
line of a function back to its return to its caller
-@footnote{Unles the code is too heavily optimized.}.
+@footnote{Unless the code is too heavily optimized.}.
@kindex reverse-nexti
@kindex rni @r{(@code{reverse-nexti})}
Like @code{nexti}, @code{reverse-nexti} executes a single instruction
in reverse, except that called functions are ``un-executed'' atomically.
That is, if the previously executed instruction was a return from
-another instruction, @code{reverse-nexti} will continue to execute
+another function, @code{reverse-nexti} will continue to execute
in reverse until the call to that function (from the current stack
frame) is reached.
@item show record stop-at-limit
Show the current setting of @code{stop-at-limit}.
-@kindex info record insn-number
-@item info record insn-number
-Show the current number of recorded instructions.
+@kindex info record
+@item info record
+Show various statistics about the state of process record and its
+in-memory execution log buffer, including:
+
+@itemize @bullet
+@item
+Whether in record mode or replay mode.
+@item
+Lowest recorded instruction number (counting from when the current execution log started recording instructions).
+@item
+Highest recorded instruction number.
+@item
+Current instruction about to be replayed (if in replay mode).
+@item
+Number of instructions contained in the execution log.
+@item
+Maximum number of instructions that may be contained in the execution log.
+@end itemize
@kindex record delete
@kindex rec del
The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
-surrounding this value. Two arguments specify a range of addresses
-(first inclusive, second exclusive) to dump.
+surrounding this value. When two arguments are given, they should
+be separated by a comma, possibly surrounded by whitespace. The
+arguments specify a range of addresses (first inclusive, second exclusive)
+to dump. In that case, the name of the function is also printed (since
+there could be several functions in the given range).
+
+The argument(s) can be any expression yielding a numeric value, such as
+@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
If the range of memory being disassembled contains current program counter,
the instruction at that location is shown with a @code{=>} marker.
HP PA-RISC 2.0 code:
@smallexample
-(@value{GDBP}) disas 0x32c4 0x32e4
+(@value{GDBP}) disas 0x32c4, 0x32e4
Dump of assembler code from 0x32c4 to 0x32e4:
0x32c4 <main+204>: addil 0,dp
0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
(@value{GDBP}) disas /m main
Dump of assembler code for function main:
5 @{
- 0x08048330 <main+0>: push %ebp
- 0x08048331 <main+1>: mov %esp,%ebp
- 0x08048333 <main+3>: sub $0x8,%esp
- 0x08048336 <main+6>: and $0xfffffff0,%esp
- 0x08048339 <main+9>: sub $0x10,%esp
+ 0x08048330 <+0>: push %ebp
+ 0x08048331 <+1>: mov %esp,%ebp
+ 0x08048333 <+3>: sub $0x8,%esp
+ 0x08048336 <+6>: and $0xfffffff0,%esp
+ 0x08048339 <+9>: sub $0x10,%esp
6 printf ("Hello.\n");
-=> 0x0804833c <main+12>: movl $0x8048440,(%esp)
- 0x08048343 <
main+19>: call 0x8048284 <puts@@plt>
+=> 0x0804833c <+12>: movl $0x8048440,(%esp)
+ 0x08048343 <+19>: call 0x8048284 <puts@@plt>
7 return 0;
8 @}
- 0x08048348 <main+24>: mov $0x0,%eax
- 0x0804834d <main+29>: leave
- 0x0804834e <main+30>: ret
+ 0x08048348 <+24>: mov $0x0,%eax
+ 0x0804834d <+29>: leave
+ 0x0804834e <+30>: ret
End of assembler dump.
@end smallexample
command (abbreviated @code{p}), or its synonym @code{inspect}. It
evaluates and prints the value of an expression of the language your
program is written in (@pxref{Languages, ,Using @value{GDBN} with
-Different Languages}).
+Different Languages}). It may also print the expression using a
+Python-based pretty-printer (@pxref{Pretty Printing}).
@table @code
@item print @var{expr}
@item r
@cindex raw printing
Print using the @samp{raw} formatting. By default, @value{GDBN} will
-use a type-specific pretty-printer. The @samp{r} format bypasses any
-pretty-printer which might exist for the value's type.
+use a Python-based pretty-printer, if one is available (@pxref{Pretty
+Printing}). This typically results in a higher-level display of the
+value's contents. The @samp{r} format bypasses any Python
+pretty-printer which might exist.
@end table
For example, to print the program counter in hex (@pxref{Registers}), type
packets used to implement tracepoints are described in @ref{Tracepoint
Packets}.
+It is also possible to get trace data from a file, in a manner reminiscent
+of corefiles; you specify the filename, and use @code{tfind} to search
+through the file. @xref{Trace Files}, for more details.
+
This chapter describes the tracepoint commands and features.
@menu
* Set Tracepoints::
* Analyze Collected Data::
* Tracepoint Variables::
+* Trace Files::
@end menu
@node Set Tracepoints
commands to examine the values these data had at the time the
tracepoint was hit.
-Tracepoints do not support every breakpoint feature. Conditional
-expressions and ignore counts on tracepoints have no effect, and
-tracepoints cannot run @value{GDBN} commands when they are
-hit. Tracepoints may not be thread-specific either.
+Tracepoints do not support every breakpoint feature. Ignore counts on
+tracepoints have no effect, and tracepoints cannot run @value{GDBN}
+commands when they are hit. Tracepoints may not be thread-specific
+either.
+
+@cindex fast tracepoints
+Some targets may support @dfn{fast tracepoints}, which are inserted in
+a different way (such as with a jump instead of a trap), that is
+faster but possibly restricted in where they may be installed.
This section describes commands to set tracepoints and associated
conditions and actions.
* Enable and Disable Tracepoints::
* Tracepoint Passcounts::
* Tracepoint Conditions::
+* Trace State Variables::
* Tracepoint Actions::
* Listing Tracepoints::
* Starting and Stopping Trace Experiments::
+* Tracepoint Restrictions::
@end menu
@node Create and Delete Tracepoints
@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
information on tracepoint conditions.
+@item ftrace @var{location} [ if @var{cond} ]
+@cindex set fast tracepoint
+@kindex ftrace
+The @code{ftrace} command sets a fast tracepoint. For targets that
+support them, fast tracepoints will use a more efficient but possibly
+less general technique to trigger data collection, such as a jump
+instruction instead of a trap, or some sort of hardware support. It
+may not be possible to create a fast tracepoint at the desired
+location, in which case the command will exit with an explanatory
+message.
+
+@value{GDBN} handles arguments to @code{ftrace} exactly as for
+@code{trace}.
+
@vindex $tpnum
@cindex last tracepoint number
@cindex recent tracepoint number
(@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
@end smallexample
+@node Trace State Variables
+@subsection Trace State Variables
+@cindex trace state variables
+
+A @dfn{trace state variable} is a special type of variable that is
+created and managed by target-side code. The syntax is the same as
+that for GDB's convenience variables (a string prefixed with ``$''),
+but they are stored on the target. They must be created explicitly,
+using a @code{tvariable} command. They are always 64-bit signed
+integers.
+
+Trace state variables are remembered by @value{GDBN}, and downloaded
+to the target along with tracepoint information when the trace
+experiment starts. There are no intrinsic limits on the number of
+trace state variables, beyond memory limitations of the target.
+
+@cindex convenience variables, and trace state variables
+Although trace state variables are managed by the target, you can use
+them in print commands and expressions as if they were convenience
+variables; @value{GDBN} will get the current value from the target
+while the trace experiment is running. Trace state variables share
+the same namespace as other ``$'' variables, which means that you
+cannot have trace state variables with names like @code{$23} or
+@code{$pc}, nor can you have a trace state variable and a convenience
+variable with the same name.
+
+@table @code
+
+@item tvariable $@var{name} [ = @var{expression} ]
+@kindex tvariable
+The @code{tvariable} command creates a new trace state variable named
+@code{$@var{name}}, and optionally gives it an initial value of
+@var{expression}. @var{expression} is evaluated when this command is
+entered; the result will be converted to an integer if possible,
+otherwise @value{GDBN} will report an error. A subsequent
+@code{tvariable} command specifying the same name does not create a
+variable, but instead assigns the supplied initial value to the
+existing variable of that name, overwriting any previous initial
+value. The default initial value is 0.
+
+@item info tvariables
+@kindex info tvariables
+List all the trace state variables along with their initial values.
+Their current values may also be displayed, if the trace experiment is
+currently running.
+
+@item delete tvariable @r{[} $@var{name} @dots{} @r{]}
+@kindex delete tvariable
+Delete the given trace state variables, or all of them if no arguments
+are specified.
+
+@end table
+
@node Tracepoint Actions
@subsection Tracepoint Action Lists
@code{actions} without bothering about its number). You specify the
actions themselves on the following lines, one action at a time, and
terminate the actions list with a line containing just @code{end}. So
-far, the only defined actions are @code{collect} and
+far, the only defined actions are @code{collect}, @code{teval}, and
@code{while-stepping}.
@cindex remove actions from a tracepoint
commands indicating the things to be collected when the tracepoint is
hit. Then, in order to single-step and collect additional data
following the tracepoint, a @code{while-stepping} command is used,
-followed by the list of things to be collected while stepping. The
-@code{while-stepping} command is terminated by its own separate
-@code{end} command. Lastly, the action list is terminated by an
-@code{end} command.
+followed by the list of things to be collected after each step in a
+sequence of single steps. The @code{while-stepping} command is
+terminated by its own separate @code{end} command. Lastly, the action
+list is terminated by an @code{end} command.
@smallexample
(@value{GDBP}) @b{trace foo}
The command @code{info scope} (@pxref{Symbols, info scope}) is
particularly useful for figuring out what data to collect.
+@kindex teval @r{(tracepoints)}
+@item teval @var{expr1}, @var{expr2}, @dots{}
+Evaluate the given expressions when the tracepoint is hit. This
+command accepts a comma-separated list of expressions. The results
+are discarded, so this is mainly useful for assigning values to trace
+state variables (@pxref{Trace State Variables}) without adding those
+values to the trace buffer, as would be the case if the @code{collect}
+action were used.
+
@kindex while-stepping @r{(tracepoints)}
@item while-stepping @var{n}
-Perform @var{n} single-step traces after the tracepoint, collecting
-new data at each step. The @code{while-stepping} command is
-followed by the list of what to collect while stepping (followed by
-its own @code{end} command):
+Perform @var{n} single-step instruction traces after the tracepoint,
+collecting new data after each step. The @code{while-stepping}
+command is followed by the list of what to collect while stepping
+(followed by its own @code{end} command):
@smallexample
> while-stepping 12
@end smallexample
@noindent
-You may abbreviate @code{while-stepping} as @code{ws} or
+Note that @code{$pc} is not automatically collected by
+@code{while-stepping}; you need to explicitly collect that register if
+you need it. You may abbreviate @code{while-stepping} as @code{ws} or
@code{stepping}.
+
+@item set default-collect @var{expr1}, @var{expr2}, @dots{}
+@kindex set default-collect
+@cindex default collection action
+This variable is a list of expressions to collect at each tracepoint
+hit. It is effectively an additional @code{collect} action prepended
+to every tracepoint action list. The expressions are parsed
+individually for each tracepoint, so for instance a variable named
+@code{xyz} may be interpreted as a global for one tracepoint, and a
+local for another, as appropriate to the tracepoint's location.
+
+@item show default-collect
+@kindex show default-collect
+Show the list of expressions that are collected by default at each
+tracepoint hit.
+
@end table
@node Listing Tracepoints
(@value{GDBP}) @b{tstop}
@end smallexample
+@cindex disconnected tracing
+You can choose to continue running the trace experiment even if
+@value{GDBN} disconnects from the target, voluntarily or
+involuntarily. For commands such as @code{detach}, the debugger will
+ask what you want to do with the trace. But for unexpected
+terminations (@value{GDBN} crash, network outage), it would be
+unfortunate to lose hard-won trace data, so the variable
+@code{disconnected-tracing} lets you decide whether the trace should
+continue running without @value{GDBN}.
+
+@table @code
+@item set disconnected-tracing on
+@itemx set disconnected-tracing off
+@kindex set disconnected-tracing
+Choose whether a tracing run should continue to run if @value{GDBN}
+has disconnected from the target. Note that @code{detach} or
+@code{quit} will ask you directly what to do about a running trace no
+matter what this variable's setting, so the variable is mainly useful
+for handling unexpected situations, such as loss of the network.
+
+@item show disconnected-tracing
+@kindex show disconnected-tracing
+Show the current choice for disconnected tracing.
+
+@end table
+
+When you reconnect to the target, the trace experiment may or may not
+still be running; it might have filled the trace buffer in the
+meantime, or stopped for one of the other reasons. If it is running,
+it will continue after reconnection.
+
+Upon reconnection, the target will upload information about the
+tracepoints in effect. @value{GDBN} will then compare that
+information to the set of tracepoints currently defined, and attempt
+to match them up, allowing for the possibility that the numbers may
+have changed due to creation and deletion in the meantime. If one of
+the target's tracepoints does not match any in @value{GDBN}, the
+debugger will create a new tracepoint, so that you have a number with
+which to specify that tracepoint. This matching-up process is
+necessarily heuristic, and it may result in useless tracepoints being
+created; you may simply delete them if they are of no use.
+
+@cindex circular trace buffer
+If your target agent supports a @dfn{circular trace buffer}, then you
+can run a trace experiment indefinitely without filling the trace
+buffer; when space runs out, the agent deletes already-collected trace
+frames, oldest first, until there is enough room to continue
+collecting. This is especially useful if your tracepoints are being
+hit too often, and your trace gets terminated prematurely because the
+buffer is full. To ask for a circular trace buffer, simply set
+@samp{circular_trace_buffer} to on. You can set this at any time,
+including during tracing; if the agent can do it, it will change
+buffer handling on the fly, otherwise it will not take effect until
+the next run.
+
+@table @code
+@item set circular-trace-buffer on
+@itemx set circular-trace-buffer off
+@kindex set circular-trace-buffer
+Choose whether a tracing run should use a linear or circular buffer
+for trace data. A linear buffer will not lose any trace data, but may
+fill up prematurely, while a circular buffer will discard old trace
+data, but it will have always room for the latest tracepoint hits.
+
+@item show circular-trace-buffer
+@kindex show circular-trace-buffer
+Show the current choice for the trace buffer. Note that this may not
+match the agent's current buffer handling, nor is it guaranteed to
+match the setting that might have been in effect during a past run,
+for instance if you are looking at frames from a trace file.
+
+@end table
+
+@node Tracepoint Restrictions
+@subsection Tracepoint Restrictions
+
+@cindex tracepoint restrictions
+There are a number of restrictions on the use of tracepoints. As
+described above, tracepoint data gathering occurs on the target
+without interaction from @value{GDBN}. Thus the full capabilities of
+the debugger are not available during data gathering, and then at data
+examination time, you will be limited by only having what was
+collected. The following items describe some common problems, but it
+is not exhaustive, and you may run into additional difficulties not
+mentioned here.
+
+@itemize @bullet
+
+@item
+Tracepoint expressions are intended to gather objects (lvalues). Thus
+the full flexibility of GDB's expression evaluator is not available.
+You cannot call functions, cast objects to aggregate types, access
+convenience variables or modify values (except by assignment to trace
+state variables). Some language features may implicitly call
+functions (for instance Objective-C fields with accessors), and therefore
+cannot be collected either.
+
+@item
+Collection of local variables, either individually or in bulk with
+@code{$locals} or @code{$args}, during @code{while-stepping} may
+behave erratically. The stepping action may enter a new scope (for
+instance by stepping into a function), or the location of the variable
+may change (for instance it is loaded into a register). The
+tracepoint data recorded uses the location information for the
+variables that is correct for the tracepoint location. When the
+tracepoint is created, it is not possible, in general, to determine
+where the steps of a @code{while-stepping} sequence will advance the
+program---particularly if a conditional branch is stepped.
+
+@item
+Collection of an incompletely-initialized or partially-destroyed object
+may result in something that @value{GDBN} cannot display, or displays
+in a misleading way.
+
+@item
+When @value{GDBN} displays a pointer to character it automatically
+dereferences the pointer to also display characters of the string
+being pointed to. However, collecting the pointer during tracing does
+not automatically collect the string. You need to explicitly
+dereference the pointer and provide size information if you want to
+collect not only the pointer, but the memory pointed to. For example,
+@code{*ptr@@50} can be used to collect the 50 element array pointed to
+by @code{ptr}.
+
+@item
+It is not possible to collect a complete stack backtrace at a
+tracepoint. Instead, you may collect the registers and a few hundred
+bytes from the stack pointer with something like @code{*$esp@@300}
+(adjust to use the name of the actual stack pointer register on your
+target architecture, and the amount of stack you wish to capture).
+Then the @code{backtrace} command will show a partial backtrace when
+using a trace frame. The number of stack frames that can be examined
+depends on the sizes of the frames in the collected stack. Note that
+if you ask for a block so large that it goes past the bottom of the
+stack, the target agent may report an error trying to read from an
+invalid address.
+
+@item
+If you do not collect registers at a tracepoint, @value{GDBN} can
+infer that the value of @code{$pc} must be the same as the address of
+the tracepoint and use that when you are looking at a trace frame
+for that tracepoint. However, this cannot work if the tracepoint has
+multiple locations (for instance if it was set in a function that was
+inlined), or if it has a @code{while-stepping} loop. In those cases
+@value{GDBN} will warn you that it can't infer @code{$pc}, and default
+it to zero.
+
+@end itemize
@node Analyze Collected Data
@section Using the Collected Data
@item tfind outside @var{addr1}, @var{addr2}
Find the next snapshot whose PC is outside the given range of
-addresses.
+addresses (exclusive).
@item tfind range @var{addr1}, @var{addr2}
Find the next snapshot whose PC is between @var{addr1} and
-@var{addr2}. @c FIXME: Is the range inclusive or exclusive?
+@var{addr2} (inclusive).
@item tfind line @r{[}@var{file}:@r{]}@var{n}
Find the next snapshot associated with the source line @var{n}. If
(@value{GDBP})
@end smallexample
+@code{tdump} works by scanning the tracepoint's current collection
+actions and printing the value of each expression listed. So
+@code{tdump} can fail, if after a run, you change the tracepoint's
+actions to mention variables that were not collected during the run.
+
+Also, for tracepoints with @code{while-stepping} loops, @code{tdump}
+uses the collected value of @code{$pc} to distinguish between trace
+frames that were collected at the tracepoint hit, and frames that were
+collected while stepping. This allows it to correctly choose whether
+to display the basic list of collections, or the collections from the
+body of the while-stepping loop. However, if @code{$pc} was not collected,
+then @code{tdump} will always attempt to dump using the basic collection
+list, and may fail if a while-stepping frame does not include all the
+same data that is collected at the tracepoint hit.
+@c This is getting pretty arcane, example would be good.
+
@node save-tracepoints
@subsection @code{save-tracepoints @var{filename}}
@kindex save-tracepoints
Here's a simple example of using these convenience variables for
stepping through all the trace snapshots and printing some of their
-data.
+data. Note that these are not the same as trace state variables,
+which are managed by the target.
@smallexample
(@value{GDBP}) @b{tfind start}
> end
@end smallexample
+@node Trace Files
+@section Using Trace Files
+@cindex trace files
+
+In some situations, the target running a trace experiment may no
+longer be available; perhaps it crashed, or the hardware was needed
+for a different activity. To handle these cases, you can arrange to
+dump the trace data into a file, and later use that file as a source
+of trace data, via the @code{target tfile} command.
+
+@table @code
+
+@kindex tsave
+@item tsave [ -r ] @var{filename}
+Save the trace data to @var{filename}. By default, this command
+assumes that @var{filename} refers to the host filesystem, so if
+necessary @value{GDBN} will copy raw trace data up from the target and
+then save it. If the target supports it, you can also supply the
+optional argument @code{-r} (``remote'') to direct the target to save
+the data directly into @var{filename} in its own filesystem, which may be
+more efficient if the trace buffer is very large. (Note, however, that
+@code{target tfile} can only read from files accessible to the host.)
+
+@kindex target tfile
+@kindex tfile
+@item target tfile @var{filename}
+Use the file named @var{filename} as a source of trace data. Commands
+that examine data work as they do with a live target, but it is not
+possible to run any new trace experiments. @code{tstatus} will report
+the state of the trace run at the moment the data was saved, as well
+as the current trace frame you are examining. @var{filename} must be
+on a filesystem accessible to the host.
+
+@end table
+
@node Overlays
@chapter Debugging Programs That Use Overlays
@cindex overlays
@code{Standard} explicitly.
@end itemize
+Older versions of the compiler sometimes generate erroneous debugging
+information, resulting in the debugger incorrectly printing the value
+of affected entities. In some cases, the debugger is able to work
+around an issue automatically. In other cases, the debugger is able
+to work around the issue, but the work-around has to be specifically
+enabled.
+
+@kindex set ada trust-PAD-over-XVS
+@kindex show ada trust-PAD-over-XVS
+@table @code
+
+@item set ada trust-PAD-over-XVS on
+Configure GDB to strictly follow the GNAT encoding when computing the
+value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
+types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
+a complete description of the encoding used by the GNAT compiler).
+This is the default.
+
+@item set ada trust-PAD-over-XVS off
+This is related to the encoding using by the GNAT compiler. If @value{GDBN}
+sometimes prints the wrong value for certain entities, changing @code{ada
+trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
+the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
+@code{off}, but this incurs a slight performance penalty, so it is
+recommended to leave this setting to @code{on} unless necessary.
+
+@end table
+
@node Unsupported Languages
@section Unsupported Languages
@kindex info variables
@item info variables
-Print the names and data types of all variables that are declared
+Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
@item info variables @var{regexp}
@kindex readnow
@cindex reading symbols immediately
@cindex symbols, reading immediately
-@item symbol-file @var{filename} @r{[} -readnow @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]}
+@item symbol-file @r{[} -readnow @r{]} @var{filename}
+@itemx file @r{[} -readnow @r{]} @var{filename}
You can override the @value{GDBN} two-stage strategy for reading symbol
tables by using the @samp{-readnow} option with any of the commands that
load symbol table information, if you want to be sure @value{GDBN} has the
@table @code
@kindex set debug-file-directory
-@item set debug-file-directory @var{directory}
-Set the directory which @value{GDBN} searches for separate debugging
-information files to @var{directory}.
+@item set debug-file-directory @var{directories}
+Set the directories which @value{GDBN} searches for separate debugging
+information files to @var{directory}. Multiple directory components can be set
+concatenating them by a directory separator.
@kindex show debug-file-directory
@item show debug-file-directory
-Show the directory @value{GDBN} searches for separate debugging
+Show the directories @value{GDBN} searches for separate debugging
information files.
@end table
system, and you can put it somewhere in memory where it won't get
clobbered by the download.
-@item target sim
+@item target sim @r{[}@var{simargs}@r{]} @dots{}
@cindex built-in simulator target
Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
In general,
target system. If it is not set, the target will use a default
filename (e.g.@: the last program run).
+@item set remote interrupt-sequence
+@cindex interrupt remote programs
+@cindex select Ctrl-C, BREAK or BREAK-g
+Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or
+@samp{BREAK-g} as the
+sequence to the remote target in order to interrupt the execution.
+@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which
+is high level of serial line for some certain time.
+Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g.
+It is @code{BREAK} signal followed by character @code{g}.
+
+@item show interrupt-sequence
+Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g}
+is sent by @value{GDBN} to interrupt the remote program.
+@code{BREAK-g} is BREAK signal followed by @code{g} and
+also known as Magic SysRq g.
+
+@item set remote interrupt-on-connect
+@cindex send interrupt-sequence on start
+Specify whether interrupt-sequence is sent to remote target when
+@value{GDBN} connects to it. This is mostly needed when you debug
+Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g}
+which is known as Magic SysRq g in order to connect @value{GDBN}.
+
+@item show interrupt-on-connect
+Show whether interrupt-sequence is sent
+to remote target when @value{GDBN} connects to it.
+
@kindex set tcp
@kindex show tcp
@item set tcp auto-retry on
@tab @code{qXfer:siginfo:write}
@tab @code{set $_siginfo}
+@item @code{threads}
+@tab @code{qXfer:threads:read}
+@tab @code{info threads}
+
@item @code{get-thread-local-@*storage-address}
@tab @code{qGetTLSAddr}
@tab Displaying @code{__thread} variables
@item set new-console @var{mode}
If @var{mode} is @code{on} the debuggee will
be started in a new console on next start.
-If @var{mode} is @code{off}i, the debuggee will
+If @var{mode} is @code{off}, the debuggee will
be started in the same console as the debugger.
@kindex show new-console
Show the setting of RDI heartbeat packets.
@end table
+@table @code
+@item target sim @r{[}@var{simargs}@r{]} @dots{}
+The @value{GDBN} ARM simulator accepts the following optional arguments.
+
+@table @code
+@item --swi-support=@var{type}
+Tell the simulator which SWI interfaces to support.
+@var{type} may be a comma separated list of the following values.
+The default value is @code{all}.
+
+@table @code
+@item none
+@item demon
+@item angel
+@item redboot
+@item all
+@end table
+@end table
+@end table
@node M32R/D
@subsection Renesas M32R/D and M32R/SDI
@itemx set pagination off
@kindex set pagination
Turn the output pagination on or off; the default is on. Turning
-pagination off is the alternative to @code{set height 0}.
+pagination off is the alternative to @code{set height 0}. Note that
+running @value{GDBN} with the @option{--batch} option (@pxref{Mode
+Options, -batch}) also automatically disables pagination.
@item show pagination
@kindex show pagination
@cindex confirmation
@cindex stupid questions
@item set confirm off
-Disables confirmation requests.
+Disables confirmation requests. Note that running @value{GDBN} with
+the @option{--batch} option (@pxref{Mode Options, -batch}) also
+automatically disables confirmation requests.
@item set confirm on
Enables confirmation requests (the default).
@item show debug overload
Displays the current state of displaying @value{GDBN} C@t{++} overload
debugging info.
+@cindex expression parser, debugging info
+@cindex debug expression parser
+@item set debug parser
+Turns on or off the display of expression parser debugging output.
+Internally, this sets the @code{yydebug} variable in the expression
+parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for
+details. The default is off.
+@item show debug parser
+Show the current state of expression parser debugging.
@cindex packets, reporting on stdout
@cindex serial connections, debugging
@cindex debug remote protocol
on composition of @value{GDBN} commands, and the second is based on the
Python scripting language.
+To facilitate the use of these extensions, @value{GDBN} is capable
+of evaluating the contents of a file. When doing so, @value{GDBN}
+can recognize which scripting language is being used by looking at
+the filename extension. Files with an unrecognized filename extension
+are always treated as a @value{GDBN} Command Files.
+@xref{Command Files,, Command files}.
+
+You can control how @value{GDBN} evaluates these files with the following
+setting:
+
+@table @code
+@kindex set script-extension
+@kindex show script-extension
+@item set script-extension off
+All scripts are always evaluated as @value{GDBN} Command Files.
+
+@item set script-extension soft
+The debugger determines the scripting language based on filename
+extension. If this scripting language is supported, @value{GDBN}
+evaluates the script using that language. Otherwise, it evaluates
+the file as a @value{GDBN} Command File.
+
+@item set script-extension strict
+The debugger determines the scripting language based on filename
+extension, and evaluates the script using that language. If the
+language is not supported, then the evaluation fails.
+
+@item show script-extension
+Display the current value of the @code{script-extension} option.
+
+@end table
+
@menu
* Sequences:: Canned Sequences of Commands
* Python:: Scripting @value{GDBN} using Python
terminal.
You can request the execution of a command file with the @code{source}
-command:
+command. Note that the @code{source} command is also used to evaluate
+scripts that are not Command Files. The exact behavior can be configured
+using the @code{script-extension} setting.
+@xref{Extending GDB,, Extending GDB}.
@table @code
@kindex source
@cindex execute commands from a file
-@item source [@code{-v}] @var{filename}
+@item source [-s] [-v] @var{filename}
Execute the command file @var{filename}.
@end table
printed as they are executed. An error in any command terminates
execution of the command file and control is returned to the console.
-@value{GDBN} searches for @var{filename} in the current directory and then
-on the search path (specified with the @samp{directory} command).
+@value{GDBN} first searches for @var{filename} in the current directory.
+If the file is not found there, and @var{filename} does not specify a
+directory, then @value{GDBN} also looks for the file on the source search path
+(specified with the @samp{directory} command);
+except that @file{$cdir} is not searched because the compilation directory
+is not relevant to scripts.
+
+If @code{-s} is specified, then @value{GDBN} searches for @var{filename}
+on the search path even if @var{filename} specifies a directory.
+The search is done by appending @var{filename} to each element of the
+search path. So, for example, if @var{filename} is @file{mylib/myscript}
+and the search path contains @file{/home/user} then @value{GDBN} will
+look for the script @file{/home/user/mylib/myscript}.
+The search is also done if @var{filename} is an absolute path.
+For example, if @var{filename} is @file{/tmp/myscript} and
+the search path contains @file{/home/user} then @value{GDBN} will
+look for the script @file{/home/user/tmp/myscript}.
+For DOS-like systems, if @var{filename} contains a drive specification,
+it is stripped before concatenation. For example, if @var{filename} is
+@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN}
+will look for the script @file{c:/tmp/myscript}.
If @code{-v}, for verbose mode, is given then @value{GDBN} displays
each command as it is executed. The option must be given before
disabled.
@end table
+It is also possible to execute a Python script from the @value{GDBN}
+interpreter:
+
+@table @code
+@item source @file{script-name}
+The script name must end with @samp{.py} and @value{GDBN} must be configured
+to recognize the script language based on filename extension using
+the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
+
+@item python execfile ("script-name")
+This method is based on the @code{execfile} Python built-in function,
+and thus is always available.
+@end table
+
@node Python API
@subsection Python API
@cindex python api
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
* Commands In Python:: Implementing new commands in Python.
* Functions In Python:: Writing new convenience functions.
+* Progspaces In Python:: Program spaces.
* Objfiles In Python:: Object files.
-* Frames In Python:: Acessing inferior stack frames from Python.
+* Frames In Python:: Accessing inferior stack frames from Python.
+* Blocks In Python:: Accessing frame blocks from Python.
+* Symbols In Python:: Python representation of symbols.
+* Symbol Tables In Python:: Python representation of symbol tables.
+* Lazy Strings In Python:: Python representation of lazy strings.
+* Breakpoints In Python:: Manipulating breakpoints using Python.
@end menu
@node Basic Python
It must be a boolean value. If omitted, it defaults to @code{False}.
@end defun
+@findex gdb.breakpoints
+@defun breakpoints
+Return a sequence holding all of @value{GDBN}'s breakpoints.
+@xref{Breakpoints In Python}, for more information.
+@end defun
+
@findex gdb.parameter
@defun parameter parameter
Return the value of a @value{GDBN} parameter. @var{parameter} is a
@code{gdb.Value} (@pxref{Values From Inferior}).
@end defun
+@findex gdb.parse_and_eval
+@defun parse_and_eval expression
+Parse @var{expression} as an expression in the current language,
+evaluate it, and return the result as a @code{gdb.Value}.
+@var{expression} must be a string.
+
+This function can be useful when implementing a new command
+(@pxref{Commands In Python}), as it provides a way to parse the
+command's argument as an expression. It is also useful simply to
+compute values, for example, it is the only way to get the value of a
+convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
+@end defun
+
@findex gdb.write
@defun write string
Print a string to @value{GDBN}'s paginated standard output stream.
function.
@end defun
+@findex gdb.target_charset
+@defun target_charset
+Return the name of the current target character set (@pxref{Character
+Sets}). This differs from @code{gdb.parameter('target-charset')} in
+that @samp{auto} is never returned.
+@end defun
+
+@findex gdb.target_wide_charset
+@defun target_wide_charset
+Return the name of the current target wide character set
+(@pxref{Character Sets}). This differs from
+@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
+never returned.
+@end defun
+
@node Exception Handling
@subsubsection Exception Handling
@cindex python exceptions
If this file does not exist, and if the parameter
@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
-then @value{GDBN} will use the file named
-@file{@var{debug-file-directory}/@var{real-name}}, where
+then @value{GDBN} will use for its each separated directory component
+@code{component} the file named @file{@code{component}/@var{real-name}}, where
@var{real-name} is the object file's real name, as described above.
Finally, if this file does not exist, then @value{GDBN} will look for
@item maint set python auto-load [yes|no]
Enable or disable the Python auto-loading feature.
-@kindex show python auto-load
-@item show python auto-load
+@kindex maint show python auto-load
+@item maint show python auto-load
Show whether Python auto-loading is enabled or disabled.
@end table
The following methods are provided:
@table @code
+@defmethod Value cast type
+Return a new instance of @code{gdb.Value} that is the result of
+casting this instance to the type described by @var{type}, which must
+be a @code{gdb.Type} object. If the cast cannot be performed for some
+reason, this method throws an exception.
+@end defmethod
+
@defmethod Value dereference
For pointer data types, this method returns a new @code{gdb.Value} object
whose contents is the object pointed to by the pointer. For example, if
If the optional @var{length} argument is given, the string will be
fetched and converted to the given length.
@end defmethod
+
+@defmethod Value lazy_string @r{[}encoding@r{]} @r{[}length@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
+In Python}). Otherwise, this method will throw an exception.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the @code{gdb.LazyString}. Some examples are:
+@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
+@var{encoding} argument is an encoding that @value{GDBN} does
+recognize, @value{GDBN} will raise an error.
+
+When a lazy string is printed, the @value{GDBN} encoding machinery is
+used to convert the string during printing. If the optional
+@var{encoding} argument is not provided, or is an empty string,
+@value{GDBN} will automatically select the encoding most suitable for
+the string type. For further information on encoding in @value{GDBN}
+please see @ref{Character Sets}.
+
+If the optional @var{length} argument is given, the string will be
+fetched and encoded to the length of characters specified. If
+the @var{length} argument is not provided, the string will be fetched
+and encoded until a null of appropriate width is found.
+@end defmethod
@end table
@node Types In Python
This function looks up a type by name. @var{name} is the name of the
type to look up. It must be a string.
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
+
Ordinarily, this function will return an instance of @code{gdb.Type}.
If the named type cannot be found, it will throw an exception.
@end defun
it was provided by the compiler and not the user. This attribute is
always provided, and is @code{False} if the field is not artificial.
+@item is_base_class
+This is @code{True} if the field represents a base class of a C@t{++}
+structure. This attribute is always provided, and is @code{False}
+if the field is not a base class of the type that is the argument of
+@code{fields}, or if that type was not a C@t{++} class.
+
@item bitsize
If the field is packed, or is a bitfield, then this will have a
non-zero value, which is the size of the field in bits. Otherwise,
@code{volatile}.
@end defmethod
+@defmethod Type range
+Return a Python @code{Tuple} object that contains two elements: the
+low bound of the argument type and the high bound of that type. If
+the type does not have a range, @value{GDBN} will raise a
+@code{RuntimeError} exception.
+@end defmethod
+
@defmethod Type reference
Return a new @code{gdb.Type} object which represents a reference to this
type.
@end defmethod
+@defmethod Type pointer
+Return a new @code{gdb.Type} object which represents a pointer to this
+type.
+@end defmethod
+
@defmethod Type strip_typedefs
Return a new @code{gdb.Type} that represents the real type,
after removing all layers of typedefs.
exception.
@end defmethod
-@defmethod Type template_argument n
+@defmethod Type template_argument n [block]
If this @code{gdb.Type} is an instantiation of a template, this will
return a new @code{gdb.Type} which represents the type of the
@var{n}th template argument.
If this @code{gdb.Type} is not a template type, this will throw an
exception. Ordinarily, only C@t{++} code will have template types.
-@var{name} is searched for globally.
+If @var{block} is given, then @var{name} is looked up in that scope.
+Otherwise, it is searched for globally.
@end defmethod
@end table
pretty-printer. Python scalars (integers, floats, and booleans) and
strings are convertible to @code{gdb.Value}; other types are not.
+Finally, if this method returns @code{None} then no further operations
+are peformed in this method and nothing is printed.
+
If the result is not one of these types, an exception is raised.
@end defop
The Python list @code{gdb.pretty_printers} contains an array of
functions that have been registered via addition as a pretty-printer.
+Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
Each @code{gdb.Objfile} also contains a @code{pretty_printers}
attribute.
@code{None}.
@value{GDBN} first checks the @code{pretty_printers} attribute of each
-@code{gdb.Objfile} and iteratively calls each function in the list for
-that @code{gdb.Objfile} until it receives a pretty-printer object.
+@code{gdb.Objfile} in the current program space and iteratively calls
+each function in the list for that @code{gdb.Objfile} until it receives
+a pretty-printer object.
+If no pretty-printer is found in the objfile lists, @value{GDBN} then
+searches the pretty-printer list of the current program space,
+calling each function until an object is returned.
After these lists have been exhausted, it tries the global
@code{gdb.pretty-printers} list, again calling each function until an
object is returned.
Python code is read into @value{GDBN}, you may need to import the
@code{gdb} module explicitly.
+@node Progspaces In Python
+@subsubsection Program Spaces In Python
+
+@cindex progspaces in python
+@tindex gdb.Progspace
+@tindex Progspace
+A program space, or @dfn{progspace}, represents a symbolic view
+of an address space.
+It consists of all of the objfiles of the program.
+@xref{Objfiles In Python}.
+@xref{Inferiors and Programs, program spaces}, for more details
+about program spaces.
+
+The following progspace-related functions are available in the
+@code{gdb} module:
+
+@findex gdb.current_progspace
+@defun current_progspace
+This function returns the program space of the currently selected inferior.
+@xref{Inferiors and Programs}.
+@end defun
+
+@findex gdb.progspaces
+@defun progspaces
+Return a sequence of all the progspaces currently known to @value{GDBN}.
+@end defun
+
+Each progspace is represented by an instance of the @code{gdb.Progspace}
+class.
+
+@defivar Progspace filename
+The file name of the progspace as a string.
+@end defivar
+
+@defivar Progspace pretty_printers
+The @code{pretty_printers} attribute is a list of functions. It is
+used to look up pretty-printers. A @code{Value} is passed to each
+function in order; if the function returns @code{None}, then the
+search continues. Otherwise, the return value should be an object
+which is used to format the value. @xref{Pretty Printing}, for more
+information.
+@end defivar
+
@node Objfiles In Python
@subsubsection Objfiles In Python
@end defivar
@node Frames In Python
-@subsubsection Acessing inferior stack frames from Python.
+@subsubsection Accessing inferior stack frames from Python.
@cindex frames in python
When the debugged program stops, @value{GDBN} is able to analyze its call
Returns the frame's resume address.
@end defmethod
+@defmethod Frame block
+Return the frame's code block. @xref{Blocks In Python}.
+@end defmethod
+
+@defmethod Frame function
+Return the symbol for the function corresponding to this frame.
+@xref{Symbols In Python}.
+@end defmethod
+
@defmethod Frame older
Return the frame that called this frame.
@end defmethod
Return the frame called by this frame.
@end defmethod
-@defmethod Frame read_var variable
-Return the value of the given variable in this frame. @var{variable} must
-be a string.
+@defmethod Frame find_sal
+Return the frame's symtab and line object.
+@xref{Symbol Tables In Python}.
+@end defmethod
+
+@defmethod Frame read_var variable @r{[}block@r{]}
+Return the value of @var{variable} in this frame. If the optional
+argument @var{block} is provided, search for the variable from that
+block; otherwise start at the frame's current block (which is
+determined by the frame's current program counter). @var{variable}
+must be a string or a @code{gdb.Symbol} object. @var{block} must be a
+@code{gdb.Block} object.
+@end defmethod
+
+@defmethod Frame select
+Set this frame to be the selected frame. @xref{Stack, ,Examining the
+Stack}.
@end defmethod
@end table
-@node Interpreters
-@chapter Command Interpreters
-@cindex command interpreters
+@node Blocks In Python
+@subsubsection Accessing frame blocks from Python.
-@value{GDBN} supports multiple command interpreters, and some command
-infrastructure to allow users or user interface writers to switch
-between interpreters or run commands in other interpreters.
+@cindex blocks in python
+@tindex gdb.Block
-@value{GDBN} currently supports two command interpreters, the console
-interpreter (sometimes called the command-line interpreter or @sc{cli})
-and the machine interface interpreter (or @sc{gdb/mi}). This manual
-describes both of these interfaces in great detail.
+Within each frame, @value{GDBN} maintains information on each block
+stored in that frame. These blocks are organized hierarchically, and
+are represented individually in Python as a @code{gdb.Block}.
+Please see @ref{Frames In Python}, for a more in-depth discussion on
+frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
+detailed technical information on @value{GDBN}'s book-keeping of the
+stack.
-By default, @value{GDBN} will start with the console interpreter.
-However, the user may choose to start @value{GDBN} with another
-interpreter by specifying the @option{-i} or @option{--interpreter}
-startup options. Defined interpreters include:
+The following block-related functions are available in the @code{gdb}
+module:
-@table @code
-@item console
-@cindex console interpreter
-The traditional console or command-line interpreter. This is the most often
-used interpreter with @value{GDBN}. With no interpreter specified at runtime,
-@value{GDBN} will use this interpreter.
+@findex gdb.block_for_pc
+@defun block_for_pc pc
+Return the @code{gdb.Block} containing the given @var{pc} value. If the
+block cannot be found for the @var{pc} value specified, the function
+will return @code{None}.
+@end defun
-@item mi
-@cindex mi interpreter
-The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
-by programs wishing to use @value{GDBN} as a backend for a debugger GUI
-or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
-Interface}.
+A @code{gdb.Block} object has the following attributes:
-@item mi2
-@cindex mi2 interpreter
-The current @sc{gdb/mi} interface.
+@table @code
+@defivar Block start
+The start address of the block. This attribute is not writable.
+@end defivar
-@item mi1
-@cindex mi1 interpreter
-The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
+@defivar Block end
+The end address of the block. This attribute is not writable.
+@end defivar
+
+@defivar Block function
+The name of the block represented as a @code{gdb.Symbol}. If the
+block is not named, then this attribute holds @code{None}. This
+attribute is not writable.
+@end defivar
+@defivar Block superblock
+The block containing this block. If this parent block does not exist,
+this attribute holds @code{None}. This attribute is not writable.
+@end defivar
@end table
-@cindex invoke another interpreter
-The interpreter being used by @value{GDBN} may not be dynamically
-switched at runtime. Although possible, this could lead to a very
-precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
-enters the command "interpreter-set console" in a console view,
-@value{GDBN} would switch to using the console interpreter, rendering
-the IDE inoperable!
+@node Symbols In Python
+@subsubsection Python representation of Symbols.
-@kindex interpreter-exec
-Although you may only choose a single interpreter at startup, you may execute
-commands in any interpreter from the current interpreter using the appropriate
-command. If you are running the console interpreter, simply use the
-@code{interpreter-exec} command:
+@cindex symbols in python
+@tindex gdb.Symbol
-@smallexample
-interpreter-exec mi "-data-list-register-names"
-@end smallexample
+@value{GDBN} represents every variable, function and type as an
+entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
+Similarly, Python represents these symbols in @value{GDBN} with the
+@code{gdb.Symbol} object.
-@sc{gdb/mi} has a similar command, although it is only available in versions of
-@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
+The following symbol-related functions are available in the @code{gdb}
+module:
-@node TUI
-@chapter @value{GDBN} Text User Interface
-@cindex TUI
-@cindex Text User Interface
+@findex gdb.lookup_symbol
+@defun lookup_symbol name [block] [domain]
+This function searches for a symbol by name. The search scope can be
+restricted to the parameters defined in the optional domain and block
+arguments.
+
+@var{name} is the name of the symbol. It must be a string. The
+optional @var{block} argument restricts the search to symbols visible
+in that @var{block}. The @var{block} argument must be a
+@code{gdb.Block} object. The optional @var{domain} argument restricts
+the search to the domain type. The @var{domain} argument must be a
+domain constant defined in the @code{gdb} module and described later
+in this chapter.
+@end defun
-@menu
-* TUI Overview:: TUI overview
-* TUI Keys:: TUI key bindings
-* TUI Single Key Mode:: TUI single key mode
-* TUI Commands:: TUI-specific commands
-* TUI Configuration:: TUI configuration variables
-@end menu
+A @code{gdb.Symbol} object has the following attributes:
-The @value{GDBN} Text User Interface (TUI) is a terminal
-interface which uses the @code{curses} library to show the source
-file, the assembly output, the program registers and @value{GDBN}
-commands in separate text windows. The TUI mode is supported only
-on platforms where a suitable version of the @code{curses} library
-is available.
+@table @code
+@defivar Symbol symtab
+The symbol table in which the symbol appears. This attribute is
+represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
+Python}. This attribute is not writable.
+@end defivar
-@pindex @value{GDBTUI}
-The TUI mode is enabled by default when you invoke @value{GDBN} as
-either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
-You can also switch in and out of TUI mode while @value{GDBN} runs by
-using various TUI commands and key bindings, such as @kbd{C-x C-a}.
-@xref{TUI Keys, ,TUI Key Bindings}.
+@defivar Symbol name
+The name of the symbol as a string. This attribute is not writable.
+@end defivar
-@node TUI Overview
-@section TUI Overview
+@defivar Symbol linkage_name
+The name of the symbol, as used by the linker (i.e., may be mangled).
+This attribute is not writable.
+@end defivar
-In TUI mode, @value{GDBN} can display several text windows:
+@defivar Symbol print_name
+The name of the symbol in a form suitable for output. This is either
+@code{name} or @code{linkage_name}, depending on whether the user
+asked @value{GDBN} to display demangled or mangled names.
+@end defivar
-@table @emph
-@item command
-This window is the @value{GDBN} command window with the @value{GDBN}
-prompt and the @value{GDBN} output. The @value{GDBN} input is still
-managed using readline.
+@defivar Symbol addr_class
+The address class of the symbol. This classifies how to find the value
+of a symbol. Each address class is a constant defined in the
+@code{gdb} module and described later in this chapter.
+@end defivar
-@item source
-The source window shows the source file of the program. The current
-line and active breakpoints are displayed in this window.
+@defivar Symbol is_argument
+@code{True} if the symbol is an argument of a function.
+@end defivar
-@item assembly
-The assembly window shows the disassembly output of the program.
+@defivar Symbol is_constant
+@code{True} if the symbol is a constant.
+@end defivar
-@item register
-This window shows the processor registers. Registers are highlighted
-when their values change.
+@defivar Symbol is_function
+@code{True} if the symbol is a function or a method.
+@end defivar
+
+@defivar Symbol is_variable
+@code{True} if the symbol is a variable.
+@end defivar
@end table
-The source and assembly windows show the current program position
-by highlighting the current line and marking it with a @samp{>} marker.
-Breakpoints are indicated with two markers. The first marker
-indicates the breakpoint type:
+The available domain categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_UNDEF_DOMAIN
+@findex gdb.SYMBOL_UNDEF_DOMAIN
+@item SYMBOL_UNDEF_DOMAIN
+This is used when a domain has not been discovered or none of the
+following domains apply. This usually indicates an error either
+in the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_VAR_DOMAIN
+@findex gdb.SYMBOL_VAR_DOMAIN
+@item SYMBOL_VAR_DOMAIN
+This domain contains variables, function names, typedef names and enum
+type values.
+@findex SYMBOL_STRUCT_DOMAIN
+@findex gdb.SYMBOL_STRUCT_DOMAIN
+@item SYMBOL_STRUCT_DOMAIN
+This domain holds struct, union and enum type names.
+@findex SYMBOL_LABEL_DOMAIN
+@findex gdb.SYMBOL_LABEL_DOMAIN
+@item SYMBOL_LABEL_DOMAIN
+This domain contains names of labels (for gotos).
+@findex SYMBOL_VARIABLES_DOMAIN
+@findex gdb.SYMBOL_VARIABLES_DOMAIN
+@item SYMBOL_VARIABLES_DOMAIN
+This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
+contains everything minus functions and types.
+@findex SYMBOL_FUNCTIONS_DOMAIN
+@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains all functions.
+@findex SYMBOL_TYPES_DOMAIN
+@findex gdb.SYMBOL_TYPES_DOMAIN
+@item SYMBOL_TYPES_DOMAIN
+This domain contains all types.
+@end table
+
+The available address class categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_LOC_UNDEF
+@findex gdb.SYMBOL_LOC_UNDEF
+@item SYMBOL_LOC_UNDEF
+If this is returned by address class, it indicates an error either in
+the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_LOC_CONST
+@findex gdb.SYMBOL_LOC_CONST
+@item SYMBOL_LOC_CONST
+Value is constant int.
+@findex SYMBOL_LOC_STATIC
+@findex gdb.SYMBOL_LOC_STATIC
+@item SYMBOL_LOC_STATIC
+Value is at a fixed address.
+@findex SYMBOL_LOC_REGISTER
+@findex gdb.SYMBOL_LOC_REGISTER
+@item SYMBOL_LOC_REGISTER
+Value is in a register.
+@findex SYMBOL_LOC_ARG
+@findex gdb.SYMBOL_LOC_ARG
+@item SYMBOL_LOC_ARG
+Value is an argument. This value is at the offset stored within the
+symbol inside the frame's argument list.
+@findex SYMBOL_LOC_REF_ARG
+@findex gdb.SYMBOL_LOC_REF_ARG
+@item SYMBOL_LOC_REF_ARG
+Value address is stored in the frame's argument list. Just like
+@code{LOC_ARG} except that the value's address is stored at the
+offset, not the value itself.
+@findex SYMBOL_LOC_REGPARM_ADDR
+@findex gdb.SYMBOL_LOC_REGPARM_ADDR
+@item SYMBOL_LOC_REGPARM_ADDR
+Value is a specified register. Just like @code{LOC_REGISTER} except
+the register holds the address of the argument instead of the argument
+itself.
+@findex SYMBOL_LOC_LOCAL
+@findex gdb.SYMBOL_LOC_LOCAL
+@item SYMBOL_LOC_LOCAL
+Value is a local variable.
+@findex SYMBOL_LOC_TYPEDEF
+@findex gdb.SYMBOL_LOC_TYPEDEF
+@item SYMBOL_LOC_TYPEDEF
+Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
+have this class.
+@findex SYMBOL_LOC_BLOCK
+@findex gdb.SYMBOL_LOC_BLOCK
+@item SYMBOL_LOC_BLOCK
+Value is a block.
+@findex SYMBOL_LOC_CONST_BYTES
+@findex gdb.SYMBOL_LOC_CONST_BYTES
+@item SYMBOL_LOC_CONST_BYTES
+Value is a byte-sequence.
+@findex SYMBOL_LOC_UNRESOLVED
+@findex gdb.SYMBOL_LOC_UNRESOLVED
+@item SYMBOL_LOC_UNRESOLVED
+Value is at a fixed address, but the address of the variable has to be
+determined from the minimal symbol table whenever the variable is
+referenced.
+@findex SYMBOL_LOC_OPTIMIZED_OUT
+@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
+@item SYMBOL_LOC_OPTIMIZED_OUT
+The value does not actually exist in the program.
+@findex SYMBOL_LOC_COMPUTED
+@findex gdb.SYMBOL_LOC_COMPUTED
+@item SYMBOL_LOC_COMPUTED
+The value's address is a computed location.
+@end table
+
+@node Symbol Tables In Python
+@subsubsection Symbol table representation in Python.
+
+@cindex symbol tables in python
+@tindex gdb.Symtab
+@tindex gdb.Symtab_and_line
+
+Access to symbol table data maintained by @value{GDBN} on the inferior
+is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
+@code{gdb.Symtab}. Symbol table and line data for a frame is returned
+from the @code{find_sal} method in @code{gdb.Frame} object.
+@xref{Frames In Python}.
+
+For more information on @value{GDBN}'s symbol table management, see
+@ref{Symbols, ,Examining the Symbol Table}, for more information.
+
+A @code{gdb.Symtab_and_line} object has the following attributes:
+
+@table @code
+@defivar Symtab_and_line symtab
+The symbol table object (@code{gdb.Symtab}) for this frame.
+This attribute is not writable.
+@end defivar
-@table @code
-@item B
-Breakpoint which was hit at least once.
+@defivar Symtab_and_line pc
+Indicates the current program counter address. This attribute is not
+writable.
+@end defivar
+
+@defivar Symtab_and_line line
+Indicates the current line number for this object. This
+attribute is not writable.
+@end defivar
+@end table
+
+A @code{gdb.Symtab} object has the following attributes:
+
+@table @code
+@defivar Symtab filename
+The symbol table's source filename. This attribute is not writable.
+@end defivar
+
+@defivar Symtab objfile
+The symbol table's backing object file. @xref{Objfiles In Python}.
+This attribute is not writable.
+@end defivar
+@end table
+
+The following methods are provided:
+
+@table @code
+@defmethod Symtab fullname
+Return the symbol table's source absolute file name.
+@end defmethod
+@end table
+
+@node Breakpoints In Python
+@subsubsection Manipulating breakpoints using Python
+
+@cindex breakpoints in python
+@tindex gdb.Breakpoint
+
+Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
+class.
+
+@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]}
+Create a new breakpoint. @var{spec} is a string naming the
+location of the breakpoint, or an expression that defines a
+watchpoint. The contents can be any location recognized by the
+@code{break} command, or in the case of a watchpoint, by the @code{watch}
+command. The optional @var{type} denotes the breakpoint to create
+from the types defined later in this chapter. This argument can be
+either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. @var{type}
+defaults to @code{BP_BREAKPOINT}. The optional @var{wp_class}
+argument defines the class of watchpoint to create, if @var{type} is
+defined as @code{BP_WATCHPOINT}. If a watchpoint class is not
+provided, it is assumed to be a @var{WP_WRITE} class.
+@end defmethod
+
+The available watchpoint types represented by constants are defined in the
+@code{gdb} module:
+
+@table @code
+@findex WP_READ
+@findex gdb.WP_READ
+@item WP_READ
+Read only watchpoint.
+
+@findex WP_WRITE
+@findex gdb.WP_WRITE
+@item WP_WRITE
+Write only watchpoint.
+
+@findex WP_ACCESS
+@findex gdb.WP_ACCESS
+@item WP_ACCESS
+Read/Write watchpoint.
+@end table
+
+@defmethod Breakpoint is_valid
+Return @code{True} if this @code{Breakpoint} object is valid,
+@code{False} otherwise. A @code{Breakpoint} object can become invalid
+if the user deletes the breakpoint. In this case, the object still
+exists, but the underlying breakpoint does not. In the cases of
+watchpoint scope, the watchpoint remains valid even if execution of the
+inferior leaves the scope of that watchpoint.
+@end defmethod
+
+@defivar Breakpoint enabled
+This attribute is @code{True} if the breakpoint is enabled, and
+@code{False} otherwise. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint silent
+This attribute is @code{True} if the breakpoint is silent, and
+@code{False} otherwise. This attribute is writable.
+
+Note that a breakpoint can also be silent if it has commands and the
+first command is @code{silent}. This is not reported by the
+@code{silent} attribute.
+@end defivar
+
+@defivar Breakpoint thread
+If the breakpoint is thread-specific, this attribute holds the thread
+id. If the breakpoint is not thread-specific, this attribute is
+@code{None}. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint task
+If the breakpoint is Ada task-specific, this attribute holds the Ada task
+id. If the breakpoint is not task-specific (or the underlying
+language is not Ada), this attribute is @code{None}. This attribute
+is writable.
+@end defivar
+
+@defivar Breakpoint ignore_count
+This attribute holds the ignore count for the breakpoint, an integer.
+This attribute is writable.
+@end defivar
+
+@defivar Breakpoint number
+This attribute holds the breakpoint's number --- the identifier used by
+the user to manipulate the breakpoint. This attribute is not writable.
+@end defivar
+
+@defivar Breakpoint type
+This attribute holds the breakpoint's type --- the identifier used to
+determine the actual breakpoint type or use-case. This attribute is not
+writable.
+@end defivar
+
+The available types are represented by constants defined in the @code{gdb}
+module:
+
+@table @code
+@findex BP_BREAKPOINT
+@findex gdb.BP_BREAKPOINT
+@item BP_BREAKPOINT
+Normal code breakpoint.
+
+@findex BP_WATCHPOINT
+@findex gdb.BP_WATCHPOINT
+@item BP_WATCHPOINT
+Watchpoint breakpoint.
+
+@findex BP_HARDWARE_WATCHPOINT
+@findex gdb.BP_HARDWARE_WATCHPOINT
+@item BP_HARDWARE_WATCHPOINT
+Hardware assisted watchpoint.
+
+@findex BP_READ_WATCHPOINT
+@findex gdb.BP_READ_WATCHPOINT
+@item BP_READ_WATCHPOINT
+Hardware assisted read watchpoint.
+
+@findex BP_ACCESS_WATCHPOINT
+@findex gdb.BP_ACCESS_WATCHPOINT
+@item BP_ACCESS_WATCHPOINT
+Hardware assisted access watchpoint.
+@end table
+
+@defivar Breakpoint hit_count
+This attribute holds the hit count for the breakpoint, an integer.
+This attribute is writable, but currently it can only be set to zero.
+@end defivar
+
+@defivar Breakpoint location
+This attribute holds the location of the breakpoint, as specified by
+the user. It is a string. If the breakpoint does not have a location
+(that is, it is a watchpoint) the attribute's value is @code{None}. This
+attribute is not writable.
+@end defivar
+
+@defivar Breakpoint expression
+This attribute holds a breakpoint expression, as specified by
+the user. It is a string. If the breakpoint does not have an
+expression (the breakpoint is not a watchpoint) the attribute's value
+is @code{None}. This attribute is not writable.
+@end defivar
+
+@defivar Breakpoint condition
+This attribute holds the condition of the breakpoint, as specified by
+the user. It is a string. If there is no condition, this attribute's
+value is @code{None}. This attribute is writable.
+@end defivar
+
+@defivar Breakpoint commands
+This attribute holds the commands attached to the breakpoint. If
+there are commands, this attribute's value is a string holding all the
+commands, separated by newlines. If there are no commands, this
+attribute is @code{None}. This attribute is not writable.
+@end defivar
+
+@node Lazy Strings In Python
+@subsubsection Python representation of lazy strings.
+
+@cindex lazy strings in python
+@tindex gdb.LazyString
+
+A @dfn{lazy string} is a string whose contents is not retrieved or
+encoded until it is needed.
+
+A @code{gdb.LazyString} is represented in @value{GDBN} as an
+@code{address} that points to a region of memory, an @code{encoding}
+that will be used to encode that region of memory, and a @code{length}
+to delimit the region of memory that represents the string. The
+difference between a @code{gdb.LazyString} and a string wrapped within
+a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
+differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
+retrieved and encoded during printing, while a @code{gdb.Value}
+wrapping a string is immediately retrieved and encoded on creation.
+
+A @code{gdb.LazyString} object has the following functions:
+
+@defmethod LazyString value
+Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
+will point to the string in memory, but will lose all the delayed
+retrieval, encoding and handling that @value{GDBN} applies to a
+@code{gdb.LazyString}.
+@end defmethod
+
+@defivar LazyString address
+This attribute holds the address of the string. This attribute is not
+writable.
+@end defivar
+
+@defivar LazyString length
+This attribute holds the length of the string in characters. If the
+length is -1, then the string will be fetched and encoded up to the
+first null of appropriate width. This attribute is not writable.
+@end defivar
+
+@defivar LazyString encoding
+This attribute holds the encoding that will be applied to the string
+when the string is printed by @value{GDBN}. If the encoding is not
+set, or contains an empty string, then @value{GDBN} will select the
+most appropriate encoding when the string is printed. This attribute
+is not writable.
+@end defivar
+
+@defivar LazyString type
+This attribute holds the type that is represented by the lazy string's
+type. For a lazy string this will always be a pointer type. To
+resolve this to the lazy string's character type, use the type's
+@code{target} method. @xref{Types In Python}. This attribute is not
+writable.
+@end defivar
+
+@node Interpreters
+@chapter Command Interpreters
+@cindex command interpreters
+
+@value{GDBN} supports multiple command interpreters, and some command
+infrastructure to allow users or user interface writers to switch
+between interpreters or run commands in other interpreters.
+
+@value{GDBN} currently supports two command interpreters, the console
+interpreter (sometimes called the command-line interpreter or @sc{cli})
+and the machine interface interpreter (or @sc{gdb/mi}). This manual
+describes both of these interfaces in great detail.
+
+By default, @value{GDBN} will start with the console interpreter.
+However, the user may choose to start @value{GDBN} with another
+interpreter by specifying the @option{-i} or @option{--interpreter}
+startup options. Defined interpreters include:
+
+@table @code
+@item console
+@cindex console interpreter
+The traditional console or command-line interpreter. This is the most often
+used interpreter with @value{GDBN}. With no interpreter specified at runtime,
+@value{GDBN} will use this interpreter.
+
+@item mi
+@cindex mi interpreter
+The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
+by programs wishing to use @value{GDBN} as a backend for a debugger GUI
+or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
+Interface}.
+
+@item mi2
+@cindex mi2 interpreter
+The current @sc{gdb/mi} interface.
+
+@item mi1
+@cindex mi1 interpreter
+The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
+
+@end table
+
+@cindex invoke another interpreter
+The interpreter being used by @value{GDBN} may not be dynamically
+switched at runtime. Although possible, this could lead to a very
+precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
+enters the command "interpreter-set console" in a console view,
+@value{GDBN} would switch to using the console interpreter, rendering
+the IDE inoperable!
+
+@kindex interpreter-exec
+Although you may only choose a single interpreter at startup, you may execute
+commands in any interpreter from the current interpreter using the appropriate
+command. If you are running the console interpreter, simply use the
+@code{interpreter-exec} command:
+
+@smallexample
+interpreter-exec mi "-data-list-register-names"
+@end smallexample
+
+@sc{gdb/mi} has a similar command, although it is only available in versions of
+@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
+
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex TUI
+@cindex Text User Interface
+
+@menu
+* TUI Overview:: TUI overview
+* TUI Keys:: TUI key bindings
+* TUI Single Key Mode:: TUI single key mode
+* TUI Commands:: TUI-specific commands
+* TUI Configuration:: TUI configuration variables
+@end menu
+
+The @value{GDBN} Text User Interface (TUI) is a terminal
+interface which uses the @code{curses} library to show the source
+file, the assembly output, the program registers and @value{GDBN}
+commands in separate text windows. The TUI mode is supported only
+on platforms where a suitable version of the @code{curses} library
+is available.
+
+@pindex @value{GDBTUI}
+The TUI mode is enabled by default when you invoke @value{GDBN} as
+either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
+You can also switch in and out of TUI mode while @value{GDBN} runs by
+using various TUI commands and key bindings, such as @kbd{C-x C-a}.
+@xref{TUI Keys, ,TUI Key Bindings}.
+
+@node TUI Overview
+@section TUI Overview
+
+In TUI mode, @value{GDBN} can display several text windows:
+
+@table @emph
+@item command
+This window is the @value{GDBN} command window with the @value{GDBN}
+prompt and the @value{GDBN} output. The @value{GDBN} input is still
+managed using readline.
+
+@item source
+The source window shows the source file of the program. The current
+line and active breakpoints are displayed in this window.
+
+@item assembly
+The assembly window shows the disassembly output of the program.
+
+@item register
+This window shows the processor registers. Registers are highlighted
+when their values change.
+@end table
+
+The source and assembly windows show the current program position
+by highlighting the current line and marking it with a @samp{>} marker.
+Breakpoints are indicated with two markers. The first marker
+indicates the breakpoint type:
+
+@table @code
+@item B
+Breakpoint which was hit at least once.
@item b
Breakpoint which was never hit.
the TUI mode. When @value{GDBN} is in the standard mode, most
of these commands will automatically switch to the TUI mode.
+Note that if @value{GDBN}'s @code{stdout} is not connected to a
+terminal, or @value{GDBN} has been started with the machine interface
+interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of
+these commands will fail with an error, because it would not be
+possible or desirable to enable curses window management.
+
@table @code
@item info win
@kindex info win
In general, the content of a thread group may be only retrieved only
after attaching to that thread group.
+Thread groups are related to inferiors (@pxref{Inferiors and
+Programs}). Each inferior corresponds to a thread group of a special
+type @samp{process}, and some additional operations are permitted on
+such thread groups.
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Command Syntax
@section @sc{gdb/mi} Command Syntax
* GDB/MI Stream Records::
* GDB/MI Async Records::
* GDB/MI Frame Information::
+* GDB/MI Thread Information::
@end menu
@node GDB/MI Result Records
@item "^running"
@findex ^running
-@c Is this one correct? Should it be an out-of-band notification?
-The asynchronous operation was successfully started. The target is
-running.
+This result record is equivalent to @samp{^done}. Historically, it
+was output instead of @samp{^done} if the command has resumed the
+target. This behaviour is maintained for backward compatibility, but
+all frontends should treat @samp{^done} and @samp{^running}
+identically and rely on the @samp{*running} output record to determine
+which threads are resumed.
@item "^connected"
@findex ^connected
all threads together, or even for a single thread, if the thread must
be stepped though some code before letting it run freely.
-@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}"
+@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
The target has stopped. The @var{reason} field can have one of the
following values:
value of @code{"all"}. Otherwise, the value of the @var{stopped}
field will be a list of thread identifiers. Presently, this list will
always include a single thread, but frontend should be prepared to see
-several threads in the list.
+several threads in the list. The @var{core} field reports the
+processor core on which the stop event has happened. This field may be absent
+if such information is not available.
+
+@item =thread-group-added,id="@var{id}"
+@itemx =thread-group-removed,id="@var{id}"
+A thread group was either added or removed. The @var{id} field
+contains the @value{GDBN} identifier of the thread group. When a thread
+group is added, it generally might not be associated with a running
+process. When a thread group is removed, its id becomes invalid and
+cannot be used in any way.
+
+@item =thread-group-started,id="@var{id}",pid="@var{pid}"
+A thread group became associated with a running program,
+either because the program was just started or the thread group
+was attached to a program. The @var{id} field contains the
+@value{GDBN} identifier of the thread group. The @var{pid} field
+contains process identifier, specific to the operating system.
-@item =thread-group-created,id="@var{id}"
@itemx =thread-group-exited,id="@var{id}"
-A thread thread group either was attached to, or has exited/detached
+A thread group is no longer associated with a running program,
+either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
thread group.
library file on the target, and on the host respectively. For native
debugging, both those fields have the same value. The
@var{symbols-loaded} field reports if the debug symbols for this
-library are loaded.
+library are loaded. The @var{thread-group} field, if present,
+specifies the id of the thread group in whose context the library was loaded.
+If the field is absent, it means the library was loaded in the context
+of all present thread groups.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
-the same meaning as for the @code{=library-loaded} notification
+the same meaning as for the @code{=library-loaded} notification.
+The @var{thread-group} field, if present, specifies the id of the
+thread group in whose context the library was unloaded. If the field is
+absent, it means the library was unloaded in the context of all present
+thread groups.
@end table
@end table
+@node GDB/MI Thread Information
+@subsection @sc{gdb/mi} Thread Information
+
+Whenever @value{GDBN} has to report an information about a thread, it
+uses a tuple with the following fields:
+
+@table @code
+@item id
+The numeric id assigned to the thread by @value{GDBN}. This field is
+always present.
+
+@item target-id
+Target-specific string identifying the thread. This field is always present.
+
+@item details
+Additional information about the thread provided by the target.
+It is supposed to be human-readable and not interpreted by the
+frontend. This field is optional.
+
+@item state
+Either @samp{stopped} or @samp{running}, depending on whether the
+thread is presently running. This field is always present.
+
+@item core
+The value of this field is an integer number of the processor core the
+thread was last seen on. This field is optional.
+@end table
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
<- ^exit
@end smallexample
+Please note that @samp{^exit} is printed immediately, but it might
+take some time for @value{GDBN} to actually exit. During that time, @value{GDBN}
+performs necessary cleanups, including killing programs being debugged
+or disconnecting from debug hardware, so the frontend should wait till
+@value{GDBN} exits and should only forcibly kill @value{GDBN} if it
+fails to exit in reasonable time.
+
@subheading A Bad Command
Here's what happens if you pass a non-existent command:
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -f ] [ -d ]
+ -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
[ -p @var{thread} ] [ @var{location} ]
@end smallexample
cannot be parsed.
@item -d
Create a disabled breakpoint.
+@item -a
+Create a tracepoint. @xref{Tracepoints}. When this parameter
+is used together with @samp{-h}, a fast tracepoint is created.
@end table
@subsubheading Result
(gdb)
@end smallexample
+@subheading The @code{-break-passcount} Command
+@findex -break-passcount
+
+@subsubheading Synopsis
+
+@smallexample
+ -break-passcount @var{tracepoint-number} @var{passcount}
+@end smallexample
+
+Set the passcount for tracepoint @var{tracepoint-number} to
+@var{passcount}. If the breakpoint referred to by @var{tracepoint-number}
+is not a tracepoint, error is emitted. This corresponds to CLI
+command @samp{passcount}.
+
@subheading The @code{-break-watch} Command
@findex -break-watch
@subsubheading Synopsis
@smallexample
- -exec-continue [--all|--thread-group N]
+ -exec-continue [--reverse] [--all|--thread-group N]
@end smallexample
-Resumes the execution of the inferior program until a breakpoint is
-encountered, or until the inferior exits. In all-stop mode
-(@pxref{All-Stop Mode}), may resume only one thread, or all threads,
-depending on the value of the @samp{scheduler-locking} variable. In
-non-stop mode (@pxref{Non-Stop Mode}), if the @samp{--all} is not
-specified, only the thread specified with the @samp{--thread} option
-(or current thread, if no @samp{--thread} is provided) is resumed. If
-@samp{--all} is specified, all threads will be resumed. The
-@samp{--all} option is ignored in all-stop mode. If the
-@samp{--thread-group} options is specified, then all threads in that
-thread group are resumed.
+Resumes the execution of the inferior program, which will continue
+to execute until it reaches a debugger stop event. If the
+@samp{--reverse} option is specified, execution resumes in reverse until
+it reaches a stop event. Stop events may include
+@itemize @bullet
+@item
+breakpoints or watchpoints
+@item
+signals or exceptions
+@item
+the end of the process (or its beginning under @samp{--reverse})
+@item
+the end or beginning of a replay log if one is being used.
+@end itemize
+In all-stop mode (@pxref{All-Stop
+Mode}), may resume only one thread, or all threads, depending on the
+value of the @samp{scheduler-locking} variable. If @samp{--all} is
+specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is
+ignored in all-stop mode. If the @samp{--thread-group} options is
+specified, then all threads in that thread group are resumed.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-finish
+ -exec-finish [--reverse]
@end smallexample
Resumes the execution of the inferior program until the current
function is exited. Displays the results returned by the function.
+If the @samp{--reverse} option is specified, resumes the reverse
+execution of the inferior program until the point where current
+function was called.
@subsubheading @value{GDBN} Command
reported after that using the @samp{*stopped} notification.
In non-stop mode, only the context thread is interrupted by default.
-All threads will be interrupted if the @samp{--all} option is
-specified. If the @samp{--thread-group} option is specified, all
-threads in that group will be interrupted.
+All threads (in all inferiors) will be interrupted if the
+@samp{--all} option is specified. If the @samp{--thread-group}
+option is specified, all threads in that group will be interrupted.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-next
+ -exec-next [--reverse]
@end smallexample
Resumes execution of the inferior program, stopping when the beginning
of the next source line is reached.
+If the @samp{--reverse} option is specified, resumes reverse execution
+of the inferior program, stopping at the beginning of the previous
+source line. If you issue this command on the first line of a
+function, it will take you back to the caller of that function, to the
+source line where the function was called.
+
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{next}.
@subsubheading Synopsis
@smallexample
- -exec-next-instruction
+ -exec-next-instruction [--reverse]
@end smallexample
Executes one machine instruction. If the instruction is a function
instruction in the middle of a source line, the address will be
printed as well.
+If the @samp{--reverse} option is specified, resumes reverse execution
+of the inferior program, stopping at the previous instruction. If the
+previously executed instruction was a return from another function,
+it will continue to execute in reverse until the call to that function
+(from the current stack frame) is reached.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{nexti}.
@subsubheading Synopsis
@smallexample
- -exec-run
+ -exec-run [--all | --thread-group N]
@end smallexample
Starts execution of the inferior from the beginning. The inferior
exits. In the latter case the output will include an exit code, if
the program has exited exceptionally.
+When no option is specified, the current inferior is started. If the
+@samp{--thread-group} option is specified, it should refer to a thread
+group of type @samp{process}, and that thread group will be started.
+If the @samp{--all} option is specified, then all inferiors will be started.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{run}.
@subsubheading Synopsis
@smallexample
- -exec-step
+ -exec-step [--reverse]
@end smallexample
Resumes execution of the inferior program, stopping when the beginning
of the next source line is reached, if the next source line is not a
function call. If it is, stop at the first instruction of the called
-function.
+function. If the @samp{--reverse} option is specified, resumes reverse
+execution of the inferior program, stopping at the beginning of the
+previously executed source line.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -exec-step-instruction
+ -exec-step-instruction [--reverse]
@end smallexample
-Resumes the inferior which executes one machine instruction. The
-output, once @value{GDBN} has stopped, will vary depending on whether
-we have stopped in the middle of a source line or not. In the former
-case, the address at which the program stopped will be printed as
-well.
+Resumes the inferior which executes one machine instruction. If the
+@samp{--reverse} option is specified, resumes reverse execution of the
+inferior program, stopping at the previously executed instruction.
+The output, once @value{GDBN} has stopped, will vary depending on
+whether we have stopped in the middle of a source line or not. In the
+former case, the address at which the program stopped will be printed
+as well.
@subsubheading @value{GDBN} Command
@subsubheading Synopsis
@smallexample
- -stack-list-arguments @var{show-values}
+ -stack-list-arguments @var{print-values}
[ @var{low-frame} @var{high-frame} ]
@end smallexample
@var{high-frame} may be larger than the actual number of frames, in
which case only existing frames will be returned.
-The @var{show-values} argument must have a value of 0 or 1. A value of
-0 means that only the names of the arguments are listed, a value of 1
-means that both names and values of the arguments are printed.
+If @var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types, and the name and type for arrays,
+structures and unions.
Use of this command to obtain arguments in a single frame is
deprecated in favor of the @samp{-stack-list-variables} command.
@var{print-values} is 0 or @code{--no-values}, print only the names of
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
-type and value for simple data types and the name and type for arrays,
+type and value for simple data types, and the name and type for arrays,
structures and unions. In this last case, a frontend can immediately
display the value of simple data types and create variable objects for
other data types when the user wishes to explore their values in
@var{print-values} is 0 or @code{--no-values}, print only the names of
the variables; if it is 1 or @code{--all-values}, print also their
values; and if it is 2 or @code{--simple-values}, print the name,
-type and value for simple data types and the name and type for arrays,
+type and value for simple data types, and the name and type for arrays,
structures and unions.
@subsubheading Example
@node GDB/MI Tracepoint Commands
@section @sc{gdb/mi} Tracepoint Commands
-The tracepoint commands are not yet implemented.
+The commands defined in this section implement MI support for
+tracepoints. For detailed introduction, see @ref{Tracepoints}.
+
+@subheading The @code{-trace-find} Command
+@findex -trace-find
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-find @var{mode} [@var{parameters}@dots{}]
+@end smallexample
+
+Find a trace frame using criteria defined by @var{mode} and
+@var{parameters}. The following table lists permissible
+modes and their parameters. For details of operation, see @ref{tfind}.
+
+@table @samp
+
+@item none
+No parameters are required. Stops examining trace frames.
+
+@item frame-number
+An integer is required as parameter. Selects tracepoint frame with
+that index.
+
+@item tracepoint-number
+An integer is required as parameter. Finds next
+trace frame that corresponds to tracepoint with the specified number.
+
+@item pc
+An address is required as parameter. Finds
+next trace frame that corresponds to any tracepoint at the specified
+address.
+
+@item pc-inside-range
+Two addresses are required as parameters. Finds next trace
+frame that corresponds to a tracepoint at an address inside the
+specified range. Both bounds are considered to be inside the range.
+
+@item pc-outside-range
+Two addresses are required as parameters. Finds
+next trace frame that corresponds to a tracepoint at an address outside
+the specified range. Both bounds are considered to be inside the range.
+
+@item line
+Line specification is required as parameter. @xref{Specify Location}.
+Finds next trace frame that corresponds to a tracepoint at
+the specified location.
+
+@end table
+
+If @samp{none} was passed as @var{mode}, the response does not
+have fields. Otherwise, the response may have the following fields:
+
+@table @samp
+@item found
+This field has either @samp{0} or @samp{1} as the value, depending
+on whether a matching tracepoint was found.
+
+@item traceframe
+The index of the found traceframe. This field is present iff
+the @samp{found} field has value of @samp{1}.
+
+@item tracepoint
+The index of the found tracepoint. This field is present iff
+the @samp{found} field has value of @samp{1}.
+
+@item frame
+The information about the frame corresponding to the found trace
+frame. This field is present only if a trace frame was found.
+@xref{GDB/MI Frame Information}, for description of this field.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tfind}.
+
+@subheading -trace-define-variable
+@findex -trace-define-variable
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-define-variable @var{name} [ @var{value} ]
+@end smallexample
+
+Create trace variable @var{name} if it does not exist. If
+@var{value} is specified, sets the initial value of the specified
+trace variable to that value. Note that the @var{name} should start
+with the @samp{$} character.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tvariable}.
+
+@subheading -trace-list-variables
+@findex -trace-list-variables
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-list-variables
+@end smallexample
+
+Return a table of all defined trace variables. Each element of the
+table has the following fields:
+
+@table @samp
+@item name
+The name of the trace variable. This field is always present.
+
+@item initial
+The initial value. This is a 64-bit signed integer. This
+field is always present.
+
+@item current
+The value the trace variable has at the moment. This is a 64-bit
+signed integer. This field is absent iff current value is
+not defined, for example if the trace was never run, or is
+presently running.
+
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tvariables}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-trace-list-variables
+^done,trace-variables=@{nr_rows="1",nr_cols="3",
+hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
+ @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
+ @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
+body=[variable=@{name="$trace_timestamp",initial="0"@}
+ variable=@{name="$foo",initial="10",current="15"@}]@}
+(gdb)
+@end smallexample
+
+@subheading -trace-save
+@findex -trace-save
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-save [-r ] @var{filename}
+@end smallexample
+
+Saves the collected trace data to @var{filename}. Without the
+@samp{-r} option, the data is downloaded from the target and saved
+in a local file. With the @samp{-r} option the target is asked
+to perform the save.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tsave}.
+
+
+@subheading -trace-start
+@findex -trace-start
+
+@subsubheading Synopsis
+
+@smallexample
+ -trace-start
+@end smallexample
+
+Starts a tracing experiments. The result of this command does not
+have any fields.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{tstart}.
+
+@subheading -trace-status
+@findex -trace-status
-@c @subheading -trace-actions
+@subsubheading Synopsis
-@c @subheading -trace-delete
+@smallexample
+ -trace-status
+@end smallexample
-@c @subheading -trace-disable
+Obtains the status of a tracing experiment. The result may include
+the following fields:
-@c @subheading -trace-dump
+@table @samp
-@c @subheading -trace-enable
+@item supported
+May have a value of either @samp{0}, when no tracing operations are
+supported, @samp{1}, when all tracing operations are supported, or
+@samp{file} when examining trace file. In the latter case, examining
+of trace frame is possible but new tracing experiement cannot be
+started. This field is always present.
-@c @subheading -trace-exists
+@item running
+May have a value of either @samp{0} or @samp{1} depending on whether
+tracing experiement is in progress on target. This field is present
+if @samp{supported} field is not @samp{0}.
+
+@item stop-reason
+Report the reason why the tracing was stopped last time. This field
+may be absent iff tracing was never stopped on target yet. The
+value of @samp{request} means the tracing was stopped as result of
+the @code{-trace-stop} command. The value of @samp{overflow} means
+the tracing buffer is full. The value of @samp{disconnection} means
+tracing was automatically stopped when @value{GDBN} has disconnected.
+The value of @samp{passcount} means tracing was stopped when a
+tracepoint was passed a maximal number of times for that tracepoint.
+This field is present if @samp{supported} field is not @samp{0}.
+
+@item stopping-tracepoint
+The number of tracepoint whose passcount as exceeded. This field is
+present iff the @samp{stop-reason} field has the value of
+@samp{passcount}.
+
+@item frames
+@itemx frames-created
+The @samp{frames} field is a count of the total number of trace frames
+in the trace buffer, while @samp{frames-created} is the total created
+during the run, including ones that were discarded, such as when a
+circular trace buffer filled up. Both fields are optional.
+
+@item buffer-size
+@itemx buffer-free
+These fields tell the current size of the tracing buffer and the
+remaining space. These fields are optional.
+
+@item circular
+The value of the circular trace buffer flag. @code{1} means that the
+trace buffer is circular and old trace frames will be discarded if
+necessary to make room, @code{0} means that the trace buffer is linear
+and may fill up.
+
+@item disconnected
+The value of the disconnected tracing flag. @code{1} means that
+tracing will continue after @value{GDBN} disconnects, @code{0} means
+that the trace run will stop.
-@c @subheading -trace-find
+@end table
-@c @subheading -trace-frame-number
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-info
+The corresponding @value{GDBN} command is @samp{tstatus}.
-@c @subheading -trace-insert
+@subheading -trace-stop
+@findex -trace-stop
-@c @subheading -trace-list
+@subsubheading Synopsis
-@c @subheading -trace-pass-count
+@smallexample
+ -trace-stop
+@end smallexample
-@c @subheading -trace-save
+Stops a tracing experiment. The result of this command has the same
+fields as @code{-trace-status}, except that the @samp{supported} and
+@samp{running} fields are not output.
-@c @subheading -trace-start
+@subsubheading @value{GDBN} Command
-@c @subheading -trace-stop
+The corresponding @value{GDBN} command is @samp{tstop}.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@subheading Synopsis
@smallexample
--list-thread-groups [ --available ] [ @var{group} ]
+-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ]
@end smallexample
-When used without the @var{group} parameter, lists top-level thread
-groups that are being debugged. When used with the @var{group}
-parameter, the children of the specified group are listed. The
-children can be either threads, or other groups. At present,
-@value{GDBN} will not report both threads and groups as children at
-the same time, but it may change in future.
+Lists thread groups (@pxref{Thread groups}). When a single thread
+group is passed as the argument, lists the children of that group.
+When several thread group are passed, lists information about those
+thread groups. Without any parameters, lists information about all
+top-level thread groups.
+
+Normally, thread groups that are being debugged are reported.
+With the @samp{--available} option, @value{GDBN} reports thread groups
+available on the target.
+
+The output of this command may have either a @samp{threads} result or
+a @samp{groups} result. The @samp{thread} result has a list of tuples
+as value, with each tuple describing a thread (@pxref{GDB/MI Thread
+Information}). The @samp{groups} result has a list of tuples as value,
+each tuple describing a thread group. If top-level groups are
+requested (that is, no parameter is passed), or when several groups
+are passed, the output always has a @samp{groups} result. The format
+of the @samp{group} result is described below.
+
+To reduce the number of roundtrips it's possible to list thread groups
+together with their children, by passing the @samp{--recurse} option
+and the recursion depth. Presently, only recursion depth of 1 is
+permitted. If this option is present, then every reported thread group
+will also include its children, either as @samp{group} or
+@samp{threads} field.
+
+In general, any combination of option and parameters is permitted, with
+the following caveats:
+
+@itemize @bullet
+@item
+When a single thread group is passed, the output will typically
+be the @samp{threads} result. Because threads may not contain
+anything, the @samp{recurse} option will be ignored.
+
+@item
+When the @samp{--available} option is passed, limited information may
+be available. In particular, the list of threads of a process might
+be inaccessible. Further, specifying specific thread groups might
+not give any performance advantage over listing all thread groups.
+The frontend should assume that @samp{-list-thread-groups --available}
+is always an expensive operation and cache the results.
+
+@end itemize
+
+The @samp{groups} result is a list of tuples, where each tuple may
+have the following fields:
+
+@table @code
+@item id
+Identifier of the thread group. This field is always present.
+The identifier is an opaque string; frontends should not try to
+convert it to an integer, even though it might look like one.
+
+@item type
+The type of the thread group. At present, only @samp{process} is a
+valid type.
+
+@item pid
+The target-specific process identifier. This field is only present
+for thread groups of type @samp{process} and only if the process exists.
+
+@item num_children
+The number of children this thread group has. This field may be
+absent for an available thread group.
+
+@item threads
+This field has a list of tuples as value, each tuple describing a
+thread. It may be present if the @samp{--recurse} option is
+specified, and it's actually possible to obtain the threads.
-With the @samp{--available} option, instead of reporting groups that
-are been debugged, GDB will report all thread groups available on the
-target. Using the @samp{--available} option together with @var{group}
-is not allowed.
+@item cores
+This field is a list of integers, each identifying a core that one
+thread of the group is running on. This field may be absent if
+such information is not available.
+
+@item executable
+The name of the executable file that corresponds to this thread group.
+The field is only present for thread groups of type @samp{process},
+and only if there is a corresponding executable file.
+
+@end table
@subheading Example
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+-list-thread-groups --available
+^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
+-list-thread-groups --available --recurse 1
+ ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
+ @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..]
+-list-thread-groups --available --recurse 1 17 18
+^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
+ threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
+ @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
+@end smallexample
+
+
+@subheading The @code{-add-inferior} Command
+@findex -add-inferior
+
+@subheading Synopsis
+
+@smallexample
+-add-inferior
+@end smallexample
+
+Creates a new inferior (@pxref{Inferiors and Programs}). The created
+inferior is not associated with any executable. Such association may
+be established with the @samp{-file-exec-and-symbols} command
+(@pxref{GDB/MI File Commands}). The command response has a single
+field, @samp{thread-group}, whose value is the identifier of the
+thread group corresponding to the new inferior.
+
+@subheading Example
+
+@smallexample
+@value{GDBP}
+-add-inferior
+^done,thread-group="i3"
@end smallexample
@subheading The @code{-interpreter-exec} Command
The command @code{maint print raw-registers} includes the contents of
the raw register cache; the command @code{maint print cooked-registers}
-includes the (cooked) value of all registers; and the command
-@code{maint print register-groups} includes the groups that each
+includes the (cooked) value of all registers, including registers which
+aren't available on the target nor visible to user; and the
+command @code{maint print register-groups} includes the groups that each
register is a member of. @xref{Registers,, Registers, gdbint,
@value{GDBN} Internals}.
* Packets::
* Stop Reply Packets::
* General Query Packets::
-* Register Packet Format::
+* Architecture-Specific Protocol Details::
* Tracepoint Packets::
* Host I/O Packets::
* Interrupts::
* File-I/O Remote Protocol Extension::
* Library List Format::
* Memory Map Format::
+* Thread List Format::
@end menu
@node Overview
for an error
@end table
-@item z @var{type},@var{addr},@var{length}
-@itemx Z @var{type},@var{addr},@var{length}
+@item z @var{type},@var{addr},@var{kind}
+@itemx Z @var{type},@var{addr},@var{kind}
@anchor{insert breakpoint or watchpoint packet}
@cindex @samp{z} packet
@cindex @samp{Z} packets
Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
-watchpoint starting at address @var{address} and covering the next
-@var{length} bytes.
+watchpoint starting at address @var{address} of kind @var{kind}.
Each breakpoint and watchpoint packet @var{type} is documented
separately.
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
-@item z0,@var{addr},@var{length}
-@itemx Z0,@var{addr},@var{length}
+@item z0,@var{addr},@var{kind}
+@itemx Z0,@var{addr},@var{kind}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
-@var{addr} of size @var{length}.
+@var{addr} of type @var{kind}.
A memory breakpoint is implemented by replacing the instruction at
@var{addr} with a software breakpoint or trap instruction. The
-@var{length} is used by targets that indicates the size of the
-breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
-@sc{mips} can insert either a 2 or 4 byte breakpoint).
+@var{kind} is target-specific and typically indicates the size of
+the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
+and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
+architectures have additional meanings for @var{kind};
+see @ref{Architecture-Specific Protocol Details}.
@emph{Implementation note: It is possible for a target to copy or move
code that contains memory breakpoints (e.g., when implementing
for an error
@end table
-@item z1,@var{addr},@var{length}
-@itemx Z1,@var{addr},@var{length}
+@item z1,@var{addr},@var{kind}
+@itemx Z1,@var{addr},@var{kind}
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
-address @var{addr} of size @var{length}.
+address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory.
+dependant on being able to modify the target's memory. @var{kind}
+has the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
for an error
@end table
-@item z2,@var{addr},@var{length}
-@itemx Z2,@var{addr},@var{length}
+@item z2,@var{addr},@var{kind}
+@itemx Z2,@var{addr},@var{kind}
@cindex @samp{z2} packet
@cindex @samp{Z2} packet
-Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint.
+Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
for an error
@end table
-@item z3,@var{addr},@var{length}
-@itemx Z3,@var{addr},@var{length}
+@item z3,@var{addr},@var{kind}
+@itemx Z3,@var{addr},@var{kind}
@cindex @samp{z3} packet
@cindex @samp{Z3} packet
-Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint.
+Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
for an error
@end table
-@item z4,@var{addr},@var{length}
-@itemx Z4,@var{addr},@var{length}
+@item z4,@var{addr},@var{kind}
+@itemx Z4,@var{addr},@var{kind}
@cindex @samp{z4} packet
@cindex @samp{Z4} packet
-Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint.
+Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
+@var{kind} is interpreted as the number of bytes to watch.
Reply:
@table @samp
If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
the stopped thread, as specified in @ref{thread-id syntax}.
+@item
+If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of
+the core on which the stop event was detected.
+
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
specific event that stopped the target. The currently defined stop
beginning when executing backward) of the log. The value of @var{r}
will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
for more information.
-
-
@end table
@item W @var{AA}
extensions unless the stub also reports that it supports them by
including @samp{multiprocess+} in its @samp{qSupported} reply.
@xref{multiprocess extensions}, for details.
+
+@item xmlRegisters
+This feature indicates that @value{GDBN} supports the XML target
+description. If the stub sees @samp{xmlRegisters=} with target
+specific strings separated by a comma, it will report register
+description.
@end table
Stubs should ignore any unknown values for
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:threads:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
@tab @samp{-}
@tab No
+@item @samp{TracepointSource}
+@tab No
+@tab @samp{-}
+@tab No
+
@end multitable
These are the currently defined stub features, in more detail:
The remote stub understands the @samp{qXfer:siginfo:write} packet
(@pxref{qXfer siginfo write}).
+@item qXfer:threads:read
+The remote stub understands the @samp{qXfer:threads:read} packet
+(@pxref{qXfer threads read}).
+
@item QNonStop
The remote stub understands the @samp{QNonStop} packet
(@pxref{QNonStop}).
The remote stub accepts and implements the reverse step packet
(@pxref{bs}).
+@item TracepointSource
+The remote stub understands the @samp{QTDPsrc} packet that supplies
+the source form of tracepoint definitions.
+
@end table
@item qSymbol::
(if available), until the target ceases to request them.
@end table
-@item QTDP
+@item qTBuffer
+@item QTBuffer
+@item QTDisconnected
+@itemx QTDP
+@itemx QTDPsrc
+@itemx QTDV
+@itemx qTfP
+@itemx qTfV
@itemx QTFrame
@xref{Tracepoint Packets}.
conventions above. Please don't use this packet as a model for new
packets.)
-@item QTStart
+@item QTSave
+@item qTsP
+@item qTsV
+@itemx QTStart
@itemx QTStop
@itemx QTinit
@itemx QTro
@itemx qTStatus
+@itemx qTV
@xref{Tracepoint Packets}.
@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
+@item qXfer:threads:read::@var{offset},@var{length}
+@anchor{qXfer threads read}
+Access the list of threads on target. @xref{Thread List Format}. The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
Access the target's @dfn{operating system information}.
@end table
-@node Register Packet Format
-@section Register Packet Format
+@node Architecture-Specific Protocol Details
+@section Architecture-Specific Protocol Details
+
+This section describes how the remote protocol is applied to specific
+target architectures. Also see @ref{Standard Target Features}, for
+details of XML target descriptions for each architecture.
+
+@subsection ARM
+
+@subsubsection Breakpoint Kinds
+
+These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
+
+@table @r
+
+@item 2
+16-bit Thumb mode breakpoint.
+
+@item 3
+32-bit Thumb mode (Thumb-2) breakpoint.
+
+@item 4
+32-bit ARM mode breakpoint.
+
+@end table
+
+@subsection MIPS
+
+@subsubsection Register Packet Format
The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
@table @samp
-@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:X@var{len},@var{bytes}]@r{[}-@r{]}
+@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
the tracepoint is disabled. @var{step} is the tracepoint's step
-count, and @var{pass} is its pass count. If an @samp{X} is present,
-it introduces a tracepoint condition, which consists of a hexadecimal
-length, followed by a comma and hex-encoded bytes, in a manner similar
-to action encodings as described below. If the trailing @samp{-} is
-present, further @samp{QTDP} packets will follow to specify this
-tracepoint's actions.
+count, and @var{pass} is its pass count. If an @samp{F} is present,
+then the tracepoint is to be a fast tracepoint, and the @var{flen} is
+the number of bytes that the target should copy elsewhere to make room
+for the tracepoint. If an @samp{X} is present, it introduces a
+tracepoint condition, which consists of a hexadecimal length, followed
+by a comma and hex-encoded bytes, in a manner similar to action
+encodings as described below. If the trailing @samp{-} is present,
+further @samp{QTDP} packets will follow to specify this tracepoint's
+actions.
Replies:
@table @samp
The packet was not recognized.
@end table
+@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
+@cindex @samp{QTDPsrc} packet
+Specify a source string of tracepoint @var{n} at address @var{addr}.
+This is useful to get accurate reproduction of the tracepoints
+originally downloaded at the beginning of the trace run. @var{type}
+is the name of the tracepoint part, such as @samp{cond} for the
+tracepoint's conditional expression (see below for a list of types), while
+@var{bytes} is the string, encoded in hexadecimal.
+
+@var{start} is the offset of the @var{bytes} within the overall source
+string, while @var{slen} is the total length of the source string.
+This is intended for handling source strings that are longer than will
+fit in a single packet.
+@c Add detailed example when this info is moved into a dedicated
+@c tracepoint descriptions section.
+
+The available string types are @samp{at} for the location,
+@samp{cond} for the conditional, and @samp{cmd} for an action command.
+@value{GDBN} sends a separate packet for each command in the action
+list, in the same order in which the commands are stored in the list.
+
+The target does not need to do anything with source strings except
+report them back as part of the replies to the @samp{qTfP}/@samp{qTsP}
+query packets.
+
+Although this packet is optional, and @value{GDBN} will only send it
+if the target replies with @samp{TracepointSource} @xref{General
+Query Packets}, it makes both disconnected tracing and trace files
+much easier to use. Otherwise the user must be careful that the
+tracepoints in effect while looking at trace frames are identical to
+the ones in effect during the trace run; even a small discrepancy
+could cause @samp{tdump} not to work, or a particular trace frame not
+be found.
+
+@item QTDV:@var{n}:@var{value}
+@cindex define trace state variable, remote request
+@cindex @samp{QTDV} packet
+Create a new trace state variable, number @var{n}, with an initial
+value of @var{value}, which is a 64-bit signed integer. Both @var{n}
+and @var{value} are encoded as hexadecimal values. @value{GDBN} has
+the option of not using this packet for initial values of zero; the
+target should simply create the trace state variables as they are
+mentioned in expressions.
+
@item QTFrame:@var{n}
Select the @var{n}'th tracepoint frame from the buffer, and use the
register and memory contents recorded there to answer subsequent
@item QTFrame:range:@var{start}:@var{end}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame whose PC is between @var{start} (inclusive)
-and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
+and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal
numbers.
@item QTFrame:outside:@var{start}:@var{end}
Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
-frame @emph{outside} the given range of addresses.
+frame @emph{outside} the given range of addresses (exclusive).
@item QTStart
Begin the tracepoint experiment. Begin collecting data from tracepoint
still have the same contents they did when the tracepoint was hit, so
there's no reason for the stub to refuse to provide their contents.
+@item QTDisconnected:@var{value}
+Set the choice to what to do with the tracing run when @value{GDBN}
+disconnects from the target. A @var{value} of 1 directs the target to
+continue the tracing run, while 0 tells the target to stop tracing if
+@value{GDBN} is no longer in the picture.
+
@item qTStatus
Ask the stub if there is a trace experiment running right now.
-Replies:
+The reply has the form:
+
+@table @samp
+
+@item T@var{running}@r{[};@var{field}@r{]}@dots{}
+@var{running} is a single digit @code{1} if the trace is presently
+running, or @code{0} if not. It is followed by semicolon-separated
+optional fields that an agent may use to report additional status.
+
+@end table
+
+If the trace is not running, the agent may report any of several
+explanations as one of the optional fields:
+
@table @samp
-@item T0
-There is no trace experiment running.
-@item T1
-There is a trace experiment running.
+
+@item tnotrun:0
+No trace has been run yet.
+
+@item tstop:0
+The trace was stopped by a user-originated stop command.
+
+@item tfull:0
+The trace stopped because the trace buffer filled up.
+
+@item tdisconnected:0
+The trace stopped because @value{GDBN} disconnected from the target.
+
+@item tpasscount:@var{tpnum}
+The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
+
+@item terror:@var{text}:@var{tpnum}
+The trace stopped because tracepoint @var{tpnum} had an error. The
+string @var{text} is available to describe the nature of the error
+(for instance, a divide by zero in the condition expression).
+@var{text} is hex encoded.
+
+@item tunknown:0
+The trace stopped for some other reason.
+
@end table
+Additional optional fields supply statistical and other information.
+Although not required, they are extremely useful for users monitoring
+the progress of a trace run. If a trace has stopped, and these
+numbers are reported, they must reflect the state of the just-stopped
+trace.
+
+@table @samp
+
+@item tframes:@var{n}
+The number of trace frames in the buffer.
+
+@item tcreated:@var{n}
+The total number of trace frames created during the run. This may
+be larger than the trace frame count, if the buffer is circular.
+
+@item tsize:@var{n}
+The total size of the trace buffer, in bytes.
+
+@item tfree:@var{n}
+The number of bytes still unused in the buffer.
+
+@item circular:@var{n}
+The value of the circular trace buffer flag. @code{1} means that the
+trace buffer is circular and old trace frames will be discarded if
+necessary to make room, @code{0} means that the trace buffer is linear
+and may fill up.
+
+@item disconn:@var{n}
+The value of the disconnected tracing flag. @code{1} means that
+tracing will continue after @value{GDBN} disconnects, @code{0} means
+that the trace run will stop.
+
@end table
+@item qTV:@var{var}
+@cindex trace state variable value, remote request
+@cindex @samp{qTV} packet
+Ask the stub for the value of the trace state variable number @var{var}.
+
+Replies:
+@table @samp
+@item V@var{value}
+The value of the variable is @var{value}. This will be the current
+value of the variable if the user is examining a running target, or a
+saved value if the variable was collected in the trace frame that the
+user is looking at. Note that multiple requests may result in
+different reply values, such as when requesting values while the
+program is running.
+
+@item U
+The value of the variable is unknown. This would occur, for example,
+if the user is examining a trace frame in which the requested variable
+was not collected.
+@end table
+
+@item qTfP
+@itemx qTsP
+These packets request data about tracepoints that are being used by
+the target. @value{GDBN} sends @code{qTfP} to get the first piece
+of data, and multiple @code{qTsP} to get additional pieces. Replies
+to these packets generally take the form of the @code{QTDP} packets
+that define tracepoints. (FIXME add detailed syntax)
+
+@item qTfV
+@itemx qTsV
+These packets request data about trace state variables that are on the
+target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
+and multiple @code{qTsV} to get additional variables. Replies to
+these packets follow the syntax of the @code{QTDV} packets that define
+trace state variables.
+
+@item QTSave:@var{filename}
+This packet directs the target to save trace data to the file name
+@var{filename} in the target's filesystem. @var{filename} is encoded
+as a hex string; the interpretation of the file name (relative vs
+absolute, wild cards, etc) is up to the target.
+
+@item qTBuffer:@var{offset},@var{len}
+Return up to @var{len} bytes of the current contents of trace buffer,
+starting at @var{offset}. The trace buffer is treated as if it were
+a contiguous collection of traceframes, as per the trace file format.
+The reply consists as many hex-encoded bytes as the target can deliver
+in a packet; it is not an error to return fewer than were asked for.
+A reply consisting of just @code{l} indicates that no bytes are
+available.
+
+@item QTBuffer:circular:@var{value}
+This packet directs the target to use a circular trace buffer if
+@var{value} is 1, or a linear buffer if the value is 0.
+
+@end table
@node Host I/O Packets
@section Host I/O Packets
@cindex interrupts (remote protocol)
When a program on the remote target is running, @value{GDBN} may
-attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
-control of which is specified via @value{GDBN}'s @samp{remotebreak}
-setting (@pxref{set remotebreak}).
+attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
+a @code{BREAK} followed by @code{g},
+control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
The precise meaning of @code{BREAK} is defined by the transport
mechanism and may, in fact, be undefined. @value{GDBN} does not
(@pxref{X packet}), used for binary downloads, may include an unescaped
@code{0x03} as part of its packet.
+@code{BREAK} followed by @code{g} is also known as Magic SysRq g.
+When Linux kernel receives this sequence from serial port,
+it stops execution and connects to gdb.
+
Stubs are not required to recognize these interrupt mechanisms and the
precise meaning associated with receipt of the interrupt is
implementation defined. If the target supports debugging of multiple
<!ATTLIST property name CDATA #REQUIRED>
@end smallexample
+@node Thread List Format
+@section Thread List Format
+@cindex thread list format
+
+To efficiently update the list of threads and their attributes,
+@value{GDBN} issues the @samp{qXfer:threads:read} packet
+(@pxref{qXfer threads read}) and obtains the XML document with
+the following structure:
+
+@smallexample
+<?xml version="1.0"?>
+<threads>
+ <thread id="id" core="0">
+ ... description ...
+ </thread>
+</threads>
+@end smallexample
+
+Each @samp{thread} element must have the @samp{id} attribute that
+identifies the thread (@pxref{thread-id syntax}). The
+@samp{core} attribute, if present, specifies which processor core
+the thread was last executing on. The content of the of @samp{thread}
+element is interpreted as human-readable auxilliary information.
+
@include agentexpr.texi
+@node Trace File Format
+@appendix Trace File Format
+@cindex trace file format
+
+The trace file comes in three parts: a header, a textual description
+section, and a trace frame section with binary data.
+
+The header has the form @code{\x7fTRACE0\n}. The first byte is
+@code{0x7f} so as to indicate that the file contains binary data,
+while the @code{0} is a version number that may have different values
+in the future.
+
+The description section consists of multiple lines of @sc{ascii} text
+separated by newline characters (@code{0xa}). The lines may include a
+variety of optional descriptive or context-setting information, such
+as tracepoint definitions or register set size. @value{GDBN} will
+ignore any line that it does not recognize. An empty line marks the end
+of this section.
+
+@c FIXME add some specific types of data
+
+The trace frame section consists of a number of consecutive frames.
+Each frame begins with a two-byte tracepoint number, followed by a
+four-byte size giving the amount of data in the frame. The data in
+the frame consists of a number of blocks, each introduced by a
+character indicating its type (at least register, memory, and trace
+state variable). The data in this section is raw binary, not a
+hexadecimal or other encoding; its endianness matches the target's
+endianness.
+
+@c FIXME bi-arch may require endianness/arch info in description section
+
+@table @code
+@item R @var{bytes}
+Register block. The number and ordering of bytes matches that of a
+@code{g} packet in the remote protocol. Note that these are the
+actual bytes, in target order and @value{GDBN} register order, not a
+hexadecimal encoding.
+
+@item M @var{address} @var{length} @var{bytes}...
+Memory block. This is a contiguous block of memory, at the 8-byte
+address @var{address}, with a 2-byte length @var{length}, followed by
+@var{length} bytes.
+
+@item V @var{number} @var{value}
+Trace state variable block. This records the 8-byte signed value
+@var{value} of trace state variable numbered @var{number}.
+
+@end table
+
+Future enhancements of the trace file format may include additional types
+of blocks.
+
@node Target Descriptions
@appendix Target Descriptions
@cindex target descriptions
</union>
@end smallexample
+@cindex <struct>
+If a register's value is composed from several separate values, define
+it with a structure type. There are two forms of the @samp{<struct>}
+element; a @samp{<struct>} element must either contain only bitfields
+or contain no bitfields. If the structure contains only bitfields,
+its total size in bytes must be specified, each bitfield must have an
+explicit start and end, and bitfields are automatically assigned an
+integer type. The field's @var{start} should be less than or
+equal to its @var{end}, and zero represents the least significant bit.
+
+@smallexample
+<struct id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+ @dots{}
+</struct>
+@end smallexample
+
+If the structure contains no bitfields, then each field has an
+explicit type, and no implicit padding is added.
+
+@smallexample
+<struct id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
+ @dots{}
+</struct>
+@end smallexample
+
+@cindex <flags>
+If a register's value is a series of single-bit flags, define it with
+a flags type. The @samp{<flags>} element has an explicit @var{size}
+and contains one or more @samp{<field>} elements. Each field has a
+@var{name}, a @var{start}, and an @var{end}. Only single-bit flags
+are supported.
+
+@smallexample
+<flags id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+ @dots{}
+</flags>
+@end smallexample
+
@subsection Registers
@cindex <reg>
@item arm_fpa_ext
The 12-byte extended precision format used by ARM FPA registers.
+@item i387_ext
+The 10-byte extended precision format used by x87 registers.
+
+@item i386_eflags
+32bit @sc{eflags} register used by x86.
+
+@item i386_mxcsr
+32bit @sc{mxcsr} register used by x86.
+
@end table
@node Standard Target Features
@menu
* ARM Features::
+* i386 Features::
* MIPS Features::
* M68K Features::
* PowerPC Features::
If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
be present and include 32 double-precision registers.
+@node i386 Features
+@subsection i386 Features
+@cindex target descriptions, i386 features
+
+The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{eax} through @samp{edi} plus @samp{eip} for i386
+@item
+@samp{rax} through @samp{r15} plus @samp{rip} for amd64
+@item
+@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es},
+@samp{fs}, @samp{gs}
+@item
+@samp{st0} through @samp{st7}
+@item
+@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
+@samp{foseg}, @samp{fooff} and @samp{fop}
+@end itemize
+
+The register sets may be different, depending on the target.
+
+The @samp{org.gnu.gdb.i386.sse} feature is optional. It should
+describe registers:
+
+@itemize @minus
+@item
+@samp{xmm0} through @samp{xmm7} for i386
+@item
+@samp{xmm0} through @samp{xmm15} for amd64
+@item
+@samp{mxcsr}
+@end itemize
+
+The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the
+@samp{org.gnu.gdb.i386.sse} feature. It should
+describe the upper 128 bits of @sc{ymm} registers:
+
+@itemize @minus
+@item
+@samp{ymm0h} through @samp{ymm7h} for i386
+@item
+@samp{ymm0h} through @samp{ymm15h} for amd64
+@item
+@end itemize
+
+The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
+describe a single register, @samp{orig_eax}.
+
@node MIPS Features
@subsection MIPS Features
@cindex target descriptions, MIPS features
<column name="pid">1</column>
<column name="user">root</column>
<column name="command">/sbin/init</column>
+ <column name="cores">1,2,3</column>
</item>
</osdata>
@end smallexample
Each item should include a column whose name is @samp{pid}. The value
of that column should identify the process on the target. The
@samp{user} and @samp{command} columns are optional, and will be
-displayed by @value{GDBN}. Target may provide additional columns,
+displayed by @value{GDBN}. The @samp{cores} column, if present,
+should contain a comma-separated list of cores that this process
+is running on. Target may provide additional columns,
which @value{GDBN} currently ignores.
@include gpl.texi
projects / deliverable / binutils-gdb.git / blobdiff