tst_af_alg.h: tst_crypto.h: Fix sphinx formatting

Signed-off-by: Petr Vorel <[email protected]>

include/tst_af_alg.h

@@ -3,10 +3,11 @@
  * Copyright 2019 Google LLC
  * Copyright (c) Linux Test Project, 2021
  */
+
 /**
- * @file tst_af_alg.h
+ * DOC: tst_af_alg.h -- Kernel crypto algorithms (AF_ALG) helpers
  *
- * Library for accessing kernel crypto algorithms via AF_ALG.
+ * Helpers for accessing kernel crypto algorithms via AF_ALG.
  *
  * See https://www.kernel.org/doc/html/latest/crypto/userspace-if.html
  * for more information about AF_ALG.
@@ -19,33 +20,33 @@
 #include <stdbool.h>
 
 /**
- * Create an AF_ALG algorithm socket.
+ * tst_alg_create() - Create an AF_ALG algorithm socket.
  *
  * This creates an AF_ALG algorithm socket that is initially not bound to any
  * particular algorithm.  On failure, tst_brk() is called with TCONF if the
  * kernel doesn't support AF_ALG, otherwise TBROK.
  *
- * @return a new AF_ALG algorithm socket
+ * Return: a new AF_ALG algorithm socket
  */
 int tst_alg_create(void);
 
 /**
- * Bind an AF_ALG algorithm socket to an algorithm.
+ * tst_alg_bind_addr() - Bind an AF_ALG algorithm socket to an algorithm.
  *
- * @param algfd An AF_ALG algorithm socket
- * @param addr A structure which specifies the algorithm to use
+ * @algfd: An AF_ALG algorithm socket
+ * @addr: A structure which specifies the algorithm to use
  *
  * On failure, tst_brk() is called with TCONF if the kernel doesn't support the
  * specified algorithm, otherwise TBROK.
  */
 void tst_alg_bind_addr(int algfd, const struct sockaddr_alg *addr);
 
 /**
- * Bind an AF_ALG algorithm socket to an algorithm.
+ * tst_alg_bind() - Bind an AF_ALG algorithm socket to an algorithm.
  *
- * @param algfd An AF_ALG algorithm socket
- * @param algtype The type of algorithm, such as "hash" or "skcipher"
- * @param algname The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @algfd: An AF_ALG algorithm socket
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
  *
  * Like tst_alg_bind_addr(), except this just takes in the algorithm type and
  * name.  The 'feat' and 'mask' fields are left 0.
@@ -56,53 +57,53 @@ void tst_alg_bind_addr(int algfd, const struct sockaddr_alg *addr);
 void tst_alg_bind(int algfd, const char *algtype, const char *algname);
 
 /**
- * Check for the availability of an algorithm.
+ * tst_try_alg() - Check for the availability of an algorithm.
  *
- * @param algtype The type of algorithm, such as "hash" or "skcipher"
- * @param algname The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
  *
- * Return 0 if the algorithm is available, or errno if unavailable.
+ * Return: 0 if the algorithm is available, or errno if unavailable.
  */
 int tst_try_alg(const char *algtype, const char *algname);
 
 /**
- * Check for the availability of an algorithm.
+ * tst_have_alg() - Check for the availability of an algorithm.
  *
- * @param algtype The type of algorithm, such as "hash" or "skcipher"
- * @param algname The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
  *
- * Return true if the algorithm is available, or false if unavailable
+ * Return: true if the algorithm is available, or false if unavailable
  * and call tst_res() with TCONF. If another error occurs, tst_brk() is called
  * with TBROK unless algorithm is disabled due FIPS mode (errno ELIBBAD).
  */
 bool tst_have_alg(const char *algtype, const char *algname);
 
 /**
- * Require the availability of an algorithm.
+ * tst_require_alg() - Require the availability of an algorithm.
  *
- * @param algtype The type of algorithm, such as "hash" or "skcipher"
- * @param algname The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
  *
  * If the algorithm is unavailable, tst_brk() is called with TCONF.
  * If another error occurs, tst_brk() is called with TBROK.
  */
 void tst_require_alg(const char *algtype, const char *algname);
 
 /**
- * Assign a cryptographic key to an AF_ALG algorithm socket.
+ * tst_alg_setkey() - Assign a cryptographic key to an AF_ALG algorithm socket.
  *
- * @param algfd An AF_ALG algorithm socket
- * @param key Pointer to the key.  If NULL, a random key is generated.
- * @param keylen Length of the key in bytes
+ * @algfd: An AF_ALG algorithm socket
+ * @key: Pointer to the key.  If NULL, a random key is generated.
+ * @keylen: Length of the key in bytes
  *
  * On failure, tst_brk() is called with TBROK.
  */
 void tst_alg_setkey(int algfd, const uint8_t *key, unsigned int keylen);
 
 /**
- * Create an AF_ALG request socket for the given algorithm socket.
+ * tst_alg_accept() - Create an AF_ALG request socket for the given algorithm socket.
  *
- * @param algfd An AF_ALG algorithm socket
+ * @algfd: An AF_ALG algorithm socket
  *
  * This creates a request socket for the given algorithm socket, which must be
  * bound to an algorithm.  The same algorithm socket can have many request
@@ -112,35 +113,40 @@ void tst_alg_setkey(int algfd, const uint8_t *key, unsigned int keylen);
  *
  * On failure, tst_brk() is called with TBROK.
  *
- * @return a new AF_ALG request socket
+ * Return: a new AF_ALG request socket
  */
 int tst_alg_accept(int algfd);
 
 /**
- * Set up an AF_ALG algorithm socket for the given algorithm w/ given key.
+ * tst_alg_setup() - Set up an AF_ALG algorithm socket for the given algorithm w/ given key.
  *
- * @param algtype The type of algorithm, such as "hash" or "skcipher"
- * @param algname The name of the algorithm, such as "sha256" or "xts(aes)"
- * @param key The key to use (optional)
- * @param keylen The length of the key in bytes (optional)
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @key: The key to use (optional)
+ * @keylen: The length of the key in bytes (optional)
  *
  * This is a helper function which creates an AF_ALG algorithm socket, binds it
  * to the specified algorithm, and optionally sets a key.  If keylen is 0 then
  * no key is set; otherwise if key is NULL a key of the given length is randomly
  * generated and set; otherwise the given key is set.
  *
- * @return the AF_ALG algorithm socket that was set up
+ * Return: the AF_ALG algorithm socket that was set up
  */
 int tst_alg_setup(const char *algtype, const char *algname,
 		  const uint8_t *key, unsigned int keylen);
 
 /**
- * Set up an AF_ALG request socket for the given algorithm w/ given key.
+ * tst_alg_setup_reqfd() - Set up an AF_ALG request socket for the given algorithm w/ given key.
+ *
+ * @algtype: The type of algorithm, such as "hash" or "skcipher"
+ * @algname: The name of the algorithm, such as "sha256" or "xts(aes)"
+ * @key: The key to use (optional)
+ * @keylen: The length of the key in bytes (optional)
  *
  * This is like tst_alg_setup(), except this returns a request fd instead of the
  * alg fd.  The alg fd is closed, so it doesn't need to be kept track of.
  *
- * @return the AF_ALG request socket that was set up
+ * Return: the AF_ALG request socket that was set up
  */
 int tst_alg_setup_reqfd(const char *algtype, const char *algname,
 			const uint8_t *key, unsigned int keylen);
