Add documentation for OPENSSL_armcap

Add man page documentation for OPENSSL_armcap, and link those docs in
the relevant places.

Fixes #17045

Reviewed-by: Matt Caswell <matt@openssl.foundation>
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
MergeDate: Wed Jul 29 14:04:21 2026
(Merged from https://github.com/openssl/openssl/pull/31749)

diff --git a/doc/build.info b/doc/build.info
index 44b06941e4d960366885c049a4e2114641dca88a..c36ff802c78ae10d814271b01ff2d043e81faf59 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -1551,6 +1551,10 @@ DEPEND[html/man3/OPENSSL_LH_stats.html]=man3/OPENSSL_LH_stats.pod
 GENERATE[html/man3/OPENSSL_LH_stats.html]=man3/OPENSSL_LH_stats.pod
 DEPEND[man/man3/OPENSSL_LH_stats.3]=man3/OPENSSL_LH_stats.pod
 GENERATE[man/man3/OPENSSL_LH_stats.3]=man3/OPENSSL_LH_stats.pod
+DEPEND[html/man3/OPENSSL_armcap.html]=man3/OPENSSL_armcap.pod
+GENERATE[html/man3/OPENSSL_armcap.html]=man3/OPENSSL_armcap.pod
+DEPEND[man/man3/OPENSSL_armcap.3]=man3/OPENSSL_armcap.pod
+GENERATE[man/man3/OPENSSL_armcap.3]=man3/OPENSSL_armcap.pod
 DEPEND[html/man3/OPENSSL_config.html]=man3/OPENSSL_config.pod
 GENERATE[html/man3/OPENSSL_config.html]=man3/OPENSSL_config.pod
 DEPEND[man/man3/OPENSSL_config.3]=man3/OPENSSL_config.pod
@@ -3443,6 +3447,7 @@ html/man3/OPENSSL_Applink.html \
 html/man3/OPENSSL_FILE.html \
 html/man3/OPENSSL_LH_COMPFUNC.html \
 html/man3/OPENSSL_LH_stats.html \
+html/man3/OPENSSL_armcap.html \
 html/man3/OPENSSL_config.html \
 html/man3/OPENSSL_fork_prepare.html \
 html/man3/OPENSSL_gmtime.html \
@@ -4119,6 +4124,7 @@ man/man3/OPENSSL_Applink.3 \
 man/man3/OPENSSL_FILE.3 \
 man/man3/OPENSSL_LH_COMPFUNC.3 \
 man/man3/OPENSSL_LH_stats.3 \
+man/man3/OPENSSL_armcap.3 \
 man/man3/OPENSSL_config.3 \
 man/man3/OPENSSL_fork_prepare.3 \
 man/man3/OPENSSL_gmtime.3 \

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 27f1d3c88e7357928bb4ebf4a40d1a8c5927302c..f514cc3183e3015f89951373a1b528138c415c79 100644 (file)
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -678,8 +678,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_ppccap(3)>, L<OPENSSL_s390xcap(3)>,
-and L<OPENSSL_riscvcap(3)>.
+L<OPENSSL_armcap(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_armcap.pod b/doc/man3/OPENSSL_armcap.pod
new file mode 100644 (file)
index 0000000..78c8d3f
--- /dev/null
+++ b/doc/man3/OPENSSL_armcap.pod
@@ -0,0 +1,246 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_armcap - the Arm processor capabilities vector
+
+=head1 SYNOPSIS
+
+ env OPENSSL_armcap=... <application>
+
+=head1 DESCRIPTION
+
+libcrypto supports a range of Arm instruction set extensions. These
+extensions are represented by bits in the Arm processor capabilities vector.
+When libcrypto initializes, it stores the results returned by Arm CPU
+capabilities detection logic in the Arm processor capabilities vector. The
+CPU capabilities detection methods are OS-dependent, using 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, set the
+B<OPENSSL_armcap> environment variable before starting the application. The
+environment variable is assigned a numerical value that denotes the bits in
+the Arm processor capabilities vector. The arm_arch.h header file defines
+the possible values, which are explained in detail below.
+
+Multiple extensions are enabled by logically OR-ing the values that represent
+the desired extensions.
+
+B<Notes>: Attempting to executing an instruction from an extension that the
+target CPU does not support will result in an illegal instruction exception
+(SIGILL).
+
+Please note that not all possible values in the Arm processor capabilities
+vector are actual processor capabilities. Some values represent OpenSSL
+performance preferences for some implementations which only make sense on
+specific CPUs.
+
+The following extensions are defined:
+
+=over 4
+
+=item 0x0001
+
+Name: B<ARMV7_NEON>
+
+Meaning: Indicates support for the Armv7 Neon SIMD extensions on the processor.
+
+Effect: Enables various Armv7 Neon SIMD implementations.
+
+=item 0x00002
+
+Name: B<ARMV7_TICK>
+
+Meaning: Indicates support for the Armv7 system timer on the processor.
+
+Effect: This is used as a seed for some random number generators.
+
+=item 0x00004
+
+Name: B<ARMV8_AES>
+
+Meaning: Indicates support for the Armv8.0 AES hardware-acceleration extensions
+on the processor.
+
+Effect: Enables various Armv8.0 AES hardware-accelerated implementations.
+
+=item 0x00008
+
+Name: B<ARMV8_SHA1>
+
+Meaning: Indicates support for the Armv8.0 SHA1 hardware-acceleration extensions
+on the processor.
+
+Effect: Enables various Armv8.0 SHA1 hardware-accelerated implementations.
+
+=item 0x00010
+
+Name: B<ARMV8_SHA256>
+
+Meaning: Indicates support for the Armv8.0 SHA256 hardware-acceleration
+extensions on the processor.
+
+Effect: Enables various Armv8.0 SHA256 hardware-accelerated implementations.
+
+=item 0x00020
+
+Name: B<ARMV8_PMULL>
+
+Meaning: Indicates support for the Armv8.0 polynomial multiplication
+hardware-acceleration extensions on the processor.
+
+Effect: Used to hardware-accelerate polynomial multiplication, for example in
+AES-GCM.
+
+=item 0x00040
+
+Name: B<ARMV8_SHA512>
+
+Meaning: Indicates support for the Armv8.2 SHA512 hardware-acceleration
+extensions on the processor.
+
+Effect: Enables Armv8.2 SHA512 hardware-accelerated implementations.
+
+=item 0x00080
+
+Name: B<ARMV8_CPUID>
+
+Meaning: Indicates support for the Armv8.0 hardware identification extensions on
+the processor.
+
+Effect: Allows implementations to change their behaviour, dependant on the
+processor platform in order to achieve better performance.
+
+=item 0x00100
+
+Name: B<ARMV8_RNG>
+
+Meaning: Indicates support for the Armv8.5 hardware random number generation
+extensions on the processor.
+
+Effect: Enables hardware random number generation on supported AArch64
+processors.
+
+=item 0x00200
+
+Name: B<ARMV8_SM3>
+
+Meaning: Indicates support for the Armv8.2 SM3 hardware-acceleration extensions
+on the processor.
+
+Effect: Enables Armv8.2 SM3 hardware-accelerated implementations.
+
+=item 0x00400
+
+Name: B<ARMV8_SM4>
+
+Meaning: Indicates support for the Armv8.2 SM4 hardware-acceleration extensions
+on the processor.
+
+Effect: Enables Armv8.2 SM4 hardware-accelerated implementations.
+
+=item 0x00800
+
+Name: B<ARMV8_SHA3>
+
+Meaning: Indicates support for the Armv8.2 SHA3 hardware-acceleration extensions
+on the processor.
+
+Effect: Enables SHA3 hardware-accelerated implementations (see also
+ARMV8_HAVE_SHA3_AND_WORTH_USING).
+
+=item 0x01000
+
+Name: B<ARMV8_UNROLL8_EOR3>
+
+Meaning: Indicates support for the Arm EOR3 instruction, which is a part of the
+Armv8.2 SHA3 extensions, and enables 8x Loop unrolling in the AES-CTR
+implementation.
+
+Effect: Enables the 8x loop unrolling utilising EOR3 implementation of AES-CTR
+on platforms that support the SHA3 extension and have enough vector bandwidth.
+
+=item 0x02000
+
+Name: B<ARMV8_SVE>
+
+Meaning: Indicates support for the Armv8.2 SVE hardware extension on the
+processor.
+
+Effect: Enables various Armv8.2 SVE implementations.
+
+=item 0x04000
+
+Name: B<ARMV9_SVE2>
+
+Meaning: Indicates support for the Armv9.0 SVE2 hardware extension on the
+processor.
+
+Effect: Enables various Armv9.0 SVE2 implementations.
+
+=item 0x08000
+
+Name: B<ARMV8_HAVE_SHA3_AND_WORTH_USING>
+
+Meaning: Indicates support for the Armv8.2 SHA3 hardware-acceleration extensions
+on the processor, and that the hardware bandwidth is sufficient for it to be
+worth using.
+
+Effect: On certain Apple platforms, although the SHA3 extension is supported, it
+is actually slower than other implementations. This flag disables the
+hardware-accelerated SHA3 implementations on these platforms.
+
+=item 0x10000
+
+Name: B<ARMV8_UNROLL12_EOR3>
+
+Meaning: Indicates support for the Arm EOR3 instruction, which is a part of the
+Armv8.2 SHA3 extensions, and enables 12x loop unrolling in the AES-CTR
+implementation.
+
+Effect: Enables the 12x loop unrolling utilising EOR3 implementation of AES-CTR
+on platforms that support the extension and have enough vector bandwidth.
+
+=item 0x20000
+
+Name: B<ARMV9_SVE2_POLY1305>
+
+Meaning: Indicates support for the Armv9.0 SVE2 hardware extension, and enables
+its use in the Poly1305 implementation.
+
+Effect: Enables the Armv9.0 SVE2 Poly1305 implementation if SVE2 is enabled, the
+vector length is greater than 128 bits, and the vector length is a power of 2.
+
+=back
+
+=head1 RETURN VALUES
+
+Not available.
+
+=head1 EXAMPLES
+
+Check currently detected capabilities:
+
+ $ openssl info -cpusettings
+ OPENSSL_armcap=0x987d
+
+The detected capabilities in the above example indicate that ARMV7_NEON,
+ARMV8_AES, ARMV8_SHA1, ARMV8_SHA256, ARMV8_PMULL, ARMV8_SHA512, ARMV8_SHA3,
+ARMV8_UNROLL8_EOR3, and ARMV8_HAVE_SHA3_AND_WORTH_USING are enabled.
+
+Disable all instruction set extensions:
+
+ export OPENSSL_armcap=0x00
+
+=head1 COPYRIGHT
+
+Copyright 2026 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 27debe8ae2477261442389148fd3d5ab4f5a54fb..945cc0eccab3486faa78a914c7211ccdecb4ad55 100644 (file)
--- a/doc/man7/openssl-env.pod
+++ b/doc/man7/openssl-env.pod
@@ -241,8 +241,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_ppccap(3)>, L<OPENSSL_riscvcap(3)>,
-and L<OPENSSL_s390xcap(3)>.
+See L<OPENSSL_armcap(3)>, L<OPENSSL_ia32cap(3)>, L<OPENSSL_ppccap(3)>,
+L<OPENSSL_riscvcap(3)> and L<OPENSSL_s390xcap(3)>.
 
 These variables are not considered security-sensitive.