NOTES-Valgrind.md

   1
   2 NOTES FOR VALGRIND
   3 ==================
   4
   5 Valgrind is a test harness that includes many tools such as memcheck,
   6 which is commonly used to check for memory leaks, etc. The default tool
   7 run by Valgrind is memcheck. There are other tools available, but this
   8 will focus on memcheck.
   9
  10 Valgrind runs programs in a virtual machine, this means OpenSSL unit
  11 tests run under Valgrind will take longer than normal.
  12
  13 Requirements
  14 ------------
  15
  16 1. Platform supported by Valgrind
  17    See: http://valgrind.org/info/platforms.html
  18 2. Valgrind installed on the platform
  19    See: http://valgrind.org/downloads/current.html
  20 3. OpensSSL compiled
  21    See: [INSTALL.md](INSTALL.md)
  22
  23 Running Tests
  24 -------------
  25
  26 Test behavior can be modified by adjusting environment variables.
  27
  28 `EXE_SHELL`
  29
  30 This variable is used to specify the shell used to execute OpenSSL test
  31 programs. The default wrapper (util/wrap.pl) initializes the environment
  32 to allow programs to find shared libraries. The variable can be modified
  33 to specify a different executable environment.
  34
  35     EXE_SHELL="`/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 [docs/man3/OPENSSL_ia32cap.pod](docs/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 --leak-check=full -q" OPENSSL_ia32cap=":0"
  66
  67 If an error occurs, you can then run the specific test via the `TESTS`
  68 variable with the VERBOSE option to gather additional information.
  69
  70     $ make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/wrap.pl valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"