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
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.
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
* Tracepoint Actions::
* Listing Tracepoints::
* Starting and Stopping Trace Experiments::
+* Tracepoint Restrictions::
@end menu
@node Create and Delete Tracepoints
@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 at each instruction. 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
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.
+
+@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
@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
@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
@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
* Commands In Python:: Implementing new commands in Python.
* Functions In Python:: Writing new convenience functions.
* 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.
@end menu
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
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
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
@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 Blocks In Python
+@subsubsection Accessing frame blocks from Python.
+
+@cindex blocks in python
+@tindex gdb.Block
+
+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.
+
+The following block-related functions are available in the @code{gdb}
+module:
+
+@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
+
+A @code{gdb.Block} object has the following attributes:
+
+@table @code
+@defivar Block start
+The start address of the block. This attribute is not writable.
+@end defivar
+
+@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
+
+@node Symbols In Python
+@subsubsection Python representation of Symbols.
+
+@cindex symbols in python
+@tindex gdb.Symbol
+
+@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.
+
+The following symbol-related functions are available in the @code{gdb}
+module:
+
+@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
+
+A @code{gdb.Symbol} object has the following attributes:
+
+@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
+
+@defivar Symbol name
+The name of the symbol as a string. This attribute is not writable.
+@end defivar
+
+@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
+
+@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
+
+@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
+
+@defivar Symbol is_argument
+@code{True} if the symbol is an argument of a function.
+@end defivar
+
+@defivar Symbol is_constant
+@code{True} if the symbol is a constant.
+@end defivar
+
+@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 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
+
+@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
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
@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
processor core on which the stop event has happened. This field may be absent
if such information is not available.
-@item =thread-group-created,id="@var{id}"
+@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.
+
@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
@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
@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
@item pid
The target-specific process identifier. This field is only present
-for thread groups of type @samp{process}.
+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
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="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
@findex -interpreter-exec
* Packets::
* Stop Reply Packets::
* General Query Packets::
-* Register Packet Format::
+* Architecture-Specific Protocol Details::
* Tracepoint Packets::
* Host I/O Packets::
* Interrupts::
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
@end table
@item qTBuffer
+@item QTBuffer
@item QTDisconnected
@itemx QTDP
@itemx QTDV
@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
@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
@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 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 tunknown:0
+The trace stopped for some other reason.
+
+@end table
+
+Additional optional fields supply statistical 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 T0
-There is no trace experiment running.
-@item T1
-There is a trace experiment running.
+
+@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.
+
@end table
@item qTV:@var{var}
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
</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 required. 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.linux} feature is optional. It should
+describe a single register, @samp{orig_eax}.
+
@node MIPS Features
@subsection MIPS Features
@cindex target descriptions, MIPS features
projects / deliverable / binutils-gdb.git / blobdiff