From e616c11e170ef524b12e218537f4bf290057f8b7 Mon Sep 17 00:00:00 2001
From: Todd Short <tshort@akamai.com>
Date: Thu, 2 May 2019 14:37:18 -0400
Subject: [PATCH] Add documentation for running unit tests under Valgrind

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8867)
---
 INSTALL        |  1 +
 NOTES.VALGRIND | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 NOTES.VALGRIND

diff --git a/INSTALL b/INSTALL
index 50722a10ea..88425a8c81 100644
--- a/INSTALL
+++ b/INSTALL
@@ -23,6 +23,7 @@
   * NOTES.WIN (any supported Windows)
   * NOTES.DJGPP (DOS platform with DJGPP)
   * NOTES.ANDROID (obviously Android [NDK])
+  * NOTES.VALGRIND (testing with Valgrind)
 
  Notational conventions in this document
  ---------------------------------------
diff --git a/NOTES.VALGRIND b/NOTES.VALGRIND
new file mode 100644
index 0000000000..f128927c1a
--- /dev/null
+++ b/NOTES.VALGRIND
@@ -0,0 +1,70 @@
+
+NOTES FOR VALGRIND
+==================
+
+Valgrind is a test harness that includes many tools such as memcheck,
+which is commonly used to check for memory leaks, etc. The default tool
+run by Valgrind is memcheck. There are other tools available, but this
+will focus on memcheck.
+
+Valgrind runs programs in a virtual machine, this means OpenSSL unit
+tests run under Valgrind will take longer than normal.
+
+Requirements
+------------
+
+1. Platform supported by Valgrind
+   See: http://valgrind.org/info/platforms.html
+2. Valgrind installed on the platform
+   See: http://valgrind.org/downloads/current.html
+3. OpensSSL compiled
+   See: INSTALL
+
+Running Tests
+-------------
+
+Test behavior can be modified by adjusting environment variables.
+
+EXE_SHELL
+
+This variable is used to specify the shell used to execute OpenSSL test
+programs. The default program (util/shlib_wrap.sh) initializes the
+environment to allow programs to find shared libraries. The variable can
+be modified to specify a different executable environment.
+
+   EXE_SHELL="`/bin/pwd`/util/shlib_wrap.sh valgrind --error-exitcode=1 --leak-check=full -q"
+
+This will start up Valgrind with the default checker (memcheck).
+The --error-exitcode=1 option specifies that Valgrind should exit with an
+error code of 1 when memory leaks occur.
+The --leak-check=full option specifies extensive memory checking.
+The -q option prints only error messages.
+Additional Valgrind options may be added to the EXE_SHELL variable.
+
+OPENSSL_ia32cap
+
+This variable controls the processor-specific code on Intel processors.
+By default, OpenSSL will attempt to figure out the capabilities of a
+processor, and use it to its fullest capability. This variable can be
+used to control what capabilities OpenSSL uses.
+
+As of valgrind-3.15.0 on Linux/x86_64, instructions up to AVX2 are
+supported. Setting the following disables instructions beyond AVX2:
+
+   OPENSSL_ia32cap=":0"
+
+This variable may need to be set to something different based on the
+processor and Valgrind version you are running tests on. More information
+may be found in docs/man3/OPENSSL_ia32cap.pod.
+
+Additional variables (i.e. VERBOSE and TESTS) are described in the
+INSTALL file in the root of the OpenSSL source tree.
+
+Example command line:
+
+   make test EXE_SHELL="`/bin/pwd`/util/shlib_wrap.sh valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"
+
+If an error occurs, you can then run the specific test via the TESTS
+variable with the VERBOSE option to gather additional information.
+
+   make test VERBOSE=1 TESTS=test_test EXE_SHELL="`/bin/pwd`/util/shlib_wrap.sh valgrind --error-exitcode=1 --leak-check=full -q" OPENSSL_ia32cap=":0"