Name Date Size

..29-Nov-20194 KiB

.dir-locals.elH A D09-Feb-2019545

.gitignoreH A D09-Feb-201957.2 KiB

AUTHORSH A D09-Feb-20193.2 KiB

autogen.shH A D13-Aug-2017191

auxprogs/H09-Feb-20194 KiB

bionic.suppH A D13-Aug-20171.3 KiB

cachegrind/H09-Feb-20194 KiB

callgrind/H09-Feb-20194 KiB

configure.acH A D09-Feb-2019145.5 KiB

COPYINGH A D13-Aug-201717.7 KiB

COPYING.DOCSH A D13-Aug-201720 KiB

coregrind/H09-Feb-20194 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 D09-Feb-201914.1 KiB

darwin15.suppH A D09-Feb-201914.8 KiB

darwin16.suppH A D09-Feb-201916.1 KiB

darwin17.suppH A D09-Feb-201915.6 KiB

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

darwin9.suppH A D13-Aug-20177 KiB

dhat/H09-Feb-20194 KiB

docs/H09-Feb-20194 KiB

drd/H09-Feb-20194 KiB

exp-bbv/H09-Feb-20194 KiB

exp-dhat/docs/H09-Feb-20194 KiB

exp-sgcheck/H09-Feb-20194 KiB

exp-sgcheck.suppH A D13-Aug-2017372

gdbserver_tests/H09-Feb-201912 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.34567-NPTL-helgrind.suppH A D13-Aug-20176.3 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.suppH A D09-Feb-20197.1 KiB

glibc-2.X.supp.inH A D09-Feb-20195.6 KiB

helgrind/H09-Feb-20194 KiB

include/H09-Feb-20194 KiB

lackey/H09-Feb-20194 KiB

Makefile.all.amH A D09-Feb-201912 KiB

Makefile.amH A D09-Feb-20193.8 KiB

Makefile.tool-tests.amH A D09-Feb-20192 KiB

Makefile.tool.amH A D13-Aug-20176.9 KiB

Makefile.vex.amH A D09-Feb-20196.4 KiB

massif/H09-Feb-20194 KiB

memcheck/H09-Feb-20194 KiB

mpi/H13-Aug-20174 KiB

NEWSH A D09-Feb-2019184.5 KiB

NEWS.oldH A D13-Aug-201784.6 KiB

nightly/H13-Aug-20174 KiB

none/H09-Feb-20194 KiB

perf/H13-Aug-20174 KiB

READMEH A D09-Feb-20193.2 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 D13-Aug-20171.9 KiB

README.s390H A D09-Feb-20192.3 KiB

README.solarisH A D13-Aug-20178.8 KiB

README_DEVELOPERSH A D09-Feb-201913.3 KiB

README_DEVELOPERS_processesH A D13-Aug-20172.8 KiB

README_MISSING_SYSCALL_OR_IOCTLH A D13-Aug-20179.2 KiB

README_PACKAGERSH A D09-Feb-20194.5 KiB

shared/H09-Feb-20194 KiB

solaris/H09-Feb-20194 KiB

solaris11.suppH A D13-Aug-2017878

solaris12.suppH A D13-Aug-20173.7 KiB

tests/H09-Feb-20194 KiB

valgrind.pc.inH A D13-Aug-2017447

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

