Name Date Size

..18-Aug.-20214 KiB

.dir-locals.elH A D31-May-2021545

.gitignoreH A D08-Sep.-202153.9 KiB

AUTHORSH A D31-May-20213.4 KiB

autogen.shH A D13-Aug.-2017191

auxprogs/H01-Sep.-20214 KiB

bionic.suppH A D13-Aug.-20171.3 KiB

cachegrind/H31-May-20214 KiB

callgrind/H31-May-20214 KiB

configure.acH A D21-Jul.-2021154.4 KiB

COPYINGH A D13-Aug.-201717.7 KiB

COPYING.DOCSH A D13-Aug.-201720 KiB

coregrind/H31-May-20214 KiB

darwin10-drd.suppH A D13-Aug.-20172.5 KiB

darwin10.suppH A D13-Aug.-20171.7 KiB

darwin11.suppH A D13-Aug.-20176.4 KiB

darwin12.suppH A D13-Aug.-20178.8 KiB

darwin13.suppH A D13-Aug.-20174.9 KiB

darwin14.suppH A D31-May-202114.1 KiB

darwin15.suppH A D31-May-202114.8 KiB

darwin16.suppH A D31-May-202115.6 KiB

darwin17.suppH A D31-May-202115.6 KiB

darwin9-drd.suppH A D13-Aug.-201710 KiB

darwin9.suppH A D13-Aug.-20177 KiB

dhat/H31-May-20214 KiB

docs/H31-May-20214 KiB

drd/H31-May-20214 KiB

exp-bbv/H31-May-20214 KiB

gdbserver_tests/H16-Jul.-202112 KiB

glibc-2.2-LinuxThreads-helgrind.suppH A D13-Aug.-20171.2 KiB

glibc-2.2.suppH A D13-Aug.-20179.3 KiB

glibc-2.3.suppH A D13-Aug.-201711 KiB

glibc-2.4.suppH A D13-Aug.-20174.7 KiB

glibc-2.5.suppH A D13-Aug.-20173.8 KiB

glibc-2.6.suppH A D13-Aug.-20174.7 KiB

glibc-2.7.suppH A D13-Aug.-2017695

glibc-2.X-drd.supp.inH A D21-Jul.-20217.2 KiB

glibc-2.X-helgrind.supp.inH A D21-Jul.-20216.4 KiB

glibc-2.X.supp.inH A D31-May-20216.3 KiB

helgrind/H31-May-20214 KiB

include/H31-May-20214 KiB

lackey/H31-May-20214 KiB

Makefile.all.amH A D31-May-202112.5 KiB

Makefile.amH A D21-Jul.-20213.8 KiB

Makefile.tool-tests.amH A D31-May-20212 KiB

Makefile.tool.amH A D31-May-20217.1 KiB

Makefile.vex.amH A D31-May-20216.6 KiB

massif/H31-May-20214 KiB

memcheck/H29-Jun.-20214 KiB

mpi/H31-May-20214 KiB

musl.suppH A D31-May-2021695

NEWSH A D07-Sep.-2021207.6 KiB

NEWS.oldH A D13-Aug.-201784.6 KiB

nightly/H13-Aug.-20174 KiB

none/H31-May-20214 KiB

perf/H31-May-20214 KiB

READMEH A D31-May-20213.3 KiB

README.aarch64H A D13-Aug.-20176.9 KiB

README.androidH A D13-Aug.-20177.6 KiB

README.android_emulatorH A D13-Aug.-20172 KiB

README.mipsH A D31-May-20212.5 KiB

README.s390H A D31-May-20212.1 KiB

README.solarisH A D31-May-20218.8 KiB

README_DEVELOPERSH A D31-May-202113.5 KiB

README_DEVELOPERS_processesH A D13-Aug.-20172.8 KiB

README_MISSING_SYSCALL_OR_IOCTLH A D31-May-20219.5 KiB

README_PACKAGERSH A D31-May-20214.5 KiB

shared/H31-May-20214 KiB

solaris/H31-May-20214 KiB

solaris11.suppH A D13-Aug.-2017878

solaris12.suppH A D13-Aug.-20173.7 KiB

tests/H01-Sep.-20214 KiB

valgrind.pc.inH A D13-Aug.-2017447

valgrind.spec.inH A D13-Aug.-20171.2 KiB

VEX/H31-May-20214 KiB

vg-in-placeH A D13-Aug.-2017691

xfree-3.suppH A D13-Aug.-20172.9 KiB

xfree-4.suppH A D13-Aug.-20178.8 KiB

README

