From patchwork Mon Dec 19 18:55:48 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Elliott, Robert \(Servers\)" X-Patchwork-Id: 635199 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6C01EC46467 for ; Mon, 19 Dec 2022 18:56:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232487AbiLSS4N (ORCPT ); Mon, 19 Dec 2022 13:56:13 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58272 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232418AbiLSS4M (ORCPT ); Mon, 19 Dec 2022 13:56:12 -0500 Received: from mx0a-002e3701.pphosted.com (mx0a-002e3701.pphosted.com [148.163.147.86]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 24DFFE63; Mon, 19 Dec 2022 10:56:09 -0800 (PST) Received: from pps.filterd (m0150242.ppops.net [127.0.0.1]) by mx0a-002e3701.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 2BJH00AA028051; Mon, 19 Dec 2022 18:56:07 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hpe.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding; s=pps0720; bh=MJlOfE47OEK7Nr+TCmJks+g4mTnzxIIzTO+0fssVP0Q=; b=ZXJAvgordKbg3K5Tb3c2PNC2/vRj81pS7iZB+/HT66g+BuOyiIEN2ZttI/r/wBGuTPPr KM/Q/g+HBZpOcUDSss+zyVCXEXmO8Wf1L95XQLkf34SVNlRMUjCHaA+1lmAueApbF03x VYEp+T/ZXFPuN6FNtrLbIJgAGKX+niiMpv414XpIFqF0agM52dxAqswaPH94qa0r9hi2 gmMDDWQwoTRr40trnsVBM0o5t4qb6a0rvVe7/2KuvAgXK7SGdoZoELVrhnl3MtRDXRLe agvmtQMAWQQ7ecmKFVjERjPVQ0Dsyi4IaIPMrR86IC3oMpyUTDHgUEJyiI4sAxGKTWus Fg== Received: from p1lg14878.it.hpe.com (p1lg14878.it.hpe.com [16.230.97.204]) by mx0a-002e3701.pphosted.com (PPS) with ESMTPS id 3mjuy6gtw5-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 19 Dec 2022 18:56:06 +0000 Received: from p1lg14885.dc01.its.hpecorp.net (unknown [10.119.18.236]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by p1lg14878.it.hpe.com (Postfix) with ESMTPS id 36B393DE38; Mon, 19 Dec 2022 18:56:06 +0000 (UTC) Received: from adevxp033-sys.us.rdlabs.hpecorp.net (unknown [16.231.227.36]) by p1lg14885.dc01.its.hpecorp.net (Postfix) with ESMTP id DC0FE80576E; Mon, 19 Dec 2022 18:56:05 +0000 (UTC) From: Robert Elliott To: herbert@gondor.apana.org.au, davem@davemloft.net, corbet@lwn.net, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Robert Elliott Subject: [PATCH v2 1/8] crypto: clean up kernel-doc headers Date: Mon, 19 Dec 2022 12:55:48 -0600 Message-Id: <20221219185555.433233-2-elliott@hpe.com> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221219185555.433233-1-elliott@hpe.com> References: <20221215063857.161665-1-elliott@hpe.com> <20221219185555.433233-1-elliott@hpe.com> MIME-Version: 1.0 X-Proofpoint-ORIG-GUID: LmiWIBayCUGeBLZKt55bA_vs9ga5R1b6 X-Proofpoint-GUID: LmiWIBayCUGeBLZKt55bA_vs9ga5R1b6 X-HPE-SCL: -1 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.923,Hydra:6.0.545,FMLib:17.11.122.1 definitions=2022-12-19_01,2022-12-15_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 adultscore=0 bulkscore=0 clxscore=1015 mlxscore=0 phishscore=0 spamscore=0 impostorscore=0 mlxlogscore=999 lowpriorityscore=0 suspectscore=0 malwarescore=0 priorityscore=1501 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2212070000 definitions=main-2212190168 Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org Fix these problems in the kernel-doc function header comments, as reported by running: scripts/kernel-doc -man \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | scripts/split-man.pl /tmp/man 2> err.log cat err.log | grep crypto | grep -v drivers arch/mips/cavium-octeon/crypto/octeon-crypto.c:18: warning: This comment starts with '/**', but isn't a kernel-doc comment. arch/mips/cavium-octeon/crypto/octeon-crypto.c:50: warning: This comment starts with '/**', but isn't a kernel-doc comment. arch/mips/cavium-octeon/crypto/octeon-crypto.c:60: warning: Function parameter or member 'crypto_flags' not described in 'octeon_crypto_disable' arch/mips/cavium-octeon/crypto/octeon-crypto.c:60: warning: Excess function parameter 'flags' description in 'octeon_crypto_disable' crypto/asymmetric_keys/verify_pefile.c:420: warning: Function parameter or member 'trusted_keys' not described in 'verify_pefile_signature' crypto/asymmetric_keys/verify_pefile.c:420: warning: Excess function parameter 'trust_keys' description in 'verify_pefile_signature' crypto/async_tx/async_pq.c:19: warning: cannot understand function prototype: 'struct page *pq_scribble_page; ' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'chan' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'scfs' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'disks' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'unmap' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'dma_flags' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:40: warning: Function parameter or member 'submit' not described in 'do_async_gen_syndrome' crypto/async_tx/async_pq.c:109: warning: Function parameter or member 'blocks' not described in 'do_sync_gen_syndrome' crypto/async_tx/async_pq.c:109: warning: Function parameter or member 'offsets' not described in 'do_sync_gen_syndrome' crypto/async_tx/async_pq.c:109: warning: Function parameter or member 'disks' not described in 'do_sync_gen_syndrome' crypto/async_tx/async_pq.c:109: warning: Function parameter or member 'len' not described in 'do_sync_gen_syndrome' crypto/async_tx/async_pq.c:109: warning: Function parameter or member 'submit' not described in 'do_sync_gen_syndrome' crypto/async_tx/async_pq.c:302: warning: Excess function parameter 'offset' description in 'async_syndrome_val' crypto/async_tx/async_tx.c:137: warning: cannot understand function prototype: 'enum submit_disposition ' crypto/async_tx/async_tx.c:265: warning: Function parameter or member 'tx' not described in 'async_tx_quiesce' crypto/crypto_engine.c:514: warning: Excess function parameter 'engine' description in 'crypto_engine_alloc_init_and_set' include/crypto/acompress.h:219: warning: Function parameter or member 'cmpl' not described in 'acomp_request_set_callback' include/crypto/acompress.h:219: warning: Excess function parameter 'cmlp' description in 'acomp_request_set_callback' include/crypto/des.h:43: warning: Function parameter or member 'keylen' not described in 'des_expand_key' include/crypto/des.h:43: warning: Excess function parameter 'len' description in 'des_expand_key' include/crypto/des.h:56: warning: Function parameter or member 'keylen' not described in 'des3_ede_expand_key' include/crypto/des.h:56: warning: Excess function parameter 'len' description in 'des3_ede_expand_key' include/crypto/if_alg.h:160: warning: Function parameter or member 'wait' not described in 'af_alg_ctx' include/crypto/if_alg.h:178: warning: This comment starts with '/**', but isn't a kernel-doc comment. include/crypto/if_alg.h:193: warning: This comment starts with '/**', but isn't a kernel-doc comment. include/crypto/if_alg.h:204: warning: This comment starts with '/**', but isn't a kernel-doc comment. include/crypto/if_alg.h:219: warning: This comment starts with '/**', but isn't a kernel-doc comment. include/crypto/if_alg.h:184: warning: Function parameter or member 'sk' not described in 'af_alg_sndbuf' include/crypto/if_alg.h:199: warning: Function parameter or member 'sk' not described in 'af_alg_writable' include/crypto/if_alg.h:210: warning: Function parameter or member 'sk' not described in 'af_alg_rcvbuf' include/crypto/if_alg.h:225: warning: Function parameter or member 'sk' not described in 'af_alg_readable' include/crypto/internal/ecc.h:85: warning: Function parameter or member 'privkey' not described in 'ecc_gen_privkey' include/crypto/internal/ecc.h:85: warning: Excess function parameter 'private_key' description in 'ecc_gen_privkey' include/crypto/internal/ecc.h:184: warning: Function parameter or member 'right' not described in 'vli_sub' include/crypto/internal/ecc.h:246: warning: expecting prototype for ecc_aloc_point(). Prototype was for ecc_alloc_point() instead include/crypto/internal/ecc.h:262: warning: Function parameter or member 'point' not described in 'ecc_point_is_zero' include/crypto/internal/ecc.h:262: warning: Excess function parameter 'p' description in 'ecc_point_is_zero' include/crypto/internal/rsa.h:32: warning: cannot understand function prototype: 'struct rsa_key ' include/crypto/kdf_sp800108.h:34: warning: Function parameter or member 'kmd' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:34: warning: Function parameter or member 'info' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:34: warning: Function parameter or member 'info_nvec' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:34: warning: Function parameter or member 'dst' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:34: warning: Function parameter or member 'dlen' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:34: warning: expecting prototype for Counter KDF generate operation according to SP800(). Prototype was for crypto_kdf108_ctr_generate() instead include/crypto/kdf_sp800108.h:37: warning: This comment starts with '/**', but isn't a kernel-doc comment. include/crypto/kdf_sp800108.h:37: warning: Function parameter or member 'info_nvec' not described in 'crypto_kdf108_ctr_generate' include/crypto/kdf_sp800108.h:37: warning: Excess function parameter 'info_vec' description in 'crypto_kdf108_ctr_generate' Signed-off-by: Robert Elliott --- .../mips/cavium-octeon/crypto/octeon-crypto.c | 19 ++++----- crypto/asymmetric_keys/verify_pefile.c | 2 +- crypto/async_tx/async_pq.c | 11 +++--- crypto/async_tx/async_tx.c | 4 +- crypto/crypto_engine.c | 2 +- include/crypto/acompress.h | 2 +- include/crypto/des.h | 4 +- include/crypto/if_alg.h | 26 ++++++------- include/crypto/internal/ecc.h | 8 ++-- include/crypto/internal/rsa.h | 2 +- include/crypto/kdf_sp800108.h | 39 +++++++++++-------- 11 files changed, 62 insertions(+), 57 deletions(-) diff --git a/arch/mips/cavium-octeon/crypto/octeon-crypto.c b/arch/mips/cavium-octeon/crypto/octeon-crypto.c index cfb4a146cf17..c4badbf756b5 100644 --- a/arch/mips/cavium-octeon/crypto/octeon-crypto.c +++ b/arch/mips/cavium-octeon/crypto/octeon-crypto.c @@ -14,10 +14,11 @@ #include "octeon-crypto.h" /** - * Enable access to Octeon's COP2 crypto hardware for kernel use. Wrap any - * crypto operations in calls to octeon_crypto_enable/disable in order to make - * sure the state of COP2 isn't corrupted if userspace is also performing - * hardware crypto operations. Allocate the state parameter on the stack. + * octeon_crypto_enable - Enable access to Octeon's COP2 crypto hardware for kernel use. + * Wrap any crypto operations in calls to octeon_crypto_enable/disable + * in order to make sure the state of COP2 isn't corrupted if userspace + * is also performing hardware crypto operations. + * Allocate the state parameter on the stack. * Returns with preemption disabled. * * @state: Pointer to state structure to store current COP2 state in. @@ -46,12 +47,12 @@ unsigned long octeon_crypto_enable(struct octeon_cop2_state *state) EXPORT_SYMBOL_GPL(octeon_crypto_enable); /** - * Disable access to Octeon's COP2 crypto hardware in the kernel. This must be - * called after an octeon_crypto_enable() before any context switch or return to - * userspace. + * octeon_crypto_disable - Disable access to Octeon's COP2 crypto hardware in the kernel. + * This must be called after an octeon_crypto_enable() before any + * context switch or return to userspace. * - * @state: Pointer to COP2 state to restore - * @flags: Return value from octeon_crypto_enable() + * @state: Pointer to COP2 state to restore + * @crypto_flags: Return value from octeon_crypto_enable() */ void octeon_crypto_disable(struct octeon_cop2_state *state, unsigned long crypto_flags) diff --git a/crypto/asymmetric_keys/verify_pefile.c b/crypto/asymmetric_keys/verify_pefile.c index 7553ab18db89..148cad70fe79 100644 --- a/crypto/asymmetric_keys/verify_pefile.c +++ b/crypto/asymmetric_keys/verify_pefile.c @@ -387,7 +387,7 @@ static int pefile_digest_pe(const void *pebuf, unsigned int pelen, * verify_pefile_signature - Verify the signature on a PE binary image * @pebuf: Buffer containing the PE binary image * @pelen: Length of the binary image - * @trust_keys: Signing certificate(s) to use as starting points + * @trusted_keys: Signing certificate(s) to use as starting points * @usage: The use to which the key is being put. * * Validate that the certificate chain inside the PKCS#7 message inside the PE diff --git a/crypto/async_tx/async_pq.c b/crypto/async_tx/async_pq.c index f9cdc5e91664..c95908d70f7e 100644 --- a/crypto/async_tx/async_pq.c +++ b/crypto/async_tx/async_pq.c @@ -11,9 +11,8 @@ #include #include -/** - * pq_scribble_page - space to hold throwaway P or Q buffer for - * synchronous gen_syndrome +/* + * space to hold throwaway P or Q buffer for synchronous gen_syndrome */ static struct page *pq_scribble_page; @@ -28,7 +27,7 @@ static struct page *pq_scribble_page; #define MAX_DISKS 255 -/** +/* * do_async_gen_syndrome - asynchronously calculate P and/or Q */ static __async_inline struct dma_async_tx_descriptor * @@ -100,7 +99,7 @@ do_async_gen_syndrome(struct dma_chan *chan, return tx; } -/** +/* * do_sync_gen_syndrome - synchronously calculate a raid6 syndrome */ static void @@ -281,7 +280,7 @@ pq_val_chan(struct async_submit_ctl *submit, struct page **blocks, int disks, si /** * async_syndrome_val - asynchronously validate a raid6 syndrome * @blocks: source blocks from idx 0..disks-3, P @ disks-2 and Q @ disks-1 - * @offset: common offset into each block (src and dest) to start transaction + * @offsets: common offset into each block (src and dest) to start transaction * @disks: number of blocks (including missing P or Q, see below) * @len: length of operation in bytes * @pqres: on val failure SUM_CHECK_P_RESULT and/or SUM_CHECK_Q_RESULT are set diff --git a/crypto/async_tx/async_tx.c b/crypto/async_tx/async_tx.c index 9256934312d7..ad72057a5e0d 100644 --- a/crypto/async_tx/async_tx.c +++ b/crypto/async_tx/async_tx.c @@ -124,7 +124,7 @@ async_tx_channel_switch(struct dma_async_tx_descriptor *depend_tx, /** - * submit_disposition - flags for routing an incoming operation + * enum submit_disposition - flags for routing an incoming operation * @ASYNC_TX_SUBMITTED: we were able to append the new operation under the lock * @ASYNC_TX_CHANNEL_SWITCH: when the lock is dropped schedule a channel switch * @ASYNC_TX_DIRECT_SUBMIT: when the lock is dropped submit directly @@ -258,7 +258,7 @@ EXPORT_SYMBOL_GPL(async_trigger_callback); /** * async_tx_quiesce - ensure tx is complete and freeable upon return - * @tx - transaction to quiesce + * @tx: transaction to quiesce */ void async_tx_quiesce(struct dma_async_tx_descriptor **tx) { diff --git a/crypto/crypto_engine.c b/crypto/crypto_engine.c index bb8e77077f02..64dc9aa3ca24 100644 --- a/crypto/crypto_engine.c +++ b/crypto/crypto_engine.c @@ -499,7 +499,7 @@ EXPORT_SYMBOL_GPL(crypto_engine_stop); * This has the form: * callback(struct crypto_engine *engine) * where: - * @engine: the crypto engine structure. + * engine: the crypto engine structure. * @rt: whether this queue is set to run as a realtime task * @qlen: maximum size of the crypto-engine queue * diff --git a/include/crypto/acompress.h b/include/crypto/acompress.h index e4bc96528902..77870c3aeec5 100644 --- a/include/crypto/acompress.h +++ b/include/crypto/acompress.h @@ -209,7 +209,7 @@ void acomp_request_free(struct acomp_req *req); * * @req: request that the callback will be set for * @flgs: specify for instance if the operation may backlog - * @cmlp: callback which will be called + * @cmpl: callback which will be called * @data: private data used by the caller */ static inline void acomp_request_set_callback(struct acomp_req *req, diff --git a/include/crypto/des.h b/include/crypto/des.h index 7812b4331ae4..2fcc72988843 100644 --- a/include/crypto/des.h +++ b/include/crypto/des.h @@ -34,7 +34,7 @@ void des3_ede_decrypt(const struct des3_ede_ctx *dctx, u8 *dst, const u8 *src); * des_expand_key - Expand a DES input key into a key schedule * @ctx: the key schedule * @key: buffer containing the input key - * @len: size of the buffer contents + * @keylen: size of the buffer contents * * Returns 0 on success, -EINVAL if the input key is rejected and -ENOKEY if * the key is accepted but has been found to be weak. @@ -45,7 +45,7 @@ int des_expand_key(struct des_ctx *ctx, const u8 *key, unsigned int keylen); * des3_ede_expand_key - Expand a triple DES input key into a key schedule * @ctx: the key schedule * @key: buffer containing the input key - * @len: size of the buffer contents + * @keylen: size of the buffer contents * * Returns 0 on success, -EINVAL if the input key is rejected and -ENOKEY if * the key is accepted but has been found to be weak. Note that weak keys will diff --git a/include/crypto/if_alg.h b/include/crypto/if_alg.h index a5db86670bdf..da66314d9bc7 100644 --- a/include/crypto/if_alg.h +++ b/include/crypto/if_alg.h @@ -124,7 +124,7 @@ struct af_alg_async_req { * @tsgl_list: Link to TX SGL * @iv: IV for cipher operation * @aead_assoclen: Length of AAD for AEAD cipher operations - * @completion: Work queue for synchronous operation + * @wait: helper structure for async operation * @used: TX bytes sent to kernel. This variable is used to * ensure that user space cannot cause the kernel * to allocate too much memory in sendmsg operation. @@ -174,10 +174,10 @@ static inline struct alg_sock *alg_sk(struct sock *sk) } /** - * Size of available buffer for sending data from user space to kernel. + * af_alg_sndbuf - Size of available buffer for sending data from user space to kernel. * - * @sk socket of connection to user space - * @return number of bytes still available + * @sk: socket of connection to user space + * @return: number of bytes still available */ static inline int af_alg_sndbuf(struct sock *sk) { @@ -189,10 +189,10 @@ static inline int af_alg_sndbuf(struct sock *sk) } /** - * Can the send buffer still be written to? + * af_alg_writable - Can the send buffer still be written to? * - * @sk socket of connection to user space - * @return true => writable, false => not writable + * @sk: socket of connection to user space + * @return: true => writable, false => not writable */ static inline bool af_alg_writable(struct sock *sk) { @@ -200,10 +200,10 @@ static inline bool af_alg_writable(struct sock *sk) } /** - * Size of available buffer used by kernel for the RX user space operation. + * af_alg_rcvbuf - Size of available buffer used by kernel for the RX user space operation. * - * @sk socket of connection to user space - * @return number of bytes still available + * @sk: socket of connection to user space + * @return: number of bytes still available */ static inline int af_alg_rcvbuf(struct sock *sk) { @@ -215,10 +215,10 @@ static inline int af_alg_rcvbuf(struct sock *sk) } /** - * Can the RX buffer still be written to? + * af_alg_readable - Can the RX buffer still be written to? * - * @sk socket of connection to user space - * @return true => writable, false => not writable + * @sk: socket of connection to user space + * @return: true => writable, false => not writable */ static inline bool af_alg_readable(struct sock *sk) { diff --git a/include/crypto/internal/ecc.h b/include/crypto/internal/ecc.h index 4f6c1a68882f..4b8155fea03c 100644 --- a/include/crypto/internal/ecc.h +++ b/include/crypto/internal/ecc.h @@ -76,7 +76,7 @@ int ecc_is_key_valid(unsigned int curve_id, unsigned int ndigits, * point G. * @curve_id: id representing the curve to use * @ndigits: curve number of digits - * @private_key: buffer for storing the generated private key + * @privkey: buffer for storing the generated private key * * Returns 0 if the private key was generated successfully, a negative value * if an error occurred. @@ -172,7 +172,7 @@ int vli_cmp(const u64 *left, const u64 *right, unsigned int ndigits); * * @result: where to write result * @left: vli - * @right vli + * @right: vli * @ndigits: length of all vlis * * Note: can modify in-place. @@ -236,7 +236,7 @@ void vli_mod_mult_slow(u64 *result, const u64 *left, const u64 *right, unsigned int vli_num_bits(const u64 *vli, unsigned int ndigits); /** - * ecc_aloc_point() - Allocate ECC point. + * ecc_alloc_point() - Allocate ECC point. * * @ndigits: Length of vlis in u64 qwords. * @@ -254,7 +254,7 @@ void ecc_free_point(struct ecc_point *p); /** * ecc_point_is_zero() - Check if point is zero. * - * @p: Point to check for zero. + * @point: Point to check for zero. * * Return: true if point is the point at infinity, false otherwise. */ diff --git a/include/crypto/internal/rsa.h b/include/crypto/internal/rsa.h index e870133f4b77..78a7544aaa11 100644 --- a/include/crypto/internal/rsa.h +++ b/include/crypto/internal/rsa.h @@ -10,7 +10,7 @@ #include /** - * rsa_key - RSA key structure + * struct rsa_key - RSA key structure * @n : RSA modulus raw byte stream * @e : RSA public exponent raw byte stream * @d : RSA private exponent raw byte stream diff --git a/include/crypto/kdf_sp800108.h b/include/crypto/kdf_sp800108.h index b7b20a778fb7..1c16343cd3fd 100644 --- a/include/crypto/kdf_sp800108.h +++ b/include/crypto/kdf_sp800108.h @@ -11,17 +11,20 @@ #include /** - * Counter KDF generate operation according to SP800-108 section 5.1 - * as well as SP800-56A section 5.8.1 (Single-step KDF). + * crypto_kdf108_ctr_generate - Counter KDF generate operation + * according to SP800-108 section 5.1 + * as well as SP800-56A section 5.8.1 + * (Single-step KDF). * - * @kmd Keyed message digest whose key was set with crypto_kdf108_setkey or - * unkeyed message digest - * @info optional context and application specific information - this may be - * NULL - * @info_vec number of optional context/application specific information entries - * @dst destination buffer that the caller already allocated - * @dlen length of the destination buffer - the KDF derives that amount of - * bytes. + * @kmd: Keyed message digest whose key was set with + * crypto_kdf108_setkey or unkeyed message digest + * @info: optional context and application specific information - + * this may be NULL + * @info_nvec: number of optional context/application specific + * information entries + * @dst: destination buffer that the caller already allocated + * @dlen: length of the destination buffer - + * the KDF derives that amount of bytes. * * To comply with SP800-108, the caller must provide Label || 0x00 || Context * in the info parameter. @@ -33,14 +36,16 @@ int crypto_kdf108_ctr_generate(struct crypto_shash *kmd, u8 *dst, unsigned int dlen); /** - * Counter KDF setkey operation + * crypto_kdf108_setkey - Counter KDF setkey operation * - * @kmd Keyed message digest allocated by the caller. The key should not have - * been set. - * @key Seed key to be used to initialize the keyed message digest context. - * @keylen This length of the key buffer. - * @ikm The SP800-108 KDF does not support IKM - this parameter must be NULL - * @ikmlen This parameter must be 0. + * @kmd: Keyed message digest allocated by the caller. + * The key should not have been set. + * @key: Seed key to be used to initialize the + * keyed message digest context. + * @keylen: This length of the key buffer. + * @ikm: The SP800-108 KDF does not support IKM - + * this parameter must be NULL + * @ikmlen: This parameter must be 0. * * According to SP800-108 section 7.2, the seed key must be at least as large as * the message digest size of the used keyed message digest. This limitation From patchwork Mon Dec 19 18:55:50 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Elliott, Robert \(Servers\)" X-Patchwork-Id: 635198 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1DA61C4167B for ; Mon, 19 Dec 2022 18:56:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232207AbiLSS4P (ORCPT ); Mon, 19 Dec 2022 13:56:15 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58276 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232450AbiLSS4M (ORCPT ); Mon, 19 Dec 2022 13:56:12 -0500 Received: from mx0a-002e3701.pphosted.com (mx0a-002e3701.pphosted.com [148.163.147.86]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4D18B116C; Mon, 19 Dec 2022 10:56:11 -0800 (PST) Received: from pps.filterd (m0134422.ppops.net [127.0.0.1]) by mx0b-002e3701.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 2BJH3euU014446; Mon, 19 Dec 2022 18:56:09 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hpe.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : content-transfer-encoding : mime-version; s=pps0720; bh=8FA3FxXvzP85Tyc60clcbxamA7EKbj9xp+cOAvqH1Gk=; b=BPLigiVU8NBMFX0KpLG5BeBfcgnffivTVuqg2+8h2rmE5GjjZk0IUzXGNjdTz1ewIiH2 NXx3ysbORClYp4NmhDQDJ52i20/t0b9KpWv7AgvksZXsUZ6z6+LlXtpHsmO+1DBUOJrP XoGCJ52omN8oC44qavS/H4/9X0Wcg4RkxO72o+5aIF0ZjqiOk/hx71tk71l6k95y1NyW FCyJItmoUgv06fnCmdmMiivkpgoNgQ5Qkau3M8fBoqTNIWH4u4Fv+mVyShf8Jq2ouU4T e6D5rYor8k8jWfxjw4UBJOImxXZ1UIbWFXrM/Ge3Xs+5s/+tNo6dFX9GNkgF92Ub+JMJ nQ== Received: from p1lg14881.it.hpe.com (p1lg14881.it.hpe.com [16.230.97.202]) by mx0b-002e3701.pphosted.com (PPS) with ESMTPS id 3mjv170rv5-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 19 Dec 2022 18:56:09 +0000 Received: from p1lg14885.dc01.its.hpecorp.net (unknown [10.119.18.236]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by p1lg14881.it.hpe.com (Postfix) with ESMTPS id 8EFE3801716; Mon, 19 Dec 2022 18:56:08 +0000 (UTC) Received: from adevxp033-sys.us.rdlabs.hpecorp.net (unknown [16.231.227.36]) by p1lg14885.dc01.its.hpecorp.net (Postfix) with ESMTP id 3C8648064AD; Mon, 19 Dec 2022 18:56:08 +0000 (UTC) From: Robert Elliott To: herbert@gondor.apana.org.au, davem@davemloft.net, corbet@lwn.net, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Robert Elliott Subject: [PATCH v2 3/8] crypto: x86/sha - add kernel-doc comments to assembly Date: Mon, 19 Dec 2022 12:55:50 -0600 Message-Id: <20221219185555.433233-4-elliott@hpe.com> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221219185555.433233-1-elliott@hpe.com> References: <20221215063857.161665-1-elliott@hpe.com> <20221219185555.433233-1-elliott@hpe.com> X-Proofpoint-ORIG-GUID: ELYJj3z1ovArVi_fBVKcgkiPZqaxBw4v X-Proofpoint-GUID: ELYJj3z1ovArVi_fBVKcgkiPZqaxBw4v X-Proofpoint-UnRewURL: 0 URL was un-rewritten MIME-Version: 1.0 X-HPE-SCL: -1 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.923,Hydra:6.0.545,FMLib:17.11.122.1 definitions=2022-12-19_01,2022-12-15_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 malwarescore=0 clxscore=1015 impostorscore=0 adultscore=0 suspectscore=0 mlxscore=0 lowpriorityscore=0 mlxlogscore=999 priorityscore=1501 phishscore=0 spamscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2212070000 definitions=main-2212190168 Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org Add kernel-doc comments for assembly language functions exported to C glue code. Remove .align directives that are overridden by SYM_FUNC_START (which includes .align 4). Signed-off-by: Robert Elliott --- arch/x86/crypto/sha1_avx2_x86_64_asm.S | 32 +++++++++++------------ arch/x86/crypto/sha1_ni_asm.S | 19 ++++++++------ arch/x86/crypto/sha1_ssse3_asm.S | 33 +++++++++++++++-------- arch/x86/crypto/sha256-avx-asm.S | 23 ++++++++++------ arch/x86/crypto/sha256-avx2-asm.S | 24 +++++++++++------ arch/x86/crypto/sha256-ssse3-asm.S | 25 +++++++++++------- arch/x86/crypto/sha256_ni_asm.S | 22 +++++++++------- arch/x86/crypto/sha512-avx-asm.S | 33 +++++++++++------------ arch/x86/crypto/sha512-avx2-asm.S | 34 ++++++++++++------------ arch/x86/crypto/sha512-ssse3-asm.S | 36 ++++++++++++-------------- 10 files changed, 159 insertions(+), 122 deletions(-) diff --git a/arch/x86/crypto/sha1_avx2_x86_64_asm.S b/arch/x86/crypto/sha1_avx2_x86_64_asm.S index a96b2fd26dab..c3ee9334cb0f 100644 --- a/arch/x86/crypto/sha1_avx2_x86_64_asm.S +++ b/arch/x86/crypto/sha1_avx2_x86_64_asm.S @@ -62,11 +62,6 @@ *Visit http://software.intel.com/en-us/articles/ *and refer to improving-the-performance-of-the-secure-hash-algorithm-1/ * - *Updates 20-byte SHA-1 record at start of 'state', from 'input', for - *even number of 'blocks' consecutive 64-byte blocks. - * - *extern "C" void sha1_transform_avx2( - * struct sha1_state *state, const u8* input, int blocks ); */ #include @@ -629,13 +624,22 @@ _loop3: _end: .endm -/* - * macro implements SHA-1 function's body for several 64-byte blocks - * param: function's name - */ -.macro SHA1_VECTOR_ASM name - SYM_FUNC_START(\name) +.text + +/** + * sha1_transform_avx2 - Calculate SHA1 hash using the x86 AVX2 feature set + * @digest: address of current 20-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, BUF macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, CNT macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha1_transform_avx2(u32 *digest, const u8 *data, int blocks) + */ +SYM_FUNC_START(sha1_transform_avx2) push %rbx push %r12 push %r13 @@ -675,9 +679,7 @@ _loop3: pop %rbx RET - - SYM_FUNC_END(\name) -.endm +SYM_FUNC_END(sha1_transform_avx2) .section .rodata @@ -706,6 +708,4 @@ BSWAP_SHUFB_CTL: .long 0x04050607 .long 0x08090a0b .long 0x0c0d0e0f -.text -SHA1_VECTOR_ASM sha1_transform_avx2 diff --git a/arch/x86/crypto/sha1_ni_asm.S b/arch/x86/crypto/sha1_ni_asm.S index cade913d4882..a69595b033c8 100644 --- a/arch/x86/crypto/sha1_ni_asm.S +++ b/arch/x86/crypto/sha1_ni_asm.S @@ -72,9 +72,16 @@ #define MSG3 %xmm6 #define SHUF_MASK %xmm7 +.text -/* - * Intel SHA Extensions optimized implementation of a SHA-1 update function +/** + * sha1_ni_transform - Calculate SHA1 hash using the x86 SHA-NI feature set + * @digest: address of current 20-byte hash value (%rdi, DIGEST_PTR macro) + * @data: address of data (%rsi, DATA_PTR macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. * * The function takes a pointer to the current hash values, a pointer to the * input data, and a number of 64 byte blocks to process. Once all blocks have @@ -86,13 +93,9 @@ * The indented lines in the loop are instructions related to rounds processing. * The non-indented lines are instructions related to the message schedule. * - * void sha1_ni_transform(uint32_t *digest, const void *data, - uint32_t numBlocks) - * digest : pointer to digest - * data: pointer to input data - * numBlocks: Number of blocks to process + * Return: none + * Prototype: asmlinkage void sha1_ni_transform(u32 *digest, const u8 *data, int blocks) */ -.text SYM_TYPED_FUNC_START(sha1_ni_transform) push %rbp mov %rsp, %rbp diff --git a/arch/x86/crypto/sha1_ssse3_asm.S b/arch/x86/crypto/sha1_ssse3_asm.S index f54988c80eb4..1472fe35dfae 100644 --- a/arch/x86/crypto/sha1_ssse3_asm.S +++ b/arch/x86/crypto/sha1_ssse3_asm.S @@ -451,20 +451,24 @@ BSWAP_SHUFB_CTL: .long 0x0c0d0e0f -.section .text - W_PRECALC_SSSE3 .macro xmm_mov a, b movdqu \a,\b .endm -/* - * SSSE3 optimized implementation: +.text + +/** + * sha1_transform_ssse3 - Calculate SHA1 hash using the x86 SSSE3 feature set + * @digest: address of current 20-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, BUF macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, CNT macro) * - * extern "C" void sha1_transform_ssse3(struct sha1_state *state, - * const u8 *data, int blocks); + * This function supports 64-bit CPUs. * - * Note that struct sha1_state is assumed to begin with u32 state[5]. + * Return: none + * Prototype: asmlinkage void sha1_transform_ssse3(u32 *digest, const u8 *data, int blocks) */ SHA1_VECTOR_ASM sha1_transform_ssse3 @@ -546,9 +550,16 @@ W_PRECALC_AVX vmovdqu \a,\b .endm - -/* AVX optimized implementation: - * extern "C" void sha1_transform_avx(struct sha1_state *state, - * const u8 *data, int blocks); +/** + * sha1_transform_avx - Calculate SHA1 hash using the x86 AVX feature set + * @digest: address of current 20-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, BUF macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, CNT macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha1_transform_avx(u32 *digest, const u8 *data, int blocks) */ SHA1_VECTOR_ASM sha1_transform_avx diff --git a/arch/x86/crypto/sha256-avx-asm.S b/arch/x86/crypto/sha256-avx-asm.S index 5555b5d5215a..73615c5bbb5f 100644 --- a/arch/x86/crypto/sha256-avx-asm.S +++ b/arch/x86/crypto/sha256-avx-asm.S @@ -95,9 +95,9 @@ SHUF_00BA = %xmm10 # shuffle xBxA -> 00BA SHUF_DC00 = %xmm12 # shuffle xDxC -> DC00 BYTE_FLIP_MASK = %xmm13 -NUM_BLKS = %rdx # 3rd arg -INP = %rsi # 2nd arg CTX = %rdi # 1st arg +INP = %rsi # 2nd arg +NUM_BLKS = %rdx # 3rd arg SRND = %rsi # clobbers INP c = %ecx @@ -340,13 +340,20 @@ a = TMP_ ROTATE_ARGS .endm -######################################################################## -## void sha256_transform_avx(state sha256_state *state, const u8 *data, int blocks) -## arg 1 : pointer to state -## arg 2 : pointer to input data -## arg 3 : Num blocks -######################################################################## .text + +/** + * sha256_transform_avx - Calculate SHA256 hash using the x86 AVX feature set + * @digest: address of current 32-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, INP macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha256_transform_avx(u32 *digest, const u8 *data, int blocks) + */ SYM_TYPED_FUNC_START(sha256_transform_avx) pushq %rbx pushq %r12 diff --git a/arch/x86/crypto/sha256-avx2-asm.S b/arch/x86/crypto/sha256-avx2-asm.S index 3eada9416852..73cbe0322e7d 100644 --- a/arch/x86/crypto/sha256-avx2-asm.S +++ b/arch/x86/crypto/sha256-avx2-asm.S @@ -90,9 +90,9 @@ BYTE_FLIP_MASK = %ymm13 X_BYTE_FLIP_MASK = %xmm13 # XMM version of BYTE_FLIP_MASK -NUM_BLKS = %rdx # 3rd arg -INP = %rsi # 2nd arg CTX = %rdi # 1st arg +INP = %rsi # 2nd arg +NUM_BLKS = %rdx # 3rd arg c = %ecx d = %r8d e = %edx # clobbers NUM_BLKS @@ -517,13 +517,21 @@ STACK_SIZE = _CTX + _CTX_SIZE .endm -######################################################################## -## void sha256_transform_rorx(struct sha256_state *state, const u8 *data, int blocks) -## arg 1 : pointer to state -## arg 2 : pointer to input data -## arg 3 : Num blocks -######################################################################## .text + +/** + * sha256_transform_rorx - Calculate SHA512 hash using x86 AVX2 feature set + * including the RORX (rotate right logical without affecting flags) instruction + * @digest: address of current 32-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, INP macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha256_transform_rorx(u32 *digest, const u8 *data, int blocks) + */ SYM_TYPED_FUNC_START(sha256_transform_rorx) pushq %rbx pushq %r12 diff --git a/arch/x86/crypto/sha256-ssse3-asm.S b/arch/x86/crypto/sha256-ssse3-asm.S index 959288eecc68..1b2a5bb405a7 100644 --- a/arch/x86/crypto/sha256-ssse3-asm.S +++ b/arch/x86/crypto/sha256-ssse3-asm.S @@ -88,9 +88,9 @@ SHUF_00BA = %xmm10 # shuffle xBxA -> 00BA SHUF_DC00 = %xmm11 # shuffle xDxC -> DC00 BYTE_FLIP_MASK = %xmm12 -NUM_BLKS = %rdx # 3rd arg -INP = %rsi # 2nd arg CTX = %rdi # 1st arg +INP = %rsi # 2nd arg +NUM_BLKS = %rdx # 3rd arg SRND = %rsi # clobbers INP c = %ecx @@ -347,15 +347,20 @@ a = TMP_ ROTATE_ARGS .endm -######################################################################## -## void sha256_transform_ssse3(struct sha256_state *state, const u8 *data, -## int blocks); -## arg 1 : pointer to state -## (struct sha256_state is assumed to begin with u32 state[8]) -## arg 2 : pointer to input data -## arg 3 : Num blocks -######################################################################## .text + +/** + * sha256_transform_ssse3 - Calculate SHA256 hash using the x86 SSSE3 feature set + * @digest: address of current 32-byte hash value (%rdi, CTX macro) + * @data: address of data (%rsi, INP macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha256_transform_ssse3(u32 *digest, const u8 *data, int blocks) + */ SYM_TYPED_FUNC_START(sha256_transform_ssse3) pushq %rbx pushq %r12 diff --git a/arch/x86/crypto/sha256_ni_asm.S b/arch/x86/crypto/sha256_ni_asm.S index 537b6dcd7ed8..e7a3b9939327 100644 --- a/arch/x86/crypto/sha256_ni_asm.S +++ b/arch/x86/crypto/sha256_ni_asm.S @@ -76,8 +76,16 @@ #define ABEF_SAVE %xmm9 #define CDGH_SAVE %xmm10 -/* - * Intel SHA Extensions optimized implementation of a SHA-256 update function +.text + +/** + * sha256_ni_transform - Calculate SHA256 hash using the x86 SHA-NI feature set + * @digest: address of current 32-byte hash value (%rdi, DIGEST_PTR macro) + * @data: address of data (%rsi, DATA_PTR macro); + * data size must be a multiple of 64 bytes + * @blocks: number of 64-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. * * The function takes a pointer to the current hash values, a pointer to the * input data, and a number of 64 byte blocks to process. Once all blocks have @@ -89,16 +97,10 @@ * The indented lines in the loop are instructions related to rounds processing. * The non-indented lines are instructions related to the message schedule. * - * void sha256_ni_transform(uint32_t *digest, const void *data, - uint32_t numBlocks); - * digest : pointer to digest - * data: pointer to input data - * numBlocks: Number of blocks to process + * Return: none + * Prototype: asmlinkage void sha256_ni_transform(u32 *digest, const u8 *data, int blocks) */ - -.text SYM_TYPED_FUNC_START(sha256_ni_transform) - shl $6, NUM_BLKS /* convert to bytes */ jz .Ldone_hash add DATA_PTR, NUM_BLKS /* pointer to end of data */ diff --git a/arch/x86/crypto/sha512-avx-asm.S b/arch/x86/crypto/sha512-avx-asm.S index b0984f19fdb4..958e355915d0 100644 --- a/arch/x86/crypto/sha512-avx-asm.S +++ b/arch/x86/crypto/sha512-avx-asm.S @@ -50,15 +50,10 @@ #include #include -.text - # Virtual Registers -# ARG1 -digest = %rdi -# ARG2 -msg = %rsi -# ARG3 -msglen = %rdx +digest = %rdi # ARG1 +msg = %rsi # ARG2 +msglen = %rdx # ARG3 T1 = %rcx T2 = %r8 a_64 = %r9 @@ -266,14 +261,20 @@ frame_size = frame_WK + WK_SIZE RotateState .endm -######################################################################## -# void sha512_transform_avx(sha512_state *state, const u8 *data, int blocks) -# Purpose: Updates the SHA512 digest stored at "state" with the message -# stored in "data". -# The size of the message pointed to by "data" must be an integer multiple -# of SHA512 message blocks. -# "blocks" is the message length in SHA512 blocks -######################################################################## +.text + +/** + * sha512_transform_avx - Calculate SHA512 hash using the x86 AVX feature set + * @digest: address of current 64-byte hash value (%rdi, digest macro) + * @data: address of data (%rsi, msg macro); + * data must be a multiple of 128 bytes + * @blocks: number of 128-byte blocks (%rdx, msglen macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha512_transform_avx(u32 *digest, const u8 *data, int blocks) + */ SYM_TYPED_FUNC_START(sha512_transform_avx) test msglen, msglen je nowork diff --git a/arch/x86/crypto/sha512-avx2-asm.S b/arch/x86/crypto/sha512-avx2-asm.S index b1ca99055ef9..e896b2f54120 100644 --- a/arch/x86/crypto/sha512-avx2-asm.S +++ b/arch/x86/crypto/sha512-avx2-asm.S @@ -52,8 +52,6 @@ #include #include -.text - # Virtual Registers Y_0 = %ymm4 Y_1 = %ymm5 @@ -69,13 +67,10 @@ XFER = YTMP0 BYTE_FLIP_MASK = %ymm9 -# 1st arg is %rdi, which is saved to the stack and accessed later via %r12 -CTX1 = %rdi +CTX1 = %rdi # 1st arg, which is saved to the stack and accessed later via %r12 CTX2 = %r12 -# 2nd arg -INP = %rsi -# 3rd arg -NUM_BLKS = %rdx +INP = %rsi # 2nd arg +NUM_BLKS = %rdx # 3rd arg c = %rcx d = %r8 @@ -558,14 +553,21 @@ frame_size = frame_CTX + CTX_SIZE .endm -######################################################################## -# void sha512_transform_rorx(sha512_state *state, const u8 *data, int blocks) -# Purpose: Updates the SHA512 digest stored at "state" with the message -# stored in "data". -# The size of the message pointed to by "data" must be an integer multiple -# of SHA512 message blocks. -# "blocks" is the message length in SHA512 blocks -######################################################################## +.text + +/** + * sha512_transform_rorx - Calculate SHA512 hash using the x86 AVX2 feature set + * including the RORX (rotate right logical without affecting flags) instruction + * @digest: address of 64-byte hash value (%rdi, CTX1 macro) + * @data: address of data (%rsi, INP macro); + * data must be a multiple of 128 bytes + * @blocks: number of 128-byte blocks (%rdx, NUM_BLKS macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha512_transform_rorx(u32 *digest, const u8 *data, int blocks) + */ SYM_TYPED_FUNC_START(sha512_transform_rorx) # Save GPRs push %rbx diff --git a/arch/x86/crypto/sha512-ssse3-asm.S b/arch/x86/crypto/sha512-ssse3-asm.S index c06afb5270e5..3bbf164e07fb 100644 --- a/arch/x86/crypto/sha512-ssse3-asm.S +++ b/arch/x86/crypto/sha512-ssse3-asm.S @@ -50,15 +50,10 @@ #include #include -.text - # Virtual Registers -# ARG1 -digest = %rdi -# ARG2 -msg = %rsi -# ARG3 -msglen = %rdx +digest = %rdi # ARG1 +msg = %rsi # ARG2 +msglen = %rdx # ARG3 T1 = %rcx T2 = %r8 a_64 = %r9 @@ -265,18 +260,21 @@ frame_size = frame_WK + WK_SIZE RotateState .endm -######################################################################## -## void sha512_transform_ssse3(struct sha512_state *state, const u8 *data, -## int blocks); -# (struct sha512_state is assumed to begin with u64 state[8]) -# Purpose: Updates the SHA512 digest stored at "state" with the message -# stored in "data". -# The size of the message pointed to by "data" must be an integer multiple -# of SHA512 message blocks. -# "blocks" is the message length in SHA512 blocks. -######################################################################## -SYM_TYPED_FUNC_START(sha512_transform_ssse3) +.text +/** + * sha512_transform_ssse3 - Calculate SHA512 hash using x86 SSSE3 feature set + * @digest: address of current 64-byte hash value (%rdi, digest macro) + * @data: address of data (%rsi, msg macro); + * data size must be a multiple of 128 bytes + * @blocks: number of 128-byte blocks (%rdx, msglen macro) + * + * This function supports 64-bit CPUs. + * + * Return: none + * Prototype: asmlinkage void sha512_transform_ssse3(u32 *digest, const u8 *data, int blocks) + */ +SYM_TYPED_FUNC_START(sha512_transform_ssse3) test msglen, msglen je nowork From patchwork Mon Dec 19 18:55:51 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Elliott, Robert \(Servers\)" X-Patchwork-Id: 635197 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4F2B4C46467 for ; Mon, 19 Dec 2022 18:56:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232557AbiLSS4S (ORCPT ); Mon, 19 Dec 2022 13:56:18 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58286 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232492AbiLSS4O (ORCPT ); Mon, 19 Dec 2022 13:56:14 -0500 Received: from mx0a-002e3701.pphosted.com (mx0a-002e3701.pphosted.com [148.163.147.86]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1D0F4D4E; Mon, 19 Dec 2022 10:56:13 -0800 (PST) Received: from pps.filterd (m0134421.ppops.net [127.0.0.1]) by mx0b-002e3701.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 2BJH9e4s024684; Mon, 19 Dec 2022 18:56:10 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hpe.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding; s=pps0720; bh=kczMy2QfNEyH0NJOgvc2/X7gY5M59ulYQ7GjkwyPeuI=; b=GKVEKt2wYzblT3SLd0cg19g8rglK4VoydeCBPEqYYc7MhLSHYI0r5EhHGXxybPQ8XttI sGi0grXhn9l673mbTxbuuOGxG2xCyJLLMy8TkgtpAce93zmuDP4UKholr9oBpJjZrgVi Hu8EYVG/i9ISevdxucg5GYTu53xTzr6WJm0C1DAwBn0UzKkmLOs9xvLvsrj5zra52iTc DOnp+5DJ4TBmn+FLzpNcX4+5IpDfy//Q3enti8llHq7LJXZW2U2N9p1CI+BmGIlcDqjg hIBIetYiQ+v4UUmJLCel0dqwB490DD7iJ4Ni2LVwMhEkH7bDC4oFwb6YjCaeqQ0koqfo fQ== Received: from p1lg14879.it.hpe.com (p1lg14879.it.hpe.com [16.230.97.200]) by mx0b-002e3701.pphosted.com (PPS) with ESMTPS id 3mjv420q8y-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 19 Dec 2022 18:56:10 +0000 Received: from p1lg14885.dc01.its.hpecorp.net (unknown [10.119.18.236]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by p1lg14879.it.hpe.com (Postfix) with ESMTPS id 04690310BD; Mon, 19 Dec 2022 18:56:09 +0000 (UTC) Received: from adevxp033-sys.us.rdlabs.hpecorp.net (unknown [16.231.227.36]) by p1lg14885.dc01.its.hpecorp.net (Postfix) with ESMTP id 7625A8064AD; Mon, 19 Dec 2022 18:56:09 +0000 (UTC) From: Robert Elliott To: herbert@gondor.apana.org.au, davem@davemloft.net, corbet@lwn.net, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Robert Elliott Subject: [PATCH v2 4/8] crypto: x86/crc - add kernel-doc comments to assembly Date: Mon, 19 Dec 2022 12:55:51 -0600 Message-Id: <20221219185555.433233-5-elliott@hpe.com> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221219185555.433233-1-elliott@hpe.com> References: <20221215063857.161665-1-elliott@hpe.com> <20221219185555.433233-1-elliott@hpe.com> MIME-Version: 1.0 X-Proofpoint-ORIG-GUID: vlgelhOGaJPQ8y5WCYQDLE-LI94covVG X-Proofpoint-GUID: vlgelhOGaJPQ8y5WCYQDLE-LI94covVG X-HPE-SCL: -1 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.923,Hydra:6.0.545,FMLib:17.11.122.1 definitions=2022-12-19_01,2022-12-15_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 clxscore=1015 adultscore=0 phishscore=0 impostorscore=0 spamscore=0 mlxlogscore=999 malwarescore=0 bulkscore=0 mlxscore=0 lowpriorityscore=0 priorityscore=1501 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2212070000 definitions=main-2212190168 Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org Add kernel-doc comments for assembly language functions exported to C glue code. Signed-off-by: Robert Elliott --- arch/x86/crypto/crc32-pclmul_asm.S | 24 ++++++++++--------- arch/x86/crypto/crc32c-pcl-intel-asm_64.S | 29 ++++++++++++++--------- arch/x86/crypto/crct10dif-pcl-asm_64.S | 24 +++++++++++++------ 3 files changed, 48 insertions(+), 29 deletions(-) diff --git a/arch/x86/crypto/crc32-pclmul_asm.S b/arch/x86/crypto/crc32-pclmul_asm.S index ca53e96996ac..f704b2067a80 100644 --- a/arch/x86/crypto/crc32-pclmul_asm.S +++ b/arch/x86/crypto/crc32-pclmul_asm.S @@ -17,7 +17,6 @@ #include - .section .rodata .align 16 /* @@ -67,19 +66,22 @@ #define CRC %ecx #endif - - .text /** - * Calculate crc32 - * BUF - buffer (16 bytes aligned) - * LEN - sizeof buffer (16 bytes aligned), LEN should be grater than 63 - * CRC - initial crc32 - * return %eax crc32 - * uint crc32_pclmul_le_16(unsigned char const *buffer, - * size_t len, uint crc32) + * crc32_pclmul_le_16 - Calculate CRC32 using x86 PCLMULQDQ instructions + * @buffer: address of data (32-bit %eax/64-bit %rdi, BUF macro); + * must be aligned to a multiple of 16 + * @len: data size (32-bit %edx/64 bit %rsi, LEN macro); + * must be a multiple of 16 and greater than 63 + * @crc32: initial CRC32 value (32-bit %ecx/64-bit $edx, CRC macro) + * only uses lower 32 bits + * + * This function supports both 32-bit and 64-bit CPUs. + * It requires data to be aligned and a minimum size. + * + * Return: (32-bit %eax/64-bit %rax) CRC32 value (in lower 32 bits) + * Prototype: asmlinkage u32 crc32_pclmul_le_16(const u8 *buffer, size_t len, u32 crc32); */ - SYM_FUNC_START(crc32_pclmul_le_16) /* buffer and buffer size are 16 bytes aligned */ movdqa (BUF), %xmm1 movdqa 0x10(BUF), %xmm2 diff --git a/arch/x86/crypto/crc32c-pcl-intel-asm_64.S b/arch/x86/crypto/crc32c-pcl-intel-asm_64.S index ec35915f0901..3d646011d84b 100644 --- a/arch/x86/crypto/crc32c-pcl-intel-asm_64.S +++ b/arch/x86/crypto/crc32c-pcl-intel-asm_64.S @@ -70,22 +70,30 @@ .error "SMALL_ SIZE must be < 256" .endif -# unsigned int crc_pcl(u8 *buffer, int len, unsigned int crc_init); - .text +/** + * crc_pcl - Calculate CRC32C using x86 CRC32 and PCLMULQDQ instructions + * @buffer: address of data (%rdi, bufp macro) + * @len: data size (%rsi, len macro) + * @crc_init: initial CRC32C value (%rdx, crc_init_arg macro); + * only using lower 32 bits + * + * This function supports 64-bit CPUs. + * It loops on 8-byte aligned QWORDs, but also supports unaligned + * addresses and all length values. + * + * Return: CRC32C value (upper 32 bits zero)(%rax) + * Prototype: asmlinkage unsigned int crc_pcl(const u8 *buffer, unsigned int len, + unsigned int crc_init); + */ SYM_FUNC_START(crc_pcl) #define bufp rdi -#define bufp_dw %edi -#define bufp_w %di -#define bufp_b %dil #define bufptmp %rcx #define block_0 %rcx #define block_1 %rdx #define block_2 %r11 #define len %rsi #define len_dw %esi -#define len_w %si -#define len_b %sil #define crc_init_arg %rdx #define tmp %rbx #define crc_init %r8 @@ -97,7 +105,7 @@ SYM_FUNC_START(crc_pcl) pushq %rdi pushq %rsi - ## Move crc_init for Linux to a different + ## Move crc_init for Linux to a different register mov crc_init_arg, crc_init ################################################################ @@ -216,7 +224,7 @@ LABEL crc_ %i ## 4) Combine three results: ################################################################ - lea (K_table-8)(%rip), %bufp # first entry is for idx 1 + lea (K_table-8)(%rip), %bufp # first entry is for idx 1 shlq $3, %rax # rax *= 8 pmovzxdq (%bufp,%rax), %xmm0 # 2 consts: K1:K2 leal (%eax,%eax,2), %eax # rax *= 3 (total *24) @@ -326,10 +334,9 @@ JMPTBL_ENTRY %i i=i+1 .endr - ################################################################ ## PCLMULQDQ tables - ## Table is 128 entries x 2 words (8 bytes) each + ## Table is 128 entries x 8 bytes each ################################################################ .align 8 K_table: diff --git a/arch/x86/crypto/crct10dif-pcl-asm_64.S b/arch/x86/crypto/crct10dif-pcl-asm_64.S index 5286db5b8165..6903713f7e1b 100644 --- a/arch/x86/crypto/crct10dif-pcl-asm_64.S +++ b/arch/x86/crypto/crct10dif-pcl-asm_64.S @@ -52,8 +52,6 @@ #include -.text - #define init_crc %edi #define buf %rsi #define len %rdx @@ -89,11 +87,23 @@ xorps \src_reg, \dst_reg .endm -# -# u16 crc_t10dif_pcl(u16 init_crc, const *u8 buf, size_t len); -# -# Assumes len >= 16. -# +.text +/** + * crc_t10dif_pcl - Calculate CRC16 per T10 DIF (data integrity format) + * using x86 PCLMULQDQ instructions + * @init_crc: initial CRC16 value (%rdi, init_crc macro); + * only uses lower 16 bits + * @buf: address of data (%rsi, buf macro); + * data buffer must be at least 16 bytes + * @len: data size (%rdx, len macro); + * must be >= 16 + * + * This function supports 64-bit CPUs. + * It allows data to be at any offset. + * + * Return: (%rax) CRC16 value (upper 48 bits zero) + * Prototype: asmlinkage u16 crc_t10dif_pcl(u16 init_crc, const *u8 buf, size_t len); + */ SYM_FUNC_START(crc_t10dif_pcl) movdqa .Lbswap_mask(%rip), BSWAP_MASK From patchwork Mon Dec 19 18:55:54 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Elliott, Robert \(Servers\)" X-Patchwork-Id: 635196 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F2272C4332F for ; Mon, 19 Dec 2022 18:56:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232630AbiLSS4X (ORCPT ); Mon, 19 Dec 2022 13:56:23 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58324 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232549AbiLSS4Q (ORCPT ); Mon, 19 Dec 2022 13:56:16 -0500 Received: from mx0a-002e3701.pphosted.com (mx0a-002e3701.pphosted.com [148.163.147.86]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E8EF825FD; Mon, 19 Dec 2022 10:56:15 -0800 (PST) Received: from pps.filterd (m0134421.ppops.net [127.0.0.1]) by mx0b-002e3701.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 2BJH9e4u024684; Mon, 19 Dec 2022 18:56:14 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hpe.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding; s=pps0720; bh=EheRUOzM1/FbUVSQp3nOUSZfGhhTVB7Lvia97WJ2X5Q=; b=Eut2YUfb20FY3aIS5HKoYDoWQ45Hj3l0HcSPW3NeunA/JbTKWFIYj2F4ItsS1d88tUT7 D+ZKbQ6/1jh34PQbibU3DC4U+FbmtORoCF595eXc/gu+rm68M8eVjtRGjMmL78tVFB4z HmgsFVX06wmp9VJPNiJTBG/EtvlNZJKPba6pmO0KSUkuGm1FpcFAbwtHIIfeZ0jRQhgy c3mjp7d1tRPFeN82jYE6d9F/E9G7cWJgb52EEoCSr9PhBFV338S3mUbfS/+KNqZbtkQj dsshrH+ylw8vs4b3lbzEMuhuw72e9IXzIznT4BQ+y8QTtcFR2qZvFsvnjPI4ijshvxxP 4A== Received: from p1lg14880.it.hpe.com (p1lg14880.it.hpe.com [16.230.97.201]) by mx0b-002e3701.pphosted.com (PPS) with ESMTPS id 3mjv420q9d-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 19 Dec 2022 18:56:13 +0000 Received: from p1lg14885.dc01.its.hpecorp.net (unknown [10.119.18.236]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by p1lg14880.it.hpe.com (Postfix) with ESMTPS id 711BA80712F; Mon, 19 Dec 2022 18:56:13 +0000 (UTC) Received: from adevxp033-sys.us.rdlabs.hpecorp.net (unknown [16.231.227.36]) by p1lg14885.dc01.its.hpecorp.net (Postfix) with ESMTP id 1EB2380576E; Mon, 19 Dec 2022 18:56:13 +0000 (UTC) From: Robert Elliott To: herbert@gondor.apana.org.au, davem@davemloft.net, corbet@lwn.net, linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Cc: Robert Elliott Subject: [PATCH v2 7/8] crypto: x86/blake2s - add kernel-doc comments to assembly Date: Mon, 19 Dec 2022 12:55:54 -0600 Message-Id: <20221219185555.433233-8-elliott@hpe.com> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221219185555.433233-1-elliott@hpe.com> References: <20221215063857.161665-1-elliott@hpe.com> <20221219185555.433233-1-elliott@hpe.com> MIME-Version: 1.0 X-Proofpoint-ORIG-GUID: p1Np6PD6r4ylubU3hGhqhv2rXeFRDAbK X-Proofpoint-GUID: p1Np6PD6r4ylubU3hGhqhv2rXeFRDAbK X-HPE-SCL: -1 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.923,Hydra:6.0.545,FMLib:17.11.122.1 definitions=2022-12-19_01,2022-12-15_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 clxscore=1015 adultscore=0 phishscore=0 impostorscore=0 spamscore=0 mlxlogscore=999 malwarescore=0 bulkscore=0 mlxscore=0 lowpriorityscore=0 priorityscore=1501 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2212070000 definitions=main-2212190168 Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org Add kernel-doc comments for assembly language functions exported to C glue code. Signed-off-by: Robert Elliott --- arch/x86/crypto/blake2s-core.S | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/arch/x86/crypto/blake2s-core.S b/arch/x86/crypto/blake2s-core.S index b50b35ff1fdb..7605e7d94fd2 100644 --- a/arch/x86/crypto/blake2s-core.S +++ b/arch/x86/crypto/blake2s-core.S @@ -46,6 +46,19 @@ SIGMA2: #endif /* CONFIG_AS_AVX512 */ .text +/** + * blake2s_compress_ssse3 - Calculate BLAKE2s hash using the x86 SSSE3 feature set + * @state: pointer to 48-byte state (%rdi) + * @data: pointer to data (%rsi) + * @nblocks: number of 64-byte blocks of data (%rdx) + * @inc: counter increment value (%rcx) + * + * This function supports 64-bit CPUs. + * + * Return: none (but modifies state) + * Prototype: asmlinkage void blake2s_compress_ssse3(struct blake2s_state *state, const u8 *data, + * unsigned int nblocks, u32 inc); + */ SYM_FUNC_START(blake2s_compress_ssse3) testq %rdx,%rdx je .Lendofloop @@ -175,6 +188,19 @@ SYM_FUNC_START(blake2s_compress_ssse3) SYM_FUNC_END(blake2s_compress_ssse3) #ifdef CONFIG_AS_AVX512 +/** + * blake2s_compress_avx512 - Calculate BLAKE2s hash using the x86 AVX-512VL feature set + * @state: address of 48-byte state (%rdi) + * @data: address of data (%rsi) + * @nblocks: number of 64-byte blocks of data (%rdx) + * @inc: counter increment value (%rcx) + * + * This function supports 64-bit CPUs. + * + * Return: none (but modifies state) + * Prototype: asmlinkage void blake2s_compress_avx512(struct blake2s_state *state, const u8 *data, + * unsigned int nblocks, u32 inc); + */ SYM_FUNC_START(blake2s_compress_avx512) vmovdqu (%rdi),%xmm0 vmovdqu 0x10(%rdi),%xmm1