X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FOPENSSL_ia32cap.pod;h=dca2e20aced6af9b526b7eb1eefb7abd9af84251;hp=46afd1988083ed20de053fd6a0ede2dd23c3bc10;hb=cca3ea1e71ae90163de515f4d63d92c31e572b07;hpb=14e21f863a3e3278bb8660ea9844e92e52e1f2f7

diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod
index 46afd19880..dca2e20ace 100644
--- a/doc/crypto/OPENSSL_ia32cap.pod
+++ b/doc/crypto/OPENSSL_ia32cap.pod
@@ -2,33 +2,51 @@
 
 =head1 NAME
 
-OPENSSL_ia32cap
+OPENSSL_ia32cap - finding the IA-32 processor capabilities
 
 =head1 SYNOPSIS
 
- extern unsigned long OPENSSL_ia32cap;
- unsigned long *OPENSSL_ia32cap_loc();
+ unsigned int *OPENSSL_ia32cap_loc(void);
+ #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
 
 =head1 DESCRIPTION
 
-OPENSSL_ia32cap is 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 defined/meaningful on IA-32 platforms only.
-The variable is normally set up automatically upon toolkit
-initialization and 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. Resetting 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 programmatically
-manipulate the value, 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.
+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 seven bits are significant, namely:
 
+1. bit #4 denoting presence of Time-Stamp Counter.
+2. bit #20, reserved by Intel, is used to choose among RC4 code
+   paths;
+3. bit #23 denoting MMX support;
+4. bit #25 denoting SSE support;
+5. bit #26 denoting SSE2 support;
+6. bit #28 denoting Hyperthreading, which is used to distiguish
+   cores with shared cache;
+7. bit #30, reserved by Intel, is used to choose among RC4 code
+   paths;
+8. bit #57 denoting Intel AES instruction set extension;
+
+For example, clearing bit #26 at run-time 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. on Intel P4 processor 'env
+OPENSSL_ia32cap=0x12900010 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 intuituve 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.
 =cut