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