diff options
Diffstat (limited to 'static/freebsd/man3/OPENSSL_ia32cap.3')
| -rw-r--r-- | static/freebsd/man3/OPENSSL_ia32cap.3 | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/static/freebsd/man3/OPENSSL_ia32cap.3 b/static/freebsd/man3/OPENSSL_ia32cap.3 new file mode 100644 index 00000000..be400467 --- /dev/null +++ b/static/freebsd/man3/OPENSSL_ia32cap.3 @@ -0,0 +1,271 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL_IA32CAP 3ossl" +.TH OPENSSL_IA32CAP 3ossl 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +OPENSSL_ia32cap \- the x86[_64] processor capabilities vector +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& env OPENSSL_ia32cap=... <application> +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL supports a range of x86[_64] instruction set extensions and +features. These extensions are denoted by individual bits or groups of bits +stored internally as ten 32\-bit capability vectors and for simplicity +represented logically below as five 64\-bit vectors. This logical +vector (LV) representation is used to streamline the definition of the +OPENSSL_ia32cap environment variable. +.PP +Upon toolkit initialization, the capability vectors are populated through +successive executions of the CPUID instruction, after which any OPENSSL_ia32cap +environment variable capability bit modifications are applied. After toolkit +initialization is complete, populated vectors are then used to choose +between different code paths to provide optimal performance across a wide +range of x86[_64] based processors. +.PP +Further CPUID information can be found in the Intel(R) Architecture +Instruction Set Extensions Programming Reference, and the AMD64 Architecture +Programmer\*(Aqs Manual (Volume 3). +.SS "Notable Capability Bits for LV0" +.IX Subsection "Notable Capability Bits for LV0" +The following are notable capability bits from logical vector 0 (LV0) +resulting from the following execution of CPUID.(EAX=01H).EDX and +CPUID.(EAX=01H).ECX: +.IP "bit #0+4 denoting presence of Time\-Stamp Counter;" 4 +.IX Item "bit #0+4 denoting presence of Time-Stamp Counter;" +.PD 0 +.IP "bit #0+19 denoting availability of CLFLUSH instruction;" 4 +.IX Item "bit #0+19 denoting availability of CLFLUSH instruction;" +.IP "bit #0+20, reserved by Intel, is used to choose among RC4 code paths;" 4 +.IX Item "bit #0+20, reserved by Intel, is used to choose among RC4 code paths;" +.IP "bit #0+23 denoting MMX support;" 4 +.IX Item "bit #0+23 denoting MMX support;" +.IP "bit #0+24, FXSR bit, denoting availability of XMM registers;" 4 +.IX Item "bit #0+24, FXSR bit, denoting availability of XMM registers;" +.IP "bit #0+25 denoting SSE support;" 4 +.IX Item "bit #0+25 denoting SSE support;" +.IP "bit #0+26 denoting SSE2 support;" 4 +.IX Item "bit #0+26 denoting SSE2 support;" +.IP "bit #0+28 denoting Hyperthreading, which is used to distinguish cores with shared cache;" 4 +.IX Item "bit #0+28 denoting Hyperthreading, which is used to distinguish cores with shared cache;" +.IP "bit #0+30, reserved by Intel, denotes specifically Intel CPUs;" 4 +.IX Item "bit #0+30, reserved by Intel, denotes specifically Intel CPUs;" +.IP "bit #0+33 denoting availability of PCLMULQDQ instruction;" 4 +.IX Item "bit #0+33 denoting availability of PCLMULQDQ instruction;" +.IP "bit #0+41 denoting SSSE3, Supplemental SSE3, support;" 4 +.IX Item "bit #0+41 denoting SSSE3, Supplemental SSE3, support;" +.IP "bit #0+43 denoting AMD XOP support (forced to zero on non\-AMD CPUs);" 4 +.IX Item "bit #0+43 denoting AMD XOP support (forced to zero on non-AMD CPUs);" +.IP "bit #0+54 denoting availability of MOVBE instruction;" 4 +.IX Item "bit #0+54 denoting availability of MOVBE instruction;" +.IP "bit #0+57 denoting AES\-NI instruction set extension;" 4 +.IX Item "bit #0+57 denoting AES-NI instruction set extension;" +.IP "bit #0+58, XSAVE bit, lack of which in combination with MOVBE is used to identify Atom Silvermont core;" 4 +.IX Item "bit #0+58, XSAVE bit, lack of which in combination with MOVBE is used to identify Atom Silvermont core;" +.IP "bit #0+59, OSXSAVE bit, denoting availability of YMM registers;" 4 +.IX Item "bit #0+59, OSXSAVE bit, denoting availability of YMM registers;" +.IP "bit #0+60 denoting AVX extension;" 4 +.IX Item "bit #0+60 denoting AVX extension;" +.IP "bit #0+62 denoting availability of RDRAND instruction;" 4 +.IX Item "bit #0+62 denoting availability of RDRAND instruction;" +.PD +.SS "Notable Capability Bits for LV1" +.IX Subsection "Notable Capability Bits for LV1" +The following are notable capability bits from logical vector 1 (LV1) +resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EBX and +CPUID.(EAX=07H,ECX=0H).ECX: +.IP "bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;" 4 +.IX Item "bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;" +.PD 0 +.IP "bit #64+5 denoting availability of AVX2 instructions;" 4 +.IX Item "bit #64+5 denoting availability of AVX2 instructions;" +.IP "bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX;" 4 +.IX Item "bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX;" +.IP "bit #64+16 denoting availability of AVX512F extension;" 4 +.IX Item "bit #64+16 denoting availability of AVX512F extension;" +.IP "bit #64+17 denoting availability of AVX512DQ extension;" 4 +.IX Item "bit #64+17 denoting availability of AVX512DQ extension;" +.IP "bit #64+18 denoting availability of RDSEED instruction;" 4 +.IX Item "bit #64+18 denoting availability of RDSEED instruction;" +.IP "bit #64+19 denoting availability of ADCX and ADOX instructions;" 4 +.IX Item "bit #64+19 denoting availability of ADCX and ADOX instructions;" +.IP "bit #64+21 denoting availability of AVX512IFMA extension;" 4 +.IX Item "bit #64+21 denoting availability of AVX512IFMA extension;" +.IP "bit #64+29 denoting availability of SHA extension;" 4 +.IX Item "bit #64+29 denoting availability of SHA extension;" +.IP "bit #64+30 denoting availability of AVX512BW extension;" 4 +.IX Item "bit #64+30 denoting availability of AVX512BW extension;" +.IP "bit #64+31 denoting availability of AVX512VL extension;" 4 +.IX Item "bit #64+31 denoting availability of AVX512VL extension;" +.IP "bit #64+41 denoting availability of VAES extension;" 4 +.IX Item "bit #64+41 denoting availability of VAES extension;" +.IP "bit #64+42 denoting availability of VPCLMULQDQ extension;" 4 +.IX Item "bit #64+42 denoting availability of VPCLMULQDQ extension;" +.PD +.SS "Notable Capability Bits for LV2" +.IX Subsection "Notable Capability Bits for LV2" +The following are notable capability bits from logical vector 2 (LV2) +resulting from the following execution of CPUID.(EAX=07H,ECX=0H).EDX and +CPUID.(EAX=07H,ECX=1H).EAX: +.IP "bit #128+15 denoting availability of Hybrid CPU;" 4 +.IX Item "bit #128+15 denoting availability of Hybrid CPU;" +.PD 0 +.IP "bit #128+29 denoting support for IA32_ARCH_CAPABILITIES MSR;" 4 +.IX Item "bit #128+29 denoting support for IA32_ARCH_CAPABILITIES MSR;" +.IP "bit #128+32 denoting availability of SHA512 extension;" 4 +.IX Item "bit #128+32 denoting availability of SHA512 extension;" +.IP "bit #128+33 denoting availability of SM3 extension;" 4 +.IX Item "bit #128+33 denoting availability of SM3 extension;" +.IP "bit #128+34 denoting availability of SM4 extension;" 4 +.IX Item "bit #128+34 denoting availability of SM4 extension;" +.IP "bit #128+55 denoting availability of AVX\-IFMA extension;" 4 +.IX Item "bit #128+55 denoting availability of AVX-IFMA extension;" +.PD +.SS "Notable Capability Bits for LV3" +.IX Subsection "Notable Capability Bits for LV3" +The following are notable capability bits from logical vector 3 (LV3) +resulting from the following execution of CPUID.(EAX=07H,ECX=1H).EDX and +CPUID.(EAX=07H,ECX=1H).EBX: +.IP "bit #192+19 denoting availability of AVX10 Converged Vector ISA extension;" 4 +.IX Item "bit #192+19 denoting availability of AVX10 Converged Vector ISA extension;" +.PD 0 +.IP "bit #192+21 denoting availability of APX_F extension;" 4 +.IX Item "bit #192+21 denoting availability of APX_F extension;" +.PD +.SS "Notable Capability Bits for LV4" +.IX Subsection "Notable Capability Bits for LV4" +The following are notable capability bits from logical vector 4 (LV4) +resulting from the following execution of CPUID.(EAX=07H,ECX=1H).ECX and +CPUID.(EAX=24H,ECX=0H).EBX: +.IP "bits #256+32+[0:7] denoting AVX10 Converged Vector ISA Version (8 bits);" 4 +.IX Item "bits #256+32+[0:7] denoting AVX10 Converged Vector ISA Version (8 bits);" +.PD 0 +.IP "bit #256+48 denoting AVX10 XMM support;" 4 +.IX Item "bit #256+48 denoting AVX10 XMM support;" +.IP "bit #256+49 denoting AVX10 YMM support;" 4 +.IX Item "bit #256+49 denoting AVX10 YMM support;" +.IP "bit #256+50 denoting AVX10 ZMM support;" 4 +.IX Item "bit #256+50 denoting AVX10 ZMM support;" +.PD +.SS "OPENSSL_ia32cap environment variable" +.IX Subsection "OPENSSL_ia32cap environment variable" +The \fBOPENSSL_ia32cap\fR environment variable provides a mechanism to override +the default capability vector values at library initialization time. +The variable consists of a series of 64\-bit numbers representing each +of the logical vectors (LV) described above. Each value is delimited by a \*(Aq\fB:\fR\*(Aq. +Decimal/Octal/Hexadecimal values representations are supported. +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=LV0:LV1:LV2:LV3:LV4\*(C'\fR +.PP +Used in this form, each non\-null logical vector will *overwrite* the entire corresponding +capability vector pair with the provided value. To keep compatibility with the +behaviour of the original OPENSSL_ia32cap environment variable +<env OPENSSL_ia32cap=LV0:LV1>, the next capability vector pairs will be set to zero. +.PP +To illustrate, the following will zero all capability bits in logical vectors 1 and further +(disable all post\-AVX extensions): +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=:0\*(C'\fR +.PP +The following will zero all capability bits in logical vectors 2 and further: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=::0\*(C'\fR +.PP +The following will zero all capability bits only in logical vector 1: +\&\f(CW\*(C`env OPENSSL_ia32cap=:0::::\*(C'\fR +.PP +A more likely usage scenario would be to disable specific instruction set extensions. +The \*(Aq\fB~\fR\*(Aq character is used to specify a bit mask of the extensions to be disabled for +a particular logical vector. +.PP +To illustrate, the following will disable AVX2 code paths and further extensions: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=:~0x20000000000\*(C'\fR +.PP +The following will disable AESNI (LV0 bit 57) and VAES (LV1 bit 41) +extensions and therefore any code paths using those extensions but leave +the rest of the logical vectors unchanged: +.PP +\&\f(CW\*(C`env OPENSSL_ia32cap=~0x200000000000000:~0x20000000000:~0x0:~0x0:~0x0\*(C'\fR +.SH NOTES +.IX Header "NOTES" +Not all capability bits are copied from CPUID output verbatim. An example +of this is the somewhat less intuitive clearing of LV0 bit #28, or ~0x10000000 +in the "environment variable" terms. It has been 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. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +Not available. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2004\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (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 +<https://www.openssl.org/source/license.html>. |