VEX/H09-Feb-20194 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 abd
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- x86/macOS
41- AMD64/macOS
42- S390X/Linux
43- MIPS32/Linux
44- MIPS64/Linux
45- X86/Solaris
46- AMD64/Solaris
47
48Note that AMD64 is just another name for x86_64, and Valgrind runs fine
49on Intel processors.  Also note that the core of macOS is called
50"Darwin" and this name is used sometimes.
51
52Valgrind is licensed under the GNU General Public License, version 2. 
53Read the file COPYING in the source distribution for details.
54
55However: if you contribute code, you need to make it available as GPL
56version 2 or later, and not 2-only.
57
58
59Documentation
60~~~~~~~~~~~~~
61A comprehensive user guide is supplied.  Point your browser at
62$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
63specified with --prefix= when building.
64
65
66Building and installing it
67~~~~~~~~~~~~~~~~~~~~~~~~~~
68To install from the GIT repository:
69
70  0. Clone the code from GIT, following the instructions at
71     http://www.valgrind.org/downloads/repository.html.
72
73  1. cd into the source directory.
74
75  2. Run ./autogen.sh to setup the environment (you need the standard
76     autoconf tools to do so).
77
78  3. Continue with the following instructions...
79
80To install from a tar.bz2 distribution:
81
82  4. Run ./configure, with some options if you wish.  The only interesting
83     one is the usual --prefix=/where/you/want/it/installed.
84
85  5. Run "make".
86
87  6. Run "make install", possibly as root if the destination permissions
88     require that.
89
90  7. See if it works.  Try "valgrind ls -l".  Either this works, or it
91     bombs out with some complaint.  In that case, please let us know
92     (see www.valgrind.org).
93
94Important!  Do not move the valgrind installation into a place
95different from that specified by --prefix at build time.  This will
96cause things to break in subtle ways, mostly when Valgrind handles
97fork/exec calls.
98
99
100The Valgrind Developers
101

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-gnu is necessary if you compile it with cross toolchain
30   compiler for little endian platform.
31
32 * --build=mips-linux is needed if you want to build it for MIPS32 on 64-bit
33   MIPS system.
34
35 * If you are compiling Valgrind for mips32 with gcc version older then
36   gcc (GCC) 4.5.1, you must specify CFLAGS="-mips32r2 -mplt", e.g.
37
38   ./configure --prefix=<path_to_install_directory>
39   CFLAGS="-mips32r2 -mplt"
40
41
42Limitations
43-----------
44- Some gdb tests will fail when gdb (GDB) older than 7.5 is used and gdb is
45  not compiled with '--with-expat=yes'.
46- You can not compile tests for DSP ASE if you are using gcc (GCC) older
47  then 4.6.1 due to a bug in the toolchain.
48- Older GCC may have issues with some inline assembly blocks. Get a toolchain
49  based on newer GCC versions, if possible.
50

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.
15- Instructions operating on vector registers are not supported.
16- memcheck, cachegrind, drd, helgrind, massif, lackey, and none are
17  supported. 
18- On machine models predating z10, cachegrind will assume a z10 cache
19  architecture. Otherwise, cachegrind will query the hosts cache system
20  and use those parameters.
21- callgrind and all experimental tools are currently not supported.
22- Some gcc versions use mvc to copy 4/8 byte values. This will affect
23  certain debug messages. For example, memcheck will complain about
24  4 one-byte reads/writes instead of just a single read/write.
25- The transactional-execution facility is not supported; it is masked
26  off from HWCAP.
27<<<<<<< HEAD
28- The vector facility is not supported; it is masked off from HWCAP.
29=======
30>>>>>>> de7fc1a0593ca94835bba5f9732997b355055c4b
31
32
33Hardware facilities
34-------------------
35Valgrind does not require that the host machine has the same hardware
36facilities as the machine for which the client program was compiled.
37This is convenient. If possible, the JIT compiler will translate the
38client instructions according to the facilities available on the host.
39This means, though, that probing for hardware facilities by issuing
40instructions from that facility and observing whether SIGILL is thrown
41may not work. As a consequence, programs that attempt to do so may
42behave differently. It is believed that this is a rare use case.
43
44
45Recommendations
46---------------
47Applications should be compiled with -fno-builtin to avoid
48false positives due to builtin string operations when running memcheck.
49
50
51Reading Material
52----------------
53(1) Linux for zSeries ELF ABI Supplement
54    http://refspecs.linuxfoundation.org/ELF/zSeries/index.html
55(2) z/Architecture Principles of Operation
56    http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr010.pdf
57(3) z/Architecture Reference Summary
58    http://publibfi.boulder.ibm.com/epubs/pdf/dz9zs008.pdf
59

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

