secure/lib/libcrypto/man/man3/OPENSSL_ia32cap.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "OPENSSL_IA32CAP 3"
 136 .TH OPENSSL_IA32CAP 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 OPENSSL_ia32cap \- the x86[_64] processor capabilities vector
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& env OPENSSL_ia32cap=... <application>
 147 .Ve
 148 .SH "DESCRIPTION"
 149 .IX Header "DESCRIPTION"
 150 OpenSSL supports a range of x86[_64] instruction set extensions. These
 151 extensions are denoted by individual bits in capability vector returned
 152 by processor in \s-1EDX:ECX\s0 register pair after executing \s-1CPUID\s0 instruction
 153 with EAX=1 input value (see Intel Application Note #241618). This vector
 154 is copied to memory upon toolkit initialization and used to choose
 155 between different code paths to provide optimal performance across wide
 156 range of processors. For the moment of this writing following bits are
 157 significant:
 158 .IP "bit #4 denoting presence of Time-Stamp Counter." 4
 159 .IX Item "bit #4 denoting presence of Time-Stamp Counter."
 160 .PD 0
 161 .IP "bit #19 denoting availability of \s-1CLFLUSH\s0 instruction;" 4
 162 .IX Item "bit #19 denoting availability of CLFLUSH instruction;"
 163 .IP "bit #20, reserved by Intel, is used to choose among \s-1RC4\s0 code paths;" 4
 164 .IX Item "bit #20, reserved by Intel, is used to choose among RC4 code paths;"
 165 .IP "bit #23 denoting \s-1MMX\s0 support;" 4
 166 .IX Item "bit #23 denoting MMX support;"
 167 .IP "bit #24, \s-1FXSR\s0 bit, denoting availability of \s-1XMM\s0 registers;" 4
 168 .IX Item "bit #24, FXSR bit, denoting availability of XMM registers;"
 169 .IP "bit #25 denoting \s-1SSE\s0 support;" 4
 170 .IX Item "bit #25 denoting SSE support;"
 171 .IP "bit #26 denoting \s-1SSE2\s0 support;" 4
 172 .IX Item "bit #26 denoting SSE2 support;"
 173 .IP "bit #28 denoting Hyperthreading, which is used to distinguish cores with shared cache;" 4
 174 .IX Item "bit #28 denoting Hyperthreading, which is used to distinguish cores with shared cache;"
 175 .IP "bit #30, reserved by Intel, denotes specifically Intel CPUs;" 4
 176 .IX Item "bit #30, reserved by Intel, denotes specifically Intel CPUs;"
 177 .IP "bit #33 denoting availability of \s-1PCLMULQDQ\s0 instruction;" 4
 178 .IX Item "bit #33 denoting availability of PCLMULQDQ instruction;"
 179 .IP "bit #41 denoting \s-1SSSE3,\s0 Supplemental \s-1SSE3,\s0 support;" 4
 180 .IX Item "bit #41 denoting SSSE3, Supplemental SSE3, support;"
 181 .IP "bit #43 denoting \s-1AMD XOP\s0 support (forced to zero on non-AMD CPUs);" 4
 182 .IX Item "bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);"
 183 .IP "bit #54 denoting availability of \s-1MOVBE\s0 instruction;" 4
 184 .IX Item "bit #54 denoting availability of MOVBE instruction;"
 185 .IP "bit #57 denoting AES-NI instruction set extension;" 4
 186 .IX Item "bit #57 denoting AES-NI instruction set extension;"
 187 .IP "bit #58, \s-1XSAVE\s0 bit, lack of which in combination with \s-1MOVBE\s0 is used to identify Atom Silvermont core;" 4
 188 .IX Item "bit #58, XSAVE bit, lack of which in combination with MOVBE is used to identify Atom Silvermont core;"
 189 .IP "bit #59, \s-1OSXSAVE\s0 bit, denoting availability of \s-1YMM\s0 registers;" 4
 190 .IX Item "bit #59, OSXSAVE bit, denoting availability of YMM registers;"
 191 .IP "bit #60 denoting \s-1AVX\s0 extension;" 4
 192 .IX Item "bit #60 denoting AVX extension;"
 193 .IP "bit #62 denoting availability of \s-1RDRAND\s0 instruction;" 4
 194 .IX Item "bit #62 denoting availability of RDRAND instruction;"
 195 .PD
 196 .PP
 197 For example, in 32\-bit application context clearing bit #26 at run-time
 198 disables high-performance \s-1SSE2\s0 code present in the crypto library, while
 199 clearing bit #24 disables \s-1SSE2\s0 code operating on 128\-bit \s-1XMM\s0 register
 200 bank. You might have to do the latter if target OpenSSL application is
 201 executed on \s-1SSE2\s0 capable \s-1CPU,\s0 but under control of \s-1OS\s0 that does not
 202 enable \s-1XMM\s0 registers. Historically address of the capability vector copy
 203 was exposed to application through \fBOPENSSL_ia32cap_loc()\fR, but not
 204 anymore. Now the only way to affect the capability detection is to set
 205 OPENSSL_ia32cap environment variable prior target application start. To
 206 give a specific example, on Intel P4 processor 'env
 207 OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env
 208 OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired
 209 effect. Alternatively you can reconfigure the toolkit with no\-sse2
 210 option and recompile.
 211 .PP
 212 Less intuitive is clearing bit #28, or ~0x10000000 in the \*(L"environment
 213 variable\*(R" terms. The truth is that it's not copied from \s-1CPUID\s0 output
 214 verbatim, but is adjusted to reflect whether or not the data cache is
 215 actually shared between logical cores. This in turn affects the decision
 216 on whether or not expensive countermeasures against cache-timing attacks
 217 are applied, most notably in \s-1AES\s0 assembler module.
 218 .PP
 219 The capability vector is further extended with \s-1EBX\s0 value returned by
 220 \&\s-1CPUID\s0 with EAX=7 and ECX=0 as input. Following bits are significant:
 221 .IP "bit #64+3 denoting availability of \s-1BMI1\s0 instructions, e.g. \s-1ANDN\s0;" 4
 222 .IX Item "bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;"
 223 .PD 0
 224 .IP "bit #64+5 denoting availability of \s-1AVX2\s0 instructions;" 4
 225 .IX Item "bit #64+5 denoting availability of AVX2 instructions;"
 226 .IP "bit #64+8 denoting availability of \s-1BMI2\s0 instructions, e.g. \s-1MULX\s0 and \s-1RORX\s0;" 4
 227 .IX Item "bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX;"
 228 .IP "bit #64+16 denoting availability of \s-1AVX512F\s0 extension;" 4
 229 .IX Item "bit #64+16 denoting availability of AVX512F extension;"
 230 .IP "bit #64+18 denoting availability of \s-1RDSEED\s0 instruction;" 4
 231 .IX Item "bit #64+18 denoting availability of RDSEED instruction;"
 232 .IP "bit #64+19 denoting availability of \s-1ADCX\s0 and \s-1ADOX\s0 instructions;" 4
 233 .IX Item "bit #64+19 denoting availability of ADCX and ADOX instructions;"
 234 .IP "bit #64+21 denoting availability of VPMADD52[\s-1LH\s0]UQ instructions, aka \s-1AVX512IFMA\s0 extension;" 4
 235 .IX Item "bit #64+21 denoting availability of VPMADD52[LH]UQ instructions, aka AVX512IFMA extension;"
 236 .IP "bit #64+29 denoting availability of \s-1SHA\s0 extension;" 4
 237 .IX Item "bit #64+29 denoting availability of SHA extension;"
 238 .IP "bit #64+30 denoting availability of \s-1AVX512BW\s0 extension;" 4
 239 .IX Item "bit #64+30 denoting availability of AVX512BW extension;"
 240 .IP "bit #64+31 denoting availability of \s-1AVX512VL\s0 extension;" 4
 241 .IX Item "bit #64+31 denoting availability of AVX512VL extension;"
 242 .IP "bit #64+41 denoting availability of \s-1VAES\s0 extension;" 4
 243 .IX Item "bit #64+41 denoting availability of VAES extension;"
 244 .IP "bit #64+42 denoting availability of \s-1VPCLMULQDQ\s0 extension;" 4
 245 .IX Item "bit #64+42 denoting availability of VPCLMULQDQ extension;"
 246 .PD
 247 .PP
 248 To control this extended capability word use ':' as delimiter when
 249 setting up OPENSSL_ia32cap environment variable. For example assigning
 250 \&':~0x20' would disable \s-1AVX2\s0 code paths, and ':0' \- all post-AVX
 251 extensions.
 252 .PP
 253 It should be noted that whether or not some of the most \*(L"fancy\*(R"
 254 extension code paths are actually assembled depends on current assembler
 255 version. Base minimum of \s-1AES\-NI/PCLMULQDQ, SSSE3\s0 and \s-1SHA\s0 extension code
 256 paths are always assembled. Apart from that, minimum assembler version
 257 requirements are summarized in below table:
 258 .PP
 259 .Vb 8
 260 \&   Extension   | GNU as | nasm   | llvm
 261 \&   \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-
 262 \&   AVX         | 2.19   | 2.09   | 3.0
 263 \&   AVX2        | 2.22   | 2.10   | 3.1
 264 \&   ADCX/ADOX   | 2.23   | 2.10   | 3.3
 265 \&   AVX512      | 2.25   | 2.11.8 | see NOTES
 266 \&   AVX512IFMA  | 2.26   | 2.11.8 | see NOTES
 267 \&   VAES        | 2.30   | 2.13.3 |
 268 .Ve
 269 .SH "NOTES"
 270 .IX Header "NOTES"
 271 Even though \s-1AVX512\s0 support was implemented in llvm 3.6, compilation of
 272 assembly modules apparently requires explicit \-march flag. But then
 273 compiler generates processor-specific code, which in turn contradicts
 274 the mere idea of run-time switch execution facilitated by the variable
 275 in question. Till the limitation is lifted, it's possible to work around
 276 the problem by making build procedure use following script:
 277 .PP
 278 .Vb 2
 279 \&   #!/bin/sh
 280 \&   exec clang \-no\-integrated\-as "$@"
 281 .Ve
 282 .PP
 283 instead of real clang. In which case it doesn't matter which clang
 284 version is used, as it is \s-1GNU\s0 assembler version that will be checked.
 285 .SH "RETURN VALUES"
 286 .IX Header "RETURN VALUES"
 287 Not available.
 288 .SH "COPYRIGHT"
 289 .IX Header "COPYRIGHT"
 290 Copyright 2004\-2020 The OpenSSL Project Authors. All Rights Reserved.
 291 .PP
 292 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 293 this file except in compliance with the License.  You can obtain a copy
 294 in the file \s-1LICENSE\s0 in the source distribution or at
 295 <https://www.openssl.org/source/license.html>.