\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1988-2020 Free Software Foundation, Inc.
+@c Copyright (C) 2020 Advanced Micro Devices, Inc. All rights reserved.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c manuals to an info tree.
@dircategory Software development
@direntry
-* Gdb: (gdb). The GNU debugger.
-* gdbserver: (gdb) Server. The GNU debugging server.
+* ROCgdb: (gdb). The ROCm GNU debugger.
+@c * gdbserver: (gdb) Server. The GNU debugging server.
@end direntry
@copying
@c man begin COPYRIGHT
+@indent
Copyright @copyright{} 1988-2020 Free Software Foundation, Inc.
+Copyright @copyright{} 2020 Advanced Micro Devices, Inc. All rights reserved.
+
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
}
@end tex
-@vskip 0pt plus 1filll
-Published by the Free Software Foundation @*
-51 Franklin Street, Fifth Floor,
-Boston, MA 02110-1301, USA@*
-ISBN 978-0-9831592-3-0 @*
+@c Comment out publisher until upstreamed:
+@c @vskip 0pt plus 1filll
+@c Published by the Free Software Foundation @*
+@c 51 Franklin Street, Fifth Floor,
+@c Boston, MA 02110-1301, USA@*
+@c ISBN 978-0-9831592-3-0 @*
@insertcopying
@end titlepage
* Altering:: Altering execution
* GDB Files:: @value{GDBN} files
* Targets:: Specifying a debugging target
+* Heterogeneous Debugging:: Debugging Heterogeneous Programs
* Remote Debugging:: Debugging remote programs
* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Extending GDB:: Extending @value{GDBN}
-* Interpreters:: Command Interpreters
+* Interpreters:: Command Interpreters
* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
* GDB/MI:: @value{GDBN}'s Machine Interface.
@end ifclear
* In Memoriam:: In Memoriam
* Formatting Documentation:: How to format and print @value{GDBN} documentation
-* Installing GDB:: Installing GDB
+* Installing GDB:: Installing @value{GDBN}
* Maintenance Commands:: Maintenance Commands
* Remote Protocol:: GDB Remote Serial Protocol
-* Agent Expressions:: The GDB Agent Expression Mechanism
+* Agent Expressions:: The @value{GDBN} Agent Expression Mechanism
* Target Descriptions:: How targets can describe themselves to
@value{GDBN}
* Operating System Information:: Getting additional information from
the operating system
-* Trace File Format:: GDB trace file format
+* Trace File Format:: @value{GDBN} trace file format
* Index Section Format:: .gdb_index section format
* Man Pages:: Manual pages
* Copying:: GNU General Public License says
- how you can copy and share GDB
+ how you can copy and share @value{GDBN}
* GNU Free Documentation License:: The license for this documentation
* Concept Index:: Index of @value{GDBN} concepts
* Command and Variable Index:: Index of @value{GDBN} commands, variables,
- functions, and Python data types
+ functions, and Python data types
@end menu
@end ifnottex
of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and
Stafford Horne.
+Initial support for heterogeneous program debugging and the
+@acronym{AMD GPU} targets was developed by the following people at the
+Advanced Micro Devices company: Scott Linder, Laurent Morichetti,
+Qingchuan Shi, Tony Tye, and Zoran Zaric.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
Example:
@smallexample
@group
-(gdb) p var
+(@value{GDBP}) p var
$1 = @{
black = 144,
red = 233,
@}
@end group
@group
-(gdb) pipe p var|wc
+(@value{GDBP}) pipe p var|wc
7 19 80
-(gdb) |p var|wc -l
+(@value{GDBP}) |p var|wc -l
7
@end group
@group
-(gdb) p /x var
+(@value{GDBP}) p /x var
$4 = @{
black = 0x90,
red = 0xe9,
blue = 0x262,
white = 0x3db
@}
-(gdb) ||grep red
+(@value{GDBP}) ||grep red
red => 0xe9,
@end group
@group
-(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+(@value{GDBP}) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
this contains a PIPE char
-(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
+(@value{GDBP}) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
this contains a PIPE char!
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
@end table
session. For example, to change the limit of array elements to print,
you can do the following:
@smallexample
-(@value{GDBN}) set print elements 10
-(@value{GDBN}) print some_array
+(@value{GDBP}) set print elements 10
+(@value{GDBP}) print some_array
$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
@end smallexample
print} subcommands. @xref{print options}. The example above could be
rewritten as:
@smallexample
-(@value{GDBN}) print -elements 10 -- some_array
+(@value{GDBP}) print -elements 10 -- some_array
$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
@end smallexample
For example, the command
@smallexample
-(@value{GDBN}) with print array on -- print some_array
+(@value{GDBP}) with print array on -- print some_array
@end smallexample
@noindent
is equivalent to the following 3 commands:
@smallexample
-(@value{GDBN}) set print array on
-(@value{GDBN}) print some_array
-(@value{GDBN}) set print array off
+(@value{GDBP}) set print array on
+(@value{GDBP}) print some_array
+(@value{GDBP}) set print array off
@end smallexample
The @code{with} command is particularly useful when you want to
defined in Python or Guile. @xref{Extending GDB,, Extending GDB}.
@smallexample
-(@value{GDBN}) with print pretty on -- my_complex_command
+(@value{GDBP}) with print pretty on -- my_complex_command
@end smallexample
To change several settings for the same command, you can nest
variable or function and the correspondence between source line numbers
and addresses in the executable code.
-To request debugging information, specify the @samp{-g} option when you run
-the compiler.
+To request debugging information, specify the @option{-g} option when
+you run the compiler. However, to use the most expressive format
+available, including @value{GDBN} extensions if at all possible,
+@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports
+@w{@option{-ggdb}} which produces debugging information for use by
+@value{GDBN}. We recommend that you @emph{always} use
+@w{@option{-ggdb}} instead of plain @option{-g} if it is supported by
+the compiler you are using.
Programs that are to be shipped to your customers are compiled with
-optimizations, using the @samp{-O} compiler option. However, some
-compilers are unable to handle the @samp{-g} and @samp{-O} options
+optimizations, using the @option{-O} compiler option. However, some
+compilers are unable to handle the @option{-g} and @option{-O} options
together. Using those compilers, you cannot generate optimized
executables containing debugging information.
-@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
-without @samp{-O}, making it possible to debug optimized code. We
-recommend that you @emph{always} use @samp{-g} whenever you compile a
-program. You may think your program is correct, but there is no sense
-in pushing your luck. For more information, see @ref{Optimized Code}.
+@value{NGCC} supports @option{-g} with or without @option{-O}, making
+it possible to debug optimized code. We recommend that you
+@emph{always} use @option{-g} whenever you compile a program. You may
+think your program is correct, but there is no sense in pushing your
+luck. For more information, see @ref{Optimized Code}.
Older versions of the @sc{gnu} C compiler permitted a variant option
-@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
-format; if your @sc{gnu} C compiler has this option, do not use it.
+@w{@option{-gg}} for debugging information. @value{GDBN} no longer
+supports this format; if your @sc{gnu} C compiler has this option, do
+not use it.
@value{GDBN} knows about preprocessor macros and can show you their
expansion (@pxref{Macros}). Most compilers do not include information
about preprocessor macros in the debugging information if you specify
the @option{-g} flag alone. Version 3.1 and later of @value{NGCC},
the @sc{gnu} C compiler, provides macro information if you are using
-the DWARF debugging format, and specify the option @option{-g3}.
+the DWARF debugging format, and specify the option @w{@option{-g3}}.
@xref{Debugging Options,,Options for Debugging Your Program or GCC,
gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more
@item automatic notification of new threads
@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{thread-id-list} | all] @var{args}},
+@item @samp{thread apply @r{[}@var{thread-id-list} @r{|} all@r{]} @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
@cindex @code{New} @var{systag} message
@cindex thread identifier (system)
+@anchor{target system thread identifier}
@c FIXME-implementors!! It would be more helpful if the [New...] message
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
the full @var{inferior-num}.@var{thread-num} form to refer to threads
of inferior 1, the initial inferior.
-@anchor{thread ID lists}
-@cindex thread ID lists
+@anchor{thread ID list}
+@cindex thread ID list
Some commands accept a space-separated @dfn{thread ID list} as
argument. A list element can be:
7.1}.
-@anchor{global thread numbers}
+@anchor{global thread number}
@cindex global thread number
@cindex global thread identifier (GDB)
In addition to a @emph{per-inferior} number, each thread is also
@vindex $_thread@r{, convenience variable}
@vindex $_gthread@r{, convenience variable}
-The debugger convenience variables @samp{$_thread} and
-@samp{$_gthread} contain, respectively, the per-inferior thread number
-and the global thread number of the current thread. You may find this
+@vindex $_thread_systag@r{, convenience variable}
+@vindex $_thread_name@r{, convenience variable}
+The debugger convenience variables @samp{$_thread}, @samp{$_gthread},
+@samp{$_thread_systag}, and @samp{$_thread_name} contain,
+respectively, the per-inferior thread number, the global thread
+number, the target system's thread identifier (@var{systag}) string,
+and the thread name string of the current thread. You may find this
useful in writing breakpoint conditional expressions, command scripts,
and so forth. @xref{Convenience Vars,, Convenience Variables}, for
general information on convenience variables.
@table @code
@kindex info threads
-@item info threads @r{[}@var{thread-id-list}@r{]}
+@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]}
Display information about one or more threads. With no arguments
displays information about all threads. You can specify the list of
threads that you want to display using the thread ID list syntax
-(@pxref{thread ID lists}).
+(@pxref{thread ID list}).
@value{GDBN} displays for each thread (in this order):
the per-inferior thread number assigned by @value{GDBN}
@item
-the global thread number assigned by @value{GDBN}, if the @samp{-gid}
-option was specified
+the global thread number assigned by @value{GDBN}, if the
+@w{@option{-gid}} option was specified
@item
the target system's thread identifier (@var{systag})
@smallexample
(@value{GDBP}) info threads
- Id Target Id Frame
+ Id Target Id Frame
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2 process 35 thread 23 0x34e5 in sigpause ()
3 process 35 thread 27 0x34e5 in sigpause ()
- at threadtest.c:68
@end smallexample
If you're debugging multiple inferiors, @value{GDBN} displays thread
IDs using the qualified @var{inferior-num}.@var{thread-num} format.
Otherwise, only @var{thread-num} is shown.
-If you specify the @samp{-gid} option, @value{GDBN} displays a column
-indicating each thread's global thread ID:
+If you specify the @w{@option{-gid}} option, @value{GDBN} displays a
+column indicating each thread's global thread ID:
@smallexample
-(@value{GDBP}) info threads
+(@value{GDBP}) info threads -gid
Id GId Target Id Frame
1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
1.2 3 process 35 thread 23 0x34e5 in sigpause ()
@end table
@table @code
-@kindex thread @var{thread-id}
-@item thread @var{thread-id}
+@kindex thread @r{[}-gid@r{]} @var{thread-id}
+@item thread @r{[}-gid@r{]} @var{thread-id}
Make thread ID @var{thread-id} the current thread. The command
-argument @var{thread-id} is the @value{GDBN} thread ID, as shown in
-the first field of the @samp{info threads} display, with or without an
-inferior qualifier (e.g., @samp{2.1} or @samp{1}).
+argument @var{thread-id} is the @value{GDBN} thread ID: if the
+@w{@option{-gid}} option is given it is a global thread identifier, as
+shown in the second field of the @samp{info threads -gid} display;
+otherwise it is a per process thread identifier, with or without an
+inferior qualifier (e.g., @samp{2.1} or @samp{1}), as shown in the
+first field of the @samp{info threads} display.
@value{GDBN} responds by displaying the system identifier of the
thread you selected, and its current stack frame summary:
@anchor{thread apply all}
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
+@item thread apply @r{[}@var{thread-id-list} @r{|} all @r{[}-ascending@r{]]} @r{[}@var{flag}@r{]@dots{}} @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the threads that you
want affected using the thread ID list syntax (@pxref{thread ID
-lists}), or specify @code{all} to apply to all threads. To apply a
+list}), or specify @code{all} to apply to all threads. To apply a
command to all threads in descending order, type @kbd{thread apply all
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
@kindex taas
@cindex apply command to all threads (ignoring errors and empty output)
@item taas [@var{option}]@dots{} @var{command}
-Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}.
+Shortcut for @code{thread apply all -s @r{[}@var{option}@r{]@dots{}} @var{command}}.
Applies @var{command} on all threads, ignoring errors and empty output.
The @code{taas} command accepts the same options as the @code{thread
@kindex tfaas
@cindex apply a command to all frames of all threads (ignoring errors and empty output)
@item tfaas [@var{option}]@dots{} @var{command}
-Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}.
+Shortcut for @code{thread apply all -s -- frame apply all -s @r{[}@var{option}@r{]@dots{}} @var{command}}.
Applies @var{command} on all frames of all threads, ignoring errors
and empty output. Note that the flag @code{-s} is specified twice:
The first @code{-s} ensures that @code{thread apply} only shows the thread
@kindex thread name
@cindex name a thread
+@anchor{thread name}
@item thread name [@var{name}]
This command assigns a name to the current thread. If no argument is
given, any existing user-specified name is removed. The thread name
@kindex thread find
@cindex search for a thread
+@anchor{thread find}
@item thread find [@var{regexp}]
Search for and display thread ids whose name or @var{systag}
-matches the supplied regular expression.
+matches the supplied regular expression. The syntax of the regular
+expression is that specified by Python's regular expression support.
As well as being the complement to the @samp{thread name} command,
this command also allows you to identify a thread by its target
is the LWP id.
@smallexample
-(@value{GDBN}) thread find 26688
+(@value{GDBP}) thread find 26688
Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
-(@value{GDBN}) info thread 4
+(@value{GDBP}) info thread 4
Id Target Id Frame
4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
@end smallexample
only on some platforms.
@kindex show libthread-db-search-path
-@item show libthread-db-search-path
+@item show libthread-db-search-path
Display current libthread_db search path.
@kindex set debug libthread-db
Use @code{1} to enable, @code{0} to disable.
@end table
+@xref{Heterogeneous Debugging} for additional infomation related to
+threads in heterogeneous systems.
+
@node Forks
@section Debugging Forks
@smallexample
(@value{GDBP}) info inferiors
-(gdb) info inferior
+(@value{GDBP}) info inferior
Id Description Executable
* 1 <null> prog1
(@value{GDBP}) run
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
+(@value{GDBP}) set dprintf-style call
+(@value{GDBP}) set dprintf-function fprintf
+(@value{GDBP}) set dprintf-channel mylog
+(@value{GDBP}) dprintf 25,"at line 25, glob=%d\n",glob
Dprintf 1 at 0x123456: file main.c, line 25.
-(gdb) info break
+(@value{GDBP}) 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)
+(@value{GDBP})
@end example
Note that the @code{info break} displays the dynamic printf commands
over when stepping.
@smallexample
-(gdb) skip -gfi utils/*.c
+(@value{GDBP}) skip -gfi utils/*.c
@end smallexample
@item -function @var{linespec}
regular expression makes this easier.
@smallexample
-(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
+(@value{GDBP}) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
@end smallexample
If you want to skip every templated C@t{++} constructor and destructor
in the @code{std} namespace you can do:
@smallexample
-(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
+(@value{GDBP}) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
@end smallexample
@end table
will be skipped over when stepping.
@smallexample
-(gdb) skip file boring.c
+(@value{GDBP}) skip file boring.c
File boring.c will be skipped when stepping.
@end smallexample
supports.
@smallexample
-(gdb) info record
+(@value{GDBP}) info record
Active record target: record-btrace
Recording format: Intel Processor Trace.
Buffer size: 16kB.
Failed to configure the Intel Processor Trace decoder: unknown cpu.
-(gdb) set record btrace cpu intel:6/158
-(gdb) info record
+(@value{GDBP}) set record btrace cpu intel:6/158
+(@value{GDBP}) info record
Active record target: record-btrace
Recording format: Intel Processor Trace.
Buffer size: 16kB.
@command{info frame}, for example:
@smallexample
-(gdb) info frame
+(@value{GDBP}) info frame
Stack level 1, frame at 0x7fffffffda30:
rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
tail call frame, caller of frame at 0x7fffffffda30
@smallexample
@group
-(gdb) frame apply all p j
+(@value{GDBP}) frame apply all p j
#0 some_function (i=5) at fun.c:4
No symbol "j" in current context.
-(gdb) frame apply all -c p j
+(@value{GDBP}) frame apply all -c p j
#0 some_function (i=5) at fun.c:4
No symbol "j" in current context.
#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
$1 = 5
-(gdb) frame apply all -s p j
+(@value{GDBP}) frame apply all -s p j
#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
$2 = 5
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
@smallexample
@group
-(gdb) frame apply all p $sp
+(@value{GDBP}) frame apply all p $sp
#0 some_function (i=5) at fun.c:4
$4 = (void *) 0xffffd1e0
#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
$5 = (void *) 0xffffd1f0
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
If the flag @code{-q} is given, no frame information is printed:
@smallexample
@group
-(gdb) frame apply all -q p $sp
+(@value{GDBP}) frame apply all -q p $sp
$12 = (void *) 0xffffd1e0
$13 = (void *) 0xffffd1f0
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
Example:
@smallexample
-(gdb) info frame-filter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 Yes BuildProgramFilter
-(gdb) disable frame-filter /build/test BuildProgramFilter
-(gdb) info frame-filter
+(@value{GDBP}) disable frame-filter /build/test BuildProgramFilter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 No BuildProgramFilter
-(gdb) enable frame-filter global PrimaryFunctionFilter
-(gdb) info frame-filter
+(@value{GDBP}) enable frame-filter global PrimaryFunctionFilter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Example:
@smallexample
-(gdb) info frame-filter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 No BuildProgramFilter
-(gdb) set frame-filter priority global Reverse 50
-(gdb) info frame-filter
+(@value{GDBP}) set frame-filter priority global Reverse 50
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Here is another example showing raw instructions in hex for AMD x86-64,
@smallexample
-(gdb) disas /r 0x400281,+10
+(@value{GDBP}) disas /r 0x400281,+10
Dump of assembler code from 0x400281 to 0x40028b:
0x0000000000400281: 38 36 cmp %dh,(%rsi)
0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
@code{explore} command as follows.
@smallexample
-(gdb) explore cs
+(@value{GDBP}) explore cs
The value of `cs' is a struct/class of type `struct ComplexStruct' with
the following fields:
@code{struct ComplexStruct} to the @code{explore} command.
@smallexample
-(gdb) explore struct ComplexStruct
+(@value{GDBP}) explore struct ComplexStruct
@end smallexample
@noindent
@smallexample
Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29
29 i++;
-(gdb) next
+(@value{GDBP}) next
30 e (i);
-(gdb) print i
+(@value{GDBP}) print i
$1 = 31
-(gdb) print i@@entry
+(@value{GDBP}) print i@@entry
$2 = 30
@end smallexample
You get during debugging
@smallexample
-(gdb) print var0
+(@value{GDBP}) print var0
$1 = "A"
-(gdb) print var1
+(@value{GDBP}) print var1
$2 = @{65 'A', 0 '\0'@}
@end smallexample
the structure that are visible, for example
@smallexample
-(gdb) set print max-depth 2
-(gdb) p var
+(@value{GDBP}) set print max-depth 2
+(@value{GDBP}) p var
$1 = @{d = @{c = @{...@}@}@}
-(gdb) p var.d
+(@value{GDBP}) p var.d
$2 = @{c = @{b = @{...@}@}@}
-(gdb) p var.d.c
+(@value{GDBP}) p var.d.c
$3 = @{b = @{a = 3@}@}
@end smallexample
@code{bar1} and @code{bar2}.
@smallexample
-(gdb) info pretty-printer
+(@value{GDBP}) info pretty-printer
library1.so:
foo
library2.so:
bar
bar1
bar2
-(gdb) info pretty-printer library2
+(@value{GDBP}) info pretty-printer library2
library2.so:
bar
bar1
bar2
-(gdb) disable pretty-printer library1
+(@value{GDBP}) disable pretty-printer library1
1 printer disabled
2 of 3 printers enabled
-(gdb) info pretty-printer
+(@value{GDBP}) info pretty-printer
library1.so:
foo [disabled]
library2.so:
bar
bar1
bar2
-(gdb) disable pretty-printer library2 bar;bar1
+(@value{GDBP}) disable pretty-printer library2 bar;bar1
1 printer disabled
1 of 3 printers enabled
-(gdb) info pretty-printer library2
+(@value{GDBP}) info pretty-printer library2
library1.so:
foo [disabled]
library2.so:
bar
bar1 [disabled]
bar2
-(gdb) disable pretty-printer library2 bar
+(@value{GDBP}) disable pretty-printer library2 bar
1 printer disabled
0 of 3 printers enabled
-(gdb) info pretty-printer library2
+(@value{GDBP}) info pretty-printer library2
library1.so:
foo [disabled]
library2.so:
The thread number of the current thread. @xref{thread numbers}.
@item $_gthread
-The global number of the current thread. @xref{global thread numbers}.
+The global number of the current thread. @xref{global thread number}.
+
+@item $_thread_systag
+The target system's thread identifier (@var{systag}) string of the
+current thread. @xref{target system thread identifier}.
+
+@item $_thread_name
+The thread name string of the current thread, or the empty string if
+no name has been assigned. @xref{thread name}.
@item $_gdb_major
@itemx $_gdb_minor
launched command. These variables are set and used similarly to
the variables @code{$_exitcode} and @code{$_exitsignal}.
+@item $_agent
+The per-inferior heterogeneous agent number of the current thread, or 0
+if not associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_gagent
+The global heterogeneous agent number of the current thread, or 0 if not
+associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_queue
+The per-inferior heterogeneous queue number of the current thread, or 0
+if not associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_gqueue
+The global heterogeneous queue number of the current thread, or 0 if not
+associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_dispatch
+The per-inferior heterogeneous dispatch number of the current thread, or
+0 if not associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_gdispatch
+The global heterogeneous dispatch number of the current thread, or 0 if
+not associated with a heterogeneous dispatch. @xref{Heterogeneous
+Debugging}.
+
+@item $_lane
+The per-inferior heterogeneous lane number of the current
+heterogeneous lane of the current thread. @xref{Heterogeneous
+Debugging}.
+
+@c FIXME-implementors!! Should there be @code{$_lane_index},
+@c @code{$_lane_active} and @code{$_lane_count} convenience variables?
+@c Note that the lane count needs to take into account when a grid
+@c size is not a multiple of the work-group size (resulting in partial
+@c work-groups on the dimension edges of the grid), and the work-group
+@c size is not a multiple of the wavefront size.
+
+@item $_glane
+The global heterogeneous lane number of the current heterogeneous
+lane. @xref{Heterogeneous Debugging}.
+
+@item $_lane_systag
+The target system's heterogeneous lane identifier (@var{lane_systag})
+string of the current lane in the current thread. @xref{target system
+lane identifier}.
+
+@item $_lane_name
+The heterogeneous lane name string of the current heterogeneous lane, or
+the empty string if no name has been assigned by the @samp{lane name}
+command. @xref{Heterogeneous Debugging}.
+
+@item $_dispatch_pos
+The heterogeneous dispatch position string of the current thread, or the
+empty string if not associated with a heterogeneous dispatch.
+@xref{Heterogeneous Debugging}.
+
+@item $_thread_workgroup_pos
+@itemx $_lane_workgroup_pos
+The heterogeneous work-group position string of the current thread or
+heterogeneous lane respectively, or the empty string if not associated
+with a heterogeneous dispatch. @xref{Heterogeneous Debugging}.
+
@end table
@node Convenience Funs
@findex $_regex@r{, convenience function}
Returns one if the string @var{str} matches the regular expression
@var{regex}. Otherwise it returns zero.
-The syntax of the regular expression is that specified by @code{Python}'s
+The syntax of the regular expression is that specified by Python's
regular expression support.
@item $_streq(@var{str1}, @var{str2})
Example:
@smallexample
-(gdb) backtrace
+(@value{GDBP}) backtrace
#0 bottom_func ()
at testsuite/gdb.python/py-caller-is.c:21
#1 0x00000000004005a0 in middle_func ()
at testsuite/gdb.python/py-caller-is.c:33
#3 0x00000000004005b6 in main ()
at testsuite/gdb.python/py-caller-is.c:39
-(gdb) print $_caller_is ("middle_func")
+(@value{GDBP}) print $_caller_is ("middle_func")
$1 = 1
-(gdb) print $_caller_is ("top_func", 2)
+(@value{GDBP}) print $_caller_is ("top_func", 2)
$1 = 1
@end smallexample
an enumerated type:
@smallexample
-(gdb) printf "Visiting node of type %s\n", $_as_string(node)
+(@value{GDBP}) printf "Visiting node of type %s\n", $_as_string(node)
Visiting node of type NODE_INTEGER
@end smallexample
complex number, e.g., using @code{$_cimag} on a @code{float complex}
will return an imaginary part of type @code{float}.
+@item $_thread_find(@var{regex})
+@findex $_thread_find@r{, convenience function}
+Searches for threads whose name or @var{systag} matches the supplied
+regular expression. The syntax of the regular expression is that
+specified by Python's regular expression support.
+
+Returns a string that is the space separated list of per-inferior
+thread numbers of the found threads. If debugging multiple inferiors,
+the thread numbers are qualified with the inferior number. If no
+threads are found, the empty string is returned. The string can be
+used in commands that accept a thread ID list. @xref{thread ID
+list}.
+
+@c FIXME-implementors!! Should this convenience function return a
+@c tuple rather than a string?
+
+For example, the following command lists all threads that are part of
+the heterogeneous work-group with dispatch position @samp{(1,2,3)}
+(@pxref{Heterogeneous Debugging}):
+
+@smallexample
+(@value{GDBP}) info threads $_thread_find ("work-group(1,2,3)")
+@end smallexample
+
+@item $_thread_find_first_gid(@var{regex})
+@findex $_thread_find_first_gid@r{, convenience function}
+Similar to the @code{$_thread_find} convenience function, except it
+returns a number that is the global thread number of one of the
+threads found, or 0 if no threads were found. The number can be used
+in commands that accept a global thread number. @xref{global thread
+number}.
+
+@c FIXME-implementors!! If @code{$_thread_find} returns a tuple then
+@c this convenience function may not be necessary as one can simply
+@c add @samp{[0]} to access the first element of a tuple.
+
+For example, the following command sets the current thread to one of
+the threads that are part of the heterogeneous work-group with
+dispatch position @samp{(1,2,3)} (@pxref{Heterogeneous Debugging}):
+
+@smallexample
+(@value{GDBP}) thread -gid $_thread_find_first_gid ("work-group(1,2,3)")
+@end smallexample
+
+@item $_lane_find(@var{regex})
+@itemx $_lane_find_first_gid(@var{regex})
+Similar to @samp{$_thread_find} and @samp{$_thread_find_first_gid}
+except for heterogeneous lanes. @xref{Heterogeneous Debugging}.
+
@end table
@value{GDBN} provides the ability to list and get help on
you get during debugging:
@smallexample
-(gdb) find &hello[0], +sizeof(hello), "hello"
+(@value{GDBP}) find &hello[0], +sizeof(hello), "hello"
0x804956d <hello.1620+6>
1 pattern found
-(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+(@value{GDBP}) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
0x8049567 <hello.1620>
0x804956d <hello.1620+6>
2 patterns found.
-(gdb) find &hello[0], +sizeof(hello), @{char[5]@}"hello"
+(@value{GDBP}) find &hello[0], +sizeof(hello), @{char[5]@}"hello"
0x8049567 <hello.1620>
0x804956d <hello.1620+6>
2 patterns found.
-(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
+(@value{GDBP}) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
0x8049567 <hello.1620>
1 pattern found
-(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+(@value{GDBP}) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
0x8049560 <mixed.1625>
1 pattern found
-(gdb) print $numfound
+(@value{GDBP}) print $numfound
$1 = 1
-(gdb) print $_
+(@value{GDBP}) print $_
$2 = (void *) 0x8049560
@end smallexample
kind by text @code{tail call frame} such as in this sample @value{GDBN} output:
@smallexample
-(gdb) x/i $pc - 2
+(@value{GDBP}) x/i $pc - 2
0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>
-(gdb) info frame
+(@value{GDBP}) info frame
Stack level 1, frame at 0x7fffffffda30:
rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
tail call frame, caller of frame at 0x7fffffffda30
DW_TAG_call_site 0x40039a in main
a () at t.c:3
3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
-(gdb) bt
+(@value{GDBP}) bt
#0 a () at t.c:3
#1 0x000000000040039a in main () at t.c:5
@end smallexample
tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)
tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)
tailcall: reduced: 0x4004d2(a) |
-(gdb) bt
+(@value{GDBP}) bt
#0 f () at t.c:2
#1 0x00000000004004d2 in a () at t.c:8
#2 0x0000000000400395 in main () at t.c:9
@{ if (i) b (i - 1); else c (0); @}
int main (void) @{ a (5); return 0; @}
-(gdb) bt
+(@value{GDBP}) bt
#0 c (i=i@@entry=0) at t.c:2
#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
function "a" at 0x400420 can call itself via tail calls
* Rust:: Rust
* Modula-2:: Modula-2
* Ada:: Ada
+* HIP:: HIP
@end menu
@node C
tag. For example:
@smallexample
-(gdb) b function(int)
+(@value{GDBP}) b function(int)
Breakpoint 2 at 0x40060d: file main.cc, line 10.
-(gdb) info breakpoints
+(@value{GDBP}) info breakpoints
Num Type Disp Enb Address What
1 breakpoint keep y 0x0040060d in function[abi:cxx11](int)
at main.cc:10
When stopped inside @code{main} either of these work:
@example
-(gdb) p myglob
-(gdb) p main.myglob
+(@value{GDBP}) p myglob
+(@value{GDBP}) p main.myglob
@end example
@cindex builtin Go types
@end table
+@node HIP
+@subsection HIP
+@cindex HIP
+
+@value{GDBN} supports the
+@url{https://github.com/ROCm-Developer-Tools/HIP/blob/master/docs/markdown/hip_kernel_language.md,
+HIP Programming Language}.
+
+@c TODO: Add any language specific differences.
+
@node Unsupported Languages
@section Unsupported Languages
need to resolve the type can be achieved.
@smallexample
-(gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
-(gdb) compile code printf ("%d\n", ((struct a *) argv)->a);
+(@value{GDBP}) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
+(@value{GDBP}) compile code printf ("%d\n", ((struct a *) argv)->a);
gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’
Compilation failed.
-(gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
+(@value{GDBP}) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
42
@end smallexample
* File Caching:: Information about @value{GDBN}'s file caching
* Separate Debug Files:: Debugging information in separate files
* MiniDebugInfo:: Debugging information in a special section
-* Index Files:: Index files speed up GDB
+* Index Files:: Index files speed up @value{GDBN}
* Symbol Errors:: Errors reading symbol files
-* Data Files:: GDB data files
+* Data Files:: @value{GDBN} data files
@end menu
@node Files
that lies within the boundaries of this symbol file in memory. Example:
@smallexample
-(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+(@value{GDBP}) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
add symbol table from file "/home/user/gdb/mylib.so" at
.text_addr = 0x7ffff7ff9480
(y or n) y
Reading symbols from /home/user/gdb/mylib.so...done.
-(gdb) remove-symbol-file -a 0x7ffff7ff9480
+(@value{GDBP}) remove-symbol-file -a 0x7ffff7ff9480
Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
-(gdb)
+(@value{GDBP})
@end smallexample
@end table
@node Data Files
-@section GDB Data Files
+@section @value{GDBN} Data Files
@cindex prefix for data files
@value{GDBN} will sometimes read an auxiliary data file. These files
data on the host, and that they have absolutely no effect on the
target system.
+@node Heterogeneous Debugging
+@chapter Debugging Heterogeneous Programs
+@cindex heterogeneous debugging
+
+@cindex heterogeneous system
+@cindex heterogeneous program
+In some operating systems, such as Linux with @acronym{AMD}'s
+@acronym{ROCm, Radeon Open Compute platforM} installed, a single
+program may have multiple threads in the same process, executing on
+different devices which may have different target architectures. Such
+a system is termed a @dfn{heterogeneous system} and a program that
+uses the multiple devices is termed a @dfn{heterogeneous program}.
+
+@cindex heterogeneous agent
+The multiple devices of a heterogeneous system are termed
+@dfn{heterogeneous agents}. They can include the following kinds of
+devices: @acronym{CPU, Central Processing Unit}, @acronym{GPU,
+Graphics Processing Unit}, @acronym{DSP, Digital Signal Processor},
+@acronym{FPGA, Field Programmable Gate Array}, as well as other
+specialized hardware.
+
+@cindex heterogeneous host agent
+The device of a heterogeneous system that starts the execution of the
+program is termed the @dfn{heterogeneous host agent}.
+
+The precise way threads are created on different heterogeneous agents
+may vary from one heterogeneous system to another, but in general the
+threads behave similarly no matter what heterogeneous agent is
+executing them, except that the target architecture may be different.
+
+@cindex heterogeneous queue
+@cindex heterogeneous packet
+A heterogeneous program can create @dfn{heterogeneous queues}
+associated with a heterogeneous agent. The heterogeneous program can
+then place @dfn{heterogeneous packets} on a heterogeneous queue to
+control the actions of the associated heterogeneous agent. A
+heterogeneous agent removes heterogeneous packets from the
+heterogeneous queues assocated with it and performs the requested
+actions. The packet actions and scheduling of packet processing
+varies depending on the heterogeneous system and the target
+architecture of the heterogeneous agent. @xref{Architectures}.
+
+@cindex heterogeneous dispatch packet
+@cindex heterogeneous dispatch
+A @dfn{heterogeneous dispatch packet} is used to initiate code
+execution on a heterogeneous agent. A single heterogeneous dispatch
+packet may specify that the heterogeneous agent create a set of
+threads that are all associated with a corresponding
+@dfn{heterogeneous dispatch}. Each thread typically has an associated
+position within the heterogeneous dispatch, possibly expressed as a
+multi-dimensional grid position. The heterogeneous agent typically
+can create multiple threads that execute concurrently. If a
+heterogeneous dispatch is larger than the number of concurrent threads
+that can be created, the heterogeneous agent creates threads of the
+heterogeneous dispatch as other threads complete. When all the
+threads of a heterogeneous dispatch have been created and have
+completed, the heterogeneous dispatch is considered complete.
+
+@cindex heterogeneous work-group
+The threads of a heterogeneous dispatch may be grouped into
+@dfn{heterogeneous work-groups}. The threads that belong to the same
+heterogeneous work-group may have special shared memory, and efficient
+execution synchronization abilities. A thread that is part of a
+heterogeneous work-group typically has an associated position within
+the heterogeneous work-group, possibly also expressed as a
+multi-dimensional grid position.
+
+Other heterogeneous packets may control heterogeneous packet
+scheduling, memory visibility between the threads of a heterogeneous
+dispatch and other threads, or other services supported by the
+heterogeneous system.
+
+@cindex heterogeneous lane
+On some heterogeneous systems there can be heterogeneous agents that
+support @acronym{SIMD, Single Instruction Multiple Data} or
+@acronym{SIMT, Single Instruction Multiple Threads} machine
+instructions. On these target achitectures, a single machine
+instruction can operate in parallel on multiple @dfn{heterogeneous
+lanes}.
+
+@cindex divergent control flow
+Source languages used by heterogeneous programs can be implemented on
+target achitectures that support multiple heterogeneous lanes by
+mapping a source language thread of execution onto a heterogeneous
+lane of a single target architecture thread. Control flow in the
+source language may be implemented by controlling which heterogeneous
+lanes are active. If the source language control flow may result in
+some heterogeneous lanes becoming inactive while some remain active,
+the control flow is said to be @dfn{divergent}. Typically, the
+machine code may execute different divergent paths for different sets
+of heterogeneous lanes, before the control flow recoverges and all
+heterogeneous lanes become active.
+
+Just because a target architecture supports multiple lanes, does not
+mean that the source language is mapped to use them to implement
+source language threads of execution. Therefore, a thread is only
+considered to have multiple heterogeneous lanes if it's current frame
+corresponds to a source language that does do such a mapping.
+
+@anchor{Address Space}
+@cindex address space
+On some heterogeneous systems there can be heterogeneous agents with
+target achitectures that support multiple @dfn{address spaces}. In
+these target achitectures, there may be memory that is physically
+disjoint from regular global virtual memory. There can also be cases
+when the same underlying memory can be accessed using linear addresses
+that map to the underlying physical memory in an interleaved manner.
+In these target architectures there can be distinct machine
+instructions to access the distinct address spaces. For example,
+there may be physical hardware scratch pad memory that is allocated
+and accessible only to the threads that are associated with the same
+heterogeneous work-group. There may be hardware address swizzle logic
+that allows regular global virtual memory to be allocated per
+heterogeneous lane such that they have a linear address view, which in
+fact maps to an interleaved global virtual memory access to improve
+cache performance.
+
+@value{GDBN} provides these facilities for debugging heterogeneous
+programs:
+
+@itemize @bullet
+
+@item @code{info sharedlibrary}, command supports code objects for
+multiple architectures
+
+@item debugger convenience variables for heterogeneous entities
+
+@item @code{set architecture}, @code{show architecture}, @code{x/i},
+@code{disassemble}, commands to disassemble multiple architectures in
+the same inferior
+
+@item @code{info threads}, @code{thread}, commands support threads
+executing on multiple heterogeneous agents
+
+@item @code{info agents}, @code{info queues}, @code{info packets},
+@code{info dispatches}, commands to inquire about the heterogeneous
+system
+
+@item @code{info lanes}, @code{lane}, commands support source language
+threads of execution that are mapped to SIMD-like lanes of a thread
+
+@item @code{$_thread_find}, @code{$_thread_find_first_gid},
+@code{$_lane_find}, @code{$_lane_find_first_gid} debugger convenience
+functions can find threads and heterogeneous lanes associated with
+specific heterogeneous entities
+
+@item @code{maint print address-spaces}, command together with address
+qualifiers supports multiple address spaces
+
+@end itemize
+
+A heterogeneous system may use separate code objects for the different
+target architectures of the heterogeneous agents. The @code{info
+sharedlibrary} command lists all the code objects currently loaded,
+regardless of their target architecture.
+
+The following rules apply in determining the target architecture used
+by commands when debugging heterogeneous programs:
+
+@enumerate
+
+@item
+Typically the target architecture of the heterogeneous host agent is
+the target architecture of the program's code object. The @code{set
+architecture} command (@pxref{Targets,,Specifying a Debugging Target})
+can be used to change this target architecture. The target
+architecture of other heterogeneous agents is typically the target
+architecture of the associated device.
+
+@item
+The target architecture of a thread is the target architecture of the
+selected stack frame. Typically stack frames will have the same
+target architecture as the heterogeneous agent on which the thread was
+created, however, a target may assocociate different target
+architectures for different stack frames.
+
+@item
+The current target architecture is the target architecture of the
+selected thread, or the target architecture of the heterogeneous host
+agent if there are no threads.
+
+@end enumerate
+
+@value{GDBN} handles the heterogeneous agent, queue, and dispatch
+entities in a similar manner to threads (@pxref{Threads}):
+
+@itemize @bullet
+
+@item
+For debugging purposes, @value{GDBN} associates its own number
+---always a single integer---with each heterogeneous entity of an
+inferior. This number is unique between all instances of
+heterogeneous entities of an inferior, but not unique between
+heterogeneous entities of different inferiors.
+
+@item
+You can refer to a given heterogeneous entity in an inferior using the
+qualified @var{inferior-num}.@var{heterogeneous-entity-num} syntax,
+also known as a @dfn{qualified heterogeneous entity ID}, with
+@var{inferior-num} being the inferior number and
+@var{heterogeneous-entity-num} being the heterogeneous entity number
+of the given inferior. If you omit @var{inferior-num}, then
+@value{GDBN} infers you're referring to a heterogeneous entity of the
+current inferior.
+
+@item
+Until you create a second inferior, @value{GDBN} does not show the
+@var{inferior-num} part of heterogeneous entity IDs, even though you
+can always use the full
+@var{inferior-num}.@var{heterogeneous-entity-num} form to refer to
+heterogeneous entities of inferior 1, the initial inferior.
+
+@item
+@anchor{heterogeneous entity ID list}
+@cindex heterogeneous entity ID list
+Some commands accept a space-separated @dfn{heterogeneous entity ID
+list} as argument. The list element has the same forms as for thread
+ID lists. @xref{thread ID list}.
+
+@item
+@anchor{global heterogeneous entity numbers} In addition to a
+@emph{per-inferior} number, each heterogeneous entity is also assigned
+a unique @emph{global} number, also known as @dfn{global heterogeneous
+entity ID}, a single integer. Unlike the heterogeneous entity number
+component of the heterogeneous entity ID, no two threads have the same
+global heterogeneous entity ID, even when you're debugging multiple
+inferiors.
+
+@end itemize
+
+The following debugger convenience variables (@pxref{Convenience
+Vars,,Convenience Variables}) are related to heterogeneous debugging.
+You may find these useful in writing breakpoint conditional
+expressions, command scripts, and so forth.
+
+@table @code
+
+@item $_thread
+@itemx $_gthread
+@itemx $_thread_systag
+@itemx $_thread_name
+@xref{Convenience Vars,,Convenience Variables}.
+
+@vindex $_agent@r{, convenience variable}
+@vindex $_gagent@r{, convenience variable}
+@vindex $_queue@r{, convenience variable}
+@vindex $_gqueue@r{, convenience variable}
+@vindex $_dispatch@r{, convenience variable}
+@vindex $_gdispatch@r{, convenience variable}
+@vindex $_lane@r{, convenience variable}
+@vindex $_glane@r{, convenience variable}
+@item $_agent
+@itemx $_gagent
+@itemx $_queue
+@itemx $_gqueue
+@itemx $_dispatch
+@itemx $_gdispatch
+@itemx $_lane
+@itemx $_glane
+There are debugger convenience variables that contain the number of
+each heterogeneous entity associated with the current thread if it was
+created by a heterogeneous dispatch, or 0 otherwise. @code{$_agent},
+@code{$_queue}, and @code{$_dispatch} contain the corresponding
+per-inferior heterogeneous entity number. While @code{$_gagent},
+@code{$_gqueue}, and @code{$_gdispatch}, contain the corresponding
+global heterogeneous entity number.
+
+@vindex $_lane@r{, convenience variable}
+@vindex $_glane@r{, convenience variable}
+@item $_lane
+@itemx $_glane
+The heterogeneous lane number of the current lane of the current thread.
+@code{$_lane} contains the corresponding per-inferior heterogeneous lane
+number. While @code{$_glane} contains the corresponding global
+heterogeneous lane number. If the current thread does not have multiple
+heterogeneous lanes, it is treated as if it has a single heterogeneous
+lane number.
+
+@vindex $_dispatch_pos@r{, convenience variable}
+@item $_dispatch_pos
+The heterogeneous dispatch position string of the current thread within
+its associated heterogeneous dispatch if it is was created by a
+heterogeneous dispatch, or the empty string otherwise. The format
+varies depending on the heterogeneous system and target architecture
+of the heterogeneous agent. @xref{Architectures}.
+
+@vindex $_lane_name@r{, convenience variable}
+@item $_lane_name
+The heterogeneous lane name string of the current heterogeneous lane, or
+the empty string if no name has been assigned by the @code{lane name}
+command.
+
+@vindex $_thread_workgroup_pos@r{, convenience variable}
+@vindex $_lane_workgroup_pos@r{, convenience variable}
+@item $_thread_workgroup_pos
+@item $_lane_workgroup_pos
+The heterogeneous work-group position string of the current thread or
+heterogeneous lane within its associated heterogeneous dispatch if it
+is was created by a heterogeneous dispatch, or the empty string
+otherwise. The format varies depending on the heterogeneous system
+and target architecture of the heterogeneous agent.
+@xref{Architectures}.
+
+@vindex $_lane_systag@r{, convenience variable}
+@item $_lane_systag
+The target system's heterogeneous lane identifier (@var{lane_systag})
+string of the current heterogeneous lane. @xref{target system lane
+identifier}.
+
+@end table
+
+The following debugger convenience functions (@pxref{Convenience
+Funs,,Convenience Functions}) are related to heterogeneous debugging.
+Given the very large number of threads on heterogeneous systems, these
+may be very useful. They allow threads or thread lists to be
+specified based on the target system's thread identifier
+(@var{systag}) or thread name, and allow heterogeneous lanes or
+heterogeneous lane lists to be specified based on the target system's
+heterogeneous lane identifier (@var{lane_systag}) or heterogeneous
+lane name.
+
+@table @code
+
+@item $_thread_find
+@itemx $_thread_find_first_gid
+@xref{Convenience Funs,,Convenience Functions}.
+
+@findex $_lane_find@r{, convenience function}
+@item $_lane_find(@var{regex})
+Searches for heterogeneous lanes whose name or @var{lane_systag}
+matches the supplied regular expression. The syntax of the regular
+expression is that specified by @code{Python}'s regular expression
+support.
+
+Returns a string that is the space separated list of per-inferior
+heterogeneous lane numbers of the found heterogeneous lanes. If
+debugging multiple inferiors, the heterogeneous lane numbers are
+qualified with the inferior number. If no heterogeneous lane are
+found, the empty string is returned. The string can be used in
+commands that accept a heterogeneous lane ID list.
+@xref{heterogeneous entity ID list}.
+
+For example, the following command lists all heterogeneous lanes that
+are part of a heterogeneous work-group with work-group position
+@samp{(1,2,3)} (@pxref{Heterogeneous Debugging}):
+
+@smallexample
+(@value{GDBP}) info lanes $_thread_find ("work-item(1,2,3)")
+@end smallexample
+
+@item $_lane_find_first_gid(@var{regex})
+@findex $_lane_find_first_gid@r{, convenience function}
+Similar to the @code{$_lane_find} convenience function, except it
+returns a number that is the global heterogeneous lane number of one
+of the heterogeneous lanes found, or 0 if no heterogeneous lanes were
+found. The number can be used in commands that accept a global
+heterogeneous lane number. @xref{global heterogeneous entity
+numbers}.
+
+For example, the following command sets the current heterogeneous lane
+to one of the heterogeneous lanes that are part of a heterogeneous
+work-group with work-item position @samp{(1,2,3)}:
+
+@smallexample
+(@value{GDBP}) lane -gid $_lane_find_first_gid ("work-item(1,2,3)")
+@end smallexample
+
+@end table
+
+The following commands are related to heterogeneous debugging:
+
+@table @code
+
+@item info agents @r{[}-gid@r{]} @r{[}@var{agent-id-list}@r{]}
+@itemx info queues @r{[}-gid@r{]} @r{[}@var{queue-id-list}@r{]}
+@itemx info dispatches @r{[}-gid@r{]} @r{[}@var{dispatch-id-list}@r{]}
+@kindex info agents
+@kindex info queues
+@kindex info dispatches
+@code{info agents}, @code{info queues} and @code{info dispatches}
+commands display information about one or more heterogeneous agents,
+heterogeneous queues and executing heterogeneous dispatches
+respectively. With no arguments displays information about all
+corresponding heterogeneous entities. You can specify the list of
+heterogeneous entities that you want to display using the
+heterogeneous entity ID list syntax (@pxref{heterogeneous entity ID
+list}).
+
+@value{GDBN} displays for each heterogeneous entity (in this order):
+
+@enumerate
+@item
+the per-inferior heterogeneous entity number assigned by @value{GDBN}
+
+@item
+the global heterogeneous entity number assigned by @value{GDBN}, if
+the @w{@option{-gid}} option was specified
+
+@item
+for the @code{info queues} and @code{info dispatches} commands, the
+associated heterogeneous agent number assigned by @value{GDBN},
+displayed as a global ID if the @w{@option{-gid}} option was
+specified, otherwise displayed as the per-inferior ID
+
+@item
+for the @code{info dispatches} command, the associated heterogeneous
+queue number assigned by @value{GDBN}, displayed as a global ID if the
+@w{@option{-gid}} option was specified, otherwise displayed as the
+per-inferior ID
+
+@item
+additional information about the heterogeneous entity that varies
+depending on the heterogeneous system and may vary depending on the
+target architecture of the heterogeneous entity
+(@pxref{Architectures})
+
+@end enumerate
+
+Some heterogeneous agents may not be listed until the inferior has
+started execution of the program.
+
+@item info packets @r{[}-gid@r{]} @r{[}@var{queue-id-list}@r{]}
+@kindex info packets
+Display information about the heterogeneous packets on one or more
+heterogeneous queues. With no arguments displays information about
+all heterogeneous queues. You can specify the list of heterogeneous
+queues that you want to display using the heterogeneous queue ID list
+syntax (@pxref{heterogeneous entity ID list}).
+
+Since heterogeneous agents may be processing heterogeneous packets
+asynchronously, the display is at best a snapshot, and may be
+inconsistent due to the heterogeneous queues being updated while they
+are being inspected.
+
+The heterogeneous packets are listed contiguously for each
+heterogeneous agent, and for each heterogeneous queue of that
+heterogeneous agent, with the oldest packet first.
+
+@value{GDBN} displays for each heterogeneous packet (in this order):
+
+@enumerate
+@item
+the associated heterogeneous agent number assigned by @value{GDBN},
+displayed as a global ID if the @w{@option{-gid}} option was
+specified, otherwise displayed as the per-inferior ID
+
+@item
+the associated heterogeneous queue number assigned by @value{GDBN},
+displayed as a global ID if the @w{@option{-gid}} option was
+specified, otherwise displayed as the per-inferior ID
+
+@item
+the packet position in the heterogeneous queue, with the oldest one
+being 1
+
+@item
+additional information about the heterogeneous packet that varies
+depending on the heterogeneous system and may vary depending on the
+target architecture of the heterogeneous entity
+(@pxref{Architectures})
+
+@end enumerate
+
+@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]}
+The @code{info threads} command (@pxref{Threads}) lists the threads
+created on all the heterogeneous agents.
+
+If any of the threads listed have multiple heterogeneous lanes, then
+an additional @emph{Lanes} column is displayed before the target
+system's thread identifier (@var{systag}) column. For threads that
+have multiple heterogeneous lanes, the number of heterogeneous lanes
+that are active followed by a slash and the total number of
+heterogeneous lanes of the current frame of the thread is displayed.
+Otherwise, nothing is displayed.
+
+The target system's thread identifier (@var{systag}) (@pxref{target
+system thread identifier}) for threads associated with heterogeneous
+dispatches varies depending on the heterogeneous system and target
+architecture of the heterogeneous agent. However, it typically will
+include information about the heterogeneous agent, heterogeneous
+queue, heterogeneous dispatch, heterogeneous work-group position
+within the heterogeneous dispatch, and thread position within the
+heterogeneous work-group. @xref{Architectures}.
+
+The stack frame summary displayed is for the active lanes of the
+thread. This may differ from the stack frame information for the
+current lane if the focus is on an inactive lane. Use the @code{info
+lanes} command for information about individual lanes of a thread.
+@xref{Threads}.
+
+For example,
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info threads
+ Id Lanes Target Id Frame
+* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 2 2/64 ROCm process 35 agent 1 queue 2 dispatch 3 work-group(2,3,4)/1 0x34e5 in saxpy ()
+ 3 64/64 ROCm process 65 agent 1 queue 2 dispatch 4 work-group(2,4,4)/2 0x34e5 in saxpy ()
+@end smallexample
+
+@table @code
+@cindex heterogeneous lane index
+@item thread @r{[}-gid@r{]} @var{thread-id} @r{[}@var{lane-index}@r{]}
+The @code{thread} command has an optional @var{lane-index} argument to
+specify the @dfn{heterogeneous lane index}. If the value is not
+between 1 and the number of heterogeneous lanes of the current frame
+of the thread, then @value{GDBN} will print an error. If omitted it
+defaults to 1.
+
+The current thread is set to @var{thread-id} and the current
+heterogeneous lane is set to the heterogeneous lane corresponding to
+the specified heterogeneous lane index.
+
+If the thread has multiple heterogeneous lanes, @value{GDBN} responds
+by displaying the system identifier of the heterogeneous lane you
+selected, otherwise it responds with the system identifier of the
+thread you selected, followed by its current stack frame summary.
+
+@item thread apply @r{[}@var{thread-id-list} @r{|} all @r{[}-ascending@r{]]} @r{[}@var{flag}@r{]@dots{}} @var{command}
+@itemx taas [@var{option}]@dots{} @var{command}
+@itemx tfaas [@var{option}]@dots{} @var{command}
+@itemx thread name
+@itemx thread find
+These commands operate the same way for all threads, regardless of
+whether or not the thread is associated with a heterogeneous dispatch.
+
+If the thread's frame has multiple heterogeneous lanes then the
+heterogeneous lane index 1 is used. Use the heterogeneous lane
+counterpart commands if it is desired to perform the the @var{command}
+on each lane of a thread.
+
+@xref{Threads}.
+
+@cindex lane identifier (system)
+@item info lanes @r{[}-gid@r{]} @var{lane-id}
+Display information about one or more heterogeneous lanes. With no
+arguments displays information about all heterogeneous lanes. You can
+specify the list of heterogeneous lanes that you want to display using
+the heterogeneous lane ID list syntax (@pxref{heterogeneous entity ID
+list}).
+
+@value{GDBN} displays for each heterogeneous lane (in this order):
+
+@enumerate
+@item
+The per-inferior heterogeneous lane number assigned by @value{GDBN}.
+
+@item
+The global heterogeneous lane number assigned by @value{GDBN}, if the
+@w{@option{-gid}} option was specified.
+
+@item
+The thread number assigned by @value{GDBN} for the thread that
+contains the heterogeneous lane. This is displayed as a global thread
+number if the @w{@option{-gid}} option was specified, otherwise as a
+per-inferior thread number. If the thread has multiple heterogeneous
+lanes then this is followed by a slash and the heterogeneous lane
+index of the heterogeneous lane within the thread with the first lane
+being 1.
+
+@item
+An indication of whether the heterogeneous lane is active or inactive.
+
+@anchor{target system lane identifier}
+@item
+The target system's heterogeneous lane identifier (@var{lane_systag}).
+This varies depending on the system and target architecture of the
+heterogeneous agent. However, for heterogeneous agents it typically
+will include information about the heterogeneous agent, heterogeneous
+queue, heterogeneous dispatch, heterogeneous work-group position
+within the heterogeneous dispatch, and position of the heterogeneous
+lane in the heterogeneous work-group. @xref{Architectures}.
+
+@item
+The heterogeneous lane's name, if one is assigned by the user (see
+@code{lane name}, below).
+
+@item
+The current stack frame summary for that heterogeneous lane. If the
+heterogeneous lane is inactive this is the source position at which the
+heterogeneous lane will resume.
+@end enumerate
+
+@noindent
+An asterisk @samp{*} to the left of the @value{GDBN} heterogeneous
+lane number indicates the current heterogeneous lane.
+
+For example,
+@end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info lanes
+ Id Thread Active Target Id Frame
+* 1 4 Y process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 2 5/2 Y ROCm process 35 agent 1 queue 2 dispatch 3 work-group(2,3,4) work-item(1,2,4) 0x34e5 in saxpy ()
+ 3 6/12 N ROCm process 65 agent 1 queue 2 dispatch 4 work-group(2,4,4) work-item(1,2,3) 0x34e5 in saxpy ()
+@end smallexample
+
+If you're debugging multiple inferiors, @value{GDBN} displays
+heterogeneous lane IDs using the qualified
+@var{inferior-num}.@var{lane-num} format. Otherwise, only
+@var{lane-num} is shown.
+
+If you specify the @w{@option{-gid}} option, @value{GDBN} displays a
+column indicating each heterogeneous lane's global heterogeneous lane
+ID, and displays the thread's global thread number:
+
+@smallexample
+(@value{GDBP}) info lanes -gid
+ Id GId Thread Active Target Id Frame
+* 1.1 1 4 Y process 35 thread 13 main (argc=1, argv=0x7ffffff8)
+ 1.2 3 5/2 Y ROCm process 35 agent 1 queue 2 dispatch 3 work-group(2,3,4) work-item(1,2,4) 0x34e5 in saxpy ()
+ 2.1 1 4 Y process 65 thread 1 main (argc=1, argv=0x7ffffff8)
+ 2.2 4 6/12 N ROCm process 65 agent 1 queue 2 dispatch 4 work-group(2,4,4) work-item(1,2,3) 0x34e5 in saxpy ()
+@end smallexample
+
+@table @code
+@kindex lane
+@item lane @r{[}-gid@r{]} @var{lane-id}
+Make heterogeneous lane ID @var{lane-id} the current heterogeneous
+lane and the thread that contains the heterogeneous lane the current
+thread. The command argument @var{lane-id} is the @value{GDBN}
+heterogeneous lane ID: if the @w{@option{-gid}} option is given it is
+a global heterogeneous lane identifier, as shown in the second field
+of the @code{info lanes -gid} display; otherwise it is a per-inferior
+heterogeneous lane identifier, with or without an inferior qualifier
+(e.g., @samp{2.1} or @samp{1}), as shown in the first field of the
+@code{info lanes} display.
+
+@value{GDBN} responds by displaying the system identifier of the
+heterogeneous lane you selected, and its current stack frame summary:
+
+@smallexample
+(@value{GDBP}) lane 2
+[Switching to lane 2 (Thread 0xb7fdab70 (LWP 12747))]
+#0 some_function (ignore=0x0) at example.c:8
+8 printf ("hello\n");
+@end smallexample
+
+@noindent
+As with the @samp{[New @dots{}]} message, the form of the text after
+@samp{Switching to} depends on your system's conventions for identifying
+heterogeneous lanes.
+
+@kindex lane name
+@cindex name a heterogeneous lane
+@anchor{heterogeneous lane name}
+@item lane name [@var{name}]
+This command assigns a name to the current heterogeneous lane. If no
+argument is given, any existing user-specified name is removed. The
+heterogeneous lane name appears in the @code{info lanes} display.
+
+@kindex lane find
+@cindex search for a heterogeneous lane
+@anchor{lane find}
+@item lane find [@var{regexp}]
+Search for and display heterogeneous lane ids whose name or
+@var{lane_systag} matches the supplied regular expression. The syntax
+of the regular expression is that specified by @code{Python}'s regular
+expression support.
+
+As well as being the complement to the @code{lane name} command, this
+command also allows you to identify a heterogeneous lane by its target
+@var{lane_systag}. For instance, on @acronym{AMD ROCm}, the target
+@var{lane_systag} is the heterogeneous agent, heterogeneous queue,
+heterogeneous dispatch, heterogeneous work-group position and
+heterogeneous work-item position.
+
+@smallexample
+(@value{GDBP}) lane find "work-group(2,3,4)"
+Lane 2 has lane id 'ROCm process 35 agent 1 queue 2 dispatch 3 work-group(2,3,4) work-item(1,2,4)'
+(@value{GDBP}) info lane 2
+ Id Thread Active Target Id Frame
+ 2 5/2 Y ROCm process 35 agent 1 queue 2 dispatch 3 work-group(2,3,4) work-item(1,2,4) 0x34e5 in saxpy ()
+@end smallexample
+
+@c FIXME-implementors!! Perhaps better ways to find lanes and threads
+@c would be beneficial. If the @var{systag} and ${lane_systag} were
+@c considered as tuples and not a plain strings, structured queries
+@c could be used. Maybe that would also support the sort order of the
+@c returned list. SQL is an example to examine.
+@c
+@c User defined pretty printing functions could be allowed so that
+@c users can control how @var{systag} and ${lane_systag} values are
+@c displayed in commands that display them. This would allow cater to
+@c situations that benefit from full verbose output, and those where
+@c partial terse output is all that is needed. But the underlying
+@c @var{systag} and ${lane_systag} values always have the full
+@c information.
+@c
+@c Ways for commands that list lanes and threads to aggregate the
+@c output would be beneficial in heterogeneous systems that tend to
+@c have very large counts. For example, all lanes that have adjacent
+@c dispatch postions, and that are at the same source postion, could
+@c be displayed as a single row that specifies the range of postions.
+@c Perhaps target or user defined functions could be allowed to guide
+@c the aggregation, and return the aggregated range. That would allow
+@c different heterogeneous system to be supported that had different
+@c ways to represent dispatch positions. There may even be multiple
+@c ways to aggregate on some system.
+
+@item lane apply @r{[}@var{thread-id-list} @r{|} all @r{[}-ascending@r{]]} @r{[}@var{flag}@r{]@dots{}} @var{command}
+@itemx laas [@var{option}]@dots{} @var{command}
+@itemx lfaas [@var{option}]@dots{} @var{command}
+@code{lane apply}, @code{laas}, and @code{lfass} commands are simalar
+to their thread counterparts @code{thread apply}, @code{taas}, and
+@code{tfaas} respectively, except they operatate on heterogeneous
+lanes. @xref{Threads}.
+
+@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
+@itemx frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command}
+@itemx select-frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx up-silently @var{n}
+@itemx down-silently @var{n}
+@itemx info frame
+@itemx info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+@itemx info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
+@itemx faas @var{command}
+The frame commands apply to the current heterogeneous lane.
+
+If the frame is switched from one that has multiple heterogeneous
+lanes to one with fewer (including only one) then the current lane is
+switched to the heterogeneous lane corresponding to the highest
+heterogeneous lane index of the new frame and @value{GDBN} responds by
+displaying the system identifier of the heterogeneous lane selected.
+
+@xref{Stack, ,Examining the Stack}.
+
+@item set libthread-db-search-path
+@itemx show libthread-db-search-path
+@itemx set debug libthread-db
+@itemx show debug libthread-db
+These commands only apply to threads created on the heterogeneous host
+agent that are not associated with a heterogeneous dispatch. There
+are no commands that support reporting of heterogeneous dispatch
+thread events.
+
+@item x/i
+@itemx display/i
+The @code{x/i} and @code{display/i} commands (@pxref{Memory,,Examining
+Memory}) can be used to disassemble machine instructions. They use
+the current target architecture.
+
+@item disassemble
+The @code{disassemble} command (@pxref{Machine Code,,Source and
+Machine Code}) can also be used to disassemble machine instructions.
+If the start address of the range is within a loaded code object, then
+the target architecture of the code object is used. Otherwise, the
+current target architecture is used.
+
+@c FIXME-implementors!! It would be more helpful if @code{set
+@c architecture} was an inferior setting used by both @code{x/i} and
+@c @code{disassemble} when not set to @code{auto}. When set to
+@c @code{auto} then the architecture of the code object containing the
+@c start address should be used by both commands. Otherwise, the
+@c thread target architecture should be used, or the heterogeneous host
+@c agent target architecture if there are no threads. That way a user
+@c can choose what architecture to disassemble in, and will get
+@c sensible behavior if they specify the default of @code{auto} even
+@c for heterogeneous systems.
+
+@item info registers
+@itemx info all-registers
+@itemx maint print reggroups
+The register commands display information about the current
+architecture.
+
+@item print
+The @code{print} command evaluates the source language expression in
+the context of the current heterogeneous lane.
+
+@item step
+@itemx next
+@itemx finish
+@itemx until
+@itemx stepi
+@itemx nexti
+If the current heterogeneous lane is set to an inactive heterogeneous
+lane, then the @code{step}, @code{next}, @code{finish} and
+@code{until} commands (@pxref{Continuing and Stepping, ,Continuing and
+Stepping}) may cause other heterogeneous lanes of the same thread to
+advance so that the current heterogeneous lane becomes active. This
+may result in other heterogeneous lanes completing whole functions.
+
+If the current heterogeneous lane is set to an inactive heterogeneous
+lane, then the @code{stepi} and @code{nexti} commands
+(@pxref{Continuing and Stepping, ,Continuing and Stepping}) may not
+cause the source position to appear to move until execution reaches a
+point that makes the current heterogeneous lane active. However,
+other heterogeneous lanes of the same thread will advance.
+
+@item break @r{[}-lane @var{lane-index}@r{]} @r{[}location@r{]} @r{[}if @var{cond}@r{]}
+@itemx tbreak @r{[}-lane @var{lane-index}@r{]} @r{[}location@r{]} @r{[}if @var{cond}@r{]}
+@itemx hbreak @r{[}-lane @var{lane-index}@r{]} @r{[}location@r{]} @r{[}if @var{cond}@r{]}
+@itemx thbreak @r{[}-lane @var{lane-index}@r{]} @r{[}location@r{]} @r{[}if @var{cond}@r{]}
+@itemx rbreak @r{[}-lane @var{lane-index}@r{]} @var{regex}
+@itemx info breakpoints @r{[}@var{list}@dots{}@r{]}
+@itemx watch @r{[}-lane @var{lane-index}@r{]} @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@itemx rwatch @r{[}-lane @var{lane-index}@r{]} @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@itemx awatch @r{[}-lane @var{lane-index}@r{]} @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@itemx info watchpoints @r{[}@var{list}@dots{}@r{]}
+@itemx catch @r{[}-lane @var{lane-index}@r{]} @var{event}
+@itemx tcatch @r{[}-lane @var{lane-index}@r{]} @var{event}
+When a breakpoint, watchpoint, or catchpoint (@pxref{Breakpoints,
+,Breakpoints; Watchpoints; and Catchpoints}) is hit by a frame of a
+thread with multiple heterogeneous lanes, each active lane is treated
+independently:
+
+@itemize @bullet
+
+@item
+The breakpoint condition, if present, is evaluated for each active
+heterogeneous lane.
+
+@item
+The breakpoint command, if present, is evaluated for each active
+heterogeneous lane that evaluates the breakpoint condition to true.
+
+@item
+If the breakpoint causes the heterogeneous lane to halt then he
+current heterogeneous lane is set to the halting heterogeneous lane
+and @value{GDBN} responds by displaying the system identifier of the
+heterogeneous lane selected.
+
+@item
+If the breakpoint is a temporary breakpoint, then it will be removed,
+and so any remaining heterogeneous lanes will not report the
+breakpoint.
+
+@item
+In non-stop mode all heterogeneous lanes that halt at the breakpoint
+will be reported.
+
+@item
+In all-stop mode, continuing from the breakpoint will cause the next
+heterogeneous ative lane that hit the breakpoint to be processed.
+
+@end itemize
+
+If a heterogeneous lane causes a thread to halt, then the other
+heterogeneous lanes of the thread will no longer execute even if in
+non-stop mode.
+
+For @code{break}, @code{watch}, @code{catch}, and their variants, the
+@w{@option{-lane @var{lane-index}}} option can be specified. This
+limits @value{GDBN} to only process breakpoints if the heterogeneous
+lane has a heterogeneous lane index that matches @var{lane-index}.
+
+The @code{info break} and @code{info watch} commands add a @emph{Lane}
+column before the @emph{Address} column if any breakoint has a
+@var{lane-index} specified that displays the heterogeneous lane index.
+
+@c FIXME-implementors!! Should there be way to request all pending
+@c breakpoints to be processed? This may result in multiple
+@c lanes/threads being reported as halted. This would avoid the user
+@c having to continue a very large number of times to get all the
+@c threads/lanes that have unprocessed breakpoints to be processed.
+@c
+@c In addition, a way to list all the theards/lanes that are halted at
+@c a breakpoint. If this was avaiable as a conveniece function, then
+@c the @code{thread apply} and @code{lane apply} commands could be
+@c used to perform a command on all such threads in one action.
+
+@anchor{maint print address-spaces}
+@c FIXME-implementers!! This is not a maintenance command as it is
+@c displaying imformation about available address spaces that can be
+@c used. It has been defined as a @code{maint} command only to match
+@c the @code{maint print reggroups} command which also should not be a
+@c maintenace command for the same reason.
+@item maint print address-spaces @r{[}@var{file}@r{]}
+@code {maint print address-spaces} displays the address space names
+supported by each target achitecture. The optional argument
+@var{file} tells to what file to write the information.
+
+The address spaces info looks like this:
+
+@smallexample
+(@value{GDBP}) @kbd{maint print address-spaces}
+ Class Arch
+ global All
+ group AMDGPU
+ private AMDGPU
+ generic AMDGPU
+@end smallexample
+
+The @var{global} address space corresponds to the default global
+virtual memory address space and is available for all target
+architectures.
+
+Every address entered or displayed can optionally specify the address
+space qualifier by appending an @samp{@@} followed by an address space
+name. @value{GDBN} will print an error if the address space name is
+not supported by the current architecture.
+
+For example,
+
+@smallexample
+(@value{GDBP}) x/x 0x10021608@@group
+0x10021608@@group: 0x0022fd98
+@end smallexample
+
+@c FIXME-implementors!! Perhaps the gdb internal types (such as used
+@c for register types) can be extended to support addresses in address
+@c spaces.
+
+If there is no current thread then the only address space that can be
+specified is @var{global}.
+
+If entering an address and no address space is specified, the
+@var{global} address space is used.
+
+If an address is displayed, the address space qualifier is omitted for
+the @var{global} address space.
+
+@end table
+
+Heterogeneous systems often have very large numbers of threads.
+Breakpoint conditions can be used to limit the number of threads
+reporting breakpoint hits. For example,
+
+@smallexample
+break kernel_foo if $_streq($_lane_workgroup_pos, "(0,0,0)")
+@end smallexample
+
+The @code{tbreak} command can be used so only one heterogeneous lane
+will report the breakpoint. Before continuing execution, the
+breakpoint will need to be set again if necessary.
+
+The @code{set scheduler-locking on} command together with the
+@w{@option{-lane}} breakpoint option can be used to lock @value{GDBN}
+to only resume the current thread, and only report breakoints for a
+fixed heterogeneous lane index. This avoids the overhead of resuming
+a large number of threads every time resuming from a breakpoint, and
+also avoids the focus being switched to other threads that hit the
+breakpoints. Note however that other threads will not be executed.
+
+@c TODO:
+@c Change command parsing so convienence variable
+@c substitution will work as shown. Investigate using tuples and
+@c lists the result of convienence variables and convienence
+@c functions.
+@c Update MI commands for heterogeneous commands.
+@c Update Python bindings for heterogeneous commands.
+@c Update gdbserver remote protocol for heterogeneous commands.
@node Remote Debugging
@chapter Debugging Remote Programs
with ssh:
@smallexample
-(gdb) target remote | ssh -T hostname gdbserver - hello
+(@value{GDBP}) target remote | ssh -T hostname gdbserver - hello
@end smallexample
The @samp{-T} option to ssh is provided because we don't need a remote pty,
tty for standard input and output as well as two network sockets:
@smallexample
-(gdb) info proc files 22136
+(@value{GDBP}) info proc files 22136
process 22136
Open files:
* Nios II::
* Sparc64::
* S12Z::
+* AMD GPU:: @acronym{AMD GPU} architectures
@end menu
@node AArch64
BDCCSR register.
@end table
+@node AMD GPU
+@subsection @acronym{AMD GPU}
+@cindex @acronym{AMD GPU} support
+
+@value{GDBN} provides support for systems that have heterogeneous
+agents associated with @acronym{AMD GPU} devices (@pxref{Heterogeneous
+Debugging}) when @acronym{AMD}'s
+@url{https://rocm-documentation.readthedocs.io/, @acronym{ROCm, Radeon
+Open Compute platforM}} for HIP-Clang is installed.
+
+The following AMD commercial GPUs are supported:
+
+@itemize @bullet{}
+
+@item
+AMD GPUs previously code-named ``Vega 10'', also denoted as gfx900
+
+@item
+AMD GPUs previously code-named ``Vega 20'', also denoted as gfx906
+
+@item
+AMD GPUs code-named ``Arcturus'', also denoted as gfx908
+
+@end itemize
+
+@value{GDBN} supports the following source languages:
+
+@table @emph
+
+@item HIP
+The
+@url{https://github.com/ROCm-Developer-Tools/HIP/blob/master/docs/markdown/hip_kernel_language.md,
+HIP Programming Language} is supported.
+
+When compiling, the @w{@option{-ggdb}} option should be used to
+produce debugging information suitable for use by @value{GDBN}. The
+@w{@option{--amdgpu-target}} option is used to specify the AMD GPUs
+that the executable is required to support. For example, to compile a
+HIP program that can utilize ``Vega 10'', ``Vega 20'', and
+``Arcturus'' AMD GPUs, with no optimization:
+
+@smallexample
+hipcc -O0 -ggdb --amdgpu-target=gfx900 --amdgpu-target=gfx906 \
+ --amdgpu-target=gfx908 bit_extract.cpp -o bit_extract
+@end smallexample
+
+The AMD GPU ROCm for HIP-Clang release compiler maps HIP source
+language work-items to the lanes of an AMD GPU wavefront, which are
+represented in @value{GDBN} as heterogeneous lanes.
+
+@item Assembly Code
+Assembly code kernels are supported.
+
+@item Other Languages
+Other languages, including OpenCL and Fortran, are currently supported
+as the minimal pseudo-language, provided they are compiled specifying
+the AMD GPU Code Object V3 and DWARF 4 formats. @xref{Unsupported
+Languages}.
+
+@end table
+
+The @code{info agents} command (@pxref{Heterogeneous Debugging}) lists
+the following information for each @acronym{AMD GPU} heterogeneous
+agent (in this order):
+
+@enumerate
+@item
+the per-inferior heterogeneous agent number assigned by @value{GDBN}
+
+@item
+the global heterogeneous agent number assigned by @value{GDBN}, if the
+@w{@option{-gid}} option was specified
+
+@item
+the @acronym{PCIe} slot number in @acronym{BDF, Bus:Device.Function}
+notation
+
+@item
+the device name
+
+@item
+the number of shader engines
+
+@item
+the number of @acronym{CU, Compute Unit}
+
+@item
+the number of @acronym{SIMD, Single Instruction Multiple Data} units per @acronym{CU}
+
+@item
+the number of wavefronts per @acronym{SIMD}
+
+@end enumerate
+
+For example,
+
+@smallexample
+(@value{GDBP}) info agents
+Id PCI Slot Device Name Shader Engines Compute Units SIMD/CU Wavefronts/SIMD
+1 43:00.0 vega10 4 56 4 10
+@end smallexample
+
+@acronym{AMD GPU} heterogeneous agents are not listed until the
+inferior has started executing the program.
+
+The @code{info queues}, @code{info dispatches}, and @code{info
+packets} commands are not yet supported by @acronym{AMD GPU}.
+
+An AMD GPU wavefront is represented in @value{GDBN} as a thread.
+
+@acronym{AMD GPU} supports the following @var{reggroup} values for the
+@samp{info registers @var{reggroup} @dots{}} command:
+
+@itemize @bullet
+
+@item
+general
+
+@item
+vector
+
+@item
+scalar
+
+@item
+system
+
+@end itemize
+
+The number of scalar and vector registers is configured when a
+wavefront is created. Only allocated registers are displayed. Scalar
+registers are reported as 32-bit signed integer values. Vector
+registers are reported as a wavefront size vector of signed 32-bit
+values. The @code{pc} is reported as a function pointer value. The
+@code{exec} register is reported as a wavefront size-bit unsigned
+integer value. The @code{vcc} and @code{xnack_mask} pseudo registers
+are reported as a wavefront size-bit unsigned integer value. The
+@code{flat_scratch} pseudo register is reported as a 64-bit unsigned
+integer value.
+
+AMD GPU code objects are loaded into each AMD GPU device separately.
+The @code{info sharedlibrary} command will therefore show the same
+code object loaded multiple times. As a consequence, setting a
+breakpoint in AMD GPU code will result in multiple breakpoints if
+there are multiple AMD GPU devices.
+
+If the source language runtime defers loading code objects until
+kernels are launched, then setting breakpoints may result in pending
+breakpoints that will be set when the code object is finally loaded.
+
+Threads created on @acronym{AMD GPU} heterogeneous agents have the
+following identifier formats:
+
+@table @asis
+
+@item @var{systag}
+The target system's thread identifier (@var{systag}) string has the
+following format:
+
+@smallexample
+ROCm process @var{process-num} agent @var{agent-num} queue @var{queue-num} dispatch @var{dispatch-num} work-group(@var{work-group-x},@var{work-group-y},@var{work-group-z})/@var{work-group-thread-index}
+@end smallexample
+
+@c TODO: What order should coordinates be: x,y,z or z,y,x?
+
+@item @var{lane_systag}
+The target system's heterogeneous lane identifier (@var{lane_systag})
+string has the following format:
+
+@smallexample
+ROCm process @var{process-num} agent @var{agent-num} queue @var{queue-num} dispatch @var{dispatch-num} work-group(@var{work-group-x},@var{work-group-y},@var{work-group-z}) work-item(@var{work-item-x},@var{work-item-y},@var{work-item-z})
+@end smallexample
+
+@item @code{$_dispatch_pos}
+The string returned by the @code{$_dispatch_pos} debugger convenience
+variable has the following format:
+
+@smallexample
+(@var{work-group-x},@var{work-group-y},@var{work-group-z})/@var{work-group-thread-index}
+@end smallexample
+
+@item @code{$_thread_workgroup_pos}
+The string returned by the @code{$_thread_workgroup_pos} debugger
+convenience variable has the following format:
+
+@smallexample
+@var{work-group-thread-index}
+@end smallexample
+
+@item @code{$_lane_workgroup_pos}
+The string returned by the @code{$_lane_workgroup_pos} debugger
+convenience variable has the following format:
+
+@smallexample
+(@var{work-item-x},@var{work-item-y},@var{work-item-z})
+@end smallexample
+
+@end table
+
+@noindent
+Where:
+
+@table @var
+
+@item process-num
+the inferior process LWP number
+
+@item agent-num
+@itemx queue-num
+@itemx dispatch-num
+the per-inferior heterogeneous agent number, the per-inferior
+heterogeneous queue number, and the per-inferior heterogeneous
+dispatch number associated with the thread respectively
+
+@item work-group-x
+@itemx work-group-y
+@itemx work-group-z
+the grid position of the thread's work-group within the heterogeneous
+dispatch
+
+@item work-group-thread-index
+the threads's number within the heterogeneous work-group
+
+@item work-item-x
+@itemx work-item-y
+@itemx work-item-z
+the position of the heterogeneous lane's work-item within the
+heterogeneous work-group
+
+@end table
+
+@acronym{AMD GPU} heterogeneous agents support the following address
+spaces:
+
+@table @code
+
+@item global
+the default global virtual address space
+
+@item group
+the per heterogeneous work-group shared address space (@acronym{LDS,
+Local Data Store})
+
+@item private
+the per heterogeneous lane private address space (Scratch)
+
+@item generic
+the generic address space that can access the @var{global},
+@var{group}, or @var{private} address spaces (Flat)
+
+@end table
+
+The @code{set debug amd-dbgapi log-level @var{level}} command can be
+used to enable diagnostic messages for the AMD GPU target, where
+@var{level} can be:
+
+@table @code
+
+@item off
+no logging is enabled
+
+@item error
+fatal errors are reported
+
+@item warning
+fatal errors and warnings are reported
+
+@item info
+fatal errors, warnings, and info messages are reported
+
+@item verbose
+all messages are reported
+
+@end table
+
+The @code{show debug amd-dbgapi log-level} command displays the
+current AMD GPU target log level.
+
+For example, the following will enable information messages and send
+the log to a new file:
+
+@smallexample
+(@value{GDBP}) set debug amd-dbgapi log-level info
+(@value{GDBP}) set logging overwrite
+(@value{GDBP}) set logging file log.out
+(@value{GDBP}) set logging debugredirect on
+(@value{GDBP}) set logging on
+@end smallexample
+
+If you want to print the log to both the console and a file, ommit the
+@code{set the logging debugredirect} command. @xref{Logging Output}.
+
+@c TODO: Add when support available:
+@c
+@c The @var{AMD_???} environment variable can be set to disable the kernel
+@c driver from ensuring that all AMD GPU wavefronts created will fully
+@c support the @value{GDBN} if it attached. If AMD GPU wavefronts are
+@c created when support is disabled, @value{GDBN} will be unable to
+@c report the heterogeneous dispatch associated with the wavefront, or the
+@c wavefront's heterogeneous work-group position. The default is enabled.
+@c Disabling may very marginally improve wavefront launch latency.
+
+@value{GDBN} @acronym{AMD GPU} support is currently a prototype and
+has the following restrictions. Future releases may remove these
+restrictions.
+
+@enumerate
+
+@item
+The debugger convenience variables, convenience functions, and
+commands described in @ref{Heterogeneous Debugging} are not yet
+implemented. The exception is the @code{info agents} command, which
+only currently supports the textual MI interface and does not have a
+Python binding.
+
+However, the debugger convenience variable @code{$_wave_id} is
+available which returns a string that has the format:
+
+@smallexample
+(@var{work-group-z},@var{work-group-y},@var{work-group-x})/@var{work-group-thread-index}
+@end smallexample
+
+Where:
+
+@table @var
+
+@item work-group-x
+@itemx work-group-y
+@itemx work-group-z
+the grid position of the thread's work-group within the heterogeneous
+dispatch
+
+@item work-group-thread-index
+the threads's number within the heterogeneous work-group
+
+@end table
+
+The AMD GPU system's thread identifier (@var{systag}) string format
+differs from that described above, and currently has the following
+format:
+
+@smallexample
+AMDGPU Thread @var{dispatch-num}.@var{wave-num} (@var{work-group-z},@var{work-group-y},@var{work-group-x})/@var{work-group-thread-index}
+@end smallexample
+
+Where:
+
+@table @var
+
+@item dispatch-num
+the thread's per-heterogeneous queue ROCm AQL packet number of the
+associated dispatch packet
+
+@item wave-num
+the thread's per-inferior AMD GPU target wavefront number
+
+@item work-group-x
+@itemx work-group-y
+@itemx work-group-z
+the grid position of the thread's work-group within the heterogeneous
+dispatch
+
+@item work-group-thread-index
+the threads's number within the heterogeneous work-group
+
+@end table
+
+Only the @code{global} address space is implemented. Memory cannot be
+read or written in the @code{group} or @code{private} address spaces.
+The address space qualification of addresses described in
+@ref{Heterogeneous Debugging} is not implemented.
+
+@item
+The AMD GPU ROCm for HIP-Clang release compiler currently does not yet
+support generating valid DWARF information for symbolic variables and
+call frame information. As a consequence:
+
+@itemize @bullet{}
+
+@item
+Source variables or expressions cannot be specified in any command,
+such as the @code{print} command and breakpoint conditions. This
+includes static variables, local variables, function arguments, and
+any language types. However, global symbols for functions and
+variables can be specified, and source line information is available.
+
+@item
+The @code{backtrace} command can only show the current frame and
+parent frames that are fully inlined. Function or kernel arguments
+will not be displayed and instead an empty formal argument list may be
+shown.
+
+@item
+The @code{next} command may not step over function calls, but instead
+stop at the first statement of the called function.
+
+@item
+Breakpoints are only reported for wavefronts. There is no support for
+HIP work-items that are mapped to heterogeneous lanes. The HIP
+work-item ID of a heterogeneous lane is not available.
+
+@end itemize
+
+The AMD GPU ROCm for HIP-Clang release compiler currently adds the
+@w{@option{-gline-tables-only}} @w{@option{-disable-O0-noinline}}
+@w{@option{-disable-O0-optnone}} options when the @w{@option{-ggdb}}
+option is specified. These ensure source line information is
+generated, but not invalid DWARF, and full inlining is performed, even
+at @w{@option{-O0}}, so the backtrace will be available even without
+CFI information. If these options are not used the invalid DWARF may
+cause @value{GDBN} to report that it is unable to read memory (such as
+when reading arguments in a backtrace), and may limit the backtrace to
+only the top frame.
+
+Note that even with @w{@option{-ggdb}}, functions marked
+@code{noinline} may result in function call frames which will prevent
+a full backtrace. If function calls are not inlined, the @code{next}
+command may report errors inserting breakpoints when stepping over
+calls due to the invalid CFI information.
+
+@item
+Only AMD GPU Code Object V3 is supported. This is the default for the
+AMD GPU ROCm for HIP-Clang release compiler. The following error will
+be reported for incompatible code objects:
+
+@smallexample
+warning: `ROCm-supplied DSO [loaded from memory 0x2361160..0x236d9b8]': ELF file ABI version (o) is not supported.
+warning: Could not load shared library symbols for ROCm-supplied DSO [loaded from memory 0x2361160..0x236d9b8].
+@end smallexample
+
+@item
+DWARF 5 is not yet supported. There is no support for compressed or split
+DWARF.
+
+DWARF 4 is the default for the AMD GPU ROCm for HIP-Clang release
+compiler.
+
+@item
+No support yet for AMD GPU core dumps.
+
+@item
+The @code{watch} command is not yet support on AMD GPU devices.
+
+@item
+When in all-stop mode, AMD GPU does not currently prevent new
+wavefronts from being created, which may report breakpoints being hit.
+However, @value{GDBN} is configured by default to not remove
+breakpoints when at the command line in all-stop mode. This prevents
+breakpoints being missed by wavefronts created after at the command
+line in all-stop mode. The @code{set breakpoint always-inserted on}
+command can be used to change the default to remove breakpoints when
+at the command line in all-stop mode, but this may result in new
+wavefronts missing breakpoints.
+
+@item
+The performance of resuming from a breakpoint when a large number of
+threads have hit a breakpoint can currently take up to 25 seconds on a
+fully occupied single AMD GPU device. The techniques described in
+@xref{Heterogeneous Debugging} can be used to mitigate this. Once
+continued from the first breakpoint hit, the responsiveness of
+commands normally is better. Other techniques that can improve
+responsiveness are:
+
+@itemize @bullet{}
+
+@item
+Try to avoid having a lot of threads stopping at a breakpoint. For
+example, by placing breakpoints in conditional paths only executed by
+one thread.
+
+@item
+Use of @code{tbreak} so only one thread reports the breakpoint and the
+other threads hitting the breakpoint will be continued. A similar
+effect can be achieved by deleting the breakpoint manually when it is
+hit.
+
+@item
+Reduce the number of wavefronts when debugging if practical.
+
+@end itemize
+
+@item
+Currently each AMD GPU device can only be in use by one process that
+is being debugged by @value{GDBN}. The Linux @emph{cgroups} facility
+can be used to limit which AMD GPU devices are used by a process. In
+order for a @value{GDBN} process to access the AMD GPU devices of the
+process it is debugging, the AMD GPU devices must be included in the
+@value{GDBN} process @emph{cgroup}.
+
+Therefore, multiple @value{GDBN} processes can each debug a process
+provided the @emph{cgroups} specify disjoint sets of AMD GPU devices.
+However, a single @value{GDBN} process cannot debug multiple inferiors
+that use AMD GPU devices even if those inferiors have @emph{cgroups}
+that specify disjoint AMD GPU devices. This is because the
+@value{GDBN} process must have all the AMD GPU devices in its
+@emph{cgroups} and so will attempt to enable debugging for all AMD GPU
+devices for all inferiors it is debugging.
+
+The @code{HIP_VISIBLE_DEVICES} environment variable can also be used
+to limit the visible GPUs used by the HIP-Clang VDI runtime. For
+example,
+
+@smallexample
+export HIP_VISIBLE_DEVICES=0
+@end smallexample
+
+@item
+Currently the @code{flat_scratch}, @code{vcc}, and @code{xnack_mask}
+special scalar registers are only accessible using their scalar
+register numbers and not by their register names. This will not match
+the assembly source text which uses register names.
+
+@item
+The @code{until} command does not work when multiple AMD GPUs are
+present as @value{GDBN} has limitations when there are multiple code
+objects that have the same breakpoint set. The work around is to use
+@samp{tbreak @var{line}; continue}.
+
+@item
+Restarting a program in @value{GDBN} may result in the followig error
+message when setting breakpoints:
+
+@smallexample
+warning: Can't read data for section '.debug_ranges' in file 'ROCm-supplied DSO [loaded from memory 0xbe5c00..0xbe98a8]'
+@end smallexample
+
+This is due to the ROCm runtime not finalizing the loader code object
+list. Performing the @code{info sharedlibrary} command before setting
+the breakpoint ensures the code object list is updated and avoids the
+error.
+
+@item
+Currently when debugging on a ``Arcturus'' AMD GPU, @value{GDBN} may
+randomly report it is unable to halt a thread and report a fatal error
+in the @emph{dmesg} log resulting in the AMD GPU hanging.
+
+@item
+@value{GDBN} does not support following a forked process.
+
+@item
+The @code{gdbserver} is not supported.
+
+@item
+No language specific support for Fortran or OpenCL. No OpenMP
+language extension support for C, C++, or Fortran.
+
+@item
+Does not support the AMD GPU ROCm for HIP-HCC release compiler or
+runtime.
+
+@item
+AMD GPU does not currently support the compiler address, memory, or
+thread sanitizers.
+
+@end enumerate
@node Controlling GDB
@chapter Controlling @value{GDBN}
For example:
@smallexample
-set extended-prompt Current working directory: \w (gdb)
+set extended-prompt Current working directory: \w (@value{GDBP})
@end smallexample
Note that when an extended-prompt is set, it takes control of the
or disabled.
@smallexample
-(gdb) show auto-load
+(@value{GDBP}) 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
not.
@smallexample
-(gdb) info auto-load
+(@value{GDBP}) info auto-load
gdb-scripts:
Loaded Script
Yes /home/user/gdb/gdb-gdb.gdb
may not be too obvious while setting it up.
@smallexample
-(gdb) set debug auto-load on
-(gdb) file ~/src/t/true
+(@value{GDBP}) set debug auto-load on
+(@value{GDBP}) file ~/src/t/true
auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
for objfile "/tmp/true".
auto-load: Updating directories of "/usr:/opt".
Example:
@example
-(gdb) define-prefix abc
-(gdb) define-prefix abc def
-(gdb) define abc def
+(@value{GDBP}) define-prefix abc
+(@value{GDBP}) define-prefix abc def
+(@value{GDBP}) define abc def
Type commands for definition of "abc def".
End with a line saying just "end".
>echo command initial def\n
>end
-(gdb) define abc def ghi
+(@value{GDBP}) define abc def ghi
Type commands for definition of "abc def ghi".
End with a line saying just "end".
>echo command ghi\n
>end
-(gdb) define abc def
+(@value{GDBP}) define abc def
Keeping subcommands of prefix command "def".
Redefine command "def"? (y or n) y
Type commands for definition of "abc def".
End with a line saying just "end".
>echo command def\n
>end
-(gdb) abc def ghi
+(@value{GDBP}) abc def ghi
command ghi
-(gdb) abc def
+(@value{GDBP}) abc def
command def
-(gdb)
+(@value{GDBP})
@end example
@kindex dont-repeat
The following will accomplish this.
@smallexample
-(gdb) alias -a di = disas
+(@value{GDBP}) alias -a di = disas
@end smallexample
Note that aliases are different from user-defined commands.
of a command.
@smallexample
-(gdb) alias -a set print elms = set print elements
-(gdb) alias -a show print elms = show print elements
-(gdb) set p elms 20
-(gdb) show p elms
+(@value{GDBP}) alias -a set print elms = set print elements
+(@value{GDBP}) alias -a show print elms = show print elements
+(@value{GDBP}) set p elms 20
+(@value{GDBP}) show p elms
Limit on string chars or array elements to print is 200.
@end smallexample
@var{ALIAS}, just as they are normally.
@smallexample
-(gdb) alias -a set pr elms = set p ele
+(@value{GDBP}) alias -a set pr elms = set p ele
@end smallexample
Finally, here is an example showing the creation of a one word
This creates alias @samp{spe} of the command @samp{set print elements}.
@smallexample
-(gdb) alias spe = set print elements
-(gdb) spe 20
+(@value{GDBP}) alias spe = set print elements
+(@value{GDBP}) spe 20
@end smallexample
@node Interpreters
@item flushregs
This command forces @value{GDBN} to flush its internal register cache.
+@kindex maint print address-spaces
+@item maint print address-spaces @r{[}@var{file}@r{]}
+Print @value{GDBN}'s internal address space data structures. The
+optional argument @var{file} tells to what file to write the
+information. @xref{maint print address-spaces,, @code{maint print
+address-spaces}}.
+
@kindex maint print objfiles
@cindex info for known object files
@item maint print objfiles @r{[}@var{regexp}@r{]}
Here is an example of the resulting disassembly:
@smallexample
-(gdb) info addr argc
+(@value{GDBP}) info addr argc
Symbol "argc" is a complex DWARF expression:
1: DW_OP_fbreg 0
@end smallexample
One can fetch individual fields like in @samp{C}.
@smallexample
-(gdb) print $my_struct_reg.field3
+(@value{GDBP}) print $my_struct_reg.field3
$1 = 42
@end smallexample
would be printed as:
@smallexample
-(gdb) info register flags
+(@value{GDBP}) info register flags
flags 0x3 [ X LEVEL=high ]
@end smallexample
@smallexample
@ifset man
@c @file would wrap it as F</dev/ttyb>.
-(gdb) target remote /dev/ttyb
+(@value{GDBP}) target remote /dev/ttyb
@end ifset
@ifclear man
-(gdb) target remote @file{/dev/ttyb}
+(@value{GDBP}) target remote @file{/dev/ttyb}
@end ifclear
@end smallexample
communicates with the server via serial line @file{/dev/ttyb}, and:
@smallexample
-(gdb) target remote the-target:2345
+(@value{GDBP}) target remote the-target:2345
@end smallexample
@noindent
In such case use the @code{extended-remote} @value{GDBN} command variant:
@smallexample
-(gdb) target extended-remote the-target:2345
+(@value{GDBP}) target extended-remote the-target:2345
@end smallexample
The @command{gdbserver} option @option{--multi} may or may not be used in such
projects / deliverable / binutils-gdb.git / commitdiff