1
2Release notes for Valgrind
3~~~~~~~~~~~~~~~~~~~~~~~~~~
4If you are building a binary package of Valgrind for distribution,
5please read README_PACKAGERS.  It contains some important information.
6
7If you are developing Valgrind, please read README_DEVELOPERS.  It contains
8some useful information.
9
10For instructions on how to build/install, see the end of this file.
11
12If you have problems, consult the FAQ to see if there are workarounds.
13
14
15Executive Summary
16~~~~~~~~~~~~~~~~~
17Valgrind is a framework for building dynamic analysis tools. There are
18Valgrind tools that can automatically detect many memory management
19and threading bugs, and profile your programs in detail. You can also
20use Valgrind to build new tools.
21
22The Valgrind distribution currently includes six production-quality
23tools: a memory error detector, two thread error detectors, a cache
24and branch-prediction profiler, a call-graph generating cache and
25branch-prediction profiler, and a heap profiler. It also includes
26three experimental tools: a heap/stack/global array overrun detector,
27a different kind of heap profiler, and a SimPoint basic block vector
28generator.
29
30Valgrind is closely tied to details of the CPU, operating system and to
31a lesser extent, compiler and basic C libraries. This makes it difficult
32to make it portable.  Nonetheless, it is available for the following
33platforms: 
34
35- X86/Linux
36- AMD64/Linux
37- PPC32/Linux
38- PPC64/Linux
39- ARM/Linux
40- ARM64/Linux
41- x86/macOS
42- AMD64/macOS
43- S390X/Linux
44- MIPS32/Linux
45- MIPS64/Linux
46- nanoMIPS/Linux
47- X86/Solaris
48- AMD64/Solaris
49
50Note that AMD64 is just another name for x86_64, and Valgrind runs fine
51on Intel processors.  Also note that the core of macOS is called
52"Darwin" and this name is used sometimes.
53
54Valgrind is licensed under the GNU General Public License, version 2. 
55Read the file COPYING in the source distribution for details.
56
57However: if you contribute code, you need to make it available as GPL
58version 2 or later, and not 2-only.
59
60
61Documentation
62~~~~~~~~~~~~~
63A comprehensive user guide is supplied.  Point your browser at
64$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
65specified with --prefix= when building.
66
67
68Building and installing it
69~~~~~~~~~~~~~~~~~~~~~~~~~~
70To install from the GIT repository:
71
72  0. Clone the code from GIT:
73     git clone git://sourceware.org/git/valgrind.git
74     There are further instructions at
75     http://www.valgrind.org/downloads/repository.html.
76
77  1. cd into the source directory.
78
79  2. Run ./autogen.sh to setup the environment (you need the standard
80     autoconf tools to do so).
81
82  3. Continue with the following instructions...
83
84To install from a tar.bz2 distribution:
85
86  4. Run ./configure, with some options if you wish.  The only interesting
87     one is the usual --prefix=/where/you/want/it/installed.
88
89  5. Run "make".
90
91  6. Run "make install", possibly as root if the destination permissions
92     require that.
93
94  7. See if it works.  Try "valgrind ls -l".  Either this works, or it
95     bombs out with some complaint.  In that case, please let us know
96     (see http://valgrind.org/support/bug_reports.html).
97
98Important!  Do not move the valgrind installation into a place
99different from that specified by --prefix at build time.  This will
100cause things to break in subtle ways, mostly when Valgrind handles
101fork/exec calls.
102
103
104The Valgrind Developers
105

README.aarch64

1
2Status
3~~~~~~
4
5As of Jan 2014 the trunk contains a port to AArch64 ARMv8 -- loosely,
6the 64-bit ARM architecture.  Currently it supports integer and FP
7instructions and can run anything generated by gcc-4.8.2 -O3.  The
8port is under active development.
9
10Current limitations, as of mid-May 2014.
11
12* limited support of vector (SIMD) instructions.  Initial target is
13  support for instructions created by gcc-4.8.2 -O3
14  (via autovectorisation).  This is complete.
15
16* Integration with the built in GDB server:
17   - works ok (breakpoint, attach to a process blocked in a syscall, ...)
18   - still to do:
19      arm64 xml register description files (allowing shadow registers
20                                            to be looked at).
21      cpsr transfer to/from gdb to be looked at (see also arm equivalent code)
22
23* limited syscall support
24
25There has been extensive testing of the baseline simulation of integer
26and FP instructions.  Memcheck is also believed to work, at least for
27small examples.  Other tools appear to at least not crash when running
28/bin/date.
29
30Enough syscalls and instructions are supported for substantial
31programs to work.  Firefox 26 is able to start up and quit.  The noise
32level from Memcheck is low enough to make it practical to use for real
33debugging.
34
35
36Building
37~~~~~~~~
38
39You could probably build it directly on a target OS, using the normal
40non-cross scheme
41
42  ./autogen.sh ; ./configure --prefix=.. ; make ; make install
43
44Development so far was however done by cross compiling, viz:
45
46  export CC=aarch64-linux-gnu-gcc
47  export LD=aarch64-linux-gnu-ld
48  export AR=aarch64-linux-gnu-ar
49
50  ./autogen.sh
51  ./configure --prefix=`pwd`/Inst --host=aarch64-unknown-linux \
52              --enable-only64bit
53  make -j4
54  make -j4 install
55
56Doing this assumes that the install path (`pwd`/Inst) is valid on
57both host and target, which isn't normally the case.  To avoid
58this limitation, do instead:
59
60  ./configure --prefix=/install/path/on/target \
61              --host=aarch64-unknown-linux \
62              --enable-only64bit
63  make -j4
64  make -j4 install DESTDIR=/a/temp/dir/on/host
65  # and then copy the contents of DESTDIR to the target.
66
67See README.android for more examples of cross-compile building.
68
69
70Implementation tidying-up/TODO notes
71~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
73UnwindStartRegs -- what should that contain?
74
75
76vki-arm64-linux.h: vki_sigaction_base
77I really don't think that __vki_sigrestore_t sa_restorer
78should be present.  Adding it surely puts sa_mask at a wrong
79offset compared to (kernel) reality.  But not having it causes
80compilation of m_signals.c to fail in hard to understand ways,
81so adding it temporarily.
82
83
84m_trampoline.S: what's the unexecutable-insn value? 0xFFFFFFFF 
85is there at the moment, but 0x00000000 is probably what it should be.
86Also, fix indentation/tab-vs-space stuff
87
88
89./include/vki/vki-arm64-linux.h: uses __uint128_t.  Should change
90it to __vki_uint128_t, but what's the defn of that?
91
92
93m_debuginfo/priv_storage.h: need proper defn of DiCfSI
94
95
96readdwarf.c: is this correct?
97#elif defined(VGP_arm64_linux)
98#  define FP_REG         29    //???
99#  define SP_REG         31    //???
100#  define RA_REG_DEFAULT 30    //???
101
102
103vki-arm64-linux.h:
104re linux-3.10.5/include/uapi/asm-generic/sembuf.h
105I'd say the amd64 version has padding it shouldn't have.  Check?
106
107
108syswrap-linux.c run_a_thread_NORETURN assembly sections
109seems like tst->os_state.exitcode has word type
110in which case the ppc64_linux use of lwz to read it, is wrong
111
112
113syswrap-linux.c ML_(do_fork_clone)
114assuming that VGP_arm64_linux is the same as VGP_arm_linux here
115
116
117dispatch-arm64-linux.S: FIXME: set up FP control state before
118entering generated code.  Also fix screwy indentation.
119
120
121dispatcher-ery general: what's a good (predictor-friendly) way to
122branch to a register?
123
124
125in vki-arm64-scnums.h
126//#if __BITS_PER_LONG == 64 && !defined(__SYSCALL_COMPAT)
127Probably want to reenable that and clean up accordingly
128
129
130putIRegXXorZR: figure out a way that the computed value is actually
131used, so as to keep any memory reads that might generate it, alive.
132(else the simulation can lose exceptions).  At least, for writes to
133the zero register generated by loads .. or .. can anything other
134integer instructions, that write to a register, cause exceptions?
135
136
137loads/stores: generate stack alignment checks as necessary
138
139
140fix barrier insns: ISB, DMB
141
142
143fix atomic loads/stores
144
145
146FMADD/FMSUB/FNMADD/FNMSUB: generate and use the relevant fused
147IROps so as to avoid double rounding
148
149
150ARM64Instr_Call getRegUsage: re-check relative to what
151getAllocableRegs_ARM64 makes available
152
153
154Make dispatch-arm64-linux.S save any callee-saved Q regs
155I think what is required is to save D8-D15 and nothing more than that.
156
157
158wrapper for __NR3264_fstat -- correct?
159
160
161PRE(sys_clone): get rid of references to vki_modify_ldt_t and the
162definition of it in vki-arm64-linux.h.  Ditto for 32 bit arm.
163
164
165sigframe-arm64-linux.c: build_sigframe: references to nonexistent
166siguc->uc_mcontext.trap_no, siguc->uc_mcontext.error_code have been
167replaced by zero.  Also in synth_ucontext.
168
169
170m_debugger.c:
171uregs.pstate   = LibVEX_GuestARM64_get_nzcv(vex); /* is this correct? */
172Is that remotely correct?
173
174
175host_arm64_defs.c: emit_ARM64INstr:
176ARM64in_VDfromX and ARM64in_VQfromXX: use simple top-half zeroing
177MOVs to vector registers instead of INS Vd.D[0], Xreg, to avoid false
178dependencies on the top half of the register.  (Or at least check
179the semantics of INS Vd.D[0] to see if it zeroes out the top.)
180
181
182preferredVectorSubTypeFromSize: review perf effects and decide
183on a types-for-subparts policy
184
185
186fold_IRExpr_Unop: add a reduction rule for this
1871Sto64(CmpNEZ64( Or64(GET:I64(1192),GET:I64(1184)) ))
188vis 1Sto64(CmpNEZ64(x)) --> CmpwNEZ64(x)
189
190
191check insn selection for memcheck-only primops:
192Left64 CmpwNEZ64 V128to64 V128HIto64 1Sto64 CmpNEZ64 CmpNEZ32
193widen_z_8_to_64 1Sto32 Left32 32HLto64 CmpwNEZ32 CmpNEZ8
194
195
196isel: get rid of various cases where zero is put into a register
197and just use xzr instead.  Especially for CmpNEZ64/32.  And for
198writing zeroes into the CC thunk fields.
199
200
201/* Keep this list in sync with that in iselNext below */
202/* Keep this list in sync with that for Ist_Exit above */
203uh .. they are not in sync
204
205
206very stupid:
207imm64  x23, 0xFFFFFFFFFFFFFFA0
20817 F4 9F D2 F7 FF BF F2 F7 FF DF F2 F7 FF FF F2 
209
210
211valgrind.h: fix VALGRIND_ALIGN_STACK/VALGRIND_RESTORE_STACK,
212also add CFI annotations
213
214
215could possibly bring r29 into use, which be useful as it is
216callee saved
217
218
219ubfm/sbfm etc: special case cases that are simple shifts, as iropt
220can't always simplify the general-case IR to a shift in such cases.
221
222
223LDP,STP (immediate, simm7) (FP&VEC)
224should zero out hi parts of dst registers in the LDP case
225
226
227DUP insns: use Iop_Dup8x16, Iop_Dup16x8, Iop_Dup32x4
228rather than doing it "by hand"
229
230
231Any place where ZeroHI64ofV128 is used in conjunction with
232FP vector IROps: find a way to make sure that arithmetic on
233the upper half of the values is "harmless."
234
235
236math_MINMAXV: use real Iop_Cat{Odd,Even}Lanes ops rather than
237inline scalar code
238
239
240chainXDirect_ARM64: use direct jump forms when possible
241

README.android

1
2How to cross-compile and run on Android.  Please read to the end,
3since there are important details further down regarding crash
4avoidance and GPU support.
5
6These notes were last updated on 4 Nov 2014, for Valgrind SVN
7revision 14689/2987.
8
9These instructions are known to work, or have worked at some time in
10the past, for:
11
12arm:
13  Android 4.0.3 running on a (rooted, AOSP build) Nexus S.
14  Android 4.0.3 running on Motorola Xoom.
15  Android 4.0.3 running on android arm emulator.
16  Android 4.1   running on android emulator.
17  Android 2.3.4 on Nexus S worked at some time in the past.
18
19x86:
20  Android 4.0.3 running on android x86 emulator.
21
22mips32:
23  Android 4.1.2 running on android mips emulator.
24  Android 4.2.2 running on android mips emulator.
25  Android 4.3   running on android mips emulator.
26  Android 4.0.4 running on BROADCOM bcm7425
27
28arm64:
29  Android 4.5 (?) running on ARM Juno
30
31On android-arm, GDBserver might insert breaks at wrong addresses.
32Feedback on this welcome.
33
34Other configurations and toolchains might work, but haven't been tested.
35Feedback is welcome.
36
37Toolchain:
38
39  For arm32, x86 and mips32 you need the android-ndk-r6 native
40    development kit.  r6b and r7 give a non-completely-working build;
41    see http://code.google.com/p/android/issues/detail?id=23203
42    For the android emulator, the versions needed and how to install
43    them are described in README.android_emulator.
44
45    You can get android-ndk-r6 from
46    http://dl.google.com/android/ndk/android-ndk-r6-linux-x86.tar.bz2
47
48  For arm64 (aarch64) you need the android-ndk-r10c NDK, from
49    http://dl.google.com/android/ndk/android-ndk-r10c-linux-x86_64.bin
50
51Install the NDK somewhere.  Doesn't matter where.  Then:
52
53
54# Modify this (obviously).  Note, this "export" command is only done
55# so as to reduce the amount of typing required.  None of the commands
56# below read it as part of their operation.
57#
58export NDKROOT=/path/to/android-ndk-r<version>
59
60
61# Then cd to the root of your Valgrind source tree.
62#
63cd /path/to/valgrind/source/tree
64
65
66# After this point, you don't need to modify anything.  Just copy and
67# paste the commands below.
68
69
70# Set up toolchain paths.
71#
72# For ARM
73export AR=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-ar
74export LD=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-ld
75export CC=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc
76
77# For x86
78export AR=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-ar
79export LD=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-ld
80export CC=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-gcc
81
82# For MIPS32
83export AR=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-ar
84export LD=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-ld
85export CC=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-gcc
86
87# For ARM64 (AArch64)
88export AR=$NDKROOT/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-ar 
89export LD=$NDKROOT/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-ld
90export CC=$NDKROOT/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-gcc
91
92
93# Do configuration stuff.  Don't mess with the --prefix in the
94# configure command below, even if you think it's wrong.
95# You may need to set the --with-tmpdir path to something
96# different if /sdcard doesn't work on the device -- this is
97# a known cause of difficulties.
98
99# The below re-generates configure, Makefiles, ...
100# This is not needed if you start from a release tarball.
101./autogen.sh
102
103# for ARM
104CPPFLAGS="--sysroot=$NDKROOT/platforms/android-3/arch-arm" \
105   CFLAGS="--sysroot=$NDKROOT/platforms/android-3/arch-arm" \
106   ./configure --prefix=/data/local/Inst \
107   --host=armv7-unknown-linux --target=armv7-unknown-linux \
108   --with-tmpdir=/sdcard
109# note: on android emulator, android-14 platform was also tested and works.
110# It is not clear what this platform nr really is.
111
112# for x86
113CPPFLAGS="--sysroot=$NDKROOT/platforms/android-9/arch-x86" \
114   CFLAGS="--sysroot=$NDKROOT/platforms/android-9/arch-x86 -fno-pic" \
115   ./configure --prefix=/data/local/Inst \
116   --host=i686-android-linux --target=i686-android-linux \
117   --with-tmpdir=/sdcard
118
119# for MIPS32
120CPPFLAGS="--sysroot=$NDKROOT/platforms/android-18/arch-mips" \
121   CFLAGS="--sysroot=$NDKROOT/platforms/android-18/arch-mips" \
122   ./configure --prefix=/data/local/Inst \
123   --host=mipsel-linux-android --target=mipsel-linux-android \
124   --with-tmpdir=/sdcard
125
126# for ARM64 (AArch64)
127CPPFLAGS="--sysroot=$NDKROOT/platforms/android-21/arch-arm64" \
128   CFLAGS="--sysroot=$NDKROOT/platforms/android-21/arch-arm64" \
129   ./configure --prefix=/data/local/Inst \
130   --host=aarch64-unknown-linux --target=aarch64-unknown-linux \
131   --with-tmpdir=/sdcard
132
133
134# At the end of the configure run, a few lines of details
135# are printed.  Make sure that you see these two lines:
136#
137# For ARM:
138#          Platform variant: android
139#     Primary -DVGPV string: -DVGPV_arm_linux_android=1
140#
141# For x86:
142#          Platform variant: android
143#     Primary -DVGPV string: -DVGPV_x86_linux_android=1
144#
145# For mips32:
146#          Platform variant: android
147#     Primary -DVGPV string: -DVGPV_mips32_linux_android=1
148#
149# For ARM64 (AArch64):
150#          Platform variant: android
151#     Primary -DVGPV string: -DVGPV_arm64_linux_android=1
152#
153# If you see anything else at this point, something is wrong, and
154# either the build will fail, or will succeed but you'll get something
155# which won't work.
156
157
158# Build, and park the install tree in `pwd`/Inst
159#
160make -j4
161make -j4 install DESTDIR=`pwd`/Inst
162
163
164# To get the install tree onto the device:
165# (I don't know why it's not "adb push Inst /data/local", but this
166# formulation does appear to put the result in /data/local/Inst.)
167#
168adb push Inst /
169
170
171# To run (on the device).  There are two things you need to consider:
172#
173# (1) if you are running on the Android emulator, Valgrind may crash
174#     at startup.  This is because the emulator (for ARM) may not be
175#     simulating a hardware TLS register.  To get around this, run
176#     Valgrind with:
177#       --kernel-variant=android-no-hw-tls
178# 
179# (2) if you are running a real device, you need to tell Valgrind
180#     what GPU it has, so Valgrind knows how to handle custom GPU
181#     ioctls.  You can choose one of the following:
182#       --kernel-variant=android-gpu-sgx5xx     # PowerVR SGX 5XX series
183#       --kernel-variant=android-gpu-adreno3xx  # Qualcomm Adreno 3XX series
184#     If you don't choose one, the program will still run, but Memcheck
185#     may report false errors after the program performs GPU-specific ioctls.
186#
187# Anyway: to run on the device:
188#
189/data/local/Inst/bin/valgrind [kernel variant args] [the usual args etc]
190
191
192# Once you're up and running, a handy modify-V-rebuild-reinstall
193# command line (on the host, of course) is
194#
195mq -j2 && mq -j2 install DESTDIR=`pwd`/Inst && adb push Inst /
196#
197# where 'mq' is an alias for 'make --quiet'.
198
199
200# One common cause of runs failing at startup is the inability of
201# Valgrind to find a suitable temporary directory.  On the device,
202# there doesn't seem to be any one location which we always have
203# permission to write to.  The instructions above use /sdcard.  If
204# that doesn't work for you, and you're Valgrinding one specific
205# application which is already installed, you could try using its
206# temporary directory, in /data/data, for example
207# /data/data/org.mozilla.firefox_beta.
208#
209# Using /system/bin/logcat on the device is helpful for diagnosing
210# these kinds of problems.
211

README.android_emulator

1
2How to install and run an android emulator.
3
4mkdir android # or any other place you prefer
5cd android
6
7# download java JDK
8# http://www.oracle.com/technetwork/java/javase/downloads/index.html
9# download android SDK
10# http://developer.android.com/sdk/index.html
11# download android NDK
12# http://developer.android.com/sdk/ndk/index.html
13
14# versions I used:
15#  jdk-7u4-linux-i586.tar.gz
16#  android-ndk-r8-linux-x86.tar.bz2
17#  android-sdk_r18-linux.tgz
18
19# install jdk
20tar xzf jdk-7u4-linux-i586.tar.gz
21
22# install sdk
23tar xzf android-sdk_r18-linux.tgz
24
25# install ndk
26tar xjf android-ndk-r8-linux-x86.tar.bz2
27
28
29# setup PATH to use the installed software:
30export SDKROOT=$HOME/android/android-sdk-linux
31export PATH=$PATH:$SDKROOT/tools:$SDKROOT/platform-tools
32export NDKROOT=$HOME/android/android-ndk-r8
33
34# install android platforms you want by starting:
35android 
36# (from $SDKROOT/tools)
37
38# select the platforms you need
39# I selected and installed:
40#   Android 4.0.3 (API 15)
41# Upgraded then to the newer version available:
42#     Android sdk 20
43#     Android platform tools 12
44
45# then define a virtual device:
46Tools -> Manage AVDs...
47# I define an AVD Name with 64 Mb SD Card, (4.0.3, api 15)
48# rest is default
49
50
51# compile and make install Valgrind, following README.android
52
53
54# Start your android emulator (it takes some time).
55# You can use adb shell to get a shell on the device
56# and see it is working. Note that I usually get
57# one or two time out from adb shell before it works
58adb shell
59
60# Once the emulator is ready, push your Valgrind to the emulator:
61adb push Inst /
62
63
64# IMPORTANT: when running Valgrind, you may need give it the flag
65#
66#    --kernel-variant=android-no-hw-tls
67#
68# since otherwise it may crash at startup.
69# See README.android for details.
70
71
72# if you need to debug:
73# You have on the android side a gdbserver
74# on the device side:
75gdbserver :1234 your_exe
76
77# on the host side:
78adb forward tcp:1234 tcp:1234
79$HOME/android/android-ndk-r8/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gdb your_exe
80target remote :1234
81
82

README.mips

1
2Supported platforms
3-------------------
4- MIPS32 and MIPS64 platforms are currently supported.
5- Both little-endian and big-endian cores are supported.
6- MIPS DSP ASE on MIPS32 platforms is supported.
7
8
9Building V for MIPS
10-------------------
11- Native build is available for all supported platforms. The build system
12expects that native GCC is configured correctly and optimized for the platform.
13Yet, this may not be the case with some Debian distributions which configure
14GCC to compile to "mips1" by default. Depending on a target platform, using
15CFLAGS="-mips32r2", CFLAGS="-mips32" or CFLAGS="-mips64" or
16CFLAGS="-mips64 -mabi=64" will do the trick and compile Valgrind correctly.
17
18- Use of cross-toolchain is supported as well.
19- Example of configure line and additional configure options:
20
21   $ ./configure --host=mipsel-linux-gnu --prefix=<path_to_install_directory>
22
23 * --host=mips-linux-gnu is necessary only if Valgrind is built on platform
24   other then MIPS, tools for building MIPS application have to be in PATH.
25
26 * --host=mips-linux-gnu is necessary if you compile it with cross toolchain
27   compiler for big endian platform.
28
29 * --host=mipsel-linux-musl is necessary if you compile it with cross toolchain
30   compiler for little endian platform.
31
32 * --host=nanomipseb-linux-gnu is necessary if you compile it with cross toolchain
33   compiler for nanoMIPS big endian platform.
34
35 * --host=nanomips-linux-gnu is necessary if you compile it with cross toolchain
36   compiler for nanoMIPS little endian platform.
37
38 * --build=mips-linux is needed if you want to build it for MIPS32 on 64-bit
39   MIPS system.
40
41 * If you are compiling Valgrind for mips32 with gcc version older then
42   gcc (GCC) 4.5.1, you must specify CFLAGS="-mips32r2 -mplt", e.g.
43
44   ./configure --prefix=<path_to_install_directory>
45   CFLAGS="-mips32r2 -mplt"
46
47
48Limitations
49-----------
50- Some gdb tests will fail when gdb (GDB) older than 7.5 is used and gdb is
51  not compiled with '--with-expat=yes'.
52- You can not compile tests for DSP ASE if you are using gcc (GCC) older
53  then 4.6.1 due to a bug in the toolchain.
54- Older GCC may have issues with some inline assembly blocks. Get a toolchain
55  based on newer GCC versions, if possible.
56- Systems with a mips64 cpu having only o32 libraries will misconfigure in case
57  no appropriate architecture flag is specified during configure time.
58  Be sure to set either mips32 or mips32r2 as the target architecture in that
59  case.
60- Some tests can not be compiled for nanoMIPS due to limitations in
61  preliminary GCC for nanoMIPS. You can use '-i' switch for building tests.
62

README.s390

1
2Requirements
3------------
4- You need GCC 3.4 or later to compile the s390 port.
5- To run valgrind a z10 machine or any later model is recommended.
6  Older machine models down to and including z990 may work but have
7  not been tested extensively.
8
9
10Limitations
11-----------
12- 31-bit client programs are not supported.
13- Hexadecimal floating point is not supported.
14- Transactional memory is not supported. The transactional-execution
15  facility is masked off from HWCAP.
16- FP signalling is not accurate. E.g., the "compare and signal"
17  instructions behave like their non-signalling counterparts.
18- memcheck, cachegrind, drd, helgrind, massif, lackey, and none are
19  supported. 
20- On machine models predating z10, cachegrind will assume a z10 cache
21  architecture. Otherwise, cachegrind will query the hosts cache system
22  and use those parameters.
23- callgrind and all experimental tools are currently not supported.
24- Some gcc versions use mvc to copy 4/8 byte values. This will affect
25  certain debug messages. For example, memcheck will complain about
26  4 one-byte reads/writes instead of just a single read/write.
27
28
29Hardware facilities
30-------------------
31Valgrind does not require that the host machine has the same hardware
32facilities as the machine for which the client program was compiled.
33This is convenient. If possible, the JIT compiler will translate the
34client instructions according to the facilities available on the host.
35This means, though, that probing for hardware facilities by issuing
36instructions from that facility and observing whether SIGILL is thrown
37may not work. As a consequence, programs that attempt to do so may
38behave differently. It is believed that this is a rare use case.
39
40
41Recommendations
42---------------
43Applications should be compiled with -fno-builtin to avoid
44false positives due to builtin string operations when running memcheck.
45
46
47Reading Material
48----------------
49(1) ELF ABI s390x Supplement
50    https://github.com/IBM/s390x-abi/releases
51(2) z/Architecture Principles of Operation
52    http://publibfp.dhe.ibm.com/epubs/pdf/a227832c.pdf
53(3) z/Architecture Reference Summary
54    https://www.ibm.com/support/pages/system/files/2020-07/SA22-7871-10.pdf
55

README.solaris

1Requirements
2------------
3- You need a recent Solaris-like OS to compile this port. Solaris 11 or
4  any illumos-based distribution should work, Solaris 10 is not supported.
5  Running `uname -r` has to print '5.11'.
6- Recent GCC tools are required, GCC 3 will probably not work. GCC version
7  4.5 (or higher) is recommended.
8- Solaris ld has to be the first linker in the PATH. GNU ld cannot be used.
9  There is currently no linker check in the configure script but the linking
10  phase fails if GNU ld is used. Recent Solaris/illumos distributions are ok.
11- A working combination of autotools is required: aclocal, autoheader,
12  automake and autoconf have to be found in the PATH. You should be able to
13  install pkg:/developer/build/automake and pkg:/developer/build/autoconf
14  packages to fulfil this requirement.
15- System header files are required. On Solaris, these can be installed with:
16    # pkg install system/header
17- GNU make is also required. On Solaris, this can be quickly achieved with:
18    $ PATH=/usr/gnu/bin:$PATH; export PATH
19- For remote debugging support, working GDB is required (see below).
20- For running regression tests, GNU sed, grep, awk, diff are required.
21  This can be quickly achieved on Solaris by prepending /usr/gnu/bin to PATH.
22
23
24Compilation
25-----------
26Please follow the generic instructions in the README file,
27in the section 'Building and installing it'.
28
29The configure script detects a canonical host to determine which version of
30Valgrind should be built. If the system compiler by default produces 32-bit
31binaries then only a 32-bit version of Valgrind will be built. To enable
32compilation of both 64-bit and 32-bit versions on such a system, issue the
33configure script as follows:
34./configure CC='gcc -m64' CXX='g++ -m64'
35
36
37Oracle Solaris and illumos support
38----------------------------------
39One of the main goal of this port is to support both Oracle Solaris and
40illumos kernels. This is a very hard task because Solaris kernel traditionally
41does not provide a stable syscall interface and because Valgrind contains
42several parts that are closely tied to the underlying kernel. For these
43reasons, the port needs to detect which syscall interfaces are present. This
44detection cannot be done easily at run time and is currently implemented as
45a set of configure tests. This means that a binary version of this port can be
46executed only on a kernel that is compatible with a kernel that was used
47during the configure and compilation time.
48
49Main currently-known incompatibilities:
50- Solaris 11 (released in November 2011) removed a large set of syscalls where
51  *at variant of the syscall was also present, for example, open() versus
52  openat(AT_FDCWD) [1]
53- syscall number for unlinkat() is 76 on Solaris 11, but 65 on illumos [2]
54- illumos (in April 2013) changed interface of the accept() and pipe()
55  syscalls [3]
56- posix_spawn() functionality is backed up by true spawn() syscall on Solaris 11.4
57  whereas illumos and Solaris 11.3 leverage vfork()
58- illumos and older Solaris use utimesys() syscall whereas newer Solaris
59  uses utimensat()
60
61[1] http://docs.oracle.com/cd/E26502_01/html/E28556/gkzlf.html#gkzip
62[2] https://www.illumos.org/issues/521
63[3] https://github.com/illumos/illumos-gate/commit/5dbfd19ad5fcc2b779f40f80fa05c1bd28fd0b4e
64
65
66Limitations
67-----------
68- The port is Work-In-Progress, many things may not work or they can be subtly
69  broken.
70- Coredumps produced by Valgrind do not contain all information available,
71  especially microstate accounting and processor bindings.
72- Accessing contents of /proc/self/psinfo is not thread-safe.  That is because
73  Valgrind emulates this file on behalf of the client programs.  Entire
74  open() - read() - close() sequence on this file needs to be performed
75  atomically.
76- Fork limitations: vfork() is translated to fork(), forkall() is not
77  supported.
78- Valgrind does not track definedness of some eflags (OF, SF, ZF, AF, CF, PF)
79  individually for each flag. After a syscall is finished, when a carry flag
80  is set and defined, all other mentioned flags will be also defined even
81  though they might be undefined before making the syscall.
82- System call "execve" with a file descriptor which points to a hardlink
83  is currently not supported. That is because from the opened file descriptor
84  itself it is not possible to reverse map the intended pathname.
85  Examples are fexecve(3C) and isaexec(3C).
86- Program headers PT_SUNW_SYSSTAT and PT_SUNW_SYSSTAT_ZONE are not supported.
87  That is, programs linked with mapfile directive RESERVE_SEGMENT and attribute
88  TYPE equal to SYSSTAT or SYSSTAT_ZONE will cause Valgrind exit. It is not
89  possible for Valgrind to arrange mapping of a kernel shared page at the
90  address specified in the mapfile for the guest application. There is currently
91  no such mechanism in Solaris. Hacky workarounds are possible, though.
92- When a thread has no stack then all system calls will result in Valgrind
93  crash, even though such system calls use just parameters passed in registers.
94  This should happen only in pathological situations when a thread is created
95  with custom mmap'ed stack and this stack is then unmap'ed during thread
96  execution.
97
98
99Remote debugging support
100------------------------
101Solaris port of GDB has a major flaw which prevents remote debugging from
102working correctly. Fortunately this flaw has an easy fix [4]. Unfortunately
103it is not present in the current GDB 7.6.2. This boils down to several
104options:
105- Use GDB shipped with Solaris 11.2 which has this flaw fixed.
106- Wait until GDB 7.7 becomes available (there won't be other 7.6.x releases).
107- Build GDB 7.6.2 with the fix by yourself using the following steps:
108    # pkg install developer/gnu-binutils
109    $ wget http://ftp.gnu.org/gnu/gdb/gdb-7.6.2.tar.gz
110    $ gzip -dc gdb-7.6.2.tar.gz | tar xf -
111    $ cd gdb-7.6.2
112    $ patch -p1 -i /path/to/valgrind-solaris/solaris/gdb-sol-thread.patch
113    $ export LIBS="-lncurses"
114    $ export CC="gcc -m64"
115    $ ./configure --with-x=no --with-curses --with-libexpat-prefix=/usr/lib
116    $ gmake && gmake install
117
118[4] https://sourceware.org/ml/gdb-patches/2013-12/msg00573.html
119
120
121TODO list
122---------
123- Fix few remaining failing tests.
124- Add more Solaris-specific tests (especially for the door and spawn
125  syscalls).
126- Provide better error reporting for various subsyscalls.
127- Implement storing of extra register state in signal frame.
128- Performance comparison against other platforms.
129- Prevent SIGPIPE when writing to a socket (coregrind/m_libcfile.c).
130- Implement ticket locking for fair scheduling (--fair-sched=yes).
131- Implement support in DRD and Helgrind tools for thr_join() with thread == 0.
132- Add support for accessing thread-local variables via gdb (auxprogs/getoff.c).
133  Requires research on internal libc TLS representation.
134- VEX supports AVX, BMI and AVX2. Investigate if they can be enabled on
135  Solaris/illumos.
136- Investigate support for more flags in AT_SUN_AUXFLAGS.
137- Fix Valgrind crash when a thread has no stack and syswrap-main.c accesses
138  all possible syscall parameters. Enable helgrind/tests/stackteardown.c
139  to see this in effect. Would require awareness of syscall parameter semantics.
140- Correctly print arguments of DW_CFA_ORCL_arg_loc in show_CF_instruction() when
141  it is implemented in libdwarf.
142- Handle a situation when guest program sets SC_CANCEL_FLG in schedctl and
143  Valgrind needs to invoke a syscall on its own.
144
145
146Summary of Solaris 11 Kernel Interfaces Used
147--------------------------------------------
148Valgrind uses directly the following kernel interfaces (not exhaustive list).
149Then, of course, it has very intimate knowledge of all syscalls, many ioctls
150and some door calls because it has wrappers around them.
151- Syscalls:
152  . clock_gettime
153  . close
154  . connect
155  . execve
156  . exit
157  . faccessat
158  . fcntl
159  . forksys
160  . fstatat
161  . getcwd
162  . getdents
163  . geteuid
164  . getgid
165  . getgroups
166  . getpeername
167  . getpid
168  . getrlimit
169  . getsockname
170  . getsockopt
171  . gettimeofday
172  . kill
173  . lseek
174  . lwp_create
175  . lwp_exit
176  . lwp_self
177  . lwp_sigqueue
178  . mknodat
179  . mmap
180  . mprotect
181  . munmap
182  . openat
183  . pipe
184  . pollsys
185  . pread
186  . prgpsys
187  . pwrite
188  . read
189  . readlinkat
190  . renameat
191  . rt_sigprocmask
192  . send
193  . setrlimit
194  . setsockopt
195  . sigaction
196  . sigreturn
197  . sigtimedwait
198  . so_socket
199  . spawn
200  . uname
201  . unlinkat
202  . waitsys
203  . write
204- Signal frames. Valgrind decomposes and synthetizes signal frames.
205- Flag sc_sigblock flag in the schedctl structure by replacing
206  function block_all_signals() from libc. The replacement emulates lwp_sigmask
207  syscall. More details in coregrind/vg_preloaded.c.
208- Initial stack layout for the main thread is synthetized.
209- procfs agent thread and other procfs commands for manipulating the process.
210- mmapobj syscall is emulated because it gets in the way of the address space
211  manager's control.
212
213
214Contacts
215--------
216Please send bug reports and any questions about the port to:
217Ivo Raisr <ivosh@ivosh.net>
218Petr Pavlu <setup@dagobah.cz>
219

README_DEVELOPERS

1Building and installing it
2~~~~~~~~~~~~~~~~~~~~~~~~~~
3To build/install from the GIT repository or from a distribution
4tarball, refer to the section with the same name in README.
5
6Building and not installing it
7~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8To run Valgrind without having to install it, run coregrind/valgrind
9with the VALGRIND_LIB environment variable set, where <dir> is the root
10of the source tree (and must be an absolute path).  Eg:
11
12  VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 
13
14This allows you to compile and run with "make" instead of "make install",
15saving you time.
16
17Or, you can use the 'vg-in-place' script which does that for you.
18
19I recommend compiling with "make --quiet" to further reduce the amount of
20output spewed out during compilation, letting you actually see any errors,
21warnings, etc.
22
23
24Building a distribution tarball
25~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26To build a distribution tarball from the valgrind sources:
27
28  make dist
29
30In addition to compiling, linking and packaging everything up, the command
31will also attempt to build the documentation.
32
33If you only want to test whether the generated tarball is complete and runs
34regression tests successfully, building documentation is not needed.
35
36  make dist BUILD_ALL_DOCS=no
37
38If you insist on building documentation some embarrassing instructions
39can be found in docs/README.
40
41
42Running the regression tests
43~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44To build and run all the regression tests, run "make [--quiet] regtest".
45
46To run a subset of the regression tests, execute:
47
48  perl tests/vg_regtest <name>
49
50where <name> is a directory (all tests within will be run) or a single
51.vgtest test file, or the name of a program which has a like-named .vgtest
52file.  Eg:
53
54  perl tests/vg_regtest memcheck
55  perl tests/vg_regtest memcheck/tests/badfree.vgtest
56  perl tests/vg_regtest memcheck/tests/badfree
57
58
59Running the performance tests
60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61To build and run all the performance tests, run "make [--quiet] perf".
62
63To run a subset of the performance suite, execute:
64
65  perl perf/vg_perf <name>
66
67where <name> is a directory (all tests within will be run) or a single
68.vgperf test file, or the name of a program which has a like-named .vgperf
69file.  Eg:
70
71  perl perf/vg_perf perf/
72  perl perf/vg_perf perf/bz2.vgperf
73  perl perf/vg_perf perf/bz2
74
75To compare multiple versions of Valgrind, use the --vg= option multiple
76times.  For example, if you have two Valgrinds next to each other, one in
77trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
78compare them on all the performance tests:
79
80  perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
81
82
83Debugging Valgrind with GDB
84~~~~~~~~~~~~~~~~~~~~~~~~~~~
85To debug the valgrind launcher program (<prefix>/bin/valgrind) just
86run it under gdb in the normal way.
87
88Debugging the main body of the valgrind code (and/or the code for
89a particular tool) requires a bit more trickery but can be achieved
90without too much problem by following these steps:
91
92(1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:
93
94      export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
95
96    or for an uninstalled version in a source directory $DIR:
97
98      export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
99
100(2) Run gdb on the tool executable.  Eg:
101
102      gdb /usr/local/lib/valgrind/lackey-ppc32-linux
103
104    or
105
106      gdb $DIR/.in_place/memcheck-x86-linux
107
108(3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
109    stopping on a SIGSEGV or SIGILL:
110
111    (gdb) handle SIGILL SIGSEGV nostop noprint
112
113    If you are using lldb, then the equivalent command is
114
115    (lldb) pro hand -p true -s false -n false SIGILL SIGSEGV
116
117(4) Set any breakpoints you want and proceed as normal for gdb. The
118    macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
119    a breakpoint VG_(do_exec), you could do like this in GDB:
120
121    (gdb) b vgPlain_do_exec
122
123(5) Run the tool with required options (the --tool option is required
124    for correct setup), e.g.
125
126    (gdb) run --tool=lackey pwd
127
128Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
129be fully expanded (ie. not an environment variable).
130
131A different and possibly easier way is as follows:
132
133(1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
134    puts the tool executable into a wait loop soon after it gains
135    control.  This delays startup for a few seconds.
136
137(2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
138    <pid> you read from the output printed by (1).  This attaches
139    GDB to the tool executable, which should be in the abovementioned
140    wait loop.
141
142(3) Do "cont" to continue.  After the loop finishes spinning, startup
143    will continue as normal.  Note that comment (3) above re passing
144    signals applies here too.
145
146
147Self-hosting
148~~~~~~~~~~~~
149This section explains :
150  (A) How to configure Valgrind to run under Valgrind.
151      Such a setup is called self hosting, or outer/inner setup.
152  (B) How to run Valgrind regression tests in a 'self-hosting' mode,
153      e.g. to verify Valgrind has no bugs such as memory leaks.
154  (C) How to run Valgrind performance tests in a 'self-hosting' mode,
155      to analyse and optimise the performance of Valgrind and its tools.
156
157(A) How to configure Valgrind to run under Valgrind:
158
159(1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
160    directly.  Outer runs Inner.
161
162(2) Configure Inner with --enable-inner and build as usual.
163
164(3) Configure Outer normally and build+install as usual.
165    Note: You must use a "make install"-ed valgrind.
166    Do *not* use vg-in-place for the Outer valgrind.
167
168(4) Choose a very simple program (date) and try
169
170    outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
171       --smc-check=all-non-file \
172       --run-libc-freeres=no --tool=cachegrind -v \
173       inner/.../vg-in-place --vgdb-prefix=./inner --tool=none -v prog
174
175If you omit the --trace-children=yes, you'll only monitor Inner's launcher
176program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
177it will try to find and run __libc_freeres in the inner, while libc is not
178used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
179gdbserver colliding with outer gdbserver.
180Currently, inner does *not* use the client request 
181VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
182translation chaining. So the outer needs --smc-check=all-non-file to
183detect the modified code.
184
185Debugging the whole thing might imply to use up to 3 GDB:
186  * a GDB attached to the Outer valgrind, allowing
187    to examine the state of Outer.
188  * a GDB using Outer gdbserver, allowing to
189    examine the state of Inner.
190  * a GDB using Inner gdbserver, allowing to
191    examine the state of prog.
192
193The whole thing is fragile, confusing and slow, but it does work well enough
194for you to get some useful performance data.  Inner has most of
195its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
196which helps a lot. However, when running regression tests in an Outer/Inner
197setup, this prefix causes the reg test diff to fail. Give 
198--sim-hints=no-inner-prefix to the Inner to disable the production
199of the prefix in the stdout/stderr output of Inner.
200
201The allocators in coregrind/m_mallocfree.c and VEX/priv/main_util.h are
202annotated with client requests so Memcheck can be used to find leaks
203and use after free in an Inner Valgrind.
204
205The Valgrind "big lock" is annotated with helgrind client requests
206so Helgrind and DRD can be used to find race conditions in an Inner
207Valgrind.
208
209All this has not been tested much, so don't be surprised if you hit problems.
210
211When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
212(on the outer). Otherwise, Callgrind has much higher memory requirements. 
213
214(B) Regression tests in an outer/inner setup:
215
216 To run all the regression tests with an outer memcheck, do :
217   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
218                         --all
219
220 To run a specific regression tests with an outer memcheck, do:
221   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
222                         none/tests/args.vgtest
223
224 To run regression tests with another outer tool:
225   perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
226                         --outer-tool=helgrind --all
227
228 --outer-args allows to give specific arguments to the outer tool,
229 replacing the default one provided by vg_regtest.
230
231Note: --outer-valgrind must be a "make install"-ed valgrind.
232Do *not* use vg-in-place.
233
234When an outer valgrind runs an inner valgrind, a regression test
235produces one additional file <testname>.outer.log which contains the
236errors detected by the outer valgrind.  E.g. for an outer memcheck, it
237contains the leaks found in the inner, for an outer helgrind or drd,
238it contains the detected race conditions.
239
240The file tests/outer_inner.supp contains suppressions for 
241the irrelevant or benign errors found in the inner.
242
243An regression test running in the inner (e.g. memcheck/tests/badrw) will
244cause the inner to report an error, which is expected and checked
245as usual when running the regtests in an outer/inner setup.
246However, the outer will often also observe an error, e.g. a jump
247using uninitialised data, or a read/write outside the bounds of a heap
248block. When the outer reports such an error, it will output the
249inner host stacktrace. To this stacktrace, it will append the
250stacktrace of the inner guest program. For example, this is an error
251reported by the outer when the inner runs the badrw regtest:
252  ==8119== Invalid read of size 2
253  ==8119==    at 0x7F2EFD7AF: ???
254  ==8119==    by 0x7F2C82EAF: ???
255  ==8119==    by 0x7F180867F: ???
256  ==8119==    by 0x40051D: main (badrw.c:5)
257  ==8119==    by 0x7F180867F: ???
258  ==8119==    by 0x1BFF: ???
259  ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
260  ==8119==    by 0x40055C: main (badrw.c:22)
261  ==8119==  Address 0x55cd03c is 4 bytes before a block of size 16 alloc'd
262  ==8119==    at 0x2804E26D: vgPlain_arena_malloc (m_mallocfree.c:1914)
263  ==8119==    by 0x2800BAB4: vgMemCheck_new_block (mc_malloc_wrappers.c:368)
264  ==8119==    by 0x2800BC87: vgMemCheck_malloc (mc_malloc_wrappers.c:403)
265  ==8119==    by 0x28097EAE: do_client_request (scheduler.c:1861)
266  ==8119==    by 0x28097EAE: vgPlain_scheduler (scheduler.c:1425)
267  ==8119==    by 0x280A7237: thread_wrapper (syswrap-linux.c:103)
268  ==8119==    by 0x280A7237: run_a_thread_NORETURN (syswrap-linux.c:156)
269  ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
270  ==8119==    by 0x4C294C4: malloc (vg_replace_malloc.c:298)
271  ==8119==    by 0x40051D: main (badrw.c:5)
272In the above, the first stacktrace starts with the inner host stacktrace,
273which in this case is some JITted code. Such code sometimes contains IPs
274that points in the inner guest code (0x40051D: main (badrw.c:5)).
275After the separator, we have the inner guest stacktrace.
276The second stacktrace gives the stacktrace where the heap block that was
277overrun was allocated. We see it was allocated by the inner valgrind
278in the client arena (first part of the stacktrace). The second part is
279the guest stacktrace that did the allocation.
280
281
282(C) Performance tests in an outer/inner setup:
283
284 To run all the performance tests with an outer cachegrind, do :
285    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
286
287 To run a specific perf test (e.g. bz2) in this setup, do :
288    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
289
290 To run all the performance tests with an outer callgrind, do :
291    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
292                      --outer-tool=callgrind perf
293
294Note: --outer-valgrind must be a "make install"-ed valgrind.
295Do *not* use vg-in-place.
296
297 To compare the performance of multiple Valgrind versions, do :
298    perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
299      --outer-tool=callgrind \
300      --vg=../inner_xxxx --vg=../inner_yyyy perf
301  (where inner_xxxx and inner_yyyy are the toplevel directories of
302  the versions to compare).
303  Cachegrind and cg_diff are particularly handy to obtain a delta
304  between the two versions.
305
306When the outer tool is callgrind or cachegrind, the following
307output files will be created for each test:
308   <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
309   <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
310 (where tt is the two letters abbreviation for the inner tool(s) run).
311
312For example, the command
313    perl perf/vg_perf \
314      --outer-valgrind=../outer_trunk/install/bin/valgrind \
315      --outer-tool=callgrind \
316      --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
317
318produces the files
319    callgrind.out.inner_tchain.no.many-loss-records.18465
320    callgrind.outer.log.inner_tchain.no.many-loss-records.18465
321    callgrind.out.inner_tchain.me.many-loss-records.21899
322    callgrind.outer.log.inner_tchain.me.many-loss-records.21899
323    callgrind.out.inner_trunk.no.many-loss-records.21224
324    callgrind.outer.log.inner_trunk.no.many-loss-records.21224
325    callgrind.out.inner_trunk.me.many-loss-records.22916
326    callgrind.outer.log.inner_trunk.me.many-loss-records.22916
327
328
329Printing out problematic blocks
330~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331If you want to print out a disassembly of a particular block that
332causes a crash, do the following.
333
334Try running with "--vex-guest-chase=no --trace-flags=10000000
335--trace-notbelow=999999".  This should print one line for each block
336translated, and that includes the address.
337
338Then re-run with 999999 changed to the highest bb number shown.
339This will print the one line per block, and also will print a
340disassembly of the block in which the fault occurred.
341

README_DEVELOPERS_processes

1This file documents various "processes" that are used by Valgrind
2developers for development and release activities.
3This file contains one section for each process.
4A summary of each process is given here. Each process is described
5more in details afterwards.
6
7
8* Update of the NEWS file: NEWS describes fixed bugs and new features.
9  It is updated and committed together with the code fixing the bug/implementing
10  the feature.
11
12* Major release production: 
13  See docs/internals/release-HOWTO.txt (currently a bit out of date)
14
15* Various guidelines/recommended usage for valgrind GIT
16  See docs/internals/git-HOWTO.txt
17
18* Minor/correction release production: TBD
19
20
21Processes detailed descriptions:
22
23Update of the NEWS file.
24========================
25  The NEWS file gives for each release:
26    - the list of fixed bugs,
27    - a short description of each functional change,
28    - a short description of each technical change impacting the users.
29  
30  The update of the NEWS file should be committed together with the
31  code change (or as part of the last committed change) that fixes the
32  bug or implements the new feature/technical change.
33  The documentation (e.g. user manual) should also be committed as part of
34  the code change.
35
36  Fixing a bug
37  ------------
38  When fixing a bug, add a line in the 'FIXED BUGS' section of
39  the NEWS file.  Keep the list of bugs sorted by bugzilla entry number.
40
41  Once you have commit the change, update the bug status in bugzilla,
42  adding in the comment the revision number of the commit fixing the bug.
43
44  If a bug is not entered in bugzilla (not encouraged), use "n-i-bz"
45  and add the bug line at the end of the bug list.
46
47  The file docs/internals/X_Y_BUGSTATUS.txt (where X_Y is the last
48  major release e.g. 3_9) contains information/statuses for some bugs.
49  If a bug is fixed, remove the (possible) bug info from this file.
50
51  Implementing a change
52  ---------------------
53  When implementing a functional or 'user impacting' technical change,
54  add a short description of the change in the relevant sub-section
55  (e.g. TOOL CHANGES, PLATFORM CHANGES, ...).
56
57
58  Some special cases:
59  -------------------
60  Some changes or bug fixes are very big and might be implemented over
61  a significant period. In such a case, update the NEWS as part of the
62  final commit.
63  If relevant, you might already update the NEWS file as part of
64  earlier commits, using the word 'PARTIAL' to indicate that the change or
65  bug fix is not complete yet.
66
67  Some bugs are reported more than once in bugzilla.
68  Also document in NEWS that such duplicated bugs have been fixed, using a line
69  such as:
70     308333 == 307106
71  to indicate that the bug 308333 is a duplicate of 307106, and was thus
72  fixed in the commit that fixed 307106.
73  Change also the status of the duplicated bug  in bugzilla,
74  indicating in the comment the commit revision that fixed the 'master bug'.
75

README_MISSING_SYSCALL_OR_IOCTL

1
2Dealing with missing system call or ioctl wrappers in Valgrind
3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4You're probably reading this because Valgrind bombed out whilst
5running your program, and advised you to read this file.  The good
6news is that, in general, it's easy to write the missing syscall or
7ioctl wrappers you need, so that you can continue your debugging.  If
8you send the resulting patches to me, then you'll be doing a favour to
9all future Valgrind users too.
10
11Note that an "ioctl" is just a special kind of system call, really; so
12there's not a lot of need to distinguish them (at least conceptually)
13in the discussion that follows.
14
15All this machinery is in coregrind/m_syswrap.
16
17
18What are syscall/ioctl wrappers?  What do they do?
19~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20Valgrind does what it does, in part, by keeping track of everything your
21program does.  When a system call happens, for example a request to read
22part of a file, control passes to the Linux kernel, which fulfills the
23request, and returns control to your program.  The problem is that the
24kernel will often change the status of some part of your program's memory
25as a result, and tools (instrumentation plug-ins) may need to know about
26this.
27
28Syscall and ioctl wrappers have two jobs: 
29
301. Tell a tool what's about to happen, before the syscall takes place.  A
31   tool could perform checks beforehand, eg. if memory about to be written
32   is actually writeable.  This part is useful, but not strictly
33   essential.
34
352. Tell a tool what just happened, after a syscall takes place.  This is
36   so it can update its view of the program's state, eg. that memory has
37   just been written to.  This step is essential.
38
39The "happenings" mostly involve reading/writing of memory.
40
41So, let's look at an example of a wrapper for a system call which
42should be familiar to many Unix programmers.
43
44
45The syscall wrapper for time()
46~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47The wrapper for the time system call looks like this:
48
49  PRE(sys_time)
50  {
51     /* time_t time(time_t *t); */
52     PRINT("sys_time ( %p )",ARG1);
53     PRE_REG_READ1(long, "time", int *, t);
54     if (ARG1 != 0) {
55        PRE_MEM_WRITE( "time(t)", ARG1, sizeof(vki_time_t) );
56     }
57  }
58
59  POST(sys_time)
60  {  
61     if (ARG1 != 0) {
62        POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
63     }
64  }
65
66The first thing we do happens before the syscall occurs, in the PRE() function.
67The PRE() function typically starts with invoking to the PRINT() macro. This
68PRINT() macro implements support for the --trace-syscalls command line option.
69Next, the tool is told the return type of the syscall, that the syscall has
70one argument, the type of the syscall argument and that the argument is being
71read from a register:
72
73     PRE_REG_READ1(long, "time", int *, t);
74
75Next, if a non-NULL buffer is passed in as the argument, tell the tool that the
76buffer is about to be written to:
77
78     if (ARG1 != 0) {
79        PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) );
80     }
81
82Finally, the really important bit, after the syscall occurs, in the POST()
83function:  if, and only if, the system call was successful, tell the tool that
84the memory was written:
85
86     if (ARG1 != 0) {
87        POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
88     }
89
90The POST() function won't be called if the syscall failed, so you
91don't need to worry about checking that in the POST() function.
92(Note: this is sometimes a bug; some syscalls do return results when
93they "fail" - for example, nanosleep returns the amount of unslept
94time if interrupted. TODO: add another per-syscall flag for this
95case.)
96
97Note that we use the type 'vki_time_t'.  This is a copy of the kernel
98type, with 'vki_' prefixed.  Our copies of such types are kept in the
99appropriate vki*.h file(s).  We don't include kernel headers or glibc headers
100directly.
101
102
103Writing your own syscall wrappers (see below for ioctl wrappers)
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105If Valgrind tells you that system call NNN is unimplemented, do the 
106following:
107
1081.  Find out the name of the system call:
109
110       grep NNN /usr/include/asm/unistd*.h
111
112    This should tell you something like  __NR_mysyscallname.
113    Copy this entry to include/vki/vki-scnums-$(VG_PLATFORM).h.
114
115    If you can't find the system call in /usr/include, try looking in the
116    strace source code (https://github.com/strace/strace). Some syscalls/ioctls
117    are not defined explicitly, but strace may have already figured it out.
118
119
1202.  Do 'man 2 mysyscallname' to get some idea of what the syscall
121    does.  Note that the actual kernel interface can differ from this,
122    so you might also want to check a version of the Linux kernel
123    source.
124
125    NOTE: any syscall which has something to do with signals or
126    threads is probably "special", and needs more careful handling.
127    Post something to valgrind-developers if you aren't sure.
128
129
1303.  Add a case to the already-huge collection of wrappers in 
131    the coregrind/m_syswrap/syswrap-*.c files. 
132    For each in-memory parameter which is read or written by
133    the syscall, do one of
134    
135      PRE_MEM_READ( ... )
136      PRE_MEM_RASCIIZ( ... ) 
137      PRE_MEM_WRITE( ... ) 
138      
139    for  that parameter.  Then do the syscall.  Then, if the syscall
140    succeeds, issue suitable POST_MEM_WRITE( ... ) calls.
141    (There's no need for POST_MEM_READ calls.)
142
143    Also, add it to the syscall_table[] array; use one of GENX_, GENXY
144    LINX_, LINXY, PLAX_, PLAXY.
145    GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux
146    specific ones (in syswrap-linux.c) and PLA* for the platform
147    dependent ones (in syswrap-$(PLATFORM)-linux.c).
148    The *XY variant if it requires a PRE() and POST() function, and
149    the *X_ variant if it only requires a PRE()
150    function.  
151    
152    If you find this difficult, read the wrappers for other syscalls
153    for ideas.  A good tip is to look for the wrapper for a syscall
154    which has a similar behaviour to yours, and use it as a 
155    starting point.
156
157    If you need structure definitions and/or constants for your syscall,
158    copy them from the kernel headers into include/vki.h and co., with
159    the appropriate vki_*/VKI_* name mangling.  Don't #include any
160    kernel headers.  And certainly don't #include any glibc headers.
161
162    Test it.
163
164    Note that a common error is to call POST_MEM_WRITE( ... )
165    with 0 (NULL) as the first (address) argument.  This usually means
166    your logic is slightly inadequate.  It's a sufficiently common bug
167    that there's a built-in check for it, and you'll get a "probably
168    sanity check failure" for the syscall wrapper you just made, if this
169    is the case.
170
171
1724.  Once happy, send us the patch.  Pretty please.
173
174
175
176
177Writing your own ioctl wrappers
178~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
180Is pretty much the same as writing syscall wrappers, except that all
181the action happens within PRE(ioctl) and POST(ioctl).
182
183There's a default case, sometimes it isn't correct and you have to write a
184more specific case to get the right behaviour.
185
186As above, please create a bug report and attach the patch as described
187on http://www.valgrind.org.
188
189
190Writing your own door call wrappers (Solaris only)
191~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
192
193Unlike syscalls or ioctls, door calls transfer data between two userspace
194programs, albeit through a kernel interface. Programs may use completely
195proprietary semantics in the data buffers passed between them.
196Therefore it may not be possible to capture these semantics within
197a Valgrind door call or door return wrapper.
198
199Nevertheless, for system or well-known door services it would be beneficial
200to have a door call and a door return wrapper. Writing such wrapper is pretty
201much the same as writing ioctl wrappers. Please take a few moments to study
202the following picture depicting how a door client and a door server interact
203through the kernel interface in a typical scenario:
204
205
206door client thread          kernel       door server thread
207invokes door_call()                     invokes door_return()
208-------------------------------------------------------------------
209                               <----  PRE(sys_door, DOOR_RETURN)
210PRE(sys_door, DOOR_CALL)  --->
211                               ---->  POST(sys_door, DOOR_RETURN)
212                                           ----> server_procedure()
213                                           <----
214                               <----  PRE(sys_door, DOOR_RETURN)
215POST(sys_door, DOOR_CALL) <---
216
217The first PRE(sys_door, DOOR_RETURN) is invoked with data_ptr=NULL
218and data_size=0. That's because it has not received any data from
219a door call, yet.
220
221Semantics are described by the following functions
222in coregring/m_syswrap/syswrap-solaris.c module:
223o For a door call wrapper the following attributes of 'params' argument:
224  - data_ptr (and associated data_size) as input buffer (request);
225      described in door_call_pre_mem_params_data()
226  - rbuf (and associated rsize) as output buffer (response);
227      described in door_call_post_mem_params_rbuf()
228o For a door return wrapper the following parameters:
229  - data_ptr (and associated data_size) as input buffer (request);
230      described in door_return_post_mem_data()
231  - data_ptr (and associated data_size) as output buffer (response);
232      described in door_return_pre_mem_data()
233
234There's a default case which may not be correct and you have to write a
235more specific case to get the right behaviour. Unless Valgrind's option
236'--sim-hints=lax-doors' is specified, the default case also spits a warning.
237
238As above, please create a bug report and attach the patch as described
239on http://www.valgrind.org.
240

README_PACKAGERS

1
2Greetings, packaging person!  This information is aimed at people
3building binary distributions of Valgrind.
4
5Thanks for taking the time and effort to make a binary distribution of
6Valgrind.  The following notes may save you some trouble.
7
8-- If your toolchain (compiler, linker) support lto, using the configure
9   option --enable-lto=yes will produce a smaller/faster valgrind
10   (up to 10%).
11
12-- Do not ship your Linux distro with a completely stripped
13   /lib/ld.so.  At least leave the debugging symbol names on -- line
14   number info isn't necessary.  If you don't want to leave symbols on
15   ld.so, alternatively you can have your distro install ld.so's
16   debuginfo package by default, or make ld.so.debuginfo be a
17   requirement of your Valgrind RPM/DEB/whatever.
18
19   Reason for this is that Valgrind's Memcheck tool needs to intercept
20   calls to, and provide replacements for, some symbols in ld.so at
21   startup (most importantly strlen).  If it cannot do that, Memcheck
22   shows a large number of false positives due to the highly optimised
23   strlen (etc) routines in ld.so.  This has caused some trouble in
24   the past.  As of version 3.3.0, on some targets (ppc32-linux,
25   ppc64-linux), Memcheck will simply stop at startup (and print an
26   error message) if such symbols are not present, because it is
27   infeasible to continue.
28
29   It's not like this is going to cost you much space.  We only need
30   the symbols for ld.so (a few K at most).  Not the debug info and
31   not any debuginfo or extra symbols for any other libraries.
32
33
34-- (Unfortunate but true) When you configure to build with the
35   --prefix=/foo/bar/xyzzy option, the prefix /foo/bar/xyzzy gets
36   baked into valgrind.  The consequence is that you _must_ install
37   valgrind at the location specified in the prefix.  If you don't,
38   it may appear to work, but will break doing some obscure things,
39   particularly doing fork() and exec().
40
41   So you can't build a relocatable RPM / whatever from Valgrind.
42
43
44-- Don't strip the debug info off lib/valgrind/$platform/vgpreload*.so
45   in the installation tree.  Either Valgrind won't work at all, or it
46   will still work if you do, but will generate less helpful error
47   messages.  Here's an example:
48
49   Mismatched free() / delete / delete []
50      at 0x40043249: free (vg_clientfuncs.c:171)
51      by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
52      by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
53      by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
54      Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
55      at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152)
56      by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
57      by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
58      by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
59
60   This tells you that some memory allocated with new[] was freed with
61   free().
62
63   Mismatched free() / delete / delete []
64      at 0x40043249: (inside vgpreload_memcheck.so)
65      by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
66      by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
67      by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
68      Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
69      at 0x4004318C: (inside vgpreload_memcheck.so)
70      by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
71      by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
72      by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
73
74   This isn't so helpful.  Although you can tell there is a mismatch, 
75   the names of the allocating and deallocating functions are no longer
76   visible.  The same kind of thing occurs in various other messages 
77   from valgrind.
78
79
80-- Don't strip symbols from lib/valgrind/* in the installation tree.
81   Doing so will likely cause problems.  Removing the line number info is
82   probably OK (at least for some of the files in that directory), although
83   that has not been tested by the Valgrind developers.
84
85
86-- Please test the final installation works by running it on something
87   huge.  I suggest checking that it can start and exit successfully
88   both Firefox and OpenOffice.org.  I use these as test programs, and I
89   know they fairly thoroughly exercise Valgrind.  The command lines to use
90   are:
91
92   valgrind -v --trace-children=yes firefox
93
94   valgrind -v --trace-children=yes soffice
95
96
97If you find any more hints/tips for packaging, please report
98it as a bugreport. See http://www.valgrind.org for details.
99