From: Andrey Matyukov Date: Thu, 25 Mar 2021 11:46:13 +0000 (+0300) Subject: Moved build instructions from the man page X-Git-Tag: openssl-3.0.0-alpha14~100 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=203c18f14aab47a1f9f0a18a5119997761184557;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/14683) --- diff --git a/INSTALL.md b/INSTALL.md index 14b6118c369..039e1bdf08b 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. + +--- + [openssl-users]: diff --git a/doc/man3/OPENSSL_ia32cap.pod b/doc/man3/OPENSSL_ia32cap.pod index 60b294acde5..98bab15fb15 100644 --- a/doc/man3/OPENSSL_ia32cap.pod +++ b/doc/man3/OPENSSL_ia32cap.pod @@ -121,36 +121,6 @@ setting up B 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.