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)

(cherry picked from commit ba26e3f46b075d44ba673e57d9c81c08f92ef7f0)

diff --git a/doc/build.info b/doc/build.info
index 4f845ca02ea8328a87cef5c9554e7fbeb4e0a344..229d1d4b4f2b29697feda28dcc2a64061983231f 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -1615,6 +1615,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
@@ -3459,6 +3463,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 \
@@ -4132,6 +4137,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 \

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index edef2ff598948a2d081d2b40971fc5c5ddd40144..635b52aeb12082e14a6ada57c74a1ded104ffbc4 100644 (file)
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -722,7 +722,8 @@ For information about specific commands, see L<openssl-engine(1)>,
 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
 

diff --git a/doc/man3/OPENSSL_ppccap.pod b/doc/man3/OPENSSL_ppccap.pod
new file mode 100644 (file)
index 0000000..8434395
--- /dev/null
+++ b/doc/man3/OPENSSL_ppccap.pod
@@ -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

diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod
index 0c7656bc5f9e9e1afefcb72982e8d06ea2f15dd3..d0727c2ce14271fd7c17fdc476231b91fa477472 100644 (file)
--- a/doc/man7/openssl-env.pod
+++ b/doc/man7/openssl-env.pod
@@ -252,7 +252,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.