X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=07f9ad6313b90c8a1ffc1ca47286194cf4bbe88e;hb=036b1ba8ec8e194f8772ed00ec6b1126e7dce710;hp=4ddda64c89787c8069f871988b6bd42c2c414bdd;hpb=adc368187c7bc29c3c227cf986dd021973ce6eaf;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 4ddda64c89..07f9ad6313 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -50,7 +50,7 @@ Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 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.1 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``Free Software'' and ``Free Software Needs Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' @@ -214,6 +214,9 @@ You can use @value{GDBN} to debug programs written in C and C@t{++}. For more information, see @ref{Supported Languages,,Supported Languages}. For more information, see @ref{C,,C and C++}. +Support for D is partial. For information on D, see +@ref{D,,D}. + @cindex Modula-2 Support for Modula-2 is partial. For information on Modula-2, see @ref{Modula-2,,Modula-2}. @@ -1028,9 +1031,9 @@ Run in batch mode. Exit with status @code{0} after processing all the command files specified with @samp{-x} (and all commands from initialization files, if not inhibited with @samp{-n}). Exit with nonzero status if an error occurs in executing the @value{GDBN} commands -in the command files. Batch mode also disables pagination; -@pxref{Screen Size} and acts as if @kbd{set confirm off} were in -effect (@pxref{Messages/Warnings}). +in the command files. Batch mode also disables pagination, sets unlimited +terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm +off} were in effect (@pxref{Messages/Warnings}). Batch mode may be useful for running @value{GDBN} as a filter, for example to download and run a program on another computer; in order to @@ -2478,12 +2481,16 @@ using the @w{@code{kill inferior}} command: @kindex detach inferior @var{infno} @item detach inferior @var{infno} Detach from the inferior identified by @value{GDBN} inferior number -@var{infno}, and remove it from the inferior list. +@var{infno}. Note that the inferior's entry still stays on the list +of inferiors shown by @code{info inferiors}, but its Description will +show @samp{}. @kindex kill inferior @var{infno} @item kill inferior @var{infno} Kill the inferior identified by @value{GDBN} inferior number -@var{infno}, and remove it from the inferior list. +@var{infno}. Note that the inferior's entry still stays on the list +of inferiors shown by @code{info inferiors}, but its Description will +show @samp{}. @end table After the successful completion of a command such as @code{detach}, @@ -2785,6 +2792,13 @@ As with the @samp{[New @dots{}]} message, the form of the text after @samp{Switching to} depends on your system's conventions for identifying threads. +@vindex $_thread@r{, convenience variable} +The debugger convenience variable @samp{$_thread} contains the number +of the current thread. You may find this useful in writing breakpoint +conditional expressions, command scripts, and so forth. See +@xref{Convenience Vars,, Convenience Variables}, for general +information on convenience variables. + @kindex thread apply @cindex apply command to several threads @item thread apply [@var{threadno}] [@var{all}] @var{command} @@ -2850,6 +2864,14 @@ only on some platforms. @kindex show libthread-db-search-path @item show libthread-db-search-path Display current libthread_db search path. + +@kindex set debug libthread-db +@kindex show debug libthread-db +@cindex debugging @code{libthread_db} +@item set debug libthread-db +@itemx show debug libthread-db +Turns on or off display of @code{libthread_db}-related events. +Use @code{1} to enable, @code{0} to disable. @end table @node Forks @@ -3247,6 +3269,7 @@ all breakpoints in that range are operated on. * Disabling:: Disabling breakpoints * Conditions:: Break conditions * Break Commands:: Breakpoint command lists +* Save Breakpoints:: How to save breakpoints in a file * Error in Breakpoints:: ``Cannot insert breakpoints'' * Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' @end menu @@ -3354,7 +3377,7 @@ See also @ref{Conditions, ,Break Conditions}. @kindex rbreak @cindex regular expression -@cindex breakpoints in functions matching a regexp +@cindex breakpoints at functions matching a regexp @cindex set breakpoints in many functions @item rbreak @var{regex} Set breakpoints on all functions matching the regular expression @@ -3384,6 +3407,19 @@ The @code{rbreak} command can be used to set breakpoints in (@value{GDBP}) rbreak . @end smallexample +@item rbreak @var{file}:@var{regex} +If @code{rbreak} is called with a filename qualification, it limits +the search for functions matching the given regular expression to the +specified @var{file}. This can be used, for example, to set breakpoints on +every function in a given file: + +@smallexample +(@value{GDBP}) rbreak file.c:. +@end smallexample + +The colon separating the filename qualifier from the regex may +optionally be surrounded by spaces. + @kindex info breakpoints @cindex @code{$_} and @code{info breakpoints} @item info breakpoints @r{[}@var{n}@r{]} @@ -3675,7 +3711,7 @@ watchpoints, which do not slow down the running of your program. @table @code @kindex watch -@item watch @var{expr} @r{[}thread @var{threadnum}@r{]} +@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} Set a watchpoint for an expression. @value{GDBN} will break when the expression @var{expr} is written into by the program and its value changes. The simplest (and the most popular) use of this command is @@ -3692,13 +3728,22 @@ change the value of @var{expr}, @value{GDBN} will not break. Note that watchpoints restricted to a single thread in this way only work with Hardware Watchpoints. +Ordinarily a watchpoint respects the scope of variables in @var{expr} +(see below). The @code{-location} argument tells @value{GDBN} to +instead watch the memory referred to by @var{expr}. In this case, +@value{GDBN} will evaluate @var{expr}, take the address of the result, +and watch the memory at that address. The type of the result is used +to determine the size of the watched memory. If the expression's +result does not have an address, then @value{GDBN} will print an +error. + @kindex rwatch -@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]} +@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} Set a watchpoint that will break when the value of @var{expr} is read by the program. @kindex awatch -@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]} +@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} Set a watchpoint that will break when @var{expr} is either read from or written into by the program. @@ -3708,6 +3753,18 @@ This command prints a list of watchpoints, using the same format as @code{info break} (@pxref{Set Breaks}). @end table +If you watch for a change in a numerically entered address you need to +dereference it, as the address itself is just a constant number which will +never change. @value{GDBN} refuses to create a watchpoint that watches +a never-changing value: + +@smallexample +(@value{GDBP}) watch 0x600850 +Cannot watch constant value 0x600850. +(@value{GDBP}) watch *(int *) 0x600850 +Watchpoint 1: *(int *) 6293584 +@end smallexample + @value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware watchpoints execute very quickly, and the debugger reports a change in value at the exact instruction where the change occurs. If @value{GDBN} @@ -4401,6 +4458,31 @@ cont end @end smallexample +@node Save Breakpoints +@subsection How to save breakpoints to a file + +To save breakpoint definitions to a file use the @w{@code{save +breakpoints}} command. + +@table @code +@kindex save breakpoints +@cindex save breakpoints to a file for future sessions +@item save breakpoints [@var{filename}] +This command saves all current breakpoint definitions together with +their commands and ignore counts, into a file @file{@var{filename}} +suitable for use in a later debugging session. This includes all +types of breakpoints (breakpoints, watchpoints, catchpoints, +tracepoints). To read the saved breakpoint definitions, use the +@code{source} command (@pxref{Command Files}). Note that watchpoints +with expressions involving local variables may fail to be recreated +because it may not be possible to access the context where the +watchpoint is valid anymore. Because the saved breakpoint definitions +are simply a sequence of @value{GDBN} commands that recreate the +breakpoints, you can edit the file in your favorite editing program, +and remove the breakpoint definitions you're not interested in, or +that can no longer be recreated. +@end table + @c @ifclear BARETARGET @node Error in Breakpoints @subsection ``Cannot insert breakpoints'' @@ -4916,6 +4998,7 @@ you examine the stopped thread in the debugger. * Background Execution:: Running your program asynchronously * Thread-Specific Breakpoints:: Controlling breakpoints * Interrupted System Calls:: GDB may interfere with system calls +* Observer Mode:: GDB does not alter program behavior @end menu @node All-Stop Mode @@ -5276,6 +5359,103 @@ monitor certain events such as thread creation and thread destruction. When such an event happens, a system call in another thread may return prematurely, even though your program does not appear to stop. +@node Observer Mode +@subsection Observer Mode + +If you want to build on non-stop mode and observe program behavior +without any chance of disruption by @value{GDBN}, you can set +variables to disable all of the debugger's attempts to modify state, +whether by writing memory, inserting breakpoints, etc. These operate +at a low level, intercepting operations from all commands. + +When all of these are set to @code{off}, then @value{GDBN} is said to +be @dfn{observer mode}. As a convenience, the variable +@code{observer} can be set to disable these, plus enable non-stop +mode. + +Note that @value{GDBN} will not prevent you from making nonsensical +combinations of these settings. For instance, if you have enabled +@code{may-insert-breakpoints} but disabled @code{may-write-memory}, +then breakpoints that work by writing trap instructions into the code +stream will still not be able to be placed. + +@table @code + +@kindex observer +@item set observer on +@itemx set observer off +When set to @code{on}, this disables all the permission variables +below (except for @code{insert-fast-tracepoints}), plus enables +non-stop debugging. Setting this to @code{off} switches back to +normal debugging, though remaining in non-stop mode. + +@item show observer +Show whether observer mode is on or off. + +@kindex may-write-registers +@item set may-write-registers on +@itemx set may-write-registers off +This controls whether @value{GDBN} will attempt to alter the values of +registers, such as with assignment expressions in @code{print}, or the +@code{jump} command. It defaults to @code{on}. + +@item show may-write-registers +Show the current permission to write registers. + +@kindex may-write-memory +@item set may-write-memory on +@itemx set may-write-memory off +This controls whether @value{GDBN} will attempt to alter the contents +of memory, such as with assignment expressions in @code{print}. It +defaults to @code{on}. + +@item show may-write-memory +Show the current permission to write memory. + +@kindex may-insert-breakpoints +@item set may-insert-breakpoints on +@itemx set may-insert-breakpoints off +This controls whether @value{GDBN} will attempt to insert breakpoints. +This affects all breakpoints, including internal breakpoints defined +by @value{GDBN}. It defaults to @code{on}. + +@item show may-insert-breakpoints +Show the current permission to insert breakpoints. + +@kindex may-insert-tracepoints +@item set may-insert-tracepoints on +@itemx set may-insert-tracepoints off +This controls whether @value{GDBN} will attempt to insert (regular) +tracepoints at the beginning of a tracing experiment. It affects only +non-fast tracepoints, fast tracepoints being under the control of +@code{may-insert-fast-tracepoints}. It defaults to @code{on}. + +@item show may-insert-tracepoints +Show the current permission to insert tracepoints. + +@kindex may-insert-fast-tracepoints +@item set may-insert-fast-tracepoints on +@itemx set may-insert-fast-tracepoints off +This controls whether @value{GDBN} will attempt to insert fast +tracepoints at the beginning of a tracing experiment. It affects only +fast tracepoints, regular (non-fast) tracepoints being under the +control of @code{may-insert-tracepoints}. It defaults to @code{on}. + +@item show may-insert-fast-tracepoints +Show the current permission to insert fast tracepoints. + +@kindex may-interrupt +@item set may-interrupt on +@itemx set may-interrupt off +This controls whether @value{GDBN} will attempt to interrupt or stop +program execution. When this variable is @code{off}, the +@code{interrupt} command will have no effect, nor will +@kbd{Ctrl-c}. It defaults to @code{on}. + +@item show may-interrupt +Show the current permission to interrupt or stop the program. + +@end table @node Reverse Execution @chapter Running programs backward @@ -5487,6 +5667,17 @@ usual ``live'' debugging of the process from that state. When the inferior process exits, or @value{GDBN} detaches from it, process record and replay target will automatically stop itself. +@kindex record save +@item record save @var{filename} +Save the execution log to a file @file{@var{filename}}. +Default filename is @file{gdb_record.@var{process_id}}, where +@var{process_id} is the process ID of the inferior. + +@kindex record restore +@item record restore @var{filename} +Restore the execution log from a file @file{@var{filename}}. +File must have been created with @code{record save}. + @kindex set record insn-number-max @item set record insn-number-max @var{limit} Set the limit of instructions to be recorded. Default value is 200000. @@ -5524,6 +5715,22 @@ oldest record to make room for each new one, without asking. @item show record stop-at-limit Show the current setting of @code{stop-at-limit}. +@kindex set record memory-query +@item set record memory-query +Control the behavior when @value{GDBN} is unable to record memory +changes caused by an instruction. If ON, @value{GDBN} will query +whether to stop the inferior in that case. + +If this option is OFF (the default), @value{GDBN} will automatically +ignore the effect of such instructions on memory. Later, when +@value{GDBN} replays this execution log, it will mark the log of this +instruction as not accessible, and it will not affect the replay +results. + +@kindex show record memory-query +@item show record memory-query +Show the current setting of @code{memory-query}. + @kindex info record @item info record Show various statistics about the state of process record and its @@ -6144,6 +6351,13 @@ in the file @var{filename}. You only need the file name with a function name to avoid ambiguity when there are identically named functions in different source files. +@item @var{label} +Specifies the line at which the label named @var{label} appears. +@value{GDBN} searches for the label in the function corresponding to +the currently selected stack frame. If there is no current selected +stack frame (for instance, if the inferior is not running), then +@value{GDBN} will not search for a label. + @item *@var{address} Specifies the program address @var{address}. For line-oriented commands, such as @code{list} and @code{edit}, this specifies a source @@ -6549,9 +6763,19 @@ program counter of the selected frame. A single argument to this command is a program counter value; @value{GDBN} dumps the function surrounding this value. When two arguments are given, they should be separated by a comma, possibly surrounded by whitespace. The -arguments specify a range of addresses (first inclusive, second exclusive) -to dump. In that case, the name of the function is also printed (since -there could be several functions in the given range). +arguments specify a range of addresses to dump, in one of two forms: + +@table @code +@item @var{start},@var{end} +the addresses from @var{start} (inclusive) to @var{end} (exclusive) +@item @var{start},+@var{length} +the addresses from @var{start} (inclusive) to +@code{@var{start}+@var{length}} (exclusive). +@end table + +@noindent +When 2 arguments are specified, the name of the function is also +printed (since there could be several functions in the given range). The argument(s) can be any expression yielding a numeric value, such as @samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. @@ -6603,6 +6827,18 @@ Dump of assembler code for function main: End of assembler dump. @end smallexample +Here is another example showing raw instructions in hex for AMD x86-64, + +@smallexample +(gdb) disas /r 0x400281,+10 +Dump of assembler code from 0x400281 to 0x40028b: + 0x0000000000400281: 38 36 cmp %dh,(%rsi) + 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax + 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) + 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al +End of assembler dump. +@end smallexample + Some architectures have more than one commonly-used set of instruction mnemonics or other syntax. @@ -6705,6 +6941,7 @@ Table}. * Memory:: Examining memory * Auto Display:: Automatic display * Print Settings:: Print settings +* Pretty Printing:: Python pretty printing * Value History:: Value history * Convenience Vars:: Convenience variables * Registers:: Registers @@ -7236,8 +7473,16 @@ Giant words (eight bytes). @end table Each time you specify a unit size with @code{x}, that size becomes the -default unit the next time you use @code{x}. (For the @samp{s} and -@samp{i} formats, the unit size is ignored and is normally not written.) +default unit the next time you use @code{x}. For the @samp{i} format, +the unit size is ignored and is normally not written. For the @samp{s} format, +the unit size defaults to @samp{b}, unless it is explicitly given. +Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display +32-bit strings. The next use of @kbd{x /s} will again display 8-bit strings. +Note that the results depend on the programming language of the +current compilation unit. If the language is C, the @samp{s} +modifier will use the UTF-16 encoding while @samp{w} will use +UTF-32. The encoding is set by the programming language and cannot +be altered. @item @var{addr}, starting display address @var{addr} is the address where you want @value{GDBN} to begin displaying @@ -7875,6 +8120,42 @@ Do not pretty print C@t{++} virtual function tables. Show whether C@t{++} virtual function tables are pretty printed, or not. @end table +@node Pretty Printing +@section Pretty Printing + +@value{GDBN} provides a mechanism to allow pretty-printing of values using +Python code. It greatly simplifies the display of complex objects. This +mechanism works for both MI and the CLI. + +For example, here is how a C@t{++} @code{std::string} looks without a +pretty-printer: + +@smallexample +(@value{GDBP}) print s +$1 = @{ + static npos = 4294967295, + _M_dataplus = @{ + > = @{ + <__gnu_cxx::new_allocator> = @{ + @}, + @}, + members of std::basic_string, + std::allocator >::_Alloc_hider: + _M_p = 0x804a014 "abcd" + @} +@} +@end smallexample + +With a pretty-printer for @code{std::string} only the contents are printed: + +@smallexample +(@value{GDBP}) print s +$2 = "abcd" +@end smallexample + +For implementing pretty printers for new types you should read the Python API +details (@pxref{Pretty Printing API}). + @node Value History @section Value History @@ -8048,12 +8329,28 @@ to match the format in which the data was printed. The variable @code{$_exitcode} is automatically set to the exit code when the program being debugged terminates. +@item $_sdata +@vindex $_sdata@r{, inspect, convenience variable} +The variable @code{$_sdata} contains extra collected static tracepoint +data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that +@code{$_sdata} could be empty, if not inspecting a trace buffer, or +if extra static tracepoint data has not been collected. + @item $_siginfo @vindex $_siginfo@r{, convenience variable} The variable @code{$_siginfo} contains extra signal information (@pxref{extra signal information}). Note that @code{$_siginfo} could be empty, if the application has not yet received any signals. For example, it will be empty before you execute the @code{run} command. + +@item $_tlb +@vindex $_tlb@r{, convenience variable} +The variable @code{$_tlb} is automatically set when debugging +applications running on MS-Windows in native mode or connected to +gdbserver that supports the @code{qGetTIBAddr} request. +@xref{General Query Packets}. +This variable contains the address of the thread information block. + @end table On HP-UX systems, if you refer to a function or variable name that @@ -8295,6 +8592,12 @@ this functionality depends on the remote stub's support of the @samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. @table @code +@kindex info os +@item info os +List the types of OS information available for the target. If the +target does not return a list of possible types, this command will +report an error. + @kindex info os processes @item info os processes Display the list of processes on the target. For each process, @@ -8612,7 +8915,7 @@ automatically determine the appropriate host character set. In this case, @value{GDBN} uses @samp{UTF-8}. @value{GDBN} can only use certain character sets as its host character -set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}}, +set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}}, @value{GDBN} will list the host character sets it supports. @item set charset @var{charset} @@ -9344,6 +9647,30 @@ Some targets may support @dfn{fast tracepoints}, which are inserted in a different way (such as with a jump instead of a trap), that is faster but possibly restricted in where they may be installed. +@cindex static tracepoints +@cindex markers, static tracepoints +@cindex probing markers, static tracepoints +Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location +in the target. Some targets may also support controlling @dfn{static +tracepoints} from @value{GDBN}. With static tracing, a set of +instrumentation points, also known as @dfn{markers}, are embedded in +the target program, and can be activated or deactivated by name or +address. These are usually placed at locations which facilitate +investigating what the target is actually doing. @value{GDBN}'s +support for static tracing includes being able to list instrumentation +points, and attach them with @value{GDBN} defined high level +tracepoints that expose the whole range of convenience of +@value{GDBN}'s tracepoints support. Namelly, support for collecting +registers values and values of global or local (to the instrumentation +point) variables; tracepoint conditions and trace state variables. +The act of installing a @value{GDBN} static tracepoint on an +instrumentation point, or marker, is referred to as @dfn{probing} a +static tracepoint marker. + +@code{gdbserver} supports tracepoints on some target systems. +@xref{Server,,Tracepoints support in @code{gdbserver}}. + This section describes commands to set tracepoints and associated conditions and actions. @@ -9355,6 +9682,7 @@ conditions and actions. * Trace State Variables:: * Tracepoint Actions:: * Listing Tracepoints:: +* Listing Static Tracepoint Markers:: * Starting and Stopping Trace Experiments:: * Tracepoint Restrictions:: @end menu @@ -9402,6 +9730,7 @@ information on tracepoint conditions. @item ftrace @var{location} [ if @var{cond} ] @cindex set fast tracepoint +@cindex fast tracepoints, setting @kindex ftrace The @code{ftrace} command sets a fast tracepoint. For targets that support them, fast tracepoints will use a more efficient but possibly @@ -9414,6 +9743,67 @@ message. @value{GDBN} handles arguments to @code{ftrace} exactly as for @code{trace}. +@item strace @var{location} [ if @var{cond} ] +@cindex set static tracepoint +@cindex static tracepoints, setting +@cindex probe static tracepoint marker +@kindex strace +The @code{strace} command sets a static tracepoint. For targets that +support it, setting a static tracepoint probes a static +instrumentation point, or marker, found at @var{location}. It may not +be possible to set a static tracepoint at the desired location, in +which case the command will exit with an explanatory message. + +@value{GDBN} handles arguments to @code{strace} exactly as for +@code{trace}, with the addition that the user can also specify +@code{-m @var{marker}} as @var{location}. This probes the marker +identified by the @var{marker} string identifier. This identifier +depends on the static tracepoint backend library your program is +using. You can find all the marker identifiers in the @samp{ID} field +of the @code{info static-tracepoint-markers} command output. +@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint +Markers}. For example, in the following small program using the UST +tracing engine: + +@smallexample +main () +@{ + trace_mark(ust, bar33, "str %s", "FOOBAZ"); +@} +@end smallexample + +@noindent +the marker id is composed of joining the first two arguments to the +@code{trace_mark} call with a slash, which translates to: + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt Enb ID Address What +1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" +[etc...] +@end smallexample + +@noindent +so you may probe the marker above with: + +@smallexample +(@value{GDBP}) strace -m ust/bar33 +@end smallexample + +Static tracepoints accept an extra collect action --- @code{collect +$_sdata}. This collects arbitrary user data passed in the probe point +call to the tracing library. In the UST example above, you'll see +that the third argument to @code{trace_mark} is a printf-like format +string. The user data is then the result of running that formating +string against the following arguments. Note that @code{info +static-tracepoint-markers} command output lists that format string in +the @samp{Data:} field. + +You can inspect this data when analyzing the trace buffer, by printing +the $_sdata variable like any other variable available to +@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. + @vindex $tpnum @cindex last tracepoint number @cindex recent tracepoint number @@ -9604,6 +9994,10 @@ terminate the actions list with a line containing just @code{end}. So far, the only defined actions are @code{collect}, @code{teval}, and @code{while-stepping}. +@code{actions} is actually equivalent to @code{commands} (@pxref{Break +Commands, ,Breakpoint Command Lists}), except that only the defined +actions are allowed; any other @value{GDBN} command is rejected. + @cindex remove actions from a tracepoint To remove all actions from a tracepoint, type @samp{actions @var{num}} and follow it immediately with @samp{end}. @@ -9632,7 +10026,7 @@ Enter actions for tracepoint 1, one per line: > collect bar,baz > collect $regs > while-stepping 12 - > collect $fp, $sp + > collect $pc, arr[i] > end end @end smallexample @@ -9646,18 +10040,39 @@ special arguments are supported: @table @code @item $regs -collect all registers +Collect all registers. @item $args -collect all function arguments +Collect all function arguments. @item $locals -collect all local variables. +Collect all local variables. + +@item $_sdata +@vindex $_sdata@r{, collect} +Collect static tracepoint marker specific data. Only available for +static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action +Lists}. On the UST static tracepoints library backend, an +instrumentation point resembles a @code{printf} function call. The +tracing library is able to collect user specified data formatted to a +character string using the format provided by the programmer that +instrumented the program. Other backends have similar mechanisms. +Here's an example of a UST marker call: + +@smallexample + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) +@end smallexample + +In this case, collecting @code{$_sdata} collects the string +@samp{hello $yourname}. When analyzing the trace buffer, you can +inspect @samp{$_sdata} like any other variable available to +@value{GDBN}. @end table You can give several consecutive @code{collect} commands, each one with a single argument, or one @code{collect} command with several -arguments separated by commas: the effect is the same. +arguments separated by commas; the effect is the same. The command @code{info scope} (@pxref{Symbols, info scope}) is particularly useful for figuring out what data to collect. @@ -9728,24 +10143,18 @@ tracing: @itemize @bullet @item its passcount as given by the @code{passcount @var{n}} command -@item -its step count as given by the @code{while-stepping @var{n}} command -@item -its action list as given by the @code{actions} command. The actions -are prefixed with an @samp{A} so as to distinguish them from commands. @end itemize @smallexample (@value{GDBP}) @b{info trace} Num Type Disp Enb Address What 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 + while-stepping 20 + collect globfoo, $regs + end + collect globfoo2 + end pass count 1200 - step count 20 - A while-stepping 20 - A collect globfoo, $regs - A end - A collect globfoo2 - A end (@value{GDBP}) @end smallexample @@ -9753,6 +10162,60 @@ Num Type Disp Enb Address What This command can be abbreviated @code{info tp}. @end table +@node Listing Static Tracepoint Markers +@subsection Listing Static Tracepoint Markers + +@table @code +@kindex info static-tracepoint-markers +@cindex information about static tracepoint markers +@item info static-tracepoint-markers +Display information about all static tracepoint markers defined in the +program. + +For each marker, the following columns are printed: + +@table @emph +@item Count +An incrementing counter, output to help readability. This is not a +stable identifier. +@item ID +The marker ID, as reported by the target. +@item Enabled or Disabled +Probed markers are tagged with @samp{y}. @samp{n} identifies marks +that are not enabled. +@item Address +Where the marker is in your program, as a memory address. +@item What +Where the marker is in the source for your program, as a file and line +number. If the debug information included in the program does not +allow @value{GDBN} to locate the source of the marker, this column +will be left blank. +@end table + +@noindent +In addition, the following information may be printed for each marker: + +@table @emph +@item Data +User data passed to the tracing library by the marker call. In the +UST backend, this is the format string passed as argument to the +marker call. +@item Static tracepoints probing the marker +The list of static tracepoints attached to the marker. +@end table + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt ID Enb Address What +1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 +2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s +(@value{GDBP}) +@end smallexample +@end table + @node Starting and Stopping Trace Experiments @subsection Starting and Stopping Trace Experiments @@ -9971,7 +10434,7 @@ the buffer will fail. @menu * tfind:: How to select a trace snapshot * tdump:: How to display all data for a snapshot -* save-tracepoints:: How to save tracepoints for a future run +* save tracepoints:: How to save tracepoints for a future run @end menu @node tfind @@ -10166,8 +10629,9 @@ list, and may fail if a while-stepping frame does not include all the same data that is collected at the tracepoint hit. @c This is getting pretty arcane, example would be good. -@node save-tracepoints -@subsection @code{save-tracepoints @var{filename}} +@node save tracepoints +@subsection @code{save tracepoints @var{filename}} +@kindex save tracepoints @kindex save-tracepoints @cindex save tracepoints for future sessions @@ -10175,7 +10639,8 @@ This command saves all current tracepoint definitions together with their actions and passcounts, into a file @file{@var{filename}} suitable for use in a later debugging session. To read the saved tracepoint definitions, use the @code{source} command (@pxref{Command -Files}). +Files}). The @w{@code{save-tracepoints}} command is a deprecated +alias for @w{@code{save tracepoints}} @node Tracepoint Variables @section Convenience Variables for Tracepoints @@ -10731,6 +11196,9 @@ C source file @itemx .c++ C@t{++} source file +@item .d +D source file + @item .m Objective-C source file @@ -11008,7 +11476,7 @@ being set automatically by @value{GDBN}. @node Supported Languages @section Supported Languages -@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal, +@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, Pascal, assembly, Modula-2, and Ada. @c This is false ... Some @value{GDBN} features may be used in expressions regardless of the @@ -11027,6 +11495,7 @@ language reference or tutorial. @menu * C:: C and C@t{++} +* D:: D * Objective-C:: Objective-C * Fortran:: Fortran * Pascal:: Pascal @@ -11564,6 +12033,14 @@ In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers to inspect @code{_Decimal128} values stored in floating point registers. See @ref{PowerPC,,PowerPC} for more details. +@node D +@subsection D + +@cindex D +@value{GDBN} can be used to debug programs written in D and compiled with +GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D +specific feature --- dynamic arrays. + @node Objective-C @subsection Objective-C @@ -13855,6 +14332,7 @@ program. To debug a core dump of a previous run, you must also tell @menu * Files:: Commands to specify files * Separate Debug Files:: Debugging information in separate files +* Index Files:: Index files speed up GDB * Symbol Errors:: Errors reading symbol files * Data Files:: GDB data files @end menu @@ -14311,6 +14789,59 @@ The part of @var{path} following the initial @file{remote:} that happens to be named @file{remote:}, you need to use some equivalent variant of the name like @file{./remote:}.} +For targets with an MS-DOS based filesystem, such as MS-Windows and +SymbianOS, @value{GDBN} tries prefixing a few variants of the target +absolute file name with @var{path}. But first, on Unix hosts, +@value{GDBN} converts all backslash directory separators into forward +slashes, because the backslash is not a directory separator on Unix: + +@smallexample + c:\foo\bar.dll @result{} c:/foo/bar.dll +@end smallexample + +Then, @value{GDBN} attempts prefixing the target file name with +@var{path}, and looks for the resulting file name in the host file +system: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll +@end smallexample + +If that does not find the shared library, @value{GDBN} tries removing +the @samp{:} character from the drive spec, both for convenience, and, +for the case of the host file system not supporting file names with +colons: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll +@end smallexample + +This makes it possible to have a system root that mirrors a target +with more than one drive. E.g., you may want to setup your local +copies of the target system shared libraries like so (note @samp{c} vs +@samp{z}): + +@smallexample + @file{/path/to/sysroot/c/sys/bin/foo.dll} + @file{/path/to/sysroot/c/sys/bin/bar.dll} + @file{/path/to/sysroot/z/sys/bin/bar.dll} +@end smallexample + +@noindent +and point the system root at @file{/path/to/sysroot}, so that +@value{GDBN} can find the correct copies of both +@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}. + +If that still does not find the shared library, @value{GDBN} tries +removing the whole drive spec from the target file name: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll +@end smallexample + +This last lookup makes it possible to not care about the drive name, +if you don't want or need to. + The @code{set solib-absolute-prefix} command is an alias for @code{set sysroot}. @@ -14342,6 +14873,55 @@ of shared library symbols. @kindex show solib-search-path @item show solib-search-path Display the current shared library search path. + +@cindex DOS file-name semantics of file names. +@kindex set target-file-system-kind (unix|dos-based|auto) +@kindex show target-file-system-kind +@item set target-file-system-kind @var{kind} +Set assumed file system kind for target reported file names. + +Shared library file names as reported by the target system may not +make sense as is on the system @value{GDBN} is running on. For +example, when remote debugging a target that has MS-DOS based file +system semantics, from a Unix host, the target may be reporting to +@value{GDBN} a list of loaded shared libraries with file names such as +@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of +drive letters, so the @samp{c:\} prefix is not normally understood as +indicating an absolute file name, and neither is the backslash +normally considered a directory separator character. In that case, +the native file system would interpret this whole absolute file name +as a relative file name with no directory components. This would make +it impossible to point @value{GDBN} at a copy of the remote target's +shared libraries on the host using @code{set sysroot}, and impractical +with @code{set solib-search-path}. Setting +@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN} +to interpret such file names similarly to how the target would, and to +map them to file names valid on @value{GDBN}'s native file system +semantics. The value of @var{kind} can be @code{"auto"}, in addition +to one of the supported file system kinds. In that case, @value{GDBN} +tries to determine the appropriate file system variant based on the +current target's operating system (@pxref{ABI, ,Configuring the +Current ABI}). The supported file system settings are: + +@table @code +@item unix +Instruct @value{GDBN} to assume the target file system is of Unix +kind. Only file names starting the forward slash (@samp{/}) character +are considered absolute, and the directory separator character is also +the forward slash. + +@item dos-based +Instruct @value{GDBN} to assume the target file system is DOS based. +File names starting with either a forward slash, or a drive letter +followed by a colon (e.g., @samp{c:}), are considered absolute, and +both the slash (@samp{/}) and the backslash (@samp{\\}) characters are +considered directory separators. + +@item auto +Instruct @value{GDBN} to use the file system kind associated with the +target operating system (@pxref{ABI, ,Configuring the Current ABI}). +This is the default. +@end table @end table @@ -14642,6 +15222,45 @@ gnu_debuglink_crc32 (unsigned long crc, This computation does not apply to the ``build ID'' method. +@node Index Files +@section Index Files Speed Up @value{GDBN} +@cindex index files +@cindex @samp{.gdb_index} section + +When @value{GDBN} finds a symbol file, it scans the symbols in the +file in order to construct an internal symbol table. This lets most +@value{GDBN} operations work quickly---at the cost of a delay early +on. For large programs, this delay can be quite lengthy, so +@value{GDBN} provides a way to build an index, which speeds up +startup. + +The index is stored as a section in the symbol file. @value{GDBN} can +write the index to a file, then you can put it into the symbol file +using @command{objcopy}. + +To create an index file, use the @code{save gdb-index} command: + +@table @code +@item save gdb-index @var{directory} +@kindex save gdb-index +Create an index file for each symbol file currently known by +@value{GDBN}. Each file is named after its corresponding symbol file, +with @samp{.gdb-index} appended, and is written into the given +@var{directory}. +@end table + +Once you have created an index file you can merge it into your symbol +file, here named @file{symfile}, using @command{objcopy}: + +@smallexample +$ objcopy --add-section .gdb_index=symfile.gdb-index \ + --set-section-flags .gdb_index=readonly symfile symfile +@end smallexample + +There are currently some limitation on indices. They only work when +for DWARF debugging information, not stabs. And, they do not +currently work for programs using Ada. + @node Symbol Errors @section Errors Reading Symbol Files @@ -14814,33 +15433,20 @@ and @code{show architecture}. @cindex active targets @cindex multiple targets -There are three classes of targets: processes, core files, and -executable files. @value{GDBN} can work concurrently on up to three -active targets, one in each class. This allows you to (for example) -start a process and inspect its activity without abandoning your work on -a core file. - -For example, if you execute @samp{gdb a.out}, then the executable file -@code{a.out} is the only active target. If you designate a core file as -well---presumably from a prior run that crashed and coredumped---then -@value{GDBN} has two active targets and uses them in tandem, looking -first in the corefile target, then in the executable file, to satisfy -requests for memory addresses. (Typically, these two classes of target -are complementary, since core files contain only a program's -read-write memory---variables and so on---plus machine status, while -executable files contain only the program text and initialized data.) - -When you type @code{run}, your executable file becomes an active process -target as well. When a process target is active, all @value{GDBN} -commands requesting memory addresses refer to that target; addresses in -an active core file or executable file target are obscured while the -process target is active. - -Use the @code{core-file} and @code{exec-file} commands to select a new -core file or executable target (@pxref{Files, ,Commands to Specify -Files}). To specify as a target a process that is already running, use -the @code{attach} command (@pxref{Attach, ,Debugging an Already-running -Process}). +There are multiple classes of targets such as: processes, executable files or +recording sessions. Core files belong to the process class, making core file +and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently +on multiple active targets, one in each class. This allows you to (for +example) start a process and inspect its activity, while still having access to +the executable file after the process finishes. Or if you start process +recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are +presented a virtual layer of the recording target, while the process target +remains stopped at the chronologically last point of the process execution. + +Use the @code{core-file} and @code{exec-file} commands to select a new core +file or executable target (@pxref{Files, ,Commands to Specify Files}). To +specify as a target a process that is already running, use the @code{attach} +command (@pxref{Attach, ,Debugging an Already-running Process}). @node Target Commands @section Commands for Managing Targets @@ -15482,6 +16088,91 @@ of a multi-process mode debug session. @end table +@subsection Tracepoints support in @code{gdbserver} +@cindex tracepoints support in @code{gdbserver} + +On some targets, @code{gdbserver} supports tracepoints, fast +tracepoints and static tracepoints. + +For fast or static tracepoints to work, a special library called the +@dfn{in-process agent} (IPA), must be loaded in the inferior process. +This library is built and distributed as an integral part of +@code{gdbserver}. In addition, support for static tracepoints +requires building the in-process agent library with static tracepoints +support. At present, the UST (LTTng Userspace Tracer, +@url{http://lttng.org/ust}) tracing engine is supported. This support +is automatically available if UST development headers are found in the +standard include path when @code{gdbserver} is built, or if +@code{gdbserver} was explicitly configured using @option{--with-ust} +to point at such headers. You can explicitly disable the support +using @option{--with-ust=no}. + +There are several ways to load the in-process agent in your program: + +@table @code +@item Specifying it as dependency at link time + +You can link your program dynamically with the in-process agent +library. On most systems, this is accomplished by adding +@code{-linproctrace} to the link command. + +@item Using the system's preloading mechanisms + +You can force loading the in-process agent at startup time by using +your system's support for preloading shared libraries. Many Unixes +support the concept of preloading user defined libraries. In most +cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so} +in the environment. See also the description of @code{gdbserver}'s +@option{--wrapper} command line option. + +@item Using @value{GDBN} to force loading the agent at run time + +On some systems, you can force the inferior to load a shared library, +by calling a dynamic loader function in the inferior that takes care +of dynamically looking up and loading a shared library. On most Unix +systems, the function is @code{dlopen}. You'll use the @code{call} +command for that. For example: + +@smallexample +(@value{GDBP}) call dlopen ("libinproctrace.so", ...) +@end smallexample + +Note that on most Unix systems, for the @code{dlopen} function to be +available, the program needs to be linked with @code{-ldl}. +@end table + +On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to @code{gdbserver} using @code{target +remote}, you'll find that the program is stopped at the dynamic +loader's entry point, and no shared library has been loaded in the +program's address space yet, including the in-process agent. In that +case, before being able to use any of the fast or static tracepoints +features, you need to let the loader run and load the shared +libraries. The simplest way to do that is to run the program to the +main procedure. E.g., if debugging a C or C@t{++} program, start +@code{gdbserver} like so: + +@smallexample +$ gdbserver :9999 myprogram +@end smallexample + +Start GDB and connect to @code{gdbserver} like so, and run to main: + +@smallexample +$ gdb myprogram +(@value{GDBP}) target remote myhost:9999 +0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 +(@value{GDBP}) b main +(@value{GDBP}) continue +@end smallexample + +The in-process tracing agent library should now be loaded into the +process; you can confirm it with the @code{info sharedlibrary} +command, which will list @file{libinproctrace.so} as loaded in the +process. You are now ready to install fast tracepoints, list static +tracepoint markers, probe static tracepoints markers, and start +tracing. + @node Remote Configuration @section Remote Configuration @@ -15731,6 +16422,10 @@ are: @tab @code{qXfer:memory-map:read} @tab @code{info mem} +@item @code{read-sdata-object} +@tab @code{qXfer:sdata:read} +@tab @code{print $_sdata} + @item @code{read-spu-object} @tab @code{qXfer:spu:read} @tab @code{info spu} @@ -15755,6 +16450,10 @@ are: @tab @code{qGetTLSAddr} @tab Displaying @code{__thread} variables +@item @code{get-thread-information-block-address} +@tab @code{qGetTIBAddr} +@tab Display MS-Windows Thread Information Block. + @item @code{search-memory} @tab @code{qSearch:memory} @tab @code{find} @@ -16534,6 +17233,11 @@ a long value to give the information about this given selector. Without argument, this command displays information about the six segment registers. +@item info w32 thread-information-block +This command displays thread specific information stored in the +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 info dll @item info dll This is a Cygwin-specific alias of @code{info shared}. @@ -17768,6 +18472,19 @@ Set suspend trace mode. @node PowerPC Embedded @subsection PowerPC Embedded +@cindex DVC register +@value{GDBN} supports using the DVC (Data Value Compare) register to +implement in hardware simple hardware watchpoint conditions of the form: + +@smallexample +(@value{GDBP}) watch @var{ADDRESS|VARIABLE} \ + if @var{ADDRESS|VARIABLE} == @var{CONSTANT EXPRESSION} +@end smallexample + +The DVC register will be automatically used whenever @value{GDBN} detects +such pattern in a condition expression. This feature is available in native +@value{GDBN} running on a Linux kernel version 2.6.34 or newer. + @value{GDBN} provides the following PowerPC-specific commands: @table @code @@ -19373,7 +20090,7 @@ using the @code{script-extension} setting. @table @code @kindex source @cindex execute commands from a file -@item source [@code{-v}] @var{filename} +@item source [-s] [-v] @var{filename} Execute the command file @var{filename}. @end table @@ -19390,6 +20107,21 @@ directory, then @value{GDBN} also looks for the file on the source search path except that @file{$cdir} is not searched because the compilation directory is not relevant to scripts. +If @code{-s} is specified, then @value{GDBN} searches for @var{filename} +on the search path even if @var{filename} specifies a directory. +The search is done by appending @var{filename} to each element of the +search path. So, for example, if @var{filename} is @file{mylib/myscript} +and the search path contains @file{/home/user} then @value{GDBN} will +look for the script @file{/home/user/mylib/myscript}. +The search is also done if @var{filename} is an absolute path. +For example, if @var{filename} is @file{/tmp/myscript} and +the search path contains @file{/home/user} then @value{GDBN} will +look for the script @file{/home/user/tmp/myscript}. +For DOS-like systems, if @var{filename} contains a drive specification, +it is stripped before concatenation. For example, if @var{filename} is +@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN} +will look for the script @file{c:/tmp/myscript}. + If @code{-v}, for verbose mode, is given then @value{GDBN} displays each command as it is executed. The option must be given before @var{filename}, and is interpreted as part of the filename anywhere else. @@ -19610,6 +20342,11 @@ Here's an example of printing DFP types using the above conversion letters: printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl @end smallexample +@kindex eval +@item eval @var{template}, @var{expressions}@dots{} +Convert the values of one or more @var{expressions} under the control of +the string @var{template} to a command line, and call it. + @end table @node Python @@ -19621,9 +20358,17 @@ You can script @value{GDBN} using the @uref{http://www.python.org/, Python programming language}. This feature is available only if @value{GDBN} was configured using @option{--with-python}. +@cindex python directory +Python scripts used by @value{GDBN} should be installed in +@file{@var{data-directory}/python}, where @var{data-directory} is +the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). This directory, known as the @dfn{python directory}, +is automatically added to the Python Search Path in order to allow +the Python interpreter to locate all scripts installed at this location. + @menu * Python Commands:: Accessing Python from @value{GDBN}. * Python API:: Accessing @value{GDBN} from Python. +* Auto-loading:: Automatically loading Python code. @end menu @node Python Commands @@ -19701,13 +20446,17 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. @menu * Basic Python:: Basic Python Functions. * Exception Handling:: -* Auto-loading:: Automatically loading Python code. * Values From Inferior:: -* Types In Python:: Python representation of types. -* Pretty Printing:: Pretty-printing values. +* Types In Python:: Python representation of types. +* Pretty Printing API:: Pretty-printing values. * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. +* Disabling Pretty-Printers:: Disabling broken printers. +* Inferiors In Python:: Python representation of inferiors (processes) +* Threads In Python:: Accessing inferior threads from Python. * Commands In Python:: Implementing new commands in Python. +* Parameters In Python:: Adding new @value{GDBN} parameters. * Functions In Python:: Writing new convenience functions. +* Progspaces In Python:: Program spaces. * Objfiles In Python:: Object files. * Frames In Python:: Accessing inferior stack frames from Python. * Blocks In Python:: Accessing frame blocks from Python. @@ -19728,16 +20477,28 @@ methods and classes added by @value{GDBN} are placed in this module. @value{GDBN} automatically @code{import}s the @code{gdb} module for use in all scripts evaluated by the @code{python} command. +@findex gdb.PYTHONDIR +@defvar PYTHONDIR +A string containing the python directory (@pxref{Python}). +@end defvar + @findex gdb.execute -@defun execute command [from_tty] +@defun execute command [from_tty] [to_string] Evaluate @var{command}, a string, as a @value{GDBN} CLI command. If a GDB exception happens while @var{command} runs, it is translated as described in @ref{Exception Handling,,Exception Handling}. -If no exceptions occur, this function returns @code{None}. @var{from_tty} specifies whether @value{GDBN} ought to consider this command as having originated from the user invoking it interactively. It must be a boolean value. If omitted, it defaults to @code{False}. + +By default, any output produced by @var{command} is sent to +@value{GDBN}'s standard output. If the @var{to_string} parameter is +@code{True}, then output will be collected by @code{gdb.execute} and +returned as a string. The default is @code{False}, in which case the +return value is @code{None}. If @var{to_string} is @code{True}, the +@value{GDBN} virtual terminal will be temporarily set to unlimited width +and height, and its pagination will be disabled; @pxref{Screen Size}. @end defun @findex gdb.breakpoints @@ -19786,6 +20547,45 @@ compute values, for example, it is the only way to get the value of a convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}. @end defun +@findex gdb.post_event +@defun post_event event +Put @var{event}, a callable object taking no arguments, into +@value{GDBN}'s internal event queue. This callable will be invoked at +some later point, during @value{GDBN}'s event processing. Events +posted using @code{post_event} will be run in the order in which they +were posted; however, there is no way to know when they will be +processed relative to other events inside @value{GDBN}. + +@value{GDBN} is not thread-safe. If your Python program uses multiple +threads, you must be careful to only call @value{GDBN}-specific +functions in the main @value{GDBN} thread. @code{post_event} ensures +this. For example: + +@smallexample +(@value{GDBP}) python +>import threading +> +>class Writer(): +> def __init__(self, message): +> self.message = message; +> def __call__(self): +> gdb.write(self.message) +> +>class MyThread1 (threading.Thread): +> def run (self): +> gdb.post_event(Writer("Hello ")) +> +>class MyThread2 (threading.Thread): +> def run (self): +> gdb.post_event(Writer("World\n")) +> +>MyThread1().start() +>MyThread2().start() +>end +(@value{GDBP}) Hello World +@end smallexample +@end defun + @findex gdb.write @defun write string Print a string to @value{GDBN}'s paginated standard output stream. @@ -19815,6 +20615,26 @@ Return the name of the current target wide character set never returned. @end defun +@findex gdb.solib_name +@defun solib_name address +Return the name of the shared library holding the given @var{address} +as a string, or @code{None}. +@end defun + +@findex gdb.decode_line +@defun decode_line @r{[}expression@r{]} +Return locations of the line specified by @var{expression}, or of the +current line if no argument was given. This function returns a Python +tuple containing two elements. The first element contains a string +holding any unparsed section of @var{expression} (or @code{None} if +the expression has been fully parsed). The second element contains +either @code{None} or another tuple that contains all the locations +that match the expression represented as @code{gdb.Symtab_and_line} +objects (@pxref{Symbol Tables In Python}). If @var{expression} is +provided, it is decoded the way that @value{GDBN}'s inbuilt +@code{break} or @code{edit} commands do (@pxref{Specify Location}). +@end defun + @node Exception Handling @subsubsection Exception Handling @cindex python exceptions @@ -19846,52 +20666,29 @@ message as its value, and the Python call stack backtrace at the Python statement closest to where the @value{GDBN} error occured as the traceback. -@node Auto-loading -@subsubsection Auto-loading -@cindex auto-loading, Python - -When a new object file is read (for example, due to the @code{file} -command, or because the inferior has loaded a shared library), -@value{GDBN} will look for a file named @file{@var{objfile}-gdb.py}, -where @var{objfile} is the object file's real name, formed by ensuring -that the file name is absolute, following all symlinks, and resolving -@code{.} and @code{..} components. If this file exists and is -readable, @value{GDBN} will evaluate it as a Python script. - -If this file does not exist, and if the parameter -@code{debug-file-directory} is set (@pxref{Separate Debug Files}), -then @value{GDBN} will use for its each separated directory component -@code{component} the file named @file{@code{component}/@var{real-name}}, where -@var{real-name} is the object file's real name, as described above. - -Finally, if this file does not exist, then @value{GDBN} will look for -a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where -@var{data-directory} is @value{GDBN}'s data directory (available via -@code{show data-directory}, @pxref{Data Files}), and @var{real-name} -is the object file's real name, as described above. - -When reading an auto-loaded file, @value{GDBN} sets the ``current -objfile''. This is available via the @code{gdb.current_objfile} -function (@pxref{Objfiles In Python}). This can be useful for -registering objfile-specific pretty-printers. - -The auto-loading feature is useful for supplying application-specific -debugging commands and scripts. You can enable or disable this -feature, and view its current state. - -@table @code -@kindex maint set python auto-load -@item maint set python auto-load [yes|no] -Enable or disable the Python auto-loading feature. - -@kindex maint show python auto-load -@item maint show python auto-load -Show whether Python auto-loading is enabled or disabled. -@end table - -@value{GDBN} does not track which files it has already auto-loaded. -So, your @samp{-gdb.py} file should take care to ensure that it may be -evaluated multiple times without error. +@findex gdb.GdbError +When implementing @value{GDBN} commands in Python via @code{gdb.Command}, +it is useful to be able to throw an exception that doesn't cause a +traceback to be printed. For example, the user may have invoked the +command incorrectly. Use the @code{gdb.GdbError} exception +to handle this case. Example: + +@smallexample +(gdb) python +>class HelloWorld (gdb.Command): +> """Greet the whole world.""" +> def __init__ (self): +> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) +> def invoke (self, args, from_tty): +> argv = gdb.string_to_argv (args) +> if len (argv) != 0: +> raise gdb.GdbError ("hello-world takes no arguments") +> print "Hello, World!" +>HelloWorld () +>end +(gdb) hello-world 42 +hello-world takes no arguments +@end smallexample @node Values From Inferior @subsubsection Values From Inferior @@ -19927,6 +20724,22 @@ bar = some_val['foo'] Again, @code{bar} will also be a @code{gdb.Value} object. +A @code{gdb.Value} that represents a function can be executed via +inferior function call. Any arguments provided to the call must match +the function's prototype, and must be provided in the order specified +by that prototype. + +For example, @code{some_val} is a @code{gdb.Value} instance +representing a function that takes two integers as arguments. To +execute this function, call it like so: + +@smallexample +result = some_val (10,20) +@end smallexample + +Any values returned from a function call will be stored as a +@code{gdb.Value}. + The following attributes are provided: @table @code @@ -19946,11 +20759,62 @@ this value, thus it is not available for fetching from the inferior. The type of this @code{gdb.Value}. The value of this attribute is a @code{gdb.Type} object. @end defivar + +@defivar Value dynamic_type +The dynamic type of this @code{gdb.Value}. This uses C@t{++} run-time +type information (@acronym{RTTI}) to determine the dynamic type of the +value. If this value is of class type, it will return the class in +which the value is embedded, if any. If this value is of pointer or +reference to a class type, it will compute the dynamic type of the +referenced object, and return a pointer or reference to that type, +respectively. In all other cases, it will return the value's static +type. + +Note that this feature will only work when debugging a C@t{++} program +that includes @acronym{RTTI} for the object in question. Otherwise, +it will just return the static type of the value as in @kbd{ptype foo} +(@pxref{Symbols, ptype}). +@end defivar @end table The following methods are provided: @table @code +@defmethod Value __init__ @var{val} +Many Python values can be converted directly to a @code{gdb.Value} via +this object initializer. Specifically: + +@table @asis +@item Python boolean +A Python boolean is converted to the boolean type from the current +language. + +@item Python integer +A Python integer is converted to the C @code{long} type for the +current architecture. + +@item Python long +A Python long is converted to the C @code{long long} type for the +current architecture. + +@item Python float +A Python float is converted to the C @code{double} type for the +current architecture. + +@item Python string +A Python string is converted to a target string, using the current +target encoding. + +@item @code{gdb.Value} +If @code{val} is a @code{gdb.Value}, then a copy of the value is made. + +@item @code{gdb.LazyString} +If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In +Python}), then the lazy string's @code{value} method is called, and +its result is used. +@end table +@end defmethod + @defmethod Value cast type Return a new instance of @code{gdb.Value} that is the result of casting this instance to the type described by @var{type}, which must @@ -19979,6 +20843,16 @@ The result @code{bar} will be a @code{gdb.Value} object holding the value pointed to by @code{foo}. @end defmethod +@defmethod Value dynamic_cast type +Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast} +operator were used. Consult a C@t{++} reference for details. +@end defmethod + +@defmethod Value reinterpret_cast type +Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast} +operator were used. Consult a C@t{++} reference for details. +@end defmethod + @defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]} @r{[}length@r{]} If this @code{gdb.Value} represents a string, then this method converts the contents to a Python string. Otherwise, this method will @@ -20125,6 +20999,15 @@ but it can be @code{None} in some situations. @end table @end defmethod +@defmethod Type array @var{n1} @r{[}@var{n2}@r{]} +Return a new @code{gdb.Type} object which represents an array of this +type. If one argument is given, it is the inclusive upper bound of +the array; in this case the lower bound is zero. If two arguments are +given, the first argument is the lower bound of the array, and the +second argument is the upper bound of the array. An array's length +must not be negative, but the bounds can be. +@end defmethod + @defmethod Type const Return a new @code{gdb.Type} object which represents a @code{const}-qualified variant of this type. @@ -20330,37 +21213,10 @@ A function internal to @value{GDBN}. This is the type used to represent convenience functions. @end table -@node Pretty Printing -@subsubsection Pretty Printing - -@value{GDBN} provides a mechanism to allow pretty-printing of values -using Python code. The pretty-printer API allows application-specific -code to greatly simplify the display of complex objects. This -mechanism works for both MI and the CLI. - -For example, here is how a C@t{++} @code{std::string} looks without a -pretty-printer: - -@smallexample -(@value{GDBP}) print s -$1 = @{ - static npos = 4294967295, - _M_dataplus = @{ - > = @{ - <__gnu_cxx::new_allocator> = @{@}, @}, - members of std::basic_string, std::allocator >::_Alloc_hider: - _M_p = 0x804a014 "abcd" - @} -@} -@end smallexample - -After a pretty-printer for @code{std::string} has been installed, only -the contents are printed: +@node Pretty Printing API +@subsubsection Pretty Printing API -@smallexample -(@value{GDBP}) print s -$2 = "abcd" -@end smallexample +An example output is provided (@pxref{Pretty Printing}). A pretty-printer is just an object that holds a value and implements a specific interface, defined here. @@ -20435,28 +21291,48 @@ the resulting value. Again, this may result in a call to another pretty-printer. Python scalars (integers, floats, and booleans) and strings are convertible to @code{gdb.Value}; other types are not. +Finally, if this method returns @code{None} then no further operations +are peformed in this method and nothing is printed. + If the result is not one of these types, an exception is raised. @end defop +@value{GDBN} provides a function which can be used to look up the +default pretty-printer for a @code{gdb.Value}: + +@findex gdb.default_visualizer +@defun default_visualizer value +This function takes a @code{gdb.Value} object as an argument. If a +pretty-printer for this value exists, then it is returned. If no such +printer exists, then this returns @code{None}. +@end defun + @node Selecting Pretty-Printers @subsubsection Selecting Pretty-Printers The Python list @code{gdb.pretty_printers} contains an array of -functions that have been registered via addition as a pretty-printer. +functions or callable objects that have been registered via addition +as a pretty-printer. +Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute. Each @code{gdb.Objfile} also contains a @code{pretty_printers} attribute. A function on one of these lists is passed a single @code{gdb.Value} argument and should return a pretty-printer object conforming to the -interface definition above (@pxref{Pretty Printing}). If a function +interface definition above (@pxref{Pretty Printing API}). If a function cannot create a pretty-printer for the value, it should return @code{None}. @value{GDBN} first checks the @code{pretty_printers} attribute of each -@code{gdb.Objfile} and iteratively calls each function in the list for -that @code{gdb.Objfile} until it receives a pretty-printer object. +@code{gdb.Objfile} in the current program space and iteratively calls +each enabled function (@pxref{Disabling Pretty-Printers}) +in the list for that @code{gdb.Objfile} until it receives +a pretty-printer object. +If no pretty-printer is found in the objfile lists, @value{GDBN} then +searches the pretty-printer list of the current program space, +calling each enabled function until an object is returned. After these lists have been exhausted, it tries the global -@code{gdb.pretty-printers} list, again calling each function until an +@code{gdb.pretty_printers} list, again calling each enabled function until an object is returned. The order in which the objfiles are searched is not specified. For a @@ -20525,7 +21401,7 @@ printers with a specific objfile, @value{GDBN} will find the correct printers for the specific version of the library used by each inferior. -To continue the @code{std::string} example (@pxref{Pretty Printing}), +To continue the @code{std::string} example (@pxref{Pretty Printing API}), this code might appear in @code{gdb.libstdcxx.v6}: @smallexample @@ -20541,6 +21417,152 @@ import gdb.libstdcxx.v6 gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) @end smallexample +@node Disabling Pretty-Printers +@subsubsection Disabling Pretty-Printers +@cindex disabling pretty-printers + +For various reasons a pretty-printer may not work. +For example, the underlying data structure may have changed and +the pretty-printer is out of date. + +The consequences of a broken pretty-printer are severe enough that +@value{GDBN} provides support for enabling and disabling individual +printers. For example, if @code{print frame-arguments} is on, +a backtrace can become highly illegible if any argument is printed +with a broken printer. + +Pretty-printers are enabled and disabled by attaching an @code{enabled} +attribute to the registered function or callable object. If this attribute +is present and its value is @code{False}, the printer is disabled, otherwise +the printer is enabled. + +@node Inferiors In Python +@subsubsection Inferiors In Python +@cindex inferiors in python + +@findex gdb.Inferior +Programs which are being run under @value{GDBN} are called inferiors +(@pxref{Inferiors and Programs}). Python scripts can access +information about and manipulate inferiors controlled by @value{GDBN} +via objects of the @code{gdb.Inferior} class. + +The following inferior-related functions are available in the @code{gdb} +module: + +@defun inferiors +Return a tuple containing all inferior objects. +@end defun + +A @code{gdb.Inferior} object has the following attributes: + +@table @code +@defivar Inferior num +ID of inferior, as assigned by GDB. +@end defivar + +@defivar Inferior pid +Process ID of the inferior, as assigned by the underlying operating +system. +@end defivar + +@defivar Inferior was_attached +Boolean signaling whether the inferior was created using `attach', or +started by @value{GDBN} itself. +@end defivar +@end table + +A @code{gdb.Inferior} object has the following methods: + +@table @code +@defmethod Inferior threads +This method returns a tuple holding all the threads which are valid +when it is called. If there are no valid threads, the method will +return an empty tuple. +@end defmethod + +@findex gdb.read_memory +@defmethod Inferior read_memory address length +Read @var{length} bytes of memory from the inferior, starting at +@var{address}. Returns a buffer object, which behaves much like an array +or a string. It can be modified and given to the @code{gdb.write_memory} +function. +@end defmethod + +@findex gdb.write_memory +@defmethod Inferior write_memory address buffer @r{[}length@r{]} +Write the contents of @var{buffer} to the inferior, starting at +@var{address}. The @var{buffer} parameter must be a Python object +which supports the buffer protocol, i.e., a string, an array or the +object returned from @code{gdb.read_memory}. If given, @var{length} +determines the number of bytes from @var{buffer} to be written. +@end defmethod + +@findex gdb.search_memory +@defmethod Inferior search_memory address length pattern +Search a region of the inferior memory starting at @var{address} with +the given @var{length} using the search pattern supplied in +@var{pattern}. The @var{pattern} parameter must be a Python object +which supports the buffer protocol, i.e., a string, an array or the +object returned from @code{gdb.read_memory}. Returns a Python @code{Long} +containing the address where the pattern was found, or @code{None} if +the pattern could not be found. +@end defmethod +@end table + +@node Threads In Python +@subsubsection Threads In Python +@cindex threads in python + +@findex gdb.InferiorThread +Python scripts can access information about, and manipulate inferior threads +controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class. + +The following thread-related functions are available in the @code{gdb} +module: + +@findex gdb.selected_thread +@defun selected_thread +This function returns the thread object for the selected thread. If there +is no selected thread, this will return @code{None}. +@end defun + +A @code{gdb.InferiorThread} object has the following attributes: + +@table @code +@defivar InferiorThread num +ID of the thread, as assigned by GDB. +@end defivar + +@defivar InferiorThread ptid +ID of the thread, as assigned by the operating system. This attribute is a +tuple containing three integers. The first is the Process ID (PID); the second +is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID). +Either the LWPID or TID may be 0, which indicates that the operating system +does not use that identifier. +@end defivar +@end table + +A @code{gdb.InferiorThread} object has the following methods: + +@table @code +@defmethod InferiorThread switch +This changes @value{GDBN}'s currently selected thread to the one represented +by this object. +@end defmethod + +@defmethod InferiorThread is_stopped +Return a Boolean indicating whether the thread is stopped. +@end defmethod + +@defmethod InferiorThread is_running +Return a Boolean indicating whether the thread is running. +@end defmethod + +@defmethod InferiorThread is_exited +Return a Boolean indicating whether the thread is exited. +@end defmethod +@end table + @node Commands In Python @subsubsection Commands In Python @@ -20603,6 +21625,20 @@ that the command came from elsewhere. If this method throws an exception, it is turned into a @value{GDBN} @code{error} call. Otherwise, the return value is ignored. + +@findex gdb.string_to_argv +To break @var{argument} up into an argv-like string use +@code{gdb.string_to_argv}. This function behaves identically to +@value{GDBN}'s internal argument lexer @code{buildargv}. +It is recommended to use this for consistency. +Arguments are separated by spaces and may be quoted. +Example: + +@smallexample +print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") +['1', '2 "3', '4 "5', "6 '7"] +@end smallexample + @end defmethod @cindex completion of Python commands @@ -20793,6 +21829,152 @@ registration of the command with @value{GDBN}. Depending on how the Python code is read into @value{GDBN}, you may need to import the @code{gdb} module explicitly. +@node Parameters In Python +@subsubsection Parameters In Python + +@cindex parameters in python +@cindex python parameters +@tindex gdb.Parameter +@tindex Parameter +You can implement new @value{GDBN} parameters using Python. A new +parameter is implemented as an instance of the @code{gdb.Parameter} +class. + +Parameters are exposed to the user via the @code{set} and +@code{show} commands. @xref{Help}. + +There are many parameters that already exist and can be set in +@value{GDBN}. Two examples are: @code{set follow fork} and +@code{set charset}. Setting these parameters influences certain +behavior in @value{GDBN}. Similarly, you can define parameters that +can be used to influence behavior in custom Python scripts and commands. + +@defmethod Parameter __init__ name @var{command-class} @var{parameter-class} @r{[}@var{enum-sequence}@r{]} +The object initializer for @code{Parameter} registers the new +parameter with @value{GDBN}. This initializer is normally invoked +from the subclass' own @code{__init__} method. + +@var{name} is the name of the new parameter. If @var{name} consists +of multiple words, then the initial words are looked for as prefix +parameters. An example of this can be illustrated with the +@code{set print} set of parameters. If @var{name} is +@code{print foo}, then @code{print} will be searched as the prefix +parameter. In this case the parameter can subsequently be accessed in +@value{GDBN} as @code{set print foo}. + +If @var{name} consists of multiple words, and no prefix parameter group +can be found, an exception is raised. + +@var{command-class} should be one of the @samp{COMMAND_} constants +(@pxref{Commands In Python}). This argument tells @value{GDBN} how to +categorize the new parameter in the help system. + +@var{parameter-class} should be one of the @samp{PARAM_} constants +defined below. This argument tells @value{GDBN} the type of the new +parameter; this information is used for input validation and +completion. + +If @var{parameter-class} is @code{PARAM_ENUM}, then +@var{enum-sequence} must be a sequence of strings. These strings +represent the possible values for the parameter. + +If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence +of a fourth argument will cause an exception to be thrown. + +The help text for the new parameter is taken from the Python +documentation string for the parameter's class, if there is one. If +there is no documentation string, a default value is used. +@end defmethod + +@defivar Parameter set_doc +If this attribute exists, and is a string, then its value is used as +the help text for this parameter's @code{set} command. The value is +examined when @code{Parameter.__init__} is invoked; subsequent changes +have no effect. +@end defivar + +@defivar Parameter show_doc +If this attribute exists, and is a string, then its value is used as +the help text for this parameter's @code{show} command. The value is +examined when @code{Parameter.__init__} is invoked; subsequent changes +have no effect. +@end defivar + +@defivar Parameter value +The @code{value} attribute holds the underlying value of the +parameter. It can be read and assigned to just as any other +attribute. @value{GDBN} does validation when assignments are made. +@end defivar + + +When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the @code{gdb} +module: + +@table @code +@findex PARAM_BOOLEAN +@findex gdb.PARAM_BOOLEAN +@item PARAM_BOOLEAN +The value is a plain boolean. The Python boolean values, @code{True} +and @code{False} are the only valid values. + +@findex PARAM_AUTO_BOOLEAN +@findex gdb.PARAM_AUTO_BOOLEAN +@item PARAM_AUTO_BOOLEAN +The value has three possible states: true, false, and @samp{auto}. In +Python, true and false are represented using boolean constants, and +@samp{auto} is represented using @code{None}. + +@findex PARAM_UINTEGER +@findex gdb.PARAM_UINTEGER +@item PARAM_UINTEGER +The value is an unsigned integer. The value of 0 should be +interpreted to mean ``unlimited''. + +@findex PARAM_INTEGER +@findex gdb.PARAM_INTEGER +@item PARAM_INTEGER +The value is a signed integer. The value of 0 should be interpreted +to mean ``unlimited''. + +@findex PARAM_STRING +@findex gdb.PARAM_STRING +@item PARAM_STRING +The value is a string. When the user modifies the string, any escape +sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are +translated into corresponding characters and encoded into the current +host charset. + +@findex PARAM_STRING_NOESCAPE +@findex gdb.PARAM_STRING_NOESCAPE +@item PARAM_STRING_NOESCAPE +The value is a string. When the user modifies the string, escapes are +passed through untranslated. + +@findex PARAM_OPTIONAL_FILENAME +@findex gdb.PARAM_OPTIONAL_FILENAME +@item PARAM_OPTIONAL_FILENAME +The value is a either a filename (a string), or @code{None}. + +@findex PARAM_FILENAME +@findex gdb.PARAM_FILENAME +@item PARAM_FILENAME +The value is a filename. This is just like +@code{PARAM_STRING_NOESCAPE}, but uses file names for completion. + +@findex PARAM_ZINTEGER +@findex gdb.PARAM_ZINTEGER +@item PARAM_ZINTEGER +The value is an integer. This is like @code{PARAM_INTEGER}, except 0 +is interpreted as itself. + +@findex PARAM_ENUM +@findex gdb.PARAM_ENUM +@item PARAM_ENUM +The value is a string, which must be one of a collection string +constants provided when the parameter is created. +@end table + @node Functions In Python @subsubsection Writing new convenience functions @@ -20852,6 +22034,49 @@ registration of the function with @value{GDBN}. Depending on how the Python code is read into @value{GDBN}, you may need to import the @code{gdb} module explicitly. +@node Progspaces In Python +@subsubsection Program Spaces In Python + +@cindex progspaces in python +@tindex gdb.Progspace +@tindex Progspace +A program space, or @dfn{progspace}, represents a symbolic view +of an address space. +It consists of all of the objfiles of the program. +@xref{Objfiles In Python}. +@xref{Inferiors and Programs, program spaces}, for more details +about program spaces. + +The following progspace-related functions are available in the +@code{gdb} module: + +@findex gdb.current_progspace +@defun current_progspace +This function returns the program space of the currently selected inferior. +@xref{Inferiors and Programs}. +@end defun + +@findex gdb.progspaces +@defun progspaces +Return a sequence of all the progspaces currently known to @value{GDBN}. +@end defun + +Each progspace is represented by an instance of the @code{gdb.Progspace} +class. + +@defivar Progspace filename +The file name of the progspace as a string. +@end defivar + +@defivar Progspace pretty_printers +The @code{pretty_printers} attribute is a list of functions. It is +used to look up pretty-printers. A @code{Value} is passed to each +function in order; if the function returns @code{None}, then the +search continues. Otherwise, the return value should be an object +which is used to format the value. @xref{Pretty Printing API}, for more +information. +@end defivar + @node Objfiles In Python @subsubsection Objfiles In Python @@ -20893,7 +22118,7 @@ The @code{pretty_printers} attribute is a list of functions. It is used to look up pretty-printers. A @code{Value} is passed to each function in order; if the function returns @code{None}, then the search continues. Otherwise, the return value should be an object -which is used to format the value. @xref{Pretty Printing}, for more +which is used to format the value. @xref{Pretty Printing API}, for more information. @end defivar @@ -21498,6 +22723,162 @@ resolve this to the lazy string's character type, use the type's writable. @end defivar +@node Auto-loading +@subsection Auto-loading +@cindex auto-loading, Python + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for Python support scripts in several ways: +@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section. + +@menu +* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file +* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section +* Which flavor to choose?:: +@end menu + +The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + +Auto-loading can be enabled or disabled. + +@table @code +@kindex maint set python auto-load +@item maint set python auto-load [yes|no] +Enable or disable the Python auto-loading feature. + +@kindex maint show python auto-load +@item maint show python auto-load +Show whether Python auto-loading is enabled or disabled. +@end table + +When reading an auto-loaded file, @value{GDBN} sets the +@dfn{current objfile}. This is available via the @code{gdb.current_objfile} +function (@pxref{Objfiles In Python}). This can be useful for +registering objfile-specific pretty-printers. + +@node objfile-gdb.py file +@subsubsection The @file{@var{objfile}-gdb.py} file +@cindex @file{@var{objfile}-gdb.py} + +When a new object file is read, @value{GDBN} looks for +a file named @file{@var{objfile}-gdb.py}, +where @var{objfile} is the object file's real name, formed by ensuring +that the file name is absolute, following all symlinks, and resolving +@code{.} and @code{..} components. If this file exists and is +readable, @value{GDBN} will evaluate it as a Python script. + +If this file does not exist, and if the parameter +@code{debug-file-directory} is set (@pxref{Separate Debug Files}), +then @value{GDBN} will look for @var{real-name} in all of the +directories mentioned in the value of @code{debug-file-directory}. + +Finally, if this file does not exist, then @value{GDBN} will look for +a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where +@var{data-directory} is @value{GDBN}'s data directory (available via +@code{show data-directory}, @pxref{Data Files}), and @var{real-name} +is the object file's real name, as described above. + +@value{GDBN} does not track which files it has already auto-loaded this way. +@value{GDBN} will load the associated script every time the corresponding +@var{objfile} is opened. +So your @file{-gdb.py} file should be careful to avoid errors if it +is evaluated more than once. + +@node .debug_gdb_scripts section +@subsubsection The @code{.debug_gdb_scripts} section +@cindex @code{.debug_gdb_scripts} section + +For systems using file formats like ELF and COFF, +when @value{GDBN} loads a new object file +it will look for a special section named @samp{.debug_gdb_scripts}. +If this section exists, its contents is a list of names of scripts to load. + +@value{GDBN} will look for each specified script file first in the +current directory and then along the source search path +(@pxref{Source Path, ,Specifying Source Directories}), +except that @file{$cdir} is not searched, since the compilation +directory is not relevant to scripts. + +Entries can be placed in section @code{.debug_gdb_scripts} with, +for example, this GCC macro: + +@example +/* Note: The "MS" section flags are to remove duplicates. */ +#define DEFINE_GDB_SCRIPT(script_name) \ + asm("\ +.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ +.byte 1\n\ +.asciz \"" script_name "\"\n\ +.popsection \n\ +"); +@end example + +@noindent +Then one can reference the macro in a header or source file like this: + +@example +DEFINE_GDB_SCRIPT ("my-app-scripts.py") +@end example + +The script name may include directories if desired. + +If the macro is put in a header, any application or library +using this header will get a reference to the specified script. + +@node Which flavor to choose? +@subsubsection Which flavor to choose? + +Given the multiple ways of auto-loading Python scripts, it might not always +be clear which one to choose. This section provides some guidance. + +Benefits of the @file{-gdb.py} way: + +@itemize @bullet +@item +Can be used with file formats that don't support multiple sections. + +@item +Ease of finding scripts for public libraries. + +Scripts specified in the @code{.debug_gdb_scripts} section are searched for +in the source search path. +For publicly installed libraries, e.g., @file{libstdc++}, there typically +isn't a source directory in which to find the script. + +@item +Doesn't require source code additions. +@end itemize + +Benefits of the @code{.debug_gdb_scripts} way: + +@itemize @bullet +@item +Works with static linking. + +Scripts for libraries done the @file{-gdb.py} way require an objfile to +trigger their loading. When an application is statically linked the only +objfile available is the executable, and it is cumbersome to attach all the +scripts from all the input libraries to the executable's @file{-gdb.py} script. + +@item +Works with classes that are entirely inlined. + +Some classes can be entirely inlined, and thus there may not be an associated +shared library to attach a @file{-gdb.py} script to. + +@item +Scripts needn't be copied out of the source tree. + +In some circumstances, apps can be built out of large collections of internal +libraries, and the build infrastructure necessary to install the +@file{-gdb.py} scripts in a place where @value{GDBN} can find them is +cumbersome. It may be easier to specify the scripts in the +@code{.debug_gdb_scripts} section as relative paths, and add a path to the +top of the source tree to the source search path. +@end itemize + @node Interpreters @chapter Command Interpreters @cindex command interpreters @@ -24701,8 +26082,13 @@ The @code{$pc} value for that frame. Function name. @item @var{file} File name of the source file where the function lives. +@item @var{fullname} +The full file name of the source file where the function lives. @item @var{line} Line number corresponding to the @code{$pc}. +@item @var{from} +The shared library where this function is defined. This is only given +if the frame's function is not known. @end table If invoked without arguments, this command prints a backtrace for the @@ -25150,7 +26536,7 @@ then this attribute will not be present. @item displayhint A dynamic varobj can supply a display hint to the front end. The value comes directly from the Python pretty-printer object's -@code{display_hint} method. @xref{Pretty Printing}. +@code{display_hint} method. @xref{Pretty Printing API}. @end table Typical output will look like this: @@ -25252,7 +26638,7 @@ be available. Return a list of the children of the specified variable object and create variable objects for them, if they do not already exist. With -a single argument or if @var{print-values} has a value for of 0 or +a single argument or if @var{print-values} has a value of 0 or @code{--no-values}, print only the names of the variables; if @var{print-values} is 1 or @code{--all-values}, also print their values; and if it is 2 or @code{--simple-values} print the name and @@ -25322,7 +26708,7 @@ The result may have its own attributes: @item displayhint A dynamic varobj can supply a display hint to the front end. The value comes directly from the Python pretty-printer object's -@code{display_hint} method. @xref{Pretty Printing}. +@code{display_hint} method. @xref{Pretty Printing API}. @item has_more This is an integer attribute which is nonzero if there are children @@ -25686,7 +27072,7 @@ single argument. @value{GDBN} will call this object with the value of the varobj @var{name} as an argument (this is done so that the same Python pretty-printing code can be used for both the CLI and MI). When called, this object must return an object which conforms to the -pretty-printing interface (@pxref{Pretty Printing}). +pretty-printing interface (@pxref{Pretty Printing API}). The pre-defined function @code{gdb.default_visualizer} may be used to select a visualizer by following the built-in process @@ -26086,6 +27472,8 @@ don't appear in the actual output): @subheading The @code{-data-read-memory} Command @findex -data-read-memory +This command is deprecated, use @code{-data-read-memory-bytes} instead. + @subsubheading Synopsis @smallexample @@ -26197,6 +27585,128 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[ (gdb) @end smallexample +@subheading The @code{-data-read-memory-bytes} Command +@findex -data-read-memory-bytes + +@subsubheading Synopsis + +@smallexample + -data-read-memory-bytes [ -o @var{byte-offset} ] + @var{address} @var{count} +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first memory word to be +read. Complex expressions containing embedded white space should be +quoted using the C convention. + +@item @var{count} +The number of bytes to read. This should be an integer literal. + +@item @var{byte-offset} +The offsets in bytes relative to @var{address} at which to start +reading. This should be an integer literal. This option is provided +so that a frontend is not required to first evaluate address and then +perform address arithmetics itself. + +@end table + +This command attempts to read all accessible memory regions in the +specified range. First, all regions marked as unreadable in the memory +map (if one is defined) will be skipped. @xref{Memory Region +Attributes}. Second, @value{GDBN} will attempt to read the remaining +regions. For each one, if reading full region results in an errors, +@value{GDBN} will try to read a subset of the region. + +In general, every single byte in the region may be readable or not, +and the only way to read every readable byte is to try a read at +every address, which is not practical. Therefore, @value{GDBN} will +attempt to read all accessible bytes at either beginning or the end +of the region, using a binary division scheme. This heuristic works +well for reading accross a memory map boundary. Note that if a region +has a readable range that is neither at the beginning or the end, +@value{GDBN} will not read it. + +The result record (@pxref{GDB/MI Result Records}) that is output of +the command includes a field named @samp{memory} whose content is a +list of tuples. Each tuple represent a successfully read memory block +and has the following fields: + +@table @code +@item begin +The start address of the memory block, as hexadecimal literal. + +@item end +The end address of the memory block, as hexadecimal literal. + +@item offset +The offset of the memory block, as hexadecimal literal, relative to +the start address passed to @code{-data-read-memory-bytes}. + +@item contents +The contents of the memory block, in hex. + +@end table + + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{x}. + +@subsubheading Example + +@smallexample +(gdb) +-data-read-memory-bytes &a 10 +^done,memory=[@{begin="0xbffff154",offset="0x00000000", + end="0xbffff15e", + contents="01000000020000000300"@}] +(gdb) +@end smallexample + + +@subheading The @code{-data-write-memory-bytes} Command +@findex -data-write-memory-bytes + +@subsubheading Synopsis + +@smallexample + -data-write-memory-bytes @var{address} @var{contents} +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first memory word to be +read. Complex expressions containing embedded white space should be +quoted using the C convention. + +@item @var{contents} +The hex-encoded bytes to write. + +@end table + +@subsubheading @value{GDBN} Command + +There's no corresponding @value{GDBN} command. + +@subsubheading Example + +@smallexample +(gdb) +-data-write-memory-bytes &a "aabbccdd" +^done +(gdb) +@end smallexample + + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Tracepoint Commands @section @sc{gdb/mi} Tracepoint Commands @@ -26387,7 +27897,7 @@ The corresponding @value{GDBN} command is @samp{tstart}. -trace-status @end smallexample -Obtains the status of a tracing experiement. The result may include +Obtains the status of a tracing experiment. The result may include the following fields: @table @samp @@ -26421,13 +27931,27 @@ present iff the @samp{stop-reason} field has the value of @samp{passcount}. @item frames -This field is an integer number of currently collected frames. This -field is optional. +@itemx frames-created +The @samp{frames} field is a count of the total number of trace frames +in the trace buffer, while @samp{frames-created} is the total created +during the run, including ones that were discarded, such as when a +circular trace buffer filled up. Both fields are optional. @item buffer-size @itemx buffer-free These fields tell the current size of the tracing buffer and the -remaining space. These field is optional. +remaining space. These fields are optional. + +@item circular +The value of the circular trace buffer flag. @code{1} means that the +trace buffer is circular and old trace frames will be discarded if +necessary to make room, @code{0} means that the trace buffer is linear +and may fill up. + +@item disconnected +The value of the disconnected tracing flag. @code{1} means that +tracing will continue after @value{GDBN} disconnects, @code{0} means +that the trace run will stop. @end table @@ -27521,6 +29045,9 @@ pretty-printing commands, and possible presence of the @samp{display_hint} field in the output of @code{-var-list-children} @item thread-info Indicates presence of the @code{-thread-info} command. +@item data-read-memory-bytes +Indicates presense of the @code{-data-read-memory-bytes} and the +@code{-data-write-memory-bytes} commands. @end table @@ -27549,6 +29076,10 @@ Indicates that the target is capable of asynchronous command execution, which means that @value{GDBN} will accept further commands while the target is running. +@item reverse +Indicates that the target is capable of reverse execution. +@xref{Reverse Execution}, for more information. + @end table @subheading The @code{-list-thread-groups} Command @@ -29246,8 +30777,9 @@ Print @value{GDBN}'s internal register data structures. The command @code{maint print raw-registers} includes the contents of the raw register cache; the command @code{maint print cooked-registers} -includes the (cooked) value of all registers; and the command -@code{maint print register-groups} includes the groups that each +includes the (cooked) value of all registers, including registers which +aren't available on the target nor visible to user; and the +command @code{maint print register-groups} includes the groups that each register is a member of. @xref{Registers,, Registers, gdbint, @value{GDBN} Internals}. @@ -29285,6 +30817,16 @@ Print a dump of all known object files. For each object file, this command prints its name, address in memory, and all of its psymtabs and symtabs. +@kindex maint print section-scripts +@cindex info for known .debug_gdb_scripts-loaded scripts +@item maint print section-scripts [@var{regexp}] +Print a dump of scripts specified in the @code{.debug_gdb_section} section. +If @var{regexp} is specified, only print scripts loaded by object files +matching @var{regexp}. +For each script, this command prints its name as specified in the objfile, +and the full path if known. +@xref{.debug_gdb_scripts section}. + @kindex maint print statistics @cindex bcache statistics @item maint print statistics @@ -29322,6 +30864,31 @@ that symbol is described. The type chain produced by this command is a recursive definition of the data type as stored in @value{GDBN}'s data structures, including its flags and contained types. +@kindex maint set dwarf2 always-disassemble +@kindex maint show dwarf2 always-disassemble +@item maint set dwarf2 always-disassemble +@item maint show dwarf2 always-disassemble +Control the behavior of @code{info address} when using DWARF debugging +information. + +The default is @code{off}, which means that @value{GDBN} should try to +describe a variable's location in an easily readable format. When +@code{on}, @value{GDBN} will instead display the DWARF location +expression in an assembly-like format. Note that some locations are +too complex for @value{GDBN} to describe simply; in this case you will +always see the disassembly form. + +Here is an example of the resulting disassembly: + +@smallexample +(gdb) info addr argc +Symbol "argc" is a complex DWARF expression: + 1: DW_OP_fbreg 0 +@end smallexample + +For more information on these expressions, see +@uref{http://www.dwarfstd.org/, the DWARF standard}. + @kindex maint set dwarf2 max-cache-age @kindex maint show dwarf2 max-cache-age @item maint set dwarf2 max-cache-age @@ -29367,6 +30934,14 @@ enabled, the debug registers values are shown when @value{GDBN} inserts or removes a hardware breakpoint or watchpoint, and when the inferior triggers a hardware-assisted breakpoint or watchpoint. +@kindex maint set show-all-tib +@kindex maint show show-all-tib +@item maint set show-all-tib +@itemx maint show show-all-tib +Control whether to show all non zero areas within a 1k block starting +at thread local base, when using the @samp{info w32 thread-information-block} +command. + @kindex maint space @cindex memory used by commands @item maint space @@ -30478,6 +32053,18 @@ Here are the currently defined query and set packets: @table @samp +@item QAllow:@var{op}:@var{val}@dots{} +@cindex @samp{QAllow} packet +Specify which operations @value{GDBN} expects to request of the +target, as a semicolon-separated list of operation name and value +pairs. Possible values for @var{op} include @samp{WriteReg}, +@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace}, +@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0, +indicating that @value{GDBN} will not request the operation, or 1, +indicating that it may. (The target can then use this to set up its +own internals optimally, for instance if the debugger never expects to +insert breakpoints, it may not need to install its own trap handler.) + @item qC @cindex current thread, remote request @cindex @samp{qC} packet @@ -30543,7 +32130,7 @@ In response to each query, the target will reply with a list of one or more thread IDs, separated by commas. @value{GDBN} will respond to each reply with a request for more thread ids (using the @samp{qs} form of the query), until the target responds -with @samp{l} (lower-case el, for @dfn{last}). +with @samp{l} (lower-case ell, for @dfn{last}). Refer to @ref{thread-id syntax}, for the format of the @var{thread-id} fields. @@ -30580,6 +32167,27 @@ An error occurred. @var{nn} are hex digits. An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub. @end table +@item qGetTIBAddr:@var{thread-id} +@cindex get thread information block address +@cindex @samp{qGetTIBAddr} packet +Fetch address of the Windows OS specific Thread Information Block. + +@var{thread-id} is the thread ID associated with the thread. + +Reply: +@table @samp +@item @var{XX}@dots{} +Hex encoded (big endian) bytes representing the linear address of the +thread information block. + +@item E @var{nn} +An error occured. This means that either the thread was not found, or the +address could not be retrieved. + +@item +An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub. +@end table + @item qL @var{startflag} @var{threadcount} @var{nextthread} Obtain thread information from RTOS. Where: @var{startflag} (one hex digit) is one to indicate the first query and zero to indicate a @@ -30839,6 +32447,11 @@ This feature indicates that @value{GDBN} supports the XML target description. If the stub sees @samp{xmlRegisters=} with target specific strings separated by a comma, it will report register description. + +@item qRelocInsn +This feature indicates whether @value{GDBN} supports the +@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate +instruction reply packet}). @end table Stubs should ignore any unknown values for @@ -30907,6 +32520,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab Yes +@item @samp{qXfer:sdata:read} +@tab No +@tab @samp{-} +@tab Yes + @item @samp{qXfer:spu:read} @tab No @tab @samp{-} @@ -30973,6 +32591,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{QAllow} +@tab No +@tab @samp{-} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -31005,6 +32628,10 @@ The remote stub understands the @samp{qXfer:libraries:read} packet The remote stub understands the @samp{qXfer:memory-map:read} packet (@pxref{qXfer memory map read}). +@item qXfer:sdata:read +The remote stub understands the @samp{qXfer:sdata:read} packet +(@pxref{qXfer sdata read}). + @item qXfer:spu:read The remote stub understands the @samp{qXfer:spu:read} packet (@pxref{qXfer spu read}). @@ -31070,6 +32697,13 @@ The remote stub accepts and implements the reverse step packet The remote stub understands the @samp{QTDPsrc} packet that supplies the source form of tracepoint definitions. +@item QAllow +The remote stub understands the @samp{QAllow} packet. + +@item StaticTracepoint +@cindex static tracepoints, in remote protocol +The remote stub supports static tracepoints. + @end table @item qSymbol:: @@ -31154,6 +32788,9 @@ packets.) @itemx QTro @itemx qTStatus @itemx qTV +@itemx qTfSTM +@itemx qTsSTM +@itemx qTSTMat @xref{Tracepoint Packets}. @item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} @@ -31210,6 +32847,18 @@ annex part of the generic @samp{qXfer} packet must be empty This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@item qXfer:sdata:read::@var{offset},@var{length} +@anchor{qXfer sdata read} + +Read contents of the extra collected static tracepoint marker +information. The annex part of the generic @samp{qXfer} packet must +be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint +Action Lists}. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). + @item qXfer:siginfo:read::@var{offset},@var{length} @anchor{qXfer siginfo read} Read contents of the extra signal information on the target @@ -31447,6 +33096,8 @@ Replies: @table @samp @item OK The packet was understood and carried out. +@item qRelocInsn +@xref{Tracepoint Packets,,Relocate instruction reply packet}. @item The packet was not recognized. @end table @@ -31511,6 +33162,8 @@ Replies: @table @samp @item OK The packet was understood and carried out. +@item qRelocInsn +@xref{Tracepoint Packets,,Relocate instruction reply packet}. @item The packet was not recognized. @end table @@ -31602,8 +33255,10 @@ Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first frame @emph{outside} the given range of addresses (exclusive). @item QTStart -Begin the tracepoint experiment. Begin collecting data from tracepoint -hits in the trace frame buffer. +Begin the tracepoint experiment. Begin collecting data from +tracepoint hits in the trace frame buffer. This packet supports the +@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate +instruction reply packet}). @item QTStop End the tracepoint experiment. Stop collecting trace frames. @@ -31743,6 +33398,43 @@ and multiple @code{qTsV} to get additional variables. Replies to these packets follow the syntax of the @code{QTDV} packets that define trace state variables. +@item qTfSTM +@itemx qTsSTM +These packets request data about static tracepoint markers that exist +in the target program. @value{GDBN} sends @code{qTfSTM} to get the +first piece of data, and multiple @code{qTsSTM} to get additional +pieces. Replies to these packets take the following form: + +Reply: +@table @samp +@item m @var{address}:@var{id}:@var{extra} +A single marker +@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} +a comma-separated list of markers +@item l +(lower case letter @samp{L}) denotes end of list. +@item E @var{nn} +An error occurred. @var{nn} are hex digits. +@item +An empty reply indicates that the request is not supported by the +stub. +@end table + +@var{address} is encoded in hex. +@var{id} and @var{extra} are strings encoded in hex. + +In response to each query, the target will reply with a list of one or +more markers, separated by commas. @value{GDBN} will respond to each +reply with a request for more markers (using the @samp{qs} form of the +query), until the target responds with @samp{l} (lower-case ell, for +@dfn{last}). + +@item qTSTMat:@var{address} +This packets requests data about static tracepoint markers in the +target program at @var{address}. Replies to this packet follow the +syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static +tracepoint markers. + @item QTSave:@var{filename} This packet directs the target to save trace data to the file name @var{filename} in the target's filesystem. @var{filename} is encoded @@ -31764,6 +33456,44 @@ This packet directs the target to use a circular trace buffer if @end table +@subsection Relocate instruction reply packet +When installing fast tracepoints in memory, the target may need to +relocate the instruction currently at the tracepoint address to a +different address in memory. For most instructions, a simple copy is +enough, but, for example, call instructions that implicitly push the +return address on the stack, and relative branches or other +PC-relative instructions require offset adjustment, so that the effect +of executing the instruction at a different address is the same as if +it had executed in the original location. + +In response to several of the tracepoint packets, the target may also +respond with a number of intermediate @samp{qRelocInsn} request +packets before the final result packet, to have @value{GDBN} handle +this relocation operation. If a packet supports this mechanism, its +documentation will explicitly say so. See for example the above +descriptions for the @samp{QTStart} and @samp{QTDP} packets. The +format of the request is: + +@table @samp +@item qRelocInsn:@var{from};@var{to} + +This requests @value{GDBN} to copy instruction at address @var{from} +to address @var{to}, possibly adjusted so that executing the +instruction at @var{to} has the same effect as executing it at +@var{from}. @value{GDBN} writes the adjusted instruction to target +memory starting at @var{to}. +@end table + +Replies: +@table @samp +@item qRelocInsn:@var{adjusted_size} +Informs the stub the relocation is complete. @var{adjusted_size} is +the length in bytes of resulting relocated instruction sequence. +@item E @var{NN} +A badly formed request was detected, or an error was encountered while +relocating the instruction. +@end table + @node Host I/O Packets @section Host I/O Packets @cindex Host I/O, remote protocol @@ -33977,10 +35707,16 @@ registers using the capitalization used in the description. @subsection ARM Features @cindex target descriptions, ARM features -The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets. +The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile +ARM targets. It should contain registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc}, and @samp{cpsr}. +For M-profile targets (e.g. Cortex-M3), the @samp{org.gnu.gdb.arm.core} +feature is replaced by @samp{org.gnu.gdb.arm.m-profile}. It should contain +registers @samp{r0} through @samp{r13}, @samp{sp}, @samp{lr}, @samp{pc}, +and @samp{xpsr}. + The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it should contain registers @samp{f0} through @samp{f7} and @samp{fps}. @@ -34047,7 +35783,6 @@ describe the upper 128 bits of @sc{ymm} registers: @samp{ymm0h} through @samp{ymm7h} for i386 @item @samp{ymm0h} through @samp{ymm15h} for amd64 -@item @end itemize The @samp{org.gnu.gdb.i386.linux} feature is optional. It should @@ -34180,9 +35915,9 @@ which @value{GDBN} currently ignores. @include gpl.texi -@raisesections +@node GNU Free Documentation License +@appendix GNU Free Documentation License @include fdl.texi -@lowersections @node Index @unnumbered Index