Add documentation for the newly added OBJ up calls

[openssl.git] / INSTALL.md

diff --git a/INSTALL.md b/INSTALL.md
index 14b6118c369ed0c3538b38c246445fdba918a198..202a66885e49f570c7d392ac90bbbd4da27f5b26 100644 (file)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -41,6 +41,7 @@ Table of Contents
    - [Notes on multi-threading](#notes-on-multi-threading)
    - [Notes on shared libraries](#notes-on-shared-libraries)
    - [Notes on random number generation](#notes-on-random-number-generation)
+   - [Notes on assembler modules compilation](#notes-on-assembler-modules-compilation)
 
 Prerequisites
 =============
@@ -520,9 +521,9 @@ never be used in production environments.  It will only work when used with
 gcc or clang and should be used in conjunction with the [no-shared](#no-shared)
 option.
 
-### no-acvp_tests
+### enable-acvp-tests
 
-Do not build support for Automated Cryptographic Validation Protocol (ACVP)
+Build support for Automated Cryptographic Validation Protocol (ACVP)
 tests.
 
 This is required for FIPS validation purposes. Certain ACVP tests require
@@ -577,6 +578,11 @@ as configuration option, you must ensure that it's valid for both the C and
 the C++ compiler.  If not, the C++ build test will most likely break.  As an
 alternative, you can use the language specific variables, `CFLAGS` and `CXXFLAGS`.
 
+### --banner=text
+
+Use the specified text instead of the default banner at the end of
+configuration.
+
 ### no-bulk
 
 Build only some minimal set of features.
@@ -704,9 +710,9 @@ for further details.
 Don't compile in filename and line number information (e.g.  for errors and
 memory allocation).
 
-### no-fips
+### enable-fips
 
-Don't compile the FIPS provider
+Build (and install) the FIPS provider
 
 ### no-fips-securitychecks
 
@@ -844,11 +850,14 @@ disengage SSE2 code paths upon application start-up, but if you aim for wider
 "audience" running such kernel, consider `no-sse2`.  Both the `386` and `no-asm`
 options imply `no-sse2`.
 
-### enable-ssl-trace
+### no-ssl-trace
+
+Don't build with SSL Trace capabilities.
 
-Build with the SSL Trace capabilities.
+This removes the `-trace` option from `s_client` and `s_server`, and omits the
+`SSL_trace()` function from libssl.
 
-This adds the `-trace` option to `s_client` and `s_server`.
+Disabling `ssl-trace` may provide a small reduction in libssl binary size.
 
 ### no-static-engine
 
@@ -1610,8 +1619,8 @@ build.  Use this command:
     $ mms clean                                      ! (or mmk) OpenVMS
     $ nmake clean                                    # Windows
 
-Assembler error messages can sometimes be sidestepped by using the
-`no-asm` configuration option.
+Assembler error messages can sometimes be sidestepped by using the `no-asm`
+configuration option. See also [notes](#notes-on-assembler-modules-compilation).
 
 Compiling parts of OpenSSL with gcc and others with the system compiler will
 result in unresolved symbols on some systems.
@@ -1734,6 +1743,41 @@ to install additional support software to obtain a random seed and reseed
 the CSPRNG manually.  Please check out the manual pages for `RAND_add()`,
 `RAND_bytes()`, `RAND_egd()`, and the FAQ for more information.
 
+Notes on assembler modules compilation
+--------------------------------------
+
+Compilation of some code paths in assembler modules might depend on whether the
+current assembler version supports certain ISA extensions or not. Code paths
+that use the AES-NI, PCLMULQDQ, SSSE3, and SHA extensions are always assembled.
+Apart from that, the minimum requirements for the assembler versions are shown
+in the table below:
+
+| ISA extension | GNU as | nasm   | llvm    |
+|---------------|--------|--------|---------|
+| AVX           | 2.19   | 2.09   | 3.0     |
+| AVX2          | 2.22   | 2.10   | 3.1     |
+| ADCX/ADOX     | 2.23   | 2.10   | 3.3     |
+| AVX512        | 2.25   | 2.11.8 | 3.6 (*) |
+| AVX512IFMA    | 2.26   | 2.11.8 | 6.0 (*) |
+| VAES          | 2.30   | 2.13.3 | 6.0 (*) |
+
+---
+
+(*) Even though AVX512 support was implemented in llvm 3.6, prior to version 7.0
+an explicit -march flag was apparently required to compile assembly modules. But
+then the compiler generates processor-specific code, which in turn contradicts
+the idea of performing dispatch at run-time, which is facilitated by the special
+variable `OPENSSL_ia32cap`. For versions older than 7.0, it is possible to work
+around the problem by forcing the build procedure to use the following script:
+
+    #!/bin/sh
+    exec clang -no-integrated-as "$@"
+
+instead of the real clang. In which case it doesn't matter what clang version
+is used, as it is the version of the GNU assembler that will be checked.
+
+---
+
 <!-- Links  -->
 
 [openssl-users]: