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)

2 files changed, 38 insertions, 32 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 14b6118c36..039e1bdf08 100644
--- 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
 =============
@@ -1610,8 +1611,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 +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.
 
+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]:
diff --git a/doc/man3/OPENSSL_ia32cap.pod b/doc/man3/OPENSSL_ia32cap.pod
index 60b294acde..98bab15fb1 100644
--- 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.
 
-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.