README
1
2 Release notes for Valgrind
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~
4 If you are building a binary package of Valgrind for distribution,
5 please read README_PACKAGERS. It contains some important information.
6
7 If you are developing Valgrind, please read README_DEVELOPERS. It contains
8 some useful information.
9
10 For instructions on how to build/install, see the end of this file.
11
12 If you have problems, consult the FAQ to see if there are workarounds.
13
14
15 Executive Summary
16 ~~~~~~~~~~~~~~~~~
17 Valgrind is a framework for building dynamic analysis tools. There are
18 Valgrind tools that can automatically detect many memory management
19 and threading bugs, and profile your programs in detail. You can also
20 use Valgrind to build new tools.
21
22 The Valgrind distribution currently includes six production-quality
23 tools: a memory error detector, two thread error detectors, a cache
24 and branch-prediction profiler, a call-graph generating cache abd
25 branch-prediction profiler, and a heap profiler. It also includes
26 three experimental tools: a heap/stack/global array overrun detector,
27 a different kind of heap profiler, and a SimPoint basic block vector
28 generator.
29
30 Valgrind is closely tied to details of the CPU, operating system and to
31 a lesser extent, compiler and basic C libraries. This makes it difficult
32 to make it portable. Nonetheless, it is available for the following
33 platforms:
34
35 - X86/Linux
36 - AMD64/Linux
37 - PPC32/Linux
38 - PPC64/Linux
39 - ARM/Linux
40 - x86/MacOSX
41 - AMD64/MacOSX
42 - S390X/Linux
43 - MIPS32/Linux
44 - MIPS64/Linux
45
46 Note that AMD64 is just another name for x86_64, and Valgrind runs fine
47 on Intel processors. Also note that the core of MacOSX is called
48 "Darwin" and this name is used sometimes.
49
50 Valgrind is licensed under the GNU General Public License, version 2.
51 Read the file COPYING in the source distribution for details.
52
53 However: if you contribute code, you need to make it available as GPL
54 version 2 or later, and not 2-only.
55
56
57 Documentation
58 ~~~~~~~~~~~~~
59 A comprehensive user guide is supplied. Point your browser at
60 $PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
61 specified with --prefix= when building.
62
63
64 Building and installing it
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~
66 To install from the Subversion repository :
67
68 0. Check out the code from SVN, following the instructions at
69 http://www.valgrind.org/downloads/repository.html.
70
71 1. cd into the source directory.
72
73 2. Run ./autogen.sh to setup the environment (you need the standard
74 autoconf tools to do so).
75
76 3. Continue with the following instructions...
77
78 To install from a tar.bz2 distribution:
79
80 4. Run ./configure, with some options if you wish. The only interesting
81 one is the usual --prefix=/where/you/want/it/installed.
82
83 5. Run "make".
84
85 6. Run "make install", possibly as root if the destination permissions
86 require that.
87
88 7. See if it works. Try "valgrind ls -l". Either this works, or it
89 bombs out with some complaint. In that case, please let us know
90 (see www.valgrind.org).
91
92 Important! Do not move the valgrind installation into a place
93 different from that specified by --prefix at build time. This will
94 cause things to break in subtle ways, mostly when Valgrind handles
95 fork/exec calls.
96
97
98 The Valgrind Developers
99
README.aarch64
1
2 Status
3 ~~~~~~
4
5 As of Jan 2014 the trunk contains a port to AArch64 ARMv8 -- loosely,
6 the 64-bit ARM architecture. Currently it supports integer and FP
7 instructions and can run anything generated by gcc-4.8.2 -O3. The
8 port is under active development.
9
10 Current 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
25 There has been extensive testing of the baseline simulation of integer
26 and FP instructions. Memcheck is also believed to work, at least for
27 small examples. Other tools appear to at least not crash when running
28 /bin/date.
29
30 Enough syscalls and instructions are supported for substantial
31 programs to work. Firefox 26 is able to start up and quit. The noise
32 level from Memcheck is low enough to make it practical to use for real
33 debugging.
34
35
36 Building
37 ~~~~~~~~
38
39 You could probably build it directly on a target OS, using the normal
40 non-cross scheme
41
42 ./autogen.sh ; ./configure --prefix=.. ; make ; make install
43
44 Development 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
56 Doing this assumes that the install path (`pwd`/Inst) is valid on
57 both host and target, which isn't normally the case. To avoid
58 this 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
67 See README.android for more examples of cross-compile building.
68
69
70 Implementation tidying-up/TODO notes
71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
73 UnwindStartRegs -- what should that contain?
74
75
76 vki-arm64-linux.h: vki_sigaction_base
77 I really don't think that __vki_sigrestore_t sa_restorer
78 should be present. Adding it surely puts sa_mask at a wrong
79 offset compared to (kernel) reality. But not having it causes
80 compilation of m_signals.c to fail in hard to understand ways,
81 so adding it temporarily.
82
83
84 m_trampoline.S: what's the unexecutable-insn value? 0xFFFFFFFF
85 is there at the moment, but 0x00000000 is probably what it should be.
86 Also, fix indentation/tab-vs-space stuff
87
88
89 ./include/vki/vki-arm64-linux.h: uses __uint128_t. Should change
90 it to __vki_uint128_t, but what's the defn of that?
91
92
93 m_debuginfo/priv_storage.h: need proper defn of DiCfSI
94
95
96 readdwarf.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
103 vki-arm64-linux.h:
104 re linux-3.10.5/include/uapi/asm-generic/sembuf.h
105 I'd say the amd64 version has padding it shouldn't have. Check?
106
107
108 syswrap-linux.c run_a_thread_NORETURN assembly sections
109 seems like tst->os_state.exitcode has word type
110 in which case the ppc64_linux use of lwz to read it, is wrong
111
112
113 syswrap-linux.c ML_(do_fork_clone)
114 assuming that VGP_arm64_linux is the same as VGP_arm_linux here
115
116
117 dispatch-arm64-linux.S: FIXME: set up FP control state before
118 entering generated code. Also fix screwy indentation.
119
120
121 dispatcher-ery general: what's a good (predictor-friendly) way to
122 branch to a register?
123
124
125 in vki-arm64-scnums.h
126 //#if __BITS_PER_LONG == 64 && !defined(__SYSCALL_COMPAT)
127 Probably want to reenable that and clean up accordingly
128
129
130 putIRegXXorZR: figure out a way that the computed value is actually
131 used, so as to keep any memory reads that might generate it, alive.
132 (else the simulation can lose exceptions). At least, for writes to
133 the zero register generated by loads .. or .. can anything other
134 integer instructions, that write to a register, cause exceptions?
135
136
137 loads/stores: generate stack alignment checks as necessary
138
139
140 fix barrier insns: ISB, DMB
141
142
143 fix atomic loads/stores
144
145
146 FMADD/FMSUB/FNMADD/FNMSUB: generate and use the relevant fused
147 IROps so as to avoid double rounding
148
149
150 ARM64Instr_Call getRegUsage: re-check relative to what
151 getAllocableRegs_ARM64 makes available
152
153
154 Make dispatch-arm64-linux.S save any callee-saved Q regs
155 I think what is required is to save D8-D15 and nothing more than that.
156
157
158 wrapper for __NR3264_fstat -- correct?
159
160
161 PRE(sys_clone): get rid of references to vki_modify_ldt_t and the
162 definition of it in vki-arm64-linux.h. Ditto for 32 bit arm.
163
164
165 sigframe-arm64-linux.c: build_sigframe: references to nonexistent
166 siguc->uc_mcontext.trap_no, siguc->uc_mcontext.error_code have been
167 replaced by zero. Also in synth_ucontext.
168
169
170 m_debugger.c:
171 uregs.pstate = LibVEX_GuestARM64_get_nzcv(vex); /* is this correct? */
172 Is that remotely correct?
173
174
175 host_arm64_defs.c: emit_ARM64INstr:
176 ARM64in_VDfromX and ARM64in_VQfromXX: use simple top-half zeroing
177 MOVs to vector registers instead of INS Vd.D[0], Xreg, to avoid false
178 dependencies on the top half of the register. (Or at least check
179 the semantics of INS Vd.D[0] to see if it zeroes out the top.)
180
181
182 preferredVectorSubTypeFromSize: review perf effects and decide
183 on a types-for-subparts policy
184
185
186 fold_IRExpr_Unop: add a reduction rule for this
187 1Sto64(CmpNEZ64( Or64(GET:I64(1192),GET:I64(1184)) ))
188 vis 1Sto64(CmpNEZ64(x)) --> CmpwNEZ64(x)
189
190
191 check insn selection for memcheck-only primops:
192 Left64 CmpwNEZ64 V128to64 V128HIto64 1Sto64 CmpNEZ64 CmpNEZ32
193 widen_z_8_to_64 1Sto32 Left32 32HLto64 CmpwNEZ32 CmpNEZ8
194
195
196 isel: get rid of various cases where zero is put into a register
197 and just use xzr instead. Especially for CmpNEZ64/32. And for
198 writing 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 */
203 uh .. they are not in sync
204
205
206 very stupid:
207 imm64 x23, 0xFFFFFFFFFFFFFFA0
208 17 F4 9F D2 F7 FF BF F2 F7 FF DF F2 F7 FF FF F2
209
210
211 valgrind.h: fix VALGRIND_ALIGN_STACK/VALGRIND_RESTORE_STACK,
212 also add CFI annotations
213
214
215 could possibly bring r29 into use, which be useful as it is
216 callee saved
217
218
219 ubfm/sbfm etc: special case cases that are simple shifts, as iropt
220 can't always simplify the general-case IR to a shift in such cases.
221
222
223 LDP,STP (immediate, simm7) (FP&VEC)
224 should zero out hi parts of dst registers in the LDP case
225
226
227 DUP insns: use Iop_Dup8x16, Iop_Dup16x8, Iop_Dup32x4
228 rather than doing it "by hand"
229
230
231 Any place where ZeroHI64ofV128 is used in conjunction with
232 FP vector IROps: find a way to make sure that arithmetic on
233 the upper half of the values is "harmless."
234
235
236 math_MINMAXV: use real Iop_Cat{Odd,Even}Lanes ops rather than
237 inline scalar code
238
239
240 chainXDirect_ARM64: use direct jump forms when possible
241
README.android
1
2 How to cross-compile and run on Android. Please read to the end,
3 since there are important details further down regarding crash
4 avoidance and GPU support.
5
6 These notes were last updated on 4 Nov 2014, for Valgrind SVN
7 revision 14689/2987.
8
9 These instructions are known to work, or have worked at some time in
10 the past, for:
11
12 arm:
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
19 x86:
20 Android 4.0.3 running on android x86 emulator.
21
22 mips32:
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
28 arm64:
29 Android 4.5 (?) running on ARM Juno
30
31 On android-arm, GDBserver might insert breaks at wrong addresses.
32 Feedback on this welcome.
33
34 Other configurations and toolchains might work, but haven't been tested.
35 Feedback is welcome.
36
37 Toolchain:
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
51 Install 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 #
58 export NDKROOT=/path/to/android-ndk-r<version>
59
60
61 # Then cd to the root of your Valgrind source tree.
62 #
63 cd /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
73 export AR=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-ar
74 export LD=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-ld
75 export CC=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/bin/arm-linux-androideabi-gcc
76
77 # For x86
78 export AR=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-ar
79 export LD=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-ld
80 export CC=$NDKROOT/toolchains/x86-4.4.3/prebuilt/linux-x86/bin/i686-android-linux-gcc
81
82 # For MIPS32
83 export AR=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-ar
84 export LD=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-ld
85 export CC=$NDKROOT/toolchains/mipsel-linux-android-4.8/prebuilt/linux-x86_64/bin/mipsel-linux-android-gcc
86
87 # For ARM64 (AArch64)
88 export AR=$NDKROOT/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-ar
89 export LD=$NDKROOT/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-ld
90 export 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
104 CPPFLAGS="--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
113 CPPFLAGS="--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
120 CPPFLAGS="--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)
127 CPPFLAGS="--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 #
160 make -j4
161 make -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 #
168 adb 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-emulator-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 #
195 mq -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
README.mips
1
2 Supported 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
9 Building V for MIPS
10 -------------------
11 - Native build is available for all supported platforms. The build system
12 expects that native GCC is configured correctly and optimized for the platform.
13 Yet, this may not be the case with some Debian distributions which configure
14 GCC to compile to "mips1" by default. Depending on a target platform, using
15 CFLAGS="-mips32r2", CFLAGS="-mips32" or CFLAGS="-mips64" or
16 CFLAGS="-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 [--with-pagesize=<4|16|64>]
23
24 * --host=mips-linux-gnu is necessary only if Valgrind is built on platform
25 other then MIPS, tools for building MIPS application have to be in PATH.
26
27 * --with-pagesize option is used to set default PAGE SIZE. If option is not
28 used, PAGE SIZE is set to value default for platform on which Valgrind is
29 built on. Possible values are 4, 16 of 64 and represent size in kilobytes.
30
31 * --host=mips-linux-gnu is necessary if you compile it with cross toolchain
32 compiler for big endian platform.
33
34 * --host=mipsel-linux-gnu is necessary if you compile it with cross toolchain
35 compiler for little endian platform.
36
37 * --build=mips-linux is needed if you want to build it for MIPS32 on 64-bit
38 MIPS system.
39
40 * If you are compiling Valgrind for mips32 with gcc version older then
41 gcc (GCC) 4.5.1, you must specify CFLAGS="-mips32r2 -mplt", e.g.
42
43 ./configure --prefix=<path_to_install_directory>
44 CFLAGS="-mips32r2 -mplt"
45
46
47 Limitations
48 -----------
49 - Some gdb tests will fail when gdb (GDB) older than 7.5 is used and gdb is
50 not compiled with '--with-expat=yes'.
51 - You can not compile tests for DSP ASE if you are using gcc (GCC) older
52 then 4.6.1 due to a bug in the toolchain.
53 - Older GCC may have issues with some inline assembly blocks. Get a toolchain
54 based on newer GCC versions, if possible.
55
README.s390
1
2 Requirements
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
10 Limitations
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 - The vector facility is not supported; it is masked off from HWCAP.
28
29
30 Hardware facilities
31 -------------------
32 Valgrind does not require that the host machine has the same hardware
33 facilities as the machine for which the client program was compiled.
34 This is convenient. If possible, the JIT compiler will translate the
35 client instructions according to the facilities available on the host.
36 This means, though, that probing for hardware facilities by issuing
37 instructions from that facility and observing whether SIGILL is thrown
38 may not work. As a consequence, programs that attempt to do so may
39 behave differently. It is believed that this is a rare use case.
40
41
42 Recommendations
43 ---------------
44 Applications should be compiled with -fno-builtin to avoid
45 false positives due to builtin string operations when running memcheck.
46
47
48 Reading Material
49 ----------------
50 (1) Linux for zSeries ELF ABI Supplement
51 http://refspecs.linuxfoundation.org/ELF/zSeries/index.html
52 (2) z/Architecture Principles of Operation
53 http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr010.pdf
54 (3) z/Architecture Reference Summary
55 http://publibfi.boulder.ibm.com/epubs/pdf/dz9zs008.pdf
56
README.solaris
1 Requirements
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 fullfil 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
21
22 Compilation
23 -----------
24 Please follow the generic instructions in the README file.
25
26 The configure script detects a canonical host to determine which version of
27 Valgrind should be built. If the system compiler by default produces 32-bit
28 binaries then only a 32-bit version of Valgrind will be built. To enable
29 compilation of both 64-bit and 32-bit versions on such a system, issue the
30 configure script as follows:
31 ./configure CC='gcc -m64' CXX='g++ -m64'
32
33
34 Oracle Solaris and illumos support
35 ----------------------------------
36 One of the main goal of this port is to support both Oracle Solaris and
37 illumos kernels. This is a very hard task because Solaris kernel traditionally
38 does not provide a stable syscall interface and because Valgrind contains
39 several parts that are closely tied to the underlying kernel. For these
40 reasons, the port needs to detect which syscall interfaces are present. This
41 detection cannot be done easily at run time and is currently implemented as
42 a set of configure tests. This means that a binary version of this port can be
43 executed only on a kernel that is compatible with a kernel that was used
44 during the configure and compilation time.
45
46 Main currently-known incompatibilities:
47 - Solaris 11 (released in November 2011) removed a large set of syscalls where
48 *at variant of the syscall was also present, for example, open() versus
49 openat(AT_FDCWD) [1]
50 - syscall number for unlinkat() is 76 on Solaris 11, but 65 on illumos [2]
51 - illumos (in April 2013) changed interface of the accept() and pipe()
52 syscalls [3]
53
54 [1] http://docs.oracle.com/cd/E26502_01/html/E28556/gkzlf.html#gkzip
55 [2] https://www.illumos.org/issues/521
56 [3] https://github.com/illumos/illumos-gate/commit/5dbfd19ad5fcc2b779f40f80fa05c1bd28fd0b4e
57
58
59 Limitations
60 -----------
61 - The port is Work-In-Progress, many things may not work or they can be subtly
62 broken.
63 - Coredumps produced by Valgrind do not contain all information available,
64 especially microstate accounting and processor bindings.
65 - Accessing contents of /proc/self/psinfo is not thread-safe. That is because
66 Valgrind emulates this file on behalf of the client programs. Entire
67 open() - read() - close() sequence on this file needs to be performed
68 atomically.
69 - Fork limitations: vfork() is translated to fork(), forkall() is not
70 supported.
71 - Valgrind does not track definedness of some eflags (OF, SF, ZF, AF, CF, PF)
72 individually for each flag. After a syscall is finished, when a carry flag
73 is set and defined, all other mentioned flags will be also defined even
74 though they might be undefined before making the syscall.
75 - System call "execve" with a file descriptor which points to a hardlink
76 is currently not supported. That is because from the opened file descriptor
77 itself it is not possible to reverse map the intended pathname.
78 Examples are fexecve(3C) and isaexec(3C).
79 - Program headers PT_SUNW_SYSSTAT and PT_SUNW_SYSSTAT_ZONE are not supported.
80 That is, programs linked with mapfile directive RESERVE_SEGMENT and attribute
81 TYPE equal to SYSSTAT or SYSSTAT_ZONE will cause Valgrind exit. It is not
82 possible for Valgrind to arrange mapping of a kernel shared page at the
83 address specified in the mapfile for the guest application. There is currently
84 no such mechanism in Solaris. Hacky workarounds are possible, though.
85 - When a thread has no stack then all system calls will result in Valgrind
86 crash, even though such system calls use just parameters passed in registers.
87 This should happen only in pathological situations when a thread is created
88 with custom mmap'ed stack and this stack is then unmap'ed during thread
89 execution.
90
91
92 Remote debugging support
93 ------------------------
94 Solaris port of GDB has a major flaw which prevents remote debugging from
95 working correctly. Fortunately this flaw has an easy fix [4]. Unfortunately
96 it is not present in the current GDB 7.6.2. This boils down to several
97 options:
98 - Use GDB shipped with Solaris 11.2 which has this flaw fixed.
99 - Wait until GDB 7.7 becomes available (there won't be other 7.6.x releases).
100 - Build GDB 7.6.2 with the fix by yourself using the following steps:
101 # pkg install developer/gnu-binutils
102 $ wget http://ftp.gnu.org/gnu/gdb/gdb-7.6.2.tar.gz
103 $ gzip -dc gdb-7.6.2.tar.gz | tar xf -
104 $ cd gdb-7.6.2
105 $ patch -p1 -i /path/to/valgrind-solaris/solaris/gdb-sol-thread.patch
106 $ export LIBS="-lncurses"
107 $ export CC="gcc -m64"
108 $ ./configure --with-x=no --with-curses --with-libexpat-prefix=/usr/lib
109 $ gmake && gmake install
110
111 [4] https://sourceware.org/ml/gdb-patches/2013-12/msg00573.html
112
113
114 TODO list
115 ---------
116 - Fix few remaining failing tests.
117 - Add more Solaris-specific tests (especially for the door and spawn
118 syscalls).
119 - Provide better error reporting for various subsyscalls.
120 - Implement storing of extra register state in signal frame.
121 - Performance comparison against other platforms.
122
123 - Prevent SIGPIPE when writing to a socket (coregrind/m_libcfile.c).
124 - Implement ticket locking for fair scheduling (--fair-sched=yes).
125 - Implement support in DRD and Helgrind tools for thr_join() with thread == 0.
126 - Add support for accessing thread-local variables via gdb (auxprogs/getoff.c).
127 Requires research on internal libc TLS representation.
128 - VEX supports AVX, BMI and AVX2. Investigate if they can be enabled on
129 Solaris/illumos.
130 - Investigate support for more flags in AT_SUN_AUXFLAGS.
131 - Fix Valgrind crash when a thread has no stack and syswrap-main.c accesses
132 all possible syscall parameters. Enable helgrind/tests/stackteardown.c
133 to see this in effect. Would require awareness of syscall parameter semantics.
134 - Correctly print arguments of DW_CFA_ORCL_arg_loc in show_CF_instruction() when
135 it is implemented in libdwarf.
136
137
138 Contacts
139 --------
140 Please send bug reports and any questions about the port to:
141 Ivo Raisr <ivosh (a] ivosh.net>
142 Petr Pavlu <setup (a] dagobah.cz>
143
README_DEVELOPERS
1
2 Building and not installing it
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4 To run Valgrind without having to install it, run coregrind/valgrind
5 with the VALGRIND_LIB environment variable set, where <dir> is the root
6 of the source tree (and must be an absolute path). Eg:
7
8 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
9
10 This allows you to compile and run with "make" instead of "make install",
11 saving you time.
12
13 Or, you can use the 'vg-in-place' script which does that for you.
14
15 I recommend compiling with "make --quiet" to further reduce the amount of
16 output spewed out during compilation, letting you actually see any errors,
17 warnings, etc.
18
19
20 Building a distribution tarball
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 To build a distribution tarball from the valgrind sources:
23
24 make dist
25
26 In addition to compiling, linking and packaging everything up, the command
27 will also attempt to build the documentation.
28
29 If you only want to test whether the generated tarball is complete and runs
30 regression tests successfully, building documentation is not needed.
31
32 make dist BUILD_ALL_DOCS=no
33
34 If you insist on building documentation some embarrassing instructions
35 can be found in docs/README.
36
37
38 Running the regression tests
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 To build and run all the regression tests, run "make [--quiet] regtest".
41
42 To run a subset of the regression tests, execute:
43
44 perl tests/vg_regtest <name>
45
46 where <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
48 file. 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
55 Running the performance tests
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57 To build and run all the performance tests, run "make [--quiet] perf".
58
59 To run a subset of the performance suite, execute:
60
61 perl perf/vg_perf <name>
62
63 where <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
65 file. Eg:
66
67 perl perf/vg_perf perf/
68 perl perf/vg_perf perf/bz2.vgperf
69 perl perf/vg_perf perf/bz2
70
71 To compare multiple versions of Valgrind, use the --vg= option multiple
72 times. For example, if you have two Valgrinds next to each other, one in
73 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
74 compare them on all the performance tests:
75
76 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
77
78
79 Debugging Valgrind with GDB
80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
81 To debug the valgrind launcher program (<prefix>/bin/valgrind) just
82 run it under gdb in the normal way.
83
84 Debugging the main body of the valgrind code (and/or the code for
85 a particular tool) requires a bit more trickery but can be achieved
86 without 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
120 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
121 be fully expanded (ie. not an environment variable).
122
123 A 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
139 Self-hosting
140 ~~~~~~~~~~~~
141 This 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/install as usual.
155
156 (3) Configure Outer normally and build/install as usual.
157
158 (4) Choose a very simple program (date) and try
159
160 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \
161 --smc-check=all-non-file \
162 --run-libc-freeres=no --tool=cachegrind -v \
163 inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog
164
165 Note: You must use a "make install"-ed valgrind.
166 Do *not* use vg-in-place for the outer valgrind.
167
168 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
169 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
170 it will try to find and run __libc_freeres in the inner, while libc is not
171 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
172 gdbserver colliding with outer gdbserver.
173 Currently, inner does *not* use the client request
174 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
175 translation chaining. So the outer needs --smc-check=all-non-file to
176 detect the modified code.
177
178 Debugging the whole thing might imply to use up to 3 GDB:
179 * a GDB attached to the Outer valgrind, allowing
180 to examine the state of Outer.
181 * a GDB using Outer gdbserver, allowing to
182 examine the state of Inner.
183 * a GDB using Inner gdbserver, allowing to
184 examine the state of prog.
185
186 The whole thing is fragile, confusing and slow, but it does work well enough
187 for you to get some useful performance data. Inner has most of
188 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
189 which helps a lot. However, when running regression tests in an Outer/Inner
190 setup, this prefix causes the reg test diff to fail. Give
191 --sim-hints=no-inner-prefix to the Inner to disable the production
192 of the prefix in the stdout/stderr output of Inner.
193
194 The allocator (coregrind/m_mallocfree.c) is annotated with client requests
195 so Memcheck can be used to find leaks and use after free in an Inner
196 Valgrind.
197
198 The Valgrind "big lock" is annotated with helgrind client requests
199 so helgrind and drd can be used to find race conditions in an Inner
200 Valgrind.
201
202 All this has not been tested much, so don't be surprised if you hit problems.
203
204 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
205 (on the outer). Otherwise, Callgrind has much higher memory requirements.
206
207 (B) Regression tests in an outer/inner setup:
208
209 To run all the regression tests with an outer memcheck, do :
210 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
211 --all
212
213 To run a specific regression tests with an outer memcheck, do:
214 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
215 none/tests/args.vgtest
216
217 To run regression tests with another outer tool:
218 perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
219 --outer-tool=helgrind --all
220
221 --outer-args allows to give specific arguments to the outer tool,
222 replacing the default one provided by vg_regtest.
223
224 Note: --outer-valgrind must be a "make install"-ed valgrind.
225 Do *not* use vg-in-place.
226
227 When an outer valgrind runs an inner valgrind, a regression test
228 produces one additional file <testname>.outer.log which contains the
229 errors detected by the outer valgrind. E.g. for an outer memcheck, it
230 contains the leaks found in the inner, for an outer helgrind or drd,
231 it contains the detected race conditions.
232
233 The file tests/outer_inner.supp contains suppressions for
234 the irrelevant or benign errors found in the inner.
235
236 (C) Performance tests in an outer/inner setup:
237
238 To run all the performance tests with an outer cachegrind, do :
239 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
240
241 To run a specific perf test (e.g. bz2) in this setup, do :
242 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
243
244 To run all the performance tests with an outer callgrind, do :
245 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
246 --outer-tool=callgrind perf
247
248 Note: --outer-valgrind must be a "make install"-ed valgrind.
249 Do *not* use vg-in-place.
250
251 To compare the performance of multiple Valgrind versions, do :
252 perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
253 --outer-tool=callgrind \
254 --vg=../inner_xxxx --vg=../inner_yyyy perf
255 (where inner_xxxx and inner_yyyy are the toplevel directories of
256 the versions to compare).
257 Cachegrind and cg_diff are particularly handy to obtain a delta
258 between the two versions.
259
260 When the outer tool is callgrind or cachegrind, the following
261 output files will be created for each test:
262 <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
263 <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
264 (where tt is the two letters abbreviation for the inner tool(s) run).
265
266 For example, the command
267 perl perf/vg_perf \
268 --outer-valgrind=../outer_trunk/install/bin/valgrind \
269 --outer-tool=callgrind \
270 --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
271
272 produces the files
273 callgrind.out.inner_tchain.no.many-loss-records.18465
274 callgrind.outer.log.inner_tchain.no.many-loss-records.18465
275 callgrind.out.inner_tchain.me.many-loss-records.21899
276 callgrind.outer.log.inner_tchain.me.many-loss-records.21899
277 callgrind.out.inner_trunk.no.many-loss-records.21224
278 callgrind.outer.log.inner_trunk.no.many-loss-records.21224
279 callgrind.out.inner_trunk.me.many-loss-records.22916
280 callgrind.outer.log.inner_trunk.me.many-loss-records.22916
281
282
283 Printing out problematic blocks
284 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 If you want to print out a disassembly of a particular block that
286 causes a crash, do the following.
287
288 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
289 --trace-notbelow=999999". This should print one line for each block
290 translated, and that includes the address.
291
292 Then re-run with 999999 changed to the highest bb number shown.
293 This will print the one line per block, and also will print a
294 disassembly of the block in which the fault occurred.
295
README_DEVELOPERS_processes
1 This file documents various "processes" that are used by Valgrind
2 developers for development and release activities.
3 This file contains one section for each process.
4 A summary of each process is given here. Each process is described
5 more 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 SVN
16 See docs/internals/svn-HOWTO.txt
17
18 * Minor/correction release production: TBD
19
20
21 Processes detailed descriptions:
22
23 Update 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 bugs or changes only touch the VEX SVN repository, so it is not
61 possible to commit the NEWS change together with the code changes.
62 In such a case, first commit the VEX change. Then just after, commit
63 the NEWS change. In the bugzilla status, reference (at least) the Valgrind
64 revision number.
65
66 Some changes or bug fixes are very big and might be implemented over
67 a significant period. In such a case, update the NEWS as part of the
68 final commit.
69 If relevant, you might already update the NEWS file as part of
70 earlier commits, using the word 'PARTIAL' to indicate that the change or
71 bug fix is not complete yet.
72
73 Some bugs are reported more than once in bugzilla.
74 Also document in NEWS that such duplicated bugs have been fixed, using a line
75 such as:
76 308333 == 307106
77 to indicate that the bug 308333 is a duplicate of 307106, and was thus
78 fixed in the commit that fixed 307106.
79 Change also the status of the duplicated bug in bugzilla,
80 indicating in the comment the commit revision that fixed the 'master bug'.
81
82
83
84 Minor/correction release:
85 =========================
86 Describe here how to do changes and bug fixed in a minor (correction) release
87 and how/when to merge the branch to the trunk.
88
89 Proposal to be discussed:
90 When a bug is fixed on the branch, the NEWS file is updated on the branch
91 (i.e. a 3.9.1 section is created if needed).
92
93 When often to merge the branch to trunk ?
94 after each fix ?
95 just after the correction release is produced ?
96
97 How is the branch merged to the trunk ?
98
README_MISSING_SYSCALL_OR_IOCTL
1
2 Dealing with missing system call or ioctl wrappers in Valgrind
3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4 You're probably reading this because Valgrind bombed out whilst
5 running your program, and advised you to read this file. The good
6 news is that, in general, it's easy to write the missing syscall or
7 ioctl wrappers you need, so that you can continue your debugging. If
8 you send the resulting patches to me, then you'll be doing a favour to
9 all future Valgrind users too.
10
11 Note that an "ioctl" is just a special kind of system call, really; so
12 there's not a lot of need to distinguish them (at least conceptually)
13 in the discussion that follows.
14
15 All this machinery is in coregrind/m_syswrap.
16
17
18 What are syscall/ioctl wrappers? What do they do?
19 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 Valgrind does what it does, in part, by keeping track of everything your
21 program does. When a system call happens, for example a request to read
22 part of a file, control passes to the Linux kernel, which fulfills the
23 request, and returns control to your program. The problem is that the
24 kernel will often change the status of some part of your program's memory
25 as a result, and tools (instrumentation plug-ins) may need to know about
26 this.
27
28 Syscall and ioctl wrappers have two jobs:
29
30 1. 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
35 2. 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
39 The "happenings" mostly involve reading/writing of memory.
40
41 So, let's look at an example of a wrapper for a system call which
42 should be familiar to many Unix programmers.
43
44
45 The syscall wrapper for time()
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47 The 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
66 The first thing we do happens before the syscall occurs, in the PRE() function.
67 The PRE() function typically starts with invoking to the PRINT() macro. This
68 PRINT() macro implements support for the --trace-syscalls command line option.
69 Next, the tool is told the return type of the syscall, that the syscall has
70 one argument, the type of the syscall argument and that the argument is being
71 read from a register:
72
73 PRE_REG_READ1(long, "time", int *, t);
74
75 Next, if a non-NULL buffer is passed in as the argument, tell the tool that the
76 buffer is about to be written to:
77
78 if (ARG1 != 0) {
79 PRE_MEM_WRITE( "time", ARG1, sizeof(vki_time_t) );
80 }
81
82 Finally, the really important bit, after the syscall occurs, in the POST()
83 function: if, and only if, the system call was successful, tell the tool that
84 the memory was written:
85
86 if (ARG1 != 0) {
87 POST_MEM_WRITE( ARG1, sizeof(vki_time_t) );
88 }
89
90 The POST() function won't be called if the syscall failed, so you
91 don't need to worry about checking that in the POST() function.
92 (Note: this is sometimes a bug; some syscalls do return results when
93 they "fail" - for example, nanosleep returns the amount of unslept
94 time if interrupted. TODO: add another per-syscall flag for this
95 case.)
96
97 Note that we use the type 'vki_time_t'. This is a copy of the kernel
98 type, with 'vki_' prefixed. Our copies of such types are kept in the
99 appropriate vki*.h file(s). We don't include kernel headers or glibc headers
100 directly.
101
102
103 Writing your own syscall wrappers (see below for ioctl wrappers)
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105 If Valgrind tells you that system call NNN is unimplemented, do the
106 following:
107
108 1. 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
116 2. 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
126 3. 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 dependant 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
168 4. Once happy, send us the patch. Pretty please.
169
170
171
172
173 Writing your own ioctl wrappers
174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176 Is pretty much the same as writing syscall wrappers, except that all
177 the action happens within PRE(ioctl) and POST(ioctl).
178
179 There's a default case, sometimes it isn't correct and you have to write a
180 more specific case to get the right behaviour.
181
182 As above, please create a bug report and attach the patch as described
183 on http://www.valgrind.org.
184
185
186 Writing your own door call wrappers (Solaris only)
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189 Unlike syscalls or ioctls, door calls transfer data between two userspace
190 programs, albeit through a kernel interface. Programs may use completely
191 proprietary semantics in the data buffers passed between them.
192 Therefore it may not be possible to capture these semantics within
193 a Valgrind door call or door return wrapper.
194
195 Nevertheless, for system or well-known door services it would be beneficial
196 to have a door call and a door return wrapper. Writing such wrapper is pretty
197 much the same as writing ioctl wrappers. Please take a few moments to study
198 the following picture depicting how a door client and a door server interact
199 through the kernel interface in a typical scenario:
200
201
202 door client thread kernel door server thread
203 invokes door_call() invokes door_return()
204 -------------------------------------------------------------------
205 <---- PRE(sys_door, DOOR_RETURN)
206 PRE(sys_door, DOOR_CALL) --->
207 ----> POST(sys_door, DOOR_RETURN)
208 ----> server_procedure()
209 <----
210 <---- PRE(sys_door, DOOR_RETURN)
211 POST(sys_door, DOOR_CALL) <---
212
213 The first PRE(sys_door, DOOR_RETURN) is invoked with data_ptr=NULL
214 and data_size=0. That's because it has not received any data from
215 a door call, yet.
216
217 Semantics are described by the following functions
218 in coregring/m_syswrap/syswrap-solaris.c module:
219 o 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()
224 o 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
230 There's a default case which may not be correct and you have to write a
231 more 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
234 As above, please create a bug report and attach the patch as described
235 on http://www.valgrind.org.
236
README_PACKAGERS
1
2 Greetings, packaging person! This information is aimed at people
3 building binary distributions of Valgrind.
4
5 Thanks for taking the time and effort to make a binary distribution of
6 Valgrind. The following notes may save you some trouble.
7
8
9 -- Do not ship your Linux distro with a completely stripped
10 /lib/ld.so. At least leave the debugging symbol names on -- line
11 number info isn't necessary. If you don't want to leave symbols on
12 ld.so, alternatively you can have your distro install ld.so's
13 debuginfo package by default, or make ld.so.debuginfo be a
14 requirement of your Valgrind RPM/DEB/whatever.
15
16 Reason for this is that Valgrind's Memcheck tool needs to intercept
17 calls to, and provide replacements for, some symbols in ld.so at
18 startup (most importantly strlen). If it cannot do that, Memcheck
19 shows a large number of false positives due to the highly optimised
20 strlen (etc) routines in ld.so. This has caused some trouble in
21 the past. As of version 3.3.0, on some targets (ppc32-linux,
22 ppc64-linux), Memcheck will simply stop at startup (and print an
23 error message) if such symbols are not present, because it is
24 infeasible to continue.
25
26 It's not like this is going to cost you much space. We only need
27 the symbols for ld.so (a few K at most). Not the debug info and
28 not any debuginfo or extra symbols for any other libraries.
29
30
31 -- (Unfortunate but true) When you configure to build with the
32 --prefix=/foo/bar/xyzzy option, the prefix /foo/bar/xyzzy gets
33 baked into valgrind. The consequence is that you _must_ install
34 valgrind at the location specified in the prefix. If you don't,
35 it may appear to work, but will break doing some obscure things,
36 particularly doing fork() and exec().
37
38 So you can't build a relocatable RPM / whatever from Valgrind.
39
40
41 -- Don't strip the debug info off lib/valgrind/$platform/vgpreload*.so
42 in the installation tree. Either Valgrind won't work at all, or it
43 will still work if you do, but will generate less helpful error
44 messages. Here's an example:
45
46 Mismatched free() / delete / delete []
47 at 0x40043249: free (vg_clientfuncs.c:171)
48 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
49 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
50 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
51 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
52 at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152)
53 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
54 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
55 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
56
57 This tells you that some memory allocated with new[] was freed with
58 free().
59
60 Mismatched free() / delete / delete []
61 at 0x40043249: (inside vgpreload_memcheck.so)
62 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
63 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
64 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
65 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
66 at 0x4004318C: (inside vgpreload_memcheck.so)
67 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
68 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
69 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)
70
71 This isn't so helpful. Although you can tell there is a mismatch,
72 the names of the allocating and deallocating functions are no longer
73 visible. The same kind of thing occurs in various other messages
74 from valgrind.
75
76
77 -- Don't strip symbols from lib/valgrind/* in the installation tree.
78 Doing so will likely cause problems. Removing the line number info is
79 probably OK (at least for some of the files in that directory), although
80 that has not been tested by the Valgrind developers.
81
82
83 -- Please test the final installation works by running it on something
84 huge. I suggest checking that it can start and exit successfully
85 both Firefox and OpenOffice.org. I use these as test programs, and I
86 know they fairly thoroughly exercise Valgrind. The command lines to use
87 are:
88
89 valgrind -v --trace-children=yes firefox
90
91 valgrind -v --trace-children=yes soffice
92
93
94 If you find any more hints/tips for packaging, please report
95 it as a bugreport. See http://www.valgrind.org for details.
96