Re: [PATCH v7 15/17] docs/s390: Document CPACF instructions support

[Harald Freudenberger <freude@linux.ibm.com>]

On 2026-06-18 08:28, Finn Callies wrote:
> On 17.06.26 11:48, Harald Freudenberger wrote:
>> Add a first document covering the Qemu s390 CPACF instructions
>> and functions supported.
>> 
>> Signed-off-by: Harald Freudenberger <freude@linux.ibm.com>
> 
> With the one comment applied:
> 
> Reviewed-by: Finn Callies <fcallies@linux.ibm.com>
> 
>> ---
>>   docs/system/s390x/cpacf.rst  | 116 
>> +++++++++++++++++++++++++++++++++++
>>   docs/system/target-s390x.rst |   1 +
>>   2 files changed, 117 insertions(+)
>>   create mode 100644 docs/system/s390x/cpacf.rst
>> 
>> diff --git a/docs/system/s390x/cpacf.rst b/docs/system/s390x/cpacf.rst
>> new file mode 100644
>> index 0000000000..85f35b4e9c
>> --- /dev/null
>> +++ b/docs/system/s390x/cpacf.rst
>> @@ -0,0 +1,116 @@
>> +CPACF Support
>> +=============
>> +
>> +CPACF
>> +-----
>> +
>> +CP Assist for Cryptographic Function (CPACF) is a hardware-integrated
>> +coprocessor feature built into every  processor core of IBM Z and
>> +LinuxONE mainframes (s390x architecture). It provides high-speed,
>> +hardware-accelerated encryption and hashing directly on the CPU.
>> +
>> +CPACF provides a set of z/Architecture instructions (known as Message
>> +Security Assist or MSA) that execute cryptographic operations
>> +synchronously with the main processor.
>> +
>> +- Symmetric Encryption: Support for AES (128, 192, 256-bit), DES, and
>> +  Triple-DES (TDES).
>> +- Hashing: Acceleration for SHA-1, SHA-2 (up to SHA-512), SHA-3 and
>> +  SHAKE.
>> +- Random Number Generation: Pseudo Random Number Generator (PRNG) and
>> +  a hardware-based True Random Number Generator (TRNG).
>> +- Asymmetric Support: Elliptic Curve Cryptography (ECC) primitives
>> +  P-256, P-384, P-521, Montgomery/Edwards curves (e.g., Ed25519).
>> +
>> +Documentation about CPACF instructions is public available and
>> +can be found in the "z/Architecture Principles of Operation"
>> +accessible at the IBM documentation hub https://www.ibm.com/docs/en.
>> +For example the latest version as a pdf is available here:
>> +https://www.ibm.com/support/pages/zvm/library/other/22783214.pdf
>> +
>> +
>> +CPACF instructions
>> +------------------
>> +
>> +Here is a list of implemented CPACF instructions and the supported
>> +functions for each instruction:
>> +
>> +KDSA (COMPUTE DIGITAL SIGNATURE AUTHENTICATION)
>> +- Function code 0x00 - Function Query
>> +
>> +KIMD (COMPUTE INTERMEDIATE MESSAGE DIGEST)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x02 - CPACF_KIMD_SHA_256
>> +- Function code 0x03 - CPACF_KIMD_SHA_512
>> +
>> +KLMD (COMPUTE LAST MESSAGE DIGEST)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x02 - CPACF_KLMD_SHA_256
>> +- Function code 0x03 - CPACF_KLMD_SHA_512
>> +
>> +KM (CIPHER MESSAGE)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x12 - CPACF_KM_AES_128
>> +- Function code 0x13 - CPACF_KM_AES_192
>> +- Function code 0x14 - CPACF_KM_AES_256
>> +- Function code 0x1a - CPACF_KM_PAES_128
>> +- Function code 0x1b - CPACF_KM_PAES_192
>> +- Function code 0x1c - CPACF_KM_PAES_256
>> +- Function code 0x32 - CPACF_KM_XTS_128
>> +- Function code 0x34 - CPACF_KM_XTS_256
>> +- Function code 0x3a - CPACF_KM_PXTS_128
>> +- Function code 0x3c - CPACF_KM_PXTS_256
>> +
>> +KMAC (COMPUTE MESSAGE AUTHENTICATION CODE)
>> +- Function code 0x00 - Function Query
>> +
>> +KMC (CIPHER MESSAGE WITH CHAINING)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x12 - CPACF_KMC_AES_128
>> +- Function code 0x13 - CPACF_KMC_AES_192
>> +- Function code 0x14 - CPACF_KMC_AES_256
>> +- Function code 0x1a - CPACF_KMC_PAES_128
>> +- Function code 0x1b - CPACF_KMC_PAES_192
>> +- Function code 0x1c - CPACF_KMC_PAES_256
>> +
>> +KMCTR (CIPHER MESSAGE WITH COUNTER)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x12 - CPACF_KMCTR_AES_128
>> +- Function code 0x13 - CPACF_KMCTR_AES_192
>> +- Function code 0x14 - CPACF_KMCTR_AES_256
>> +- Function code 0x1a - CPACF_KMCTR_PAES_128
>> +- Function code 0x1b - CPACF_KMCTR_PAES_192
>> +- Function code 0x1c - CPACF_KMCTR_PAES_256
>> +
>> +KMF (CIPHER MESSAGE WITH CIPHER FEEDBACK)
>> +- not supported
>> +
>> +KMO (CIPHER MESSAGE WITH OUTPUT FEEDBACK)
>> +- not supported
> 
> You list these as unsupported but KMA is missing completely. At least
> mention it as unsupported as well as you do so for KMO and KMF or
> leave the unsupported ones out completely.
> 

