\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2016 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2017 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2016 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2017 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2016 Free Software Foundation, Inc.
+Copyright (C) 1988-2017 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
Michael Eager and staff of Xilinx, Inc., contributed support for the
Xilinx MicroBlaze architecture.
+Initial support for the FreeBSD/mips target and native configuration
+was developed by SRI International and the University of Cambridge
+Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237
+("CTSRD"), as part of the DARPA CRASH research programme.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
@kindex set startup-with-shell
+@anchor{set startup-with-shell}
@item set startup-with-shell
@itemx set startup-with-shell on
@itemx set startup-with-shell off
-@itemx show set startup-with-shell
+@itemx show startup-with-shell
On Unix systems, by default, if a shell is available on your target,
@value{GDBN}) uses it to start your program. Arguments of the
@code{run} command are passed to the shell, which does variable
program.
@table @code
-@item set inferior-tty /dev/ttyb
+@item set inferior-tty [ @var{tty} ]
@kindex set inferior-tty
-Set the tty for the program being debugged to /dev/ttyb.
+Set the tty for the program being debugged to @var{tty}. Omitting @var{tty}
+restores the default behavior, which is to use the same terminal as
+@value{GDBN}.
@item show inferior-tty
@kindex show inferior-tty
enable it again.
@cindex breakpoint ranges
+@cindex breakpoint lists
@cindex ranges of breakpoints
-Some @value{GDBN} commands accept a range of breakpoints on which to
-operate. A breakpoint range is either a single breakpoint number, like
-@samp{5}, or two such numbers, in increasing order, separated by a
-hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
-all breakpoints in that range are operated on.
+@cindex lists of breakpoints
+Some @value{GDBN} commands accept a space-separated list of breakpoints
+on which to operate. A list element can be either a single breakpoint number,
+like @samp{5}, or a range of such numbers, like @samp{5-7}.
+When a breakpoint list is given to a command, all breakpoints in that list
+are operated on.
@menu
* Set Breaks:: Setting breakpoints
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @r{[}@var{n}@dots{}@r{]}
-@itemx info break @r{[}@var{n}@dots{}@r{]}
+@item info breakpoints @r{[}@var{list}@dots{}@r{]}
+@itemx info break @r{[}@var{list}@dots{}@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(s) (or watchpoint(s) or catchpoint(s)).
breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
-You can control this automatic behaviour with the following commands::
+You can control this automatic behaviour with the following commands:
@kindex set breakpoint auto-hw
@kindex show breakpoint auto-hw
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
-@kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
-@item info watchpoints @r{[}@var{n}@dots{}@r{]}
+@kindex info watchpoints @r{[}@var{list}@dots{}@r{]}
+@item info watchpoints @r{[}@var{list}@dots{}@r{]}
This command prints a list of watchpoints, using the same format as
@code{info break} (@pxref{Set Breaks}).
@end table
A call to @code{exec}.
@item syscall
-@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
+@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{}
@kindex catch syscall
@cindex break on a system call.
A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
list of syscalls on your system (e.g., because @value{GDBN} lags
behind the OS upgrades).
+You may specify a group of related syscalls to be caught at once using
+the @code{group:} syntax (@code{g:} is a shorter equivalent). For
+instance, on some platforms @value{GDBN} allows you to catch all
+network related syscalls, by passing the argument @code{group:network}
+to @code{catch syscall}. Note that not all syscall groups are
+available in every system. You can use the command completion
+facilities (@pxref{Completion,, command completion}) to list the
+syscall groups available on your environment.
+
The example below illustrates how this command works if you don't provide
arguments to it:
(@value{GDBP})
@end smallexample
+Here is an example of catching a syscall group:
+
+@smallexample
+(@value{GDBP}) catch syscall group:process
+Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]
+'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]
+'exit_group' [252] 'waitid' [284] 'unshare' [310])
+(@value{GDBP}) r
+Starting program: /tmp/catch-syscall
+
+Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()
+ from /lib64/ld-linux-x86-64.so.2
+
+(@value{GDBP}) c
+Continuing.
+@end smallexample
+
However, there can be situations when there is no corresponding name
in XML file for that syscall number. In this case, @value{GDBN} prints
a warning message saying that it was not able to find the syscall name,
@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}
-@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
-ranges specified as arguments. If no argument is specified, delete all
+list specified as argument. If no argument is specified, delete all
breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
confirm off}). You can abbreviate this command as @code{d}.
@end table
@table @code
@kindex disable
@kindex dis @r{(@code{disable})}
-@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
options such as ignore-counts, conditions and commands are remembered in
@code{disable} as @code{dis}.
@kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
-@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
-@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} records
@var{count} with each of the specified breakpoints, and decrements a
breakpoint's count when it is hit. When any count reaches 0,
count (@pxref{Conditions, ,Break Conditions}), that will be
decremented to 0 before @var{count} is affected.
-@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
Breakpoints set by the @code{tbreak} command start out in this state.
@table @code
@kindex commands
@kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{range}@dots{}@r{]}
+@item commands @r{[}@var{list}@dots{}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
Specify a list of commands for the given breakpoints. The commands
print commands, simply define normal breakpoints with
explicitly-supplied command lists.)
+@table @code
@item gdb
@kindex dprintf-style gdb
Handle the output using the @value{GDBN} @code{printf} command.
Have the remote debugging agent (such as @code{gdbserver}) handle
the output itself. This style is only available for agents that
support running commands on the target.
+@end table
@item set dprintf-function @var{function}
Set the function to call if the dprintf style is @code{call}. By
@cindex skipping over functions and files
The program you are debugging may contain some functions which are
-uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to
-skip a function or all functions in a file when stepping.
+uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to
+skip a function, all functions in a file or a particular function in
+a particular file when stepping.
For example, consider the following C function:
@code{step} at line 103, you'll step over @code{boring} and directly into
@code{foo}.
-You can also instruct @value{GDBN} to skip all functions in a file, with, for
-example, @code{skip file boring.c}.
+Functions may be skipped by providing either a function name, linespec
+(@pxref{Specify Location}), regular expression that matches the function's
+name, file name or a @code{glob}-style pattern that matches the file name.
+
+On Posix systems the form of the regular expression is
+``Extended Regular Expressions''. See for example @samp{man 7 regex}
+on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular
+expression is whatever is provided by the @code{regcomp} function of
+the underlying system.
+See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a
+description of @code{glob}-style patterns.
+
+@table @code
+@kindex skip
+@item skip @r{[}@var{options}@r{]}
+The basic form of the @code{skip} command takes zero or more options
+that specify what to skip.
+The @var{options} argument is any useful combination of the following:
@table @code
+@item -file @var{file}
+@itemx -fi @var{file}
+Functions in @var{file} will be skipped over when stepping.
+
+@item -gfile @var{file-glob-pattern}
+@itemx -gfi @var{file-glob-pattern}
+@cindex skipping over files via glob-style patterns
+Functions in files matching @var{file-glob-pattern} will be skipped
+over when stepping.
+
+@smallexample
+(gdb) skip -gfi utils/*.c
+@end smallexample
+
+@item -function @var{linespec}
+@itemx -fu @var{linespec}
+Functions named by @var{linespec} or the function containing the line
+named by @var{linespec} will be skipped over when stepping.
+@xref{Specify Location}.
+
+@item -rfunction @var{regexp}
+@itemx -rfu @var{regexp}
+@cindex skipping over functions via regular expressions
+Functions whose name matches @var{regexp} will be skipped over when stepping.
+
+This form is useful for complex function names.
+For example, there is generally no need to step into C@t{++} @code{std::string}
+constructors or destructors. Plus with C@t{++} templates it can be hard to
+write out the full name of the function, and often it doesn't matter what
+the template arguments are. Specifying the function to be skipped as a
+regular expression makes this easier.
+
+@smallexample
+(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
+@end smallexample
+
+If you want to skip every templated C@t{++} constructor and destructor
+in the @code{std} namespace you can do:
+
+@smallexample
+(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
+@end smallexample
+@end table
+
+If no options are specified, the function you're currently debugging
+will be skipped.
+
@kindex skip function
-@item skip @r{[}@var{linespec}@r{]}
-@itemx skip function @r{[}@var{linespec}@r{]}
+@item skip function @r{[}@var{linespec}@r{]}
After running this command, the function named by @var{linespec} or the
function containing the line named by @var{linespec} will be skipped over when
stepping. @xref{Specify Location}.
After running this command, any function whose source lives in @var{filename}
will be skipped over when stepping.
+@smallexample
+(gdb) skip file boring.c
+File boring.c will be skipped when stepping.
+@end smallexample
+
If you do not specify @var{filename}, functions whose source lives in the file
you're currently debugging will be skipped.
@end table
@table @emph
@item Identifier
A number identifying this skip.
-@item Type
-The type of this skip, either @samp{function} or @samp{file}.
@item Enabled or Disabled
-Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}.
-@item Address
-For function skips, this column indicates the address in memory of the function
-being skipped. If you've set a function skip on a function which has not yet
-been loaded, this field will contain @samp{<PENDING>}. Once a shared library
-which has the function is loaded, @code{info skip} will show the function's
-address here.
-@item What
-For file skips, this field contains the filename being skipped. For functions
-skips, this field contains the function name and its line number in the file
-where it is defined.
+Enabled skips are marked with @samp{y}.
+Disabled skips are marked with @samp{n}.
+@item Glob
+If the file name is a @samp{glob} pattern this is @samp{y}.
+Otherwise it is @samp{n}.
+@item File
+The name or @samp{glob} pattern of the file to be skipped.
+If no file is specified this is @samp{<none>}.
+@item RE
+If the function name is a @samp{regular expression} this is @samp{y}.
+Otherwise it is @samp{n}.
+@item Function
+The name or regular expression of the function to skip.
+If no function is specified this is @samp{<none>}.
@end table
@kindex skip delete
Depending on target support, @code{$_siginfo} may also be writable.
+@cindex Intel MPX boundary violations
+@cindex boundary violations, Intel MPX
+On some targets, a @code{SIGSEGV} can be caused by a boundary
+violation, i.e., accessing an address outside of the allowed range.
+In those cases @value{GDBN} may displays additional information,
+depending on how @value{GDBN} has been told to handle the signal.
+With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation
+kind: "Upper" or "Lower", the memory address accessed and the
+bounds, while with @code{handle nostop SIGSEGV} no additional
+information is displayed.
+
+The usual output of a segfault is:
+@smallexample
+Program received signal SIGSEGV, Segmentation fault
+0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
+68 value = *(p + len);
+@end smallexample
+
+While a bound violation is presented as:
+@smallexample
+Program received signal SIGSEGV, Segmentation fault
+Upper bound violation while accessing address 0x7fffffffc3b3
+Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3]
+0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68
+68 value = *(p + len);
+@end smallexample
+
@node Thread Stops
@section Stopping and Starting Multi-thread Programs
data. Further, the data is collected in a ring buffer so old data will
be overwritten when the buffer is full. It allows limited reverse
execution. Variables and registers are not available during reverse
-execution.
+execution. In remote debugging, recording continues on disconnect.
+Recorded data can be inspected after reconnecting. The recording may
+be stopped using @code{record stop}.
The recording format can be specified as parameter. Without a parameter
the command chooses the recording format. The following recording
@item @var{funcaddr}
An address of a function or procedure derived from its name. In C,
-C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
+C@t{++}, Objective-C, Fortran, minimal, and assembly, this is
simply the function's name @var{function} (and actually a special case
of a valid expression). In Pascal and Modula-2, this is
@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
location of the relocation table. On some architectures, @value{GDBN}
might be able to resolve these to actual function names.
+@table @code
+@kindex set disassembler-options
+@cindex disassembler options
+@item set disassembler-options @var{option1}[,@var{option2}@dots{}]
+This command controls the passing of target specific information to
+the disassembler. For a list of valid options, please refer to the
+@code{-M}/@code{--disassembler-options} section of the @samp{objdump}
+manual and/or the output of @kbd{objdump --help}
+(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}).
+The default value is the empty string.
+
+If it is necessary to specify more than one disassembler option, then
+multiple options can be placed together into a comma separated list.
+Currently this command is only supported on targets ARM, PowerPC
+and S/390.
+
+@kindex show disassembler-options
+@item show disassembler-options
+Show the current setting of the disassembler options.
+@end table
+
@table @code
@kindex set disassembly-flavor
@cindex Intel disassembly flavor
character set than GDB does
* Caching Target Data:: Data caching for targets
* Searching Memory:: Searching memory for a sequence of bytes
+* Value Sizes:: Managing memory allocated for values
@end menu
@node Expressions
@table @r
@item @var{n}, the repeat count
The repeat count is a decimal integer; the default is 1. It specifies
-how much memory (counting by units @var{u}) to display.
+how much memory (counting by units @var{u}) to display. If a negative
+number is specified, memory is examined backward from @var{addr}.
@c This really is **decimal**; unaffected by 'set radix' as of GDB
@c 4.1.2.
words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
+You can also specify a negative repeat count to examine memory backward
+from the given address. For example, @samp{x/-3uh 0x54320} prints three
+halfwords (@code{h}) at @code{0x54314}, @code{0x54328}, and @code{0x5431c}.
+
Since the letters indicating unit sizes are all distinct from the
letters specifying output formats, you do not have to remember whether
unit size or format comes first; either order works. The output
@code{disassemble} gives an alternative way of inspecting machine
instructions; see @ref{Machine Code,,Source and Machine Code}.
+If a negative repeat count is specified for the formats @samp{s} or @samp{i},
+the command displays null-terminated strings or instructions before the given
+address as many as the absolute value of the given number. For the @samp{i}
+format, we use line number information in the debug info to accurately locate
+instruction boundaries while disassembling backward. If line info is not
+available, the command stops examining memory with an error message.
+
All the defaults for the arguments to @code{x} are designed to make it
easy to continue scanning memory with minimal specifications each time
you use @code{x}. For example, after you have inspected three machine
@code{no} setting.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
frame specified by @var{number_of_frames}.
+@item $_as_string(@var{value})
+@findex $_as_string@r{, convenience function}
+Return the string representation of @var{value}.
+
+This function is useful to obtain the textual label (enumerator) of an
+enumeration value. For example, assuming the variable @var{node} is of
+an enumerated type:
+
+@smallexample
+(gdb) printf "Visiting node of type %s\n", $_as_string(node)
+Visiting node of type NODE_INTEGER
+@end smallexample
+
@end table
@value{GDBN} provides the ability to list and get help on
$2 = (void *) 0x8049560
@end smallexample
+@node Value Sizes
+@section Value Sizes
+
+Whenever @value{GDBN} prints a value memory will be allocated within
+@value{GDBN} to hold the contents of the value. It is possible in
+some languages with dynamic typing systems, that an invalid program
+may indicate a value that is incorrectly large, this in turn may cause
+@value{GDBN} to try and allocate an overly large ammount of memory.
+
+@table @code
+@kindex set max-value-size
+@item set max-value-size @var{bytes}
+@itemx set max-value-size unlimited
+Set the maximum size of memory that @value{GDBN} will allocate for the
+contents of a value to @var{bytes}, trying to display a value that
+requires more memory than that will result in an error.
+
+Setting this variable does not effect values that have already been
+allocated within @value{GDBN}, only future allocations.
+
+There's a minimum size that @code{max-value-size} can be set to in
+order that @value{GDBN} can still operate correctly, this minimum is
+currently 16 bytes.
+
+The limit applies to the results of some subexpressions as well as to
+complete expressions. For example, an expression denoting a simple
+integer component, such as @code{x.y.z}, may fail if the size of
+@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand,
+@value{GDBN} is sometimes clever; the expression @code{A[i]}, where
+@var{A} is an array variable with non-constant size, will generally
+succeed regardless of the bounds on @var{A}, as long as the component
+size is less than @var{bytes}.
+
+The default value of @code{max-value-size} is currently 64k.
+
+@kindex show max-value-size
+@item show max-value-size
+Show the maximum size of memory, in bytes, that @value{GDBN} will
+allocate for the contents of a value.
+@end table
+
@node Optimized Code
@chapter Debugging Optimized Code
@cindex optimized code, debugging
return address set up as if @code{B} called @code{C} normally.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
static void __attribute__((noinline, noclone)) c (void) @{ a (); @}
int main (void) @{ x (); return 0; @}
-Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find
-DW_TAG_GNU_call_site 0x40039a in main
+Breakpoint 1, DW_OP_entry_value resolving cannot find
+DW_TAG_call_site 0x40039a in main
a () at t.c:3
3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
(gdb) bt
(gdb) bt
#0 c (i=i@@entry=0) at t.c:2
-#1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found
+#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
function "a" at 0x400420 can call itself via tail calls
i=<optimized out>) at t.c:6
#2 0x000000000040036e in main () at t.c:7
Collect the return address. This is helpful if you want to see more
of a backtrace.
+@emph{Note:} The return address location can not always be reliably
+determined up front, and the wrong address / registers may end up
+collected instead. On some architectures the reliability is higher
+for tracepoints at function entry, while on others it's the opposite.
+When this happens, backtracing will stop because the return address is
+found unavailable (unless another collect rule happened to match it).
+
@item $_probe_argc
Collects the number of arguments from the static probe at which the
tracepoint is located.
Same as @samp{tfind none}.
@item tfind
-No argument means find the next trace snapshot.
+No argument means find the next trace snapshot or find the first
+one if no trace snapshot is selected.
@item tfind -
Find the previous trace snapshot before the current one. This permits
more efficient if the trace buffer is very large. (Note, however, that
@code{target tfile} can only read from files accessible to the host.)
By default, this command will save trace frame in tfile format.
-You can supply the optional argument @code{-ctf} to save date in CTF
+You can supply the optional argument @code{-ctf} to save data in CTF
format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format
that can be shared by multiple debugging and tracing tools. Please go to
@indicateurl{http://www.efficios.com/ctf} to get more information.
@node Supported Languages
@section Supported Languages
-@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java,
-OpenCL C, Pascal, assembly, Modula-2, and Ada.
+@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran,
+OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada.
@c This is false ...
Some @value{GDBN} features may be used in expressions regardless of the
language you use: the @value{GDBN} @code{@@} and @code{::} operators,
* OpenCL C:: OpenCL C
* Fortran:: Fortran
* Pascal:: Pascal
+* Rust:: Rust
* Modula-2:: Modula-2
* Ada:: Ada
@end menu
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C@t{++} references; you can use
-them in expressions just as you do in C@t{++} source---they are automatically
-dereferenced.
+@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue
+references; you can use them in expressions just as you do in C@t{++}
+source---they are automatically dereferenced.
In the parameter list shown when @value{GDBN} displays a frame, the values of
reference variables are not displayed (unlike other variables); this
controls whether static members of Pascal objects are displayed.
@xref{Print Settings, pascal_static-members}.
+@node Rust
+@subsection Rust
+
+@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust
+Programming Language}. Type- and value-printing, and expression
+parsing, are reasonably complete. However, there are a few
+peculiarities and holes to be aware of.
+
+@itemize @bullet
+@item
+Linespecs (@pxref{Specify Location}) are never relative to the current
+crate. Instead, they act as if there were a global namespace of
+crates, somewhat similar to the way @code{extern crate} behaves.
+
+That is, if @value{GDBN} is stopped at a breakpoint in a function in
+crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
+to set a breakpoint in a function named @samp{f} in a crate named
+@samp{B}.
+
+As a consequence of this approach, linespecs also cannot refer to
+items using @samp{self::} or @samp{super::}.
+
+@item
+Because @value{GDBN} implements Rust name-lookup semantics in
+expressions, it will sometimes prepend the current crate to a name.
+For example, if @value{GDBN} is stopped at a breakpoint in the crate
+@samp{K}, then @code{print ::x::y} will try to find the symbol
+@samp{K::x::y}.
+
+However, since it is useful to be able to refer to other crates when
+debugging, @value{GDBN} provides the @code{extern} extension to
+circumvent this. To use the extension, just put @code{extern} before
+a path expression to refer to the otherwise unavailable ``global''
+scope.
+
+In the above example, if you wanted to refer to the symbol @samp{y} in
+the crate @samp{x}, you would use @code{print extern x::y}.
+
+@item
+The Rust expression evaluator does not support ``statement-like''
+expressions such as @code{if} or @code{match}, or lambda expressions.
+
+@item
+Tuple expressions are not implemented.
+
+@item
+The Rust expression evaluator does not currently implement the
+@code{Drop} trait. Objects that may be created by the evaluator will
+never be destroyed.
+
+@item
+@value{GDBN} does not implement type inference for generics. In order
+to call generic functions or otherwise refer to generic items, you
+will have to specify the type parameters manually.
+
+@item
+@value{GDBN} currently uses the C@t{++} demangler for Rust. In most
+cases this does not cause any problems. However, in an expression
+context, completing a generic function name will give syntactically
+invalid results. This happens because Rust requires the @samp{::}
+operator between the function name and its generic arguments. For
+example, @value{GDBN} might provide a completion like
+@code{crate::f<u32>}, where the parser would require
+@code{crate::f::<u32>}.
+
+@item
+As of this writing, the Rust compiler (version 1.8) has a few holes in
+the debugging information it generates. These holes prevent certain
+features from being implemented by @value{GDBN}:
+@itemize @bullet
+
+@item
+Method calls cannot be made via traits.
+
+@item
+Trait objects cannot be created or inspected.
+
+@item
+Operator overloading is not implemented.
+
+@item
+When debugging in a monomorphized function, you cannot use the generic
+type names.
+
+@item
+The type @code{Self} is not available.
+
+@item
+@code{use} statements are not available, so some names may not be
+available in the crate.
+@end itemize
+@end itemize
+
@node Modula-2
@subsection Modula-2
@cindex partial symbol dump
@kindex maint print msymbols
@cindex minimal symbol dump
-@item maint print symbols @var{filename}
-@itemx maint print psymbols @var{filename}
-@itemx maint print msymbols @var{filename}
-Write a dump of debugging symbol data into the file @var{filename}.
-These commands are used to debug the @value{GDBN} symbol-reading code. Only
-symbols with debugging data are included. If you use @samp{maint print
-symbols}, @value{GDBN} includes all the symbols for which it has already
-collected full details: that is, @var{filename} reflects symbols for
-only those files whose symbols @value{GDBN} has read. You can use the
-command @code{info sources} to find out which files these are. If you
-use @samp{maint print psymbols} instead, the dump shows information about
-symbols that @value{GDBN} only knows partially---that is, symbols defined in
-files that @value{GDBN} has skimmed, but not yet read completely. Finally,
-@samp{maint print msymbols} dumps just the minimal symbol information
-required for each object file from which @value{GDBN} has read some symbols.
+@item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+@itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]}
+Write a dump of debugging symbol data into the file @var{filename} or
+the terminal if @var{filename} is unspecified.
+If @code{-objfile @var{objfile}} is specified, only dump symbols for
+that objfile.
+If @code{-pc @var{address}} is specified, only dump symbols for the file
+with code at that address. Note that @var{address} may be a symbol like
+@code{main}.
+If @code{-source @var{source}} is specified, only dump symbols for that
+source file.
+
+These commands are used to debug the @value{GDBN} symbol-reading code.
+These commands do not modify internal @value{GDBN} state, therefore
+@samp{maint print symbols} will only print symbols for already expanded symbol
+tables.
+You can use the command @code{info sources} to find out which files these are.
+If you use @samp{maint print psymbols} instead, the dump shows information
+about symbols that @value{GDBN} only knows partially---that is, symbols
+defined in files that @value{GDBN} has skimmed, but not yet read completely.
+Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g.,
+``ELF symbols''.
+
@xref{Files, ,Commands to Specify Files}, for a discussion of how
@value{GDBN} reads symbols (in the description of @code{symbol-file}).
(@value{GDBP})
@end smallexample
+@kindex maint info line-table
+@cindex listing @value{GDBN}'s internal line tables
+@cindex line tables, listing @value{GDBN}'s internal
+@item maint info line-table @r{[} @var{regexp} @r{]}
+
+List the @code{struct linetable} from all @code{struct symtab}
+instances whose name matches @var{regexp}. If @var{regexp} is not
+given, list the @code{struct linetable} from all @code{struct symtab}.
+
@kindex maint set symbol-cache-size
@cindex symbol cache size
@item maint set symbol-cache-size @var{size}
@table @code
-@kindex load @var{filename}
-@item load @var{filename}
+@kindex load @var{filename} @var{offset}
+@item load @var{filename} @var{offset}
@anchor{load}
Depending on what remote debugging facilities are configured into
@value{GDBN}, the @code{load} command may be available. Where it exists, it
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+It is also possible to tell @value{GDBN} to load the executable file at a
+specific offset described by the optional argument @var{offset}. When
+@var{offset} is provided, @var{filename} must also be provided.
+
Depending on the remote side capabilities, @value{GDBN} may be able to
load programs into flash memory.
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
+@table @code
+
+@kindex flash-erase
+@item flash-erase
+@anchor{flash-erase}
+
+Erases all known flash memory regions on the target.
+
+@end table
+
@node Byte Order
@section Choosing Target Byte Order
$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
@end smallexample
+@cindex @option{--selftest}
+The @option{--selftest} option runs the self tests in @code{gdbserver}:
+
+@smallexample
+$ gdbserver --selftest
+Ran 2 unit tests, 0 failed
+@end smallexample
+
+These tests are disabled in release.
@subsection Connecting to @code{gdbserver}
The basic procedure for connecting to the remote target is:
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+@item @code{startup-with-shell}
+@tab @code{QStartupWithShell}
+@tab @code{set startup-with-shell}
+
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
Thread Information Block (readable on the X86 CPU family using @code{$fs}
selector for 32-bit programs and @code{$gs} for 64-bit programs).
+@kindex signal-event
+@item signal-event @var{id}
+This command signals an event with user-provided @var{id}. Used to resume
+crashing process when attached to it using MS-Windows JIT debugging (AeDebug).
+
+To use it, create or edit the following keys in
+@code{HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug} and/or
+@code{HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug}
+(for x86_64 versions):
+
+@itemize @minus
+@item
+@code{Debugger} (REG_SZ) --- a command to launch the debugger.
+Suggested command is: @code{@var{fully-qualified-path-to-gdb.exe} -ex
+"attach %ld" -ex "signal-event %ld" -ex "continue"}.
+
+The first @code{%ld} will be replaced by the process ID of the
+crashing process, the second @code{%ld} will be replaced by the ID of
+the event that blocks the crashing process, waiting for @value{GDBN}
+to attach.
+
+@item
+@code{Auto} (REG_SZ) --- either @code{1} or @code{0}. @code{1} will
+make the system run debugger specified by the Debugger key
+automatically, @code{0} will cause a dialog box with ``OK'' and
+``Cancel'' buttons to appear, which allows the user to either
+terminate the crashing process (OK) or debug it (Cancel).
+@end itemize
+
@kindex set cygwin-exceptions
@cindex debugging the Cygwin DLL
@cindex Cygwin DLL, debugging
@menu
+* ARC:: Synopsys ARC
* ARM:: ARM
-* M32R/SDI:: Renesas M32R/SDI
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
* Super-H:: Renesas Super-H
@end menu
+@node ARC
+@subsection Synopsys ARC
+@cindex Synopsys ARC
+@cindex ARC specific commands
+@cindex ARC600
+@cindex ARC700
+@cindex ARC EM
+@cindex ARC HS
+
+@value{GDBN} provides the following ARC-specific commands:
+
+@table @code
+@item set debug arc
+@kindex set debug arc
+Control the level of ARC specific debug messages. Use 0 for no messages (the
+default), 1 for debug messages, and 2 for even more debug messages.
+
+@item show debug arc
+@kindex show debug arc
+Show the level of ARC specific debugging in operation.
+
+@item maint print arc arc-instruction @var{address}
+@kindex maint print arc arc-instruction
+Print internal disassembler information about instruction at a given address.
+
+@end table
+
@node ARM
@subsection ARM
@end table
@end table
-@node M32R/SDI
-@subsection Renesas M32R/SDI
-
-The following commands are available for M32R/SDI:
-
-@table @code
-@item sdireset
-@kindex sdireset
-@cindex reset SDI connection, M32R
-This command resets the SDI connection.
-
-@item sdistatus
-@kindex sdistatus
-This command shows the SDI connection status.
-
-@item debug_chaos
-@kindex debug_chaos
-@cindex M32R/Chaos debugging
-Instructs the remote that M32R/Chaos debugging is to be used.
-
-@item use_debug_dma
-@kindex use_debug_dma
-Instructs the remote to use the DEBUG_DMA method of accessing memory.
-
-@item use_mon_code
-@kindex use_mon_code
-Instructs the remote to use the MON_CODE method of accessing memory.
-
-@item use_ib_break
-@kindex use_ib_break
-Instructs the remote to set breakpoints by IB break.
-
-@item use_dbt_break
-@kindex use_dbt_break
-Instructs the remote to set breakpoints by DBT.
-@end table
-
@node M68K
@subsection M68k
@node MIPS Embedded
@subsection @acronym{MIPS} Embedded
-@cindex @acronym{MIPS} boards
-@value{GDBN} can use the @acronym{MIPS} remote debugging protocol to talk to a
-@acronym{MIPS} board attached to a serial line. This is available when
-you configure @value{GDBN} with @samp{--target=mips-elf}.
-
-@need 1000
-Use these @value{GDBN} commands to specify the connection to your target board:
-
-@table @code
-@item target mips @var{port}
-@kindex target mips @var{port}
-To run a program on the board, start up @code{@value{GDBP}} with the
-name of your program as the argument. To connect to the board, use the
-command @samp{target mips @var{port}}, where @var{port} is the name of
-the serial port connected to the board. If the program has not already
-been downloaded to the board, you may use the @code{load} command to
-download it. You can then use all the usual @value{GDBN} commands.
-
-For example, this sequence connects to the target board through a serial
-port, and loads and runs a program called @var{prog} through the
-debugger:
-
-@smallexample
-host$ @value{GDBP} @var{prog}
-@value{GDBN} is free software and @dots{}
-(@value{GDBP}) target mips /dev/ttyb
-(@value{GDBP}) load @var{prog}
-(@value{GDBP}) run
-@end smallexample
-
-@item target mips @var{hostname}:@var{portnumber}
-On some @value{GDBN} host configurations, you can specify a TCP
-connection (for instance, to a serial line managed by a terminal
-concentrator) instead of a serial port, using the syntax
-@samp{@var{hostname}:@var{portnumber}}.
-
-@item target pmon @var{port}
-@kindex target pmon @var{port}
-PMON ROM monitor.
-
-@item target ddb @var{port}
-@kindex target ddb @var{port}
-NEC's DDB variant of PMON for Vr4300.
-
-@item target lsi @var{port}
-@kindex target lsi @var{port}
-LSI variant of PMON.
-
-@end table
-
-
@noindent
-@value{GDBN} also supports these special commands for @acronym{MIPS} targets:
+@value{GDBN} supports these special commands for @acronym{MIPS} targets:
@table @code
@item set mipsfpu double
As usual, you can inquire about the @code{mipsfpu} variable with
@samp{show mipsfpu}.
-
-@item set timeout @var{seconds}
-@itemx set retransmit-timeout @var{seconds}
-@itemx show timeout
-@itemx show retransmit-timeout
-@cindex @code{timeout}, @acronym{MIPS} protocol
-@cindex @code{retransmit-timeout}, @acronym{MIPS} protocol
-@kindex set timeout
-@kindex show timeout
-@kindex set retransmit-timeout
-@kindex show retransmit-timeout
-You can control the timeout used while waiting for a packet, in the @acronym{MIPS}
-remote protocol, with the @code{set timeout @var{seconds}} command. The
-default is 5 seconds. Similarly, you can control the timeout used while
-waiting for an acknowledgment of a packet with the @code{set
-retransmit-timeout @var{seconds}} command. The default is 3 seconds.
-You can inspect both values with @code{show timeout} and @code{show
-retransmit-timeout}. (These commands are @emph{only} available when
-@value{GDBN} is configured for @samp{--target=mips-elf}.)
-
-The timeout set by @code{set timeout} does not apply when @value{GDBN}
-is waiting for your program to stop. In that case, @value{GDBN} waits
-forever because it has no way of knowing how long the program is going
-to run before stopping.
-
-@item set syn-garbage-limit @var{num}
-@kindex set syn-garbage-limit@r{, @acronym{MIPS} remote}
-@cindex synchronize with remote @acronym{MIPS} target
-Limit the maximum number of characters @value{GDBN} should ignore when
-it tries to synchronize with the remote target. The default is 10
-characters. Setting the limit to -1 means there's no limit.
-
-@item show syn-garbage-limit
-@kindex show syn-garbage-limit@r{, @acronym{MIPS} remote}
-Show the current limit on the number of characters to ignore when
-trying to synchronize with the remote system.
-
-@item set monitor-prompt @var{prompt}
-@kindex set monitor-prompt@r{, @acronym{MIPS} remote}
-@cindex remote monitor prompt
-Tell @value{GDBN} to expect the specified @var{prompt} string from the
-remote monitor. The default depends on the target:
-@table @asis
-@item pmon target
-@samp{PMON}
-@item ddb target
-@samp{NEC010}
-@item lsi target
-@samp{PMON>}
-@end table
-
-@item show monitor-prompt
-@kindex show monitor-prompt@r{, @acronym{MIPS} remote}
-Show the current strings @value{GDBN} expects as the prompt from the
-remote monitor.
-
-@item set monitor-warnings
-@kindex set monitor-warnings@r{, @acronym{MIPS} remote}
-Enable or disable monitor warnings about hardware breakpoints. This
-has effect only for the @code{lsi} target. When on, @value{GDBN} will
-display warning messages whose codes are returned by the @code{lsi}
-PMON monitor for breakpoint commands.
-
-@item show monitor-warnings
-@kindex show monitor-warnings@r{, @acronym{MIPS} remote}
-Show the current setting of printing monitor warnings.
-
-@item pmon @var{command}
-@kindex pmon@r{, @acronym{MIPS} remote}
-@cindex send PMON command
-This command allows sending an arbitrary @var{command} string to the
-monitor. The monitor must be in debug mode for this to work.
@end table
@node PowerPC Embedded
for lower and upper bounds respectively.
@end table
+When you call an inferior function on an Intel MPX enabled program,
+GDB sets the inferior's bound registers to the init (disabled) state
+before calling the function. As a consequence, bounds checks for the
+pointer arguments passed to the function will always pass.
+
+This is necessary because when you call an inferior function, the
+program is usually in the middle of the execution of other function.
+Since at that point bound registers are in an arbitrary state, not
+clearing them would lead to random bound violations in the called
+function.
+
+You can still examine the influence of the bound registers on the
+execution of the called function by stopping the execution of the
+called function at its prologue, setting bound registers, and
+continuing the execution. For example:
+
+@smallexample
+ $ break *upper
+ Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47.
+ $ print upper (a, b, c, d, 1)
+ Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48)....
+ $ print $bnd0
+ @{lbound = 0x0, ubound = ffffffff@} : size -1
+@end smallexample
+
+At this last step the value of bnd0 can be changed for investigation of bound
+violations caused along the execution of the call. In order to know how to
+set the bound registers or bound table for the call consult the ABI.
+
@node Alpha
@subsection Alpha
@value{GDBN} standard output stream. The default is off.
@item show debug remote
Displays the state of display of remote packets.
+
+@item set debug separate-debug-file
+Turns on or off display of debug output about separate debug file search.
+@item show debug separate-debug-file
+Displays the state of separate debug file search debug output.
+
@item set debug serial
Turns on or off display of @value{GDBN} serial debugging info. The
default is off.
@cindex arguments, to user-defined commands
A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
which you assign a new name as a command. This is done with the
-@code{define} command. User commands may accept up to 10 arguments
+@code{define} command. User commands may accept an unlimited number of arguments
separated by whitespace. Arguments are accessed within the user command
-via @code{$arg0@dots{}$arg9}. A trivial example:
+via @code{$arg0@dots{}$argN}. A trivial example:
@smallexample
define adder
@cindex argument count in user-defined commands
@cindex how many arguments (user-defined commands)
In addition, @code{$argc} may be used to find out how many arguments have
-been passed. This expands to a number in the range 0@dots{}10.
+been passed.
@smallexample
define adder
end
@end smallexample
+Combining with the @code{eval} command (@pxref{eval}) makes it easier
+to process a variable number of arguments:
+
+@smallexample
+define adder
+ set $i = 0
+ set $sum = 0
+ while $i < $argc
+ eval "set $sum = $sum + $arg%d", $i
+ set $i = $i + 1
+ end
+ print $sum
+end
+@end smallexample
+
@table @code
@kindex define
printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
@end smallexample
+@anchor{eval}
@kindex eval
@item eval @var{template}, @var{expressions}@dots{}
Convert the values of one or more @var{expressions} under the control of
@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:
+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"
@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).
+Note that @code{interpreter-exec} only changes the interpreter for the
+duration of the specified command. It does not change the interpreter
+permanently.
+
+@cindex start a new independent interpreter
+
+Although you may only choose a single interpreter at startup, it is
+possible to run an independent interpreter on a specified input/output
+device (usually a tty).
+
+For example, consider a debugger GUI or IDE that wants to provide a
+@value{GDBN} console view. It may do so by embedding a terminal
+emulator widget in its GUI, starting @value{GDBN} in the traditional
+command-line mode with stdin/stdout/stderr redirected to that
+terminal, and then creating an MI interpreter running on a specified
+input/output device. The console interpreter created by @value{GDBN}
+at startup handles commands the user types in the terminal widget,
+while the GUI controls and synchronizes state with @value{GDBN} using
+the separate MI interpreter.
+
+To start a new secondary @dfn{user interface} running MI, use the
+@code{new-ui} command:
+
+@kindex new-ui
+@cindex new user interface
+@smallexample
+new-ui @var{interpreter} @var{tty}
+@end smallexample
+
+The @var{interpreter} parameter specifies the interpreter to run.
+This accepts the same values as the @code{interpreter-exec} command.
+For example, @samp{console}, @samp{mi}, @samp{mi2}, etc. The
+@var{tty} parameter specifies the name of the bidirectional file the
+interpreter uses for input/output, usually the name of a
+pseudoterminal slave on Unix systems. For example:
+
+@smallexample
+(@value{GDBP}) new-ui mi /dev/pts/9
+@end smallexample
+
+@noindent
+runs an MI interpreter on @file{/dev/pts/9}.
+
@node TUI
@chapter @value{GDBN} Text User Interface
@cindex TUI
@item n
next
+@kindex o @r{(SingleKey TUI key)}
+@item o
+nexti. The shortcut letter @samp{o} stands for ``step Over''.
+
@kindex q @r{(SingleKey TUI key)}
@item q
exit the SingleKey mode.
@item s
step
+@kindex i @r{(SingleKey TUI key)}
+@item i
+stepi. The shortcut letter @samp{i} stands for ``step Into''.
+
@kindex u @r{(SingleKey TUI key)}
@item u
up
Usually, each top-level window in a frontend allows the user to select
a thread and a frame, and remembers the user selection for further
operations. However, in some cases @value{GDBN} may suggest that the
-current thread be changed. For example, when stopping on a breakpoint
-it is reasonable to switch to the thread where breakpoint is hit. For
-another example, if the user issues the CLI @samp{thread} command via
-the frontend, it is desirable to change the frontend's selected thread to the
-one specified by user. @value{GDBN} communicates the suggestion to
-change current thread using the @samp{=thread-selected} notification.
-No such notification is available for the selected frame at the moment.
+current thread or frame be changed. For example, when stopping on a
+breakpoint it is reasonable to switch to the thread where breakpoint is
+hit. For another example, if the user issues the CLI @samp{thread} or
+@samp{frame} commands via the frontend, it is desirable to change the
+frontend's selection to the one specified by user. @value{GDBN}
+communicates the suggestion to change current thread and frame using the
+@samp{=thread-selected} notification.
Note that historically, MI shares the selected thread with CLI, so
frontends used the @code{-thread-select} to execute commands in the
contains the global @value{GDBN} identifier of the thread. The @var{gid}
field identifies the thread group this thread belongs to.
-@item =thread-selected,id="@var{id}"
-Informs that the selected thread was changed as result of the last
-command. This notification is not emitted as result of @code{-thread-select}
-command but is emitted whenever an MI command that is not documented
-to change the selected thread actually changes it. In particular,
-invoking, directly or indirectly (via user-defined command), the CLI
-@code{thread} command, will generate this notification.
+@item =thread-selected,id="@var{id}"[,frame="@var{frame}"]
+Informs that the selected thread or frame were changed. This notification
+is not emitted as result of the @code{-thread-select} or
+@code{-stack-select-frame} commands, but is emitted whenever an MI command
+that is not documented to change the selected thread and frame actually
+changes them. In particular, invoking, directly or indirectly
+(via user-defined command), the CLI @code{thread} or @code{frame} commands,
+will generate this notification. Changing the thread or frame from another
+user interface (see @ref{Interpreters}) will also generate this notification.
+
+The @var{frame} field is only present if the newly selected thread is
+stopped. See @ref{GDB/MI Frame Information} for the format of its value.
We suggest that in response to this notification, front ends
highlight the selected thread and cause subsequent commands to apply to
@item =library-loaded,...
Reports that a new library file was loaded by the program. This
-notification has 4 fields---@var{id}, @var{target-name},
-@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
+notification has 5 fields---@var{id}, @var{target-name},
+@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an
opaque identifier of the library. For remote debugging case,
@var{target-name} and @var{host-name} fields give the name of the
library file on the target, and on the host respectively. For native
@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.
+thread groups. The @var{ranges} field specifies the ranges of addresses belonging
+to this library.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
Note that if a breakpoint is emitted in the result record of a
command, then it will not also be emitted in an async record.
-@item =record-started,thread-group="@var{id}"
+@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"]
@itemx =record-stopped,thread-group="@var{id}"
Execution log recording was either started or stopped on an
inferior. The @var{id} is the @value{GDBN} identifier of the thread
group corresponding to the affected inferior.
+The @var{method} field indicates the method used to record execution. If the
+method in use supports multiple recording formats, @var{format} will be present
+and contain the currently used format. @xref{Process Record and Replay},
+for existing method and format values.
+
@item =cmd-param-changed,param=@var{param},value=@var{value}
Reports that a parameter of the command @code{set @var{param}} is
changed to @var{value}. In the multi-word @code{set} command,
@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:
+uses a tuple with the following fields. The fields are always present unless
+stated otherwise.
@table @code
@item id
-The global numeric id assigned to the thread by @value{GDBN}. This field is
-always present.
+The global numeric id assigned to the thread by @value{GDBN}.
@item target-id
-Target-specific string identifying the thread. This field is always present.
+The target-specific string identifying the thread.
@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 name
+The name of the thread. If the user specified a name using the
+@code{thread name} command, then this name is given. Otherwise, if
+@value{GDBN} can extract the thread name from the target, then that
+name is given. If @value{GDBN} cannot find the thread name, then this
+field is omitted.
+
@item state
-Either @samp{stopped} or @samp{running}, depending on whether the
-thread is presently running. This field is always present.
+The execution state of the thread, either @samp{stopped} or @samp{running},
+depending on whether the thread is presently running.
+
+@item frame
+The stack frame currently executing in the thread. This field is only present
+if the thread is stopped. Its format is documented in
+@ref{GDB/MI Frame Information}.
@item core
The value of this field is an integer number of the processor core the
@subsubheading Result
-The result is a list of threads. The following attributes are
-defined for a given thread:
+The result contains the following attributes:
@table @samp
-@item current
-This field exists only for the current thread. It has the value @samp{*}.
-
-@item id
-The global identifier that @value{GDBN} uses to refer to the thread.
-
-@item target-id
-The identifier that the target uses to refer to the thread.
-
-@item details
-Extra information about the thread, in a target-specific format. This
-field is optional.
-
-@item name
-The name of the thread. If the user specified a name using the
-@code{thread name} command, then this name is given. Otherwise, if
-@value{GDBN} can extract the thread name from the target, then that
-name is given. If @value{GDBN} cannot find the thread name, then this
-field is omitted.
-
-@item frame
-The stack frame currently executing in the thread.
-
-@item state
-The thread's state. The @samp{state} field may have the following
-values:
-
-@table @code
-@item stopped
-The thread is stopped. Frame information is available for stopped
-threads.
-
-@item running
-The thread is running. There's no frame information for running
-threads.
-
-@end table
+@item threads
+A list of threads. The format of the elements of the list is described in
+@ref{GDB/MI Thread Information}.
-@item core
-If @value{GDBN} can find the CPU core on which this thread is running,
-then this field is the core identifier. This field is optional.
+@item current-thread-id
+The global id of the currently selected thread. This field is omitted if there
+is no selected thread (for example, when the selected inferior is not running,
+and therefore has no threads) or if a @var{thread-id} argument was passed to
+the command.
@end table
@subsubheading Synopsis
@smallexample
- -trace-save [-r ] @var{filename}
+ -trace-save [ -r ] [ -ctf ] @var{filename}
@end smallexample
Saves the collected trace data to @var{filename}. Without the
in a local file. With the @samp{-r} option the target is asked
to perform the save.
+By default, this command will save the trace in the tfile format. You can
+supply the optional @samp{-ctf} argument to save it the CTF format. See
+@ref{Trace Files} for more information about CTF.
+
@subsubheading @value{GDBN} Command
The corresponding @value{GDBN} command is @samp{tsave}.
-trace-start
@end smallexample
-Starts a tracing experiments. The result of this command does not
+Starts a tracing experiment. The result of this command does not
have any fields.
@subsubheading @value{GDBN} Command
(gdb)
@end smallexample
-@ignore
@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -file-list-shared-libraries [ @var{regexp} ]
@end smallexample
List the shared libraries in the program.
+With a regular expression @var{regexp}, only those libraries whose
+names match @var{regexp} are listed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info shared}.
+The corresponding @value{GDBN} command is @samp{info shared}. The fields
+have a similar meaning to the @code{=library-loaded} notification.
+The @code{ranges} field specifies the multiple segments belonging to this
+library. Each range has the following fields:
+
+@table @samp
+@item from
+The address defining the inclusive lower bound of the segment.
+@item to
+The address defining the exclusive upper bound of the segment.
+@end table
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-list-exec-source-files
+^done,shared-libraries=[
+@{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@},
+@{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}]
+(gdb)
+@end smallexample
+@ignore
@subheading The @code{-file-list-symbol-files} Command
@findex -file-list-symbol-files
@subsubheading Example
N.A.
+@subheading The @code{-target-flash-erase} Command
+@findex -target-flash-erase
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-flash-erase
+@end smallexample
+
+Erases all known flash memory regions on the target.
+
+The corresponding @value{GDBN} command is @samp{flash-erase}.
+
+The output is a list of flash regions that have been erased, with starting
+addresses and memory region sizes.
+
+@smallexample
+(gdb)
+-target-flash-erase
+^done,erased-regions=@{address="0x0",size="0x40000"@}
+(gdb)
+@end smallexample
@subheading The @code{-target-select} Command
@findex -target-select
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
-@kindex maint print c-tdesc
+@kindex maint print c-tdesc @r{[}@var{file}@r{]}
@item maint print c-tdesc
-Print the current target description (@pxref{Target Descriptions}) as
-a C source file. The created source file can be used in @value{GDBN}
-when an XML parser is not available to parse the description.
+Print the target description (@pxref{Target Descriptions}) as
+a C source file. By default, the target description is for the current
+target, but if the optional argument @var{file} is provided, that file
+is used to produce the description. The @var{file} should be an XML
+document, of the form described in @ref{Target Description Format}.
+The created source file is built into @value{GDBN} when @value{GDBN} is
+built again. This command is used by developers after they add or
+modify XML target descriptions.
+
+@kindex maint check xml-descriptions
+@item maint check xml-descriptions @var{dir}
+Check that the target descriptions dynamically created by @value{GDBN}
+equal the descriptions created from XML files found in @var{dir}.
@kindex maint print dummy-frames
@item maint print dummy-frames
a recursive definition of the data type as stored in @value{GDBN}'s
data structures, including its flags and contained types.
+@kindex maint selftest
+@cindex self tests
+Run any self tests that were compiled in to @value{GDBN}. This will
+print a message showing how many tests were run, and how many failed.
+
@kindex maint set dwarf always-disassemble
@kindex maint show dwarf always-disassemble
@item maint set dwarf always-disassemble
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
determined by the @value{GDBN} internal gdbarch functions
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
-specification of several standard @samp{g} packets is specified below.
+@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
When reading registers from a trace frame (@pxref{Analyze Collected
Data,,Using the Collected Data}), the stub may also return a string of
@cindex @samp{vCont} packet
@anchor{vCont packet}
Resume the inferior, specifying different actions for each thread.
-If an action is specified with no @var{thread-id}, then it is applied to any
-threads that don't have a specific action specified; if no default action is
-specified then other threads should remain stopped in all-stop mode and
-in their current state in non-stop mode.
-Specifying multiple
-default actions is an error; specifying no actions is also an error.
-Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
+
+For each inferior thread, the leftmost action with a matching
+@var{thread-id} is applied. Threads that don't match any action
+remain in their current state. Thread IDs are specified using the
+syntax described in @ref{thread-id syntax}. If multiprocess
+extensions (@pxref{multiprocess extensions}) are supported, actions
+can be specified to match all threads in a process by using the
+@samp{p@var{pid}.-1} form of the @var{thread-id}. An action with no
+@var{thread-id} matches all threads. Specifying no actions is an
+error.
Currently supported actions are:
signal @samp{0}, regardless of whether the target uses some other signal
as an implementation detail.
+The server must ignore @samp{c}, @samp{C}, @samp{s}, @samp{S}, and
+@samp{r} actions for threads that are already running. Conversely,
+the server must ignore @samp{t} actions for threads that are already
+stopped.
+
+@emph{Note:} In non-stop mode, a thread is considered running until
+@value{GDBN} acknowleges an asynchronous stop notification for it with
+the @samp{vStopped} packet (@pxref{Remote Non-Stop}).
+
The stub must support @samp{vCont} if it reports support for
-multiprocess extensions (@pxref{multiprocess extensions}). Note that in
-this case @samp{vCont} actions can be specified to apply to all threads
-in a process by using the @samp{p@var{pid}.-1} form of the
-@var{thread-id}.
+multiprocess extensions (@pxref{multiprocess extensions}).
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
for success
@end table
+@item vMustReplyEmpty
+@cindex @samp{vMustReplyEmpty} packet
+The correct reply to an unknown @samp{v} packet is to return the empty
+string, however, some older versions of @command{gdbserver} would
+incorrectly return @samp{OK} for unknown @samp{v} packets.
+
+The @samp{vMustReplyEmpty} is used as a feature test to check how
+@command{gdbserver} handles unknown packets, it is important that this
+packet be handled in the same way as other unknown @samp{v} packets.
+If this packet is handled differently to other unknown @samp{v}
+packets then it is possile that @value{GDBN} may run into problems in
+other areas, specifically around use of @samp{vFile:setfs:}.
+
@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
@cindex @samp{vRun} packet
Run the program @var{filename}, passing it each @var{argument} on its
@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
@cindex @samp{z0} packet
@cindex @samp{Z0} packet
-Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
+Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address
@var{addr} of type @var{kind}.
-A memory breakpoint is implemented by replacing the instruction at
+A software breakpoint is implemented by replacing the instruction at
@var{addr} with a software breakpoint or trap instruction. The
-@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};
-@var{cond_list} is an optional list of conditional expressions in bytecode
-form that should be evaluated on the target's side. These are the
-conditions that should be taken into consideration when deciding if
-the breakpoint trigger should be reported back to @var{GDBN}.
+@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}
+(@pxref{Architecture-Specific Protocol Details}); if no
+architecture-specific value is being used, it should be @samp{0}.
+@var{kind} is hex-encoded. @var{cond_list} is an optional list of
+conditional expressions in bytecode form that should be evaluated on
+the target's side. These are the conditions that should be taken into
+consideration when deciding if the breakpoint trigger should be
+reported back to @value{GDBN}.
See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason})
-for how to best report a memory breakpoint event to @value{GDBN}.
+for how to best report a software breakpoint event to @value{GDBN}.
The @var{cond_list} parameter is comprised of a series of expressions,
concatenated without separators. Each expression has the following form:
@item X @var{len},@var{expr}
@var{len} is the length of the bytecode expression and @var{expr} is the
-actual conditional expression in bytecode form.
+actual commands expression in bytecode form.
@end table
-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
+code that contains software breakpoints (e.g., when implementing
overlays). The behavior of this packet, in the presence of such a
target, is not defined.}
@end table
@item z1,@var{addr},@var{kind}
-@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}
+@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]}
@cindex @samp{z1} packet
@cindex @samp{Z1} packet
Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory. The @var{kind}
-and @var{cond_list} have the same meaning as in @samp{Z0} packets.
+dependent on being able to modify the target's memory. The
+@var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the
+same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
movement.}
number} is defined by the header @file{include/gdb/signals.h} in the
@value{GDBN} source code.
+In non-stop mode, the server will simply reply @samp{OK} to commands
+such as @samp{vCont}; any stop will be the subject of a future
+notification. @xref{Remote Non-Stop}.
+
As in the description of request packets, we include spaces in the
reply templates for clarity; these are not part of the reply packet's
syntax. No @value{GDBN} stop reply packet uses spaces to separate its
@item swbreak
@anchor{swbreak stop reason}
-The packet indicates a memory breakpoint instruction was executed,
+The packet indicates a software breakpoint instruction was executed,
irrespective of whether it was @value{GDBN} that planted the
breakpoint or the breakpoint is hardcoded in the program. The @var{r}
part must be left empty.
is stopped until @value{GDBN} sets it running with a resumption packet
(@pxref{vCont packet}). This packet should not be sent by default;
@value{GDBN} requests it with the @ref{QThreadEvents} packet. See
-also the @samp{w} (@ref{thread exit event}) remote reply below.
+also the @samp{w} (@pxref{thread exit event}) remote reply below. The
+@var{r} part is ignored.
@end table
The process exited, and @var{AA} is the exit status. This is only
applicable to certain targets.
-The second form of the response, including the process ID of the exited
-process, can be used only when @value{GDBN} has reported support for
-multiprocess protocol extensions; see @ref{multiprocess extensions}.
-The @var{pid} is formatted as a big-endian hex string.
+The second form of the response, including the process ID of the
+exited process, can be used only when @value{GDBN} has reported
+support for multiprocess protocol extensions; see @ref{multiprocess
+extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
+hex strings.
@item X @var{AA}
@itemx X @var{AA} ; process:@var{pid}
The second form of the response, including the process ID of the
terminated process, can be used only when @value{GDBN} has reported
support for multiprocess protocol extensions; see @ref{multiprocess
-extensions}. The @var{pid} is formatted as a big-endian hex string.
+extensions}. Both @var{AA} and @var{pid} are formatted as big-endian
+hex strings.
@anchor{thread exit event}
@cindex thread exit event, remote reply
The thread exited, and @var{AA} is the exit status. This response
should not be sent by default; @value{GDBN} requests it with the
@ref{QThreadEvents} packet. See also @ref{thread create event} above.
+@var{AA} is formatted as a big-endian hex string.
@item N
There are no resumed threads left in the target. In other words, even
This should only be done on targets that actually support disabling
address space randomization.
+@item QStartupWithShell:@var{value}
+@cindex startup with shell, remote request
+@cindex @samp{QStartupWithShell} packet
+On UNIX-like targets, it is possible to start the inferior using a
+shell program. This is the default behavior on both @value{GDBN} and
+@command{gdbserver} (@pxref{set startup-with-shell}). This packet is
+used to inform @command{gdbserver} whether it should start the
+inferior using a shell or not.
+
+If @var{value} is @samp{0}, @command{gdbserver} will not use a shell
+to start the inferior. If @var{value} is @samp{1},
+@command{gdbserver} will use a shell to start the inferior. All other
+values are considered an error.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support starting the inferior using a shell.
+
+Use of this packet is controlled by the @code{set startup-with-shell}
+command; @pxref{set startup-with-shell}.
+
@item qfThreadInfo
@itemx qsThreadInfo
@cindex list active threads, remote request
encoding of @var{annex} is specific to @var{object}; it can supply
additional details about what data to access.
-Here are the specific requests of this form defined so far. All
+Reply:
+@table @samp
+@item m @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the
+target. There may be more data at a higher address (although
+it is permitted to return @samp{m} even for the last valid
+block of data, as long as at least one byte of data was read).
+It is possible for @var{data} to have fewer bytes than the @var{length} in the
+request.
+
+@item l @var{data}
+Data @var{data} (@pxref{Binary Data}) has been read from the target.
+There is no more data to be read. It is possible for @var{data} to
+have fewer bytes than the @var{length} in the request.
+
+@item l
+The @var{offset} in the request is at the end of the data.
+There is no more data to be read.
+
+@item E00
+The request was malformed, or @var{annex} was invalid.
+
+@item E @var{nn}
+The offset was invalid, or there was an error encountered reading the data.
+The @var{nn} part is a hex-encoded @code{errno} value.
+
+@item @w{}
+An empty reply indicates the @var{object} string was not recognized by
+the stub, or that the object does not support reading.
+@end table
+
+Here are the specific requests of this form defined so far. All the
@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
-formats, listed below.
+formats, listed above.
@table @samp
@item qXfer:auxv:read::@var{offset},@var{length}
@end table
+@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
+@cindex write data into object, remote request
+@anchor{qXfer write}
+Write uninterpreted bytes into the target's special data area
+identified by the keyword @var{object}, starting at @var{offset} bytes
+into the data. The binary-encoded data (@pxref{Binary Data}) to be
+written is given by @var{data}@dots{}. The content and encoding of @var{annex}
+is specific to @var{object}; it can supply additional details about what data
+to access.
+
Reply:
@table @samp
-@item m @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the
-target. There may be more data at a higher address (although
-it is permitted to return @samp{m} even for the last valid
-block of data, as long as at least one byte of data was read).
-It is possible for @var{data} to have fewer bytes than the @var{length} in the
-request.
-
-@item l @var{data}
-Data @var{data} (@pxref{Binary Data}) has been read from the target.
-There is no more data to be read. It is possible for @var{data} to
-have fewer bytes than the @var{length} in the request.
-
-@item l
-The @var{offset} in the request is at the end of the data.
-There is no more data to be read.
+@item @var{nn}
+@var{nn} (hex encoded) is the number of bytes written.
+This may be fewer bytes than supplied in the request.
@item E00
The request was malformed, or @var{annex} was invalid.
@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
+The offset was invalid, or there was an error encountered writing the data.
The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
-An empty reply indicates the @var{object} string was not recognized by
-the stub, or that the object does not support reading.
+An empty reply indicates the @var{object} string was not
+recognized by the stub, or that the object does not support writing.
@end table
-@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@cindex write data into object, remote request
-@anchor{qXfer write}
-Write uninterpreted bytes into the target's special data area
-identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. The binary-encoded data (@pxref{Binary Data}) to be
-written is given by @var{data}@dots{}. The content and encoding of @var{annex}
-is specific to @var{object}; it can supply additional details about what data
-to access.
-
-Here are the specific requests of this form defined so far. All
+Here are the specific requests of this form defined so far. All the
@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
-formats, listed below.
+formats, listed above.
@table @samp
@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
-Reply:
-@table @samp
-@item @var{nn}
-@var{nn} (hex encoded) is the number of bytes written.
-This may be fewer bytes than supplied in the request.
-
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered writing the data.
-The @var{nn} part is a hex-encoded @code{errno} value.
-
-@item @w{}
-An empty reply indicates the @var{object} string was not
-recognized by the stub, or that the object does not support writing.
-@end table
-
@item qXfer:@var{object}:@var{operation}:@dots{}
Requests of this form may be added in the future. When a stub does
not recognize the @var{object} keyword, or its support for
The process of asynchronous notification can be illustrated by the
following example:
@smallexample
-<- @code{%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
+<- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;}
@code{...}
-> @code{vStopped}
<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;}
* Target Description Format:: The contents of a target description.
* Predefined Target Types:: Standard types available for target
descriptions.
+* Enum Target Types:: How to define enum target types.
* Standard Target Features:: Features @value{GDBN} knows about.
@end menu
interpret. The default interpretation is a two's complement integer,
but other types can be requested by name in the register description.
Some predefined types are provided by @value{GDBN} (@pxref{Predefined
-Target Types}), and the description can define additional composite types.
+Target Types}), and the description can define additional composite
+and enum types.
Each type element must have an @samp{id} attribute, which gives
a unique (within the containing @samp{<feature>}) name to the type.
@end smallexample
@cindex <struct>
+@cindex <flags>
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.
+it with either a structure type or a flags type.
+A flags type may only contain bitfields.
+A structure type may either contain only bitfields or contain no bitfields.
+If the value contains only bitfields, its total size in bytes must be
+specified.
+
+Non-bitfield values have a @var{name} and @var{type}.
@smallexample
-<struct id="@var{id}" size="@var{size}">
- <field name="@var{name}" start="@var{start}" end="@var{end}"/>
+<struct id="@var{id}">
+ <field name="@var{name}" type="@var{type}"/>
@dots{}
</struct>
@end smallexample
-If the structure contains no bitfields, then each field has an
-explicit type, and no implicit padding is added.
+Both @var{name} and @var{type} values are required.
+No implicit padding is added.
+
+Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}.
@smallexample
-<struct id="@var{id}">
- <field name="@var{name}" type="@var{type}"/>
+<struct id="@var{id}" size="@var{size}">
+ <field name="@var{name}" start="@var{start}" end="@var{end}" 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}"/>
+ <field name="@var{name}" start="@var{start}" end="@var{end}" type="@var{type}"/>
@dots{}
</flags>
@end smallexample
+The @var{name} value is required.
+Bitfield values may be named with the empty string, @samp{""},
+in which case the field is ``filler'' and its value is not printed.
+Not all bits need to be specified, so ``filler'' fields are optional.
+
+The @var{start} and @var{end} values are required, and @var{type}
+is optional.
+The field's @var{start} must be less than or equal to its @var{end},
+and zero represents the least significant bit.
+
+The default value of @var{type} is @code{bool} for single bit fields,
+and an unsigned integer otherwise.
+
+Which to choose? Structures or flags?
+
+Registers defined with @samp{flags} have these advantages over
+defining them with @samp{struct}:
+
+@itemize @bullet
+@item
+Arithmetic may be performed on them as if they were integers.
+@item
+They are printed in a more readable fashion.
+@end itemize
+
+Registers defined with @samp{struct} have one advantage over
+defining them with @samp{flags}:
+
+@itemize @bullet
+@item
+One can fetch individual fields like in @samp{C}.
+
+@smallexample
+(gdb) print $my_struct_reg.field3
+$1 = 42
+@end smallexample
+
+@end itemize
+
@subsection Registers
@cindex <reg>
@table @code
+@item bool
+Boolean type, occupying a single bit.
+
@item int8
@itemx int16
@itemx int32
@end table
+@node Enum Target Types
+@section Enum Target Types
+@cindex target descriptions, enum types
+
+Enum target types are useful in @samp{struct} and @samp{flags}
+register descriptions. @xref{Target Description Format}.
+
+Enum types have a name, size and a list of name/value pairs.
+
+@smallexample
+<enum id="@var{id}" size="@var{size}">
+ <evalue name="@var{name}" value="@var{value}"/>
+ @dots{}
+</enum>
+@end smallexample
+
+Enums must be defined before they are used.
+
+@smallexample
+<enum id="levels_type" size="4">
+ <evalue name="low" value="0"/>
+ <evalue name="high" value="1"/>
+</enum>
+<flags id="flags_type" size="4">
+ <field name="X" start="0"/>
+ <field name="LEVEL" start="1" end="1" type="levels_type"/>
+</flags>
+<reg name="flags" bitsize="32" type="flags_type"/>
+@end smallexample
+
+Given that description, a value of 3 for the @samp{flags} register
+would be printed as:
+
+@smallexample
+(gdb) info register flags
+flags 0x3 [ X LEVEL=high ]
+@end smallexample
+
@node Standard Target Features
@section Standard Target Features
@cindex target descriptions, standard features
@menu
* AArch64 Features::
+* ARC Features::
* ARM Features::
* i386 Features::
* MicroBlaze Features::
* MIPS Features::
* M68K Features::
+* NDS32 Features::
* Nios II Features::
* PowerPC Features::
* S/390 and System z Features::
+* Sparc Features::
* TIC6x Features::
@end menu
it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
and @samp{fpcr}.
+@node ARC Features
+@subsection ARC Features
+@cindex target descriptions, ARC Features
+
+ARC processors are highly configurable, so even core registers and their number
+are not completely predetermined. In addition flags and PC registers which are
+important to @value{GDBN} are not ``core'' registers in ARC. It is required
+that one of the core registers features is present.
+@samp{org.gnu.gdb.arc.aux-minimal} feature is mandatory.
+
+The @samp{org.gnu.gdb.arc.core.v2} feature is required for ARC EM and ARC HS
+targets with a normal register file. It should contain registers @samp{r0}
+through @samp{r25}, @samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}, @samp{blink},
+@samp{lp_count} and @samp{pcl}. This feature may contain register @samp{ilink}
+and any of extension core registers @samp{r32} through @samp{r59/acch}.
+@samp{ilink} and extension core registers are not available to read/write, when
+debugging GNU/Linux applications, thus @samp{ilink} is made optional.
+
+The @samp{org.gnu.gdb.arc.core-reduced.v2} feature is required for ARC EM and
+ARC HS targets with a reduced register file. It should contain registers
+@samp{r0} through @samp{r3}, @samp{r10} through @samp{r15}, @samp{gp},
+@samp{fp}, @samp{sp}, @samp{r30}, @samp{blink}, @samp{lp_count} and @samp{pcl}.
+This feature may contain register @samp{ilink} and any of extension core
+registers @samp{r32} through @samp{r59/acch}.
+
+The @samp{org.gnu.gdb.arc.core.arcompact} feature is required for ARCompact
+targets with a normal register file. It should contain registers @samp{r0}
+through @samp{r25}, @samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}, @samp{blink},
+@samp{lp_count} and @samp{pcl}. This feature may contain registers
+@samp{ilink1}, @samp{ilink2} and any of extension core registers @samp{r32}
+through @samp{r59/acch}. @samp{ilink1} and @samp{ilink2} and extension core
+registers are not available when debugging GNU/Linux applications. The only
+difference with @samp{org.gnu.gdb.arc.core.v2} feature is in the names of
+@samp{ilink1} and @samp{ilink2} registers and that @samp{r30} is mandatory in
+ARC v2, but @samp{ilink2} is optional on ARCompact.
+
+The @samp{org.gnu.gdb.arc.aux-minimal} feature is required for all ARC
+targets. It should contain registers @samp{pc} and @samp{status32}.
+
@node ARM Features
@subsection ARM Features
@cindex target descriptions, ARM features
The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
describe a single register, @samp{orig_eax}.
+The @samp{org.gnu.gdb.i386.segments} feature is optional. It should
+describe two system registers: @samp{fs_base} and @samp{gs_base}.
+
The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the
@samp{org.gnu.gdb.i386.avx} feature. It should
describe additional @sc{xmm} registers:
@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
@end itemize
+The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should
+describe a single register, @samp{pkru}. It is a 32-bit register
+valid for i386 and amd64.
+
@node MicroBlaze Features
@subsection MicroBlaze Features
@cindex target descriptions, MicroBlaze features
@samp{fpiaddr}.
@end table
+@node NDS32 Features
+@subsection NDS32 Features
+@cindex target descriptions, NDS32 features
+
+The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32
+targets. It should contain at least registers @samp{r0} through
+@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp},
+and @samp{pc}.
+
+The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present,
+it should contain 64-bit double-precision floating-point registers
+@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7},
+@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented.
+
+@emph{Note:} The first sixteen 64-bit double-precision floating-point
+registers are overlapped with the thirty-two 32-bit single-precision
+floating-point registers. The 32-bit single-precision registers, if
+not being listed explicitly, will be synthesized from halves of the
+overlapping 64-bit double-precision registers. Listing 32-bit
+single-precision registers explicitly is deprecated, and the
+support to it could be totally removed some day.
+
@node Nios II Features
@subsection Nios II Features
@cindex target descriptions, Nios II features
contain the 128-bit wide vector registers @samp{v16} through
@samp{v31}.
+@node Sparc Features
+@subsection Sparc Features
+@cindex target descriptions, sparc32 features
+@cindex target descriptions, sparc64 features
+The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{g0} through @samp{g7}
+@item
+@samp{o0} through @samp{o7}
+@item
+@samp{l0} through @samp{l7}
+@item
+@samp{i0} through @samp{i7}
+@end itemize
+
+They may be 32-bit or 64-bit depending on the target.
+
+Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{f0} through @samp{f31}
+@item
+@samp{f32} through @samp{f62} for sparc64
+@end itemize
+
+The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64
+targets. It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc},
+@samp{fsr}, and @samp{csr} for sparc32
+@item
+@samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y}
+for sparc64
+@end itemize
+
@node TIC6x Features
@subsection TMS320C6x Features
@cindex target descriptions, TIC6x features
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
+@table @code
+@item R @var{size}
+Specifies the size of a register block in bytes. This is equal to the
+size of a @code{g} packet payload in the remote protocol. @var{size}
+is an ascii decimal number. There should be only one such line in
+a single trace file.
+
+@item status @var{status}
+Trace status. @var{status} has the same format as a @code{qTStatus}
+remote packet reply. There should be only one such line in a single trace
+file.
+
+@item tp @var{payload}
+Tracepoint definition. The @var{payload} has the same format as
+@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint
+may take multiple lines of definition, corresponding to the multiple
+reply packets.
+
+@item tsv @var{payload}
+Trace state variable definition. The @var{payload} has the same format as
+@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable
+may take multiple lines of definition, corresponding to the multiple
+reply packets.
+
+@item tdesc @var{payload}
+Target description in XML format. The @var{payload} is a single line of
+the XML file. All such lines should be concatenated together to get
+the original XML file. This file is in the same format as @code{qXfer}
+@code{features} payload, and corresponds to the main @code{target.xml}
+file. Includes are not allowed.
+
+@end table
The trace frame section consists of a number of consecutive frames.
Each frame begins with a two-byte tracepoint number, followed by a
@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.
+actual bytes, in target 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
break;
case DW_TAG_enumerator:
kind = VARIABLE;
- is_static = (language != CPLUS && language != JAVA);
+ is_static = language != CPLUS;
break;
case DW_TAG_subprogram:
kind = FUNCTION;
case DW_TAG_union_type:
case DW_TAG_enumeration_type:
kind = TYPE;
- is_static = (language != CPLUS && language != JAVA);
+ is_static = language != CPLUS;
break;
default:
assert (0);
@c pod2man highlights the right hand side of the @item lines.
@table @env
-@item break [@var{file}:]@var{functiop}
+@item break [@var{file}:]@var{function}
Set a breakpoint at @var{function} (in @var{file}).
@item run [@var{arglist}]
projects / thirdparty / binutils-gdb.git / blobdiff