From e616c11e170ef524b12e218537f4bf290057f8b7 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Thu, 2 May 2019 14:37:18 -0400 Subject: [PATCH] Add documentation for running unit tests under Valgrind Reviewed-by: Tim Hudson Reviewed-by: Richard Levitte (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" -- 2.25.1