Debian Codegraph @

upstream/debian-unstable/man3/OPENSSL_ppccap.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL_PPCCAP 3SSL"
58 .TH OPENSSL_PPCCAP 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OPENSSL_ppccap \- the PowerPC processor capabilities vector
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& env OPENSSL_ppccap=... <application>
69 .Ve
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 libcrypto supports PowerPC instruction set extensions. These extensions are
73 represented by bits in the PowerPC capabilities vector. When libcrypto
74 initializes, it stores the results returned by PowerPC CPU capabilities detection
75 logic in the PowerPC capabilities vector. The CPU capabilities detection methods
76 are OS-dependent and use a combination of information gathered by the kernel
77 during boot and probe functions that attempt to execute instructions and trap
78 illegal instruction signals with a signal handler.
79 .PP
80 To override the set of extensions available to an application, you can set the
81 \&\fBOPENSSL_ppccap\fR environment variable before you start the application. The
82 environment variable is assigned a numerical value that denotes the bits in
83 the PowerPC capabilities vector. The ppc_arch.h header file states that, "Flags'
84 usage can appear ambiguous, because they are set rather to reflect OpenSSL
85 performance preferences than actual processor capabilities."
86 .PP
87 Multiple extensions are enabled by logically OR-ing the values that represent the
88 desired extensions.
89 .PP
90 \&\fBNotes\fR: Enabling an extension on a CPU that does not support the extension
91 will result in a SIGILL crash. On AIX, all vector instructions can be disabled
92 with the schedo \-ro allow_vmx=0 command. DO NOT USE THIS COMMAND to disable
93 vector instructions in the OS when it is running on a CPU level that supports the
94 instructions without also disabling them in libcrpto via the OPENSSL_ppccap
95 environment variable or the application will crash with a SIGILL.
96 .PP
97 Currently, the following extensions are defined:
98 .IP 0x01 4
99 .IX Item "0x01"
100 Name: \fBPPC_FPU64\fR
101 .Sp
102 This flag is obsolete.
103 .IP 0x02 4
104 .IX Item "0x02"
105 Name: \fBPPC_ALTIVEC\fR
106 .Sp
107 Meaning: Use AltiVec (aka VMX) instructions. In some but not all cases, this
108 capability gates the use of later ISA vector instructions. The associated probe
109 instruction is vor (vector logical or).
110 .Sp
111 Effect: Enables use of vector instructions but does not enable extensions added
112 at specific ISA levels. However, disabling this capability disables a subset of
113 vector extensions added at specific ISA levels even if they are otherwise
114 enabled.
115 .IP 0x04 4
116 .IX Item "0x04"
117 Name: \fBPPC_CRYPTO207\fR
118 .Sp
119 Meaning: Use instructions added in ISA level 2.07. The associated probe
120 instruction instruction is vcipher (vector AES cipher round).
121 .Sp
122 Effect: Enables AES, SHA\-2 sigma, and other ISA 2.07 instructions for AES, SHA\-2,
123 GHASH, and Poly1305.
124 .IP 0x08 4
125 .IX Item "0x08"
126 Name: \fBPPC_FPU\fR
127 .Sp
128 Meaning: Use FPU instructions. The associated probe instruction is fmr (floating
129 move register).
130 .Sp
131 Effect: Enables Poly1305 FPU implementation. The PPC_CRYPTO207 capability
132 overrides this effect.
133 .IP 0x10 4
134 .IX Item "0x10"
135 Name: \fBPPC_MADD300\fR
136 .Sp
137 Meaning: Use instructions added in ISA level 3.00. The associated probe
138 instruction is maddhdu (multiply-add high doubleword unsigned).
139 .Sp
140 Effect: Enables use of the polynomial multiply and other ISA 3.00 instructions
141 for AES-GCM, P\-384, and P\-521.
142 .IP 0x20 4
143 .IX Item "0x20"
144 Name: \fBPPC_MFTB\fR
145 .Sp
146 Meaning: Use the mftb (move from time base) instruction. The associated probe
147 instruction is mftb.
148 .Sp
149 Effect: Enables use of the mftb instruction to sample the lower 32 bits of the
150 CPU time base register in order to acquire entropy. Considered obsolete. The
151 PPC_MFSPR268 capability overrides this capability.
152 .IP 0x40 4
153 .IX Item "0x40"
154 Name: \fBPPC_MFSPR268\fR
155 .Sp
156 Meaning: Use the mfspr (move from special purpose register) instruction to
157 read SPR 268. The associated probe instruction is mfspr 268.
158 .Sp
159 Effect: Enables use of the mfspr instruction to sample the lower 32 bits of the
160 CPU time base register from SPR 268, the TBL (time base lower) register, in order
161 to acquire entropy.
162 .IP 0x80 4
163 .IX Item "0x80"
164 Name: \fBPPC_BRD31\fR
165 .Sp
166 Meaning: Use instructions added in ISA level 3.1. The associated probe instruction
167 is brd (byte-reverse doubleword).
168 .Sp
169 Effect: Enables use of ISA 3.1 instructions in ChaCha20.
170 .SH "RETURN VALUES"
171 .IX Header "RETURN VALUES"
172 Not available.
173 .SH EXAMPLES
174 .IX Header "EXAMPLES"
175 Check currently detected capabilities:
176 .PP
177 .Vb 2
178 \& $ openssl info \-cpusettings
179 \& OPENSSL_ppccap=0x2E
180 .Ve
181 .PP
182 The detected capabilities in the above example indicate that PPC_MFTB, PPC_FPU,
183 PPC_CRYPTO207, PPC_MFSPR268, and PPC_ALTIVEC are enabled.
184 .PP
185 Disable all instruction set extensions:
186 .PP
187 .Vb 1
188 \& OPENSSL_ppccap=0x00
189 .Ve
190 .PP
191 Enable base AltiVec extensions:
192 .PP
193 .Vb 1
194 \& OPENSSL_ppccap=0x02
195 .Ve
196 .SH COPYRIGHT
197 .IX Header "COPYRIGHT"
198 Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
199 .PP
200 Licensed under the Apache License 2.0 (the "License"). You may not use
201 this file except in compliance with the License. You can obtain a copy
202 in the file LICENSE in the source distribution or at
203 <https://www.openssl.org/source/license.html>.