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