[PATCH 1/8] crypto: clean up kernel-doc headers
From: Robert Elliott
Date: Thu Dec 15 2022 - 01:39:45 EST
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 <elliott@xxxxxxx>
---
.../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 <linux/async_tx.h>
#include <linux/gfp.h>
-/**
- * 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 cb3d6b1c655d..8d50c19e0f8e 100644
--- a/include/crypto/acompress.h
+++ b/include/crypto/acompress.h
@@ -208,7 +208,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 <linux/types.h>
/**
- * 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 <linux/uio.h>
/**
- * 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
--
2.38.1