1*b0d17251SchristosNotes on Valgrind 2*b0d17251Schristos================= 3*b0d17251Schristos 4*b0d17251SchristosValgrind is a test harness that includes many tools such as memcheck, 5*b0d17251Schristoswhich is commonly used to check for memory leaks, etc. The default tool 6*b0d17251Schristosrun by Valgrind is memcheck. There are other tools available, but this 7*b0d17251Schristoswill focus on memcheck. 8*b0d17251Schristos 9*b0d17251SchristosValgrind runs programs in a virtual machine, this means OpenSSL unit 10*b0d17251Schristostests run under Valgrind will take longer than normal. 11*b0d17251Schristos 12*b0d17251SchristosRequirements 13*b0d17251Schristos------------ 14*b0d17251Schristos 15*b0d17251Schristos1. Platform supported by Valgrind 16*b0d17251Schristos See <http://valgrind.org/info/platforms.html> 17*b0d17251Schristos2. Valgrind installed on the platform 18*b0d17251Schristos See <http://valgrind.org/downloads/current.html> 19*b0d17251Schristos3. OpenSSL compiled 20*b0d17251Schristos See [INSTALL.md](INSTALL.md) 21*b0d17251Schristos 22*b0d17251SchristosRunning Tests 23*b0d17251Schristos------------- 24*b0d17251Schristos 25*b0d17251SchristosTest behavior can be modified by adjusting environment variables. 26*b0d17251Schristos 27*b0d17251Schristos`EXE_SHELL` 28*b0d17251Schristos 29*b0d17251SchristosThis variable is used to specify the shell used to execute OpenSSL test 30*b0d17251Schristosprograms. The default wrapper (`util/wrap.pl`) initializes the environment 31*b0d17251Schristosto allow programs to find shared libraries. The variable can be modified 32*b0d17251Schristosto specify a different executable environment. 33*b0d17251Schristos 34*b0d17251Schristos EXE_SHELL=\ 35*b0d17251Schristos "`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" 36*b0d17251Schristos 37*b0d17251SchristosThis will start up Valgrind with the default checker (`memcheck`). 38*b0d17251SchristosThe `--error-exitcode=1` option specifies that Valgrind should exit with an 39*b0d17251Schristoserror code of 1 when memory leaks occur. 40*b0d17251SchristosThe `--leak-check=full` option specifies extensive memory checking. 41*b0d17251SchristosThe `-q` option prints only error messages. 42*b0d17251SchristosAdditional Valgrind options may be added to the `EXE_SHELL` variable. 43*b0d17251Schristos 44*b0d17251Schristos`OPENSSL_ia32cap` 45*b0d17251Schristos 46*b0d17251SchristosThis variable controls the processor-specific code on Intel processors. 47*b0d17251SchristosBy default, OpenSSL will attempt to figure out the capabilities of a 48*b0d17251Schristosprocessor, and use it to its fullest capability. This variable can be 49*b0d17251Schristosused to control what capabilities OpenSSL uses. 50*b0d17251Schristos 51*b0d17251SchristosAs of valgrind-3.15.0 on Linux/x86_64, instructions up to AVX2 are 52*b0d17251Schristossupported. Setting the following disables instructions beyond AVX2: 53*b0d17251Schristos 54*b0d17251Schristos`OPENSSL_ia32cap=":0"` 55*b0d17251Schristos 56*b0d17251SchristosThis variable may need to be set to something different based on the 57*b0d17251Schristosprocessor and Valgrind version you are running tests on. More information 58*b0d17251Schristosmay be found in [doc/man3/OPENSSL_ia32cap.pod](doc/man3/OPENSSL_ia32cap.pod). 59*b0d17251Schristos 60*b0d17251SchristosAdditional variables (such as `VERBOSE` and `TESTS`) are described in the 61*b0d17251Schristosfile [test/README.md](test/README.md). 62*b0d17251Schristos 63*b0d17251SchristosExample command line: 64*b0d17251Schristos 65*b0d17251Schristos $ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 \ 66*b0d17251Schristos --leak-check=full -q" OPENSSL_ia32cap=":0" 67*b0d17251Schristos 68*b0d17251SchristosIf an error occurs, you can then run the specific test via the `TESTS` variable 69*b0d17251Schristoswith the `VERBOSE` or `VF` or `VFP` options to gather additional information. 70*b0d17251Schristos 71*b0d17251Schristos $ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl \ 72*b0d17251Schristos valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0" 73