NOTES-VALGRIND.md

   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"