This adds two new pretty-printer methods, to support random access to
children. The methods are implemented for the no-op array printer,
and DAP is updated to use this.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
There was an earlier thread about adding new methods to
pretty-printers:
https://sourceware.org/pipermail/gdb-patches/2023-June/200503.html
We've known about the need for printer extensibility for a while, but
have been hampered by backward-compatibilty concerns: gdb never
documented that printers might acquire new methods, and so existing
printers may have attribute name clashes.
To solve this problem, this patch adds a new pretty-printer tag class
that signals to gdb that the printer follows new extensibility rules.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=30816
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Rationale:
I use the mouse with my terminal to select and copy text. In gdb, I use
the mouse to select a function name to set a breakpoint, or a variable
name to print, for example.
When gdb is compiled with ncurses mouse support, gdb's TUI mode
intercepts mouse events. Left-clicking and dragging, which would
normally select text, seems to do nothing. This means I cannot select
text using my mouse anymore. This makes it harder to set breakpoints,
print variables, etc.
Solution:
I tried to fix this issue by editing the 'mousemask' call to only enable
buttons 4 and 5. However, this still caused my terminal (gnome-terminal)
to not allow text to be selected. The only way I could make it work is
by calling 'mousemask (0, NULL);'. But doing so disables the mouse code
entirely, which other people might want.
I therefore decided to make a setting in gdb called 'tui mouse-events'.
If enabled (the default), the behavior is as it is now: terminal mouse
events are given to gdb, disabling the terminal's default behavior.
If disabled (opt-in), the behavior is as it was before the year 2020:
terminal mouse events are not given to gdb, therefore the mouse can be
used to select and copy text.
Notes:
I am not attached to the setting name or its description. Feel free to
suggest better wording.
Testing:
I tested this change in gnome-terminal by performing the following steps
manually:
1. Run: gdb --args ./myprogram
2. Enable TUI: press ctrl-x ctrl-a
3. Click and drag text with the mouse. Observe no selection.
4. Input: set tui mouse-events off
5. Click and drag text with the mouse. Observe that selection works now.
6. Input: set tui mouse-events on.
7. Click and drag text with the mouse. Observe no selection.
After the series that added this command was pushed, Pedro mentioned
that the news description could easily be misinterpreted, as well as
some code and test improvements that should be made.
While fixing the test, I realized that code repetition wasn't
happening as it should, so I took care of that too.
Approved-By: Andrew Burgess <aburgess@redhat.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The amd-dbgapi library exposes a setting called "memory precision" for
AMD GPUs [1]. Here's a copy of the description of the setting:
The AMD GPU can overlap the execution of memory instructions with other
instructions. This can result in a wave stopping due to a memory violation
or hardware data watchpoint hit with a program counter beyond the
instruction that caused the wave to stop.
Some architectures allow the hardware to be configured to always wait for
memory operations to complete before continuing. This will result in the
wave stopping at the instruction immediately after the one that caused the
stop event. Enabling this mode can make execution of waves significantly
slower.
Expose this option through a new "amdgpu precise-memory" setting.
The precise memory setting is per inferior. The setting is transferred
from one inferior to another when using the clone-inferior command, or
when a new inferior is created following an exec or a fork.
It can be set before starting the inferior, in which case GDB will
attempt to apply what the user wants when attaching amd-dbgapi. If the
user has requested to enable precise memory, but it can't be enabled
(not all hardware supports it), GDB prints a warning.
If precise memory is disabled, GDB prints a warning when hitting a
memory exception (translated into GDB_SIGNAL_SEGV or GDB_SIGNAL_BUS),
saying that the stop location may not be precise.
Note that the precise memory setting also affects memory watchpoint
reporting, but the watchpoint support for AMD GPUs hasn't been
upstreamed to GDB yet. When we do upstream watchpoint support, GDB will
produce a similar warning message when stopping due to a watchpoint if
precise memory is disabled.
Add a handful of tests. Add a util proc
"hip_devices_support_precise_memory", which indicates if all devices
used for testing support that feature.
[1] 687374258a/include/amd-dbgapi.h.in (L6300-L6317)
Change-Id: Ife1a99c0e960513da375ced8f8afaf8e47a61b3f
Approved-By: Lancelot Six <lancelot.six@amd.com>
I noticed a typo in the "Basic Python" node, and when fixing it
realized that the paragraph could use a link to the block_signals
function. This patch is the result.
Approved-By: Eli Zaretskii <eliz@gnu.org>
While investigating this [1], I initially had no idea what register
"fioff" stood for, making it difficult to map it to something in the
Intel or AMD manuals. Similarly, I can imaging someone familiar with
x87 to want to print the "x87 last instruction address", and have no
clue that GDB makes it available as register "fioff". The names of the
x87 state fields don't seem to be standardized, they even change between
sections of the Intel manual (between the FSAVE, FXSAVE and XSAVE area
descriptions).
Add some details to the doc to help one map GDB register names to x87
state fields.
[1] https://inbox.sourceware.org/gdb-patches/20230908022722.430741-1-simon.marchi@efficios.com/T/#u
Change-Id: I0ea1eb648358e62da4aa87eea3515ee8a09f2762
Approved-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Pedro Alves <pedro@palves.net>
I'm looking to add some x86-specific information to the doc, but I find
the naming of this section odd. It doesn't really talk about issues, it
just gives generally useful information. Also, the sections about other
architectures don't mention "issues", just the architecture name.
Also, at least in the HTML version of the doc, the name is inconsistent
between the main table of content, where it appears as "x86
Architecture-specific Issues", and the sub-table of contents of the
"Architectures" section, where it appears as "i386".
Rename the section to just "x86".
Change-Id: I0a119ff1ab5e7b83c9afa3c3977eb085e88f52ca
Approved-By: Eli Zaretskii <eliz@gnu.org>
gdb's language code may know how to display values specially. For
example, the Rust code understands that &str is a string-like type, or
Ada knows how to handle unconstrained arrays. This knowledge is
exposed via val-print, and via varobj -- but currently not via DAP.
This patch adds some support code to let DAP also handle these cases,
though in a somewhat more generic way.
Type.is_array_like and Value.to_array are added to make Python aware
of the cases where gdb knows that a structure type is really
"array-like".
Type.is_string_like is added to make Python aware of cases where gdb's
language code knows that a type is string-like.
Unlike Value.string, these cases are handled by the type's language,
rather than the current language.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This commit extends the breakpoint mechanism to allow for inferior
specific breakpoints (but not watchpoints in this commit).
As GDB gains better support for multiple connections, and so for
running multiple (possibly unrelated) inferiors, then it is not hard
to imagine that a user might wish to create breakpoints that apply to
any thread in a single inferior. To achieve this currently, the user
would need to create a condition possibly making use of the $_inferior
convenience variable, which, though functional, isn't the most user
friendly.
This commit adds a new 'inferior' keyword that allows for the creation
of inferior specific breakpoints.
Inferior specific breakpoints are automatically deleted when the
associated inferior is removed from GDB, this is similar to how
thread-specific breakpoints are deleted when the associated thread is
deleted.
Watchpoints are already per-program-space, which in most cases mean
watchpoints are already inferior specific. There is a small window
where inferior-specific watchpoints might make sense, which is after a
vfork, when two processes are sharing the same address space.
However, I'm leaving that as an exercise for another day. For now,
attempting to use the inferior keyword with a watchpoint will give an
error, like this:
(gdb) watch a8 inferior 1
Cannot use 'inferior' keyword with watchpoints
A final note on the implementation: currently, inferior specific
breakpoints, like thread-specific breakpoints, are inserted into every
inferior, GDB then checks once the inferior stops if we are in the
correct thread or inferior, and resumes automatically if we stopped in
the wrong thread/inferior.
An obvious optimisation here is to only insert breakpoint locations
into the specific program space (which mostly means inferior) that
contains either the inferior or thread we are interested in. This
would reduce the number times GDB has to stop and then resume again in
a multi-inferior setup.
I have a series on the mailing list[1] that implements this
optimisation for thread-specific breakpoints. Once this series has
landed I'll update that series to also handle inferior specific
breakpoints in the same way. For now, inferior specific breakpoints
are just slightly less optimal, but this is no different to
thread-specific breakpoints in a multi-inferior debug session, so I
don't see this as a huge problem.
[1] https://inbox.sourceware.org/gdb-patches/cover.1685479504.git.aburgess@redhat.com/
GDB's Python documentation claims that range types have two fields,
but this is not true, and attempts to access them hit this error:
"Type is not a structure, union, enum, or function type."
This patch fixes the documentation.
Add new commands:
set debug breakpoint on|off
show debug breakpoint
This patch introduces new debugging information that prints
breakpoint location insertion and removal flow.
The debug output looks like:
~~~
(gdb) set debug breakpoint on
(gdb) disassemble main
Dump of assembler code for function main:
0x0000555555555129 <+0>: endbr64
0x000055555555512d <+4>: push %rbp
0x000055555555512e <+5>: mov %rsp,%rbp
=> 0x0000555555555131 <+8>: mov $0x0,%eax
0x0000555555555136 <+13>: pop %rbp
0x0000555555555137 <+14>: ret
End of assembler dump.
(gdb) break *0x0000555555555137
Breakpoint 2 at 0x555555555137: file main.c, line 4.
[breakpoint] update_global_location_list: insert_mode = UGLL_MAY_INSERT
(gdb) c
Continuing.
[breakpoint] update_global_location_list: insert_mode = UGLL_INSERT
[breakpoint] insert_bp_location: Breakpoint 2 (0x5565daddb1e0) at address 0x555555555137 in main at main.c:4
[breakpoint] insert_bp_location: Breakpoint -2 (0x5565dab51c10) at address 0x7ffff7fd37b5
[breakpoint] insert_bp_location: Breakpoint -5 (0x5565dab68f30) at address 0x7ffff7fe509e
[breakpoint] insert_bp_location: Breakpoint -7 (0x5565dab694f0) at address 0x7ffff7fe63f4
[breakpoint] remove_breakpoint_1: Breakpoint 2 (0x5565daddb1e0) at address 0x555555555137 in main at main.c:4 due to regular remove
[breakpoint] remove_breakpoint_1: Breakpoint -2 (0x5565dab51c10) at address 0x7ffff7fd37b5 due to regular remove
[breakpoint] remove_breakpoint_1: Breakpoint -5 (0x5565dab68f30) at address 0x7ffff7fe509e due to regular remove
[breakpoint] remove_breakpoint_1: Breakpoint -7 (0x5565dab694f0) at address 0x7ffff7fe63f4 due to regular remove
Breakpoint 2, 0x0000555555555137 in main () at main.c:4
4 }
~~~
Co-Authored-By: Christina Schimpe <christina.schimpe@intel.com>
While working on an experiment, I realized that I needed the DAP
block_signals function. I figured other developers may need it as
well, so this patch moves it from DAP to the gdb module and exports
it.
I also added a new subclass of threading.Thread that ensures that
signals are blocked in the new thread.
Finally, this patch slightly rearranges the documentation so that
gdb-side threading issues and functions are all discussed in a single
node.
This adds a new objfile_for_address method to gdb.Progspace. This
makes it easy to find the objfile for a given address.
There's a related PR; and while this change would have been sufficient
for my original need, it's not clear to me whether I should close the
bug. Nevertheless I think it makes sense to at least mention it here.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=19288
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
In a review, Eli pointed out that @findex is redundant when used with
@defun. This patch removes all such uses from python.texi, plus a
couple uses before @defvar that are also unnecessary.
Approved-By: Eli Zaretskii <eliz@gnu.org>
The DAP disassemble command lets the client return the underlying
bytes of the instruction in an implementation-defined format. This
patch updates gdb to return this, and simply uses a hex string of the
bytes as the format.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The command 'list' has accepted the argument '+' for many years already,
but this option wasn't documented either in the texinfo docs or in the
help text for the command. This commit documents it.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
When using "list" with no arguments, GDB will first print the lines
around where the inferior is stopped, then print the next N lines until
reaching the end of file, at which point it warns the user "Line X out
of range, file Y only has X-1 lines.". This is usually desirable, but
if the user can no longer see the original line, they may have forgotten
the current line or that a list command was used at all, making GDB's
error message look cryptic. It was reported in bugzilla as PR cli/30497.
This commit improves the user experience by changing the behavior of
"list" slightly when a user passes no arguments. It now prints that the
end of the file has been reached and recommends that the user use the
command "list ." instead.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=30497
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
Currently, after the user has used the list command once, there is no
self-contained way to ask GDB to print the location where the inferior is
stopped. The current best options require either using a separate
command to scope out where the inferior is stopped, or using "list *$pc"
requiring knowledge of GDB standard registers. This commit adds a way
to do that using '.' as a new argument for the 'list' command. If the
inferior isn't running, the command prints around the main function.
Because this necessitated having the inferior running and the test was
(seemingly unnecessarily) using printf in a non-essential way and it
would make the resulting log harder to read for no benefit, it was
replaced by a different statement.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Tom Tromey <tom@tromey.com>
v6:
Fix comments.
Fix copyright
Remove unnecessary test suite stuff. save_var had to stay, as it mutates
some test suite state that otherwise fails.
v5:
Did what Tom Tromey requested in v4; which can be found here: https://pi.simark.ca/gdb-patches/87pmjm0xar.fsf@tromey.com/
v4:
Doc formatting fixed.
v3:
Eli:
Updated docs & NEWS to reflect new changes. Added
a reference from the .ptid attribute of the ThreadExitedEvent
to the ptid attribute of InferiorThread. To do this,
I've added an anchor to that attribute.
Tom:
Tom requested that I should probably just emit the thread object;
I ran into two issues for this, which I could not resolve in this patch;
1 - The Thread Object (the python type) checks it's own validity
by doing a comparison of it's `thread_info* thread` to nullptr. This
means that any access of it's attributes may (probably, since we are
in "async" land) throw Python exceptions because the thread has been
removed from the thread object. Therefore I've decided in v3 of this
patch to just emit most of the same fields that gdb.InferiorThread has, namely
global_num, name, num and ptid (the 3-attribute tuple provided by
gdb.InferiorThread.ptid).
2 - A python user can hold a global reference to an exiting thread. Thus
in order to have a ThreadExit event that can provide attribute access
reliably (both as a global reference, but also inside the thread exit
handler, as we can never guarantee that it's executed _before_ the
thread_info pointer is removed from the gdbpy thread object),
the `thread_info *` thread pointer must not be null. However, this
comes at the cost of gdb.InferiorThread believing it is "valid" - which means,
that if a user holds takes a global reference to that
exiting event thread object, they can some time later do `t.switch()` at which
point GDB will 'explode' so to speak.
v2:
Fixed white space issues and NULL/nullptr stuff,
as requested by Tom Tromey.
v1:
Currently no event is emitted for a thread exit.
This adds this functionality by emitting a new gdb.ThreadExitedEvent.
It currently provides four attributes:
- global_num: The GDB assigned global thread number
- num: the per-inferior thread number
- name: name of the thread or none if not set
- ptid: the PTID of the thread, a 3-attribute tuple, identical to
InferiorThread.ptid attribute
Added info to docs & the NEWS file as well.
Added test to test suite.
Fixed formatting.
Feedback wanted and appreciated.
Co-workers who work on a program that uses DAP asked for the ability
to have gdb stop at the main subprogram when launching. This patch
implements this extension.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds a new "target" to the DAP attach request. This is passed to
"target remote". I thought "attach" made the most sense for this,
because in some sense gdb is attaching to a running process. It's
worth noting that all DAP "attach" parameters are defined by the
implementation.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds an 'assign' method to gdb.Value. This allows for assignment
without requiring the use of parse_and_eval.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This implements the DAP "attach" request.
Note that the copyright dates on the new test source file are not
incorrect -- this was copied verbatim from another directory.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Fix grammar in some comments and docs:
- machines that doesn't -> machines that don't
- its a -> it's a
- its the -> it's the
- if does its not -> if it does it's not
- one more instructions if doesn't match ->
one more instruction if it doesn't match
- it's own -> its own
- it's first -> its first
- it's pointer -> its pointer
I also came across "it's performance" in gdb/stubs/*-stub.c in the HP public
domain notice, I've left that alone.
Tested on x86_64-linux.
I found the documentation for -dprintf-insert a bit unclear. It
didn't mention the possibility of multiple arguments, and I also
noticed that it implied that the format parameter is optional, which
it is not.
While looking into this I also noticed a few comments in the
implementation that could also be improved.
Then, I noticed a repeated call to strlen in a loop condition, so I
fixed this up as well.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I noticed a couple instance of this warning when rebuilding the gdb
info files:
warning: undefined flag: GDB
The problem is that the wrong argument was passed to @value. This
patch fixes the problem.
This commit adds a new format for the printf and dprintf commands:
'%V'. This new format takes any GDB expression and formats it as a
string, just as GDB would for a 'print' command, e.g.:
(gdb) print a1
$a = {2, 4, 6, 8, 10, 12, 14, 16, 18, 20}
(gdb) printf "%V\n", a1
{2, 4, 6, 8, 10, 12, 14, 16, 18, 20}
(gdb)
It is also possible to pass the same options to %V as you might pass
to the print command, e.g.:
(gdb) print -elements 3 -- a1
$4 = {2, 4, 6...}
(gdb) printf "%V[-elements 3]\n", a1
{2, 4, 6...}
(gdb)
This new feature would effectively replace an existing feature of GDB,
the $_as_string builtin convenience function. However, the
$_as_string function has a few problems which this new feature solves:
1. $_as_string doesn't currently work when the inferior is not
running, e.g:
(gdb) printf "%s", $_as_string(a1)
You can't do that without a process to debug.
(gdb)
The reason for this is that $_as_string returns a value object with
string type. When we try to print this we call value_as_address,
which ends up trying to push the string into the inferior's address
space.
Clearly we could solve this problem, the string data exists in GDB, so
there's no reason why we have to push it into the inferior, but this
is an existing problem that would need solving.
2. $_as_string suffers from the fact that C degrades arrays to
pointers, e.g.:
(gdb) printf "%s\n", $_as_string(a1)
0x404260 <a1>
(gdb)
The implementation of $_as_string is passed a gdb.Value object that is
a pointer, it doesn't understand that it's actually an array. Solving
this would be harder than issue #1 I think. The whole array to
pointer transformation is part of our expression evaluation. And in
most cases this is exactly what we want. It's not clear to me how
we'd (easily) tell GDB that we didn't want this reduction in _some_
cases. But I'm sure this is solvable if we really wanted to.
3. $_as_string is a gdb.Function sub-class, and as such is passed
gdb.Value objects. There's no super convenient way to pass formatting
options to $_as_string. By this I mean that the new %V feature
supports print formatting options. Ideally, we might want to add this
feature to $_as_string, we might imagine it working something like:
(gdb) printf "%s\n", $_as_string(a1,
elements = 3,
array_indexes = True)
where the first item is the value to print, while the remaining
options are the print formatting options. However, this relies on
Python calling syntax, which isn't something that convenience
functions handle. We could possibly rely on strictly positional
arguments, like:
(gdb) printf "%s\n", $_as_string(a1, 3, 1)
But that's clearly terrible as there's far more print formatting
options, and if you needed to set the 9th option you'd need to fill in
all the previous options.
And right now, the only way to pass these options to a gdb.Function is
to have GDB first convert them all into gdb.Value objects, which is
really overkill for what we want.
The new %V format solves all these problems: the string is computed
and printed entirely on the GDB side, we are able to print arrays as
actual arrays rather than pointers, and we can pass named format
arguments.
Finally, the $_as_string is sold in the manual as allowing users to
print the string representation of flag enums, so given:
enum flags
{
FLAG_A = (1 << 0),
FLAG_B = (1 << 1),
FLAG_C = (1 << 1)
};
enum flags ff = FLAG_B;
We can:
(gdb) printf "%s\n", $_as_string(ff)
FLAG_B
This works just fine with %V too:
(gdb) printf "%V\n", ff
FLAG_B
So all functionality of $_as_string is replaced by %V. I'm not
proposing to remove $_as_string, there might be users currently
depending on it, but I am proposing that we don't push $_as_string in
the documentation.
As %V is a feature of printf, GDB's dprintf breakpoints naturally gain
access to this feature too. dprintf breakpoints can be operated in
three different styles 'gdb' (use GDB's printf), 'call' (call a
function in the inferior), or 'agent' (perform the dprintf on the
remote).
The use of '%V' will work just fine when dprintf-style is 'gdb'.
When dprintf-style is 'call' the format string and arguments are
passed to an inferior function (printf by default). In this case GDB
doesn't prevent use of '%V', but the documentation makes it clear that
support for '%V' will depend on the inferior function being called.
I chose this approach because the current implementation doesn't place
any restrictions on the format string when operating in 'call' style.
That is, the user might already be calling a function that supports
custom print format specifiers (maybe including '%V') so, I claim, it
would be wrong to block use of '%V' in this case. The documentation
does make it clear that users shouldn't expect this to "just work"
though.
When dprintf-style is 'agent' then GDB does no support the use of
'%V' (right now). This is handled at the point when GDB tries to
process the format string and send the dprintf command to the remote,
here's an example:
Reading symbols from /tmp/hello.x...
(gdb) dprintf call_me, "%V", a1
Dprintf 1 at 0x401152: file /tmp/hello.c, line 8.
(gdb) set sysroot /
(gdb) target remote | gdbserver --once - /tmp/hello.x
Remote debugging using | gdbserver --once - /tmp/hello.x
stdin/stdout redirected
Process /tmp/hello.x created; pid = 3088822
Remote debugging using stdio
Reading symbols from /lib64/ld-linux-x86-64.so.2...
(No debugging symbols found in /lib64/ld-linux-x86-64.so.2)
0x00007ffff7fd3110 in _start () from /lib64/ld-linux-x86-64.so.2
(gdb) set dprintf-style agent
(gdb) c
Continuing.
Unrecognized format specifier 'V' in printf
Command aborted.
(gdb)
This is exactly how GDB would handle any other invalid format
specifier, for example:
Reading symbols from /tmp/hello.x...
(gdb) dprintf call_me, "%Q", a1
Dprintf 1 at 0x401152: file /tmp/hello.c, line 8.
(gdb) set sysroot /
(gdb) target remote | gdbserver --once - /tmp/hello.x
Remote debugging using | gdbserver --once - /tmp/hello.x
stdin/stdout redirected
Process /tmp/hello.x created; pid = 3089193
Remote debugging using stdio
Reading symbols from /lib64/ld-linux-x86-64.so.2...
(No debugging symbols found in /lib64/ld-linux-x86-64.so.2)
0x00007ffff7fd3110 in _start () from /lib64/ld-linux-x86-64.so.2
(gdb) set dprintf-style agent
(gdb) c
Continuing.
Unrecognized format specifier 'Q' in printf
Command aborted.
(gdb)
The error message isn't the greatest, but improving that can be put
off for another day I hope.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Acked-By: Simon Marchi <simon.marchi@efficios.com>
If a header file defining a static function is included in multiple source
files, each calling the function, and GDB is asked to jump to a line inside
that function, there would be multiple locations matching the target. The
solution in this commit is to select the location in the current symtab.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Andrew Burgess <aburgess@redhat.com>
This patch augments the DAP launch request with some optional new
parameters that let the client control the command-line arguments and
the environment of the inferior.
Reviewed-By: Andrew Burgess <aburgess@redhat.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds two new attributes and three new methods to gdb.Inferior.
The attributes let Python code see the command-line arguments and the
name of "main". Argument setting is also supported.
The methods let Python code manipulate the inferior's environment
variables.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds a 'global_context' parse_and_eval to gdb.parse_and_eval.
This lets users request a parse that is done at "global scope".
I considered letting callers pass in a block instead, with None
meaning "global" -- but then there didn't seem to be a clean way to
express the default for this parameter.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This adds a new Python function, gdb.execute_mi, that can be used to
invoke an MI command but get the output as a Python object, rather
than a string. This is done by implementing a new ui_out subclass
that builds a Python object.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=11688
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I noticed that Frame.older and Frame.newer don't document that they
return None at the ends of the stack. This patch updates the
documentation, and also fixes a somewhat related typo in a comment
that I noticed while digging into this.
Approved-By: Eli Zaretskii <eliz@gnu.org>
Eli pointed out that @sc only produces small caps for lower case
letters in its argument, so it's weird to write it using upper-case
letters. This patch fixes the instances I found.
Approved-By: Eli Zaretskii <eliz@gnu.org>
This commit extends the Python Disassembler API to allow for styling
of the instructions.
Before this commit the Python Disassembler API allowed the user to do
two things:
- They could intercept instruction disassembly requests and return a
string of their choosing, this string then became the disassembled
instruction, or
- They could call builtin_disassemble, which would call back into
libopcode to perform the disassembly. As libopcode printed the
instruction GDB would collect these print requests and build a
string. This string was then returned from the builtin_disassemble
call, and the user could modify or extend this string as needed.
Neither of these approaches allowed for, or preserved, disassembler
styling, which is now available within libopcodes for many of the more
popular architectures GDB supports.
This commit aims to fill this gap. After this commit a user will be
able to do the following things:
- Implement a custom instruction disassembler entirely in Python
without calling back into libopcodes, the custom disassembler will
be able to return styling information such that GDB will display
the instruction fully styled. All of GDB's existing style
settings will affect how instructions coming from the Python
disassembler are displayed in the expected manner.
- Call builtin_disassemble and receive a result that represents how
libopcode would like the instruction styled. The user can then
adjust or extend the disassembled instruction before returning the
result to GDB. Again, the instruction will be styled as expected.
To achieve this I will add two new classes to GDB,
DisassemblerTextPart and DisassemblerAddressPart.
Within builtin_disassemble, instead of capturing the print calls from
libopcodes and building a single string, we will now create either a
text part or address part and store these parts in a vector.
The DisassemblerTextPart will capture a small piece of text along with
the associated style that should be used to display the text. This
corresponds to the disassembler calling
disassemble_info::fprintf_styled_func, or for disassemblers that don't
support styling disassemble_info::fprintf_func.
The DisassemblerAddressPart is used when libopcodes requests that an
address be printed, and takes care of printing the address and
associated symbol, this corresponds to the disassembler calling
disassemble_info::print_address_func.
These parts are then placed within the DisassemblerResult when
builtin_disassemble returns.
Alternatively, the user can directly create parts by calling two new
methods on the DisassembleInfo class: DisassembleInfo.text_part and
DisassembleInfo.address_part.
Having created these parts the user can then pass these parts when
initializing a new DisassemblerResult object.
Finally, when we return from Python to gdbpy_print_insn, one way or
another, the result being returned will have a list of parts. Back in
GDB's C++ code we walk the list of parts and call back into GDB's core
to display the disassembled instruction with the correct styling.
The new API lives in parallel with the old API. Any existing code
that creates a DisassemblerResult using a single string immediately
creates a single DisassemblerTextPart containing the entire
instruction and gives this part the default text style. This is also
what happens if the user calls builtin_disassemble for an architecture
that doesn't (yet) support libopcode styling.
This matches up with what happens when the Python API is not involved,
an architecture without disassembler styling support uses the old
libopcodes printing API (the API that doesn't pass style info), and
GDB just prints everything using the default text style.
The reason that parts are created by calling methods on
DisassembleInfo, rather than calling the class constructor directly,
is DisassemblerAddressPart. Ideally this part would only hold the
address which the part represents, but in order to support backwards
compatibility we need to be able to convert the
DisassemblerAddressPart into a string. To do that we need to call
GDB's internal print_address function, and to do that we need an
gdbarch.
What this means is that the DisassemblerAddressPart needs to take a
gdb.Architecture object at creation time. The only valid place a user
can pull this from is from the DisassembleInfo object, so having the
DisassembleInfo act as a factory ensures that the correct gdbarch is
passed over each time. I implemented both solutions (the one
presented here, and an alternative where parts could be constructed
directly), and this felt like the cleanest solution.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: Tom Tromey <tom@tromey.com>
This commit is a refactor ahead of the next change which will make
disassembler styling available through the Python API.
Unfortunately, in order to make the styling support available, I think
the easiest solution is to make a very small change to the existing
API.
The current API relies on returning a DisassemblerResult object to
represent each disassembled instruction. Currently GDB allows the
DisassemblerResult class to be sub-classed, which could mean that a
user tries to override the various attributes that exist on the
DisassemblerResult object.
This commit removes this ability, effectively making the
DisassemblerResult class final.
Though this is a change to the existing API, I'm hoping this isn't
going to cause too many issues:
- The Python disassembler API was only added in the previous release
of GDB, so I don't expect it to be widely used yet, and
- It's not clear to me why a user would need to sub-class the
DisassemblerResult type, I allowed it in the original patch
because at the time I couldn't see any reason to NOT allow it.
Having prevented sub-classing I can now rework the tail end of the
gdbpy_print_insn function; instead of pulling the results out of the
DisassemblerResult object by calling back into Python, I now cast the
Python object back to its C++ type (disasm_result_object), and access
the fields directly from there. In later commits I will be reworking
the disasm_result_object type in order to hold information about the
styled disassembler output.
The tests that dealt with sub-classing DisassemblerResult have been
removed, and a new test that confirms that DisassemblerResult can't be
sub-classed has been added.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: Tom Tromey <tom@tromey.com>
Some small improvements to the Python Disassembler API documentation:
* Be consistent about using the package scope in the @deftp lines,
* Rework the description of the DisassemblerResult class to include
mention of builtin_disassemble.
Consider a hello.c, with less than 10 lines:
...
$ wc -l hello.c
8 hello.c
...
and compiled with -g into an a.out.
With compact-source off:
...
$ gdb -q a.out \
-ex "set tui border-kind ascii" \
-ex "maint set tui-left-margin-verbose on" \
-ex "set tui compact-source off" \
-ex "tui enable"
...
we get:
...
+-./data/hello.c-----------------------+
|___000005_{ |
|___000006_ printf ("hello\n"); |
|___000007_ return 0; |
|___000008_} |
|___000009_ |
|___000010_ |
|___000011_ |
...
but with compact-source on:
...
+-./data/hello.c-----------------------+
|___5{ |
|___6 printf ("hello\n"); |
|___7 return 0; |
|___8} |
|___9 |
|___1 |
|___1 |
...
There are a couple of problems with compact-source.
First of all the documentation mentions:
...
The default display uses more space for line numbers and starts the
source text at the next tab stop; the compact display uses only as
much space as is needed for the line numbers in the current file, and
only a single space to separate the line numbers from the source.
...
The bit about the default display and the next tab stop looks incorrect. The
source doesn't start at a tab stop, instead it uses a single space to separate
the line numbers from the source.
Then the documentation mentions that there's single space in the compact
display, but evidently that's missing.
Then there's the fact that the line numbers "10" and "11" are both abbreviated
to "1" in the compact case.
The abbreviation is due to allocating space for <lines in source>, which is
8 for this example, and takes a single digit. The line numbers though
continue past the end of the file, so fix this by allocating space for
max (<lines in source>, <last line in window>), which in this example takes 2
digits.
The missing space is due to some confusion about what the "1" here in
tui_source_window::set_contents represent:
...
double l = log10 ((double) offsets->size ());
m_digits = 1 + (int) l;
...
It could be the trailing space that's mentioned in tui-source.h:
...
/* How many digits to use when formatting the line number. This
includes the trailing space. */
int m_digits;
...
Then again, it could be part of the calculation for the number of digits
needed for printing. With this minimal example:
...
int main () {
for (int i = 8; i <= 11; ++i) {
double l = log10 ((double) i);
printf ("%d %d\n", i, (int)l);
}
return 0;
}
...
we get:
...
$ ./a.out
8 0
9 0
10 1
11 1
...
which shows that the number of digits needed for printing i is
"1 + (int)log10 ((double) i)".
Fix this by introducing named variables needed_digits and trailing_space, each
adding 1.
With the fixes, we get for compact-source on:
...
+-./data/hello.c-----------------------+
|___05_{ |
|___06_ printf ("hello\n"); |
|___07_ return 0; |
|___08_} |
|___09_ |
|___10_ |
|___11_ |
|...
Also fix the documentation and help text to actually match effect of
compact-source.
Tested on x86_64-linux.
SUMMARY
The '--simple-values' argument to '-stack-list-arguments' and similar
GDB/MI commands does not take reference types into account, so that
references to arbitrarily large structures are considered "simple" and
printed. This means that the '--simple-values' argument cannot be used
by IDEs when tracing the stack due to the time taken to print large
structures passed by reference.
DETAILS
Various GDB/MI commands ('-stack-list-arguments', '-stack-list-locals',
'-stack-list-variables' and so on) take a PRINT-VALUES argument which
may be '--no-values' (0), '--all-values' (1) or '--simple-values' (2).
In the '--simple-values' case, the command is supposed to print the
name, type, and value of variables with simple types, and print only the
name and type of variables with compound types.
The '--simple-values' argument ought to be suitable for IDEs that need
to update their user interface with the program's call stack every time
the program stops. However, it does not take C++ reference types into
account, and this makes the argument unsuitable for this purpose.
For example, consider the following C++ program:
struct s {
int v[10];
};
int
sum(const struct s &s)
{
int total = 0;
for (int i = 0; i < 10; ++i) total += s.v[i];
return total;
}
int
main(void)
{
struct s s = { { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 } };
return sum(s);
}
If we start GDB in MI mode and continue to 'sum', the behaviour of
'-stack-list-arguments' is as follows:
(gdb)
-stack-list-arguments --simple-values
^done,stack-args=[frame={level="0",args=[{name="s",type="const s &",value="@0x7fffffffe310: {v = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}}"}]},frame={level="1",args=[]}]
Note that the value of the argument 's' was printed, even though 's' is
a reference to a structure, which is not a simple value.
See https://github.com/microsoft/MIEngine/pull/673 for a case where this
behaviour caused Microsoft to avoid the use of '--simple-values' in
their MIEngine debug adapter, because it caused Visual Studio Code to
take too long to refresh the call stack in the user interface.
SOLUTIONS
There are two ways we could fix this problem, depending on whether we
consider the current behaviour to be a bug.
1. If the current behaviour is a bug, then we can update the behaviour
of '--simple-values' so that it takes reference types into account:
that is, a value is simple if it is neither an array, struct, or
union, nor a reference to an array, struct or union.
In this case we must add a feature to the '-list-features' command so
that IDEs can detect that it is safe to use the '--simple-values'
argument when refreshing the call stack.
2. If the current behaviour is not a bug, then we can add a new option
for the PRINT-VALUES argument, for example, '--scalar-values' (3),
that would be suitable for use by IDEs.
In this case we must add a feature to the '-list-features' command
so that IDEs can detect that the '--scalar-values' argument is
available for use when refreshing the call stack.
PATCH
This patch implements solution (1) as I think the current behaviour of
not printing structures, but printing references to structures, is
contrary to reasonable expectation.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=29554
The Debugger Adapter Protocol defines a "launch" request but leaves
the parameters up to the implementation:
Since launching is debugger/runtime specific, the arguments for
this request are not part of this specification.
This patch adds some documentation for the parameter GDB currently
defines. Note that I plan to add more parameters here, and perhaps
there will be other extensions in time as well.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I noticed the following behaviour:
$ gdb -q -i=mi /tmp/hello.x
=thread-group-added,id="i1"
=cmd-param-changed,param="print pretty",value="on"
~"Reading symbols from /tmp/hello.x...\n"
(gdb)
-break-insert -p 99 main
^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",addr="0x0000000000401198",func="main",file="/tmp/hello.c",fullname="/tmp/hello.c",line="18",thread-groups=["i1"],thread="99",times="0",original-location="main"}
(gdb)
info breakpoints
&"info breakpoints\n"
~"Num Type Disp Enb Address What\n"
~"1 breakpoint keep y 0x0000000000401198 in main at /tmp/hello.c:18\n"
&"../../src/gdb/thread.c:1434: internal-error: print_thread_id: Assertion `thr != nullptr' failed.\nA problem internal to GDB has been detected,\nfurther debugging may prove unreliable."
&"\n"
&"----- Backtrace -----\n"
&"Backtrace unavailable\n"
&"---------------------\n"
&"\nThis is a bug, please report it."
&" For instructions, see:\n"
&"<https://www.gnu.org/software/gdb/bugs/>.\n\n"
Aborted (core dumped)
What we see here is that when using the MI a user can create
thread-specific breakpoints for non-existent threads. Then if we try
to use the CLI 'info breakpoints' command GDB throws an assertion.
The assert is a result of the print_thread_id call when trying to
build the 'stop only in thread xx.yy' line; print_thread_id requires a
valid thread_info pointer, which we can't have for a non-existent
thread.
In contrast, when using the CLI we see this behaviour:
$ gdb -q /tmp/hello.x
Reading symbols from /tmp/hello.x...
(gdb) break main thread 99
Unknown thread 99.
(gdb)
The CLI doesn't allow a breakpoint to be created for a non-existent
thread. So the 'info breakpoints' command is always fine.
Interestingly, the MI -break-info command doesn't crash, this is
because the MI uses global thread-ids, and so never calls
print_thread_id. However, GDB does support using CLI and MI in
parallel, so we need to solve this problem.
One option would be to change the CLI behaviour to allow printing
breakpoints for non-existent threads. This would preserve the current
MI behaviour.
The other option is to pull the MI into line with the CLI and prevent
breakpoints being created for non-existent threads. This is good for
consistency, but is a breaking change for the MI.
In the end I figured that it was probably better to retain the
consistent CLI behaviour, and just made the MI reject requests to
place a breakpoint on a non-existent thread. The only test we had
that depended on the old behaviour was
gdb.mi/mi-thread-specific-bp.exp, which was added by me in commit:
commit 2fd9a436c8
Date: Fri Feb 17 10:48:06 2023 +0000
gdb: don't duplicate 'thread' field in MI breakpoint output
I certainly didn't intend for this test to rely on this feature of the
MI, so I propose to update this test to only create breakpoints for
threads that exist.
Actually, I've added a new test that checks the MI rejects creating a
breakpoint for a non-existent thread, and I've also extended the test
to run with the separate MI/CLI UIs, and then tested 'info
breakpoints' to ensure this command doesn't crash.
I've extended the documentation of the `-p` flag to explain the
constraints better.
I have also added a NEWS entry just in case someone runs into this
issue, at least then they'll know this change in behaviour was
intentional.
One thing that I did wonder about while writing this patch, is whether
we should treat requests like this, on both the MI and CLI, as another
form of pending breakpoint, something like:
(gdb) break foo thread 9
Thread 9 does not exist.
Make breakpoint pending on future thread creation? (y or [n]) y
Breakpoint 1 (foo thread 9) pending.
(gdb) info breakpoints
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> foo thread 9
Don't know if folk think that would be a useful idea or not? Either
way, I think that would be a separate patch from this one.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Eli pointed out that @var isn't needed in @defun in Texinfo. This
patch removes the cases I found in python.texi. I also renamed some
variables in one spot, because "-" isn't valid in a Python variable
name.
