Add OPENSSL_riscvcap man page

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24172)

diff --git a/doc/build.info b/doc/build.info
index 114a37ce4a07e0e1facd26cd5c24d3a3de9acf5b..bff96a8a90a06454c9b454f389df7dfaa730476a 100644 (file)
--- a/doc/build.info
+++ b/doc/build.info
@@ -1575,6 +1575,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_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
+GENERATE[man/man3/OPENSSL_riscvcap.3]=man3/OPENSSL_riscvcap.pod
 DEPEND[html/man3/OPENSSL_s390xcap.html]=man3/OPENSSL_s390xcap.pod
 GENERATE[html/man3/OPENSSL_s390xcap.html]=man3/OPENSSL_s390xcap.pod
 DEPEND[man/man3/OPENSSL_s390xcap.3]=man3/OPENSSL_s390xcap.pod
@@ -3365,6 +3369,7 @@ html/man3/OPENSSL_init_ssl.html \
 html/man3/OPENSSL_instrument_bus.html \
 html/man3/OPENSSL_load_builtin_modules.html \
 html/man3/OPENSSL_malloc.html \
+html/man3/OPENSSL_riscvcap.html \
 html/man3/OPENSSL_s390xcap.html \
 html/man3/OPENSSL_secure_malloc.html \
 html/man3/OPENSSL_strcasecmp.html \
@@ -4020,6 +4025,7 @@ man/man3/OPENSSL_init_ssl.3 \
 man/man3/OPENSSL_instrument_bus.3 \
 man/man3/OPENSSL_load_builtin_modules.3 \
 man/man3/OPENSSL_malloc.3 \
+man/man3/OPENSSL_riscvcap.3 \
 man/man3/OPENSSL_s390xcap.3 \
 man/man3/OPENSSL_secure_malloc.3 \
 man/man3/OPENSSL_strcasecmp.3 \

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index f4274d53b75b6962a16b121042c27e42ad2d44d7..6210db45159c4e57c577a2c966ae9d0f3bfa16a0 100644 (file)
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -700,7 +700,7 @@ For information about the use of environment variables in configuration,
 see L<config(5)/ENVIRONMENT>.
 
 For information about querying or specifying CPU architecture flags, see
-L<OPENSSL_ia32cap(3)>, and L<OPENSSL_s390xcap(3)>.
+L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>.
 
 For information about all environment variables used by the OpenSSL libraries,
 see L<openssl-env(7)>.

diff --git a/doc/man3/OPENSSL_riscvcap.pod b/doc/man3/OPENSSL_riscvcap.pod
new file mode 100644 (file)
index 0000000..e1a2aa5
--- /dev/null
+++ b/doc/man3/OPENSSL_riscvcap.pod
@@ -0,0 +1,211 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_riscvcap - the RISC-V processor capabilities vector
+
+=head1 SYNOPSIS
+
+ env OPENSSL_riscvcap=... <application>
+
+=head1 DESCRIPTION
+
+libcrypto supports RISC-V instruction set extensions. These
+extensions are denoted by individual extension names in the capabilities
+vector. For Linux platform, when libcrypto is initialized, the results
+returned by the RISC-V Hardware Probing syscall (hwprobe) are stored
+in the vector. Otherwise all capabilities are disabled.
+
+To override the set of instructions available to an application, you can
+set the B<OPENSSL_riscvcap> environment variable before you start the
+application.
+
+The environment variable is similar to the RISC-V ISA string defined in the
+RISC-V Instruction Set Manual. It is case insensitive. Though due to the limit
+of the environment variable parser inside libcrypto, an extension must be
+prefixed with an underscore to make it recognizable. This also applies to the
+Vector extension.
+
+ OPENSSL_riscvcap="rv64gc_v_zba_zbb_zbs..."
+
+Note that extension implication is currently not implemented.
+For example, when "rv64gc_b" is provided as the environment variable,
+zba/zbb/zbs would not be implied in the capability vector.
+
+Currently only these extensions are recognized:
+
+=over 4
+
+=item ZBA
+
+Address Generation
+
+Could be detected using hwprobe for Linux kernel >= 6.5
+
+=item ZBB
+
+Basic bit-manipulation
+
+Could be detected using hwprobe for Linux kernel >= 6.5
+
+=item ZBC
+
+Carry-less multiplication
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZBS
+
+Single-bit instructions
+
+Could be detected using hwprobe for Linux kernel >= 6.5
+
+=item ZBKB
+
+Bit-manipulation for Cryptography
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZBKC
+
+Carry-less multiplication for Cryptography
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZBKX
+
+Crossbar permutations
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKND
+
+NIST Suite: AES Decryption
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKNE
+
+NIST Suite: AES Encryption
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKNH
+
+NIST Suite: Hash Function Instructions
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKSED
+
+ShangMi Suite: SM4 Block Cipher Instructions
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKSH
+
+ShangMi Suite: SM3 Hash Function Instructions
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZKR
+
+Entropy Source Extension
+
+=item ZKT
+
+Data Independent Execution Latency
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item V
+
+Vector Extention for Application Processors
+
+Could be detected using hwprobe for Linux kernel >= 6.5
+
+=item ZVBB
+
+Vector Basic Bit-manipulation
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVBC
+
+Vector Carryless Multiplication
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKB
+
+Vector Cryptography Bit-manipulation
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKG
+
+Vector GCM/GMAC
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKNED
+
+NIST Suite: Vector AES Block Cipher
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKNHA
+
+NIST Suite: Vector SHA-2 Secure Hash
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKNHB
+
+NIST Suite: Vector SHA-2 Secure Hash
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKSED
+
+ShangMi Suite: SM4 Block Cipher
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=item ZVKSH
+
+ShangMi Suite: SM3 Secure Hash
+
+Could be detected using hwprobe for Linux kernel >= 6.8
+
+=back
+
+=head1 RETURN VALUES
+
+Not available.
+
+=head1 EXAMPLES
+
+Check currently detected capabilities
+
+ $ openssl info -cpusettings
+ OPENSSL_riscvcap=ZBA_ZBB_ZBC_ZBS_V
+
+Disables all instruction set extensions:
+
+ OPENSSL_riscvcap="rv64gc"
+
+Only enable the vector extension:
+
+ OPENSSL_riscvcap="rv64gc_v"
+
+=head1 COPYRIGHT
+
+Copyright 2024 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 65ff2faacbd09da968eec2c44dbdecd9e80fa89d..45271d89654b76e16679a8f845590532da4b3f29 100644 (file)
--- a/doc/man7/openssl-env.pod
+++ b/doc/man7/openssl-env.pod
@@ -80,7 +80,7 @@ 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_s390xcap(3)>.
+See L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)> and L<OPENSSL_riscvcap(3)>.
 
 =item B<NO_PROXY>, B<HTTPS_PROXY>, B<HTTP_PROXY>
 

diff --git a/util/other.syms b/util/other.syms
index 6bffe6bf186f9e6ce6c5fe0d842215e668c6793d..acb7f5f1d8c0304d9f2d02829a81a04c182346b1 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -4,6 +4,7 @@
 #
 OPENSSL_ia32cap                         environment
 OPENSSL_s390xcap                        environment
+OPENSSL_riscvcap                        environment
 OPENSSL_MALLOC_FD                       environment
 OPENSSL_MALLOC_FAILURES                 environment
 OPENSSL_instrument_bus                  assembler