| 1 | Notes on 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. OpenSSL 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"
|
|---|
