Import OpenSSL 1.1.0f

doc/crypto/OPENSSL_ia32cap.pod

@@ -2,25 +2,24 @@
 
 =head1 NAME
 
-OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector
+OPENSSL_ia32cap - the x86[_64] processor capabilities vector
 
 =head1 SYNOPSIS
 
- unsigned long *OPENSSL_ia32cap_loc(void);
- #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
+ env OPENSSL_ia32cap=... <application>
 
 =head1 DESCRIPTION
 
-Value returned by OPENSSL_ia32cap_loc() is address of a variable
-containing IA-32 processor capabilities bit vector as it appears in
-EDX:ECX register pair after executing CPUID instruction with EAX=1
-input value (see Intel Application Note #241618). Naturally it's
-meaningful on x86 and x86_64 platforms only. The variable is normally
-set up automatically upon toolkit initialization, but can be
-manipulated afterwards to modify crypto library behaviour. For the
-moment of this writing following bits are significant:
+OpenSSL supports a range of x86[_64] instruction set extensions. These
+extensions are denoted by individual bits in capability vector returned
+by processor in EDX:ECX register pair after executing CPUID instruction
+with EAX=1 input value (see Intel Application Note #241618). This vector
+is copied to memory upon toolkit initialization and used to choose
+between different code paths to provide optimal performance across wide
+range of processors. For the moment of this writing following bits are
+significant:
 
-=over
+=over 4
 
 =item bit #4 denoting presence of Time-Stamp Counter.
 
@@ -47,8 +46,13 @@ cores with shared cache;
 
 =item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);
 
+=item bit #54 denoting availability of MOVBE instruction;
+
 =item bit #57 denoting AES-NI instruction set extension;
 
+=item bit #58, XSAVE bit, lack of which in combination with MOVBE is used
+to identify Atom Silvermont core;
+
 =item bit #59, OSXSAVE bit, denoting availability of YMM registers;
 
 =item bit #60 denoting AVX extension;
@@ -57,40 +61,80 @@ cores with shared cache;
 
 =back
 
-For example, clearing bit #26 at run-time disables high-performance
-SSE2 code present in the crypto library, while clearing bit #24
-disables SSE2 code operating on 128-bit XMM register bank. You might
-have to do the latter if target OpenSSL application is executed on SSE2
-capable CPU, but under control of OS that does not enable XMM
-registers. Even though you can manipulate the value programmatically,
-you most likely will find it more appropriate to set up an environment
-variable with the same name prior starting target application, e.g. on
-Intel P4 processor 'env OPENSSL_ia32cap=0x16980010 apps/openssl', or
-better yet 'env OPENSSL_ia32cap=~0x1000000 apps/openssl' to achieve same
-effect without modifying the application source code. Alternatively you
-can reconfigure the toolkit with no-sse2 option and recompile.
+For example, in 32-bit application context clearing bit #26 at run-time
+disables high-performance SSE2 code present in the crypto library, while
+clearing bit #24 disables SSE2 code operating on 128-bit XMM register
+bank. You might have to do the latter if target OpenSSL application is
+executed on SSE2 capable CPU, but under control of OS that does not
+enable XMM registers. Historically address of the capability vector copy
+was exposed to application through OPENSSL_ia32cap_loc(), but not
+anymore. Now the only way to affect the capability detection is to set
+OPENSSL_ia32cap environment variable prior target application start. To
+give a specific example, on Intel P4 processor 'env
+OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env
+OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired
+effect. Alternatively you can reconfigure the toolkit with no-sse2
+option and recompile.
 
-Less intuitive is clearing bit #28. The truth is that it's not copied
-from CPUID output verbatim, but is adjusted to reflect whether or not
-the data cache is actually shared between logical cores. This in turn
-affects the decision on whether or not expensive countermeasures
-against cache-timing attacks are applied, most notably in AES assembler
-module.
+Less intuitive is clearing bit #28, or ~0x10000000 in the "environment
+variable" terms. The truth is that it's not copied from CPUID output
+verbatim, but is adjusted to reflect whether or not the data cache is
+actually shared between logical cores. This in turn affects the decision
+on whether or not expensive countermeasures against cache-timing attacks
+are applied, most notably in AES assembler module.
 
-The vector is further extended with EBX value returned by CPUID with
-EAX=7 and ECX=0 as input. Following bits are significant:
+The capability vector is further extended with EBX value returned by
+CPUID with EAX=7 and ECX=0 as input. Following bits are significant:
 
-=over
+=over 4
 
 =item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
 
 =item bit #64+5 denoting availability of AVX2 instructions;
 
-=item bit #64+8 denoting availability of BMI2 instructions, e.g. MUXL
+=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX
 and RORX;
 
+=item bit #64+16 denoting availability of AVX512F extension;
+
 =item bit #64+18 denoting availability of RDSEED instruction;
 
 =item bit #64+19 denoting availability of ADCX and ADOX instructions;
 
+=item bit #64+29 denoting availability of SHA extension;
+
+=item bit #64+30 denoting availability of AVX512BW extension;
+
+=item bit #64+31 denoting availability of AVX512VL extension;
+
 =back
+
+To control this extended capability word use ':' as delimiter when
+setting up OPENSSL_ia32cap environment variable. For example assigning
+':~0x20' would disable AVX2 code paths, and ':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. Besides 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
+   AVX512      | 2.25   | 2.11.8 | 3.6
+
+B<OPENSSL_ia32cap> is a macro returning the first word of the vector.
+
+=head1 COPYRIGHT
+
+Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut