This commit changes the 'target ...' commands that accept a filename
to take a quoted or escaped filename rather than a literal filename.
What this means in practice is that if you are specifying a filename
that contains no white space or quote characters, then nothing should
change, e.g.:
target exec /path/to/some/file
works both before and after this commit.
However, if a user wishes to specify a file containing white space
then either the entire filename needs to be quoted, or the special
white space needs to be escaped. Before this patch a user could
write:
target exec /path/to a file/containing spaces
But after this commit the user would have to choose one of:
target exec "/path/to a file/containing spaces"
or
target exec /path/to\ a\ file/containing\ spaces
Obviously this is a potentially breaking change. The benefit of
making this change is consistency. Commands that take multiple
arguments (one of which is a filename) or in the future, commands that
take filename options, will always need to use quoted/escaped
filenames, so converting all unquoted filename commands to use quoting
or escaping makes the UI more consistent.
Additionally (though this is probably not a common problem), GDB
strips trailing white space from commands that the user enters. As
such it is not possible to reference any file that ends in white space
unless the quoting / escaping style is used. Though I suspect very
few users run into this problem!
The downside obviously is that this is a UI breaking change.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This commit changes how GDB processes command arguments for the
following commands:
compile file
maint print c-tdesc
save gdb-index
After this commit these commands will now expect their single filename
argument to be (optionally) quoted if it contains any special
characters (e.g. whit space or quotes).
If the filename does not contain any special characters then nothing
changes. As an example:
(gdb) save gdb-index /path/to/some/directory/
will work before and after this patch. However, if the directory
name contains a white space then before this patch a user would write:
(gdb) save gdb-index /path/to some/directory/
But this will now fail as GDB will consider this as two arguments,
'/path/to' and 'some/directory/'. To pass this single directory name
a user must now do one of these:
(gdb) save gdb-index "/path/to some/directory/"
(gdb) save gdb-index '/path/to some/directory/'
(gdb) save gdb-index /path/to\ some/directory/
This brings these commands into line with commands like 'file' and
'symbol-file', which have supported quoted filenames for a while.
The motivation for this change is to make handling of filename
arguments consistent throughout GDB. We can't move to all commands
taking non-quoted filenames as the non-quoted style only allows for a
single argument. Additionally, the non-quoted style doesn't allow for
filenames that end in white space (though this is probably pretty
rare). So, if we want to have consistency the only choice is to move
towards supporting quote filenames.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The 'remove-symbol-file' command doesn't currently offer command
completion. This commit addresses this.
The 'remove-symbol-file' uses gdb_argv to split its command arguments,
this means that the filename the command expects can be quoted.
However, the 'remove-symbol-file' command is a little weird in that it
also has a '-a' option, if this option is passed then the command
expects not a filename, but an address.
Currently the remove_symbol_file_command function splits the command
args using gdb_argv, checks for a '-a' flag by looking at the first
argument value, and then expects the filename or address to occupy a
single entry in the gdb_argv array.
The first thing I do is handle the '-a' flag using GDB's option
system. I model this option as a flag_option_def (a boolean option).
I've dropped the use of gdb_argv and instead use the new(ish) function
extract_single_filename_arg, which was added a couple of commits back,
to parse the filename argument (when '-a' is not given).
If '-a' is given the the remove-symbol-file command expects an address
rather than a filename. As we previously split the arguments using
gdb_argv this meant the address needed to appear as a single
argument. So a user could write:
(gdb) remove-symbol-file 0x1234
Or they could write:
(gdb) remove-symbol-file some_function
Both of these would work fine. But a user could not write:
(gdb) remove-symbol-file some_function + 0x1000
As only the 'some_function' part would be processed. Now the user
could do this:
(gdb) remove-symbol-file "some_function + 0x1000"
By enclosing the address expression in quotes this would be handled as
a single argument. However, this is a little weird, that's not how
commands like 'print' or 'x' work. Also this functionality was
neither documented, or tested.
And so, in this commit, by removing the use of gdb_argv I bring the
'remove-symbol-file' command inline with GDB's other commands that
take an expression, the quotes are no longer needed.
Usually in a completer we call 'complete_options', but don't actually
capture the option values. But for remove-symbol-file I do. This
allows me to spot when the '-a' option has been given, I can then
complete the rest of the command line as either a filename or an
expression.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
While reviewing a patch I wanted to understand which blocks existed at
a given address.
The 'maint print symbols' command does provide some of this
information, but that command displays all blocks within a given
symtab. If I want to know which blocks are at a given address I have
to figure that out for myself based on the output of 'maint print
symbols' ... and I'm too lazy for that!
So this command lists just those blocks at a given address, along with
information about the blocks type. This new command doesn't list the
symbols within each block, for that my expectation is that you'd cross
reference the output with that of 'maint print symbols'.
The new command format is:
maintenance info blocks
maintenance info blocks ADDRESS
This lists the blocks at ADDRESS, or at the current $pc if ADDRESS is
not given. Blocks are listed starting at the global block, then the
static block, and then the progressively narrower scoped blocks.
For each block we list the internal block pointer (which allows easy
cross referencing with 'maint print symbols'), the inferior address
range, along with other useful information.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Simon Marchi <simon.marchi@efficios.com>
While reviewing a patch I wanted to view GDB's inline frame state. I
don't believe there's currently a maintenance command to view this
information, so in this commit I've added one.
The new command is:
maintenance info inline-frames
maintenance info inline-frames ADDRESS
The command lists the inline frames that start at ADDRESS, or at the
current $pc if no ADDRESS is given. The command also displays the
"outer" function in which the inline functions are present.
An example of the command output:
(gdb) maintenance info inline-frames
Cached inline state information for thread 1.
program counter = 0x401137
skipped frames = 1
bar
> foo
main
(gdb)
This tells us that function 'main' called 'foo' which called 'bar'.
The functions 'foo' and 'bar' are both inline and both start at the
address 0x401137. Currently GDB considers the inferior to be stopped
in frame 'foo' (note the '>' marker), this means that there is 1
skipped frame (function 'bar').
The function 'main' is the outer function. The outer function might
not start at 0x401137, it is simply the function that contains the
inline functions.
If the user does a 'step' then GDB will not actually move the inferior
forward, but will instead simply tell the user that the inferior
entered 'bar'. The output of 'maint info inline-frames' will change
like this:
(gdb) step
bar () at inline.c:6
6 ++global_counter;
(gdb) maintenance info inline-frames
Cached inline state information for thread 1.
program counter = 0x401137
skipped frames = 0
> bar
foo
main
(gdb)
Now GDB is in function 'bar' and there are no skipped frames.
I have renamed skipped_symbols to function symbols within the
inline_state class. We are now going to carry the "outer"
function (the function that contains all the inlined functions) within
this list (as the last entry), so the old name didn't really make
sense. As a consequence of this rename I've updated some comments.
I've changed stopped_by_user_bp_inline_frame to take a symbol rather
than a block. Previously we just used the block to access the
associated function symbol. After this commit we can just pass in the
function symbol directly, so lets do that.
New function gather_inline_frames contains some of the logic pulled
from skip_inline_frames. This new function builds the list of all
symbols of inlined functions that start at a given $pc value and also
the "outer" function that contains all of the inlined functions.
In skip_inline_frames I've split the loop logic into two. The loop to
build the function symbol list has moved to gather_inline_frames. The
loop to figure out how many of the inlined functions we are skipping
remains in skip_inline_frames and uses the result of calling
gather_inline_frames.
In inline_skipped_symbol there are some minor updates to the comment,
and I've tweaked one of the asserts now that the function symbols list
also contains the "outer" function (a <= becomes <).
The maintenance_info_inline_frames function is now and implements the
new maintenance command.
And _initialize_inline_frame is updated to register the new command.
I've added a basic test for the new command. Please excuse the file
name for the new test, in the next commit I'll be adding additional
tests and at that point the file name will make sense.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Simon Marchi <simon.marchi@efficios.com>
Call the ptwrite filter function whenever a ptwrite event is decoded.
The returned string is written to the aux_data string table and a
corresponding auxiliary instruction is appended to the function segment.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This enables gdb and gdbserver to communicate about ptwrite support. If
ptwrite support would be enabled unconditionally, GDBs with older libipt
versions would break.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
This function allows to clear the trace data from python, forcing to
re-decode the trace for successive commands.
This will be used in future ptwrite patches, to trigger re-decoding when
the ptwrite filter changes.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Auxiliary instructions are no real instructions and get their own object
class, similar to gaps. gdb.Record.instruction_history is now possibly a
list of gdb.RecordInstruction, gdb.RecordGap or gdb.RecordAuxiliary
objects.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Print the auxiliary data when a btrace_insn of type BTRACE_INSN_AUX
is encountered in the function-call-history. Printing is
active by default, it can be silenced with the /a modifier.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Print the auxiliary data when a btrace_insn of type BTRACE_INSN_AUX
is encountered in the instruction-history. Printing is active by default,
it can be silenced with the /a modifier.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Auxiliary instructions are pseudo instructions pointing to auxiliary data.
This auxiliary data can be printed in all commands displaying (record
function-call-history, record instruction-history) or stepping through
(stepi etc.) the execution history, which will be introduced in the next
commits.
This patch is in preparation for the new ptwrite feature, which is based on
auxiliary instructions.
Approved-By: Markus Metzger <markus.t.metzger@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Remove the support for the QNX Neutrino OS (tdep and native bits). This
has been unmaintained for years, and we don't have a way to see if it
works (or even builds, for the native parts). Without somebody actively
maintaining it, this is just a burden for developers, especially that
this port does a few weird unique things that require reasoning about
when doing big change.
Support for GDBserver was removed in 2020, commit 613f149a90
("gdbserver: remove support for Neutrino").
Change-Id: I4e25ec26ab06636629adebd02ceb161ee31c232d
Approved-by: Kevin Buettner <kevinb@redhat.com>
When building the GDB info manual I see this warning:
gdb.texinfo:41447: warning: @anchor should not appear on @item line
And indeed line 41447 looks like this:
@item @anchor{maint info breakpoints}maint info breakpoints
I propose moving the @anchor{...} part to the previous line which
silences the warning.
Approved-By: Eli Zaretskii <eliz@gnu.org>
It also tests the gcore script being run without its accessible
terminal.
This test was written by Jan Kratochvil a long time ago. I modernized
the test making it use various procs from lib/gdb.exp, reorganizing it
and added some comments.
Modify the gcore script to make it possible to pass the --data-directory to
it. This prevents a lot of these warnings:
Python Exception <class 'AttributeError'>: module 'gdb' has no attribute
'_handle_missing_debuginfo'
Tested by using make check-all-boards.
Co-Authored-By: Jan Kratochvil <jan.kratochvil@redhat.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
A while ago, an AdaCore user reported some difficulties with the
'define' command. While some of these difficulties are intrinsic, or
at least difficult to change, it seemed sensible to document a couple
of the typical problems -- and to make the text describing argument
substitution a bit more prominent.
Approved-By: Eli Zaretskii <eliz@gnu.org>
This commit adds the GDB side of target_ops::fileio_stat. There's an
implementation for inf_child_target, which just calls 'lstat', and
there's an implementation for remote_target, which sends a new
vFile:stat packet.
The new packet is documented.
There's still no users of target_fileio_stat as I have not yet added
support for vFile::stat to gdbserver. If these packets are currently
sent to gdbserver then they will be reported as not supported and the
ENOSYS error code will be returned.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
I noticed that the 'all-doc' build target doesn't build all the doc
formats, 'man' and 'html' are missing.
This commit updates 'all-doc' so that all formats are built.
This doesn't change the default 'all' target, which is the default
target used when building GDB itself, the 'all' target continues to
just build the 'info' docs.
There should be no difference in the actual generated output after
this commit, I'm just changing what gets built.
Approved-By: Tom Tromey <tom@tromey.com>
After this commit:
commit 0700386f14 (gdb-tmp-c)
Date: Wed May 8 19:12:57 2024 +0100
gdb/doc: fix parallel build of pdf and dvi files
When building the dvi or pdf targets you'd get errors like this:
mkdir: cannot create directory ‘texi2dvi_tmpdir/gdb_dvi’: No such file or directory
mkdir: cannot create directory ‘texi2dvi_tmpdir/gdb_pdf’: No such file or directory
fixed by ensuring the directory is created before calling texi2dvi.
When building with 'make -j20 -C gdb/doc all-doc' I often see problems
caused from trying to build some dvi files in parallel with some pdf
files. The problem files are: gdb.dvi and gdb.pdf; stabs.dvi and
stabs.pdf; and annotate.dvi and annotate.pdf.
The problem is that building these files create temporary files in the
local directory. There's already a race here that two make threads
might try to create these files at the same time.
But it gets worse, to avoid issues where a failed build could leave
these temporary files in a corrupted state, and so prevent the next
build from succeeding, the recipe for each of these files deletes all
the temporary files first, this obviously causes problems if some
other thread has already started the build and is relying on these
temporary files.
To work around this problem I propose we start using the --build and
--build-dir options for texi2dvi (which is the same tool used to
create the pdf files). These options were added in texinfo 4.9 which
was released in June 2007. We already require using a version of
texinfo after 4.9 (I tried to build with 4.13 and the doc build failed
as some of the texinfo constructs were not understood), so this patch
has not changed the minimum required version at all.
The --build flag allows the temporary files to be placed into a
sub-directory, and the --build-dir option allows us to control the
name of that sub-directory.
What we do is create a unique sub-directory for each target that
invokes texi2dvi, all of the unique sub-directories are created within
a single directory texi2dvi_tmpdir, and so after a complete doc build,
we are left with a build tree like this:
build/gdb/doc/
'-- texi2dvi_tmpdir/
|-- annotate_dvi/
|-- annotate_pdf/
|-- gdb_dvi/
|-- gdb_pdf/
|-- stabs_dvi/
'-- stabs_pdf/
I've left out all the individual files that live within these
directories for simplicity.
To avoid corrupted temporary files preventing a future build to
complete, each recipe deletes its associated sub-directory from within
texi2dvi_tmpdir/ before it attempts a build, this ensures a fresh
start each time.
And the mostlyclean target deletes texi2dvi_tmpdir/ and all its
sub-directories, ensuring that everything is cleaned up.
For me, with this fix in place, I can now run 'make -j20 -C gdb/doc
all-doc' without seeing any build problems.
Approved-By: Pedro Alves <pedro@palves.net>
There are two problems we encounter when trying to build the refcard
related target in parallel, i.e.:
$ make -j20 -C gdb/doc/ refcard.dvi refcard.ps refcard.pdf
These problems are:
(1) The refcard.dvi and refcard.pdf targets both try and generate the
tmp.sed and sedref.tex files. If two make threads end up trying
to create these files at the same time then the result is these
files become corrupted.
I've fixed this by creating a new rule that creates sedref.tex,
both refcard.dvi and refcard.pdf now depend on this, and make will
build sedref.tex just once. The tmp.sed file is now generated as
refcard.sed, this is generated and deleted as a temporary file
within the sedref.tex recipe.
(2) Having created sedref.tex the recipes for refcard.dvi and
refcard.pdf both run various LaTeX based tools with sedref.tex as
the input file. The problem with this is that these tools all
rely on creating temporary files calls sedref.*.
If the refcard.dvi and refcard.pdf rules run at the same time then
these temporary files clash and overwrite each other causing the
build to fail.
We already copy the result file in order to rename it, our input
file is sedref.tex which results in an output file named
sedref.dvi or sedref.pdf, but we actually want refcard.dvi or
refcard.pdf. So within the recipe for refcard.dvi I copy the
input file from sedref.tex to sedref_dvi.tex. Now all the temp
files are named sedref_dvi.* and the output is sedref_dvi.dvi, I
then rename this new output file to refcard.dvi.
I've done the same thing for refcard.pdf, but I copy the input
to sedref_pdf.tex.
In this way the temp files no longer clash, and both recipes can
safely run in parallel.
After this commit I was able to reliably build all of the refcard
targets in parallel. There should be no change in the final file.
Approved-By: Tom Tromey <tom@tromey.com>
In gdb/doc/Makefile.in the TEXI2POD variable is used to invoke
texi2pod.pl, which process the .texinfo files. This also handles the
'include' directives within the .texinfo files.
Like the texi2dvi and texi2pdf tools, texi2pod.pl handles the -I flag
to add search directories for resolving 'include' directives within
.texinfo files.
When GDB runs TEXI2POD we include gdb-cfg.texi, which then includes
GDBvn.texi.
When building from a git checkout the gdb-cfg.texi files and
GDBvn.texi files will be created in the build directory, which is
where texi2pod.pl is invoked, so the files will be found just fine.
However, for a GDB release we ship gdb-cfg.texi and GDBvn.texi in the
source tree, along with the generated manual (.1 and .5) files.
So when building a release, what normally happens is that we spot that
the .1 and .5 man files are up to date, and don't run the recipe to
regenerate these files.
However, if we deliberately touch the *.texinfo files in a release
source tree, and then try to rebuild the man files, we'll get an error
like this:
make: Entering directory '/tmp/release-build/build/gdb/doc'
TEXI2POD gdb.1
cannot find GDBvn.texi at ../../../gdb-16.0.50.20240529/gdb/doc/../../etc/texi2pod.pl line 251, <GEN0> line 16.
make: *** [Makefile:664: gdb.1] Error 2
make: Leaving directory '/tmp/release-build/build/gdb/doc'
The problem is that texi2pod.pl doesn't know to look in the source
tree for the GDBvn.texi file.
If we compare this to the recipe for creating (for example) gdb.dvi,
which uses texi2dvi, this recipe adds '-I $(srcdir)' to the texi2dvi
command line, which allows texi2dvi to find GDBvn.texi in the source
tree.
In this commit I add a similar -I option to the texi2pod.pl command
line. After this, given a GDB release, it is possible to edit (or
just touch) the gdb.texinfo file and rebuild the man pages, the
GDBvn.texi will be picked up from the source tree.
If however a dependency for GDBvn.texi is changed in a release tree
then GDBvn.texi will be regenerated into the build directory and this
will be picked up in preference to the GDBvn.texi in the source tree,
just as you would want.
Approved-By: Tom Tromey <tom@tromey.com>
In a git checkout of the source code we don't have a version.subst
file in the gdb/doc directory. When building the GDB docs the
version.subst file is generated on demand (we have a recipe for that).
However, in a release tar file we do include a copy of the
version.subst file in the source tree, as a result the version.subst
recipe will not be run.
If, in a release build, we force the running of any recipe that
depends on version.subst then we run into a problem. For example,
slightly confusingly, if we 'touch gdb/doc/version.subst' within the
unpacked source tree of a release, then 'make -C gdb/doc GDBvn.texi'
in the build tree, we'll see:
make: Entering directory '/tmp/build/build/gdb/doc'
GEN GDBvn.texi
sed: can't read version.subst: No such file or directory
make: Leaving directory '/tmp/build/build/gdb/doc'
The problem is that every reference to version.subst in GDB's Makefile
assumes that the version.subst file will always be in the build
directory.
Handily version.subst is always the first dependency in every recipe
that uses that file. As such we can replace references to
version.subst with $<, make will expand this to the location where the
dependency was found.
In the case of the man page generation, the reference to version.subst
is hidden inside POD2MAN. It seemed a little confusing adding a use
of $< within POD2MAN, so I've moved the use into the recipe, which I
think is clearer.
I've also added comments for the two rules that I've modified to
explain our use of $<.
After this change it is possible to rebuild the man pages even when
version.subst is located in the source tree.
Approved-By: Tom Tromey <tom@tromey.com>
We have two rules, one each for building the .1 and .5 man pages. The
only actual difference is that one rule passes --section=1 and the
other passes --section=5 (see the definitions of POD2MAN1 and POD2MAN5
respectively.
I figure by using the suffix from the target of the rule we can
combine these two rules into one.
I use:
$(subst .,,$(suffix $@))
This gets the suffix from the target, either '.1' or '.5', and the
'subst' removes the '.' leaving '1' or '5'.
Now that I'm not using a static pattern rule for building the man
pages, the advice in the 'make' documentation is to not use $*, so
I've moved away from that to instead use $(basename $@), e.g. for
'gdbinit.5' this gives 'gdbinit', which is what we want.
There should be no difference in what is created after this change.
Approved-By: Tom Tromey <tom@tromey.com>
The build recipe for gdb.dvi and gdb.pdf contains instructions for
copying the GDBvn.texi file from the source tree into the build
directory if the GDBvn.texi file doesn't already exist in the build
directory.
The gdb.dvi and gdb.pdf targets also have a dependency on GDBvn.texi,
and we have a recipe for building GDBvn.texi.
What's happening here is this:
- In a git checkout of the source tree there is no GDBvn.texi in the
source tree, the GDBvn.texi dependency will trigger a rebuild of
GDBvn.texi, which is then used to build gdb.dvi and/or gdb.pdf.
- In a release tar file we do include a copy of GDBvn.texi. This
file will appear to be up to date, and so no copy of GDBvn.texi is
created within the build directory. Now when building gdb.dvi
and/or gdb.pdf we copy (or symlink) the version of GDBvn.texi from
the source tree into the build directory.
However, copying GDBvn.texi from the source directory is completely
unnecessary. The gdb.dvi/gdb.pdf recipes both invoke texi2dvi and
pass '-I $(srcdir)' as an argument, this means that texi2dvi will look
in the $(srcdir) to find included files, including GDBvn.texi.
As such I believe we can remove the code that copies GDBvn.texi from
the source tree into the build tree.
I've tested with a release build; creating a release with:
./src-release gdb
Then in an empty directory, unpacking the resulting .tar file,
creating a parallel build directory and doing the usual configure,
make, and 'make install'.
Having done this I can then 'touch gdb/doc/*.texinfo' in the unpacked
source tree, and do 'make -C gdb/doc pdf dvi' to rebuild all the pdf
and dvi files, this works fine without having to either build or copy
GDBvn.texi into the build directory.
Approved-By: Tom Tromey <tom@tromey.com>
Add a new 'error_message' feature to the qSupported packet. When GDB
supports this feature then gdbserver is able to send
errors in the E.errtext format for the qRcmd and m packets.
Update qRcmd packet and m packets documentation as qRcmd newly
accepts errors in a E.errtext format.
Previously these two packets didn't support E.errtext style errors.
Approved-By: Tom Tromey <tom@tromey.com>
Approved-By: Andrew Burgess <aburgess@redhat.com>
In commit:
commit 824083f34c
Date: Fri Apr 12 17:47:20 2024 +0100
gdb/doc: use silent-rules.mk in the Makefile
I rewrote the rules for building the man pages. While doing this I
accidentally switched from using MAN2POD5 to MAN2POD1 for generating
the file gdbinit.5.
Restore use of MAN2POD5 where appropriate.
org.gnu.gdb.i386.avx512 adds k registers, but these aren't mentioned in the
docs yet. Fix that.
In addition the documentation describes xmm registers with an `h`
(e.g. xmm16h). I am assuming that we follow the register xml files here,
which don't have the h suffix. So this removes that as well.
Approved-By: Eli Zaretskii <eliz@gnu.org>
While preparing the new release it was discovered that commit:
commit 824083f34c
Date: Fri Apr 12 17:47:20 2024 +0100
gdb/doc: use silent-rules.mk in the Makefile
was causing problems. Given a release tar file, an attempt to build
and install GDB would give an error like this:
[...]
TEXI2POD gdb.pod
cannot find GDBvn.texi at ../../../gdb-15.0.50.20240508/gdb/doc/../../etc/texi2pod.pl line 251, <GEN0> line 16.
make[5]: *** [Makefile:663: gdb.pod] Error 2
The problem here is how the man pages are built, and how they are
distributed within a release.
Within the development (git) tree, the man page files are not part of
the source tree, these files are built as needed. Within a release
tar file though, the man pages are included. The idea being that a
user can build and install GDB, including getting the man pages,
without having to install the tools needed to generate the man pages.
The man pages are generated in a two step process. First the .texi
file is processed with texi2pod to create a .pod file, then this .pod
file is processed to create the .1 or .5 man file.
Prior to the above commit these two steps were combined into a single
recipe, this meant that when a user performed a build/install from a
release tree all of the dependencies, as well as the final result,
were all present in the source tree, and so nothing needed to be
rebuilt.
However, the above commit split the two steps apart. Now we had a
separate rule for building the .pod files, and the .1/.5 man page
files depended on the relevant .pod file.
As the .pod files are not shipped in a GDB release, this meant that
one of the dependencies of the man page files was now missing. As a
result if a user tried to install from a release tree a rebuild of the
.pod files would be attempted, and if that succeeded then building the
man pages would follow that.
Unfortunately, building the .pod files would fail as the GDBvn.texi
file, though present in the source tree, was not present in the build
tree, which is where it is needed for the .pod file generation to
work.
To fix this, I propose merging the .pod creation and the .1/.5 man
page creation back into a single recipe. Having these two steps split
is probably the "cleaner" solution, but makes it harder for us to
achieve our goal of shipping the prebuilt man page files. I've added
a comment explaining what's going on (such a comment would have
prevented this mistake having been made in the first place).
One possibly weird thing here is that I have left both an
ECHO_TEXI2POD and a ECHO_TEXI2MAN in the rule $(MAN1S) and $(MAN5S)
recipes. This is 100% not going to break anything, these just print
two different progress messages while executing the recipes, but I'm
not sure if this is considered poor style or not. Maybe we're only
supposed to have a single ECHO_* per recipe?
Anyway, even if this is poor style, I figure it really is just a style
thing. We can tweak this later as needed. Otherwise, this commit
should fix the current issue blocking the next GDB release.
Approved-By: Tom Tromey <tom@tromey.com>
An Ada pretty-printer had a bug where its 'child' method returned a
gdb.Value rather than a tuple. Kévin suggested that the documentation
for this method could be improved to clarify this.
Reviewed-By: Kévin Le Gouguec <legouguec@adacore.com>
Approved-By: Eli Zaretskii <eliz@gnu.org>
When doing 'make -C gdb/doc man' to build the man pages, I noticed
that the outputs were being rebuilt each time the make command was
rerun, even when the input files hadn't changed.
This was caused by this commit:
commit 824083f34c
Date: Fri Apr 12 17:47:20 2024 +0100
gdb/doc: use silent-rules.mk in the Makefile
Which split the generation of the .pod file from the actual creation
of the man page file. Prior to this split it was OK to delete the
.pod file at the end of the recipe, the rule depending on the .texi
input file, and output was the .1 or .5 man page file.
Now however, with the split, the man page creation depends on the .pod
file, if we delete this after creating the .1 or .5 man page file then
the next time we run 'make' the .pod file is missing and is
regenerated, which in turn triggers the regeneration of the man page
file.
Fix this by leaving the .pod file around, and only cleaning up these
files in the 'mostlyclean' target.
Which leads to a second problem, the POD_FILE_TMPS is not created
correctly, so we don't actually clean up the .pod files! This too is
fixed in this commit.
After this commit running 'make -C gdb/doc man' will build the manual
pages the first time, and each subsequent run will do nothing.
Running 'make -C gdb/doc mostlyclean' will now delete the .pod files.
Approved-By: Tom Tromey <tom@tromey.com>
Make use of silent-rules.mk when building the GDB docs.
During review it was requested that there be more specific rules than
just reusing the general 'GEN' rule everywhere in the doc/ directory,
so I've added:
ECHO_DVIPS = @echo " DVIPS $@";
ECHO_TEX = @echo " TEX $@";
ECHO_PDFTEX = @echo " PDFTEX $@";
ECHO_TEXI2DVI = @echo " TEXI2DVI $@";
ECHO_MAKEHTML = @echo " MAKEHTML $@";
ECHO_TEXI2POD = @echo " TEXI2POD $@";
ECHO_TEXI2MAN = @echo " TEXI2MAN $@";
ECHO_MAKEINFO = @echo " MAKEINFO $@";
Then I've made use of these new silent rules and added lots of uses of
SILENT to reduce additional clutter.
As the man page generation is done in two phases, first the creation
of a .pod file, then the creation of the final man page file, I've
restructured the man page rules. Previously we had one rule for each
of the 5 man pages. I now have one general rule that will generate
all of the 5 .pod files, then I have two rules that convert the .pod
files into the final man pages.
I needed two rules for the man page generation as some man pages match
%.1 and some match %.5. I could combine these by using the GNU Make
.SECONDARYEXPANSION extension, but I think having two rules like this
is probably clearer, and the duplication is minimal.
Cleaning up the temporary .pod files is now moved into the
'mostlyclean' target rather than being done as soon as the man page is
created.
I've added a new SILENT_Q_FLAG to silent-rules.mk, this is like
SILENT_FLAG, but is set to '-q' when in silent mode, this can be used
with the 'dvips' and 'texi2dvi' commands, both of which use '-q' to
mean: only report errors.
As with the rest of the GDB makefiles, I've only converted the
"generation" rules to use silent-rules.mk, the install / uninstall
rules are left unchanged.
When looking at the 'diststuff' target, which generates the info and
man pages, I noticed the recipe for this rule just deleted a temporary
file. As that temporary file is already cleaned up as part of the
'clean' rule I've removed the deletion from the 'diststuff' target.
There are still a few "generation" targets that produce output, there
seems to be no flag to silence the 'tex' and 'pdftex' commands which
some recipes use, I've not worried about these for now, e.g. the
refcard.dvi and refcard.pdf targets still produce some output.
Luckily, when doing a 'make all' in the gdb/ directory, we only build
the info docs by default, and those rules are now nice and silent, so
a complete GDB build is now looking nice and quiet by default.
While working on this patch I noticed that 'make -j all-doc' doesn't
work (reliably), this is a preexisting bug in the way that dvi/pdf
targets are generated. For example gdb.dvi and gdb.pdf both use the
texi2dvi tool, which relies on temporary files to hold state. If both
these rules run in parallel then one (or both) of the recipes will
fail.
Luckily, the default docs target (all), which is what gets run when we
do 'make all' in the gdb/ directory, doesn't build the dvi and pdf
targets, so we're OK in that case.
I've not tried to fix this problem in this commit as it already
existed, and I don't want to do too much in one commit. I mention it
only because I ran into this issue while testing this commit.
In the following commits I intend to improve GDB's filename
completion. However, how filenames should be completed is a little
complex because GDB is not consistent with how it expects filename
arguments to be formatted.
This commit documents the current state of GDB when it comes to
formatting filename arguments.
Currently GDB will not correctly complete filenames inline with this
documentation; GDB will either fail to complete, or complete
incorrectly (i.e. the result of completion will not then be accepted
by GDB). However, later commits in this series will fix completion.
Approved-By: Eli Zaretskii <eliz@gnu.org>
For many years, GDB has accepted a "E.MESSAGE" error reponse, in
addition to "E NN". For many packets, GDB strips the "E." before
giving the error message to the user. For others, GDB does not strip
the "E.", but still understands that it is an error, as it starts with
"E", and either prints the whole string, or ignores it and just
mentions an error occured (same as for "E NN").
This has been the case for as long as I remember. Now that I check, I
see that it's been there since 2006 (commit a76d924dff, also here:
https://sourceware.org/pipermail/gdb-patches/2006-September/047286.html).
All along, I actually thought it was documented. Turns out it wasn't.
This commit documents it, in the new "Standard Replies" section, near
where we document "E NN".
The original version of this 3-patch documentation series was a single
CodeSourcery patch that documented the textual error as
"E.NAME.MESSAGE", with MESSAGE being 8-bit binary encoded. But I
think the ship has sailed for that. GDBserver has been sending error
messages with more than one "." for a long while, and with no binary
encoding. Still, I've preserved the "Co-Authored-By" list of the
original larger patch.
The 'qRcmd' and 'm' commands are exceptions and do not accept this
reply format. The top of the "Standard Replies" section already says:
"All commands support these, except as noted in the individual
command descriptions."
So this adds a note to the description of 'qRcmd' and 'm', explicitly
stating that they do not support this error reply format.
Change-Id: Ie4fee3d00d82ede39e439bf162e8cb7485532fd8
Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
Approved-By: Eli Zaretskii <eliz@gnu.org>
Currently, for each packet, we document the "E NN" response (error),
and the empty response (unsupported). This patch centralizes that in
a new "Standard Replies" section.
In the "Packets", "General Query Packets", "Tracepoint Packets"
sections, Remove explicit mention of empty and error replies, except
when they provide detail not covered in Standard Replies.
Note this hunk:
-@item E @var{NN}
-@var{NN} is errno
and this one:
-@item E00
-The request was malformed, or @var{annex} was invalid.
-
-@item E @var{nn}
-The offset was invalid, or there was an error encountered reading the data.
-The @var{nn} part is a hex-encoded @code{errno} value.
were really documenting things that don't really work that way.
The first is the documentation of the "m" packet. GDB does _not_
interpret the NN as an errno. It can't, in fact, because the
remote/target errno numbers have nothing to do with GDB/host errno
numbers in a cross debugging scenario.
The second hunk above is from the documentation of qXfer. Again, GDB
does not give any interpretation to the NN error code at all. Nor
does GDBserver. And again, an errno number can't be interpreted in a
cross debugging scenario.
Change-Id: I973695c80809cdb5a5e8d5be8b78ba4d1ecdb513
Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
Approved-By: Eli Zaretskii <eliz@gnu.org>
The 'PacketSize' attribute of the qSupported packet was
documented to be the maximum size of the packet including
the frame and checksum bytes, however this is not how it
was treated in the code. In reality, PacketSize is the
maximum size of the data in the RSP packets, not including
the framing or checksum bytes.
For instance, GDB's remote.c treats it as the maximum
number of data bytes. See remote_read_bytes_1, where the
size of the request is capped at PacketSize/2 (for
hex-encoding).
Also see gdbserver's server.cc, where the internal buffer
is sized as PBUFSIZ and PBUFSIZ-1 is used as PacketSize.
In gdbserver's case, the buffer is not used for any of the
framing or checksum characters. (I am not certain where the -1
comes from. I think it comes from back when there were no
binary packets, so packets were treated as strings with
null terminators).
It also seems like gdbservers in the wild treat it in
this way:
Embocosm doc:
https://www.embecosm.com/appnotes/ean4/embecosm-howto-rsp-server-ean4-issue-2.html#id3078000
A quick glance over openocd's gdb_server.c gdb_put_packet_inner()
function shows that the internal buffer also excludes the framing
and checksum.
Likewise, qEmu's gdbstub.c allocates PacketSize bytes for
the internal packet contents, and PacketSize+4 for the
full frame.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Approved-By: Pedro Alves <pedro@palves.net>
For some reason install-dvi is missing although other targets of the
same family are present. This looks like an oversight.
This enables calling 'make install-dvi' from the top-level build
directory.
Fix what looks like another oversight: include 'pdf' in 'all-doc' in
gdb/doc/Makefile.in.
Approved-By: Luis Machado <luis.machado@arm.com>
Tested-By: Luis Machado <luis.machado@arm.com>
The XML response to the "qXfer:threads:read" packet may include
a "handle" attribute. The attribute is mentioned in the document
but not shown in the sample XML structure. Add it.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
We now have unwind-on-timeout and unwind-on-terminating-exception, and
then the odd one out unwindonsignal.
I'm not a great fan of these squashed together command names, so in
this commit I propose renaming this to unwind-on-signal.
Obviously I've added the hidden alias unwindonsignal so any existing
GDB scripts will keep working.
There's one test that I've extended to test the alias works, but in
most of the other test scripts I've changed over to use the new name.
The docs are updated to reference the new name.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Tested-By: Luis Machado <luis.machado@arm.com>
Tested-By: Keith Seitz <keiths@redhat.com>
Now that inferior function calls can timeout (see the recent
introduction of direct-call-timeout and indirect-call-timeout), this
commit adds a new setting unwind-on-timeout.
This new setting is just like the existing unwindonsignal and
unwind-on-terminating-exception, but the new setting will cause GDB to
unwind the stack if an inferior function call times out.
The existing inferior function call timeout tests have been updated to
cover the new setting.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Tested-By: Luis Machado <luis.machado@arm.com>
Tested-By: Keith Seitz <keiths@redhat.com>
In the previous commits I have been working on improving inferior
function call support. One thing that worries me about using inferior
function calls from a conditional breakpoint is: what happens if the
inferior function call fails?
If the failure is obvious, e.g. the thread performing the call
crashes, or hits a breakpoint, then this case is already well handled,
and the error is reported to the user.
But what if the thread performing the inferior call just deadlocks?
If the user made the call from a 'print' or 'call' command, then the
user might have some expectation of when the function call should
complete, and, when this time limit is exceeded, the user
will (hopefully) interrupt GDB and regain control of the debug
session.
But, when the inferior function call is from a breakpoint condition it
is much harder to understand that GDB is deadlocked within an inferior
call. Maybe the breakpoint hasn't been hit yet? Or maybe the
condition was always false? Or maybe GDB is deadlocked in an inferior
call? The only way to know for sure is for the user to periodically
interrupt the inferior, check on the state of all the threads, and
then continue.
Additionally, the focus of the previous commit was inferior function
calls, from a conditional breakpoint, in a multi-threaded inferior.
This opens up a whole new set of potential failure conditions. For
example, what if the function called relies on interaction with some
other thread, and the other thread crashes? Or hits a breakpoint?
Given how inferior function calls work (in a synchronous manner), a
stop event in some other thread is going to be ignored while the
inferior function call is being executed as part of a breakpoint
condition, and this means that GDB could get stuck waiting for the
original condition thread, which will now never complete.
In this commit I propose a solution to this problem. A timeout. For
targets that support async-mode we can install an event-loop timer
before starting the inferior function call. When the timer expires we
will stop the thread performing the inferior function call. With this
mechanism in place a user can be sure that any inferior call they make
will either complete, or timeout eventually.
Adding a timer like this is obviously a change in behaviour for the
more common 'call' and 'print' uses of inferior function calls, so, in
this patch, I propose having two different timers. One I call the
'direct-call-timeout', which is used for 'call' and 'print' commands.
This timeout is by default set to unlimited, which, not surprisingly,
means there is no timeout in place.
A second timer, which I've called 'indirect-call-timeout', is used for
inferior function calls from breakpoint conditions. This timeout has
a default value of 30 seconds. This is a reasonably long time to
wait, and hopefully should be enough in most cases to allow the
inferior call to complete. An inferior call that takes more than 30
seconds, which is installed on a breakpoint condition is really going
to slow down the debug session, so hopefully this is not a common use
case.
The user is, of course, free to reduce, or increase the timeout value,
and can always use Ctrl-c to interrupt an inferior function call, but
this timeout will ensure that GDB will stop at some point.
The new commands added by this commit are:
set direct-call-timeout SECONDS
show direct-call-timeout
set indirect-call-timeout SECONDS
show indirect-call-timeout
These new timeouts do depend on async-mode, so, if async-mode is
disabled (maint set target-async off), or not supported (e.g. target
sim), then the timeout is treated as unlimited (that is, no timeout is
set).
For targets that "fake" non-async mode, e.g. Linux native, where
non-async mode is really just async mode, but then we park the target
in a sissuspend, we could easily fix things so that the timeouts still
work, however, for targets that really are not async aware, like the
simulator, fixing things so that timeouts work correctly would be a
much bigger task - that effort would be better spent just making the
target async-aware. And so, I'm happy for now that this feature will
only work on async targets.
The two new show commands will display slightly different text if the
current target is a non-async target, which should allow users to
understand what's going on.
There's a somewhat random test adjustment needed in gdb.base/help.exp,
the test uses a regexp with the apropos command, and expects to find a
single result. Turns out the new settings I added also matched the
regexp, which broke the test. I've updated the regexp a little to
exclude my new settings.
Reviewed-By: Tankut Baris Aktemur <tankut.baris.aktemur@intel.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Tested-By: Luis Machado <luis.machado@arm.com>
Tested-By: Keith Seitz <keiths@redhat.com>
This commit teaches GDB's gcore command to generate sparse core files
(if supported by the filesystem).
To create a sparse file, all you have to do is skip writing zeros to
the file, instead lseek'ing-ahead over them.
The sparse logic is applied when writing the memory sections, as
that's where the bulk of the data and the zeros are.
The commit also tweaks gdb.base/bigcore.exp to make it exercise
gdb-generated cores in addition to kernel-generated cores. We
couldn't do that before, because GDB's gcore on that test's program
would generate a multi-GB non-sparse core (16GB on my system).
After this commit, gdb.base/bigcore.exp generates, when testing with
GDB's gcore, a much smaller core file, roughly in line with what the
kernel produces:
real sizes:
$ du --hu testsuite/outputs/gdb.base/bigcore/bigcore.corefile.*
2.2M testsuite/outputs/gdb.base/bigcore/bigcore.corefile.gdb
2.0M testsuite/outputs/gdb.base/bigcore/bigcore.corefile.kernel
apparent sizes:
$ du --hu --apparent-size testsuite/outputs/gdb.base/bigcore/bigcore.corefile.*
16G testsuite/outputs/gdb.base/bigcore/bigcore.corefile.gdb
16G testsuite/outputs/gdb.base/bigcore/bigcore.corefile.kernel
Time to generate the core also goes down significantly. On my machine, I get:
when writing to an SSD, from 21.0s, down to 8.0s
when writing to an HDD, from 31.0s, down to 8.5s
The changes to gdb.base/bigcore.exp are smaller than they look at
first sight. It's basically mostly refactoring -- moving most of the
code to a new procedure which takes as argument who should dump the
core, and then calling the procedure twice. I purposely did not
modernize any of the refactored code in this patch.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=31494
Reviewed-By: Lancelot Six <lancelot.six@amd.com>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Reviewed-By: John Baldwin <jhb@FreeBSD.org>
Change-Id: I2554a6a4a72d8c199ce31f176e0ead0c0c76cff1
This patch deprecates the MPX commands "show/set mpx bound".
Intel listed Intel(R) Memory Protection Extensions (MPX) as removed
in 2019. Following gcc v9.1, the linux kernel v5.6 and glibc v2.35,
deprecate MPX in GDB.
This patch changes the Python "stop" event emission code to also add
the function return value, if it is known. This happens when the stop
comes from a "finish" command and when the value can be fetched.
The test is in the next patch.
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
The "python" command (and the Python implementation of the gdb
"source" command) does not handle Python exceptions in the same way as
other gdb-facing Python code. In particular, exceptions are turned
into a generic error rather than being routed through
gdbpy_handle_exception, which takes care of converting to 'quit' as
appropriate.
I think this was done this way because PyRun_SimpleFile and friends do
not propagate the Python exception -- they simply indicate that one
occurred.
This patch reimplements these functions to respect the general gdb
convention here. As a bonus, some Windows-specific code can be
removed, as can the _execute_file function.
The bulk of this change is tweaking the test suite to match the new
way that exceptions are displayed. These changes are largely
uninteresting. However, it's worth pointing out the py-error.exp
change. Here, the failure changes because the test changes the host
charset to something that isn't supported by Python. This then
results in a weird error in the new setup.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=31354
Acked-By: Tom de Vries <tdevries@suse.de>
Reviewed-By: Eli Zaretskii <eliz@gnu.org>
