Home | History | Annotate | only in /external/valgrind
Up to higher level directory
NameDateSize
Android.build_all.mk08-Oct-20151.2K
Android.build_host.mk08-Oct-20152.1K
Android.build_one.mk08-Oct-20152.2K
Android.clean.mk08-Oct-2015971
Android.mk08-Oct-201517.7K
Android.test.mk08-Oct-2015159
AUTHORS08-Oct-20153.2K
autogen.sh08-Oct-2015191
auxprogs/08-Oct-2015
bionic.supp08-Oct-20151.3K
cachegrind/08-Oct-2015
callgrind/08-Oct-2015
config.h08-Oct-201510.7K
configure.ac08-Oct-201592.5K
COPYING08-Oct-201517.6K
COPYING.DOCS08-Oct-201519.9K
coregrind/08-Oct-2015
darwin10-drd.supp08-Oct-20152.5K
darwin10.supp08-Oct-20151.7K
darwin11.supp08-Oct-20156.1K
darwin12.supp08-Oct-20158.8K
darwin13.supp08-Oct-20154.9K
darwin14.supp08-Oct-201514.4K
darwin9-drd.supp08-Oct-201510K
darwin9.supp08-Oct-20157K
docs/08-Oct-2015
drd/08-Oct-2015
exp-bbv/08-Oct-2015
exp-dhat/08-Oct-2015
exp-sgcheck/08-Oct-2015
exp-sgcheck.supp08-Oct-2015372
gdbserver_tests/08-Oct-2015
glibc-2.2-LinuxThreads-helgrind.supp08-Oct-20151.2K
glibc-2.2.supp08-Oct-20159.3K
glibc-2.3.supp08-Oct-201511K
glibc-2.34567-NPTL-helgrind.supp08-Oct-20155.8K
glibc-2.4.supp08-Oct-20154.7K
glibc-2.5.supp08-Oct-20153.8K
glibc-2.6.supp08-Oct-20154.7K
glibc-2.7.supp08-Oct-2015695
glibc-2.X-drd.supp08-Oct-20156.6K
glibc-2.X.supp.in08-Oct-20155.2K
helgrind/08-Oct-2015
include/08-Oct-2015
lackey/08-Oct-2015
LOCAL_PATCHES.txt08-Oct-2015648
Makefile.all.am08-Oct-201510.9K
Makefile.am08-Oct-20153.3K
Makefile.tool-tests.am08-Oct-20151.7K
Makefile.tool.am08-Oct-20156.5K
Makefile.vex.am08-Oct-20156.3K
massif/08-Oct-2015
memcheck/08-Oct-2015
MODULE_LICENSE_GPL08-Oct-20150
mpi/08-Oct-2015
NEWS08-Oct-2015133.7K
NEWS.old08-Oct-201584.6K
nightly/08-Oct-2015
none/08-Oct-2015
NOTICE08-Oct-201517.6K
perf/08-Oct-2015
README08-Oct-20153.2K
README.aarch6408-Oct-20156.9K
README.android08-Oct-20157.6K
README.android_emulator08-Oct-20152K
README.mips08-Oct-20152.2K
README.s39008-Oct-20152K
README_DEVELOPERS08-Oct-201511K
README_DEVELOPERS_processes08-Oct-20153.6K
README_MISSING_SYSCALL_OR_IOCTL08-Oct-20156.8K
README_PACKAGERS08-Oct-20154.4K
runtest.sh08-Oct-20152K
runtests-arm.sh08-Oct-2015671
runtests-arm64.sh08-Oct-2015711
shared/08-Oct-2015
tests/08-Oct-2015
upstream.revs.txt08-Oct-201521
valgrind.pc.in08-Oct-2015447
valgrind.spec.in08-Oct-20151.2K
VEX/08-Oct-2015
vg-in-place08-Oct-2015691
xfree-3.supp08-Oct-20152.9K
xfree-4.supp08-Oct-20158.8K

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

      1 
      2 How to install and run an android emulator.
      3 
      4 mkdir android # or any other place you prefer
      5 cd 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
     20 tar xzf jdk-7u4-linux-i586.tar.gz
     21 
     22 # install sdk
     23 tar xzf android-sdk_r18-linux.tgz
     24 
     25 # install ndk
     26 tar xjf android-ndk-r8-linux-x86.tar.bz2
     27 
     28 
     29 # setup PATH to use the installed software:
     30 export SDKROOT=$HOME/android/android-sdk-linux
     31 export PATH=$PATH:$SDKROOT/tools:$SDKROOT/platform-tools
     32 export NDKROOT=$HOME/android/android-ndk-r8
     33 
     34 # install android platforms you want by starting:
     35 android 
     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:
     46 Tools -> 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
     58 adb shell
     59 
     60 # Once the emulator is ready, push your Valgrind to the emulator:
     61 adb push Inst /
     62 
     63 
     64 # IMPORTANT: when running Valgrind, you may need give it the flag
     65 #
     66 #    --kernel-variant=android-emulator-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:
     75 gdbserver :1234 your_exe
     76 
     77 # on the host side:
     78 adb 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
     80 target remote :1234
     81 
     82

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 
     26 
     27 Hardware facilities
     28 -------------------
     29 Valgrind does not require that the host machine has the same hardware
     30 facilities as the machine for which the client program was compiled.
     31 This is convenient. If possible, the JIT compiler will translate the
     32 client instructions according to the facilities available on the host.
     33 This means, though, that probing for hardware facilities by issuing
     34 instructions from that facility and observing whether SIGILL is thrown
     35 may not work. As a consequence, programs that attempt to do so may
     36 behave differently. It is believed that this is a rare use case.
     37 
     38 
     39 Recommendations
     40 ---------------
     41 Applications should be compiled with -fno-builtin to avoid
     42 false positives due to builtin string operations when running memcheck.
     43 
     44 
     45 Reading Material
     46 ----------------
     47 (1) Linux for zSeries ELF ABI Supplement
     48     http://refspecs.linuxfoundation.org/ELF/zSeries/index.html
     49 (2) z/Architecture Principles of Operation
     50     http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr010.pdf
     51 (3) z/Architecture Reference Summary
     52     http://publibfi.boulder.ibm.com/epubs/pdf/dz9zs008.pdf
     53

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

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