mirror of
https://github.com/openssl/openssl.git
synced 2026-01-25 02:56:43 +00:00
doc/man3: Add OPENSSL_ppccap.pod
This patch adds a man page documenting the OPENSSL_ppccap environment variable that is analogous to capability environment variable man pages for other architectures. Fixes #17046 Signed-off-by: George Wilson <gcwilson@linux.ibm.com> Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com> Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org> (Merged from https://github.com/openssl/openssl/pull/29230)
This commit is contained in:
George Wilson
committed by
Tomas Mraz
Tomas Mraz
parent
688e4f4a5f
commit
ba26e3f46b
@@ -1607,6 +1607,10 @@ DEPEND[html/man3/OPENSSL_malloc.html]=man3/OPENSSL_malloc.pod
|
||||
GENERATE[html/man3/OPENSSL_malloc.html]=man3/OPENSSL_malloc.pod
|
||||
DEPEND[man/man3/OPENSSL_malloc.3]=man3/OPENSSL_malloc.pod
|
||||
GENERATE[man/man3/OPENSSL_malloc.3]=man3/OPENSSL_malloc.pod
|
||||
DEPEND[html/man3/OPENSSL_ppccap.html]=man3/OPENSSL_ppccap.pod
|
||||
GENERATE[html/man3/OPENSSL_ppccap.html]=man3/OPENSSL_ppccap.pod
|
||||
DEPEND[man/man3/OPENSSL_ppccap.3]=man3/OPENSSL_ppccap.pod
|
||||
GENERATE[man/man3/OPENSSL_ppccap.3]=man3/OPENSSL_ppccap.pod
|
||||
DEPEND[html/man3/OPENSSL_riscvcap.html]=man3/OPENSSL_riscvcap.pod
|
||||
GENERATE[html/man3/OPENSSL_riscvcap.html]=man3/OPENSSL_riscvcap.pod
|
||||
DEPEND[man/man3/OPENSSL_riscvcap.3]=man3/OPENSSL_riscvcap.pod
|
||||
@@ -3455,6 +3459,7 @@ html/man3/OPENSSL_instrument_bus.html \
|
||||
html/man3/OPENSSL_load_builtin_modules.html \
|
||||
html/man3/OPENSSL_load_u16_le.html \
|
||||
html/man3/OPENSSL_malloc.html \
|
||||
html/man3/OPENSSL_ppccap.html \
|
||||
html/man3/OPENSSL_riscvcap.html \
|
||||
html/man3/OPENSSL_s390xcap.html \
|
||||
html/man3/OPENSSL_secure_malloc.html \
|
||||
@@ -4129,6 +4134,7 @@ man/man3/OPENSSL_instrument_bus.3 \
|
||||
man/man3/OPENSSL_load_builtin_modules.3 \
|
||||
man/man3/OPENSSL_load_u16_le.3 \
|
||||
man/man3/OPENSSL_malloc.3 \
|
||||
man/man3/OPENSSL_ppccap.3 \
|
||||
man/man3/OPENSSL_riscvcap.3 \
|
||||
man/man3/OPENSSL_s390xcap.3 \
|
||||
man/man3/OPENSSL_secure_malloc.3 \
|
||||
|
||||
@@ -674,7 +674,8 @@ For information about specific commands, see L<openssl-rehash(1)>
|
||||
and L<tsget(1)>.
|
||||
|
||||
For information about querying or specifying CPU architecture flags, see
|
||||
L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>.
|
||||
L<OPENSSL_ia32cap(3)>, L<OPENSSL_ppccap(3)>, L<OPENSSL_s390xcap(3)>,
|
||||
and L<OPENSSL_riscvcap(3)>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
|
||||
155
doc/man3/OPENSSL_ppccap.pod
Normal file
155
doc/man3/OPENSSL_ppccap.pod
Normal file
@@ -0,0 +1,155 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OPENSSL_ppccap - the PowerPC processor capabilities vector
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
env OPENSSL_ppccap=... <application>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
libcrypto supports PowerPC instruction set extensions. These extensions are
|
||||
represented by bits in the PowerPC capabilities vector. When libcrypto
|
||||
initializes, it stores the results returned by PowerPC CPU capabilities detection
|
||||
logic in the PowerPC capabilities vector. The CPU capabilities detection methods
|
||||
are OS-dependent and use a combination of information gathered by the kernel
|
||||
during boot and probe functions that attempt to execute instructions and trap
|
||||
illegal instruction signals with a signal handler.
|
||||
|
||||
To override the set of extensions available to an application, you can set the
|
||||
B<OPENSSL_ppccap> environment variable before you start the application. The
|
||||
environment variable is assigned a numerical value that denotes the bits in
|
||||
the PowerPC capabilities vector. The ppc_arch.h header file states that, "Flags'
|
||||
usage can appear ambiguous, because they are set rather to reflect OpenSSL
|
||||
performance preferences than actual processor capabilities."
|
||||
|
||||
Multiple extensions are enabled by logically OR-ing the values that represent the
|
||||
desired extensions.
|
||||
|
||||
B<Notes>: Enabling an extension on a CPU that does not support the extension
|
||||
will result in a SIGILL crash. On AIX, all vector instructions can be disabled
|
||||
with the schedo -ro allow_vmx=0 command. DO NOT USE THIS COMMAND to disable
|
||||
vector instructions in the OS when it is running on a CPU level that supports the
|
||||
instructions without also disabling them in libcrpto via the OPENSSL_ppccap
|
||||
environment variable or the application will crash with a SIGILL.
|
||||
|
||||
Currently, the following extensions are defined:
|
||||
|
||||
=over 4
|
||||
|
||||
=item 0x01
|
||||
|
||||
Name: B<PPC_FPU64>
|
||||
|
||||
This flag is obsolete.
|
||||
|
||||
=item 0x02
|
||||
|
||||
Name: B<PPC_ALTIVEC>
|
||||
|
||||
Meaning: Use AltiVec (aka VMX) instructions. In some but not all cases, this
|
||||
capability gates the use of later ISA vector instructions. The associated probe
|
||||
instruction is vor (vector logical or).
|
||||
|
||||
Effect: Enables use of vector instructions but does not enable extensions added
|
||||
at specific ISA levels. However, disabling this capability disables a subset of
|
||||
vector extensions added at specific ISA levels even if they are otherwise
|
||||
enabled.
|
||||
|
||||
=item 0x04
|
||||
|
||||
Name: B<PPC_CRYPTO207>
|
||||
|
||||
Meaning: Use instructions added in ISA level 2.07. The associated probe
|
||||
instruction instruction is vcipher (vector AES cipher round).
|
||||
|
||||
Effect: Enables AES, SHA-2 sigma, and other ISA 2.07 instructions for AES, SHA-2,
|
||||
GHASH, and Poly1305.
|
||||
|
||||
=item 0x08
|
||||
|
||||
Name: B<PPC_FPU>
|
||||
|
||||
Meaning: Use FPU instructions. The associated probe instruction is fmr (floating
|
||||
move register).
|
||||
|
||||
Effect: Enables Poly1305 FPU implementation. The PPC_CRYPTO207 capability
|
||||
overrides this effect.
|
||||
|
||||
=item 0x10
|
||||
|
||||
Name: B<PPC_MADD300>
|
||||
|
||||
Meaning: Use instructions added in ISA level 3.00. The associated probe
|
||||
instruction is maddhdu (multiply-add high doubleword unsigned).
|
||||
|
||||
Effect: Enables use of the polynomial multiply and other ISA 3.00 instructions
|
||||
for AES-GCM, P-384, and P-521.
|
||||
|
||||
=item 0x20
|
||||
|
||||
Name: B<PPC_MFTB>
|
||||
|
||||
Meaning: Use the mftb (move from time base) instruction. The associated probe
|
||||
instruction is mftb.
|
||||
|
||||
Effect: Enables use of the mftb instruction to sample the lower 32 bits of the
|
||||
CPU time base register in order to acquire entropy. Considered obsolete. The
|
||||
PPC_MFSPR268 capability overrides this capability.
|
||||
|
||||
=item 0x40
|
||||
|
||||
Name: B<PPC_MFSPR268>
|
||||
|
||||
Meaning: Use the mfspr (move from special purpose register) instruction to
|
||||
read SPR 268. The associated probe instruction is mfspr 268.
|
||||
|
||||
Effect: Enables use of the mfspr instruction to sample the lower 32 bits of the
|
||||
CPU time base register from SPR 268, the TBL (time base lower) register, in order
|
||||
to acquire entropy.
|
||||
|
||||
=item 0x80
|
||||
|
||||
Name: B<PPC_BRD31>
|
||||
|
||||
Meaning: Use instructions added in ISA level 3.1. The associated probe instruction
|
||||
is brd (byte-reverse doubleword).
|
||||
|
||||
Effect: Enables use of ISA 3.1 instructions in ChaCha20.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
Not available.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Check currently detected capabilities:
|
||||
|
||||
$ openssl info -cpusettings
|
||||
OPENSSL_ppccap=0x2E
|
||||
|
||||
The detected capabilities in the above example indicate that PPC_MFTB, PPC_FPU,
|
||||
PPC_CRYPTO207, PPC_MFSPR268, and PPC_ALTIVEC are enabled.
|
||||
|
||||
Disable all instruction set extensions:
|
||||
|
||||
OPENSSL_ppccap=0x00
|
||||
|
||||
Enable base AltiVec extensions:
|
||||
|
||||
OPENSSL_ppccap=0x02
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
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
|
||||
L<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
@@ -234,7 +234,8 @@ OpenSSL supports a number of different algorithm implementations for
|
||||
various machines and, by default, it determines which to use based on the
|
||||
processor capabilities and run time feature enquiry. These environment
|
||||
variables can be used to exert more control over this selection process.
|
||||
See L<OPENSSL_ia32cap(3)>, L<OPENSSL_riscvcap(3)>, and L<OPENSSL_s390xcap(3)>.
|
||||
See L<OPENSSL_ia32cap(3)>, L<OPENSSL_ppccap(3)>, L<OPENSSL_riscvcap(3)>,
|
||||
and L<OPENSSL_s390xcap(3)>.
|
||||
|
||||
These variables are not considered security-sensitive.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user