secure/lib/libcrypto/man/OPENSSL_ia32cap.3

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