@@ -166,11 +172,11 @@ struct tst_alg_sendmsg_params {
 };
 
 /**
- * Send some data to an AF_ALG request socket, including control data.
- * @param reqfd An AF_ALG request socket
- * @param data The data to send
- * @param datalen The length of data in bytes
- * @param params Specification of the control data to send
+ * tst_alg_sendmsg() - Send some data to an AF_ALG request socket, including control data.
+ * @reqfd: An AF_ALG request socket
+ * @data: The data to send
+ * @datalen: The length of data in bytes
+ * @params: Specification of the control data to send
  *
  * On failure, tst_brk() is called with TBROK.
  */

include/tst_crypto.h

@@ -3,9 +3,9 @@
  */
 
 /**
- * @file tst_crypto.h
+ * DOC: tst_crypto.h -- kernel's crypto layer helpers
  *
- * Library for interacting with kernel's crypto layer using the netlink
+ * Helpers for interacting with kernel's crypto layer using the netlink
  * interface.
  */
 
@@ -16,28 +16,28 @@
 #include "tst_netlink.h"
 
 /**
- * Add a crypto algorithm to a session.
+ * tst_crypto_add_alg() - Add a crypto algorithm to a session.
  *
- * @param ctx Initialized netlink context
- * @param alg The crypto algorithm or module to add.
+ * @ctx: Initialized netlink context
+ * @alg: The crypto algorithm or module to add.
  *
  * This requests a new crypto algorithm/engine/module to be initialized by the
  * kernel. It sends the request contained in alg and then waits for a
  * response. If sending the message or receiving the ack fails at the netlink
  * level then tst_brk() with TBROK will be called.
  *
- * @return On success it will return 0 otherwise it will return an inverted
- *         error code from the crypto layer.
+ * Return: On success it will return 0 otherwise it will return an inverted
+ * error code from the crypto layer.
  */
 int tst_crypto_add_alg(struct tst_netlink_context *ctx,
 		       const struct crypto_user_alg *alg);
 
 /**
- * Delete a crypto algorithm from a session.
+ * tst_crypto_del_alg() - Delete a crypto algorithm from a session.
  *
- * @param ctx Initialized netlink context
- * @param alg The crypto algorithm to delete.
- * @param retries Number of retries before giving up. Recommended value: 1000
+ * @ctx: Initialized netlink context
+ * @alg: The crypto algorithm to delete.
+ * @retries: Number of retries before giving up. Recommended value: 1000
  *
  * Request that the kernel remove an existing crypto algorithm. This behaves
  * in a similar way to tst_crypto_add_alg() except that it is the inverse
@@ -47,9 +47,9 @@ int tst_crypto_add_alg(struct tst_netlink_context *ctx,
  * EBUSY.
  *
  * Return: Either 0 or an inverted error code from the crypto layer. If called
- *         during cleanup it may return a positive ENODATA value from the LTP
- *         library, you don't need to log this error as it will already have
- *         been printed by tst_brk().
+ * during cleanup it may return a positive ENODATA value from the LTP
+ * library, you don't need to log this error as it will already have
+ * been printed by tst_brk().
  */
 int tst_crypto_del_alg(struct tst_netlink_context *ctx,
 	const struct crypto_user_alg *alg, unsigned int retries);