s390x assembly pack: add OPENSSL_s390xcap man page.

Signed-off-by: Patrick Steuer <patrick.steuer@de.ibm.com>

Reviewed-by: Andy Polyakov <appro@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6813)

1 files changed, 173 insertions, 0 deletions

diff --git a/doc/man3/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod
new file mode 100644
index 0000000000..550136a82b
--- /dev/null
+++ b/doc/man3/OPENSSL_s390xcap.pod
@@ -0,0 +1,173 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_s390xcap - the IBM z processor capabilities vector
+
+=head1 SYNOPSIS
+
+ env OPENSSL_s390xcap=... <application>
+
+=head1 DESCRIPTION
+
+libcrypto supports z/Architecture instruction set extensions. These
+extensions are denoted by individual bits in the capabilities vector.
+When libcrypto is initialized, the bits returned by the STFLE instruction
+and by the QUERY functions are stored in the vector.
+
+To change the set of instructions available to an application, you can
+set the OPENSSL_s390xcap environment variable before you start the
+application. After initialization, the capability vector is ANDed bitwise
+with a mask which is derived from the environment variable.
+
+The environment variable is a semicolon-separated list of tokens which is
+processed from left to right (whitespace is ignored):
+
+ OPENSSL_s390xcap="<tok1>;<tok2>;..."
+
+There are three types of tokens:
+
+=over 4
+
+=item <string>
+
+The name of a processor generation. A bit in the environment variable's
+mask is set to one if and only if the specified processor generation
+implements the corresponding instruction set extension. Possible values
+are z900, z990, z9, z10, z196, zEC12, z13 and z14.
+
+=item <string>:<mask>:<mask>
+
+The name of an instruction followed by two 64-bit masks. The part of the
+environment variable's mask corresponding to the specified instruction is
+set to the specified 128-bit mask. Possible values are kimd, klmd, km, kmc,
+kmac, kmctr, kmo, kmf, prno and kma.
+
+=item stfle:<mask>:<mask>:<mask>
+
+Store-facility-list-extended (stfle) followed by three 64-bit masks. The
+part of the environment variable's mask corresponding to the stfle
+instruction is set to the specified 192-bit mask.
+
+=back
+
+The 64-bit masks are specified in hexadecimal notation. The 0x prefix is
+optional. Prefix a mask with a tilde (~) to denote a bitwise NOT operation.
+
+The following is a list of significant bits for each instruction. Colon
+rows separate the individual 64-bit masks. The bit numbers in the first
+column are consistent with [1], that is, 0 denotes the leftmost bit and
+the numbering is continuous across 64-bit mask boundaries.
+
+      Bit     Mask     Facility/Function
+
+ stfle:
+      # 17    1<<46    message-security assist
+      # 25    1<<38    store-clock-fast facility
+      :
+      # 76    1<<51    message-security assist extension 3
+      # 77    1<<50    message-security assist extension 4
+      :
+      #129    1<<62    vector facility
+      #134    1<<57    vector packed decimal facility
+      #135    1<<56    vector enhancements facility 1
+      #146    1<<45    message-security assist extension 8
+
+ kimd :
+      #  1    1<<62    KIMD-SHA-1
+      #  2    1<<61    KIMD-SHA-256
+      #  3    1<<60    KIMD-SHA-512
+      # 32    1<<31    KIMD-SHA3-224
+      # 33    1<<30    KIMD-SHA3-256
+      # 34    1<<29    KIMD-SHA3-384
+      # 35    1<<28    KIMD-SHA3-512
+      # 36    1<<27    KIMD-SHAKE-128
+      # 37    1<<26    KIMD-SHAKE-256
+      :
+      # 65    1<<62    KIMD-GHASH
+
+ klmd :
+      # 32    1<<31    KLMD-SHA3-224
+      # 33    1<<30    KLMD-SHA3-256
+      # 34    1<<29    KLMD-SHA3-384
+      # 35    1<<28    KLMD-SHA3-512
+      # 36    1<<27    KLMD-SHAKE-128
+      # 37    1<<26    KLMD-SHAKE-256
+      :
+
+ km   :
+      # 18    1<<45    KM-AES-128
+      # 19    1<<44    KM-AES-192
+      # 20    1<<43    KM-AES-256
+      # 50    1<<13    KM-XTS-AES-128
+      # 52    1<<11    KM-XTS-AES-256
+      :
+
+ kmc  :
+      # 18    1<<45    KMC-AES-128
+      # 19    1<<44    KMC-AES-192
+      # 20    1<<43    KMC-AES-256
+      :
+
+ kmac :
+      # 18    1<<45    KMAC-AES-128
+      # 19    1<<44    KMAC-AES-192
+      # 20    1<<43    KMAC-AES-256
+      :
+
+ kmctr:
+      :
+
+ kmo  :
+      # 18    1<<45    KMO-AES-128
+      # 19    1<<44    KMO-AES-192
+      # 20    1<<43    KMO-AES-256
+      :
+
+ kmf  :
+      # 18    1<<45    KMF-AES-128
+      # 19    1<<44    KMF-AES-192
+      # 20    1<<43    KMF-AES-256
+      :
+
+ prno :
+      :
+
+ kma  :
+      # 18    1<<45    KMA-GCM-AES-128
+      # 19    1<<44    KMA-GCM-AES-192
+      # 20    1<<43    KMA-GCM-AES-256
+      :
+
+=head1 EXAMPLES
+
+Disables all instruction set extensions which the z196 processor does not implement:
+
+ OPENSSL_s390xcap="z196"
+
+Disables the vector facility:
+
+ OPENSSL_s390xcap="stfle:~0:~0:~0x4000000000000000"
+
+Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
+
+ OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"
+
+=head1 RETURN VALUES
+
+Not available.
+
+=head1 SEE ALSO
+
+[1] z/Architecture Principles of Operation, SA22-7832-11
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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