X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=b82f3c67a8a6718544176f84b23677ca267df9dc;hb=f2faf941ae49653ff6e1485adfee299313d47c91;hp=566cb9a639d512d73fde6e9354e2c17c0d070391;hpb=55b400279267cad460ca62a8211f0b414f564e93;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 566cb9a639..b82f3c67a8 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -2791,9 +2791,9 @@ example, the list of inferiors bound to the program space. @smallexample (@value{GDBP}) maint info program-spaces Id Executable +* 1 hello 2 goodbye Bound inferiors: ID 1 (process 21561) -* 1 hello @end smallexample Here we can see that no inferior is running the program @code{hello}, @@ -2938,9 +2938,9 @@ For example, @smallexample (@value{GDBP}) info threads Id Target Id Frame - 3 process 35 thread 27 0x34e5 in sigpause () - 2 process 35 thread 23 0x34e5 in sigpause () * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 2 process 35 thread 23 0x34e5 in sigpause () + 3 process 35 thread 27 0x34e5 in sigpause () at threadtest.c:68 @end smallexample @@ -3254,8 +3254,8 @@ process 12020 is executing new program: prog2 Program exited normally. (@value{GDBP}) info inferiors Id Description Executable -* 2 prog2 1 prog1 +* 2 prog2 @end smallexample @item same @@ -5836,17 +5836,20 @@ locking the OS scheduler to allow only a single thread to run. @item set scheduler-locking @var{mode} @cindex scheduler locking mode @cindex lock scheduler -Set the scheduler locking mode. If it is @code{off}, then there is no -locking and any thread may run at any time. If @code{on}, then only the -current thread may run when the inferior is resumed. The @code{step} -mode optimizes for single-stepping; it prevents other threads -from preempting the current thread while you are stepping, so that -the focus of debugging does not change unexpectedly. -Other threads never get a chance to run when you step, and they are -completely free to run when you use commands -like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another -thread hits a breakpoint during its timeslice, @value{GDBN} does not change -the current thread away from the thread that you are debugging. +Set the scheduler locking mode. It applies to normal execution, +record mode, and replay mode. If it is @code{off}, then there is no +locking and any thread may run at any time. If @code{on}, then only +the current thread may run when the inferior is resumed. The +@code{step} mode optimizes for single-stepping; it prevents other +threads from preempting the current thread while you are stepping, so +that the focus of debugging does not change unexpectedly. Other +threads never get a chance to run when you step, and they are +completely free to run when you use commands like @samp{continue}, +@samp{until}, or @samp{finish}. However, unless another thread hits a +breakpoint during its timeslice, @value{GDBN} does not change the +current thread away from the thread that you are debugging. The +@code{replay} mode behaves like @code{off} in record mode and like +@code{on} in replay mode. @item show scheduler-locking Display the current scheduler locking mode. @@ -6060,9 +6063,9 @@ breakpoints on all threads, or on a particular thread. @cindex breakpoints and threads @cindex thread breakpoints @kindex break @dots{} thread @var{threadno} -@item break @var{linespec} thread @var{threadno} -@itemx break @var{linespec} thread @var{threadno} if @dots{} -@var{linespec} specifies source lines; there are several ways of +@item break @var{location} thread @var{threadno} +@itemx break @var{location} thread @var{threadno} if @dots{} +@var{location} specifies source lines; there are several ways of writing them (@pxref{Specify Location}), but the effect is always to specify some source line. @@ -6417,12 +6420,16 @@ For architecture environments that support process record and replay, @kindex record full @kindex record btrace @kindex record btrace bts +@kindex record btrace pt @kindex record bts +@kindex record pt @kindex rec @kindex rec full @kindex rec btrace @kindex rec btrace bts +@kindex rec btrace pt @kindex rec bts +@kindex rec pt @item record @var{method} This command starts the process record and replay target. The recording method can be specified as parameter. Without a parameter @@ -6438,8 +6445,9 @@ execution. @item btrace @var{format} Hardware-supported instruction recording. This method does not record data. Further, the data is collected in a ring buffer so old data will -be overwritten when the buffer is full. It allows limited replay and -reverse execution. +be overwritten when the buffer is full. It allows limited reverse +execution. Variables and registers are not available during reverse +execution. The recording format can be specified as parameter. Without a parameter the command chooses the recording format. The following recording @@ -6451,6 +6459,21 @@ formats are available: Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In this format, the processor stores a from/to record for each executed branch in the btrace ring buffer. + +@item pt +@cindex Intel(R) Processor Trace +Use the @dfn{Intel(R) Processor Trace} recording format. In this +format, the processor stores the execution trace in a compressed form +that is afterwards decoded by @value{GDBN}. + +The trace can be recorded with very low overhead. The compressed +trace format also allows small trace buffers to already contain a big +number of instructions compared to @acronym{BTS}. + +Decoding the recorded execution trace, on the other hand, is more +expensive than decoding @acronym{BTS} trace. This is mostly due to the +increased number of instructions to process. You should increase the +buffer-size with care. @end table Not all recording formats may be available on all processors. @@ -6461,9 +6484,6 @@ already running. Therefore, you need first to start the process with the @kbd{run} or @kbd{start} commands, and then start the recording with the @kbd{record @var{method}} command. -Both @code{record @var{method}} and @code{rec @var{method}} are -aliases of @code{target record-@var{method}}. - @cindex displaced stepping, and process record and replay Displaced stepping (@pxref{Maintenance Commands,, displaced stepping}) will be automatically disabled when process record and replay target @@ -6629,6 +6649,29 @@ also need longer to process the branch trace data before it can be used. Show the current setting of the requested ring buffer size for branch tracing in @acronym{BTS} format. +@kindex set record btrace pt +@item set record btrace pt buffer-size @var{size} +@itemx set record btrace pt buffer-size unlimited +Set the requested ring buffer size for branch tracing in Intel(R) +Processor Trace format. Default is 16KB. + +If @var{size} is a positive number, then @value{GDBN} will try to +allocate a buffer of at least @var{size} bytes for each new thread +that uses the btrace recording method and the Intel(R) Processor Trace +format. The actually obtained buffer size may differ from the +requested @var{size}. Use the @code{info record} command to see the +actual buffer size for each thread. + +If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to +allocate a buffer of 4MB. + +Bigger buffers mean longer traces. On the other hand, @value{GDBN} will +also need longer to process the branch trace data before it can be used. + +@item show record btrace pt buffer-size @var{size} +Show the current setting of the requested ring buffer size for branch +tracing in Intel(R) Processor Trace format. + @kindex info record @item info record Show various statistics about the recording depending on the recording @@ -6674,6 +6717,12 @@ For the @code{bts} recording format, it also shows: @item Size of the perf ring buffer. @end itemize + +For the @code{pt} recording format, it also shows: +@itemize @bullet +@item +Size of the perf ring buffer. +@end itemize @end table @kindex record delete @@ -6690,8 +6739,27 @@ recorded ``future'' and begin recording a new ``future''. Disassembles instructions from the recorded execution log. By default, ten instructions are disassembled. This can be changed using the @code{set record instruction-history-size} command. Instructions -are printed in execution order. There are several ways to specify -what part of the execution log to disassemble: +are printed in execution order. + +It can also print mixed source+disassembly if you specify the the +@code{/m} or @code{/s} modifier, and print the raw instructions in hex +as well as in symbolic form by specifying the @code{/r} modifier. + +The current position marker is printed for the instruction at the +current program counter value. This instruction can appear multiple +times in the trace and the current position marker will be printed +every time. To omit the current position marker, specify the +@code{/p} modifier. + +To better align the printed instructions when the trace contains +instructions from more than one function, the function name may be +omitted by specifying the @code{/f} modifier. + +Speculatively executed instructions are prefixed with @samp{?}. This +feature is not available for all recording formats. + +There are several ways to specify what part of the execution log to +disassemble: @table @code @item record instruction-history @var{insn} @@ -6711,7 +6779,7 @@ Disassembles ten more instructions after the last disassembly. @item record instruction-history - Disassembles ten more instructions before the last disassembly. -@item record instruction-history @var{begin} @var{end} +@item record instruction-history @var{begin}, @var{end} Disassembles instructions beginning with instruction number @var{begin} until instruction number @var{end}. The instruction number @var{end} is included. @@ -6783,7 +6851,7 @@ Prints ten more functions after the last ten-line print. @item record function-call-history - Prints ten more functions before the last ten-line print. -@item record function-call-history @var{begin} @var{end} +@item record function-call-history @var{begin}, @var{end} Prints functions beginning with function number @var{begin} until function number @var{end}. The function number @var{end} is included. @end table @@ -6897,23 +6965,6 @@ it had a separate frame, which is numbered zero as usual, allowing correct tracing of the function call chain. However, @value{GDBN} has no provision for frameless functions elsewhere in the stack. -@table @code -@kindex frame@r{, command} -@cindex current stack frame -@item frame @r{[}@var{framespec}@r{]} -The @code{frame} command allows you to move from one stack frame to another, -and to print the stack frame you select. The @var{framespec} may be either the -address of the frame or the stack frame number. Without an argument, -@code{frame} prints the current stack frame. - -@kindex select-frame -@cindex selecting frame silently -@item select-frame -The @code{select-frame} command allows you to move from one stack frame -to another without printing the frame. This is the silent version of -@code{frame}. -@end table - @node Backtrace @section Backtraces @@ -7113,6 +7164,156 @@ Display an absolute filename. Show the current way to display filenames. @end table +@node Selection +@section Selecting a Frame + +Most commands for examining the stack and other data in your program work on +whichever stack frame is selected at the moment. Here are the commands for +selecting a stack frame; all of them finish by printing a brief description +of the stack frame just selected. + +@table @code +@kindex frame@r{, selecting} +@kindex f @r{(@code{frame})} +@item frame @var{n} +@itemx f @var{n} +Select frame number @var{n}. Recall that frame zero is the innermost +(currently executing) frame, frame one is the frame that called the +innermost one, and so on. The highest-numbered frame is the one for +@code{main}. + +@item frame @var{stack-addr} [ @var{pc-addr} ] +@itemx f @var{stack-addr} [ @var{pc-addr} ] +Select the frame at address @var{stack-addr}. This is useful mainly if the +chaining of stack frames has been damaged by a bug, making it +impossible for @value{GDBN} to assign numbers properly to all frames. In +addition, this can be useful when your program has multiple stacks and +switches between them. The optional @var{pc-addr} can also be given to +specify the value of PC for the stack frame. + +@kindex up +@item up @var{n} +Move @var{n} frames up the stack; @var{n} defaults to 1. For positive +numbers @var{n}, this advances toward the outermost frame, to higher +frame numbers, to frames that have existed longer. + +@kindex down +@kindex do @r{(@code{down})} +@item down @var{n} +Move @var{n} frames down the stack; @var{n} defaults to 1. For +positive numbers @var{n}, this advances toward the innermost frame, to +lower frame numbers, to frames that were created more recently. +You may abbreviate @code{down} as @code{do}. +@end table + +All of these commands end by printing two lines of output describing the +frame. The first line shows the frame number, the function name, the +arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + +@need 1000 +For example: + +@smallexample +@group +(@value{GDBP}) up +#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 +10 read_input_file (argv[i]); +@end group +@end smallexample + +After such a printout, the @code{list} command with no arguments +prints ten lines centered on the point of execution in the frame. +You can also edit the program at the point of execution with your favorite +editing program by typing @code{edit}. +@xref{List, ,Printing Source Lines}, +for details. + +@table @code +@kindex select-frame +@item select-frame +The @code{select-frame} command is a variant of @code{frame} that does +not display the new frame after selecting it. This command is +intended primarily for use in @value{GDBN} command scripts, where the +output might be unnecessary and distracting. + +@kindex down-silently +@kindex up-silently +@item up-silently @var{n} +@itemx down-silently @var{n} +These two commands are variants of @code{up} and @code{down}, +respectively; they differ in that they do their work silently, without +causing display of the new frame. They are intended primarily for use +in @value{GDBN} command scripts, where the output might be unnecessary and +distracting. +@end table + +@node Frame Info +@section Information About a Frame + +There are several other commands to print information about the selected +stack frame. + +@table @code +@item frame +@itemx f +When used without any argument, this command does not change which +frame is selected, but prints a brief description of the currently +selected stack frame. It can be abbreviated @code{f}. With an +argument, this command is used to select a stack frame. +@xref{Selection, ,Selecting a Frame}. + +@kindex info frame +@kindex info f @r{(@code{info frame})} +@item info frame +@itemx info f +This command prints a verbose description of the selected stack frame, +including: + +@itemize @bullet +@item +the address of the frame +@item +the address of the next frame down (called by this frame) +@item +the address of the next frame up (caller of this frame) +@item +the language in which the source code corresponding to this frame is written +@item +the address of the frame's arguments +@item +the address of the frame's local variables +@item +the program counter saved in it (the address of execution in the caller frame) +@item +which registers were saved in the frame +@end itemize + +@noindent The verbose description is useful when +something has gone wrong that has made the stack format fail to fit +the usual conventions. + +@item info frame @var{addr} +@itemx info f @var{addr} +Print a verbose description of the frame at address @var{addr}, without +selecting that frame. The selected frame remains unchanged by this +command. This requires the same kind of address (more than one for some +architectures) that you specify in the @code{frame} command. +@xref{Selection, ,Selecting a Frame}. + +@kindex info args +@item info args +Print the arguments of the selected frame, each on a separate line. + +@item info locals +@kindex info locals +Print the local variables of the selected frame, each on a separate +line. These are all variables (declared either static or automatic) +accessible at the point of execution of the selected frame. + +@end table + @node Frame Filter Management @section Management of Frame Filters. @cindex managing frame filters @@ -7256,158 +7457,6 @@ objfile /build/test frame-filters: @end smallexample @end table -@node Selection -@section Selecting a Frame - -Most commands for examining the stack and other data in your program work on -whichever stack frame is selected at the moment. Here are the commands for -selecting a stack frame; all of them finish by printing a brief description -of the stack frame just selected. - -@table @code -@kindex frame@r{, selecting} -@kindex f @r{(@code{frame})} -@item frame @var{n} -@itemx f @var{n} -Select frame number @var{n}. Recall that frame zero is the innermost -(currently executing) frame, frame one is the frame that called the -innermost one, and so on. The highest-numbered frame is the one for -@code{main}. - -@item frame @var{addr} -@itemx f @var{addr} -Select the frame at address @var{addr}. This is useful mainly if the -chaining of stack frames has been damaged by a bug, making it -impossible for @value{GDBN} to assign numbers properly to all frames. In -addition, this can be useful when your program has multiple stacks and -switches between them. - -On the SPARC architecture, @code{frame} needs two addresses to -select an arbitrary frame: a frame pointer and a stack pointer. - -On the @acronym{MIPS} and Alpha architecture, it needs two addresses: a stack -pointer and a program counter. - -On the 29k architecture, it needs three addresses: a register stack -pointer, a program counter, and a memory stack pointer. - -@kindex up -@item up @var{n} -Move @var{n} frames up the stack; @var{n} defaults to 1. For positive -numbers @var{n}, this advances toward the outermost frame, to higher -frame numbers, to frames that have existed longer. - -@kindex down -@kindex do @r{(@code{down})} -@item down @var{n} -Move @var{n} frames down the stack; @var{n} defaults to 1. For -positive numbers @var{n}, this advances toward the innermost frame, to -lower frame numbers, to frames that were created more recently. -You may abbreviate @code{down} as @code{do}. -@end table - -All of these commands end by printing two lines of output describing the -frame. The first line shows the frame number, the function name, the -arguments, and the source file and line number of execution in that -frame. The second line shows the text of that source line. - -@need 1000 -For example: - -@smallexample -@group -(@value{GDBP}) up -#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) - at env.c:10 -10 read_input_file (argv[i]); -@end group -@end smallexample - -After such a printout, the @code{list} command with no arguments -prints ten lines centered on the point of execution in the frame. -You can also edit the program at the point of execution with your favorite -editing program by typing @code{edit}. -@xref{List, ,Printing Source Lines}, -for details. - -@table @code -@kindex down-silently -@kindex up-silently -@item up-silently @var{n} -@itemx down-silently @var{n} -These two commands are variants of @code{up} and @code{down}, -respectively; they differ in that they do their work silently, without -causing display of the new frame. They are intended primarily for use -in @value{GDBN} command scripts, where the output might be unnecessary and -distracting. -@end table - -@node Frame Info -@section Information About a Frame - -There are several other commands to print information about the selected -stack frame. - -@table @code -@item frame -@itemx f -When used without any argument, this command does not change which -frame is selected, but prints a brief description of the currently -selected stack frame. It can be abbreviated @code{f}. With an -argument, this command is used to select a stack frame. -@xref{Selection, ,Selecting a Frame}. - -@kindex info frame -@kindex info f @r{(@code{info frame})} -@item info frame -@itemx info f -This command prints a verbose description of the selected stack frame, -including: - -@itemize @bullet -@item -the address of the frame -@item -the address of the next frame down (called by this frame) -@item -the address of the next frame up (caller of this frame) -@item -the language in which the source code corresponding to this frame is written -@item -the address of the frame's arguments -@item -the address of the frame's local variables -@item -the program counter saved in it (the address of execution in the caller frame) -@item -which registers were saved in the frame -@end itemize - -@noindent The verbose description is useful when -something has gone wrong that has made the stack format fail to fit -the usual conventions. - -@item info frame @var{addr} -@itemx info f @var{addr} -Print a verbose description of the frame at address @var{addr}, without -selecting that frame. The selected frame remains unchanged by this -command. This requires the same kind of address (more than one for some -architectures) that you specify in the @code{frame} command. -@xref{Selection, ,Selecting a Frame}. - -@kindex info args -@item info args -Print the arguments of the selected frame, each on a separate line. - -@item info locals -@kindex info locals -Print the local variables of the selected frame, each on a separate -line. These are all variables (declared either static or automatic) -accessible at the point of execution of the selected frame. - -@end table - - @node Source @chapter Examining Source Files @@ -7488,21 +7537,21 @@ argument of @samp{-}; that argument is preserved in repetition so that each repetition moves up in the source file. In general, the @code{list} command expects you to supply zero, one or two -@dfn{linespecs}. Linespecs specify source lines; there are several ways +@dfn{locations}. Locations specify source lines; there are several ways of writing them (@pxref{Specify Location}), but the effect is always to specify some source line. Here is a complete description of the possible arguments for @code{list}: @table @code -@item list @var{linespec} -Print lines centered around the line specified by @var{linespec}. +@item list @var{location} +Print lines centered around the line specified by @var{location}. @item list @var{first},@var{last} Print lines from @var{first} to @var{last}. Both arguments are -linespecs. When a @code{list} command has two linespecs, and the -source file of the second linespec is omitted, this refers to -the same source file as the first linespec. +locations. When a @code{list} command has two locations, and the +source file of the second location is omitted, this refers to +the same source file as the first location. @item list ,@var{last} Print lines ending with @var{last}. @@ -7523,15 +7572,28 @@ As described in the preceding table. @node Specify Location @section Specifying a Location @cindex specifying location -@cindex linespec +@cindex location +@cindex source location + +@menu +* Linespec Locations:: Linespec locations +* Explicit Locations:: Explicit locations +* Address Locations:: Address locations +@end menu Several @value{GDBN} commands accept arguments that specify a location of your program's code. Since @value{GDBN} is a source-level -debugger, a location usually specifies some line in the source code; -for that reason, locations are also known as @dfn{linespecs}. +debugger, a location usually specifies some line in the source code. +Locations may be specified using three different formats: +linespec locations, explicit locations, or address locations. + +@node Linespec Locations +@subsection Linespec Locations +@cindex linespec locations -Here are all the different ways of specifying a code location that -@value{GDBN} understands: +A @dfn{linespec} is a colon-separated list of source location parameters such +as file name, function name, etc. Here are all the different ways of +specifying a linespec: @table @code @item @var{linenum} @@ -7570,25 +7632,93 @@ 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 -line that contains @var{address}. For @code{break} and other -breakpoint oriented commands, this can be used to set breakpoints in +Specifies the line at which the label named @var{label} appears +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. + +@cindex breakpoint at static probe point +@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} +The @sc{gnu}/Linux tool @code{SystemTap} provides a way for +applications to embed static probes. @xref{Static Probe Points}, for more +information on finding and using static probes. This form of linespec +specifies the location of such a static probe. + +If @var{objfile} is given, only probes coming from that shared library +or executable matching @var{objfile} as a regular expression are considered. +If @var{provider} is given, then only probes from that provider are considered. +If several probes match the spec, @value{GDBN} will insert a breakpoint at +each one of those probes. +@end table + +@node Explicit Locations +@subsection Explicit Locations +@cindex explicit locations + +@dfn{Explicit locations} allow the user to directly specify the source +location's parameters using option-value pairs. + +Explicit locations are useful when several functions, labels, or +file names have the same name (base name for files) in the program's +sources. In these cases, explicit locations point to the source +line you meant more accurately and unambiguously. Also, using +explicit locations might be faster in large programs. + +For example, the linespec @samp{foo:bar} may refer to a function @code{bar} +defined in the file named @file{foo} or the label @code{bar} in a function +named @code{foo}. @value{GDBN} must search either the file system or +the symbol table to know. + +The list of valid explicit location options is summarized in the +following table: + +@table @code +@item -source @var{filename} +The value specifies the source file name. To differentiate between +files with the same base name, prepend as many directories as is necessary +to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise +@value{GDBN} will use the first file it finds with the given base +name. This option requires the use of either @code{-function} or @code{-line}. + +@item -function @var{function} +The value specifies the name of a function. Operations +on function locations unmodified by other options (such as @code{-label} +or @code{-line}) refer to the line that begins the body of the function. +In C, for example, this is the line with the open brace. + +@item -label @var{label} +The value specifies the name of a label. When the function +name is not specified, the label is searched in the function of the currently +selected stack frame. + +@item -line @var{number} +The value specifies a line offset for the location. The offset may either +be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on +the command. When specified without any other options, the line offset is +relative to the current line. +@end table + +Explicit location options may be abbreviated by omitting any non-unique +trailing characters from the option name, e.g., @code{break -s main.c -li 3}. + +@node Address Locations +@subsection Address Locations +@cindex address locations + +@dfn{Address locations} indicate a specific program address. They have +the generalized form *@var{address}. + +For line-oriented commands, such as @code{list} and @code{edit}, this +specifies a source line that contains @var{address}. For @code{break} and +other breakpoint-oriented commands, this can be used to set breakpoints in parts of your program which do not have debugging information or source files. Here @var{address} may be any expression valid in the current working language (@pxref{Languages, working language}) that specifies a code address. In addition, as a convenience, @value{GDBN} extends the -semantics of expressions used in locations to cover the situations -that frequently happen during debugging. Here are the various forms +semantics of expressions used in locations to cover several situations +that frequently occur during debugging. Here are the various forms of @var{address}: @table @code @@ -7613,22 +7743,6 @@ specify the function unambiguously, e.g., if there are several functions with identical names in different source files. @end table -@cindex breakpoint at static probe point -@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} -The @sc{gnu}/Linux tool @code{SystemTap} provides a way for -applications to embed static probes. @xref{Static Probe Points}, for more -information on finding and using static probes. This form of linespec -specifies the location of such a static probe. - -If @var{objfile} is given, only probes coming from that shared library -or executable matching @var{objfile} as a regular expression are considered. -If @var{provider} is given, then only probes from that provider are considered. -If several probes match the spec, @value{GDBN} will insert a breakpoint at -each one of those probes. - -@end table - - @node Edit @section Editing Source Files @cindex editing source files @@ -7872,11 +7986,11 @@ For example, if the file @file{/foo/bar/baz.c} was moved to @file{/mnt/cross/baz.c}, then the command @smallexample -(@value{GDBP}) set substitute-path /usr/src /mnt/cross +(@value{GDBP}) set substitute-path /foo/bar /mnt/cross @end smallexample @noindent -will tell @value{GDBN} to replace @samp{/usr/src} with +will tell @value{GDBN} to replace @samp{/foo/bar} with @samp{/mnt/cross}, which will allow @value{GDBN} to find the file @file{baz.c} even though it was moved. @@ -7946,9 +8060,9 @@ well as hex. @table @code @kindex info line -@item info line @var{linespec} +@item info line @var{location} Print the starting and ending addresses of the compiled code for -source line @var{linespec}. You can specify source lines in any of +source line @var{location}. You can specify source lines in any of the ways documented in @ref{Specify Location}. @end table @@ -7966,7 +8080,7 @@ Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. @noindent @cindex code address and its source line We can also inquire (using @code{*@var{addr}} as the form for -@var{linespec}) what source line covers a particular address: +@var{location}) what source line covers a particular address: @smallexample (@value{GDBP}) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. @@ -7990,11 +8104,12 @@ Variables}). @cindex listing machine instructions @item disassemble @itemx disassemble /m +@itemx disassemble /s @itemx disassemble /r This specialized command dumps a range of memory as machine instructions. It can also print mixed source+disassembly by specifying -the @code{/m} modifier and print the raw instructions in hex as well as -in symbolic form by specifying the @code{/r}. +the @code{/m} or @code{/s} modifier and print the raw instructions in hex +as well as in symbolic form by specifying the @code{/r} modifier. The default memory range is the function surrounding the program counter of the selected frame. A single argument to this command is a program counter value; @value{GDBN} dumps the function @@ -8038,8 +8153,9 @@ Dump of assembler code from 0x32c4 to 0x32e4: End of assembler dump. @end smallexample -Here is an example showing mixed source+assembly for Intel x86, when the -program is stopped just after function prologue: +Here is an example showing mixed source+assembly for Intel x86 +with @code{/m} or @code{/s}, when the program is stopped just after +function prologue in a non-optimized function with no inline code. @smallexample (@value{GDBP}) disas /m main @@ -8064,6 +8180,96 @@ Dump of assembler code for function main: End of assembler dump. @end smallexample +The @code{/m} option is deprecated as its output is not useful when +there is either inlined code or re-ordered code. +The @code{/s} option is the preferred choice. +Here is an example for AMD x86-64 showing the difference between +@code{/m} output and @code{/s} output. +This example has one inline function defined in a header file, +and the code is compiled with @samp{-O2} optimization. +Note how the @code{/m} output is missing the disassembly of +several instructions that are present in the @code{/s} output. + +@file{foo.h}: + +@smallexample +int +foo (int a) +@{ + if (a < 0) + return a * 2; + if (a == 0) + return 1; + return a + 10; +@} +@end smallexample + +@file{foo.c}: + +@smallexample +#include "foo.h" +volatile int x, y; +int +main () +@{ + x = foo (y); + return 0; +@} +@end smallexample + +@smallexample +(@value{GDBP}) disas /m main +Dump of assembler code for function main: +5 @{ + +6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + +7 return 0; +8 @} + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 + +End of assembler dump. +(@value{GDBP}) disas /s main +Dump of assembler code for function main: +foo.c: +5 @{ +6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + +foo.h: +4 if (a < 0) + 0x0000000000400406 <+6>: test %eax,%eax + 0x0000000000400408 <+8>: js 0x400420 + +6 if (a == 0) +7 return 1; +8 return a + 10; + 0x000000000040040a <+10>: lea 0xa(%rax),%edx + 0x000000000040040d <+13>: test %eax,%eax + 0x000000000040040f <+15>: mov $0x1,%eax + 0x0000000000400414 <+20>: cmovne %edx,%eax + +foo.c: +6 x = foo (y); + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + +7 return 0; +8 @} + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + +foo.h: +5 return a * 2; + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 +End of assembler dump. +@end smallexample + Here is another example showing raw instructions in hex for AMD x86-64, @smallexample @@ -8076,7 +8282,7 @@ Dump of assembler code from 0x400281 to 0x40028b: End of assembler dump. @end smallexample -Addresses cannot be specified as a linespec (@pxref{Specify Location}). +Addresses cannot be specified as a location (@pxref{Specify Location}). So, for example, if you want to disassemble function @code{bar} in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}. @@ -9009,6 +9215,18 @@ If the @code{x} command has a repeat count, the address and contents saved are from the last memory unit printed; this is not the same as the last address printed if several units were printed on the last line of output. +@anchor{addressable memory unit} +@cindex addressable memory unit +Most targets have an addressable memory unit size of 8 bits. This means +that to each memory address are associated 8 bits of data. Some +targets, however, have other addressable memory unit sizes. +Within @value{GDBN} and this document, the term +@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used +when explicitly referring to a chunk of data of that size. The word +@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of +the addressable memory unit size of the target. For most systems, +addressable memory unit is a synonym of byte. + @cindex remote memory comparison @cindex target memory comparison @cindex verify remote memory image @@ -11717,9 +11935,9 @@ argument processing and the beginning of @var{macro} for non C-like macros where the macro may begin with a hyphen. @kindex info macros -@item info macros @var{linespec} +@item info macros @var{location} Show all macro definitions that are in effect at the location specified -by @var{linespec}, and describe the source location or compiler +by @var{location}, and describe the source location or compiler command-line where those definitions were established. @kindex macro define @@ -12024,12 +12242,11 @@ conditions and actions. @kindex trace @item trace @var{location} The @code{trace} command is very similar to the @code{break} command. -Its argument @var{location} can be a source line, a function name, or -an address in the target program. @xref{Specify Location}. The -@code{trace} command defines a tracepoint, which is a point in the -target program where the debugger will briefly stop, collect some -data, and then allow the program to continue. Setting a tracepoint or -changing its actions takes effect immediately if the remote stub +Its argument @var{location} can be any valid location. +@xref{Specify Location}. The @code{trace} command defines a tracepoint, +which is a point in the target program where the debugger will briefly stop, +collect some data, and then allow the program to continue. Setting a tracepoint +or changing its actions takes effect immediately if the remote stub supports the @samp{InstallInTrace} feature (@pxref{install tracepoint in tracing}). If remote stub doesn't support the @samp{InstallInTrace} feature, all @@ -15909,14 +16126,14 @@ from the current task to the given task. #4 0x804aacc in un () at un.adb:5 @end smallexample -@item break @var{linespec} task @var{taskno} -@itemx break @var{linespec} task @var{taskno} if @dots{} +@item break @var{location} task @var{taskno} +@itemx break @var{location} task @var{taskno} if @dots{} @cindex breakpoints and tasks, in Ada @cindex task breakpoints, in Ada @kindex break @dots{} task @var{taskno}@r{ (Ada)} These commands are like the @code{break @dots{} thread @dots{}} command (@pxref{Thread Stops}). The -@var{linespec} argument specifies source lines, as described +@var{location} argument specifies source lines, as described in @ref{Specify Location}. Use the qualifier @samp{task @var{taskno}} with a breakpoint command @@ -16844,20 +17061,17 @@ an address of your own choosing, with the following commands: @table @code @kindex jump @kindex j @r{(@code{jump})} -@item jump @var{linespec} -@itemx j @var{linespec} -@itemx jump @var{location} +@item jump @var{location} @itemx j @var{location} -Resume execution at line @var{linespec} or at address given by -@var{location}. Execution stops again immediately if there is a -breakpoint there. @xref{Specify Location}, for a description of the -different forms of @var{linespec} and @var{location}. It is common +Resume execution at @var{location}. Execution stops again immediately +if there is a breakpoint there. @xref{Specify Location}, for a description +of the different forms of @var{location}. It is common practice to use the @code{tbreak} command in conjunction with @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. The @code{jump} command does not change the current stack frame, or the stack pointer, or the contents of any memory location or any -register other than the program counter. If line @var{linespec} is in +register other than the program counter. If @var{location} is in a different function from the one currently executing, the results may be bizarre if the two functions expect different patterns of arguments or of local variables. For this reason, the @code{jump} command requests @@ -17485,6 +17699,7 @@ program. To debug a core dump of a previous run, you must also tell @menu * Files:: Commands to specify files +* File Caching:: Information about @value{GDBN}'s file caching * Separate Debug Files:: Debugging information in separate files * MiniDebugInfo:: Debugging information in a special section * Index Files:: Index files speed up GDB @@ -18135,6 +18350,46 @@ Set whether a source file may have multiple base names. Show whether a source file may have multiple base names. @end table +@node File Caching +@section File Caching +@cindex caching of opened files +@cindex caching of bfd objects + +To speed up file loading, and reduce memory usage, @value{GDBN} will +reuse the @code{bfd} objects used to track open files. @xref{Top, , +BFD, bfd, The Binary File Descriptor Library}. The following commands +allow visibility and control of the caching behavior. + +@table @code +@kindex maint info bfds +@item maint info bfds +This prints information about each @code{bfd} object that is known to +@value{GDBN}. + +@kindex maint set bfd-sharing +@kindex maint show bfd-sharing +@kindex bfd caching +@item maint set bfd-sharing +@item maint show bfd-sharing +Control whether @code{bfd} objects can be shared. When sharing is +enabled @value{GDBN} reuses already open @code{bfd} objects rather +than reopening the same file. Turning sharing off does not cause +already shared @code{bfd} objects to be unshared, but all future files +that are opened will create a new @code{bfd} object. Similarly, +re-enabling sharing does not cause multiple existing @code{bfd} +objects to be collapsed into a single shared @code{bfd} object. + +@kindex set debug bfd-cache @var{level} +@kindex bfd caching +@item set debug bfd-cache @var{level} +Turns on debugging of the bfd cache, setting the level to @var{level}. + +@kindex show debug bfd-cache +@kindex bfd caching +@item show debug bfd-cache +Show the current debugging level of the bfd cache. +@end table + @node Separate Debug Files @section Debugging Information in Separate Files @cindex separate debugging information files @@ -18170,7 +18425,7 @@ the executable and the debug file came from the same build. @item The executable contains a @dfn{build ID}, a unique bit string that is also present in the corresponding debug info file. (This is supported -only on some operating systems, notably those which use the ELF format +only on some operating systems, when using the ELF or PE file formats for binary files and the @sc{gnu} Binutils.) For more details about this feature, see the description of the @option{--build-id} command-line option in @ref{Options, , Command Line Options, ld.info, @@ -19916,6 +20171,10 @@ are: @tab @code{vFile:fstat} @tab Host I/O +@item @code{hostio-setfs-packet} +@tab @code{vFile:setfs} +@tab Host I/O + @item @code{noack-packet} @tab @code{QStartNoAckMode} @tab Packet acknowledgment @@ -19952,6 +20211,10 @@ are: @tab @code{Z0 and Z1} @tab @code{Support for target-side breakpoint condition evaluation} +@item @code{multiprocess-extensions} +@tab @code{multiprocess extensions} +@tab Debug multiple processes and remote process PID awareness + @item @code{swbreak-feature} @tab @code{swbreak stop reason} @tab @code{break} @@ -19968,6 +20231,18 @@ are: @tab @code{vfork stop reason} @tab @code{vfork} +@item @code{exec-event-feature} +@tab @code{exec stop reason} +@tab @code{exec} + +@item @code{thread-events} +@tab @code{QThreadEvents} +@tab Tracking thread lifetime. + +@item @code{no-resumed-stop-reply} +@tab @code{no resumed thread left stop reply} +@tab Tracking thread lifetime. + @end multitable @node Remote Stub @@ -21173,16 +21448,12 @@ acceptable commands. @menu -* ARM:: ARM RDI -* M32R/D:: Renesas M32R/D +* ARM:: ARM +* M32R/SDI:: Renesas M32R/SDI * M68K:: Motorola M68K * MicroBlaze:: Xilinx MicroBlaze * MIPS Embedded:: MIPS Embedded * PowerPC Embedded:: PowerPC Embedded -* PA:: HP PA Embedded -* Sparclet:: Tsqware Sparclet -* Sparclite:: Fujitsu Sparclite -* Z8000:: Zilog Z8000 * AVR:: Atmel AVR * CRIS:: CRIS * Super-H:: Renesas Super-H @@ -21190,20 +21461,6 @@ acceptable commands. @node ARM @subsection ARM -@cindex ARM RDI - -@table @code -@kindex target rdi -@item target rdi @var{dev} -ARM Angel monitor, via RDI library interface to ADP protocol. You may -use this target to communicate with both boards running the Angel -monitor, or with the EmbeddedICE JTAG debug device. - -@kindex target rdp -@item target rdp @var{dev} -ARM Demon monitor. - -@end table @value{GDBN} provides the following ARM-specific commands: @@ -21279,50 +21536,6 @@ target support subsystem. Show whether ARM-specific debugging messages are enabled. @end table -The following commands are available when an ARM target is debugged -using the RDI interface: - -@table @code -@item rdilogfile @r{[}@var{file}@r{]} -@kindex rdilogfile -@cindex ADP (Angel Debugger Protocol) logging -Set the filename for the ADP (Angel Debugger Protocol) packet log. -With an argument, sets the log file to the specified @var{file}. With -no argument, show the current log file name. The default log file is -@file{rdi.log}. - -@item rdilogenable @r{[}@var{arg}@r{]} -@kindex rdilogenable -Control logging of ADP packets. With an argument of 1 or @code{"yes"} -enables logging, with an argument 0 or @code{"no"} disables it. With -no arguments displays the current setting. When logging is enabled, -ADP packets exchanged between @value{GDBN} and the RDI target device -are logged to a file. - -@item set rdiromatzero -@kindex set rdiromatzero -@cindex ROM at zero address, RDI -Tell @value{GDBN} whether the target has ROM at address 0. If on, -vector catching is disabled, so that zero address can be used. If off -(the default), vector catching is enabled. For this command to take -effect, it needs to be invoked prior to the @code{target rdi} command. - -@item show rdiromatzero -@kindex show rdiromatzero -Show the current setting of ROM at zero address. - -@item set rdiheartbeat -@kindex set rdiheartbeat -@cindex RDI heartbeat -Enable or disable RDI heartbeat packets. It is not recommended to -turn on this option, since it confuses ARM and EPI JTAG interface, as -well as the Angel monitor. - -@item show rdiheartbeat -@kindex show rdiheartbeat -Show the setting of RDI heartbeat packets. -@end table - @table @code @item target sim @r{[}@var{simargs}@r{]} @dots{} The @value{GDBN} ARM simulator accepts the following optional arguments. @@ -21343,60 +21556,8 @@ The default value is @code{all}. @end table @end table -@node M32R/D -@subsection Renesas M32R/D and M32R/SDI - -@table @code -@kindex target m32r -@item target m32r @var{dev} -Renesas M32R/D ROM monitor. - -@kindex target m32rsdi -@item target m32rsdi @var{dev} -Renesas M32R SDI server, connected via parallel port to the board. -@end table - -The following @value{GDBN} commands are specific to the M32R monitor: - -@table @code -@item set download-path @var{path} -@kindex set download-path -@cindex find downloadable @sc{srec} files (M32R) -Set the default path for finding downloadable @sc{srec} files. - -@item show download-path -@kindex show download-path -Show the default path for downloadable @sc{srec} files. - -@item set board-address @var{addr} -@kindex set board-address -@cindex M32-EVA target board address -Set the IP address for the M32R-EVA target board. - -@item show board-address -@kindex show board-address -Show the current IP address of the target board. - -@item set server-address @var{addr} -@kindex set server-address -@cindex download server address (M32R) -Set the IP address for the download server, which is the @value{GDBN}'s -host machine. - -@item show server-address -@kindex show server-address -Display the IP address of the download server. - -@item upload @r{[}@var{file}@r{]} -@kindex upload@r{, M32R} -Upload the specified @sc{srec} @var{file} via the monitor's Ethernet -upload capability. If no @var{file} argument is given, the current -executable file is uploaded. - -@item tload @r{[}@var{file}@r{]} -@kindex tload@r{, M32R} -Test the @code{upload} command. -@end table +@node M32R/SDI +@subsection Renesas M32R/SDI The following commands are available for M32R/SDI: @@ -21435,16 +21596,7 @@ Instructs the remote to set breakpoints by DBT. @node M68K @subsection M68k -The Motorola m68k configuration includes ColdFire support, and a -target command for the following ROM monitor. - -@table @code - -@kindex target dbug -@item target dbug @var{dev} -dBUG ROM monitor for Motorola ColdFire. - -@end table +The Motorola m68k configuration includes ColdFire support. @node MicroBlaze @subsection MicroBlaze @@ -21535,14 +21687,6 @@ NEC's DDB variant of PMON for Vr4300. @kindex target lsi @var{port} LSI variant of PMON. -@kindex target r3900 -@item target r3900 @var{dev} -Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. - -@kindex target array -@item target array @var{dev} -Array Tech LSI33K RAID controller board. - @end table @@ -21729,270 +21873,8 @@ Allow @value{GDBN} to use only one debug register when watching a variable of scalar type, thus assuming that the variable is accessed through the address of its first byte. -@kindex target dink32 -@item target dink32 @var{dev} -DINK32 ROM monitor. - -@kindex target ppcbug -@item target ppcbug @var{dev} -@kindex target ppcbug1 -@item target ppcbug1 @var{dev} -PPCBUG ROM monitor for PowerPC. - -@kindex target sds -@item target sds @var{dev} -SDS monitor, running on a PowerPC board (such as Motorola's ADS). -@end table - -@cindex SDS protocol -The following commands specific to the SDS protocol are supported -by @value{GDBN}: - -@table @code -@item set sdstimeout @var{nsec} -@kindex set sdstimeout -Set the timeout for SDS protocol reads to be @var{nsec} seconds. The -default is 2 seconds. - -@item show sdstimeout -@kindex show sdstimeout -Show the current value of the SDS timeout. - -@item sds @var{command} -@kindex sds@r{, a command} -Send the specified @var{command} string to the SDS monitor. -@end table - - -@node PA -@subsection HP PA Embedded - -@table @code - -@kindex target op50n -@item target op50n @var{dev} -OP50N monitor, running on an OKI HPPA board. - -@kindex target w89k -@item target w89k @var{dev} -W89K monitor, running on a Winbond HPPA board. - @end table -@node Sparclet -@subsection Tsqware Sparclet - -@cindex Sparclet - -@value{GDBN} enables developers to debug tasks running on -Sparclet targets from a Unix host. -@value{GDBN} uses code that runs on -both the Unix host and on the Sparclet target. The program -@code{@value{GDBP}} is installed and executed on the Unix host. - -@table @code -@item remotetimeout @var{args} -@kindex remotetimeout -@value{GDBN} supports the option @code{remotetimeout}. -This option is set by the user, and @var{args} represents the number of -seconds @value{GDBN} waits for responses. -@end table - -@cindex compiling, on Sparclet -When compiling for debugging, include the options @samp{-g} to get debug -information and @samp{-Ttext} to relocate the program to where you wish to -load it on the target. You may also want to add the options @samp{-n} or -@samp{-N} in order to reduce the size of the sections. Example: - -@smallexample -sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N -@end smallexample - -You can use @code{objdump} to verify that the addresses are what you intended: - -@smallexample -sparclet-aout-objdump --headers --syms prog -@end smallexample - -@cindex running, on Sparclet -Once you have set -your Unix execution search path to find @value{GDBN}, you are ready to -run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} -(or @code{sparclet-aout-gdb}, depending on your installation). - -@value{GDBN} comes up showing the prompt: - -@smallexample -(gdbslet) -@end smallexample - -@menu -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging -@end menu - -@node Sparclet File -@subsubsection Setting File to Debug - -The @value{GDBN} command @code{file} lets you choose with program to debug. - -@smallexample -(gdbslet) file prog -@end smallexample - -@need 1000 -@value{GDBN} then attempts to read the symbol table of @file{prog}. -@value{GDBN} locates -the file by searching the directories listed in the command search -path. -If the file was compiled with debug information (option @samp{-g}), source -files will be searched as well. -@value{GDBN} locates -the source files by searching the directories listed in the directory search -path (@pxref{Environment, ,Your Program's Environment}). -If it fails -to find a file, it displays a message such as: - -@smallexample -prog: No such file or directory. -@end smallexample - -When this happens, add the appropriate directories to the search paths with -the @value{GDBN} commands @code{path} and @code{dir}, and execute the -@code{target} command again. - -@node Sparclet Connection -@subsubsection Connecting to Sparclet - -The @value{GDBN} command @code{target} lets you connect to a Sparclet target. -To connect to a target on serial port ``@code{ttya}'', type: - -@smallexample -(gdbslet) target sparclet /dev/ttya -Remote target sparclet connected to /dev/ttya -main () at ../prog.c:3 -@end smallexample - -@need 750 -@value{GDBN} displays messages like these: - -@smallexample -Connected to ttya. -@end smallexample - -@node Sparclet Download -@subsubsection Sparclet Download - -@cindex download to Sparclet -Once connected to the Sparclet target, -you can use the @value{GDBN} -@code{load} command to download the file from the host to the target. -The file name and load offset should be given as arguments to the @code{load} -command. -Since the file format is aout, the program must be loaded to the starting -address. You can use @code{objdump} to find out what this value is. The load -offset is an offset which is added to the VMA (virtual memory address) -of each of the file's sections. -For instance, if the program -@file{prog} was linked to text address 0x1201000, with data at 0x12010160 -and bss at 0x12010170, in @value{GDBN}, type: - -@smallexample -(gdbslet) load prog 0x12010000 -Loading section .text, size 0xdb0 vma 0x12010000 -@end smallexample - -If the code is loaded at a different address then what the program was linked -to, you may need to use the @code{section} and @code{add-symbol-file} commands -to tell @value{GDBN} where to map the symbol table. - -@node Sparclet Execution -@subsubsection Running and Debugging - -@cindex running and debugging Sparclet programs -You can now begin debugging the task using @value{GDBN}'s execution control -commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} -manual for the list of commands. - -@smallexample -(gdbslet) b main -Breakpoint 1 at 0x12010000: file prog.c, line 3. -(gdbslet) run -Starting program: prog -Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 -3 char *symarg = 0; -(gdbslet) step -4 char *execarg = "hello!"; -(gdbslet) -@end smallexample - -@node Sparclite -@subsection Fujitsu Sparclite - -@table @code - -@kindex target sparclite -@item target sparclite @var{dev} -Fujitsu sparclite boards, used only for the purpose of loading. -You must use an additional command to debug the program. -For example: target remote @var{dev} using @value{GDBN} standard -remote protocol. - -@end table - -@node Z8000 -@subsection Zilog Z8000 - -@cindex Z8000 -@cindex simulator, Z8000 -@cindex Zilog Z8000 simulator - -When configured for debugging Zilog Z8000 targets, @value{GDBN} includes -a Z8000 simulator. - -For the Z8000 family, @samp{target sim} simulates either the Z8002 (the -unsegmented variant of the Z8000 architecture) or the Z8001 (the -segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. - -@table @code -@item target sim @var{args} -@kindex sim -@kindex target sim@r{, with Z8000} -Debug programs on a simulated CPU. If the simulator supports setup -options, specify them via @var{args}. -@end table - -@noindent -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -@code{file} command to load a new program image, the @code{run} command -to run your program, and so on. - -As well as making available all the usual machine registers -(@pxref{Registers, ,Registers}), the Z8000 simulator provides three -additional items of information as specially named registers: - -@table @code - -@item cycles -Counts clock-ticks in the simulator. - -@item insts -Counts instructions run in the simulator. - -@item time -Execution time in 60ths of a second. - -@end table - -You can refer to these values in @value{GDBN} expressions with the usual -conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a -conditional breakpoint that suspends only after at least 5000 -simulated clock ticks. - @node AVR @subsection Atmel AVR @cindex AVR @@ -22129,6 +22011,7 @@ Show the current setting of the convention to return @code{struct}s from functions. @end table + @subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX). @cindex Intel(R) Memory Protection Extensions (MPX). @@ -22162,6 +22045,25 @@ counterpart. When the bnd0@dots{}bnd3 registers are displayed via Python, the display includes the memory size, in bits, accessible to the pointer. +Bounds can also be stored in bounds tables, which are stored in +application memory. These tables store bounds for pointers by specifying +the bounds pointer's value along with its bounds. Evaluating and changing +bounds located in bound tables is therefore interesting while investigating +bugs on MPX context. @value{GDBN} provides commands for this purpose: + +@table @code +@item show mpx bound @var{pointer} +@kindex show mpx bound +Display bounds of the given @var{pointer}. + +@item set mpx bound @var{pointer}, @var{lbound}, @var{ubound} +@kindex set mpx bound +Set the bounds of a pointer in the bound table. +This command takes three parameters: @var{pointer} is the pointers +whose bounds are to be changed, @var{lbound} and @var{ubound} are new values +for lower and upper bounds respectively. +@end table + @node Alpha @subsection Alpha @@ -22599,14 +22501,30 @@ Stop recording command history in a file. @cindex history size @kindex set history size -@cindex @env{HISTSIZE}, environment variable +@cindex @env{GDBHISTSIZE}, environment variable @item set history size @var{size} @itemx set history size unlimited Set the number of commands which @value{GDBN} keeps in its history list. -This defaults to the value of the environment variable -@code{HISTSIZE}, or to 256 if this variable is not set. If @var{size} -is @code{unlimited}, the number of commands @value{GDBN} keeps in the -history list is unlimited. +This defaults to the value of the environment variable @env{GDBHISTSIZE}, or +to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE} +are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is +either a negative number or the empty string, then the number of commands +@value{GDBN} keeps in the history list is unlimited. + +@cindex remove duplicate history +@kindex set history remove-duplicates +@item set history remove-duplicates @var{count} +@itemx set history remove-duplicates unlimited +Control the removal of duplicate history entries in the command history list. +If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count} +history entries and remove the first entry that is a duplicate of the current +entry being added to the command history list. If @var{count} is +@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then +removal of duplicate history entries is disabled. + +Only history entries added during the current session are considered for +removal. This option is set to 0 by default. + @end table History expansion assigns special meaning to the character @kbd{!}. @@ -23410,21 +23328,29 @@ exported symbols. The default is off. @item show debug coff-pe-read Displays the current state of displaying debugging messages related to reading of COFF/PE exported symbols. -@item set debug dwarf2-die -@cindex DWARF2 DIEs -Dump DWARF2 DIEs after they are read in. +@item set debug dwarf-die +@cindex DWARF DIEs +Dump DWARF DIEs after they are read in. The value is the number of nesting levels to print. A value of zero turns off the display. -@item show debug dwarf2-die -Show the current state of DWARF2 DIE debugging. -@item set debug dwarf2-read -@cindex DWARF2 Reading +@item show debug dwarf-die +Show the current state of DWARF DIE debugging. +@item set debug dwarf-line +@cindex DWARF Line Tables +Turns on or off display of debugging messages related to reading +DWARF line tables. The default is 0 (off). +A value of 1 provides basic information. +A value greater than 1 provides more verbose information. +@item show debug dwarf-line +Show the current state of DWARF line table debugging. +@item set debug dwarf-read +@cindex DWARF Reading Turns on or off display of debugging messages related to reading DWARF debug info. The default is 0 (off). A value of 1 provides basic information. A value greater than 1 provides more verbose information. -@item show debug dwarf2-read -Show the current state of DWARF2 reader debugging. +@item show debug dwarf-read +Show the current state of DWARF reader debugging. @item set debug displaced @cindex displaced stepping debugging info Turns on or off display of @value{GDBN} debugging info for the @@ -23476,6 +23402,11 @@ Displays the current state of @value{GDBN} JIT debugging. Turns on or off debugging messages from the Linux LWP debug support. @item show debug lin-lwp Show the current state of Linux LWP debugging messages. +@item set debug linux-namespaces +@cindex @sc{gnu}/Linux namespaces debug messages +Turns on or off debugging messages from the Linux namespaces debug support. +@item show debug linux-namespaces +Show the current state of Linux namespaces debugging messages. @item set debug mach-o @cindex Mach-O symbols processing Control display of debugging messages related to Mach-O symbols @@ -24670,7 +24601,7 @@ The TUI mode is enabled by default when you invoke @value{GDBN} as @samp{@value{GDBP} -tui}. You can also switch in and out of TUI mode while @value{GDBN} runs by using various TUI commands and key bindings, such as @command{tui -enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands} and +enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and @ref{TUI Keys, ,TUI Key Bindings}. @node TUI Overview @@ -24959,69 +24890,91 @@ Disable TUI mode, returning to the console interpreter. @kindex info win List and give the size of all displayed windows. -@item layout next +@item layout @var{name} @kindex layout +Changes which TUI windows are displayed. In each layout the command +window is always displayed, the @var{name} parameter controls which +additional windows are displayed, and can be any of the following: + +@table @code +@item next Display the next layout. -@item layout prev +@item prev Display the previous layout. -@item layout src -Display the source window only. +@item src +Display the source and command windows. -@item layout asm -Display the assembly window only. +@item asm +Display the assembly and command windows. -@item layout split -Display the source and assembly window. +@item split +Display the source, assembly, and command windows. -@item layout regs -Display the register window together with the source or assembly window. +@item regs +When in @code{src} layout display the register, source, and command +windows. When in @code{asm} or @code{split} layout display the +register, assembler, and command windows. +@end table -@item focus next +@item focus @var{name} @kindex focus +Changes which TUI window is currently active for scrolling. The +@var{name} parameter can be any of the following: + +@table @code +@item next Make the next window active for scrolling. -@item focus prev +@item prev Make the previous window active for scrolling. -@item focus src +@item src Make the source window active for scrolling. -@item focus asm +@item asm Make the assembly window active for scrolling. -@item focus regs +@item regs Make the register window active for scrolling. -@item focus cmd +@item cmd Make the command window active for scrolling. +@end table @item refresh @kindex refresh Refresh the screen. This is similar to typing @kbd{C-L}. -@item tui reg float +@item tui reg @var{group} @kindex tui reg -Show the floating point registers in the register window. - -@item tui reg general -Show the general registers in the register window. - -@item tui reg next -Show the next register group. The list of register groups as well as -their order is target specific. The predefined register groups are the -following: @code{general}, @code{float}, @code{system}, @code{vector}, -@code{all}, @code{save}, @code{restore}. - -@item tui reg prev -Show the previous register group. The list of register groups as well -as their order is target specific. The predefined register groups are -the following: @code{general}, @code{float}, @code{system}, -@code{vector}, @code{all}, @code{save}, @code{restore}. - -@item tui reg system -Show the system registers in the register window. +Changes the register group displayed in the tui register window to +@var{group}. If the register window is not currently displayed this +command will cause the register window to be displayed. The list of +register groups, as well as their order is target specific. The +following groups are available on most targets: +@table @code +@item next +Repeatedly selecting this group will cause the display to cycle +through all of the available register groups. + +@item prev +Repeatedly selecting this group will cause the display to cycle +through all of the available register groups in the reverse order to +@var{next}. + +@item general +Display the general registers. +@item float +Display the floating point registers. +@item system +Display the system registers. +@item vector +Display the vector registers. +@item all +Display all registers. +@end table @item update @kindex update @@ -26721,6 +26674,7 @@ N.A. @subheading The @code{-break-insert} Command @findex -break-insert +@anchor{-break-insert} @subsubheading Synopsis @@ -26733,16 +26687,35 @@ N.A. @noindent If specified, @var{location}, can be one of: -@itemize @bullet -@item function -@c @item +offset -@c @item -offset -@c @item linenum -@item filename:linenum -@item filename:function -@item *address -@end itemize +@table @var +@item linespec location +A linespec location. @xref{Linespec Locations}. + +@item explicit location +An explicit location. @sc{gdb/mi} explicit locations are +analogous to the CLI's explicit locations using the option names +listed below. @xref{Explicit Locations}. + +@table @samp +@item --source @var{filename} +The source file name of the location. This option requires the use +of either @samp{--function} or @samp{--line}. + +@item --function @var{function} +The name of a function or method. +@item --label @var{label} +The name of a label. + +@item --line @var{lineoffset} +An absolute or relative line offset from the start of the location. +@end table + +@item address location +An address location, *@var{address}. @xref{Address Locations}. +@end table + +@noindent The possible optional parameters of this command are: @table @samp @@ -26834,17 +26807,8 @@ times="0"@}]@} @end smallexample @noindent -If specified, @var{location}, can be one of: - -@itemize @bullet -@item @var{function} -@c @item +offset -@c @item -offset -@c @item @var{linenum} -@item @var{filename}:@var{linenum} -@item @var{filename}:function -@item *@var{address} -@end itemize +If supplied, @var{location} may be specified the same way as for +the @code{-break-insert} command. @xref{-break-insert}. The possible optional parameters of this command are: @@ -29535,6 +29499,9 @@ can be used to instantiate this class for a varobj: This section describes the @sc{gdb/mi} commands that manipulate data: examine memory and registers, evaluate expressions, etc. +For details about what an addressable memory unit is, +@pxref{addressable memory unit}. + @c REMOVED FROM THE INTERFACE. @c @subheading -data-assign @c Change the value of a program variable. Plenty of side effects. @@ -29577,9 +29544,20 @@ displayed; if @var{lines} is higher than the number of lines between @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} are displayed. @item @var{mode} -is either 0 (meaning only disassembly), 1 (meaning mixed source and -disassembly), 2 (meaning disassembly with raw opcodes), or 3 (meaning -mixed source and disassembly with raw opcodes). +is one of: +@itemize @bullet +@item 0 disassembly only +@item 1 mixed source and disassembly (deprecated) +@item 2 disassembly with raw opcodes +@item 3 mixed source and disassembly with raw opcodes (deprecated) +@item 4 mixed source and disassembly +@item 5 mixed source and disassembly with raw opcodes +@end itemize + +Modes 1 and 3 are deprecated. The output is ``source centric'' +which hasn't proved useful in practice. +@xref{Machine Code}, for a discussion of the difference between +@code{/m} and @code{/s} output of the @code{disassemble} command. @end table @subsubheading Result @@ -29605,12 +29583,12 @@ The decimal offset in bytes from the start of @samp{func-name}. The text disassembly for this @samp{address}. @item opcodes -This field is only present for mode 2. This contains the raw opcode +This field is only present for modes 2, 3 and 5. This contains the raw opcode bytes for the @samp{inst} field. @end table -For modes 1 and 3 the @samp{asm_insns} list contains tuples named +For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named @samp{src_and_asm_line}, each of which has the following fields: @table @code @@ -30059,7 +30037,7 @@ next-page="0x000013c0",prev-page="0x00001380",memory=[ @subsubheading Synopsis @smallexample - -data-read-memory-bytes [ -o @var{byte-offset} ] + -data-read-memory-bytes [ -o @var{offset} ] @var{address} @var{count} @end smallexample @@ -30068,18 +30046,19 @@ 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 +An expression specifying the address of the first addressable memory unit +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. +The number of addressable memory units 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. +@item @var{offset} +The offset 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 @@ -30090,10 +30069,10 @@ 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 +In general, every single memory unit in the region may be readable or not, +and the only way to read every readable unit 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 +attempt to read all accessible memory units 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, @@ -30153,17 +30132,19 @@ where: @table @samp @item @var{address} -An expression specifying the address of the first memory word to be -written. Complex expressions containing embedded white space should be -quoted using the C convention. +An expression specifying the address of the first addressable memory unit +to be written. Complex expressions containing embedded white space should +be quoted using the C convention. @item @var{contents} -The hex-encoded bytes to write. +The hex-encoded data to write. It is an error if @var{contents} does +not represent an integral number of addressable memory units. @item @var{count} -Optional argument indicating the number of bytes to be written. If @var{count} -is greater than @var{contents}' length, @value{GDBN} will repeatedly -write @var{contents} until it fills @var{count} bytes. +Optional argument indicating the number of addressable memory units to be +written. If @var{count} is greater than @var{contents}' length, +@value{GDBN} will repeatedly write @var{contents} until it fills +@var{count} memory units. @end table @@ -33851,10 +33832,65 @@ Shared library events. @end table -@kindex maint info bfds -@item maint info bfds -This prints information about each @code{bfd} object that is known to -@value{GDBN}. @xref{Top, , BFD, bfd, The Binary File Descriptor Library}. +@kindex maint info btrace +@item maint info btrace +Pint information about raw branch tracing data. + +@kindex maint btrace packet-history +@item maint btrace packet-history +Print the raw branch trace packets that are used to compute the +execution history for the @samp{record btrace} command. Both the +information and the format in which it is printed depend on the btrace +recording format. + +@table @code +@item bts +For the BTS recording format, print a list of blocks of sequential +code. For each block, the following information is printed: + +@table @asis +@item Block number +Newer blocks have higher numbers. The oldest block has number zero. +@item Lowest @samp{PC} +@item Highest @samp{PC} +@end table + +@item pt +For the Intel(R) Processor Trace recording format, print a list of +Intel(R) Processor Trace packets. For each packet, the following +information is printed: + +@table @asis +@item Packet number +Newer packets have higher numbers. The oldest packet has number zero. +@item Trace offset +The packet's offset in the trace stream. +@item Packet opcode and payload +@end table +@end table + +@kindex maint btrace clear-packet-history +@item maint btrace clear-packet-history +Discards the cached packet history printed by the @samp{maint btrace +packet-history} command. The history will be computed again when +needed. + +@kindex maint btrace clear +@item maint btrace clear +Discard the branch trace data. The data will be fetched anew and the +branch trace will be recomputed when needed. + +This implicitly truncates the branch trace to a single branch trace +buffer. When updating branch trace incrementally, the branch trace +available to @value{GDBN} may be bigger than a single branch trace +buffer. + +@kindex maint set btrace pt skip-pad +@item maint set btrace pt skip-pad +@kindex maint show btrace pt skip-pad +@item maint show btrace pt skip-pad +Control whether @value{GDBN} will skip PAD packets when computing the +packet history. @kindex set displaced-stepping @kindex show displaced-stepping @@ -34154,10 +34190,10 @@ 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 +@kindex maint set dwarf always-disassemble +@kindex maint show dwarf always-disassemble +@item maint set dwarf always-disassemble +@item maint show dwarf always-disassemble Control the behavior of @code{info address} when using DWARF debugging information. @@ -34179,15 +34215,15 @@ Symbol "argc" is a complex DWARF expression: 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 -@itemx maint show dwarf2 max-cache-age -Control the DWARF 2 compilation unit cache. +@kindex maint set dwarf max-cache-age +@kindex maint show dwarf max-cache-age +@item maint set dwarf max-cache-age +@itemx maint show dwarf max-cache-age +Control the DWARF compilation unit cache. -@cindex DWARF 2 compilation units cache +@cindex DWARF compilation units cache In object files with inter-compilation-unit references, such as those -produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2 +produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF reader needs to frequently refer to previously read compilation units. This setting controls how long a compilation unit will remain in the cache if it is not referenced. A higher limit means that cached @@ -34241,6 +34277,30 @@ asynchronous mode (@pxref{Background Execution}). Normally the default is asynchronous, if it is available; but this can be changed to more easily debug problems occurring only in synchronous mode. +@kindex maint set target-non-stop @var{mode} [on|off|auto] +@kindex maint show target-non-stop +@item maint set target-non-stop +@itemx maint show target-non-stop + +This controls whether @value{GDBN} targets always operate in non-stop +mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop +Mode}). The default is @code{auto}, meaning non-stop mode is enabled +if supported by the target. + +@table @code +@item maint set target-non-stop auto +This is the default mode. @value{GDBN} controls the target in +non-stop mode if the target supports it. + +@item maint set target-non-stop on +@value{GDBN} controls the target in non-stop mode even if the target +does not indicate support. + +@item maint set target-non-stop off +@value{GDBN} does not control the target in non-stop mode even if the +target supports it. +@end table + @kindex maint set per-command @kindex maint show per-command @item maint set per-command @@ -34798,8 +34858,9 @@ probes the target state as if a new connection was opened @item m @var{addr},@var{length} @cindex @samp{m} packet -Read @var{length} bytes of memory starting at address @var{addr}. -Note that @var{addr} may not be aligned to any particular boundary. +Read @var{length} addressable memory units starting at address @var{addr} +(@pxref{addressable memory unit}). Note that @var{addr} may not be aligned to +any particular boundary. The stub need not use any particular size or alignment when gathering data from memory for the response; even if @var{addr} is word-aligned @@ -34813,8 +34874,8 @@ suitable for accessing memory-mapped I/O devices. Reply: @table @samp @item @var{XX@dots{}} -Memory contents; each byte is transmitted as a two-digit hexadecimal -number. The reply may contain fewer bytes than requested if the +Memory contents; each byte is transmitted as a two-digit hexadecimal number. +The reply may contain fewer addressable memory units than requested if the server was able to read only part of the region of memory. @item E @var{NN} @var{NN} is errno @@ -34822,9 +34883,9 @@ server was able to read only part of the region of memory. @item M @var{addr},@var{length}:@var{XX@dots{}} @cindex @samp{M} packet -Write @var{length} bytes of memory starting at address @var{addr}. -The data is given by @var{XX@dots{}}; each byte is transmitted as a two-digit -hexadecimal number. +Write @var{length} addressable memory units starting at address @var{addr} +(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each +byte is transmitted as a two-digit hexadecimal number. Reply: @table @samp @@ -35037,6 +35098,24 @@ command in the @samp{vCont} packet. The @samp{vCont} packet is not supported. @end table +@anchor{vCtrlC packet} +@item vCtrlC +@cindex @samp{vCtrlC} packet +Interrupt remote target as if a control-C was pressed on the remote +terminal. This is the equivalent to reacting to the @code{^C} +(@samp{\003}, the control-C character) character in all-stop mode +while the target is running, except this works in non-stop mode. +@xref{interrupting remote targets}, for more info on the all-stop +variant. + +Reply: +@table @samp +@item E @var{nn} +for an error +@item OK +for success +@end table + @item vFile:@var{operation}:@var{parameter}@dots{} @cindex @samp{vFile} packet Perform a file operation on the target system. For details, @@ -35138,7 +35217,8 @@ for success (@pxref{Stop Reply Packets}) @anchor{X packet} @cindex @samp{X} packet Write data to memory, where the data is transmitted in binary. -Memory is specified by its address @var{addr} and number of bytes @var{length}; +Memory is specified by its address @var{addr} and number of addressable memory +units @var{length} (@pxref{addressable memory unit}); @samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). Reply: @@ -35462,6 +35542,27 @@ appropriate @samp{qSupported} feature (@pxref{qSupported}). The remote stub must also supply the appropriate @samp{qSupported} feature indicating support. +@cindex exec events, remote reply +@item exec +The packet indicates that @code{execve} was called, and @var{r} +is the absolute pathname of the file that was executed, in hex. +This packet is only applicable to targets that support exec events. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +@cindex thread create event, remote reply +@anchor{thread create event} +@item create +The packet indicates that the thread was just created. The new thread +is stopped until @value{GDBN} sets it running with a resumption packet +(@pxref{vCont packet}). This packet should not be sent by default; +@value{GDBN} requests it with the @ref{QThreadEvents} packet. See +also the @samp{w} (@ref{thread exit event}) remote reply below. + @end table @item W @var{AA} @@ -35483,6 +35584,29 @@ terminated process, can be used only when @value{GDBN} has reported support for multiprocess protocol extensions; see @ref{multiprocess extensions}. The @var{pid} is formatted as a big-endian hex string. +@anchor{thread exit event} +@cindex thread exit event, remote reply +@item w @var{AA} ; @var{tid} + +The thread exited, and @var{AA} is the exit status. This response +should not be sent by default; @value{GDBN} requests it with the +@ref{QThreadEvents} packet. See also @ref{thread create event} above. + +@item N +There are no resumed threads left in the target. In other words, even +though the process is alive, the last resumed thread has exited. For +example, say the target process has two threads: thread 1 and thread +2. The client leaves thread 1 stopped, and resumes thread 2, which +subsequently exits. At this point, even though the process is still +alive, and thus no @samp{W} stop reply is sent, no thread is actually +executing either. The @samp{N} stop reply thus informs the client +that it can stop waiting for stop replies. This packet should not be +sent by default; older @value{GDBN} versions did not support it. +@value{GDBN} requests it, by supplying an appropriate +@samp{qSupported} feature (@pxref{qSupported}). The remote stub must +also supply the appropriate @samp{qSupported} feature indicating +support. + @item O @var{XX}@dots{} @samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be written as the program's console output. This can happen at any time @@ -35900,6 +36024,39 @@ command (@pxref{Remote Configuration, set remote program-signals}). This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@anchor{QThreadEvents} +@item QThreadEvents:1 +@itemx QThreadEvents:0 +@cindex thread create/exit events, remote request +@cindex @samp{QThreadEvents} packet + +Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0}) +reporting of thread create and exit events. @xref{thread create +event}, for the reply specifications. For example, this is used in +non-stop mode when @value{GDBN} stops a set of threads and +synchronously waits for the their corresponding stop replies. Without +exit events, if one of the threads exits, @value{GDBN} would hang +forever not knowing that it should no longer expect a stop for that +same thread. @value{GDBN} does not enable this feature unless the +stub reports that it supports it by including @samp{QThreadEvents+} in +its @samp{qSupported} reply. + +Reply: +@table @samp +@item OK +The request succeeded. + +@item E @var{nn} +An error occurred. The error number @var{nn} is given as hex digits. + +@item @w{} +An empty reply indicates that @samp{QThreadEvents} is not supported by +the stub. +@end table + +Use of this packet is controlled by the @code{set remote thread-events} +command (@pxref{Remote Configuration, set remote thread-events}). + @item qRcmd,@var{command} @cindex execute remote command, remote request @cindex @samp{qRcmd} packet @@ -36066,6 +36223,16 @@ This feature indicates whether @value{GDBN} supports vfork event extensions to the remote protocol. @value{GDBN} does not use such extensions unless the stub also reports that it supports them by including @samp{vfork-events+} in its @samp{qSupported} reply. + +@item exec-events +This feature indicates whether @value{GDBN} supports exec event +extensions to the remote protocol. @value{GDBN} does not use such +extensions unless the stub also reports that it supports them by +including @samp{exec-events+} in its @samp{qSupported} reply. + +@item vContSupported +This feature indicates whether @value{GDBN} wants to know the +supported actions in the reply to @samp{vCont?} packet. @end table Stubs should ignore any unknown values for @@ -36214,11 +36381,21 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab Yes +@item @samp{Qbtrace:pt} +@tab Yes +@tab @samp{-} +@tab Yes + @item @samp{Qbtrace-conf:bts:size} @tab Yes @tab @samp{-} @tab Yes +@item @samp{Qbtrace-conf:pt:size} +@tab Yes +@tab @samp{-} +@tab Yes + @item @samp{QNonStop} @tab No @tab @samp{-} @@ -36319,6 +36496,21 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{exec-events} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QThreadEvents} +@tab No +@tab @samp{-} +@tab No + +@item @samp{no-resumed} +@tab No +@tab @samp{-} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -36500,9 +36692,15 @@ The remote stub understands the @samp{Qbtrace:off} packet. @item Qbtrace:bts The remote stub understands the @samp{Qbtrace:bts} packet. +@item Qbtrace:pt +The remote stub understands the @samp{Qbtrace:pt} packet. + @item Qbtrace-conf:bts:size The remote stub understands the @samp{Qbtrace-conf:bts:size} packet. +@item Qbtrace-conf:pt:size +The remote stub understands the @samp{Qbtrace-conf:pt:size} packet. + @item swbreak The remote stub reports the @samp{swbreak} stop reason for memory breakpoints. @@ -36518,6 +36716,19 @@ The remote stub reports the @samp{fork} stop reason for fork events. The remote stub reports the @samp{vfork} stop reason for vfork events and vforkdone events. +@item exec-events +The remote stub reports the @samp{exec} stop reason for exec events. + +@item vContSupported +The remote stub reports the supported actions in the reply to +@samp{vCont?} packet. + +@item QThreadEvents +The remote stub understands the @samp{QThreadEvents} packet. + +@item no-resumed +The remote stub reports the @samp{N} stop reply. + @end table @item qSymbol:: @@ -36947,7 +37158,18 @@ A badly formed request or an error was encountered. @end table @item Qbtrace:bts -Enable branch tracing for the current thread using bts tracing. +Enable branch tracing for the current thread using Branch Trace Store. + +Reply: +@table @samp +@item OK +Branch tracing has been enabled. +@item E.errtext +A badly formed request or an error was encountered. +@end table + +@item Qbtrace:pt +Enable branch tracing for the current thread using Intel(R) Processor Trace. Reply: @table @samp @@ -36980,6 +37202,18 @@ The ring buffer size has been set. A badly formed request or an error was encountered. @end table +@item Qbtrace-conf:pt:size=@var{value} +Set the requested ring buffer size for new threads that use the +btrace recording method in pt format. + +Reply: +@table @samp +@item OK +The ring buffer size has been set. +@item E.errtext +A badly formed request or an error was encountered. +@end table + @end table @node Architecture-Specific Protocol Details @@ -37711,16 +37945,31 @@ attachment (i.e.@: a trailing semicolon). The return value is the number of target bytes read; the binary attachment may be longer if some characters were escaped. +@item vFile:setfs: @var{pid} +Select the filesystem on which @code{vFile} operations with +@var{filename} arguments will operate. This is required for +@value{GDBN} to be able to access files on remote targets where +the remote stub does not share a common filesystem with the +inferior(s). + +If @var{pid} is nonzero, select the filesystem as seen by process +@var{pid}. If @var{pid} is zero, select the filesystem as seen by +the remote stub. Return 0 on success, or -1 if an error occurs. +If @code{vFile:setfs:} indicates success, the selected filesystem +remains selected until the next successful @code{vFile:setfs:} +operation. + @end table @node Interrupts @section Interrupts @cindex interrupts (remote protocol) +@anchor{interrupting remote targets} -When a program on the remote target is running, @value{GDBN} may -attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or -a @code{BREAK} followed by @code{g}, -control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}. +In all-stop mode, when a program on the remote target is running, +@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C}, +@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which +is specified via @value{GDBN}'s @samp{interrupt-sequence}. The precise meaning of @code{BREAK} is defined by the transport mechanism and may, in fact, be undefined. @value{GDBN} does not @@ -37741,6 +37990,13 @@ and does @emph{not} represent an interrupt. E.g., an @samp{X} packet When Linux kernel receives this sequence from serial port, it stops execution and connects to gdb. +In non-stop mode, because packet resumptions are asynchronous +(@pxref{vCont packet}), @value{GDBN} is always free to send a remote +command to the remote stub, even when the target is running. For that +reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC +packet}) with the usual packet framing instead of the single byte +@code{0x03}. + Stubs are not required to recognize these interrupt mechanisms and the precise meaning associated with receipt of the interrupt is implementation defined. If the target supports debugging of multiple @@ -39401,7 +39657,7 @@ the following structure: @smallexample - + ... description ... @@ -39410,8 +39666,10 @@ the following structure: Each @samp{thread} element must have the @samp{id} attribute that identifies the thread (@pxref{thread-id syntax}). The @samp{core} attribute, if present, specifies which processor core -the thread was last executing on. The content of the of @samp{thread} -element is interpreted as human-readable auxilliary information. +the thread was last executing on. The @samp{name} attribute, if +present, specifies the human-readable name of the thread. The content +of the of @samp{thread} element is interpreted as human-readable +auxiliary information. @node Traceframe Info Format @section Traceframe Info Format @@ -39517,12 +39775,24 @@ and ending at @var{end}: The formal DTD for the branch trace format is given below: @smallexample - + + + + + + + + + + @end smallexample @node Branch Trace Configuration Format @@ -39543,6 +39813,13 @@ This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format. @item size The size of the @acronym{BTS} ring buffer in bytes. @end table +@item pt +This thread uses the @dfn{Intel(R) Processor Trace} (@acronym{Intel(R) +PT}) format. +@table @code +@item size +The size of the @acronym{Intel(R) PT} ring buffer in bytes. +@end table @end table @value{GDBN} must be linked with the Expat library to support XML @@ -39551,11 +39828,14 @@ branch trace configuration discovery. @xref{Expat}. The formal DTD for the branch trace configuration format is given below: @smallexample - + + + + @end smallexample @include agentexpr.texi