doc/crypto/OPENSSL_ia32cap.pod update.
authorAndy Polyakov <appro@openssl.org>
Sun, 12 Jun 2016 10:31:40 +0000 (12:31 +0200)
committerAndy Polyakov <appro@openssl.org>
Mon, 13 Jun 2016 10:26:07 +0000 (12:26 +0200)
Reviewed-by: Rich Salz <rsalz@openssl.org>
doc/crypto/OPENSSL_ia32cap.pod

index 363d158..33c25f4 100644 (file)
@@ -47,8 +47,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,18 +62,19 @@ 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. 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.
 
 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
@@ -77,8 +83,8 @@ 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
 
@@ -86,15 +92,40 @@ EAX=7 and ECX=0 as input. Following bits are significant:
 
 =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
+
 =head1 COPYRIGHT
 
 Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.