OPENSSL_ia32cap.pod update.
[openssl.git] / doc / crypto / OPENSSL_ia32cap.pod
index 2e659d34a5c43b29e36b2e622a30fd165c99aa1f..dca2e20aced6af9b526b7eb1eefb7abd9af84251 100644 (file)
@@ -6,28 +6,31 @@ OPENSSL_ia32cap - finding the IA-32 processor capabilities
 
 =head1 SYNOPSIS
 
- unsigned long *OPENSSL_ia32cap_loc(void);
- #define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc()))
+ unsigned int *OPENSSL_ia32cap_loc(void);
+ #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
 
 =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[E]
-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 six bits are
-significant, namely:
-
-1. bit #28 denoting Hyperthreading, which is used to distiguish
+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;
-2. bit #26 denoting SSE2 support;
-3. bit #25 denoting SSE support;
-4. bit #23 denoting MMX support;
-5. bit #20, reserved by Intel, is used to choose between RC4 code
-   pathes;
-6. bit #4 denoting presence of Time-Stamp Counter.
+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
@@ -40,4 +43,10 @@ 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