X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FOPENSSL_ia32cap.pod;h=60dd96484c7d9702f5c6beec8d4b4eed0c0abbce;hp=790e8e9b1ef2d120c6a55a2f5546274547be42f4;hb=bf78883d45bd717f2b777312fe77511096925ab7;hpb=2b247cf81fbc320a313f952e2ea39cf63aa21010 diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod index 790e8e9b1e..60dd96484c 100644 --- a/doc/crypto/OPENSSL_ia32cap.pod +++ b/doc/crypto/OPENSSL_ia32cap.pod @@ -2,33 +2,138 @@ =head1 NAME -OPENSSL_ia32cap +OPENSSL_ia32cap - the x86[_64] processor capabilities vector =head1 SYNOPSIS - unsigned long *OPENSSL_ia32cap_loc(void); - #define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc())) + env OPENSSL_ia32cap=... =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 -register after executing CPUID instruction with EAX=1 input value (see -Intel Application Note #241618). Naturally it's meaningful on IA-32 -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 only two bits -are significant, namely bit #26 denoting SSE2 support, and bit #4 -denoting presence of Time-Stamp Counter. Clearing bit #26 at run-time -for example disables high-performance SSE2 code present in the crypto -library. You might have to do this if target OpenSSL application is -executed on SSE2 capable CPU, but under control of OS which does not -support SSE2 extentions. 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. 'env OPENSSL_ia32cap=0x10 apps/openssl', to achieve -same effect without modifying the application source code. -Alternatively you can reconfigure the toolkit with no-sse2 option and -recompile. +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 + +=item bit #4 denoting presence of Time-Stamp Counter. + +=item bit #19 denoting availability of CLFLUSH instruction; + +=item bit #20, reserved by Intel, is used to choose among RC4 code paths; + +=item bit #23 denoting MMX support; + +=item bit #24, FXSR bit, denoting availability of XMM registers; + +=item bit #25 denoting SSE support; + +=item bit #26 denoting SSE2 support; + +=item bit #28 denoting Hyperthreading, which is used to distinguish +cores with shared cache; + +=item bit #30, reserved by Intel, denotes specifically Intel CPUs; + +=item bit #33 denoting availability of PCLMULQDQ instruction; + +=item bit #41 denoting SSSE3, Supplemental SSE3, support; + +=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; + +=item bit #62 denoting availability of RDRAND instruction; + +=back + +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, 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 capability vector is further extended with EBX value returned by +CPUID with EAX=7 and ECX=0 as input. Following bits are significant: + +=over + +=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. 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 + ADCX/ADOX | 2.23 | 2.10 | 3.3 + AVX512 | 2.25 | 2.11.8 | 3.6 + +=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. =cut