]>
Commit | Line | Data |
---|---|---|
4148581e DMSP |
1 | Notes on Valgrind |
2 | ================= | |
e616c11e TS |
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 | |
1dc1ea18 | 16 | See <http://valgrind.org/info/platforms.html> |
e616c11e | 17 | 2. Valgrind installed on the platform |
1dc1ea18 | 18 | See <http://valgrind.org/downloads/current.html> |
e616c11e | 19 | 3. OpensSSL compiled |
1dc1ea18 | 20 | See [INSTALL.md](INSTALL.md) |
e616c11e TS |
21 | |
22 | Running Tests | |
23 | ------------- | |
24 | ||
25 | Test behavior can be modified by adjusting environment variables. | |
26 | ||
3a0b3cc9 | 27 | `EXE_SHELL` |
e616c11e TS |
28 | |
29 | This variable is used to specify the shell used to execute OpenSSL test | |
1dc1ea18 | 30 | programs. The default wrapper (`util/wrap.pl`) initializes the environment |
30a4cda5 RL |
31 | to allow programs to find shared libraries. The variable can be modified |
32 | to specify a different executable environment. | |
e616c11e | 33 | |
1dc1ea18 DDO |
34 | EXE_SHELL=\ |
35 | "`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" | |
e616c11e | 36 | |
1dc1ea18 DDO |
37 | This will start up Valgrind with the default checker (`memcheck`). |
38 | The `--error-exitcode=1` option specifies that Valgrind should exit with an | |
e616c11e | 39 | error code of 1 when memory leaks occur. |
1dc1ea18 DDO |
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. | |
e616c11e | 43 | |
3a0b3cc9 | 44 | `OPENSSL_ia32cap` |
e616c11e TS |
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 | ||
9afbb681 | 54 | `OPENSSL_ia32cap=":0"` |
e616c11e TS |
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 | |
1dc1ea18 | 58 | may be found in [doc/man3/OPENSSL_ia32cap.pod](doc/man3/OPENSSL_ia32cap.pod). |
e616c11e | 59 | |
3a0b3cc9 | 60 | Additional variables (such as `VERBOSE` and `TESTS`) are described in the |
9afbb681 | 61 | file [test/README.md](test/README.md). |
e616c11e TS |
62 | |
63 | Example command line: | |
64 | ||
1dc1ea18 DDO |
65 | $ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 \ |
66 | --leak-check=full -q" OPENSSL_ia32cap=":0" | |
e616c11e | 67 | |
1dc1ea18 DDO |
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. | |
e616c11e | 70 | |
1dc1ea18 DDO |
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" |