KMA is MSA 8. I am not sure if qemu even has configured some MSA 8.
I'll check this - but as of now all unknown instructions (and KMA is
one of this) would result in a Operation Exception. However, at least
KMA shold be listed then below. I'll check this maybe add KMA query
support or at least document it here.

Update: MSA 8 is listed in qemu. So i added KMA to the docu.

>> +
>> +PCC (PERFORM CRYPTOGRAPHIC COMPUTATION)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x32 - compute XTS param AES-128
>> +- Function code 0x34 - compute XTS param AES-256
>> +- Function code 0x3a - compute XTS param Encrypted AES-128
>> +- Function code 0x3c - compute XTS param Encrypted AES-256
>> +
>> +PCKMO (PERFORM CRYPTOGRAPHIC KEY MANAGEMENT OPERATION)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x12 - CPACF_PCKMO_ENC_AES_128_KEY
>> +- Function code 0x13 - CPACF_PCKMO_ENC_AES_192_KEY
>> +- Function code 0x14 - CPACF_PCKMO_ENC_AES_256_KEY
>> +
>> +PRNO (PERFORM RANDOM NUMBER OPERATION)
>> +- Function code 0x00 - Function Query
>> +- Function code 0x72 - CPACF_PRNO_TRNG
>> +
>> +Note that the use of a not supported CPACF instruction (KMF and KMO)
>> +or invocation of a not listed function will result in a Specification
>> +Exception.
>> +
>> +Not listed CPACF instructions (KMF, KMO) cause an Operation Exception

                                    ^^^ here I added KMA

>> +when used. Not listed functions cause a Specification Exception when
>> +called. If only the query function is listed (KDSA), then the query
>> +function will return a function status word with all but the query
>> +function bit set to 0.
>> diff --git a/docs/system/target-s390x.rst 
>> b/docs/system/target-s390x.rst
>> index 94c981e732..49159826eb 100644
>> --- a/docs/system/target-s390x.rst
>> +++ b/docs/system/target-s390x.rst
>> @@ -35,3 +35,4 @@ Architectural features
>>      s390x/bootdevices
>>      s390x/protvirt
>>      s390x/cpu-topology
>> +   s390x/cpacf