mirror of
https://github.com/Zenithsiz/ftmemsim-valgrind.git
synced 2026-02-03 10:05:29 +00:00
39a063513c
This commit implements in python a set of GDB commands corresponding to the
Valgrind gdbserver monitor commands.
Basically, the idea is that one GDB command is defined for each valgrind
gdbserver subcommand and will generate and send a monitor command to valgrind.
The python code is auto-loaded by GDB as soon as GDB observes that the valgrind
preload core shared lib is loaded (e.g. vgpreload_core-amd64-linux.so).
This automatic loading is done thanks to the .debug_gdb_scripts section
added in vg_preloaded.c file.
Sadly, the auto-load only happens once valgrind has started to execute the code
of ld that loads this vg_preload file.
I have tried 2 approaches to have the python code auto-loaded when attaching at
startup to valgrind:
* have valgrind gdbserver reporting first to GDB that the executable file is
the tool executable (with a .debug_gdb_scripts section) and then reporting
the real (guest) executable file.
The drawback of this approach is that it triggers a warning/question in GDB
according to the GDB setting 'set exec-file-mismatch'.
* have valgrind gdbserver pretending to be multiprocess enabled, and report
a fake process using the tool executable with a .debug_gdb_scripts section.
The drawback of this is that this always creates a second inferior in GDB,
which will be confusing.
Possibly, we might complete the below message :
==2984378== (action at startup) vgdb me ...
==2984378==
==2984378== TO DEBUG THIS PROCESS USING GDB: start GDB like this
==2984378== /path/to/gdb /home/philippe/valgrind/littleprogs/some_mem
==2984378== and then give GDB the following command
==2984378== target remote | /home/philippe/valgrind/git/improve/Inst/libexec/valgrind/../../bin/vgdb --pid=2984378
==2984378== --pid is optional if only one valgrind process is running
with:
==2984378== GDB valgrind python specific commands will be auto-loaded when execution begins.
==2984378== Alternatively, you might load it before with the GDB command:
==2984378== source /abs/path/to/valgrind/install/libexec/valgrind/valgrind-monitor.py
The following GDB setting traces the monitor commands sent by a GDB valgrind
command to the valgrind gdbserver:
set debug valgrind-execute-monitor on
How to use the new GDB valgrind commands?
-----------------------------------------
The usage of the GDB front end commands is compatible with the
monitor command as accepted today by Valgrind.
For example, the memcheck monitor command "xb' has the following usage:
xb <addr> [<len>]
With some piece of code:
'char some_mem [5];'
xb can be used the following way:
(gdb) print &some_mem
(gdb) $2 = (char (*)[5]) 0x1ffefffe8b
(gdb) monitor xb 0x1ffefffe8b 5
ff ff ff ff ff
0x4A43040: 0x00 0x00 0x00 0x00 0x00
(gdb)
The same action can be done with the new GDB 'memcheck xb' command:
(gdb) memcheck xb 0x1ffefffe8b 5
ff ff ff ff ff
0x1FFEFFFE8B: 0x00 0x00 0x00 0x00 0x00
(gdb)
At this point, you might ask yourself: "what is the interest ?".
Using GDB valgrind commands provides several advantages compared to
the valgrind gdbserver monitor commands.
Evaluation of arguments by GDB:
-------------------------------
For relevant arguments, the GDB command will evaluate its arguments using
the usual GDB evaluation logic, for example, instead of printing/copying
the address and size of 'some_mem', the following will work:
(gdb) memcheck xb &some_mem sizeof(some_mem)
ff ff ff ff ff
0x1FFEFFFE8B: 0x00 0x00 0x00 0x00 0x00
(gdb)
or:
(gdb) p some_mem
$4 = "\000\000\000\000"
(gdb) memcheck xb &$4
ff ff ff ff ff
0x1FFEFFFE8B: 0x00 0x00 0x00 0x00 0x00
(gdb)
This is both easier to use interactively and easier to use in GDB scripts,
as you can directly use variable names in the GDB valgrind commands.
Command completion by GDB:
--------------------------
The usual command completion in GDB will work for the GDB valgrind commands.
For example, typing TAB after the letter 'l' in:
(gdb) valgrind v.info l
will show the 2 "valgrind v.info" subcommands:
last_error location
(gdb) valgrind v.info l
Note that as usual, GDB will recognise a command as soon as it is unambiguous.
Usual help and apropos support by GDB:
--------------------------------------
The Valgrind gdbserver provides an online help using:
(gdb) monitor help
However, this gives the help for all monitor commands, and is not searchable.
GDB provides a better help and documentation search.
For example, the following commands can be used to get various help
or search the GDB Valgrind command online documentation:
help valgrind
help memcheck
help helgrind
help callgrind
help massif
to get help about the general valgrind commands or the tool specific commands.
Examples of searching the online documentation:
apropos valgrind.*location
apropos -v validity
apropos -v leak
User can define aliases for the valgrind commands:
--------------------------------------------------
The following aliases are predefined:
v and vg for valgrind
mc for memcheck
hg for helgrind
cg for callgrind
ms for massif
So, the following will be equivalent:
(gdb) valgrind v.info location &some_mem
(gdb) v v.i lo &some_mem
(gdb) alias Vl = valgrind v.info location
(gdb) Vl &some_mem
Thanks to Hassan El Karouni for the help in factorising the python
code common to all valgrind python commands using a decorator.
Valgrind Documentation
----------------------
This text assumes the following directory structure:
Distribution text files (eg. AUTHORS, NEWS, ...):
valgrind/
Main /docs/ dir:
valgrind/docs/
Top-level XML files:
valgrind/docs/xml/
Tool specific XML docs:
valgrind/<toolname>/docs/
All images used in the docs:
valgrind/docs/images/
Stylesheets, catalogs, parsing/formatting scripts:
valgrind/docs/lib/
Some files of note:
docs/xml/index.xml: Top-level book-set wrapper
docs/xml/FAQ.xml: The FAQ
docs/valgrind-manpage.xml The valgrind manpage
docs/xml/vg-entities.xml: Various strings, dates etc. used all over
docs/xml/xml_help.txt: Basic guide to common XML tags.
The docs/internals directory contains some useful high-level stuff about
Valgrind's internals. It's not relevant for the rest of this discussion.
Overview
---------
The Documentation Set contains all books, articles, manpages,
etc. pertaining to Valgrind, and is designed to be built as:
- chunked html files
- PDF file
- PS file
- manpage
The whole thing is a "book set", made up of multiple books (the user
manual, the FAQ, the tech-docs, the licenses). Each book could be
made individually, but the build system doesn't do that.
CSS: the style-sheet used by the docs is the same as that used by the
website (consistency is king). It might be worth doing a pre-build diff
to check whether the website stylesheet has changed.
The build process
-----------------
It's not obvious exactly when things get built, and so on. Here's an
overview:
- The HTML docs can be built manually by running 'make html-docs' in
valgrind/docs/. (Don't use 'make html'; that is a valid built-in
automake target, but does nothing.) Likewise for PDF/PS with 'make
print-docs'.
- 'make dist' (nb: at the top level, not in docs/) puts the XML files
into the tarball. It also builds the HTML docs and puts them in too,
in valgrind/docs/html/ (including style sheets, images, etc).
- 'make install' installs the HTML docs in
$(install)/share/doc/valgrind/html/, if they are present. (They will
be present if you are installing from the result of a 'make dist'.
They might not be present if you are developing in a git workspace and
have not built them.) It doesn't install the XML docs, as they're not
useful installed.
If the XML processing tools ever mature enough to become standard, we
could just build the docs from XML when doing 'make install', which
would be simpler.
Notes on building HTML / PDF / PS documents
-------------------------------------------
Below are random notes and recollections about how to build documents
from the XML source at various times on various Linux distros. They're
mostly about the PDF/PS documents, because they are the hardest to
build.
Notes [May 2020]
----------------
The default pdf generation has switched to xmlto using fop.
Make sure to install the packages xmlto fop (and on Fedora
also xmlto-tex). For other package requirements, see below.
If fop is giving you trouble you can edit the docs/Makefile.am file
at the top to remove WITH_FOP. It will then fall back to pdfxmltex
for which you will need the hack described in "Notes [Mar 2015]".
On Fedora the pdftops command is provided by poppler-utils.
Notes [Jan 2019]
-----------------
For Ubuntu 18.04, to build HTML docs I had to:
sudo apt-get install xsltproc
Notes [May 2017]
----------------
Fedora 25: the "Notes [Sept 2015]" are still valid. But to summarise,
two steps are necessary:
(1) install packages as listed below
(2) apply Mark's epstopdf-base.sty hack as documented in "Notes [Mar 2015]"
Packages to install:
sudo dnf install texlive-xmltex texlive-xmltex-bin texlive-xmltex-doc \
texlive dblatex texlive-xmltex docbook-style-xsl docbook-dtds \
docbook-style-xsl.noarch docbook-simple.noarch docbook-simple.noarch \
docbook-slides.noarch docbook-style-dsssl.noarch docbook-utils.noarch \
docbook-utils-pdf.noarch docbook5-schemas.noarch \
docbook5-style-xsl.noarch passivetex
Notes [Sept 2015]
-----------------
Fedora 21 and 22: Had mucho trouble with building the print docs on
F21/22 even with the [Mar 2015] package set (or something similarish)
installed. Eventually installed "passivetex" and that fixes the
failures.
Installing the packages below on Fedora _might_ get you a working setup.
Also you need the epstopdf-base.sty hack detailed below.
texlive-xmltex texlive-xmltex-bin texlive-xmltex-doc texlive dblatex
texlive-xmltex docbook-style-xsl docbook-dtds docbook-style-xsl.noarch
docbook-simple.noarch docbook-simple.noarch docbook-slides.noarch
docbook-style-dsssl.noarch docbook-utils.noarch
docbook-utils-pdf.noarch docbook5-schemas.noarch
docbook5-style-xsl.noarch passivetex
Notes [Mar 2015]
----------------
On Ubuntu 14.04.2 LTS the following is known to work:
Required packages:
texlive
dblatex
xsltproc
xmltex
docbook-xml
docbook-xsl
Additional the following lines need to be changed in
/usr/share/texlive/texmf-dist/tex/latex/oberdiek/epstopdf-base.sty
around line 450 from
\ifETE@prepend
\expandafter\PrependGraphicsExtensions
\else
\expandafter\AppendGraphicsExtensions
\fi
{.eps}
to
%% \ifETE@prepend
%% \expandafter\PrependGraphicsExtensions
%% \else
%% \expandafter\AppendGraphicsExtensions
%% \fi
%% {.eps}
This hack was devised by Mark Wielaard.
Notes [Aug. 2012]
-----------------
On Ubuntu 10.04 there was a new capacity-related failure whilst
building the print docs in the run up to the 3.8.0 release. This was
fixed by editing /etc/texmf/texmf.cnf and changing pool_size to
2000000.
Notes [May 2009]
-----------------
For Ubuntu 9.04, to build HTML docs I had to:
sudo apt-get install docbook docbook-xsl
Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
definitely is.
To build the man pages I also changed the Makefile.am to try this
stylesheet:
/usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
if it can't find this one:
/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
I haven't succeeded in building the print docs.
Notes [Mar. 2007]
-----------------
For SuSE 10.1, I have to install the following packages to get a
working toolchain. Non-indented ones I asked YaST to install;
indented ones are extras it added on:
docbook_4
iso_ent
xmlcharent
docbook-dsssl-stylesheets
docbook_3
docbook-xsl-stylesheets
xmltex
gd
latex-ucs
te_latex
tetex
xaw3d
passivetex
xpdf
xpdf-tools
pdfxmltex still bombs when building the print docs. On SuSE 10.1 I
edited /etc/texmf/web2c/texmf.cnf and changed
pool_size.pdfxmltex = 500000
to
pool_size.pdfxmltex = 1500000
and that fixes it.
It is also reported that the print docs build OK on Fedora Core 5.
Notes [Nov. 2005]
-----------------
After upgrading to Suse 10, found a (known) bug in PassiveTex which
broke the build, so added a bug-fix to 'docs/lib/vg-fo.xsl'.
Bug-fix related links:
http://lists.oasis-open.org/archives/docbook/200509/msg00032.html
http://www.dpawson.co.uk/docbook/tools.html#d850e300
http://www.haskell.org/pipermail/glasgow-haskell-bugs/2005-January.txt
Notes [July 2005]
-----------------
jrs had to install zillions of packages on SuSE 9.2 in order to
build the print docs (make print-docs), including
passivetex
xpdf (for pdftops, which does the nicest job)
Even then, pdfxmltex eventually dies with "TeX capacity exceeded,
sorry [pool size = 67555]" or some such. To fix this, he edited
/etc/texmf/texmf.cnf and changed
pool_size.pdfxmltex = 500000
to
pool_size.pdfxmltex = 1500000
and that fixed it.
Notes [Nov. 2004]:
-----------------
- the end of file.xml must have only ONE newline after the last tag:
</book>
- pdfxmltex barfs if given a filename with an underscore in it
References:
----------
- samba have got all the stuff
http://websvn.samba.org/listing.php?rep=4&path=/trunk/&opt=dir&sc=1
excellent on-line howto reference:
- http://www.cogent.ca/
using automake with docbook:
- http://www.movement.uklinux.net/docs/docbook-autotools/index.html
Debugging catalog processing:
- http://xmlsoft.org/catalog.html#Declaring
xmlcatalog -v <catalog-file>
shell script to generate xml catalogs for docbook 4.1.2:
- http://xmlsoft.org/XSLT/docbook.html
configure.in re pdfxmltex
- http://cvs.sourceforge.net/viewcvs.py/logreport/service/configure.in?rev=1.325
some useful xls stylesheets in cvs:
- http://cvs.sourceforge.net/viewcvs.py/perl-xml/perl-xml-faq/
TODO LESS CRUCIAL:
------------------
- concat titlepage + subtitle page in fo output
- try and get the QuickStart and FAQ titlepage+toc+content onto one page