Moved build instructions from the man page

Some requirements and build hints for assembler modules compilation were
moved from doc/man3/OPENSSL_ia32cap.pod to INSTALL.md.

Fixes #14674

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14683)

diff --git a/INSTALL.md b/INSTALL.md
index 14b6118c369ed0c3538b38c246445fdba918a198..039e1bdf08b9944d3617d945cb7220fdc01f6cf9 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 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
 =============
 
 Prerequisites
 =============


@@ -1610,8 +1611,8 @@ build.  Use this command:
     $ mms clean                                      ! (or mmk) OpenVMS
     $ nmake clean                                    # Windows
 
     $ 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.
 
 Compiling parts of OpenSSL with gcc and others with the system compiler will
 result in unresolved symbols on some systems.


@@ -1734,6 +1735,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.
 
 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]:
 <!-- Links  -->
 
 [openssl-users]:

diff --git a/doc/man3/OPENSSL_ia32cap.pod b/doc/man3/OPENSSL_ia32cap.pod
index 60b294acde5955e1df45367e9b1d8b12c6f83243..98bab15fb154d7eac8dacb9977b03e2f8e77c928 100644 (file)
--- a/doc/man3/OPENSSL_ia32cap.pod
+++ b/doc/man3/OPENSSL_ia32cap.pod
@@ -121,36 +121,6 @@ setting up B<OPENSSL_ia32cap> environment variable. For example assigning
 C<:~0x20> would disable AVX2 code paths, and C<:0> - all post-AVX
 extensions.
 
 C<:~0x20> would disable AVX2 code paths, and C<:0> - all post-AVX
 extensions.
 

-It should be noted that whether or not some of the most "fancy"
-extension code paths are actually assembled depends on current assembler
-version. Base minimum of AES-NI/PCLMULQDQ, SSSE3 and SHA extension code
-paths are always assembled. Apart from that, minimum assembler version
-requirements are summarized in below table:
-
-   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 | see NOTES
-   AVX512IFMA  | 2.26   | 2.11.8 | see NOTES
-   VAES        | 2.30   | 2.13.3 |
-
-=head1 NOTES
-
-Even though AVX512 support was implemented in llvm 3.6, compilation of
-assembly modules apparently requires explicit -march flag. But then
-compiler generates processor-specific code, which in turn contradicts
-the mere idea of run-time switch execution facilitated by the variable
-in question. Till the limitation is lifted, it's possible to work around
-the problem by making build procedure use following script:
-
-   #!/bin/sh
-   exec clang -no-integrated-as "$@"
-
-instead of real clang. In which case it doesn't matter which clang
-version is used, as it is GNU assembler version that will be checked.
-

 =head1 RETURN VALUES
 
 Not available.
 =head1 RETURN VALUES
 
 Not available.