1=pod 2 3=head1 NAME 4 5OPENSSL_ia32cap - the x86[_64] processor capabilities vector 6 7=head1 SYNOPSIS 8 9 env OPENSSL_ia32cap=... <application> 10 11=head1 DESCRIPTION 12 13OpenSSL supports a range of x86[_64] instruction set extensions and 14features. These extensions are denoted by individual bits or groups of bits 15stored internally as ten 32-bit capability vectors and for simplicity 16represented logically below as five 64-bit vectors. This logical 17vector (LV) representation is used to streamline the definition of the 18OPENSSL_ia32cap environment variable. 19 20Upon toolkit initialization, the capability vectors are populated through 21successive executions of the CPUID instruction, after which any OPENSSL_ia32cap 22environment variable capability bit modifications are applied. After toolkit 23initialization is complete, populated vectors are then used to choose 24between different code paths to provide optimal performance across a wide 25range of x86[_64] based processors. 26 27Further CPUID information can be found in the Intel(R) Architecture 28Instruction Set Extensions Programming Reference, and the AMD64 Architecture 29Programmer's Manual (Volume 3). 30 31=head2 Notable Capability Bits for LV0 32 33The following are notable capability bits from logical vector 0 (LV0) 34resulting from the following execution of CPUID.(EAX=01H).EDX and 35CPUID.(EAX=01H).ECX: 36 37=over 4 38 39=item bit #0+4 denoting presence of Time-Stamp Counter; 40 41=item bit #0+19 denoting availability of CLFLUSH instruction; 42 43=item bit #0+20, reserved by Intel, is used to choose among RC4 code paths; 44 45=item bit #0+23 denoting MMX support; 46 47=item bit #0+24, FXSR bit, denoting availability of XMM registers; 48 49=item bit #0+25 denoting SSE support; 50 51=item bit #0+26 denoting SSE2 support; 52 53=item bit #0+28 denoting Hyperthreading, which is used to distinguish 54cores with shared cache; 55 56=item bit #0+30, reserved by Intel, denotes specifically Intel CPUs; 57 58=item bit #0+33 denoting availability of PCLMULQDQ instruction; 59 60=item bit #0+41 denoting SSSE3, Supplemental SSE3, support; 61 62=item bit #0+43 denoting AMD XOP support (forced to zero on non-AMD CPUs); 63 64=item bit #0+54 denoting availability of MOVBE instruction; 65 66=item bit #0+57 denoting AES-NI instruction set extension; 67 68=item bit #0+58, XSAVE bit, lack of which in combination with MOVBE is used 69to identify Atom Silvermont core; 70 71=item bit #0+59, OSXSAVE bit, denoting availability of YMM registers; 72 73=item bit #0+60 denoting AVX extension; 74 75=item bit #0+62 denoting availability of RDRAND instruction; 76 77=back 78 79=head2 Notable Capability Bits for LV1 80 81The following are notable capability bits from logical vector 1 (LV1) 82resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EBX and 83CPUID.(EAX=07H,ECX=0H).ECX: 84 85=over 4 86 87=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN; 88 89=item bit #64+5 denoting availability of AVX2 instructions; 90 91=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX 92and RORX; 93 94=item bit #64+16 denoting availability of AVX512F extension; 95 96=item bit #64+17 denoting availability of AVX512DQ extension; 97 98=item bit #64+18 denoting availability of RDSEED instruction; 99 100=item bit #64+19 denoting availability of ADCX and ADOX instructions; 101 102=item bit #64+21 denoting availability of AVX512IFMA extension; 103 104=item bit #64+29 denoting availability of SHA extension; 105 106=item bit #64+30 denoting availability of AVX512BW extension; 107 108=item bit #64+31 denoting availability of AVX512VL extension; 109 110=item bit #64+41 denoting availability of VAES extension; 111 112=item bit #64+42 denoting availability of VPCLMULQDQ extension; 113 114=back 115 116=head2 Notable Capability Bits for LV2 117 118The following are notable capability bits from logical vector 2 (LV2) 119resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EDX and 120CPUID.(EAX=07H,ECX=1H).EAX: 121 122=over 4 123 124=item bit #128+15 denoting availability of Hybrid CPU; 125 126=item bit #128+29 denoting support for IA32_ARCH_CAPABILITIES MSR; 127 128=item bit #128+32 denoting availability of SHA512 extension; 129 130=item bit #128+33 denoting availability of SM3 extension; 131 132=item bit #128+34 denoting availability of SM4 extension; 133 134=item bit #128+55 denoting availability of AVX-IFMA extension; 135 136=back 137 138=head2 Notable Capability Bits for LV3 139 140The following are notable capability bits from logical vector 3 (LV3) 141resulting from the following execution of CPUID.(EAX=07H,ECX=1H).EDX and 142CPUID.(EAX=07H,ECX=1H).EBX: 143 144=over 4 145 146=item bit #192+19 denoting availability of AVX10 Converged Vector ISA extension; 147 148=item bit #192+21 denoting availability of APX_F extension; 149 150=back 151 152=head2 Notable Capability Bits for LV4 153 154The following are notable capability bits from logical vector 4 (LV4) 155resulting from the following execution of CPUID.(EAX=07H,ECX=1H).ECX and 156CPUID.(EAX=24H,ECX=0H).EBX: 157 158=over 4 159 160=item bits #256+32+[0:7] denoting AVX10 Converged Vector ISA Version (8 bits); 161 162=item bit #256+48 denoting AVX10 XMM support; 163 164=item bit #256+49 denoting AVX10 YMM support; 165 166=item bit #256+50 denoting AVX10 ZMM support; 167 168=back 169 170=head2 OPENSSL_ia32cap environment variable 171 172The B<OPENSSL_ia32cap> environment variable provides a mechanism to override 173the default capability vector values at library initialization time. 174The variable consists of a series of 64-bit numbers representing each 175of the logical vectors (LV) described above. Each value is delimited by a 'B<:>'. 176Decimal/Octal/Hexadecimal values representations are supported. 177 178C<env OPENSSL_ia32cap=LV0:LV1:LV2:LV3:LV4> 179 180Used in this form, each non-null logical vector will *overwrite* the entire corresponding 181capability vector pair with the provided value. To keep compatibility with the 182behaviour of the original OPENSSL_ia32cap environment variable 183<env OPENSSL_ia32cap=LV0:LV1>, the next capability vector pairs will be set to zero. 184 185To illustrate, the following will zero all capability bits in logical vectors 1 and further 186(disable all post-AVX extensions): 187 188C<env OPENSSL_ia32cap=:0> 189 190The following will zero all capability bits in logical vectors 2 and further: 191 192C<env OPENSSL_ia32cap=::0> 193 194The following will zero all capability bits only in logical vector 1: 195C<env OPENSSL_ia32cap=:0::::> 196 197A more likely usage scenario would be to disable specific instruction set extensions. 198The 'B<~>' character is used to specify a bit mask of the extensions to be disabled for 199a particular logical vector. 200 201To illustrate, the following will disable AVX2 code paths and further extensions: 202 203C<env OPENSSL_ia32cap=:~0x20000000000> 204 205The following will disable AESNI (LV0 bit 57) and VAES (LV1 bit 41) 206extensions and therefore any code paths using those extensions but leave 207the rest of the logical vectors unchanged: 208 209C<env OPENSSL_ia32cap=~0x200000000000000:~0x20000000000:~0x0:~0x0:~0x0> 210 211=head1 NOTES 212 213Not all capability bits are copied from CPUID output verbatim. An example 214of this is the somewhat less intuitive clearing of LV0 bit #28, or ~0x10000000 215in the "environment variable" terms. It has been adjusted to reflect whether or 216not the data cache is actually shared between logical cores. This in turn affects 217the decision on whether or not expensive countermeasures against cache-timing attacks 218are applied, most notably in AES assembler module. 219 220=head1 RETURN VALUES 221 222Not available. 223 224=head1 COPYRIGHT 225 226Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved. 227 228Licensed under the Apache License 2.0 (the "License"). You may not use 229this file except in compliance with the License. You can obtain a copy 230in the file LICENSE in the source distribution or at 231L<https://www.openssl.org/source/license.html>. 232 233=cut 234