README_DEVELOPERS

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

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
1162.  Do 'man 2 mysyscallname' to get some idea of what the syscall
117    does.  Note that the actual kernel interface can differ from this,
118    so you might also want to check a version of the Linux kernel
119    source.
120
121    NOTE: any syscall which has something to do with signals or
122    threads is probably "special", and needs more careful handling.
123    Post something to valgrind-developers if you aren't sure.
124
125
1263.  Add a case to the already-huge collection of wrappers in 
127    the coregrind/m_syswrap/syswrap-*.c files. 
128    For each in-memory parameter which is read or written by
129    the syscall, do one of
130    
131      PRE_MEM_READ( ... )
132      PRE_MEM_RASCIIZ( ... ) 
133      PRE_MEM_WRITE( ... ) 
134      
135    for  that parameter.  Then do the syscall.  Then, if the syscall
136    succeeds, issue suitable POST_MEM_WRITE( ... ) calls.
137    (There's no need for POST_MEM_READ calls.)
138
139    Also, add it to the syscall_table[] array; use one of GENX_, GENXY
140    LINX_, LINXY, PLAX_, PLAXY.
141    GEN* for generic syscalls (in syswrap-generic.c), LIN* for linux
142    specific ones (in syswrap-linux.c) and PLA* for the platform
143    dependent ones (in syswrap-$(PLATFORM)-linux.c).
144    The *XY variant if it requires a PRE() and POST() function, and
145    the *X_ variant if it only requires a PRE()
146    function.  
147    
148    If you find this difficult, read the wrappers for other syscalls
149    for ideas.  A good tip is to look for the wrapper for a syscall
150    which has a similar behaviour to yours, and use it as a 
151    starting point.
152
153    If you need structure definitions and/or constants for your syscall,
154    copy them from the kernel headers into include/vki.h and co., with
155    the appropriate vki_*/VKI_* name mangling.  Don't #include any
156    kernel headers.  And certainly don't #include any glibc headers.
157
158    Test it.
159
160    Note that a common error is to call POST_MEM_WRITE( ... )
161    with 0 (NULL) as the first (address) argument.  This usually means
162    your logic is slightly inadequate.  It's a sufficiently common bug
163    that there's a built-in check for it, and you'll get a "probably
164    sanity check failure" for the syscall wrapper you just made, if this
165    is the case.
166
167
1684.  Once happy, send us the patch.  Pretty please.
169
170
171
172
173Writing your own ioctl wrappers
174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176Is pretty much the same as writing syscall wrappers, except that all
177the action happens within PRE(ioctl) and POST(ioctl).
178
179There's a default case, sometimes it isn't correct and you have to write a
180more specific case to get the right behaviour.
181
182As above, please create a bug report and attach the patch as described
183on http://www.valgrind.org.
184
185
186Writing your own door call wrappers (Solaris only)
187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189Unlike syscalls or ioctls, door calls transfer data between two userspace
190programs, albeit through a kernel interface. Programs may use completely
191proprietary semantics in the data buffers passed between them.
192Therefore it may not be possible to capture these semantics within
193a Valgrind door call or door return wrapper.
194
195Nevertheless, for system or well-known door services it would be beneficial
196to have a door call and a door return wrapper. Writing such wrapper is pretty
197much the same as writing ioctl wrappers. Please take a few moments to study
198the following picture depicting how a door client and a door server interact
199through the kernel interface in a typical scenario:
200
201
202door client thread          kernel       door server thread
203invokes door_call()                     invokes door_return()
204-------------------------------------------------------------------
205                               <----  PRE(sys_door, DOOR_RETURN)
206PRE(sys_door, DOOR_CALL)  --->
207                               ---->  POST(sys_door, DOOR_RETURN)
208                                           ----> server_procedure()
209                                           <----
210                               <----  PRE(sys_door, DOOR_RETURN)
211POST(sys_door, DOOR_CALL) <---
212
213The first PRE(sys_door, DOOR_RETURN) is invoked with data_ptr=NULL
214and data_size=0. That's because it has not received any data from
215a door call, yet.
216
217Semantics are described by the following functions
218in coregring/m_syswrap/syswrap-solaris.c module:
219o For a door call wrapper the following attributes of 'params' argument:
220  - data_ptr (and associated data_size) as input buffer (request);
221      described in door_call_pre_mem_params_data()
222  - rbuf (and associated rsize) as output buffer (response);
223      described in door_call_post_mem_params_rbuf()
224o For a door return wrapper the following parameters:
225  - data_ptr (and associated data_size) as input buffer (request);
226      described in door_return_post_mem_data()
227  - data_ptr (and associated data_size) as output buffer (response);
228      described in door_return_pre_mem_data()
229
230There's a default case which may not be correct and you have to write a
231more specific case to get the right behaviour. Unless Valgrind's option
232'--sim-hints=lax-doors' is specified, the default case also spits a warning.
233
234As above, please create a bug report and attach the patch as described
235on http://www.valgrind.org.
236

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