\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}
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
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::
@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
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
@noindent
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.
@node Analyze Collected Data
@section Using the Collected Data
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
@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
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
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
* Functions In Python:: Writing new convenience functions.
* Objfiles In Python:: Object files.
* Frames In Python:: Acessing inferior stack frames from Python.
+* Lazy Strings In Python:: Python representation of lazy strings.
@end menu
@node Basic Python
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
@end defmethod
@end table
+@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
* GDB/MI Stream Records::
* GDB/MI Async Records::
* GDB/MI Frame Information::
+* GDB/MI Thread Information::
@end menu
@node GDB/MI Result Records
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-created,id="@var{id}"
@itemx =thread-group-exited,id="@var{id}"
@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
@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.
+
+@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}.
+
+@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.
+
+@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.
-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.
+@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{-interpreter-exec} Command
* 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}
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:threads:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
+
@item @samp{QNonStop}
@tab No
@tab @samp{-}
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}).
(if available), until the target ceases to request them.
@end table
-@item QTDP
+@item qTBuffer
+@item QTDisconnected
+@itemx QTDP
+@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 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
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.
There is a trace experiment running.
@end table
-@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.
+@end table
@node Host I/O Packets
@section Host I/O Packets
<!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
<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 / binutils-gdb.git / blobdiff