X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=facca8f369d68e1ed9d93f135ee765baa5c794ea;hb=d6b289409bc58646f2a8ca2744e78fbee349497e;hp=31e90ab0e8e380ecffe08be5e3373159ccaa1f9c;hpb=68d41a48a46e2e92b76fc3e9c9dd5b657467a848;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 31e90ab0e8..facca8f369 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -18,13 +18,17 @@ @end iftex @finalout -@syncodeindex ky cp -@syncodeindex tp cp +@c To avoid file-name clashes between index.html and Index.html, when +@c the manual is produced on a Posix host and then moved to a +@c case-insensitive filesystem (e.g., MS-Windows), we separate the +@c indices into two: Concept Index and all the rest. +@syncodeindex ky fn +@syncodeindex tp fn @c readline appendices use @vindex, @findex and @ftable, @c annotate.texi and gdbmi use @findex. -@syncodeindex vr cp -@syncodeindex fn cp +@syncodeindex vr fn +@syncodeindex fn fn @c !!set GDB manual's edition---not the same as GDB version! @c This is updated by GNU Press. @@ -45,6 +49,7 @@ @copying Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +2011, 2012 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -114,7 +119,7 @@ This is the @value{EDITION} Edition, for @value{GDBN} @end ifset Version @value{GDBVN}. -Copyright (C) 1988-2010 Free Software Foundation, Inc. +Copyright (C) 1988-2012 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 @@ -181,7 +186,9 @@ software in general. We will miss him. * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation -* Index:: Index +* Concept Index:: Index of @value{GDBN} concepts +* Command and Variable Index:: Index of @value{GDBN} commands, variables, + functions, and Python data types @end menu @end ifnottex @@ -243,6 +250,7 @@ using either the Apple/NeXT or the GNU Objective-C runtime. @menu * Free Software:: Freely redistributable software +* Free Documentation:: Free Software Needs Free Documentation * Contributors:: Contributors to GDB @end menu @@ -262,6 +270,7 @@ Fundamentally, the General Public License is a license which says that you have these freedoms and that you cannot take these freedoms away from anyone else. +@node Free Documentation @unnumberedsec Free Software Needs Free Documentation The biggest deficiency in the free software community today is not in @@ -994,16 +1003,16 @@ also be interleaved with @samp{-command} as required. @itemx -ix @var{file} @cindex @code{--init-command} @cindex @code{-ix} -Execute commands from file @var{file} before loading gdbinit files or the -inferior. +Execute commands from file @var{file} before loading the inferior (but +after loading gdbinit files). @xref{Startup}. @item -init-eval-command @var{command} @itemx -iex @var{command} @cindex @code{--init-eval-command} @cindex @code{-iex} -Execute a single @value{GDBN} command before loading gdbinit files or the -inferior. +Execute a single @value{GDBN} command before loading the inferior (but +after loading gdbinit files). @xref{Startup}. @item -directory @var{directory} @@ -1238,13 +1247,6 @@ memory usage after it completes each command and returns to the prompt. This option causes @value{GDBN} to print its version number and no-warranty blurb, and exit. -@item -use-deprecated-index-sections -@cindex @code{--use-deprecated-index-sections} -This option causes @value{GDBN} to read and use deprecated -@samp{.gdb_index} sections from symbol files. This can speed up -startup, but may result in some functionality being lost. -@xref{Index Section Format}. - @end table @node Startup @@ -1258,14 +1260,6 @@ Here's the description of what @value{GDBN} does during session startup: Sets up the command interpreter as specified by the command line (@pxref{Mode Options, interpreter}). -@anchor{Option -init-eval-command} -@item -Executes commands and command files specified by the @samp{-iex} and -@samp{-ix} options in their specified order. Usually you should use the -@samp{-ex} and @samp{-x} options instead, but this way you can apply -settings before @value{GDBN} init files get executed and before inferior -gets loaded. - @item @cindex init file Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was @@ -1280,6 +1274,14 @@ DOS/Windows systems, the home directory is the one pointed to by the @code{HOME} environment variable.} and executes all the commands in that file. +@anchor{Option -init-eval-command} +@item +Executes commands and command files specified by the @samp{-iex} and +@samp{-ix} options in their specified order. Usually you should use the +@samp{-ex} and @samp{-x} options instead, but this way you can apply +settings before @value{GDBN} init files get executed and before inferior +gets loaded. + @item Processes command line options and operands. @@ -1777,8 +1779,9 @@ In addition to @code{help}, you can use the @value{GDBN} commands @code{info} and @code{show} to inquire about the state of your program, or the state of @value{GDBN} itself. Each command supports many topics of inquiry; this manual introduces each of them in the appropriate context. The listings -under @code{info} and under @code{show} in the Index point to -all the sub-commands. @xref{Index}. +under @code{info} and under @code{show} in the Command, Variable, and +Function Index point to all the sub-commands. @xref{Command and Variable +Index}. @c @group @table @code @@ -3341,7 +3344,9 @@ all breakpoints in that range are operated on. * Disabling:: Disabling breakpoints * Conditions:: Break conditions * Break Commands:: Breakpoint command lists +* Dynamic Printf:: Dynamic printf * Save Breakpoints:: How to save breakpoints in a file +* Static Probe Points:: Listing static probe points * Error in Breakpoints:: ``Cannot insert breakpoints'' * Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' @end menu @@ -4627,6 +4632,114 @@ cont end @end smallexample +@node Dynamic Printf +@subsection Dynamic Printf + +@cindex dynamic printf +@cindex dprintf +The dynamic printf command @code{dprintf} combines a breakpoint with +formatted printing of your program's data to give you the effect of +inserting @code{printf} calls into your program on-the-fly, without +having to recompile it. + +In its most basic form, the output goes to the GDB console. However, +you can set the variable @code{dprintf-style} for alternate handling. +For instance, you can ask to format the output by calling your +program's @code{printf} function. This has the advantage that the +characters go to the program's output device, so they can recorded in +redirects to files and so forth. + +If you are doing remote debugging with a stub or agent, you can also +ask to have the printf handled by the remote agent. In addition to +ensuring that the output goes to the remote program's device along +with any other output the program might produce, you can also ask that +the dprintf remain active even after disconnecting from the remote +target. Using the stub/agent is also more efficient, as it can do +everything without needing to communicate with @value{GDBN}. + +@table @code +@kindex dprintf +@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}] +Whenever execution reaches @var{location}, print the values of one or +more @var{expressions} under the control of the string @var{template}. +To print several values, separate them with commas. + +@item set dprintf-style @var{style} +Set the dprintf output to be handled in one of several different +styles enumerated below. A change of style affects all existing +dynamic printfs immediately. (If you need individual control over the +print commands, simply define normal breakpoints with +explicitly-supplied command lists.) + +@item gdb +@kindex dprintf-style gdb +Handle the output using the @value{GDBN} @code{printf} command. + +@item call +@kindex dprintf-style call +Handle the output by calling a function in your program (normally +@code{printf}). + +@item agent +@kindex dprintf-style agent +Have the remote debugging agent (such as @code{gdbserver}) handle +the output itself. This style is only available for agents that +support running commands on the target. + +@item set dprintf-function @var{function} +Set the function to call if the dprintf style is @code{call}. By +default its value is @code{printf}. You may set it to any expression. +that @value{GDBN} can evaluate to a function, as per the @code{call} +command. + +@item set dprintf-channel @var{channel} +Set a ``channel'' for dprintf. If set to a non-empty value, +@value{GDBN} will evaluate it as an expression and pass the result as +a first argument to the @code{dprintf-function}, in the manner of +@code{fprintf} and similar functions. Otherwise, the dprintf format +string will be the first argument, in the manner of @code{printf}. + +As an example, if you wanted @code{dprintf} output to go to a logfile +that is a standard I/O stream assigned to the variable @code{mylog}, +you could do the following: + +@example +(gdb) set dprintf-style call +(gdb) set dprintf-function fprintf +(gdb) set dprintf-channel mylog +(gdb) dprintf 25,"at line 25, glob=%d\n",glob +Dprintf 1 at 0x123456: file main.c, line 25. +(gdb) info break +1 dprintf keep y 0x00123456 in main at main.c:25 + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) + continue +(gdb) +@end example + +Note that the @code{info break} displays the dynamic printf commands +as normal breakpoint commands; you can thus easily see the effect of +the variable settings. + +@item set disconnected-dprintf on +@itemx set disconnected-dprintf off +@kindex set disconnected-dprintf +Choose whether @code{dprintf} commands should continue to run if +@value{GDBN} has disconnected from the target. This only applies +if the @code{dprintf-style} is @code{agent}. + +@item show disconnected-dprintf off +@kindex show disconnected-dprintf +Show the current choice for disconnected @code{dprintf}. + +@end table + +@value{GDBN} does not check the validity of function and channel, +relying on you to supply values that are meaningful for the contexts +in which they are being used. For instance, the function and channel +may be the values of local variables, but if that is the case, then +all enabled dynamic prints must be at locations within the scope of +those locals. If evaluation fails, @value{GDBN} will report an error. + @node Save Breakpoints @subsection How to save breakpoints to a file @@ -4652,6 +4765,69 @@ and remove the breakpoint definitions you're not interested in, or that can no longer be recreated. @end table +@node Static Probe Points +@subsection Static Probe Points + +@cindex static probe point, SystemTap +@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands +for Statically Defined Tracing, and the probes are designed to have a tiny +runtime code and data footprint, and no dynamic relocations. They are +usable from assembly, C and C@t{++} languages. See +@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} +for a good reference on how the @acronym{SDT} probes are implemented. + +Currently, @code{SystemTap} (@uref{http://sourceware.org/systemtap/}) +@acronym{SDT} probes are supported on ELF-compatible systems. See +@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps} +for more information on how to add @code{SystemTap} @acronym{SDT} probes +in your applications. + +@cindex semaphores on static probe points +Some probes have an associated semaphore variable; for instance, this +happens automatically if you defined your probe using a DTrace-style +@file{.d} file. If your probe has a semaphore, @value{GDBN} will +automatically enable it when you specify a breakpoint using the +@samp{-probe-stap} notation. But, if you put a breakpoint at a probe's +location by some other method (e.g., @code{break file:line}), then +@value{GDBN} will not automatically set the semaphore. + +You can examine the available static static probes using @code{info +probes}, with optional arguments: + +@table @code +@kindex info probes +@item info probes stap @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} +If given, @var{provider} is a regular expression used to match against provider +names when selecting which probes to list. If omitted, probes by all +probes from all providers are listed. + +If given, @var{name} is a regular expression to match against probe names +when selecting which probes to list. If omitted, probe names are not +considered when deciding whether to display them. + +If given, @var{objfile} is a regular expression used to select which +object files (executable or shared libraries) to examine. If not +given, all object files are considered. + +@item info probes all +List the available static probes, from all types. +@end table + +@vindex $_probe_arg@r{, convenience variable} +A probe may specify up to twelve arguments. These are available at the +point at which the probe is defined---that is, when the current PC is +at the probe's location. The arguments are available using the +convenience variables (@pxref{Convenience Vars}) +@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. Each probe argument is +an integer of the appropriate size; types are not preserved. The +convenience variable @code{$_probe_argc} holds the number of arguments +at the current probe point. + +These variables are always available, but attempts to access them at +any location other than a probe point will cause @value{GDBN} to give +an error message. + + @c @ifclear BARETARGET @node Error in Breakpoints @subsection ``Cannot insert breakpoints'' @@ -4809,7 +4985,7 @@ called within the line. Also, the @code{step} command only enters a function if there is line number information for the function. Otherwise it acts like the @code{next} command. This avoids problems when using @code{cc -gl} -on MIPS machines. Previously, @code{step} entered subroutines if there +on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there was any debugging information about the routine. @item step @var{count} @@ -4945,7 +5121,7 @@ invocations have returned. @kindex advance @var{location} -@itemx advance @var{location} +@item advance @var{location} Continue running the program up to the given @var{location}. An argument is required, which should be of one of the forms described in @ref{Specify Location}. @@ -5840,7 +6016,7 @@ function invocation, you end up at the beginning. @kindex set exec-direction @item set exec-direction Set the direction of target execution. -@itemx set exec-direction reverse +@item set exec-direction reverse @cindex execute forward or backward in time @value{GDBN} will perform all execution commands in reverse, until the exec-direction mode is changed to ``forward''. Affected commands include @@ -6341,7 +6517,7 @@ 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 MIPS and Alpha architecture, it needs two addresses: a stack +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 @@ -6667,6 +6843,19 @@ 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 @@ -8274,6 +8463,24 @@ does not show the symbol name and filename of the referent, even with the appropriate @code{set print} options turned on. @end quotation +You can also enable @samp{/a}-like formatting all the time using +@samp{set print symbol on}: + +@table @code +@item set print symbol on +Tell @value{GDBN} to print the symbol corresponding to an address, if +one exists. + +@item set print symbol off +Tell @value{GDBN} not to print the symbol corresponding to an +address. In this mode, @value{GDBN} will still print the symbol +corresponding to pointers to functions. This is the default. + +@item show print symbol +Show whether @value{GDBN} will display the symbol corresponding to an +address. +@end table + Other settings control how different kinds of objects are printed: @table @code @@ -9071,6 +9278,10 @@ to match the format in which the data was printed. The variable @code{$_exitcode} is automatically set to the exit code when the program being debugged terminates. +@item $_probe_argc +@itemx $_probe_arg0@dots{}$_probe_arg11 +Arguments to a static probe. @xref{Static Probe Points}. + @item $_sdata @vindex $_sdata@r{, inspect, convenience variable} The variable @code{$_sdata} contains extra collected static tracepoint @@ -9328,23 +9539,109 @@ most appropriate form for a recognized tag, and in hexadecimal for an unrecognized tag. @end table -On some targets, @value{GDBN} can access operating-system-specific information -and display it to user, without interpretation. For remote targets, -this functionality depends on the remote stub's support of the +On some targets, @value{GDBN} can access operating system-specific +information and show it to you. The types of information available +will differ depending on the type of operating system running on the +target. The mechanism used to fetch the data is described in +@ref{Operating System Information}. For remote targets, this +functionality depends on the remote stub's support of the @samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. @table @code @kindex info os -@item info os -List the types of OS information available for the target. If the -target does not return a list of possible types, this command will -report an error. +@item info os @var{infotype} +Display OS information of the requested type. + +On @sc{gnu}/Linux, the following values of @var{infotype} are valid: + +@anchor{linux info os infotypes} +@table @code @kindex info os processes -@item info os processes +@item processes Display the list of processes on the target. For each process, -@value{GDBN} prints the process identifier, the name of the user, and -the command corresponding to the process. +@value{GDBN} prints the process identifier, the name of the user, the +command corresponding to the process, and the list of processor cores +that the process is currently running on. (To understand what these +properties mean, for this and the following info types, please consult +the general @sc{gnu}/Linux documentation.) + +@kindex info os procgroups +@item procgroups +Display the list of process groups on the target. For each process, +@value{GDBN} prints the identifier of the process group that it belongs +to, the command corresponding to the process group leader, the process +identifier, and the command line of the process. The list is sorted +first by the process group identifier, then by the process identifier, +so that processes belonging to the same process group are grouped together +and the process group leader is listed first. + +@kindex info os threads +@item threads +Display the list of threads running on the target. For each thread, +@value{GDBN} prints the identifier of the process that the thread +belongs to, the command of the process, the thread identifier, and the +processor core that it is currently running on. The main thread of a +process is not listed. + +@kindex info os files +@item files +Display the list of open file descriptors on the target. For each +file descriptor, @value{GDBN} prints the identifier of the process +owning the descriptor, the command of the owning process, the value +of the descriptor, and the target of the descriptor. + +@kindex info os sockets +@item sockets +Display the list of Internet-domain sockets on the target. For each +socket, @value{GDBN} prints the address and port of the local and +remote endpoints, the current state of the connection, the creator of +the socket, the IP address family of the socket, and the type of the +connection. + +@kindex info os shm +@item shm +Display the list of all System V shared-memory regions on the target. +For each shared-memory region, @value{GDBN} prints the region key, +the shared-memory identifier, the access permissions, the size of the +region, the process that created the region, the process that last +attached to or detached from the region, the current number of live +attaches to the region, and the times at which the region was last +attached to, detach from, and changed. + +@kindex info os semaphores +@item semaphores +Display the list of all System V semaphore sets on the target. For each +semaphore set, @value{GDBN} prints the semaphore set key, the semaphore +set identifier, the access permissions, the number of semaphores in the +set, the user and group of the owner and creator of the semaphore set, +and the times at which the semaphore set was operated upon and changed. + +@kindex info os msg +@item msg +Display the list of all System V message queues on the target. For each +message queue, @value{GDBN} prints the message queue key, the message +queue identifier, the access permissions, the current number of bytes +on the queue, the current number of messages on the queue, the processes +that last sent and received a message on the queue, the user and group +of the owner and creator of the message queue, the times at which a +message was last sent and received on the queue, and the time at which +the message queue was last changed. + +@kindex info os modules +@item modules +Display the list of all loaded kernel modules on the target. For each +module, @value{GDBN} prints the module name, the size of the module in +bytes, the number of times the module is used, the dependencies of the +module, the status of the module, and the address of the loaded module +in memory. +@end table + +@item info os +If @var{infotype} is omitted, then list the possible values for +@var{infotype} and the kind of OS information available for each +@var{infotype}. If the target does not return a list of possible +types, this command will report an error. @end table @node Memory Region Attributes @@ -11015,6 +11312,16 @@ Collect all local variables. Collect the return address. This is helpful if you want to see more of a backtrace. +@item $_probe_argc +Collects the number of arguments from the static probe at which the +tracepoint is located. +@xref{Static Probe Points}. + +@item $_probe_arg@var{n} +@var{n} is an integer between 0 and 11. Collects the @var{n}th argument +from the static probe at which the tracepoint is located. +@xref{Static Probe Points}. + @item $_sdata @vindex $_sdata@r{, collect} Collect static tracepoint marker specific data. Only available for @@ -12487,8 +12794,8 @@ being set automatically by @value{GDBN}. @node Supported Languages @section Supported Languages -@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, OpenCL C, Pascal, -assembly, Modula-2, and Ada. +@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, Java, +OpenCL C, Pascal, 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, @@ -12507,6 +12814,7 @@ language reference or tutorial. @menu * C:: C and C@t{++} * D:: D +* Go:: Go * Objective-C:: Objective-C * OpenCL C:: OpenCL C * Fortran:: Fortran @@ -13059,6 +13367,55 @@ See @ref{PowerPC,,PowerPC} for more details. GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D specific feature --- dynamic arrays. +@node Go +@subsection Go + +@cindex Go (programming language) +@value{GDBN} can be used to debug programs written in Go and compiled with +@file{gccgo} or @file{6g} compilers. + +Here is a summary of the Go-specific features and restrictions: + +@table @code +@cindex current Go package +@item The current Go package +The name of the current package does not need to be specified when +specifying global variables and functions. + +For example, given the program: + +@example +package main +var myglob = "Shall we?" +func main () @{ + // ... +@} +@end example + +When stopped inside @code{main} either of these work: + +@example +(gdb) p myglob +(gdb) p main.myglob +@end example + +@cindex builtin Go types +@item Builtin Go types +The @code{string} type is recognized by @value{GDBN} and is printed +as a string. + +@cindex builtin Go functions +@item Builtin Go functions +The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof} +function and handles it internally. + +@cindex restrictions on Go expressions +@item Restrictions on Go expressions +All Go operators are supported except @code{&^}. +The Go @code{_} ``blank identifier'' is not supported. +Automatic dereferencing of pointers is not supported. +@end table + @node Objective-C @subsection Objective-C @@ -16060,7 +16417,7 @@ Show whether a source file may have multiple base names. @cindex debugging information in separate files @cindex @file{.debug} subdirectories @cindex debugging information directory, global -@cindex global debugging information directory +@cindex global debugging information directories @cindex build ID, and separate debugging files @cindex @file{.build-id} directory @@ -16105,14 +16462,14 @@ uses two different methods of looking for the debug file: @item For the ``debug link'' method, @value{GDBN} looks up the named file in the directory of the executable file, then in a subdirectory of that -directory named @file{.debug}, and finally under the global debug -directory, in a subdirectory whose name is identical to the leading +directory named @file{.debug}, and finally under each one of the global debug +directories, in a subdirectory whose name is identical to the leading directories of the executable's absolute file name. @item For the ``build ID'' method, @value{GDBN} looks in the -@file{.build-id} subdirectory of the global debug directory for a file -named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the +@file{.build-id} subdirectory of each one of the global debug directories for +a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} are the rest of the bit string. (Real build ID strings are 32 or more hex characters, not 10.) @@ -16121,7 +16478,7 @@ hex characters, not 10.) So, for example, suppose you ask @value{GDBN} to debug @file{/usr/bin/ls}, which has a debug link that specifies the file @file{ls.debug}, and a build ID whose value in hex is -@code{abcdef1234}. If the global debug directory is +@code{abcdef1234}. If the list of the global debug directories includes @file{/usr/lib/debug}, then @value{GDBN} will look for the following debug information files, in the indicated order: @@ -16136,16 +16493,19 @@ debug information files, in the indicated order: @file{/usr/lib/debug/usr/bin/ls.debug}. @end itemize -You can set the global debugging info directory's name, and view the -name @value{GDBN} is currently using. +@anchor{debug-file-directory} +Global debugging info directories default to what is set by @value{GDBN} +configure option @option{--with-separate-debug-dir}. During @value{GDBN} run +you can also set the global debugging info directories, and view the list +@value{GDBN} is currently using. @table @code @kindex set debug-file-directory @item set debug-file-directory @var{directories} Set the directories which @value{GDBN} searches for separate debugging -information files to @var{directory}. Multiple directory components can be set -concatenating them by a directory separator. +information files to @var{directory}. Multiple path components can be set +concatenating them by a path separator. @kindex show debug-file-directory @item show debug-file-directory @@ -16386,6 +16746,28 @@ $ objcopy --add-section .gdb_index=symfile.gdb-index \ --set-section-flags .gdb_index=readonly symfile symfile @end smallexample +@value{GDBN} will normally ignore older versions of @file{.gdb_index} +sections that have been deprecated. Usually they are deprecated because +they are missing a new feature or have performance issues. +To tell @value{GDBN} to use a deprecated index section anyway +specify @code{set use-deprecated-index-sections on}. +The default is @code{off}. +This can speed up startup, but may result in some functionality being lost. +@xref{Index Section Format}. + +@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on} +must be done before gdb reads the file. The following will not work: + +@smallexample +$ gdb -ex "set use-deprecated-index-sections on" +@end smallexample + +Instead you must do, for example, + +@smallexample +$ gdb -iex "set use-deprecated-index-sections on" +@end smallexample + There are currently some limitation on indices. They only work when for DWARF debugging information, not stabs. And, they do not currently work for programs using Ada. @@ -16761,7 +17143,7 @@ load programs into flash memory. @cindex choosing target byte order @cindex target byte order -Some types of processors, such as the MIPS, PowerPC, and Renesas SH, +Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH, offer the ability to run either big-endian or little-endian byte orders. Usually the executable or symbol will include a bit to designate the endian-ness, and you will not need to worry about @@ -19121,8 +19503,8 @@ acceptable commands. * MicroBlaze:: Xilinx MicroBlaze * MIPS Embedded:: MIPS Embedded * OpenRISC 1000:: OpenRisc 1000 -* PA:: HP PA Embedded * PowerPC Embedded:: PowerPC Embedded +* PA:: HP PA Embedded * Sparclet:: Tsqware Sparclet * Sparclite:: Fujitsu Sparclite * Z8000:: Zilog Z8000 @@ -19428,11 +19810,11 @@ Show MicroBlaze-specific debugging level. @end table @node MIPS Embedded -@subsection MIPS Embedded +@subsection @acronym{MIPS} Embedded -@cindex MIPS boards -@value{GDBN} can use the MIPS remote debugging protocol to talk to a -MIPS board attached to a serial line. This is available when +@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 @@ -19490,7 +19872,7 @@ Array Tech LSI33K RAID controller board. @noindent -@value{GDBN} also supports these special commands for MIPS targets: +@value{GDBN} also supports these special commands for @acronym{MIPS} targets: @table @code @item set mipsfpu double @@ -19500,9 +19882,9 @@ Array Tech LSI33K RAID controller board. @itemx show mipsfpu @kindex set mipsfpu @kindex show mipsfpu -@cindex MIPS remote floating point -@cindex floating point, MIPS remote -If your target board does not support the MIPS floating point +@cindex @acronym{MIPS} remote floating point +@cindex floating point, @acronym{MIPS} remote +If your target board does not support the @acronym{MIPS} floating point coprocessor, you should use the command @samp{set mipsfpu none} (if you need this, you may wish to put the command in your @value{GDBN} init file). This tells @value{GDBN} how to find the return value of @@ -19525,13 +19907,13 @@ As usual, you can inquire about the @code{mipsfpu} variable with @itemx set retransmit-timeout @var{seconds} @itemx show timeout @itemx show retransmit-timeout -@cindex @code{timeout}, MIPS protocol -@cindex @code{retransmit-timeout}, MIPS protocol +@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 MIPS +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 @@ -19546,19 +19928,19 @@ 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{, MIPS remote} -@cindex synchronize with remote MIPS target +@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{, MIPS remote} +@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{, MIPS remote} +@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: @@ -19572,23 +19954,23 @@ remote monitor. The default depends on the target: @end table @item show monitor-prompt -@kindex show monitor-prompt@r{, MIPS remote} +@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{, MIPS remote} +@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{, MIPS remote} +@kindex show monitor-warnings@r{, @acronym{MIPS} remote} Show the current setting of printing monitor warnings. @item pmon @var{command} -@kindex pmon@r{, MIPS remote} +@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. @@ -20111,6 +20493,9 @@ commands: @table @code @item regs @kindex regs@r{, Super-H} +This command is deprecated, and @code{info all-registers} should be +used instead. + Show the values of all Super-H registers. @item set sh calling-convention @var{convention} @@ -20141,7 +20526,6 @@ all uses of @value{GDBN} with the architecture, both native and cross. @menu * i386:: -* A29K:: * Alpha:: * MIPS:: * HPPA:: HP PA architecture @@ -20171,56 +20555,30 @@ Show the current setting of the convention to return @code{struct}s from functions. @end table -@node A29K -@subsection A29K - -@table @code - -@kindex set rstack_high_address -@cindex AMD 29K register stack -@cindex register stack, AMD29K -@item set rstack_high_address @var{address} -On AMD 29000 family processors, registers are saved in a separate -@dfn{register stack}. There is no way for @value{GDBN} to determine the -extent of this stack. Normally, @value{GDBN} just assumes that the -stack is ``large enough''. This may result in @value{GDBN} referencing -memory locations that do not exist. If necessary, you can get around -this problem by specifying the ending address of the register stack with -the @code{set rstack_high_address} command. The argument should be an -address, which you probably want to precede with @samp{0x} to specify in -hexadecimal. - -@kindex show rstack_high_address -@item show rstack_high_address -Display the current limit of the register stack, on AMD 29000 family -processors. - -@end table - @node Alpha @subsection Alpha See the following section. @node MIPS -@subsection MIPS +@subsection @acronym{MIPS} @cindex stack on Alpha -@cindex stack on MIPS +@cindex stack on @acronym{MIPS} @cindex Alpha stack -@cindex MIPS stack -Alpha- and MIPS-based computers use an unusual stack frame, which +@cindex @acronym{MIPS} stack +Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which sometimes requires @value{GDBN} to search backward in the object code to find the beginning of a function. -@cindex response time, MIPS debugging +@cindex response time, @acronym{MIPS} debugging To improve response time (especially for embedded applications, where @value{GDBN} may be restricted to a slow serial line for this search) you may want to limit the size of this search, using one of these commands: @table @code -@cindex @code{heuristic-fence-post} (Alpha, MIPS) +@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS}) @item set heuristic-fence-post @var{limit} Restrict @value{GDBN} to examining at most @var{limit} bytes in its search for the beginning of a function. A value of @var{0} (the @@ -20235,16 +20593,16 @@ Display the current limit. @noindent These commands are available @emph{only} when @value{GDBN} is configured -for debugging programs on Alpha or MIPS processors. +for debugging programs on Alpha or @acronym{MIPS} processors. -Several MIPS-specific commands are available when debugging MIPS +Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS} programs: @table @code @item set mips abi @var{arg} @kindex set mips abi -@cindex set ABI for MIPS -Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible +@cindex set ABI for @acronym{MIPS} +Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible values of @var{arg} are: @table @samp @@ -20261,7 +20619,39 @@ default). @item show mips abi @kindex show mips abi -Show the MIPS ABI used by @value{GDBN} to debug the inferior. +Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior. + +@item set mips compression @var{arg} +@kindex set mips compression +@cindex code compression, @acronym{MIPS} +Tell @value{GDBN} which @acronym{MIPS} compressed +@acronym{ISA, Instruction Set Architecture} encoding is used by the +inferior. @value{GDBN} uses this for code disassembly and other +internal interpretation purposes. This setting is only referred to +when no executable has been associated with the debugging session or +the executable does not provide information about the encoding it uses. +Otherwise this setting is automatically updated from information +provided by the executable. + +Possible values of @var{arg} are @samp{mips16} and @samp{micromips}. +The default compressed @acronym{ISA} encoding is @samp{mips16}, as +executables containing @acronym{MIPS16} code frequently are not +identified as such. + +This setting is ``sticky''; that is, it retains its value across +debugging sessions until reset either explicitly with this command or +implicitly from an executable. + +The compiler and/or assembler typically add symbol table annotations to +identify functions compiled for the @acronym{MIPS16} or +@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations +are present, @value{GDBN} uses them in preference to the global +compressed @acronym{ISA} encoding setting. + +@item show mips compression +@kindex show mips compression +Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by +@value{GDBN} to debug the inferior. @item set mipsfpu @itemx show mipsfpu @@ -20269,36 +20659,36 @@ Show the MIPS ABI used by @value{GDBN} to debug the inferior. @item set mips mask-address @var{arg} @kindex set mips mask-address -@cindex MIPS addresses, masking +@cindex @acronym{MIPS} addresses, masking This command determines whether the most-significant 32 bits of 64-bit -MIPS addresses are masked off. The argument @var{arg} can be +@acronym{MIPS} addresses are masked off. The argument @var{arg} can be @samp{on}, @samp{off}, or @samp{auto}. The latter is the default setting, which lets @value{GDBN} determine the correct value. @item show mips mask-address @kindex show mips mask-address -Show whether the upper 32 bits of MIPS addresses are masked off or +Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or not. @item set remote-mips64-transfers-32bit-regs @kindex set remote-mips64-transfers-32bit-regs -This command controls compatibility with 64-bit MIPS targets that -transfer data in 32-bit quantities. If you have an old MIPS 64 target +This command controls compatibility with 64-bit @acronym{MIPS} targets that +transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, and 64 bits for other registers, set this option to @samp{on}. @item show remote-mips64-transfers-32bit-regs @kindex show remote-mips64-transfers-32bit-regs -Show the current setting of compatibility with older MIPS 64 targets. +Show the current setting of compatibility with older @acronym{MIPS} 64 targets. @item set debug mips @kindex set debug mips -This command turns on and off debugging messages for the MIPS-specific +This command turns on and off debugging messages for the @acronym{MIPS}-specific target code in @value{GDBN}. @item show debug mips @kindex show debug mips -Show the current setting of MIPS debugging messages. +Show the current setting of @acronym{MIPS} debugging messages. @end table @@ -20859,6 +21249,10 @@ without being explicitly told so by the user. We call this feature results or introduce security risks (e.g., if the file comes from untrusted sources). +Note that loading of these associated files (including the local @file{.gdbinit} +file) requires accordingly configured @code{auto-load safe-path} +(@pxref{Auto-loading safe path}). + For these reasons, @value{GDBN} includes commands and options to let you control when to auto-load files and which files should be auto-loaded. @@ -20890,10 +21284,13 @@ or disabled. (gdb) show auto-load gdb-scripts: Auto-loading of canned sequences of commands scripts is on. libthread-db: Auto-loading of inferior specific libthread_db is on. -local-gdbinit: Auto-loading of .gdbinit script from current directory is on. +local-gdbinit: Auto-loading of .gdbinit script from current directory + is on. python-scripts: Auto-loading of Python scripts is on. safe-path: List of directories from which it is safe to auto-load files - is /usr/local. + is $debugdir:$datadir/auto-load. +scripts-directory: List of directories from which to load auto-loaded scripts + is $debugdir:$datadir/auto-load. @end smallexample @anchor{info auto-load} @@ -20908,7 +21305,8 @@ gdb-scripts: Loaded Script Yes /home/user/gdb/gdb-gdb.gdb libthread-db: No auto-loaded libthread-db. -local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been loaded. +local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been + loaded. python-scripts: Loaded Script Yes /home/user/gdb/gdb-gdb.py @@ -20953,6 +21351,10 @@ These are @value{GDBN} control commands for the auto-loading: @tab Show setting of @value{GDBN} Python scripts. @item @xref{info auto-load python-scripts}. @tab Show state of @value{GDBN} Python scripts. +@item @xref{set auto-load scripts-directory}. +@tab Control for @value{GDBN} auto-loaded scripts location. +@item @xref{show auto-load scripts-directory}. +@tab Show @value{GDBN} auto-loaded scripts location. @item @xref{set auto-load local-gdbinit}. @tab Control for init file in the current directory. @item @xref{show auto-load local-gdbinit}. @@ -20990,6 +21392,9 @@ By default, @value{GDBN} reads and executes the canned sequences of commands from init file (if any) in the current working directory, see @ref{Init File in the Current Directory during Startup}. +Note that loading of this local @file{.gdbinit} file also requires accordingly +configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). + @table @code @anchor{set auto-load local-gdbinit} @kindex set auto-load local-gdbinit @@ -21026,6 +21431,9 @@ libraries have to be trusted in general. In all other cases of auto-load libthread-db} is enabled before trying to open such thread debugging library. +Note that loading of this debugging library also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + @table @code @anchor{set auto-load libthread-db} @kindex set auto-load libthread-db @@ -21053,6 +21461,9 @@ for each such library print list of inferior @var{pid}s using it. canned sequences of commands (@pxref{Sequences}), as long as @samp{set auto-load gdb-scripts} is set to @samp{on}. +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + For more background refer to the similar Python scripts auto-loading description (@pxref{objfile-gdb.py file}). @@ -21087,6 +21498,7 @@ As the files of inferior can come from untrusted source (such as submitted by an application user) @value{GDBN} does not always load any files automatically. @value{GDBN} provides the @samp{set auto-load safe-path} setting to list directories trusted for loading files not explicitly requested by user. +Each directory can also be a shell wildcard pattern. If the path is not set properly you will see a warning and the file will not get loaded: @@ -21095,9 +21507,11 @@ get loaded: $ ./gdb -q ./gdb Reading symbols from /home/user/gdb/gdb...done. warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been - declined by your `auto-load safe-path' set to "/usr/local". + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been - declined by your `auto-load safe-path' set to "/usr/local". + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". @end smallexample The list of trusted directories is controlled by the following commands: @@ -21105,10 +21519,16 @@ The list of trusted directories is controlled by the following commands: @table @code @anchor{set auto-load safe-path} @kindex set auto-load safe-path -@item set auto-load safe-path @var{directories} +@item set auto-load safe-path @r{[}@var{directories}@r{]} Set the list of directories (and their subdirectories) trusted for automatic loading and execution of scripts. You can also enter a specific trusted file. -The list of directories uses directory separator (@samp{:} on GNU and Unix +Each directory can also be a shell wildcard pattern; wildcards do not match +directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch} +(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}). +If you omit @var{directories}, @samp{auto-load safe-path} will be reset to +its default value as specified during @value{GDBN} compilation. + +The list of directories uses path separator (@samp{:} on GNU and Unix systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly to the @env{PATH} environment variable. @@ -21123,10 +21543,18 @@ scripts. @item add-auto-load-safe-path Add an entry (or list of entries) the list of directories trusted for automatic loading and execution of scripts. Multiple entries may be delimited by the -host platform directory separator in use. +host platform path separator in use. @end table -Setting this variable to an empty string disables this security protection. +This variable defaults to what @code{--with-auto-load-dir} has been configured +to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir} +substitution applies the same as for @ref{set auto-load scripts-directory}. +The default @code{set auto-load safe-path} value can be also overriden by +@value{GDBN} configuration option @option{--with-auto-load-safe-path}. + +Setting this variable to @file{/} disables this security protection, +corresponding @value{GDBN} configuration option is +@option{--without-auto-load-safe-path}. This variable is supposed to be set to the system directories writable by the system superuser only. Users can add their source directories in init files in their home directories (@pxref{Home Directory Init File}). See also deprecated @@ -21142,11 +21570,11 @@ Specify this trusted directory (or a file) as additional component of the list. You have to specify also any existing directories displayed by by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example). -@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb"} +@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}} Specify this directory as in the previous case but just for a single @value{GDBN} session. -@item @kbd{gdb -iex "set auto-load safe-path"} +@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}} Disable auto-loading safety for a single @value{GDBN} session. This assumes all the files you debug during this @value{GDBN} session will come from trusted sources. @@ -21161,7 +21589,7 @@ On the other hand you can also explicitly forbid automatic files loading which also suppresses any such warning messages: @table @asis -@item @kbd{gdb -iex "set auto-load no"} +@item @kbd{gdb -iex "set auto-load no" @dots{}} You can use @value{GDBN} command-line option for a single @value{GDBN} session. @item @file{~/.gdbinit}: @samp{set auto-load no} @@ -21364,6 +21792,12 @@ The value is the number of nesting levels to print. A value of zero turns off the display. @item show debug dwarf2-die Show the current state of DWARF2 DIE debugging. +@item set debug dwarf2-read +@cindex DWARF2 Reading +Turns on or off display of debugging messages related to reading +DWARF debug info. The default is off. +@item show debug dwarf2-read +Show the current state of DWARF2 reader debugging. @item set debug displaced @cindex displaced stepping debugging info Turns on or off display of @value{GDBN} debugging info for the @@ -21461,6 +21895,12 @@ Turns 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. +@item set debug symtab-create +@cindex symbol table creation +Turns on or off display of debugging messages related to symbol table creation. +The default is off. +@item show debug symtab-create +Show the current state of symbol table creation debugging. @item set debug target @cindex target debugging info Turns on or off display of @value{GDBN} target debugging info. This info @@ -22187,10 +22627,10 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Blocks In Python:: Accessing frame blocks from Python. * Symbols In Python:: Python representation of symbols. * Symbol Tables In Python:: Python representation of symbol tables. -* Lazy Strings In Python:: Python representation of lazy strings. * Breakpoints In Python:: Manipulating breakpoints using Python. * Finish Breakpoints in Python:: Setting Breakpoints on function return using Python. +* Lazy Strings In Python:: Python representation of lazy strings. @end menu @node Basic Python @@ -22275,6 +22715,15 @@ compute values, for example, it is the only way to get the value of a convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}. @end defun +@findex gdb.find_pc_line +@defun gdb.find_pc_line (pc) +Return the @code{gdb.Symtab_and_line} object corresponding to the +@var{pc} value. @xref{Symbol Tables In Python}. If an invalid +value of @var{pc} is passed as an argument, then the @code{symtab} and +@code{line} attributes of the returned @code{gdb.Symtab_and_line} object +will be @code{None} and 0 respectively. +@end defun + @findex gdb.post_event @defun gdb.post_event (event) Put @var{event}, a callable object taking no arguments, into @@ -23504,20 +23953,20 @@ when it is called. If there are no valid threads, the method will return an empty tuple. @end defun -@findex gdb.read_memory +@findex Inferior.read_memory @defun Inferior.read_memory (address, length) Read @var{length} bytes of memory from the inferior, starting at @var{address}. Returns a buffer object, which behaves much like an array -or a string. It can be modified and given to the @code{gdb.write_memory} -function. +or a string. It can be modified and given to the +@code{Inferior.write_memory} function. @end defun -@findex gdb.write_memory +@findex Inferior.write_memory @defun Inferior.write_memory (address, buffer @r{[}, length@r{]}) Write the contents of @var{buffer} to the inferior, starting at @var{address}. The @var{buffer} parameter must be a Python object which supports the buffer protocol, i.e., a string, an array or the -object returned from @code{gdb.read_memory}. If given, @var{length} +object returned from @code{Inferior.read_memory}. If given, @var{length} determines the number of bytes from @var{buffer} to be written. @end defun @@ -24530,7 +24979,11 @@ detailed technical information on @value{GDBN}'s book-keeping of the stack. A @code{gdb.Block} is iterable. The iterator returns the symbols -(@pxref{Symbols In Python}) local to the block. +(@pxref{Symbols In Python}) local to the block. Python programs +should not assume that a specific block object will always contain a +given symbol, since changes in @value{GDBN} features and +infrastructure may cause symbols move across blocks in a symbol +table. The following block-related functions are available in the @code{gdb} module: @@ -24870,8 +25323,13 @@ This attribute is not writable. @end defvar @defvar Symtab_and_line.pc -Indicates the current program counter address. This attribute is not -writable. +Indicates the start of the address range occupied by code for the +current source line. This attribute is not writable. +@end defvar + +@defvar Symtab_and_line.last +Indicates the end of the address range occupied by code for the current +source line. This attribute is not writable. @end defvar @defvar Symtab_and_line.line @@ -24920,6 +25378,16 @@ if it is invalid at the time the method is called. @defun Symtab.fullname () Return the symbol table's source absolute file name. @end defun + +@defun Symtab.global_block () +Return the global block of the underlying symbol table. +@xref{Blocks In Python}. +@end defun + +@defun Symtab.static_block () +Return the static block of the underlying symbol table. +@xref{Blocks In Python}. +@end defun @end table @node Breakpoints In Python @@ -25305,22 +25773,51 @@ registering objfile-specific pretty-printers. @cindex @file{@var{objfile}-gdb.py} When a new object file is read, @value{GDBN} looks for -a file named @file{@var{objfile}-gdb.py}, +a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below), where @var{objfile} is the object file's real name, formed by ensuring that the file name is absolute, following all symlinks, and resolving @code{.} and @code{..} components. If this file exists and is readable, @value{GDBN} will evaluate it as a Python script. -If this file does not exist, and if the parameter -@code{debug-file-directory} is set (@pxref{Separate Debug Files}), -then @value{GDBN} will look for @var{real-name} in all of the -directories mentioned in the value of @code{debug-file-directory}. +If this file does not exist, then @value{GDBN} will look for +@var{script-name} file in all of the directories as specified below. + +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +@table @code +@anchor{set auto-load scripts-directory} +@kindex set auto-load scripts-directory +@item set auto-load scripts-directory @r{[}@var{directories}@r{]} +Control @value{GDBN} auto-loaded scripts location. Multiple directory entries +may be delimited by the host platform path separator in use +(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). + +Each entry here needs to be covered also by the security setting +@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). + +@anchor{with-auto-load-dir} +This variable defaults to @file{$debugdir:$datadir/auto-load}. The default +@code{set auto-load safe-path} value can be also overriden by @value{GDBN} +configuration option @option{--with-auto-load-dir}. -Finally, if this file does not exist, then @value{GDBN} will look for -a file named @file{@var{data-directory}/auto-load/@var{real-name}}, where -@var{data-directory} is @value{GDBN}'s data directory (available via -@code{show data-directory}, @pxref{Data Files}), and @var{real-name} -is the object file's real name, as described above. +Any reference to @file{$debugdir} will get replaced by +@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any +reference to @file{$datadir} will get replaced by @var{data-directory} which is +determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and +@file{$datadir} must be placed as a directory component --- either alone or +delimited by @file{/} or @file{\} directory separators, depending on the host +platform. + +The list of directories uses path separator (@samp{:} on GNU and Unix +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly +to the @env{PATH} environment variable. + +@anchor{show auto-load scripts-directory} +@kindex show auto-load scripts-directory +@item show auto-load scripts-directory +Show @value{GDBN} auto-loaded scripts location. +@end table @value{GDBN} does not track which files it has already auto-loaded this way. @value{GDBN} will load the associated script every time the corresponding @@ -25366,6 +25863,9 @@ DEFINE_GDB_SCRIPT ("my-app-scripts.py") The script name may include directories if desired. +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + If the macro is put in a header, any application or library using this header will get a reference to the specified script. @@ -27588,7 +28088,7 @@ N.A. @smallexample -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ -c @var{condition} ] [ -i @var{ignore-count} ] - [ -p @var{thread} ] [ @var{location} ] + [ -p @var{thread-id} ] [ @var{location} ] @end smallexample @noindent @@ -27611,10 +28111,6 @@ The possible optional parameters of this command are: Insert a temporary breakpoint. @item -h Insert a hardware breakpoint. -@item -c @var{condition} -Make the breakpoint conditional on @var{condition}. -@item -i @var{ignore-count} -Initialize the @var{ignore-count}. @item -f If @var{location} cannot be parsed (for example if it refers to unknown files or functions), create a pending @@ -27626,6 +28122,12 @@ Create a disabled breakpoint. @item -a Create a tracepoint. @xref{Tracepoints}. When this parameter is used together with @samp{-h}, a fast tracepoint is created. +@item -c @var{condition} +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}. @end table @subsubheading Result @@ -27654,7 +28156,7 @@ Note: this format is open to change. @subsubheading @value{GDBN} Command The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, -@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}. +@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}. @subsubheading Example @@ -27683,11 +28185,11 @@ bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", addr="0x00010774",func="foo",file="recursive2.c", fullname="/home/foo/recursive2.c",line="11",times="0"@}]@} (gdb) --break-insert -r foo.* -~int foo(int, int); -^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c, -"fullname="/home/foo/recursive2.c",line="11",times="0"@} -(gdb) +@c -break-insert -r foo.* +@c ~int foo(int, int); +@c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c, +@c "fullname="/home/foo/recursive2.c",line="11",times="0"@} +@c (gdb) @end smallexample @subheading The @code{-break-list} Command @@ -32185,6 +32687,78 @@ and only if there is a corresponding executable file. @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...] @end smallexample +@subheading The @code{-info-os} Command +@findex -info-os + +@subsubheading Synopsis + +@smallexample +-info-os [ @var{type} ] +@end smallexample + +If no argument is supplied, the command returns a table of available +operating-system-specific information types. If one of these types is +supplied as an argument @var{type}, then the command returns a table +of data of that type. + +The types of information available depend on the target operating +system. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info os}. + +@subsubheading Example + +When run on a @sc{gnu}/Linux system, the output will look something +like this: + +@smallexample +@value{GDBP} +-info-os +^done,OSDataTable=@{nr_rows="9",nr_cols="3", +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@}, + @{width="10",alignment="-1",col_name="col1",colhdr="Description"@}, + @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}], +body=[item=@{col0="processes",col1="Listing of all processes", + col2="Processes"@}, + item=@{col0="procgroups",col1="Listing of all process groups", + col2="Process groups"@}, + item=@{col0="threads",col1="Listing of all threads", + col2="Threads"@}, + item=@{col0="files",col1="Listing of all file descriptors", + col2="File descriptors"@}, + item=@{col0="sockets",col1="Listing of all internet-domain sockets", + col2="Sockets"@}, + item=@{col0="shm",col1="Listing of all shared-memory regions", + col2="Shared-memory regions"@}, + item=@{col0="semaphores",col1="Listing of all semaphores", + col2="Semaphores"@}, + item=@{col0="msg",col1="Listing of all message queues", + col2="Message queues"@}, + item=@{col0="modules",col1="Listing of all loaded kernel modules", + col2="Kernel modules"@}]@} +@value{GDBP} +-info-os processes +^done,OSDataTable=@{nr_rows="190",nr_cols="4", +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@}, + @{width="10",alignment="-1",col_name="col1",colhdr="user"@}, + @{width="10",alignment="-1",col_name="col2",colhdr="command"@}, + @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}], +body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@}, + item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@}, + item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@}, + ... + item=@{col0="26446",col1="stan",col2="bash",col3="0"@}, + item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@} +(gdb) +@end smallexample + +(Note that the MI output here includes a @code{"Title"} column that +does not appear in command-line @code{info os}; this column is useful +for MI clients that want to enumerate the types of data, such as in a +popup menu, but is needless clutter on the command line, and +@code{info os} omits it.) @subheading The @code{-add-inferior} Command @findex -add-inferior @@ -32965,6 +33539,158 @@ Display the current setting of execution of debugging operations by the in-process agent. @end table +@menu +* In-Process Agent Protocol:: +@end menu + +@node In-Process Agent Protocol +@section In-Process Agent Protocol +@cindex in-process agent protocol + +The in-process agent is able to communicate with both @value{GDBN} and +GDBserver (@pxref{In-Process Agent}). This section documents the protocol +used for communications between @value{GDBN} or GDBserver and the IPA. +In general, @value{GDBN} or GDBserver sends commands +(@pxref{IPA Protocol Commands}) and data to in-process agent, and then +in-process agent replies back with the return result of the command, or +some other information. The data sent to in-process agent is composed +of primitive data types, such as 4-byte or 8-byte type, and composite +types, which are called objects (@pxref{IPA Protocol Objects}). + +@menu +* IPA Protocol Objects:: +* IPA Protocol Commands:: +@end menu + +@node IPA Protocol Objects +@subsection IPA Protocol Objects +@cindex ipa protocol objects + +The commands sent to and results received from agent may contain some +complex data types called @dfn{objects}. + +The in-process agent is running on the same machine with @value{GDBN} +or GDBserver, so it doesn't have to handle as much differences between +two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. +However, there are still some differences of two ends in two processes: + +@enumerate +@item +word size. On some 64-bit machines, @value{GDBN} or GDBserver can be +compiled as a 64-bit executable, while in-process agent is a 32-bit one. +@item +ABI. Some machines may have multiple types of ABI, @value{GDBN} or +GDBserver is compiled with one, and in-process agent is compiled with +the other one. +@end enumerate + +Here are the IPA Protocol Objects: + +@enumerate +@item +agent expression object. It represents an agent expression +(@pxref{Agent Expressions}). +@anchor{agent expression object} +@item +tracepoint action object. It represents a tracepoint action +(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, +memory, static trace data and to evaluate expression. +@anchor{tracepoint action object} +@item +tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). +@anchor{tracepoint object} + +@end enumerate + +The following table describes important attributes of each IPA protocol +object: + +@multitable @columnfractions .30 .20 .50 +@headitem Name @tab Size @tab Description +@item @emph{agent expression object} @tab @tab +@item length @tab 4 @tab length of bytes code +@item byte code @tab @var{length} @tab contents of byte code +@item @emph{tracepoint action for collecting memory} @tab @tab +@item 'M' @tab 1 @tab type of tracepoint action +@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the +address of the lowest byte to collect, otherwise @var{addr} is the offset +of @var{basereg} for memory collecting. +@item len @tab 8 @tab length of memory for collecting +@item basereg @tab 4 @tab the register number containing the starting +memory address for collecting. +@item @emph{tracepoint action for collecting registers} @tab @tab +@item 'R' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for collecting static trace data} @tab @tab +@item 'L' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for expression evaluation} @tab @tab +@item 'X' @tab 1 @tab type of tracepoint action +@item agent expression @tab length of @tab @ref{agent expression object} +@item @emph{tracepoint object} @tab @tab +@item number @tab 4 @tab number of tracepoint +@item address @tab 8 @tab address of tracepoint inserted on +@item type @tab 4 @tab type of tracepoint +@item enabled @tab 1 @tab enable or disable of tracepoint +@item step_count @tab 8 @tab step +@item pass_count @tab 8 @tab pass +@item numactions @tab 4 @tab number of tracepoint actions +@item hit count @tab 8 @tab hit count +@item trace frame usage @tab 8 @tab trace frame usage +@item compiled_cond @tab 8 @tab compiled condition +@item orig_size @tab 8 @tab orig size +@item condition @tab 4 if condition is NULL otherwise length of +@ref{agent expression object} +@tab zero if condition is NULL, otherwise is +@ref{agent expression object} +@item actions @tab variable +@tab numactions number of @ref{tracepoint action object} +@end multitable + +@node IPA Protocol Commands +@subsection IPA Protocol Commands +@cindex ipa protocol commands + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +@table @samp + +@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} +Installs a new fast tracepoint described by @var{tracepoint_object} +(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the +head of @dfn{jumppad}, which is used to jump to data collection routine +in IPA finally. + +Replies: +@table @samp +@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} +@var{target_address} is address of tracepoint in the inferior. +@var{gdb_jump_pad_head} is updated head of jumppad. Both of +@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. +@var{fjump} contains a sequence of instructions jump to jumppad entry. +@var{fjump_size}, 4-byte long, is the size of @var{fjump}. +@item E @var{NN} +for an error + +@end table + +@item qTfSTM +@xref{qTfSTM}. +@item qTsSTM +@xref{qTsSTM}. +@item qTSTMat +@xref{qTSTMat}. +@item probe_marker_at:@var{address} +Asks in-process agent to probe the marker at @var{address}. + +Replies: +@table @samp +@item E @var{NN} +for an error +@end table +@item unprobe_marker_at:@var{address} +Asks in-process agent to unprobe the marker at @var{address}. +@end table + @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} @@ -33755,8 +34481,8 @@ messages, see @ref{Debugging Output}.) @table @code @kindex maint agent @kindex maint agent-eval -@item maint agent @var{expression} -@itemx maint agent-eval @var{expression} +@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression} +@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression} Translate the given @var{expression} into remote agent bytecodes. This command is useful for debugging the Agent Expression mechanism (@pxref{Agent Expressions}). The @samp{agent} version produces an @@ -33767,6 +34493,15 @@ globb} will include bytecodes to record four bytes of memory at each of the addresses of @code{globa} and @code{globb}, while discarding the result of the addition, while an evaluation expression will do the addition and return the sum. +If @code{-at} is given, generate remote agent bytecode for @var{location}. +If not, generate remote agent bytecode for current frame PC address. + +@kindex maint agent-printf +@item maint agent-printf @var{format},@var{expr},... +Translate the given format string and list of argument expressions +into remote agent bytecodes and display them as a disassembled list. +This command is useful for debugging the agent version of dynamic +printf (@pxref{Dynamic Printf}. @kindex maint info breakpoints @item @anchor{maint info breakpoints}maint info breakpoints @@ -33801,6 +34536,11 @@ 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 set displaced-stepping @kindex show displaced-stepping @cindex displaced stepping support @@ -35002,7 +35742,7 @@ avoid potential problems with duplicate packets, the operations should be implemented in an idempotent way.} @item z0,@var{addr},@var{kind} -@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]} +@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} @cindex @samp{z0} packet @cindex @samp{Z0} packet Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address @@ -35030,6 +35770,22 @@ actual conditional expression in bytecode form. @end table +The optional @var{cmd_list} parameter introduces commands that may be +run on the target, rather than being reported back to @value{GDBN}. +The parameter starts with a numeric flag @var{persist}; if the flag is +nonzero, then the breakpoint may remain active and the commands +continue to be run even when @value{GDBN} disconnects from the target. +Following this flag is a series of expressions concatenated with no +separators. Each expression has the following form: + +@table @samp + +@item X @var{len},@var{expr} +@var{len} is the length of the bytecode expression and @var{expr} is the +actual conditional expression in bytecode form. + +@end table + see @ref{Architecture-Specific Protocol Details}. @emph{Implementation note: It is possible for a target to copy or move @@ -35963,6 +36719,11 @@ These are the currently defined stub features and their properties: @tab @samp{-} @tab No +@item @samp{BreakpointCommands} +@tab No +@tab @samp{-} +@tab No + @end multitable These are the currently defined stub features, in more detail: @@ -36112,6 +36873,11 @@ to be enabled and disabled while a trace experiment is running. The remote stub supports the @samp{tracenz} bytecode for collecting strings. See @ref{Bytecode Descriptions} for details about the bytecode. +@item BreakpointCommands +@cindex breakpoint commands, in remote protocol +The remote stub supports running a breakpoint's command list itself, +rather than reporting the hit to @value{GDBN}. + @end table @item qSymbol:: @@ -36475,9 +37241,21 @@ This section describes how the remote protocol is applied to specific target architectures. Also see @ref{Standard Target Features}, for details of XML target descriptions for each architecture. -@subsection ARM +@menu +* ARM-Specific Protocol Details:: +* MIPS-Specific Protocol Details:: +@end menu + +@node ARM-Specific Protocol Details +@subsection @acronym{ARM}-specific Protocol Details + +@menu +* ARM Breakpoint Kinds:: +@end menu -@subsubsection Breakpoint Kinds +@node ARM Breakpoint Kinds +@subsubsection @acronym{ARM} Breakpoint Kinds +@cindex breakpoint kinds, @acronym{ARM} These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. @@ -36490,37 +37268,65 @@ These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. 32-bit Thumb mode (Thumb-2) breakpoint. @item 4 -32-bit ARM mode breakpoint. +32-bit @acronym{ARM} mode breakpoint. @end table -@subsection MIPS +@node MIPS-Specific Protocol Details +@subsection @acronym{MIPS}-specific Protocol Details -@subsubsection Register Packet Format +@menu +* MIPS Register packet Format:: +* MIPS Breakpoint Kinds:: +@end menu + +@node MIPS Register packet Format +@subsubsection @acronym{MIPS} Register Packet Format +@cindex register packet format, @acronym{MIPS} The following @code{g}/@code{G} packets have previously been defined. In the below, some thirty-two bit registers are transferred as sixty-four bits. Those registers should be zero/sign extended (which?) to fill the space allocated. Register bytes are transferred in target byte order. The two nibbles within a register byte are transferred -most-significant - least-significant. +most-significant -- least-significant. @table @r @item MIPS32 - All registers are transferred as thirty-two bit quantities in the order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point registers; fsr; fir; fp. @item MIPS64 - All registers are transferred as sixty-four bit quantities (including thirty-two bit registers such as @code{sr}). The ordering is the same as @code{MIPS32}. @end table +@node MIPS Breakpoint Kinds +@subsubsection @acronym{MIPS} Breakpoint Kinds +@cindex breakpoint kinds, @acronym{MIPS} + +These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. + +@table @r + +@item 2 +16-bit @acronym{MIPS16} mode breakpoint. + +@item 3 +16-bit @acronym{microMIPS} mode breakpoint. + +@item 4 +32-bit standard @acronym{MIPS} mode breakpoint. + +@item 5 +32-bit @acronym{microMIPS} mode breakpoint. + +@end table + @node Tracepoint Packets @section Tracepoint Packets @cindex tracepoint packets @@ -36532,6 +37338,7 @@ tracepoints (@pxref{Tracepoints}). @table @samp @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]} +@cindex @samp{QTDP} packet Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then the tracepoint is disabled. @var{step} is the tracepoint's step @@ -36666,6 +37473,7 @@ target should simply create the trace state variables as they are mentioned in expressions. @item QTFrame:@var{n} +@cindex @samp{QTFrame} packet Select the @var{n}'th tracepoint frame from the buffer, and use the register and memory contents recorded there to answer subsequent request packets from @value{GDBN}. @@ -36708,6 +37516,7 @@ Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first frame @emph{outside} the given range of addresses (exclusive). @item qTMinFTPILen +@cindex @samp{qTMinFTPILen} packet This packet requests the minimum length of instruction at which a fast tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on the 32-bit x86 architecture, it is possible to use a 4-byte jump, but @@ -36732,30 +37541,36 @@ An empty reply indicates that the request is not supported by the stub. @end table @item QTStart +@cindex @samp{QTStart} packet Begin the tracepoint experiment. Begin collecting data from tracepoint hits in the trace frame buffer. This packet supports the @samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate instruction reply packet}). @item QTStop +@cindex @samp{QTStop} packet End the tracepoint experiment. Stop collecting trace frames. @item QTEnable:@var{n}:@var{addr} @anchor{QTEnable} +@cindex @samp{QTEnable} packet Enable tracepoint @var{n} at address @var{addr} in a started tracepoint experiment. If the tracepoint was previously disabled, then collection of data from it will resume. @item QTDisable:@var{n}:@var{addr} @anchor{QTDisable} +@cindex @samp{QTDisable} packet Disable tracepoint @var{n} at address @var{addr} in a started tracepoint experiment. No more data will be collected from the tracepoint unless @samp{QTEnable:@var{n}:@var{addr}} is subsequently issued. @item QTinit +@cindex @samp{QTinit} packet Clear the table of tracepoints, and empty the trace frame buffer. @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} +@cindex @samp{QTro} packet Establish the given ranges of memory as ``transparent''. The stub will answer requests for these ranges from memory's current contents, if they were not collected as part of the tracepoint hit. @@ -36766,12 +37581,14 @@ still have the same contents they did when the tracepoint was hit, so there's no reason for the stub to refuse to provide their contents. @item QTDisconnected:@var{value} +@cindex @samp{QTDisconnected} packet Set the choice to what to do with the tracing run when @value{GDBN} disconnects from the target. A @var{value} of 1 directs the target to continue the tracing run, while 0 tells the target to stop tracing if @value{GDBN} is no longer in the picture. @item qTStatus +@cindex @samp{qTStatus} packet Ask the stub if there is a trace experiment running right now. The reply has the form: @@ -36891,7 +37708,9 @@ was not collected. @end table @item qTfP +@cindex @samp{qTfP} packet @itemx qTsP +@cindex @samp{qTsP} packet These packets request data about tracepoints that are being used by the target. @value{GDBN} sends @code{qTfP} to get the first piece of data, and multiple @code{qTsP} to get additional pieces. Replies @@ -36899,7 +37718,9 @@ to these packets generally take the form of the @code{QTDP} packets that define tracepoints. (FIXME add detailed syntax) @item qTfV +@cindex @samp{qTfV} packet @itemx qTsV +@cindex @samp{qTsV} packet These packets request data about trace state variables that are on the target. @value{GDBN} sends @code{qTfV} to get the first vari of data, and multiple @code{qTsV} to get additional variables. Replies to @@ -36908,6 +37729,10 @@ trace state variables. @item qTfSTM @itemx qTsSTM +@anchor{qTfSTM} +@anchor{qTsSTM} +@cindex @samp{qTfSTM} packet +@cindex @samp{qTsSTM} packet These packets request data about static tracepoint markers that exist in the target program. @value{GDBN} sends @code{qTfSTM} to get the first piece of data, and multiple @code{qTsSTM} to get additional @@ -36938,18 +37763,22 @@ query), until the target responds with @samp{l} (lower-case ell, for @dfn{last}). @item qTSTMat:@var{address} +@anchor{qTSTMat} +@cindex @samp{qTSTMat} packet This packets requests data about static tracepoint markers in the target program at @var{address}. Replies to this packet follow the syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static tracepoint markers. @item QTSave:@var{filename} +@cindex @samp{QTSave} packet This packet directs the target to save trace data to the file name @var{filename} in the target's filesystem. @var{filename} is encoded as a hex string; the interpretation of the file name (relative vs absolute, wild cards, etc) is up to the target. @item qTBuffer:@var{offset},@var{len} +@cindex @samp{qTBuffer} packet Return up to @var{len} bytes of the current contents of trace buffer, starting at @var{offset}. The trace buffer is treated as if it were a contiguous collection of traceframes, as per the trace file format. @@ -36963,6 +37792,7 @@ This packet directs the target to use a circular trace buffer if @var{value} is 1, or a linear buffer if the value is 0. @item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} +@cindex @samp{QTNotes} packet This packet adds optional textual notes to the trace run. Allowable types include @code{user}, @code{notes}, and @code{tstop}, the @var{text} fields are arbitrary strings, hex-encoded. @@ -38827,7 +39657,7 @@ The formal DTD for the traceframe info format is given below: One of the challenges of using @value{GDBN} to debug embedded systems is that there are so many minor variants of each processor architecture in use. It is common practice for vendors to start with -a standard processor core --- ARM, PowerPC, or MIPS, for example --- +a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example --- and then make changes to adapt it to a particular market niche. Some architectures have hundreds of variants, available from dozens of vendors. This leads to a number of problems: @@ -39370,10 +40200,10 @@ The @samp{org.gnu.gdb.i386.linux} feature is optional. It should describe a single register, @samp{orig_eax}. @node MIPS Features -@subsection MIPS Features -@cindex target descriptions, MIPS features +@subsection @acronym{MIPS} Features +@cindex target descriptions, @acronym{MIPS} features -The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets. +The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets. It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, @samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending on the target. @@ -39593,11 +40423,12 @@ unless otherwise noted: @enumerate @item -The version number, currently 6. Versions 1, 2 and 3 are obsolete. +The version number, currently 7. Versions 1, 2 and 3 are obsolete. Version 4 uses a different hashing function from versions 5 and 6. -Version 6 includes symbols for inlined functions, whereas versions -4 and 5 do not. @value{GDBN} will only read version 4 and 5 indices -if the @code{--use-deprecated-index-sections} option is used. +Version 6 includes symbols for inlined functions, whereas versions 4 +and 5 do not. Version 7 adds attributes to the CU indices in the +symbol table. @value{GDBN} will only read version 4, 5, or 6 indices +by specifying @code{set use-deprecated-index-sections on}. @item The offset, from the start of the file, of the CU list. @@ -39672,7 +40503,7 @@ index version: @item Version 4 The formula is @code{r = r * 67 + c - 113}. -@item Versions 5 and 6 +@item Versions 5 to 7 The formula is @code{r = r * 67 + tolower (c) - 113}. @end table @@ -39696,26 +40527,121 @@ strings. A CU vector in the constant pool is a sequence of @code{offset_type} values. The first value is the number of CU indices in the vector. -Each subsequent value is the index of a CU in the CU list. This -element in the hash table is used to indicate which CUs define the -symbol. +Each subsequent value is the index and symbol attributes of a CU in +the CU list. This element in the hash table is used to indicate which +CUs define the symbol and how the symbol is used. +See below for the format of each CU index+attributes entry. A string in the constant pool is zero-terminated. @end enumerate +Attributes were added to CU index values in @code{.gdb_index} version 7. +If a symbol has multiple uses within a CU then there is one +CU index+attributes value for each use. + +The format of each CU index+attributes entry is as follows +(bit 0 = LSB): + +@table @asis + +@item Bits 0-23 +This is the index of the CU in the CU list. +@item Bits 24-27 +These bits are reserved for future purposes and must be zero. +@item Bits 28-30 +The kind of the symbol in the CU. + +@table @asis +@item 0 +This value is reserved and should not be used. +By reserving zero the full @code{offset_type} value is backwards compatible +with previous versions of the index. +@item 1 +The symbol is a type. +@item 2 +The symbol is a variable or an enum value. +@item 3 +The symbol is a function. +@item 4 +Any other kind of symbol. +@item 5,6,7 +These values are reserved. +@end table + +@item Bit 31 +This bit is zero if the value is global and one if it is static. + +The determination of whether a symbol is global or static is complicated. +The authorative reference is the file @file{dwarf2read.c} in +@value{GDBN} sources. + +@end table + +This pseudo-code describes the computation of a symbol's kind and +global/static attributes in the index. + +@smallexample +is_external = get_attribute (die, DW_AT_external); +language = get_attribute (cu_die, DW_AT_language); +switch (die->tag) + @{ + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = (language != CPLUS && language != JAVA); + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = (language != CPLUS && language != JAVA); + break; + default: + assert (0); + @} +@end smallexample + @include gpl.texi @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl.texi -@node Index -@unnumbered Index +@node Concept Index +@unnumbered Concept Index @printindex cp +@node Command and Variable Index +@unnumbered Command, Variable, and Function Index + +@printindex fn + @tex -% I think something like @colophon should be in texinfo. In the +% I think something like @@colophon should be in texinfo. In the % meantime: \long\def\colophon{\hbox to0pt{}\vfill \centerline{The body of this manual is set in} @@ -39727,7 +40653,7 @@ A string in the constant pool is zero-terminated. \centerline{{\sl\fontname\tensl\/}} \centerline{are used for emphasis.}\vfill} \page\colophon -% Blame: doc@cygnus.com, 1991. +% Blame: doc@@cygnus.com, 1991. @end tex @bye