X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=795a70b21038ad8451a4d4606d6b4418b651c9d0;hb=cb814510676f7f6c08b329af2f57006fa598b619;hp=4bb092c13c3a8d132af241ec44201f0dec6a6bcb;hpb=7a6a173129107538574949116c0ce1c0ead589b4;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 4bb092c13c..795a70b210 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@c Copyright (C) 1988-2015 Free Software Foundation, Inc. +@c Copyright (C) 1988-2016 Free Software Foundation, Inc. @c @c %**start of header @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use @@ -50,7 +50,7 @@ @copying @c man begin COPYRIGHT -Copyright @copyright{} 1988-2015 Free Software Foundation, Inc. +Copyright @copyright{} 1988-2016 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -120,7 +120,7 @@ This is the @value{EDITION} Edition, for @value{GDBN} @end ifset Version @value{GDBVN}. -Copyright (C) 1988-2015 Free Software Foundation, Inc. +Copyright (C) 1988-2016 Free Software Foundation, Inc. This edition of the GDB manual is dedicated to the memory of Fred Fish. Fred was a long-standing contributor to GDB and to Free @@ -2658,6 +2658,12 @@ Make inferior number @var{infno} the current inferior. The argument in the first field of the @samp{info inferiors} display. @end table +@vindex $_inferior@r{, convenience variable} +The debugger convenience variable @samp{$_inferior} contains the +number of the current inferior. You may find this useful in writing +breakpoint conditional expressions, command scripts, and so forth. +@xref{Convenience Vars,, Convenience Variables}, for general +information on convenience variables. You can get multiple executables into a debugging session via the @code{add-inferior} and @w{@code{clone-inferior}} commands. On some @@ -2791,9 +2797,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}, @@ -2819,7 +2825,7 @@ space as a result of inferior 1 having executed a @code{vfork} call. @cindex threads of execution @cindex multiple threads @cindex switching threads -In some operating systems, such as HP-UX and Solaris, a single program +In some operating systems, such as GNU/Linux and Solaris, a single program may have more than one @dfn{thread} of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes---except @@ -2832,9 +2838,9 @@ programs: @itemize @bullet @item automatic notification of new threads -@item @samp{thread @var{threadno}}, a command to switch among threads +@item @samp{thread @var{thread-id}}, a command to switch among threads @item @samp{info threads}, a command to inquire about existing threads -@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, +@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}}, a command to apply a command to a list of threads @item thread-specific breakpoints @item @samp{set print thread-events}, which controls printing of @@ -2844,24 +2850,6 @@ the user specify which @code{libthread_db} to use if the default choice isn't compatible with the program. @end itemize -@quotation -@emph{Warning:} These facilities are not yet available on every -@value{GDBN} configuration where the operating system supports threads. -If your @value{GDBN} does not support threads, these commands have no -effect. For example, a system without thread support shows no output -from @samp{info threads}, and always rejects the @code{thread} command, -like this: - -@smallexample -(@value{GDBP}) info threads -(@value{GDBP}) thread 1 -Thread ID 1 not known. Use the "info threads" command to -see the IDs of currently known threads. -@end smallexample -@c FIXME to implementors: how hard would it be to say "sorry, this GDB -@c doesn't support threads"? -@end quotation - @cindex focus of debugging @cindex current thread The @value{GDBN} thread debugging facility allows you to observe all @@ -2886,7 +2874,7 @@ whose form varies depending on the particular system. For example, on @end smallexample @noindent -when @value{GDBN} notices a new thread. In contrast, on an SGI system, +when @value{GDBN} notices a new thread. In contrast, on other systems, the @var{systag} is simply something like @samp{process 368}, with no further qualifier. @@ -2898,22 +2886,116 @@ further qualifier. @c multithread systems permit starting a program with multiple @c threads ab initio? -@cindex thread number +@anchor{thread numbers} +@cindex thread number, per inferior @cindex thread identifier (GDB) -For debugging purposes, @value{GDBN} associates its own thread -number---always a single integer---with each thread in your program. +For debugging purposes, @value{GDBN} associates its own thread number +---always a single integer---with each thread of an inferior. This +number is unique between all threads of an inferior, but not unique +between threads of different inferiors. + +@cindex qualified thread ID +You can refer to a given thread in an inferior using the qualified +@var{inferior-num}.@var{thread-num} syntax, also known as +@dfn{qualified thread ID}, with @var{inferior-num} being the inferior +number and @var{thread-num} being the thread number of the given +inferior. For example, thread @code{2.3} refers to thread number 3 of +inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}), +then @value{GDBN} infers you're referring to a thread of the current +inferior. + +Until you create a second inferior, @value{GDBN} does not show the +@var{inferior-num} part of thread IDs, even though you can always use +the full @var{inferior-num}.@var{thread-num} form to refer to threads +of inferior 1, the initial inferior. + +@anchor{thread ID lists} +@cindex thread ID lists +Some commands accept a space-separated @dfn{thread ID list} as +argument. A list element can be: + +@enumerate +@item +A thread ID as shown in the first field of the @samp{info threads} +display, with or without an inferior qualifier. E.g., @samp{2.1} or +@samp{1}. + +@item +A range of thread numbers, again with or without an inferior +qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or +@var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}. + +@item +All threads of an inferior, specified with a star wildcard, with or +without an inferior qualifier, as in @var{inf}.@code{*} (e.g., +@samp{1.*}) or @code{*}. The former refers to all threads of the +given inferior, and the latter form without an inferior qualifier +refers to all threads of the current inferior. + +@end enumerate + +For example, if the current inferior is 1, and inferior 7 has one +thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*} +includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads +7 to 9 of inferior 6 and all threads of inferior 7. That is, in +expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9 +7.1}. + + +@anchor{global thread numbers} +@cindex global thread number +@cindex global thread identifier (GDB) +In addition to a @emph{per-inferior} number, each thread is also +assigned a unique @emph{global} number, also known as @dfn{global +thread ID}, a single integer. Unlike the thread number component of +the thread ID, no two threads have the same global ID, even when +you're debugging multiple inferiors. + +From @value{GDBN}'s perspective, a process always has at least one +thread. In other words, @value{GDBN} assigns a thread number to the +program's ``main thread'' even if the program is not multi-threaded. + +@vindex $_thread@r{, convenience variable} +@vindex $_gthread@r{, convenience variable} +The debugger convenience variables @samp{$_thread} and +@samp{$_gthread} contain, respectively, the per-inferior thread number +and the global thread number of the current thread. You may find this +useful in writing breakpoint conditional expressions, command scripts, +and so forth. @xref{Convenience Vars,, Convenience Variables}, for +general information on convenience variables. + +If @value{GDBN} detects the program is multi-threaded, it augments the +usual message about stopping at a breakpoint with the ID and name of +the thread that hit the breakpoint. + +@smallexample +Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 +@end smallexample + +Likewise when the program receives a signal: + +@smallexample +Thread 1 "main" received signal SIGINT, Interrupt. +@end smallexample @table @code @kindex info threads -@item info threads @r{[}@var{id}@dots{}@r{]} -Display a summary of all threads currently in your program. Optional -argument @var{id}@dots{} is one or more thread ids separated by spaces, and -means to print information only about the specified thread or threads. +@item info threads @r{[}@var{thread-id-list}@r{]} + +Display information about one or more threads. With no arguments +displays information about all threads. You can specify the list of +threads that you want to display using the thread ID list syntax +(@pxref{thread ID lists}). + @value{GDBN} displays for each thread (in this order): @enumerate @item -the thread number assigned by @value{GDBN} +the per-inferior thread number assigned by @value{GDBN} + +@item +the global thread number assigned by @value{GDBN}, if the @samp{-gid} +option was specified @item the target system's thread identifier (@var{systag}) @@ -2938,12 +3020,28 @@ 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 +If you're debugging multiple inferiors, @value{GDBN} displays thread +IDs using the qualified @var{inferior-num}.@var{thread-num} format. +Otherwise, only @var{thread-num} is shown. + +If you specify the @samp{-gid} option, @value{GDBN} displays a column +indicating each thread's global thread ID: + +@smallexample +(@value{GDBP}) info threads + Id GId Target Id Frame + 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 1.2 3 process 35 thread 23 0x34e5 in sigpause () + 1.3 4 process 35 thread 27 0x34e5 in sigpause () +* 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) +@end smallexample + On Solaris, you can display more information about user threads with a Solaris-specific command: @@ -2955,13 +3053,15 @@ Display info on Solaris user threads. @end table @table @code -@kindex thread @var{threadno} -@item thread @var{threadno} -Make thread number @var{threadno} the current thread. The command -argument @var{threadno} is the internal @value{GDBN} thread number, as -shown in the first field of the @samp{info threads} display. -@value{GDBN} responds by displaying the system identifier of the thread -you selected, and its current stack frame summary: +@kindex thread @var{thread-id} +@item thread @var{thread-id} +Make thread ID @var{thread-id} the current thread. The command +argument @var{thread-id} is the @value{GDBN} thread ID, as shown in +the first field of the @samp{info threads} display, with or without an +inferior qualifier (e.g., @samp{2.1} or @samp{1}). + +@value{GDBN} responds by displaying the system identifier of the +thread you selected, and its current stack frame summary: @smallexample (@value{GDBP}) thread 2 @@ -2975,23 +3075,14 @@ As with the @samp{[New @dots{}]} message, the form of the text after @samp{Switching to} depends on your system's conventions for identifying threads. -@vindex $_thread@r{, convenience variable} -The debugger convenience variable @samp{$_thread} contains the number -of the current thread. You may find this useful in writing breakpoint -conditional expressions, command scripts, and so forth. See -@xref{Convenience Vars,, Convenience Variables}, for general -information on convenience variables. - @kindex thread apply @cindex apply command to several threads -@item thread apply [@var{threadno} | all [-ascending]] @var{command} +@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command} The @code{thread apply} command allows you to apply the named -@var{command} to one or more threads. Specify the numbers of the -threads that you want affected with the command argument -@var{threadno}. It can be a single thread number, one of the numbers -shown in the first field of the @samp{info threads} display; or it -could be a range of thread numbers, as in @code{2-4}. To apply -a command to all threads in descending order, type @kbd{thread apply all +@var{command} to one or more threads. Specify the threads that you +want affected using the thread ID list syntax (@pxref{thread ID +lists}), or specify @code{all} to apply to all threads. To apply a +command to all threads in descending order, type @kbd{thread apply all @var{command}}. To apply a command to all threads in ascending order, type @kbd{thread apply all -ascending @var{command}}. @@ -3130,13 +3221,14 @@ get its process ID. Then tell @value{GDBN} (a new invocation of the child process (@pxref{Attach}). From that point on you can debug the child process just like any other process which you attached to. -On some systems, @value{GDBN} provides support for debugging programs that -create additional processes using the @code{fork} or @code{vfork} functions. -Currently, the only platforms with this feature are HP-UX (11.x and later -only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later). +On some systems, @value{GDBN} provides support for debugging programs +that create additional processes using the @code{fork} or @code{vfork} +functions. On @sc{gnu}/Linux platforms, this feature is supported +with kernel version 2.5.46 and later. -The fork debugging commands are supported in both native mode and when -connected to @code{gdbserver} using @kbd{target extended-remote}. +The fork debugging commands are supported in native mode and when +connected to @code{gdbserver} in either @code{target remote} mode or +@code{target extended-remote} mode. By default, when a program forks, @value{GDBN} will continue to debug the parent process and the child process will run unimpeded. @@ -3254,8 +3346,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 @@ -3282,6 +3374,9 @@ Program exited normally. @end table @end table +@code{follow-exec-mode} is supported in native mode and +@code{target extended-remote} mode. + You can use the @code{catch} command to make @value{GDBN} stop whenever a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set Catchpoints, ,Setting Catchpoints}. @@ -3444,11 +3539,7 @@ should stop by line number, function name or exact address in the program. On some systems, you can set breakpoints in shared libraries before -the executable is run. There is a minor limitation on HP-UX systems: -you must wait until the executable is run in order to set breakpoints -in shared library routines that are not called directly by the program -(for example, routines that are arguments in a @code{pthread_create} -call). +the executable is run. @cindex watchpoints @cindex data breakpoints @@ -3985,13 +4076,13 @@ times slower than normal execution. (But this may still be worth it, to catch errors where you have no clue what part of your program is the culprit.) -On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other -x86-based targets, @value{GDBN} includes support for hardware -watchpoints, which do not slow down the running of your program. +On some systems, such as most PowerPC or x86-based targets, +@value{GDBN} includes support for hardware watchpoints, which do not +slow down the running of your program. @table @code @kindex watch -@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} +@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} Set a watchpoint for an expression. @value{GDBN} will break when the expression @var{expr} is written into by the program and its value changes. The simplest (and the most popular) use of this command is @@ -4001,9 +4092,9 @@ to watch the value of a single variable: (@value{GDBP}) watch foo @end smallexample -If the command includes a @code{@r{[}thread @var{threadnum}@r{]}} +If the command includes a @code{@r{[}thread @var{thread-id}@r{]}} argument, @value{GDBN} breaks only when the thread identified by -@var{threadnum} changes the value of @var{expr}. If any other threads +@var{thread-id} changes the value of @var{expr}. If any other threads change the value of @var{expr}, @value{GDBN} will not break. Note that watchpoints restricted to a single thread in this way only work with Hardware Watchpoints. @@ -4035,12 +4126,12 @@ Examples: @end smallexample @kindex rwatch -@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} +@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} Set a watchpoint that will break when the value of @var{expr} is read by the program. @kindex awatch -@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]} +@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} Set a watchpoint that will break when @var{expr} is either read from or written into by the program. @@ -4281,8 +4372,7 @@ A failed Ada assertion. @item exec @kindex catch exec @cindex break on fork/exec -A call to @code{exec}. This is currently only available for HP-UX -and @sc{gnu}/Linux. +A call to @code{exec}. @item syscall @itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} @@ -4418,13 +4508,11 @@ Again, in this case @value{GDBN} would not be able to display syscall's names. @item fork @kindex catch fork -A call to @code{fork}. This is currently only available for HP-UX -and @sc{gnu}/Linux. +A call to @code{fork}. @item vfork @kindex catch vfork -A call to @code{vfork}. This is currently only available for HP-UX -and @sc{gnu}/Linux. +A call to @code{vfork}. @item load @r{[}regexp@r{]} @itemx unload @r{[}regexp@r{]} @@ -5439,8 +5527,9 @@ default is @code{on}. @cindex skipping over functions and files The program you are debugging may contain some functions which are -uninteresting to debug. The @code{skip} comand lets you tell @value{GDBN} to -skip a function or all functions in a file when stepping. +uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to +skip a function, all functions in a file or a particular function in +a particular file when stepping. For example, consider the following C function: @@ -5467,13 +5556,75 @@ A more flexible solution is to execute @kbd{skip boring}. This instructs @code{step} at line 103, you'll step over @code{boring} and directly into @code{foo}. -You can also instruct @value{GDBN} to skip all functions in a file, with, for -example, @code{skip file boring.c}. +Functions may be skipped by providing either a function name, linespec +(@pxref{Specify Location}), regular expression that matches the function's +name, file name or a @code{glob}-style pattern that matches the file name. + +On Posix systems the form of the regular expression is +``Extended Regular Expressions''. See for example @samp{man 7 regex} +on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular +expression is whatever is provided by the @code{regcomp} function of +the underlying system. +See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a +description of @code{glob}-style patterns. + +@table @code +@kindex skip +@item skip @r{[}@var{options}@r{]} +The basic form of the @code{skip} command takes zero or more options +that specify what to skip. +The @var{options} argument is any useful combination of the following: @table @code +@item -file @var{file} +@itemx -fi @var{file} +Functions in @var{file} will be skipped over when stepping. + +@item -gfile @var{file-glob-pattern} +@itemx -gfi @var{file-glob-pattern} +@cindex skipping over files via glob-style patterns +Functions in files matching @var{file-glob-pattern} will be skipped +over when stepping. + +@smallexample +(gdb) skip -gfi utils/*.c +@end smallexample + +@item -function @var{linespec} +@itemx -fu @var{linespec} +Functions named by @var{linespec} or the function containing the line +named by @var{linespec} will be skipped over when stepping. +@xref{Specify Location}. + +@item -rfunction @var{regexp} +@itemx -rfu @var{regexp} +@cindex skipping over functions via regular expressions +Functions whose name matches @var{regexp} will be skipped over when stepping. + +This form is useful for complex function names. +For example, there is generally no need to step into C@t{++} @code{std::string} +constructors or destructors. Plus with C@t{++} templates it can be hard to +write out the full name of the function, and often it doesn't matter what +the template arguments are. Specifying the function to be skipped as a +regular expression makes this easier. + +@smallexample +(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( +@end smallexample + +If you want to skip every templated C@t{++} constructor and destructor +in the @code{std} namespace you can do: + +@smallexample +(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( +@end smallexample +@end table + +If no options are specified, the function you're currently debugging +will be skipped. + @kindex skip function -@item skip @r{[}@var{linespec}@r{]} -@itemx skip function @r{[}@var{linespec}@r{]} +@item skip function @r{[}@var{linespec}@r{]} After running this command, the function named by @var{linespec} or the function containing the line named by @var{linespec} will be skipped over when stepping. @xref{Specify Location}. @@ -5489,6 +5640,11 @@ will be skipped. After running this command, any function whose source lives in @var{filename} will be skipped over when stepping. +@smallexample +(gdb) skip file boring.c +File boring.c will be skipped when stepping. +@end smallexample + If you do not specify @var{filename}, functions whose source lives in the file you're currently debugging will be skipped. @end table @@ -5506,20 +5662,21 @@ print a table with details about all functions and files marked for skipping. @table @emph @item Identifier A number identifying this skip. -@item Type -The type of this skip, either @samp{function} or @samp{file}. @item Enabled or Disabled -Enabled skips are marked with @samp{y}. Disabled skips are marked with @samp{n}. -@item Address -For function skips, this column indicates the address in memory of the function -being skipped. If you've set a function skip on a function which has not yet -been loaded, this field will contain @samp{}. Once a shared library -which has the function is loaded, @code{info skip} will show the function's -address here. -@item What -For file skips, this field contains the filename being skipped. For functions -skips, this field contains the function name and its line number in the file -where it is defined. +Enabled skips are marked with @samp{y}. +Disabled skips are marked with @samp{n}. +@item Glob +If the file name is a @samp{glob} pattern this is @samp{y}. +Otherwise it is @samp{n}. +@item File +The name or @samp{glob} pattern of the file to be skipped. +If no file is specified this is @samp{}. +@item RE +If the function name is a @samp{regular expression} this is @samp{y}. +Otherwise it is @samp{n}. +@item Function +The name or regular expression of the function to skip. +If no function is specified this is @samp{}. @end table @kindex skip delete @@ -5764,6 +5921,33 @@ $1 = (void *) 0x7ffff7ff7000 Depending on target support, @code{$_siginfo} may also be writable. +@cindex Intel MPX boundary violations +@cindex boundary violations, Intel MPX +On some targets, a @code{SIGSEGV} can be caused by a boundary +violation, i.e., accessing an address outside of the allowed range. +In those cases @value{GDBN} may displays additional information, +depending on how @value{GDBN} has been told to handle the signal. +With @code{handle stop SIGSEGV}, @value{GDBN} displays the violation +kind: "Upper" or "Lower", the memory address accessed and the +bounds, while with @code{handle nostop SIGSEGV} no additional +information is displayed. + +The usual output of a segfault is: +@smallexample +Program received signal SIGSEGV, Segmentation fault +0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 +68 value = *(p + len); +@end smallexample + +While a bound violation is presented as: +@smallexample +Program received signal SIGSEGV, Segmentation fault +Upper bound violation while accessing address 0x7fffffffc3b3 +Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3] +0x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 +68 value = *(p + len); +@end smallexample + @node Thread Stops @section Stopping and Starting Multi-thread Programs @@ -5836,17 +6020,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. @@ -6059,25 +6246,25 @@ breakpoints on all threads, or on a particular thread. @table @code @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 +@kindex break @dots{} thread @var{thread-id} +@item break @var{location} thread @var{thread-id} +@itemx break @var{location} thread @var{thread-id} 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. -Use the qualifier @samp{thread @var{threadno}} with a breakpoint command +Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command to specify that you only want @value{GDBN} to stop the program when a -particular thread reaches this breakpoint. The @var{threadno} specifier -is one of the numeric thread identifiers assigned by @value{GDBN}, shown +particular thread reaches this breakpoint. The @var{thread-id} specifier +is one of the thread identifiers assigned by @value{GDBN}, shown in the first column of the @samp{info threads} display. -If you do not specify @samp{thread @var{threadno}} when you set a +If you do not specify @samp{thread @var{thread-id}} when you set a breakpoint, the breakpoint applies to @emph{all} threads of your program. You can use the @code{thread} qualifier on conditional breakpoints as -well; in this case, place @samp{thread @var{threadno}} before or +well; in this case, place @samp{thread @var{thread-id}} before or after the breakpoint condition, like this: @smallexample @@ -6417,12 +6604,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 +6629,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 +6643,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 Processor Trace +Use the @dfn{Intel 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 +6668,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 +6833,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 +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 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 Processor Trace format. + @kindex info record @item info record Show various statistics about the recording depending on the recording @@ -6674,6 +6901,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 +6923,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 +6963,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 +7035,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 @@ -6836,9 +7088,9 @@ currently executing frame and describes it briefly, similar to the @menu * Frames:: Stack frames * Backtrace:: Backtraces -* Frame Filter Management:: Managing frame filters * Selection:: Selecting a frame * Frame Info:: Information on a frame +* Frame Filter Management:: Managing frame filters @end menu @@ -6897,23 +7149,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 +7348,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 +7641,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 +7721,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 +7756,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 +7816,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 +7927,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 +8170,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 +8244,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 +8264,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 +8288,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 +8337,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 +8364,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 +8466,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}. @@ -8342,6 +8732,7 @@ being passed the type of @var{arg} as the argument. character set than GDB does * Caching Target Data:: Data caching for targets * Searching Memory:: Searching memory for a sequence of bytes +* Value Sizes:: Managing memory allocated for values @end menu @node Expressions @@ -8904,7 +9295,8 @@ Several commands set convenient defaults for @var{addr}. @table @r @item @var{n}, the repeat count The repeat count is a decimal integer; the default is 1. It specifies -how much memory (counting by units @var{u}) to display. +how much memory (counting by units @var{u}) to display. If a negative +number is specified, memory is examined backward from @var{addr}. @c This really is **decimal**; unaffected by 'set radix' as of GDB @c 4.1.2. @@ -8959,6 +9351,10 @@ starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; @pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). +You can also specify a negative repeat count to examine memory backward +from the given address. For example, @samp{x/-3uh 0x54320} prints three +halfwords (@code{h}) at @code{0x54314}, @code{0x54328}, and @code{0x5431c}. + Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you do not have to remember whether unit size or format comes first; either order works. The output @@ -8975,6 +9371,13 @@ follow the last instruction that is within the count. The command @code{disassemble} gives an alternative way of inspecting machine instructions; see @ref{Machine Code,,Source and Machine Code}. +If a negative repeat count is specified for the formats @samp{s} or @samp{i}, +the command displays null-terminated strings or instructions before the given +address as many as the absolute value of the given number. For the @samp{i} +format, we use line number information in the debug info to accurately locate +instruction boundaries while disassembling backward. If line info is not +available, the command stops examining memory with an error message. + All the defaults for the arguments to @code{x} are designed to make it easy to continue scanning memory with minimal specifications each time you use @code{x}. For example, after you have inspected three machine @@ -9009,6 +9412,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 @@ -10181,11 +10596,17 @@ gdbserver that supports the @code{qGetTIBAddr} request. @xref{General Query Packets}. This variable contains the address of the thread information block. -@end table +@item $_inferior +The number of the current inferior. @xref{Inferiors and +Programs, ,Debugging Multiple Inferiors and Programs}. + +@item $_thread +The thread number of the current thread. @xref{thread numbers}. + +@item $_gthread +The global number of the current thread. @xref{global thread numbers}. -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, @value{GDBN} searches for a user or system -name first, before it searches for a convenience variable. +@end table @node Convenience Funs @section Convenience Functions @@ -10351,6 +10772,19 @@ checks all stack frames from the immediate caller to the frame specified by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the frame specified by @var{number_of_frames}. +@item $_as_string(@var{value}) +@findex $_as_string@r{, convenience function} +Return the string representation of @var{value}. + +This function is useful to obtain the textual label (enumerator) of an +enumeration value. For example, assuming the variable @var{node} is of +an enumerated type: + +@smallexample +(gdb) printf "Visiting node of type %s\n", $_as_string(node) +Visiting node of type NODE_INTEGER +@end smallexample + @end table @value{GDBN} provides the ability to list and get help on @@ -11399,6 +11833,47 @@ $1 = 1 $2 = (void *) 0x8049560 @end smallexample +@node Value Sizes +@section Value Sizes + +Whenever @value{GDBN} prints a value memory will be allocated within +@value{GDBN} to hold the contents of the value. It is possible in +some languages with dynamic typing systems, that an invalid program +may indicate a value that is incorrectly large, this in turn may cause +@value{GDBN} to try and allocate an overly large ammount of memory. + +@table @code +@kindex set max-value-size +@item set max-value-size @var{bytes} +@itemx set max-value-size unlimited +Set the maximum size of memory that @value{GDBN} will allocate for the +contents of a value to @var{bytes}, trying to display a value that +requires more memory than that will result in an error. + +Setting this variable does not effect values that have already been +allocated within @value{GDBN}, only future allocations. + +There's a minimum size that @code{max-value-size} can be set to in +order that @value{GDBN} can still operate correctly, this minimum is +currently 16 bytes. + +The limit applies to the results of some subexpressions as well as to +complete expressions. For example, an expression denoting a simple +integer component, such as @code{x.y.z}, may fail if the size of +@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand, +@value{GDBN} is sometimes clever; the expression @code{A[i]}, where +@var{A} is an array variable with non-constant size, will generally +succeed regardless of the bounds on @var{A}, as long as the component +size is less than @var{bytes}. + +The default value of @code{max-value-size} is currently 64k. + +@kindex show max-value-size +@item show max-value-size +Show the maximum size of memory, in bytes, that @value{GDBN} will +allocate for the contents of a value. +@end table + @node Optimized Code @chapter Debugging Optimized Code @cindex optimized code, debugging @@ -11717,9 +12192,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 +12499,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 @@ -12416,6 +12890,13 @@ Collect all local variables. Collect the return address. This is helpful if you want to see more of a backtrace. +@emph{Note:} The return address location can not always be reliably +determined up front, and the wrong address / registers may end up +collected instead. On some architectures the reliability is higher +for tracepoints at function entry, while on others it's the opposite. +When this happens, backtracing will stop because the return address is +found unavailable (unless another collect rule happened to match it). + @item $_probe_argc Collects the number of arguments from the static probe at which the tracepoint is located. @@ -12916,7 +13397,8 @@ Stop debugging trace snapshots, resume @emph{live} debugging. Same as @samp{tfind none}. @item tfind -No argument means find the next trace snapshot. +No argument means find the next trace snapshot or find the first +one if no trace snapshot is selected. @item tfind - Find the previous trace snapshot before the current one. This permits @@ -13929,7 +14411,7 @@ being set automatically by @value{GDBN}. @section Supported Languages @value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java, -OpenCL C, Pascal, assembly, Modula-2, and Ada. +OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada. @c This is false ... Some @value{GDBN} features may be used in expressions regardless of the language you use: the @value{GDBN} @code{@@} and @code{::} operators, @@ -13953,6 +14435,7 @@ language reference or tutorial. * OpenCL C:: OpenCL C * Fortran:: Fortran * Pascal:: Pascal +* Rust:: Rust * Modula-2:: Modula-2 * Ada:: Ada @end menu @@ -14758,6 +15241,99 @@ The Pascal-specific command @code{set print pascal_static-members} controls whether static members of Pascal objects are displayed. @xref{Print Settings, pascal_static-members}. +@node Rust +@subsection Rust + +@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust +Programming Language}. Type- and value-printing, and expression +parsing, are reasonably complete. However, there are a few +peculiarities and holes to be aware of. + +@itemize @bullet +@item +Linespecs (@pxref{Specify Location}) are never relative to the current +crate. Instead, they act as if there were a global namespace of +crates, somewhat similar to the way @code{extern crate} behaves. + +That is, if @value{GDBN} is stopped at a breakpoint in a function in +crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt +to set a breakpoint in a function named @samp{f} in a crate named +@samp{B}. + +As a consequence of this approach, linespecs also cannot refer to +items using @samp{self::} or @samp{super::}. + +@item +Because @value{GDBN} implements Rust name-lookup semantics in +expressions, it will sometimes prepend the current crate to a name. +For example, if @value{GDBN} is stopped at a breakpoint in the crate +@samp{K}, then @code{print ::x::y} will try to find the symbol +@samp{K::x::y}. + +However, since it is useful to be able to refer to other crates when +debugging, @value{GDBN} provides the @code{extern} extension to +circumvent this. To use the extension, just put @code{extern} before +a path expression to refer to the otherwise unavailable ``global'' +scope. + +In the above example, if you wanted to refer to the symbol @samp{y} in +the crate @samp{x}, you would use @code{print extern x::y}. + +@item +The Rust expression evaluator does not support ``statement-like'' +expressions such as @code{if} or @code{match}, or lambda expressions. + +@item +Tuple expressions are not implemented. + +@item +The Rust expression evaluator does not currently implement the +@code{Drop} trait. Objects that may be created by the evaluator will +never be destroyed. + +@item +@value{GDBN} does not implement type inference for generics. In order +to call generic functions or otherwise refer to generic items, you +will have to specify the type parameters manually. + +@item +@value{GDBN} currently uses the C@t{++} demangler for Rust. In most +cases this does not cause any problems. However, in an expression +context, completing a generic function name will give syntactically +invalid results. This happens because Rust requires the @samp{::} +operator between the function name and its generic arguments. For +example, @value{GDBN} might provide a completion like +@code{crate::f}, where the parser would require +@code{crate::f::}. + +@item +As of this writing, the Rust compiler (version 1.8) has a few holes in +the debugging information it generates. These holes prevent certain +features from being implemented by @value{GDBN}: +@itemize @bullet + +@item +Method calls cannot be made via traits. + +@item +Trait objects cannot be created or inspected. + +@item +Operator overloading is not implemented. + +@item +When debugging in a monomorphized function, you cannot use the generic +type names. + +@item +The type @code{Self} is not available. + +@item +@code{use} statements are not available, so some names may not be +available in the crate. +@end itemize +@end itemize + @node Modula-2 @subsection Modula-2 @@ -15389,6 +15965,8 @@ to be difficult. in @value{GDBN}. * Omissions from Ada:: Restrictions on the Ada expression syntax. * Additions to Ada:: Extensions of the Ada expression syntax. +* Overloading support for Ada:: Support for expressions involving overloaded + subprograms. * Stopping Before Main Program:: Debugging the program during elaboration. * Ada Exceptions:: Ada Exceptions * Ada Tasks:: Listing and setting breakpoints in tasks. @@ -15436,13 +16014,6 @@ mostly for documenting command files. The standard @value{GDBN} comment (@samp{#}) still works at the beginning of a line in Ada mode, but not in the middle (to allow based literals). -The debugger supports limited overloading. Given a subprogram call in which -the function symbol has multiple definitions, it will use the number of -actual parameters and some information about their types to attempt to narrow -the set of definitions. It also makes very limited use of context, preferring -procedures to functions in the context of the @code{call} command, and -functions to procedures elsewhere. - @node Omissions from Ada @subsubsection Omissions from Ada @cindex Ada, omissions from @@ -15703,6 +16274,53 @@ object. @end itemize +@node Overloading support for Ada +@subsubsection Overloading support for Ada +@cindex overloading, Ada + +The debugger supports limited overloading. Given a subprogram call in which +the function symbol has multiple definitions, it will use the number of +actual parameters and some information about their types to attempt to narrow +the set of definitions. It also makes very limited use of context, preferring +procedures to functions in the context of the @code{call} command, and +functions to procedures elsewhere. + +If, after narrowing, the set of matching definitions still contains more than +one definition, @value{GDBN} will display a menu to query which one it should +use, for instance: + +@smallexample +(@value{GDBP}) print f(1) +Multiple matches for f +[0] cancel +[1] foo.f (integer) return boolean at foo.adb:23 +[2] foo.f (foo.new_integer) return boolean at foo.adb:28 +> +@end smallexample + +In this case, just select one menu entry either to cancel expression evaluation +(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific +instance (type the corresponding number and press @key{RET}). + +Here are a couple of commands to customize @value{GDBN}'s behavior in this +case: + +@table @code + +@kindex set ada print-signatures +@item set ada print-signatures +Control whether parameter types and return types are displayed in overloads +selection menus. It is @code{on} by default. +@xref{Overloading support for Ada}. + +@kindex show ada print-signatures +@item show ada print-signatures +Show the current setting for displaying parameter types and return types in +overloads selection menu. +@xref{Overloading support for Ada}. + +@end table + @node Stopping Before Main Program @subsubsection Stopping at the Very Beginning @@ -15886,7 +16504,7 @@ This command prints the ID of the current task. @item task @var{taskno} @cindex Ada task switching -This command is like the @code{thread @var{threadno}} +This command is like the @code{thread @var{thread-id}} command (@pxref{Threads}). It switches the context of debugging from the current task to the given task. @@ -15909,14 +16527,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 @@ -16671,6 +17289,15 @@ line 1574. (@value{GDBP}) @end smallexample +@kindex maint info line-table +@cindex listing @value{GDBN}'s internal line tables +@cindex line tables, listing @value{GDBN}'s internal +@item maint info line-table @r{[} @var{regexp} @r{]} + +List the @code{struct linetable} from all @code{struct symtab} +instances whose name matches @var{regexp}. If @var{regexp} is not +given, list the @code{struct linetable} from all @code{struct symtab}. + @kindex maint set symbol-cache-size @cindex symbol cache size @item maint set symbol-cache-size @var{size} @@ -16844,20 +17471,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 @@ -16866,7 +17490,6 @@ executing. However, even bizarre results are predictable if you are well acquainted with the machine-language code of your program. @end table -@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. On many systems, you can get much the same effect as the @code{jump} command by storing a new value into the register @code{$pc}. The difference is that this does not start your program running; it only @@ -17485,6 +18108,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 @@ -17812,8 +18436,9 @@ name and remembers it that way. @cindex shared libraries @anchor{Shared Libraries} -@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, -and IBM RS/6000 AIX shared libraries. +@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS, +Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and +DSBT (TIC6X) shared libraries. On MS-Windows @value{GDBN} must be linked with the Expat library to support shared libraries. @xref{Expat}. @@ -17824,9 +18449,6 @@ when you use the @code{run} command, or when you examine a core file. references to a function in a shared library, however---unless you are debugging a core file). -On HP-UX, if the program loads a library explicitly, @value{GDBN} -automatically loads the symbols at the time of the @code{shl_load} call. - @c FIXME: some @value{GDBN} release may permit some refs to undef @c FIXME...symbols---eg in a break cmd---assuming they are from a shared @c FIXME...lib; check this from time to time when updating manual @@ -18135,6 +18757,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 +18832,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, @@ -18979,28 +19641,148 @@ configuration of @value{GDBN}; use @code{help target} to list them. @node Connecting @section Connecting to a Remote Target +@cindex remote debugging, connecting +@cindex @code{gdbserver}, connecting +@cindex remote debugging, types of connections +@cindex @code{gdbserver}, types of connections +@cindex @code{gdbserver}, @code{target remote} mode +@cindex @code{gdbserver}, @code{target extended-remote} mode + +This section describes how to connect to a remote target, including the +types of connections and their differences, how to set up executable and +symbol files on the host and target, and the commands used for +connecting to and disconnecting from the remote target. + +@subsection Types of Remote Connections -@value{GDBN} needs an unstripped copy of your program to access symbol -and debugging information. Some remote targets (@pxref{qXfer -executable filename read}, and @pxref{Host I/O Packets}) allow -@value{GDBN} to access program files over the same connection used to -communicate with @value{GDBN}. With such a target, if the remote -program is unstripped, the only command you need is @code{target -remote}. Otherwise, start up @value{GDBN} using the name of the local +@value{GDBN} supports two types of remote connections, @code{target remote} +mode and @code{target extended-remote} mode. Note that many remote targets +support only @code{target remote} mode. There are several major +differences between the two types of connections, enumerated here: + +@table @asis + +@cindex remote debugging, detach and program exit +@item Result of detach or program exit +@strong{With target remote mode:} When the debugged program exits or you +detach from it, @value{GDBN} disconnects from the target. When using +@code{gdbserver}, @code{gdbserver} will exit. + +@strong{With target extended-remote mode:} When the debugged program exits or +you detach from it, @value{GDBN} remains connected to the target, even +though no program is running. You can rerun the program, attach to a +running program, or use @code{monitor} commands specific to the target. + +When using @code{gdbserver} in this case, it does not exit unless it was +invoked using the @option{--once} option. If the @option{--once} option +was not used, you can ask @code{gdbserver} to exit using the +@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}). + +@item Specifying the program to debug +For both connection types you use the @code{file} command to specify the +program on the host system. If you are using @code{gdbserver} there are +some differences in how to specify the location of the program on the +target. + +@strong{With target remote mode:} You must either specify the program to debug +on the @code{gdbserver} command line or use the @option{--attach} option +(@pxref{Attaching to a program,,Attaching to a Running Program}). + +@cindex @option{--multi}, @code{gdbserver} option +@strong{With target extended-remote mode:} You may specify the program to debug +on the @code{gdbserver} command line, or you can load the program or attach +to it using @value{GDBN} commands after connecting to @code{gdbserver}. + +@anchor{--multi Option in Types of Remote Connnections} +You can start @code{gdbserver} without supplying an initial command to run +or process ID to attach. To do this, use the @option{--multi} command line +option. Then you can connect using @code{target extended-remote} and start +the program you want to debug (see below for details on using the +@code{run} command in this scenario). Note that the conditions under which +@code{gdbserver} terminates depend on how @value{GDBN} connects to it +(@code{target remote} or @code{target extended-remote}). The +@option{--multi} option to @code{gdbserver} has no influence on that. + +@item The @code{run} command +@strong{With target remote mode:} The @code{run} command is not +supported. Once a connection has been established, you can use all +the usual @value{GDBN} commands to examine and change data. The +remote program is already running, so you can use commands like +@kbd{step} and @kbd{continue}. + +@strong{With target extended-remote mode:} The @code{run} command is +supported. The @code{run} command uses the value set by +@code{set remote exec-file} (@pxref{set remote exec-file}) to select +the program to run. Command line arguments are supported, except for +wildcard expansion and I/O redirection (@pxref{Arguments}). + +If you specify the program to debug on the command line, then the +@code{run} command is not required to start execution, and you can +resume using commands like @kbd{step} and @kbd{continue} as with +@code{target remote} mode. + +@anchor{Attaching in Types of Remote Connections} +@item Attaching +@strong{With target remote mode:} The @value{GDBN} command @code{attach} is +not supported. To attach to a running program using @code{gdbserver}, you +must use the @option{--attach} option (@pxref{Running gdbserver}). + +@strong{With target extended-remote mode:} To attach to a running program, +you may use the @code{attach} command after the connection has been +established. If you are using @code{gdbserver}, you may also invoke +@code{gdbserver} using the @option{--attach} option +(@pxref{Running gdbserver}). + +@end table + +@anchor{Host and target files} +@subsection Host and Target Files +@cindex remote debugging, symbol files +@cindex symbol files, remote debugging + +@value{GDBN}, running on the host, needs access to symbol and debugging +information for your program running on the target. This requires +access to an unstripped copy of your program, and possibly any associated +symbol files. Note that this section applies equally to both @code{target +remote} mode and @code{target extended-remote} mode. + +Some remote targets (@pxref{qXfer executable filename read}, and +@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over +the same connection used to communicate with @value{GDBN}. With such a +target, if the remote program is unstripped, the only command you need is +@code{target remote} (or @code{target extended-remote}). + +If the remote program is stripped, or the target does not support remote +program file access, start up @value{GDBN} using the name of the local unstripped copy of your program as the first argument, or use the -@code{file} command. +@code{file} command. Use @code{set sysroot} to specify the location (on +the host) of target libraries (unless your @value{GDBN} was compiled with +the correct sysroot using @code{--with-sysroot}). Alternatively, you +may use @code{set solib-search-path} to specify how @value{GDBN} locates +target libraries. -@cindex @code{target remote} +The symbol file and target libraries must exactly match the executable +and libraries on the target, with one exception: the files on the host +system should not be stripped, even if the files on the target system +are. Mismatched or missing files will lead to confusing results +during debugging. On @sc{gnu}/Linux targets, mismatched or missing +files may also prevent @code{gdbserver} from debugging multi-threaded +programs. + +@subsection Remote Connection Commands +@cindex remote connection commands @value{GDBN} can communicate with the target over a serial line, or over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In each case, @value{GDBN} uses the same protocol for debugging your program; only the medium carrying the debugging packets varies. The -@code{target remote} command establishes a connection to the target. -Its arguments indicate which medium to use: +@code{target remote} and @code{target extended-remote} commands +establish a connection to the target. Both commands accept the same +arguments, which indicate the medium to use: @table @code @item target remote @var{serial-device} +@itemx target extended-remote @var{serial-device} @cindex serial line, @code{target remote} Use @var{serial-device} to communicate with the target. For example, to use a serial line connected to the device named @file{/dev/ttyb}: @@ -19016,6 +19798,8 @@ If you're using a serial line, you may want to give @value{GDBN} the @item target remote @code{@var{host}:@var{port}} @itemx target remote @code{tcp:@var{host}:@var{port}} +@itemx target extended-remote @code{@var{host}:@var{port}} +@itemx target extended-remote @code{tcp:@var{host}:@var{port}} @cindex @acronym{TCP} port, @code{target remote} Debug using a @acronym{TCP} connection to @var{port} on @var{host}. The @var{host} may be either a host name or a numeric @acronym{IP} @@ -19044,6 +19828,7 @@ target remote :1234 Note that the colon is still required here. @item target remote @code{udp:@var{host}:@var{port}} +@itemx target extended-remote @code{udp:@var{host}:@var{port}} @cindex @acronym{UDP} port, @code{target remote} Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: @@ -19058,6 +19843,7 @@ can silently drop packets on busy or unreliable networks, which will cause havoc with your debugging session. @item target remote | @var{command} +@itemx target extended-remote | @var{command} @cindex pipe, @code{target remote} to Run @var{command} in the background and communicate with it using a pipe. The @var{command} is a shell command, to be parsed and expanded @@ -19073,11 +19859,6 @@ program has already exited, this will have no effect.) @end table -Once the connection has been established, you can use all the usual -commands to examine and change data. The remote program is already -running; you can use @kbd{step} and @kbd{continue}, and you do not -need to use @kbd{run}. - @cindex interrupting remote programs @cindex remote programs, interrupting Whenever @value{GDBN} is waiting for the remote program, if you type the @@ -19091,10 +19872,13 @@ Interrupted while waiting for the program. Give up (and stop debugging it)? (y or n) @end smallexample -If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. -(If you decide you want to try again later, you can use @samp{target -remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} -goes back to waiting. +In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons +the remote debugging session. (If you decide you want to try again later, +you can use @kbd{target remote} again to connect once more.) If you type +@kbd{n}, @value{GDBN} goes back to waiting. + +In @code{target extended-remote} mode, typing @kbd{n} will leave +@value{GDBN} connected to the target. @table @code @kindex detach (remote) @@ -19103,11 +19887,13 @@ When you have finished debugging the remote program, you can use the @code{detach} command to release it from @value{GDBN} control. Detaching from the target normally resumes its execution, but the results will depend on your particular remote stub. After the @code{detach} -command, @value{GDBN} is free to connect to another target. +command in @code{target remote} mode, @value{GDBN} is free to connect to +another target. In @code{target extended-remote} mode, @value{GDBN} is +still connected to the target. @kindex disconnect @item disconnect -The @code{disconnect} command behaves like @code{detach}, except that +The @code{disconnect} command closes the connection to the target, and the target is generally not resumed. It will wait for @value{GDBN} (this instance or another one) to connect and continue debugging. After the @code{disconnect} command, @value{GDBN} is again free to connect to @@ -19164,7 +19950,8 @@ Delete @var{targetfile} from the target system. @cindex remote connection without stubs @code{gdbserver} is a control program for Unix-like systems, which allows you to connect your program with a remote @value{GDBN} via -@code{target remote}---but without linking in the usual debugging stub. +@code{target remote} or @code{target extended-remote}---but without +linking in the usual debugging stub. @code{gdbserver} is not a complete replacement for the debugging stubs, because it requires essentially the same operating-system facilities @@ -19192,6 +19979,7 @@ target system with the same privileges as the user running @code{gdbserver}. @end quotation +@anchor{Running gdbserver} @subsection Running @code{gdbserver} @cindex arguments, to @code{gdbserver} @cindex @code{gdbserver}, command-line arguments @@ -19259,6 +20047,7 @@ Programs started with stdio-connected gdbserver have @file{/dev/null} for display through a pipe connected to gdbserver. Both @code{stdout} and @code{stderr} use the same pipe. +@anchor{Attaching to a program} @subsubsection Attaching to a Running Program @cindex attach to a program, @code{gdbserver} @cindex @option{--attach}, @code{gdbserver} option @@ -19270,8 +20059,12 @@ This is accomplished via the @code{--attach} argument. The syntax is: target> gdbserver --attach @var{comm} @var{pid} @end smallexample -@var{pid} is the process ID of a currently running process. It isn't necessary -to point @code{gdbserver} at a binary for the running process. +@var{pid} is the process ID of a currently running process. It isn't +necessary to point @code{gdbserver} at a binary for the running process. + +In @code{target extended-remote} mode, you can also attach using the +@value{GDBN} attach command +(@pxref{Attaching in Types of Remote Connections}). @pindex pidof You can debug processes by name instead of process ID if your target has the @@ -19285,41 +20078,10 @@ In case more than one copy of @var{program} is running, or @var{program} has multiple threads, most versions of @code{pidof} support the @code{-s} option to only return the first process ID. -@subsubsection Multi-Process Mode for @code{gdbserver} -@cindex @code{gdbserver}, multiple processes -@cindex multiple processes with @code{gdbserver} - -When you connect to @code{gdbserver} using @code{target remote}, -@code{gdbserver} debugs the specified program only once. When the -program exits, or you detach from it, @value{GDBN} closes the connection -and @code{gdbserver} exits. - -If you connect using @kbd{target extended-remote}, @code{gdbserver} -enters multi-process mode. When the debugged program exits, or you -detach from it, @value{GDBN} stays connected to @code{gdbserver} even -though no program is running. The @code{run} and @code{attach} -commands instruct @code{gdbserver} to run or attach to a new program. -The @code{run} command uses @code{set remote exec-file} (@pxref{set -remote exec-file}) to select the program to run. Command line -arguments are supported, except for wildcard expansion and I/O -redirection (@pxref{Arguments}). - -@cindex @option{--multi}, @code{gdbserver} option -To start @code{gdbserver} without supplying an initial command to run -or process ID to attach, use the @option{--multi} command line option. -Then you can connect using @kbd{target extended-remote} and start -the program you want to debug. - -In multi-process mode @code{gdbserver} does not automatically exit unless you -use the option @option{--once}. You can terminate it by using -@code{monitor exit} (@pxref{Monitor Commands for gdbserver}). Note that the -conditions under which @code{gdbserver} terminates depend on how @value{GDBN} -connects to it (@kbd{target remote} or @kbd{target extended-remote}). The -@option{--multi} option to @code{gdbserver} has no influence on that. - @subsubsection TCP port allocation lifecycle of @code{gdbserver} -This section applies only when @code{gdbserver} is run to listen on a TCP port. +This section applies only when @code{gdbserver} is run to listen on a TCP +port. @code{gdbserver} normally terminates after all of its debugged processes have terminated in @kbd{target remote} mode. On the other hand, for @kbd{target @@ -19350,6 +20112,12 @@ instance closes its port after the first connection. @anchor{Other Command-Line Arguments for gdbserver} @subsubsection Other Command-Line Arguments for @code{gdbserver} +You can use the @option{--multi} option to start @code{gdbserver} without +specifying a program to debug or a process to attach to. Then you can +attach in @code{target extended-remote} mode and run or attach to a +program. For more information, +@pxref{--multi Option in Types of Remote Connnections}. + @cindex @option{--debug}, @code{gdbserver} option The @option{--debug} option tells @code{gdbserver} to display extra status information about the debugging process. @@ -19401,32 +20169,34 @@ $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog @subsection Connecting to @code{gdbserver} -Run @value{GDBN} on the host system. +The basic procedure for connecting to the remote target is: +@itemize -First make sure you have the necessary symbol files. Load symbols for -your application using the @code{file} command before you connect. Use -@code{set sysroot} to locate target libraries (unless your @value{GDBN} -was compiled with the correct sysroot using @code{--with-sysroot}). +@item +Run @value{GDBN} on the host system. -The symbol file and target libraries must exactly match the executable -and libraries on the target, with one exception: the files on the host -system should not be stripped, even if the files on the target system -are. Mismatched or missing files will lead to confusing results -during debugging. On @sc{gnu}/Linux targets, mismatched or missing -files may also prevent @code{gdbserver} from debugging multi-threaded -programs. +@item +Make sure you have the necessary symbol files +(@pxref{Host and target files}). +Load symbols for your application using the @code{file} command before you +connect. Use @code{set sysroot} to locate target libraries (unless your +@value{GDBN} was compiled with the correct sysroot using +@code{--with-sysroot}). +@item Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). For TCP connections, you must start up @code{gdbserver} prior to using -the @code{target remote} command. Otherwise you may get an error whose +the @code{target} command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like @samp{Connection refused}. Don't use the @code{load} -command in @value{GDBN} when using @code{gdbserver}, since the program is -already on the target. +command in @value{GDBN} when using @code{target remote} mode, since the +program is already on the target. +@end itemize + +@anchor{Monitor Commands for gdbserver} @subsection Monitor Commands for @code{gdbserver} @cindex monitor commands, for @code{gdbserver} -@anchor{Monitor Commands for gdbserver} During a @value{GDBN} session using @code{gdbserver}, you can use the @code{monitor} command to send special requests to @code{gdbserver}. @@ -19880,6 +20650,10 @@ are: @tab @code{qSupported} @tab Remote communications parameters +@item @code{catch-syscalls} +@tab @code{QCatchSyscalls} +@tab @code{catch syscall} + @item @code{pass-signals} @tab @code{QPassSignals} @tab @code{handle @var{signal}} @@ -19916,6 +20690,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 +20730,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 +20750,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 @@ -20313,7 +21107,6 @@ This section describes details specific to particular native configurations. @menu -* HP-UX:: HP-UX * BSD libkvm Interface:: Debugging BSD kernel memory images * SVR4 Process Information:: SVR4 process information * DJGPP Native:: Features specific to the DJGPP port @@ -20322,14 +21115,6 @@ configurations. * Darwin:: Features specific to Darwin @end menu -@node HP-UX -@subsection HP-UX - -On HP-UX systems, if you refer to a function or variable name that -begins with a dollar sign, @value{GDBN} searches for a user or system -name first, before it searches for a convenience variable. - - @node BSD libkvm Interface @subsection BSD libkvm Interface @@ -20384,7 +21169,7 @@ If @value{GDBN} is configured for an operating system with this facility, the command @code{info proc} is available to report information about the process running your program, or about any process running on your system. This includes, as of this writing, -@sc{gnu}/Linux and Solaris, but not HP-UX, for example. +@sc{gnu}/Linux and Solaris, for example. This command may also work on core files that were created on a system that has the @samp{/proc} facility. @@ -21173,16 +21958,11 @@ acceptable commands. @menu -* ARM:: ARM RDI -* M32R/D:: Renesas M32R/D +* ARM:: ARM * 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 +21970,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 +22045,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,108 +22065,10 @@ 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 - -The following commands are available for M32R/SDI: - -@table @code -@item sdireset -@kindex sdireset -@cindex reset SDI connection, M32R -This command resets the SDI connection. - -@item sdistatus -@kindex sdistatus -This command shows the SDI connection status. - -@item debug_chaos -@kindex debug_chaos -@cindex M32R/Chaos debugging -Instructs the remote that M32R/Chaos debugging is to be used. - -@item use_debug_dma -@kindex use_debug_dma -Instructs the remote to use the DEBUG_DMA method of accessing memory. - -@item use_mon_code -@kindex use_mon_code -Instructs the remote to use the MON_CODE method of accessing memory. - -@item use_ib_break -@kindex use_ib_break -Instructs the remote to set breakpoints by IB break. - -@item use_dbt_break -@kindex use_dbt_break -Instructs the remote to set breakpoints by DBT. -@end table - @node M68K @subsection M68k -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 @@ -21487,67 +22111,8 @@ Show MicroBlaze-specific debugging level. @node MIPS Embedded @subsection @acronym{MIPS} Embedded -@cindex @acronym{MIPS} boards -@value{GDBN} can use the @acronym{MIPS} remote debugging protocol to talk to a -@acronym{MIPS} board attached to a serial line. This is available when -you configure @value{GDBN} with @samp{--target=mips-elf}. - -@need 1000 -Use these @value{GDBN} commands to specify the connection to your target board: - -@table @code -@item target mips @var{port} -@kindex target mips @var{port} -To run a program on the board, start up @code{@value{GDBP}} with the -name of your program as the argument. To connect to the board, use the -command @samp{target mips @var{port}}, where @var{port} is the name of -the serial port connected to the board. If the program has not already -been downloaded to the board, you may use the @code{load} command to -download it. You can then use all the usual @value{GDBN} commands. - -For example, this sequence connects to the target board through a serial -port, and loads and runs a program called @var{prog} through the -debugger: - -@smallexample -host$ @value{GDBP} @var{prog} -@value{GDBN} is free software and @dots{} -(@value{GDBP}) target mips /dev/ttyb -(@value{GDBP}) load @var{prog} -(@value{GDBP}) run -@end smallexample - -@item target mips @var{hostname}:@var{portnumber} -On some @value{GDBN} host configurations, you can specify a TCP -connection (for instance, to a serial line managed by a terminal -concentrator) instead of a serial port, using the syntax -@samp{@var{hostname}:@var{portnumber}}. - -@item target pmon @var{port} -@kindex target pmon @var{port} -PMON ROM monitor. - -@item target ddb @var{port} -@kindex target ddb @var{port} -NEC's DDB variant of PMON for Vr4300. - -@item target lsi @var{port} -@kindex target lsi @var{port} -LSI variant of PMON. - -@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 - - @noindent -@value{GDBN} also supports these special commands for @acronym{MIPS} targets: +@value{GDBN} supports these special commands for @acronym{MIPS} targets: @table @code @item set mipsfpu double @@ -21577,78 +22142,6 @@ and @samp{set mipsfpu off} will select no floating point. As usual, you can inquire about the @code{mipsfpu} variable with @samp{show mipsfpu}. - -@item set timeout @var{seconds} -@itemx set retransmit-timeout @var{seconds} -@itemx show timeout -@itemx show retransmit-timeout -@cindex @code{timeout}, @acronym{MIPS} protocol -@cindex @code{retransmit-timeout}, @acronym{MIPS} protocol -@kindex set timeout -@kindex show timeout -@kindex set retransmit-timeout -@kindex show retransmit-timeout -You can control the timeout used while waiting for a packet, in the @acronym{MIPS} -remote protocol, with the @code{set timeout @var{seconds}} command. The -default is 5 seconds. Similarly, you can control the timeout used while -waiting for an acknowledgment of a packet with the @code{set -retransmit-timeout @var{seconds}} command. The default is 3 seconds. -You can inspect both values with @code{show timeout} and @code{show -retransmit-timeout}. (These commands are @emph{only} available when -@value{GDBN} is configured for @samp{--target=mips-elf}.) - -The timeout set by @code{set timeout} does not apply when @value{GDBN} -is waiting for your program to stop. In that case, @value{GDBN} waits -forever because it has no way of knowing how long the program is going -to run before stopping. - -@item set syn-garbage-limit @var{num} -@kindex set syn-garbage-limit@r{, @acronym{MIPS} remote} -@cindex synchronize with remote @acronym{MIPS} target -Limit the maximum number of characters @value{GDBN} should ignore when -it tries to synchronize with the remote target. The default is 10 -characters. Setting the limit to -1 means there's no limit. - -@item show syn-garbage-limit -@kindex show syn-garbage-limit@r{, @acronym{MIPS} remote} -Show the current limit on the number of characters to ignore when -trying to synchronize with the remote system. - -@item set monitor-prompt @var{prompt} -@kindex set monitor-prompt@r{, @acronym{MIPS} remote} -@cindex remote monitor prompt -Tell @value{GDBN} to expect the specified @var{prompt} string from the -remote monitor. The default depends on the target: -@table @asis -@item pmon target -@samp{PMON} -@item ddb target -@samp{NEC010} -@item lsi target -@samp{PMON>} -@end table - -@item show monitor-prompt -@kindex show monitor-prompt@r{, @acronym{MIPS} remote} -Show the current strings @value{GDBN} expects as the prompt from the -remote monitor. - -@item set monitor-warnings -@kindex set monitor-warnings@r{, @acronym{MIPS} remote} -Enable or disable monitor warnings about hardware breakpoints. This -has effect only for the @code{lsi} target. When on, @value{GDBN} will -display warning messages whose codes are returned by the @code{lsi} -PMON monitor for breakpoint commands. - -@item show monitor-warnings -@kindex show monitor-warnings@r{, @acronym{MIPS} remote} -Show the current setting of printing monitor warnings. - -@item pmon @var{command} -@kindex pmon@r{, @acronym{MIPS} remote} -@cindex send PMON command -This command allows sending an arbitrary @var{command} string to the -monitor. The monitor must be in debug mode for this to work. @end table @node PowerPC Embedded @@ -21729,270 +22222,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 @@ -22127,10 +22358,11 @@ be returned in a register. @kindex show struct-convention 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). +@subsubsection Intel @dfn{Memory Protection Extensions} (MPX). +@cindex Intel Memory Protection Extensions (MPX). Memory Protection Extension (MPX) adds the bound registers @samp{BND0} @footnote{The register named with capital letters represent the architecture @@ -22168,6 +22400,7 @@ 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}. @@ -22617,14 +22850,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{!}. @@ -23472,6 +23721,11 @@ expression parsing. The default is off. @item show debug expression Displays the current state of displaying debugging info about @value{GDBN} expression parsing. +@item set debug fbsd-lwp +@cindex FreeBSD LWP debug messages +Turns on or off debugging messages from the FreeBSD LWP debug support. +@item show debug fbsd-lwp +Show the current state of FreeBSD LWP debugging messages. @item set debug frame @cindex frame debugging info Turns on or off display of @value{GDBN} frame debugging info. The @@ -23481,7 +23735,7 @@ Displays the current state of displaying @value{GDBN} frame debugging info. @item set debug gnu-nat @cindex @sc{gnu}/Hurd debug messages -Turns on or off debugging messages from the @sc{gnu}/Hurd debug support. +Turn on or off debugging messages from the @sc{gnu}/Hurd debug support. @item show debug gnu-nat Show the current state of @sc{gnu}/Hurd debugging messages. @item set debug infrun @@ -23493,18 +23747,18 @@ for implementing operations such as single-stepping the inferior. Displays the current state of @value{GDBN} inferior debugging. @item set debug jit @cindex just-in-time compilation, debugging messages -Turns on or off debugging messages from JIT debug support. +Turn on or off debugging messages from JIT debug support. @item show debug jit Displays the current state of @value{GDBN} JIT debugging. @item set debug lin-lwp @cindex @sc{gnu}/Linux LWP debug messages @cindex Linux lightweight processes -Turns on or off debugging messages from the Linux LWP debug support. +Turn 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. +Turn 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 @@ -23516,7 +23770,7 @@ Displays the current state of displaying debugging messages related to reading of COFF/PE exported symbols. @item set debug notification @cindex remote async notification debugging info -Turns on or off debugging messages about remote async notification. +Turn on or off debugging messages about remote async notification. The default is off. @item show debug notification Displays the current state of remote async notification debugging messages. @@ -23562,7 +23816,7 @@ Displays the current state of displaying @value{GDBN} serial debugging info. @item set debug solib-frv @cindex FR-V shared-library debugging -Turns on or off debugging messages for FR-V shared-library code. +Turn on or off debugging messages for FR-V shared-library code. @item show debug solib-frv Display the current state of FR-V shared-library code debugging messages. @@ -23614,7 +23868,7 @@ Displays the current state of displaying @value{GDBN} variable object debugging info. @item set debug xml @cindex XML parser debugging -Turns on or off debugging messages for built-in XML parsers. +Turn on or off debugging messages for built-in XML parsers. @item show debug xml Displays the current state of XML debugging messages. @end table @@ -24701,7 +24955,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 @@ -24990,69 +25244,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 @@ -25430,8 +25706,8 @@ increases the risk that by relying on implicitly selected thread, the frontend may be operating on a wrong one. Therefore, each MI command should explicitly specify which thread and frame to operate on. To make it possible, each MI command accepts the @samp{--thread} and -@samp{--frame} options, the value to each is @value{GDBN} identifier -for thread and frame to operate on. +@samp{--frame} options, the value to each is @value{GDBN} global +identifier for thread and frame to operate on. Usually, each top-level window in a frontend allows the user to select a thread and a frame, and remembers the user selection for further @@ -25984,15 +26260,16 @@ The following is the list of possible async records: @table @code @item *running,thread-id="@var{thread}" -The target is now running. The @var{thread} field tells which -specific thread is now running, and can be @samp{all} if all threads -are running. The frontend should assume that no interaction with a -running thread is possible after this notification is produced. -The frontend should not assume that this notification is output -only once for any command. @value{GDBN} may emit this notification -several times, either for different threads, because it cannot resume -all threads together, or even for a single thread, if the thread must -be stepped though some code before letting it run freely. +The target is now running. The @var{thread} field can be the global +thread ID of the the thread that is now running, and it can be +@samp{all} if all threads are running. The frontend should assume +that no interaction with a running thread is possible after this +notification is produced. The frontend should not assume that this +notification is output only once for any command. @value{GDBN} may +emit this notification several times, either for different threads, +because it cannot resume all threads together, or even for a single +thread, if the thread must be stepped though some code before letting +it run freely. @item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}" The target has stopped. The @var{reason} field can have one of the @@ -26046,8 +26323,9 @@ The inferior called @code{exec}. This is reported when @code{catch exec} (@pxref{Set Catchpoints}) has been used. @end table -The @var{id} field identifies the thread that directly caused the stop --- for example by hitting a breakpoint. Depending on whether all-stop +The @var{id} field identifies the global thread ID of the thread +that directly caused the stop -- for example by hitting a breakpoint. +Depending on whether all-stop mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either stop all threads, or only the thread that directly triggered the stop. If all threads are stopped, the @var{stopped} field will have the @@ -26083,7 +26361,7 @@ only when the inferior exited with some code. @item =thread-created,id="@var{id}",group-id="@var{gid}" @itemx =thread-exited,id="@var{id}",group-id="@var{gid}" A thread either was created, or has exited. The @var{id} field -contains the @value{GDBN} identifier of the thread. The @var{gid} +contains the global @value{GDBN} identifier of the thread. The @var{gid} field identifies the thread group this thread belongs to. @item =thread-selected,id="@var{id}" @@ -26157,12 +26435,17 @@ breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The Note that if a breakpoint is emitted in the result record of a command, then it will not also be emitted in an async record. -@item =record-started,thread-group="@var{id}" +@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"] @itemx =record-stopped,thread-group="@var{id}" Execution log recording was either started or stopped on an inferior. The @var{id} is the @value{GDBN} identifier of the thread group corresponding to the affected inferior. +The @var{method} field indicates the method used to record execution. If the +method in use supports multiple recording formats, @var{format} will be present +and contain the currently used format. @xref{Process Record and Replay} +for existing method and format values. + @item =cmd-param-changed,param=@var{param},value=@var{value} Reports that a parameter of the command @code{set @var{param}} is changed to @var{value}. In the multi-word @code{set} command, @@ -26344,7 +26627,7 @@ uses a tuple with the following fields: @table @code @item id -The numeric id assigned to the thread by @value{GDBN}. This field is +The global numeric id assigned to the thread by @value{GDBN}. This field is always present. @item target-id @@ -26752,6 +27035,7 @@ N.A. @subheading The @code{-break-insert} Command @findex -break-insert +@anchor{-break-insert} @subsubheading Synopsis @@ -26764,16 +27048,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 @@ -26797,7 +27100,8 @@ Make the breakpoint conditional on @var{condition}. @item -i @var{ignore-count} Initialize the @var{ignore-count}. @item -p @var{thread-id} -Restrict the breakpoint to the specified @var{thread-id}. +Restrict the breakpoint to the thread with the specified global +@var{thread-id}. @end table @subsubheading Result @@ -26865,17 +27169,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: @@ -26896,7 +27191,8 @@ Make the breakpoint conditional on @var{condition}. Set the ignore count of the breakpoint (@pxref{Conditions, ignore count}) to @var{ignore-count}. @item -p @var{thread-id} -Restrict the breakpoint to the specified @var{thread-id}. +Restrict the breakpoint to the thread with the specified global +@var{thread-id}. @end table @subsubheading Result @@ -27546,10 +27842,11 @@ The corresponding @value{GDBN} command is @samp{pwd}. -thread-info [ @var{thread-id} ] @end smallexample -Reports information about either a specific thread, if -the @var{thread-id} parameter is present, or about all -threads. When printing information about all threads, -also reports the current thread. +Reports information about either a specific thread, if the +@var{thread-id} parameter is present, or about all threads. +@var{thread-id} is the thread's global thread ID. When printing +information about all threads, also reports the global ID of the +current thread. @subsubheading @value{GDBN} Command @@ -27566,7 +27863,7 @@ defined for a given thread: This field exists only for the current thread. It has the value @samp{*}. @item id -The identifier that @value{GDBN} uses to refer to the thread. +The global identifier that @value{GDBN} uses to refer to the thread. @item target-id The identifier that the target uses to refer to the thread. @@ -27632,8 +27929,9 @@ current-thread-id="1" -thread-list-ids @end smallexample -Produces a list of the currently known @value{GDBN} thread ids. At the -end of the list it also prints the total number of such threads. +Produces a list of the currently known global @value{GDBN} thread ids. +At the end of the list it also prints the total number of such +threads. This command is retained for historical reasons, the @code{-thread-info} command should be used instead. @@ -27659,11 +27957,12 @@ current-thread-id="1",number-of-threads="3" @subsubheading Synopsis @smallexample - -thread-select @var{threadnum} + -thread-select @var{thread-id} @end smallexample -Make @var{threadnum} the current thread. It prints the number of the new -current thread, and the topmost frame for that thread. +Make thread with global thread number @var{thread-id} the current +thread. It prints the number of the new current thread, and the +topmost frame for that thread. This command is deprecated in favor of explicitly using the @samp{--thread} option to each command. @@ -27732,7 +28031,8 @@ The identifier that @value{GDBN} uses to refer to the Ada task. The identifier that the target uses to refer to the Ada task. @item thread-id -The identifier of the thread corresponding to the Ada task. +The global thread identifier of the thread corresponding to the Ada +task. This field should always exist, as Ada tasks are always implemented on top of a thread. But if @value{GDBN} cannot find this corresponding @@ -28948,7 +29248,7 @@ would be printed by the @value{GDBN} CLI. If @samp{print object} @item thread-id If a variable object is bound to a specific thread, then this is the -thread's identifier. +thread's global identifier. @item has_more For a dynamic varobj, this indicates whether there appear to be any @@ -29005,13 +29305,18 @@ The syntax for the @var{format-spec} is as follows: @smallexample @var{format-spec} @expansion{} - @{binary | decimal | hexadecimal | octal | natural@} + @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@} @end smallexample The natural format is the default format choosen automatically based on the variable type (like decimal for an @code{int}, hex for pointers, etc.). +The zero-hexadecimal format has a representation similar to hexadecimal +but with padding zeroes to the left of the value. For example, a 32-bit +hexadecimal value of 0x1234 would be represented as 0x00001234 in the +zero-hexadecimal format. + For a variable with children, the format is set only on the variable itself, and the children are not affected. @@ -29124,8 +29429,8 @@ The type of the child. If @samp{print object} If values were requested, this is the value. @item thread-id -If this variable object is associated with a thread, this is the thread id. -Otherwise this result is not present. +If this variable object is associated with a thread, this is the +thread's global thread id. Otherwise this result is not present. @item frozen If the variable object is frozen, this variable will be present with a value of 1. @@ -29566,6 +29871,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. @@ -29608,9 +29916,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 @@ -29636,12 +29955,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 @@ -30090,7 +30409,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 @@ -30099,18 +30418,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 @@ -30121,10 +30441,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, @@ -30184,17 +30504,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 @@ -33882,10 +34204,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 Processor Trace recording format, print a list of +Intel 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 @@ -34185,6 +34562,11 @@ 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 selftest +@cindex self tests +Run any self tests that were compiled in to @value{GDBN}. This will +print a message showing how many tests were run, and how many failed. + @kindex maint set dwarf always-disassemble @kindex maint show dwarf always-disassemble @item maint set dwarf always-disassemble @@ -34272,6 +34654,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 @@ -34829,8 +35235,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 @@ -34844,8 +35251,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 @@ -34853,9 +35260,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 @@ -35068,6 +35475,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, @@ -35169,7 +35594,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: @@ -35409,6 +35835,11 @@ The currently defined stop reasons are: The packet indicates a watchpoint hit, and @var{r} is the data address, in hex. +@item syscall_entry +@itemx syscall_return +The packet indicates a syscall entry or return, and @var{r} is the +syscall number, in hex. + @cindex shared library events, remote reply @item library The packet indicates that the loaded libraries have changed. @@ -35493,6 +35924,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} @@ -35514,6 +35966,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 @@ -35857,6 +36332,49 @@ by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). Use of this packet is controlled by the @code{set non-stop} command; @pxref{Non-Stop Mode}. +@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} +@itemx QCatchSyscalls:0 +@cindex catch syscalls from inferior, remote request +@cindex @samp{QCatchSyscalls} packet +@anchor{QCatchSyscalls} +Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0}) +catching syscalls from the inferior process. + +For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded +in hex) should be reported to @value{GDBN}. If no syscall @var{sysno} +is listed, every system call should be reported. + +Note that if a syscall not in the list is reported, @value{GDBN} will +still filter the event according to its own list from all corresponding +@code{catch syscall} commands. However, it is more efficient to only +report the requested syscalls. + +Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier +@samp{QCatchSyscalls:1} list is completely replaced by the new list. + +If the inferior process execs, the state of @samp{QCatchSyscalls} is +kept for the new process too. On targets where exec may affect syscall +numbers, for example with exec between 32 and 64-bit processes, the +client should send a new packet with the new syscall list. + +Reply: +@table @samp +@item OK +The request succeeded. + +@item E @var{nn} +An error occurred. @var{nn} are hex digits. + +@item @w{} +An empty reply indicates that @samp{QCatchSyscalls} is not supported by +the stub. +@end table + +Use of this packet is controlled by the @code{set remote catch-syscalls} +command (@pxref{Remote Configuration, set remote catch-syscalls}). +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + @item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} @cindex pass signals to inferior, remote request @cindex @samp{QPassSignals} packet @@ -35931,6 +36449,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 @@ -36097,6 +36648,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 @@ -36245,16 +36806,31 @@ 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{-} @tab Yes +@item @samp{QCatchSyscalls} +@tab No +@tab @samp{-} +@tab Yes + @item @samp{QPassSignals} @tab No @tab @samp{-} @@ -36350,6 +36926,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: @@ -36443,6 +37034,10 @@ packet (@pxref{qXfer fdpic loadmap read}). The remote stub understands the @samp{QNonStop} packet (@pxref{QNonStop}). +@item QCatchSyscalls +The remote stub understands the @samp{QCatchSyscalls} packet +(@pxref{QCatchSyscalls}). + @item QPassSignals The remote stub understands the @samp{QPassSignals} packet (@pxref{QPassSignals}). @@ -36531,9 +37126,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. @@ -36549,6 +37150,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:: @@ -36654,9 +37268,40 @@ starting at @var{offset} bytes into the data. The content and encoding of @var{annex} is specific to @var{object}; it can supply additional details about what data to access. -Here are the specific requests of this form defined so far. All +Reply: +@table @samp +@item m @var{data} +Data @var{data} (@pxref{Binary Data}) has been read from the +target. There may be more data at a higher address (although +it is permitted to return @samp{m} even for the last valid +block of data, as long as at least one byte of data was read). +It is possible for @var{data} to have fewer bytes than the @var{length} in the +request. + +@item l @var{data} +Data @var{data} (@pxref{Binary Data}) has been read from the target. +There is no more data to be read. It is possible for @var{data} to +have fewer bytes than the @var{length} in the request. + +@item l +The @var{offset} in the request is at the end of the data. +There is no more data to be read. + +@item E00 +The request was malformed, or @var{annex} was invalid. + +@item E @var{nn} +The offset was invalid, or there was an error encountered reading the data. +The @var{nn} part is a hex-encoded @code{errno} value. + +@item @w{} +An empty reply indicates the @var{object} string was not recognized by +the stub, or that the object does not support reading. +@end table + +Here are the specific requests of this form defined so far. All the @samp{qXfer:@var{object}:read:@dots{}} requests use the same reply -formats, listed below. +formats, listed above. @table @samp @item qXfer:auxv:read::@var{offset},@var{length} @@ -36861,50 +37506,37 @@ Access the target's @dfn{operating system information}. @end table +@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} +@cindex write data into object, remote request +@anchor{qXfer write} +Write uninterpreted bytes into the target's special data area +identified by the keyword @var{object}, starting at @var{offset} bytes +into the data. The binary-encoded data (@pxref{Binary Data}) to be +written is given by @var{data}@dots{}. The content and encoding of @var{annex} +is specific to @var{object}; it can supply additional details about what data +to access. + Reply: @table @samp -@item m @var{data} -Data @var{data} (@pxref{Binary Data}) has been read from the -target. There may be more data at a higher address (although -it is permitted to return @samp{m} even for the last valid -block of data, as long as at least one byte of data was read). -It is possible for @var{data} to have fewer bytes than the @var{length} in the -request. - -@item l @var{data} -Data @var{data} (@pxref{Binary Data}) has been read from the target. -There is no more data to be read. It is possible for @var{data} to -have fewer bytes than the @var{length} in the request. - -@item l -The @var{offset} in the request is at the end of the data. -There is no more data to be read. +@item @var{nn} +@var{nn} (hex encoded) is the number of bytes written. +This may be fewer bytes than supplied in the request. @item E00 The request was malformed, or @var{annex} was invalid. @item E @var{nn} -The offset was invalid, or there was an error encountered reading the data. +The offset was invalid, or there was an error encountered writing the data. The @var{nn} part is a hex-encoded @code{errno} value. @item @w{} -An empty reply indicates the @var{object} string was not recognized by -the stub, or that the object does not support reading. +An empty reply indicates the @var{object} string was not +recognized by the stub, or that the object does not support writing. @end table -@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} -@cindex write data into object, remote request -@anchor{qXfer write} -Write uninterpreted bytes into the target's special data area -identified by the keyword @var{object}, starting at @var{offset} bytes -into the data. The binary-encoded data (@pxref{Binary Data}) to be -written is given by @var{data}@dots{}. The content and encoding of @var{annex} -is specific to @var{object}; it can supply additional details about what data -to access. - -Here are the specific requests of this form defined so far. All +Here are the specific requests of this form defined so far. All the @samp{qXfer:@var{object}:write:@dots{}} requests use the same reply -formats, listed below. +formats, listed above. @table @samp @item qXfer:siginfo:write::@var{offset}:@var{data}@dots{} @@ -36929,24 +37561,6 @@ This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). @end table -Reply: -@table @samp -@item @var{nn} -@var{nn} (hex encoded) is the number of bytes written. -This may be fewer bytes than supplied in the request. - -@item E00 -The request was malformed, or @var{annex} was invalid. - -@item E @var{nn} -The offset was invalid, or there was an error encountered writing the data. -The @var{nn} part is a hex-encoded @code{errno} value. - -@item @w{} -An empty reply indicates the @var{object} string was not -recognized by the stub, or that the object does not support writing. -@end table - @item qXfer:@var{object}:@var{operation}:@dots{} Requests of this form may be added in the future. When a stub does not recognize the @var{object} keyword, or its support for @@ -36978,7 +37592,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 Processor Trace. Reply: @table @samp @@ -37011,6 +37636,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 @@ -37742,16 +38379,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 @@ -37772,6 +38424,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 @@ -37783,7 +38442,8 @@ reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result of successfully stopping the program in all-stop mode, and a stop reply for each stopped thread in non-stop mode. Interrupts received while the -program is stopped are discarded. +program is stopped are queued and the program will be interrupted when +it is resumed next time. @node Notification Packets @section Notification Packets @@ -39432,7 +40092,7 @@ the following structure: @smallexample - + ... description ... @@ -39441,8 +40101,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 @@ -39548,12 +40210,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 @@ -39574,6 +40248,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 Processor Trace} (@acronym{Intel +PT}) format. +@table @code +@item size +The size of the @acronym{Intel PT} ring buffer in bytes. +@end table @end table @value{GDBN} must be linked with the Expat library to support XML @@ -39582,11 +40263,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 @@ -39631,6 +40315,7 @@ target descriptions. @xref{Expat}. * Target Description Format:: The contents of a target description. * Predefined Target Types:: Standard types available for target descriptions. +* Enum Target Types:: How to define enum target types. * Standard Target Features:: Features @value{GDBN} knows about. @end menu @@ -39831,7 +40516,8 @@ Any register's value is a collection of bits which @value{GDBN} must interpret. The default interpretation is a two's complement integer, but other types can be requested by name in the register description. Some predefined types are provided by @value{GDBN} (@pxref{Predefined -Target Types}), and the description can define additional composite types. +Target Types}), and the description can define additional composite +and enum types. Each type element must have an @samp{id} attribute, which gives a unique (within the containing @samp{}) name to the type. @@ -39861,46 +40547,84 @@ each of which has a @var{name} and a @var{type}: @end smallexample @cindex +@cindex If a register's value is composed from several separate values, define -it with a structure type. There are two forms of the @samp{} -element; a @samp{} element must either contain only bitfields -or contain no bitfields. If the structure contains only bitfields, -its total size in bytes must be specified, each bitfield must have an -explicit start and end, and bitfields are automatically assigned an -integer type. The field's @var{start} should be less than or -equal to its @var{end}, and zero represents the least significant bit. +it with either a structure type or a flags type. +A flags type may only contain bitfields. +A structure type may either contain only bitfields or contain no bitfields. +If the value contains only bitfields, its total size in bytes must be +specified. + +Non-bitfield values have a @var{name} and @var{type}. @smallexample - - + + @dots{} @end smallexample -If the structure contains no bitfields, then each field has an -explicit type, and no implicit padding is added. +Both @var{name} and @var{type} values are required. +No implicit padding is added. + +Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}. @smallexample - - + + @dots{} @end smallexample -@cindex -If a register's value is a series of single-bit flags, define it with -a flags type. The @samp{} element has an explicit @var{size} -and contains one or more @samp{} elements. Each field has a -@var{name}, a @var{start}, and an @var{end}. Only single-bit flags -are supported. - @smallexample - + @dots{} @end smallexample +The @var{name} value is required. +Bitfield values may be named with the empty string, @samp{""}, +in which case the field is ``filler'' and its value is not printed. +Not all bits need to be specified, so ``filler'' fields are optional. + +The @var{start} value is required, and @var{end} and @var{type} +are optional. +The field's @var{start} must be less than or equal to its @var{end}, +and zero represents the least significant bit. +The default value of @var{end} is @var{start}, a single bit field. + +The default value of @var{type} depends on whether the +@var{end} was specified. If @var{end} is specified then the default +value of @var{type} is an unsigned integer. If @var{end} is unspecified +then the default value of @var{type} is @code{bool}. + +Which to choose? Structures or flags? + +Registers defined with @samp{flags} have these advantages over +defining them with @samp{struct}: + +@itemize @bullet +@item +Arithmetic may be performed on them as if they were integers. +@item +They are printed in a more readable fashion. +@end itemize + +Registers defined with @samp{struct} have one advantage over +defining them with @samp{flags}: + +@itemize @bullet +@item +One can fetch individual fields like in @samp{C}. + +@smallexample +(gdb) print $my_struct_reg.field3 +$1 = 42 +@end smallexample + +@end itemize + @subsection Registers @cindex @@ -39969,6 +40693,9 @@ types. The currently supported types are: @table @code +@item bool +Boolean type, occupying a single bit. + @item int8 @itemx int16 @itemx int32 @@ -40011,6 +40738,44 @@ The 10-byte extended precision format used by x87 registers. @end table +@node Enum Target Types +@section Enum Target Types +@cindex target descriptions, enum types + +Enum target types are useful in @samp{struct} and @samp{flags} +register descriptions. @xref{Target Description Format}. + +Enum types have a name, size and a list of name/value pairs. + +@smallexample + + + @dots{} + +@end smallexample + +Enums must be defined before they are used. + +@smallexample + + + + + + + + + +@end smallexample + +Given that description, a value of 3 for the @samp{flags} register +would be printed as: + +@smallexample +(gdb) info register flags +flags 0x3 [ X LEVEL=high ] +@end smallexample + @node Standard Target Features @section Standard Target Features @cindex target descriptions, standard features @@ -40052,6 +40817,7 @@ registers using the capitalization used in the description. * MicroBlaze Features:: * MIPS Features:: * M68K Features:: +* NDS32 Features:: * Nios II Features:: * PowerPC Features:: * S/390 and System z Features:: @@ -40153,7 +40919,7 @@ describe the upper 128 bits of @sc{ymm} registers: @samp{ymm0h} through @samp{ymm15h} for amd64 @end itemize -The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R) +The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel Memory Protection Extension (MPX). It should describe the following registers: @itemize @minus @@ -40260,6 +41026,28 @@ This feature is optional. If present, it should contain registers @samp{fpiaddr}. @end table +@node NDS32 Features +@subsection NDS32 Features +@cindex target descriptions, NDS32 features + +The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32 +targets. It should contain at least registers @samp{r0} through +@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp}, +and @samp{pc}. + +The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present, +it should contain 64-bit double-precision floating-point registers +@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7}, +@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented. + +@emph{Note:} The first sixteen 64-bit double-precision floating-point +registers are overlapped with the thirty-two 32-bit single-precision +floating-point registers. The 32-bit single-precision registers, if +not being listed explicitly, will be synthesized from halves of the +overlapping 64-bit double-precision registers. Listing 32-bit +single-precision registers explicitly is deprecated, and the +support to it could be totally removed some day. + @node Nios II Features @subsection Nios II Features @cindex target descriptions, Nios II features @@ -40428,7 +41216,38 @@ as tracepoint definitions or register set size. @value{GDBN} will ignore any line that it does not recognize. An empty line marks the end of this section. -@c FIXME add some specific types of data +@table @code +@item R @var{size} +Specifies the size of a register block in bytes. This is equal to the +size of a @code{g} packet payload in the remote protocol. @var{size} +is an ascii decimal number. There should be only one such line in +a single trace file. + +@item status @var{status} +Trace status. @var{status} has the same format as a @code{qTStatus} +remote packet reply. There should be only one such line in a single trace +file. + +@item tp @var{payload} +Tracepoint definition. The @var{payload} has the same format as +@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint +may take multiple lines of definition, corresponding to the multiple +reply packets. + +@item tsv @var{payload} +Trace state variable definition. The @var{payload} has the same format as +@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable +may take multiple lines of definition, corresponding to the multiple +reply packets. + +@item tdesc @var{payload} +Target description in XML format. The @var{payload} is a single line of +the XML file. All such lines should be concatenated together to get +the original XML file. This file is in the same format as @code{qXfer} +@code{features} payload, and corresponds to the main @code{target.xml} +file. Includes are not allowed. + +@end table The trace frame section consists of a number of consecutive frames. Each frame begins with a two-byte tracepoint number, followed by a @@ -40445,8 +41264,7 @@ endianness. @item R @var{bytes} Register block. The number and ordering of bytes matches that of a @code{g} packet in the remote protocol. Note that these are the -actual bytes, in target order and @value{GDBN} register order, not a -hexadecimal encoding. +actual bytes, in target order, not a hexadecimal encoding. @item M @var{address} @var{length} @var{bytes}... Memory block. This is a contiguous block of memory, at the 8-byte @@ -40784,7 +41602,7 @@ Here are some of the most frequently needed @value{GDBN} commands: @c pod2man highlights the right hand side of the @item lines. @table @env -@item break [@var{file}:]@var{functiop} +@item break [@var{file}:]@var{function} Set a breakpoint at @var{function} (in @var{file}). @item run [@var{arglist}]