xref: /freebsd/crypto/openssl/NOTES-VALGRIND.md (revision 031beb4e239bfce798af17f5fe8dba8bcaf13d99)
1Notes on Valgrind
2=================
3
4Valgrind 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, 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 <http://valgrind.org/info/platforms.html>
172. Valgrind installed on the platform
18   See <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