@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
@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
@menu
* Free Software:: Freely redistributable software
+* Free Documentation:: Free Software Needs Free Documentation
* Contributors:: Contributors to GDB
@end menu
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
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}
@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}.
@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
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
@file{/usr/lib/debug/usr/bin/ls.debug}.
@end itemize
-You can set the global debugging info directories, and view the
-list @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
@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
* 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
@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
@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
@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
@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
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:
@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.
@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}
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
@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
@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
@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
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 $ddir/auto-load.
+ is $debugdir:$datadir/auto-load.
scripts-directory: List of directories from which to load auto-loaded scripts
- is $ddir/auto-load.
+ is $debugdir:$datadir/auto-load.
@end smallexample
@anchor{info auto-load}
$ ./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 "$ddir/auto-load".
+ 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 "$ddir/auto-load".
+ 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:
@end table
This variable defaults to what @code{--with-auto-load-dir} has been configured
-to (@pxref{with-auto-load-dir}). @file{$ddir} substituation applies the same
-as for @xref{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}.
+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
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
@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
* 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
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
@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
@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{script-name} in all of the
-directories mentioned in the value of @code{debug-file-directory}.
-
-Finally, if this file does not exist, then @value{GDBN} will look for
+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{set auto-load safe-path} (@pxref{set auto-load safe-path}).
@anchor{with-auto-load-dir}
-This variable defaults to @file{$ddir/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}.
-
-Any used string @file{$ddir} will get replaced by @var{data-directory} which is
-determined at @value{GDBN} startup (@pxref{Data Files}). @file{$ddir} must be
-be placed as a directory component --- either alone or delimited by @file{/} or
-@file{\} directory separators, depending on the host platform.
+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}.
+
+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
@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
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
@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
@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
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
@{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
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}
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.
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
@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
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}.
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
@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.
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:
@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
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
@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
@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.
@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.
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:
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.
@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
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
@printindex cp
@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}
\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
projects / deliverable / binutils-gdb.git / blobdiff