diff options
author | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2021-02-02 18:16:19 +0100 |
---|---|---|
committer | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2021-02-12 20:35:26 +0100 |
commit | 9f1fe6a950d20fefe9c3477b9b5260609538d7fc (patch) | |
tree | c3f52287a6056c4180786ee8dc8b7ee679ffc08c /NOTES-VALGRIND.md | |
parent | 9ff5bd612a415571b12cc9febe22c710d9d2d42a (diff) | |
download | openssl-9f1fe6a950d20fefe9c3477b9b5260609538d7fc.tar.gz |
Revise some renamings of NOTES and README files
Some of the notes and readme files have been converted to markdown
format recently and renamed during this process. While adding the
.md extension was a natural step, switching to mixed cases was not
a change to the better, it gives them a ragged appearance:
NOTES.ANDROID => NOTES-Android.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-Perl.md
NOTES.UNIX => NOTES-Unix.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-Valgrind.md
NOTES.WIN => NOTES-Windows.txt
README.ENGINE => README-Engine.md
README.FIPS => README-FIPS.md
Moreover, the NOTES-Windows.txt file is the only file which has been
converted to markdown but has received a .txt file extension.
This doesn't make sense, because the OpenSSL users on Windows will
need to read the other markdown documents as well. Since they are
developers, we can trust them to be able to associate their favorite
editor with the .md extension.
In fact, having a comment at the beginning of the file saying that it
is in markdown format but we didn't dare to add the correct extension
in order not to overwhelm our Windows users can be interpreted either
as unintentionally funny or disrespectful ;-)
This commit suggests the following more consistent renaming:
NOTES.ANDROID => NOTES-ANDROID.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-PERL.md
NOTES.UNIX => NOTES-UNIX.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-VALGRIND.md
NOTES.WIN => NOTES-WINDOWS.md
README.ENGINE => README-ENGINES.md
README.FIPS => README-FIPS.md
(note the plural in README-ENGINES, anticipating a README-PROVIDERS)
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14042)
Diffstat (limited to 'NOTES-VALGRIND.md')
-rw-r--r-- | NOTES-VALGRIND.md | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/NOTES-VALGRIND.md b/NOTES-VALGRIND.md new file mode 100644 index 0000000000..00647cbd9b --- /dev/null +++ b/NOTES-VALGRIND.md @@ -0,0 +1,72 @@ +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.md](INSTALL.md) + +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 wrapper (`util/wrap.pl`) 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/wrap.pl 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 [doc/man3/OPENSSL_ia32cap.pod](doc/man3/OPENSSL_ia32cap.pod). + +Additional variables (such as `VERBOSE` and `TESTS`) are described in the +file [test/README.md](test/README.md). + +Example command line: + + $ make test EXE_SHELL="`/bin/pwd`/util/wrap.pl 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` or `VF` or `VFP` options to gather additional information. + + $ 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" |