Home | History | Annotate | Line # | Download | only in dist 
      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"
     73