From d3184110196b690d314424ac55404278d98eda32 Mon Sep 17 00:00:00 2001 From: Hongren Zheng Date: Mon, 22 Apr 2024 12:50:21 +0800 Subject: [PATCH] Add OPENSSL_riscvcap man page Reviewed-by: Paul Dale Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/24172) --- doc/build.info | 6 + doc/man1/openssl.pod | 2 +- doc/man3/OPENSSL_riscvcap.pod | 211 ++++++++++++++++++++++++++++++++++ doc/man7/openssl-env.pod | 2 +- util/other.syms | 1 + 5 files changed, 220 insertions(+), 2 deletions(-) create mode 100644 doc/man3/OPENSSL_riscvcap.pod diff --git a/doc/build.info b/doc/build.info index 114a37ce4a..bff96a8a90 100644 --- 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 f4274d53b7..6210db4515 100644 --- 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. For information about querying or specifying CPU architecture flags, see -L, and L. +L, L and L. For information about all environment variables used by the OpenSSL libraries, see L. diff --git a/doc/man3/OPENSSL_riscvcap.pod b/doc/man3/OPENSSL_riscvcap.pod new file mode 100644 index 0000000000..e1a2aa5337 --- /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=... + +=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 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. + +=cut diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod index 65ff2faacb..45271d8965 100644 --- 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, L. +See L, L and L. =item B, B, B diff --git a/util/other.syms b/util/other.syms index 6bffe6bf18..acb7f5f1d8 100644 --- 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