Re: [LTP] [PATCH v3 2/2] include: doc: Convert comments into linuxdoc

[Petr Vorel <pvorel@suse.cz>]

> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
> ---
>  doc_new/developers/api_c_tests.rst |  26 ++
>  include/tst_buffers.h              |  86 +++--
>  include/tst_capability.h           |  80 ++++-
>  include/tst_checkpoint.h           |  64 +++-
>  include/tst_hugepage.h             |   2 +
>  include/tst_parse.h                |  65 ++++
>  include/tst_res_flags.h            |  72 +++-
>  include/tst_test.h                 | 509 +++++++++++++++++++++--------
>  8 files changed, 702 insertions(+), 202 deletions(-)
>  create mode 100644 include/tst_parse.h

> diff --git a/doc_new/developers/api_c_tests.rst b/doc_new/developers/api_c_tests.rst
> index adee17f16..2c0c8419d 100644
> --- a/doc_new/developers/api_c_tests.rst
> +++ b/doc_new/developers/api_c_tests.rst
> @@ -5,3 +5,29 @@

>  Developing using C API
>  ======================
> +
> +Core LTP API
> +------------
> +
> +.. kernel-doc:: ../../include/tst_res_flags.h
> +.. kernel-doc:: ../../include/tst_test.h
> +
> +Option parsing
> +--------------
> +
> +.. kernel-doc:: ../../include/tst_parse.h
> +
> +Guarded buffers
> +---------------
> +
> +.. kernel-doc:: ../../include/tst_buffers.h
> +
> +Checkpoints
> +-----------
> +
> +.. kernel-doc:: ../../include/tst_checkpoint.h
> +
> +Capabilities
> +------------
> +
> +.. kernel-doc:: ../../include/tst_capability.h
> diff --git a/include/tst_buffers.h b/include/tst_buffers.h
> index b5f355f0f..bd1a112a2 100644
> --- a/include/tst_buffers.h
> +++ b/include/tst_buffers.h
> @@ -3,69 +3,95 @@
>   * Copyright (c) 2019 Cyril Hrubis <chrubis@suse.cz>
>   */

> +/**
> + * DOC: Guarded buffers introduction
> + *
> + * Guarded buffer has a page with PROT_NONE allocated right before the start of
> + * the buffer and canary after the end of the buffer. That means that any
> + * memory access before the buffer ends with EFAULT or SEGFAULT and any write
> + * after the end of the buffer will be detected because it would overwrite the
> + * canaries.
> + *
> + * It should be used for all buffers passed to syscalls to make sure off-by-one
> + * buffer accesses does not happen.
> + */
> +
>  #ifndef TST_BUFFERS_H__
>  #define TST_BUFFERS_H__

> -/*
> +/**
> + * struct tst_buffers - A guarded buffer description for allocator.
> + *
>   * Buffer description consist of a pointer to a pointer and buffer type/size
>   * encoded as a different structure members.
>   *
> - * Only one of the size and iov_sizes can be set at a time.
> + * @ptr: A pointer to the pointer to buffer. This is dereferenced and set by the
> + *       allocator.
> + * @size: A buffer size in bytes. Only one of size and iov_sizes can be set.
> + * @iov_sizes: An -1 terminated array of sizes used to construct a
> + *             struct iovec buffers.
> + * @str: If size is zero and iov_sizes is NULL this string is going to be
> + *       copied into the buffer.
>   */
>  struct tst_buffers {
> -	/*
> -	 * This pointer points to a buffer pointer.
> -	 */
>  	void *ptr;
> -	/*
> -	 * Buffer size.
> -	 */
>  	size_t size;
> -	/*
> -	 * Array of iov buffer sizes terminated by -1.
> -	 */
>  	int *iov_sizes;
> -	/*
> -	 * If size and iov_sizes is NULL this is the string we want to strdup()
> -	 * into the buffer.
> -	 */
>  	char *str;
>  };

> -/*
> - * Allocates buffers based on the tst_buffers structure.
> +/**
> + * tst_buffers_alloc() - Allocates buffers based on the tst_buffers structure.
>   *
> - * @bufs NULL terminated array of test buffer descriptions.
> + * @bufs: A NULL terminated array of test buffer descriptions.
>   *
> - * This is called from the test library if the tst_test->bufs pointer is set.
> + * This is called from the test library if the tst_test.bufs pointer is set.
>   */
>  void tst_buffers_alloc(struct tst_buffers bufs[]);

> -/*
> - * strdup() that callls tst_alloc().
> +/**
> + * tst_strdup() - Copies a string into a newly allocated guarded buffer.
> + *
> + * @str: A string to be duplicated.
> + * return: A pointer to the string duplicated in a guarded buffer.
> + *
> + * Allocates a buffer with tst_alloc() and copies the string into it.
>   */
>  char *tst_strdup(const char *str);

> -/*
> - * Allocates size bytes, returns pointer to the allocated buffer.
> +/**
> + * tst_alloc() - Allocates a guarded buffer.
> + *
> + * @size: A size of the buffer.
> + * return: A newly allocated guarded buffer.
>   */
>  void *tst_alloc(size_t size);

> -/*
> - * Printf into a guarded buffer.
> +/**
> + * tst_aprintf() - Printf into a newly allocated guarded buffer.
> + *
> + * @fmt: A printf-like format.
> + * @...: A printf-like parameters.
> + * return: A newly allocated buffer.
> + *
> + * Allocates a buffer with tst_alloc() then prints the data into it.
>   */
>  char *tst_aprintf(const char *fmt, ...)
>        __attribute__((format (printf, 1, 2)));

> -/*
> - * Allocates iovec structure including the buffers.
> +/**
> + * tst_iovec_alloc() - Allocates a complete iovec structure.
>   *
> - * @sizes -1 terminated array of buffer sizes.
> + * @sizes: A -1 terminated array of buffer sizes.
> + * return: Newly allocated iovec structure.
>   */
>  struct iovec *tst_iovec_alloc(int sizes[]);

> -/*
> - * Frees all allocated buffers.
> +/**
> + * tst_free_all() - Frees all allocated buffers.
> + *
> + * It's important to free all guarded buffers because the canaries after the
> + * buffer are checked only when the buffer is being freed.
>   *
>   * This is called at the end of the test automatically.
>   */
> diff --git a/include/tst_capability.h b/include/tst_capability.h
> index 6067804a3..ccf4bd77b 100644
> --- a/include/tst_capability.h
> +++ b/include/tst_capability.h
> @@ -2,8 +2,9 @@
>  /*
>   * Copyright (c) 2019 Richard Palethorpe <rpalethorpe@suse.com>
>   */
> +
>  /**
> - * @file tst_capability.h
> + * DOC: Capabilities introduction
>   *
>   * Limited capability operations without libcap.
>   */
> @@ -15,22 +16,51 @@

>  #include "lapi/capability.h"

> -#define TST_CAP_DROP 1
> -#define TST_CAP_REQ  (1 << 1)
> -
> -#define TST_CAP(action, capability) {action, capability, #capability}
> +/**
> + * enum tst_cap_act - A capability action masks.
> + *
> + * @TST_CAP_DROP: Drop capabilities.
> + * @TST_CAP_REQ: Add capabilities.
> + */
> +enum tst_cap_act {
> +	TST_CAP_DROP = 1,
> +	TST_CAP_REQ = (1 << 1)
> +};

> +/**
> + * struct tst_cap_user_header - Kernel capget(), capset() syscall header.
> + *
> + * @version: A capability API version.
> + * @pid: A process to operate on.
> + */
>  struct tst_cap_user_header {
>  	uint32_t version;
>  	int pid;
>  };

> +/**
> + * struct tst_cap_user_data - Kernel capset(), capget() syscall payload.
> + *
> + * @effective: A capability effective set.
> + * @permitted: A capability permitted set.
> + * @inheritable: A capability inheritable set.
> + */
>  struct tst_cap_user_data {
>  	uint32_t effective;
>  	uint32_t permitted;
>  	uint32_t inheritable;
>  };

> +/**
> + * struct tst_cap - A capability to alter.
> + *
> + * @action: What should we do, i.e. drop or add a capability.
> + * @id: A capability id.
> + * @name: A capability name.
> + *
> + * This structure is usually constructed with the TST_CAP() macro so that the
> + * name is created automatically.
> + */
>  struct tst_cap {
>  	uint32_t action;
>  	uint32_t id;
> @@ -38,25 +68,43 @@ struct tst_cap {
>  };

>  /**
> - * Get the capabilities as decided by hdr.
> + * TST_CAP() - Create a struct tst_cap entry.
>   *
> - * Note that the memory pointed to by data should be large enough to store two
> - * structs.
> + * @action: What should we do, i.e. drop or add capability.
> + * @capability: A capability id, e.g. CAP_BPF.
> + */
> +#define TST_CAP(action, capability) {action, capability, #capability}
> +
> +/**
> + * tst_capget() - Get the capabilities as decided by hdr.
> + *
> + * @hdr: A capability user header stores a pid to operate on and which
> + *       capability API version is used.
> + * @data: A memory to store the capabilities to. The memory pointed to by data
> + *        should be large enough to store two structs.
> + *
> + * return: Returns 0 on success, -1 on a failure and sets errno.
>   */
>  int tst_capget(struct tst_cap_user_header *hdr,
>  	       struct tst_cap_user_data *data);

>  /**
> - * Set the capabilities as decided by hdr and data
> + * tst_capset() - Set the capabilities as decided by hdr and data
>   *
> - * Note that the memory pointed to by data should be large enough to store two
> - * structs.
> + * @hdr: A capability user header stores a pid to operate on and which
> + *       capability API version is used.
> + * @data: A memory to store the capabilities to. The memory pointed to by data
> + *        should be large enough to store two structs.
> + *
> + * return: Returns 0 on success, -1 on a failure and sets errno.
>   */
>  int tst_capset(struct tst_cap_user_header *hdr,
>  	       const struct tst_cap_user_data *data);

>  /**
> - * Add, check or remove a capability
> + * tst_cap_action() - Add, check or remove a capability.
> + *
> + * @cap: An {} terminated array of capabilities to alter.
>   *
>   * It will attempt to drop or add capability to the effective set. It will
>   * try to detect if this is needed and whether it can or can't be done. If it
> @@ -71,13 +119,17 @@ void tst_cap_action(struct tst_cap *cap);


>  /**
> - * Add, check or remove a capabilities
> + * tst_cap_setup() - Add, check or remove a capabilities.
> + *
> + * @cap: An {} terminated array of capabilities to alter.
> + * @action_mask: Decides which actions are done, i.e. only drop caps, add them
> + *               or both.
>   *
>   * Takes a NULL terminated array of structs which describe whether some
>   * capabilities are needed or not and mask that determines subset of the
>   * actions to be performed. Loops over the array and if mask matches the
>   * element action it's passed to tst_cap_action().
>   */
> -void tst_cap_setup(struct tst_cap *cap, unsigned int action_mask);
> +void tst_cap_setup(struct tst_cap *cap, enum tst_cap_act action_mask);

>  #endif /* TST_CAPABILITY_H */
> diff --git a/include/tst_checkpoint.h b/include/tst_checkpoint.h
> index 1b6911d73..a8d66a333 100644
> --- a/include/tst_checkpoint.h
> +++ b/include/tst_checkpoint.h
> @@ -1,24 +1,86 @@
> -/* SPDX-License-Identifier: GPL-2.0-or-later
> +// SPDX-License-Identifier: GPL-2.0-or-later
> +/*
>   * Copyright (c) 2016 Cyril Hrubis <chrubis@suse.cz>
>   */

> +/**
> + * DOC: Checkpoints introduction
> + *
> + * Checkpoints implements a futex based synchronization primitive for threads
> + * and processes. When a process calls wait function its execution is suspended
> + * until wake is called for a corresponding checkpoint. Checkpoints are
> + * numbered from 0 and process can use at least hundred of them.
> + *
> + * In order to use checkpoints the test must set the tst_test.needs_checkpoints
> + * flag.
> + */
> +
>  #ifndef TST_CHECKPOINT__
>  #define TST_CHECKPOINT__

>  #include "tst_checkpoint_fn.h"

> +/**
> + * TST_CHECKPOINT_WAIT() - Waits for a checkpoint.
> + *
> + * @id: A checkpoint id a positive integer.
> + *
> + * Suspends thread/process execution until it's woken up with a wake. The call
> + * does not wait indefinitely it gives up after 10 seconds. If an error
> + * happened or timeout was reached the function calls tst_brk(TBROK, ...) which
> + * exits the test.
> + */
>  #define TST_CHECKPOINT_WAIT(id) \
>          tst_safe_checkpoint_wait(__FILE__, __LINE__, NULL, id, 0)

> +/**
> + * TST_CHECKPOINT_WAIT2() - Waits for a checkpoint.
> + *
> + * @id: A checkpoint id a positive integer.
> + * @msec_timeout: A timeout.
> + *
> + * Suspends thread/process execution until it's woken up with a wake. If an
> + * error happened or timeout was reached the function calls tst_brk(TBROK, ...)
> + * which exits the test.
> + */
>  #define TST_CHECKPOINT_WAIT2(id, msec_timeout) \
>          tst_safe_checkpoint_wait(__FILE__, __LINE__, NULL, id, msec_timeout)

> +/**
> + * TST_CHECKPOINT_WAKE() - Wakes up a checkpoint.
> + *
> + * @id: A checkpoint id a positive integer.
> + *
> + * Wakes up a process suspended on a checkpoint and retries if there is no
> + * process suspended on the checkpoint yet. The call does not retry
> + * indefinitely but gives up after 10 seconds. If an error happened or timeout
> + * was reached the function calls tst_brk(TBROK, ...) which exits the test.
> + */
>  #define TST_CHECKPOINT_WAKE(id) \
>          tst_safe_checkpoint_wake(__FILE__, __LINE__, NULL, id, 1)

> +/**
> + * TST_CHECKPOINT_WAKE2() - Wakes up several checkpoints.
> + *
> + * @id: A checkpoint id a positive integer.
> + * @nr_wake: A number of processes to wake.
> + *
> + * Wakes up nr_wake processes suspended on a checkpoint and retries if there
> + * wasn't enough process suspended on the checkpoint yet. The call does not
> + * retry indefinitely but gives up if it does not wake nr_wake processes after
> + * 10 seconds. If an error happened or timeout was reached the function calls
> + * tst_brk(TBROK, ...) which exits the test.
> + */
>  #define TST_CHECKPOINT_WAKE2(id, nr_wake) \
>          tst_safe_checkpoint_wake(__FILE__, __LINE__, NULL, id, nr_wake)

> +/**
> + * TST_CHECKPOINT_WAKE_AND_WAIT() - Wakes up a checkpoint and immediately waits on it.
> + *
> + * @id: A checkpoint id a positive integer.
> + *
> + * This is a combination of TST_CHECKPOINT_WAKE() and TST_CHECKPOINT_WAIT().
> + */
>  #define TST_CHECKPOINT_WAKE_AND_WAIT(id) do { \
>          tst_safe_checkpoint_wake(__FILE__, __LINE__, NULL, id, 1); \
>          tst_safe_checkpoint_wait(__FILE__, __LINE__, NULL, id, 0); \
> diff --git a/include/tst_hugepage.h b/include/tst_hugepage.h
> index 46327c79a..6b865b2f2 100644
> --- a/include/tst_hugepage.h
> +++ b/include/tst_hugepage.h
> @@ -24,6 +24,8 @@ enum tst_hp_policy {
>  	TST_NEEDS,
>  };

> +#define TST_NO_HUGEPAGES ((unsigned long)-1)
> +
>  struct tst_hugepage {
>  	const unsigned long number;
>  	enum  tst_hp_policy policy;
> diff --git a/include/tst_parse.h b/include/tst_parse.h
> new file mode 100644
> index 000000000..167d416f4
> --- /dev/null
> +++ b/include/tst_parse.h
> @@ -0,0 +1,65 @@
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
> +/*
> + * Copyright (c) 2015-2024 Cyril Hrubis <chrubis@suse.cz>
> + */
> +
> +/**
> + * DOC: Option parsing functions
> + *
> + * Implements simple helpers on the top of the strtol() and strtod() for
> + * command line option parsing.
> + */
> +
> +#ifndef TST_PARSE_H__
> +#define TST_PARSE_H__
> +
> +/**
> + * tst_parse_int() - Parse an integer from a string.
> + *
> + * @str: A string with an integer number.
> + * @val: A pointer to integer to store the result to.
> + * @min: A lower bound, pass INT_MIN for full range.
> + * @max: An upper bound, pass INT_MAX for full range.
> + * return: A zero if whole string was consumed and the value was within bounds,
> + *         an errno otherwise.
> + */
> +int tst_parse_int(const char *str, int *val, int min, int max);
> +
> +/**
> + * tst_parse_long() - Parse a long integer from a string.
> + *
> + * @str: A string with an integer number.
> + * @val: A pointer to long integer to store the result to.
> + * @min: A lower bound, pass LONG_MIN for full range.
> + * @max: An upper bound, pass LONG_MAX for full range.
> + * return: A zero if whole string was consumed and the value was within bounds,
> + *         an errno otherwise.
> + */
> +int tst_parse_long(const char *str, long *val, long min, long max);
> +
> +/**
> + * tst_parse_float() - Parse a floating point number from a string.
> + *
> + * @str: A string with a floating point number.
> + * @val: A pointer to float to store the result to.
> + * @min: A lower bound.
> + * @max: An upper bound.
> + * return: A zero if whole string was consumed and the value was within bounds,
> + *         an errno otherwise.
> + */
> +int tst_parse_float(const char *str, float *val, float min, float max);
> +
> +/**
> + * tst_parse_filesize() - Parse a file size from a string.
> + *
> + * @str: A string a positive number optionally followed by an unit, i.e. K, M,
> + *       or G for kilobytes, megabytes and gigabytes.
> + * @val: A pointer to long long integer to store the size in bytes to.
> + * @min: A lower bound.
> + * @max: An upper bound.
> + * return: A zero if whole string was consumed and the value was within bounds,
> + *         an errno otherwise.
> + */
> +int tst_parse_filesize(const char *str, long long *val, long long min, long long max);
> +
> +#endif	/* TST_PARSE_H__ */
> diff --git a/include/tst_res_flags.h b/include/tst_res_flags.h
> index 872352144..806940e0d 100644
> --- a/include/tst_res_flags.h
> +++ b/include/tst_res_flags.h
> @@ -1,24 +1,66 @@
> -/* SPDX-License-Identifier: GPL-2.0-or-later
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
> +/*
>   * Copyright (c) Linux Test Project, 2014
>   */

>  #ifndef TST_RES_FLAGS_H
>  #define TST_RES_FLAGS_H

> -/* Use low 6 bits to encode test type */
> -#define TTYPE_MASK	0x3f
> -#define TPASS	0	/* Test passed flag */
> -#define TFAIL	1	/* Test failed flag */
> -#define TBROK	2	/* Test broken flag */
> -#define TWARN	4	/* Test warning flag */
> -#define TDEBUG	8	/* Test debug information flag */
> -#define TINFO	16	/* Test information flag */
> -#define TCONF	32	/* Test not appropriate for configuration flag */
> -#define TTYPE_RESULT(ttype)	((ttype) & TTYPE_MASK)
> +/**
> + * enum tst_res_flags - Test result reporting flags.
> + *
> + * @TPASS: Reports a single success.
> + * @TFAIL: Reports a single failure.
> + * @TBROK: Reports a single breakage.
> + * @TWARN: Reports a single warning. Warnings increment a warning counter and
> + *         show up in test results.
> + *
> + * @TDEBUG: Prints additional debugging messages, it does not change the test result counters and
> + *          the message is not displayed unless debugging is enabled with -D
> + *          test command line parameter.
> + *
> + * @TINFO: Prints an additional information, it does not change the test result
> + *         counters but unlike TDEBUG the message is always displayed.
> + *
> + * @TCONF: Reports unsupported configuration. When tests produce this result at
> + *         least a subset of test was skipped, because it couldn't run. The
> + *         usual reasons are, missing kernel modules or CONFIG options.
> + *         Unsuitable CPU architecture, not enough memory, etc.
> + *
> + * @TERRNO: Combine bitwise with result flags to append errno to the output message.
> + *
> + * @TTERRNO: Combine bitwise with result flags to append error from TST_ERR to
> + *           the message. The TST_TEST() macros store the errno into the
> + *           TST_ERR global variable in order to make sure it's not change
> + *           between the test is done and results are printed.
> + *
> + * @TRERRNO: Combine bitwise with result flags to errno from TST_RET variable
> + *           to the message. The TST_TEST() macros store return value into the
> + *           TST_RET global variable and quite a few, e.g. pthread functions,
> + *           return the error value directly instead of storing it to the errno.
> + *
> + * A result flag with optional bitwise combination of errno flag are passed to
> + * the tst_res() and tst_brk() functions. Each message counts as a single test
> + * result and tests can produce arbitrary number of results, i.e. TPASS, TFAIL,
> + * TBROK, TWARN and TCONF messages. Each such message increases a result
> + * counter in a piece of shared memory, which means that reported results are
> + * accounted immediately even from child processes and there is no need for
> + * result propagation.
> + */
> +enum tst_res_flags {
> +	TPASS = 0,
> +	TFAIL = 1,
> +	TBROK = 2,
> +	TWARN = 4,
> +	TDEBUG = 8,
> +	TINFO = 16,
> +	TCONF = 32,
> +	TERRNO = 0x100,
> +	TTERRNO = 0x200,
> +	TRERRNO	= 0x400,
> +};

> -#define TERRNO	0x100	/* Append errno information to output */
> -#define TTERRNO	0x200	/* Append TEST_ERRNO information to output */
> -#define TRERRNO	0x400	/* Capture errno information from TEST_RETURN to
> -			   output; useful for pthread-like APIs :). */
> +#define TTYPE_RESULT(ttype)	((ttype) & TTYPE_MASK)
> +#define TTYPE_MASK 0x3f

>  #endif /* TST_RES_FLAGS_H */
> diff --git a/include/tst_test.h b/include/tst_test.h
> index 47b5902f9..e6c8747c0 100644
> --- a/include/tst_test.h
> +++ b/include/tst_test.h
> @@ -1,4 +1,4 @@
> -// SPDX-License-Identifier: GPL-2.0-or-later
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
>  /*
>   * Copyright (c) 2015-2016 Cyril Hrubis <chrubis@suse.cz>
>   * Copyright (c) Linux Test Project, 2016-2019
> @@ -19,6 +19,7 @@

>  #include "tst_common.h"
>  #include "tst_res_flags.h"
> +#include "tst_parse.h"
>  #include "tst_test_macros.h"
>  #include "tst_checkpoint.h"
>  #include "tst_device.h"
> @@ -47,50 +48,102 @@
>  #include "tst_arch.h"
>  #include "tst_fd.h"

> -/*
> - * Reports testcase result.
> - */
>  void tst_res_(const char *file, const int lineno, int ttype,
>                const char *fmt, ...)
>                __attribute__ ((format (printf, 4, 5)));

> +/**
> + * tst_res() - Reports a test result.
> + *
> + * @ttype: An enum tst_res_type.
> + * @arg_fmt: A printf-like format.
> + * @...: A printf-like parameters.
> + *
> + * This is the main test reporting function. Each time this function is called
> + * with one of TPASS, TFAIL, TCONF, TBROK or TWARN a counter in page of shared
> + * memory is incremented. This means that there is no need to propagate test
> + * results from children and that results are accounted for once this function
> + * returns. The counters are incremented atomically which makes this function
> + * thread-safe.
> + */
>  #define tst_res(ttype, arg_fmt, ...) \
>  	({									\
>  		TST_RES_SUPPORTS_TCONF_TDEBUG_TFAIL_TINFO_TPASS_TWARN(\
>  			!((TTYPE_RESULT(ttype) ?: TCONF) & \
> -			(TCONF | TDEBUG | TFAIL | TINFO | TPASS | TWARN))); 				\
> +			(TCONF | TDEBUG | TFAIL | TINFO | TPASS | TWARN)));				\
>  		tst_res_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
>  	})

>  void tst_resm_hexd_(const char *file, const int lineno, int ttype,
>  	const void *buf, size_t size, const char *arg_fmt, ...)
>  	__attribute__ ((format (printf, 6, 7)));
> -
> +/**
> + * tst_res_hexd() - Reports a test result along with hex dump of a buffer.
> + *
> + * This call is the same as tst_res() but includes a pointer and size of the
> + * buffer that is going to be printed in the output in a hexadecimal format.
> + *
> + * @ttype: An enum tst_res_type.
> + * @buf: A pointer to a buffer to print in hexadecimal format.
> + * @size: A size of the buffer.
> + * @arg_fmt: A printf-like format.
> + * @...: A printf-like parameters.
> + */
>  #define tst_res_hexd(ttype, buf, size, arg_fmt, ...) \
>  	tst_resm_hexd_(__FILE__, __LINE__, (ttype), (buf), (size), \
>  			(arg_fmt), ##__VA_ARGS__)

> -/*
> - * Reports result and exits a test.
> - */
>  void tst_brk_(const char *file, const int lineno, int ttype,
>                const char *fmt, ...)
>                __attribute__ ((format (printf, 4, 5)));

> +/**
> + * tst_brk() - Reports a breakage and exits the test.
> + *
> + * @ttype: An enum tst_res_type.
> + * @arg_fmt: A printf-like format.
> + * @...: A printf-like parameters.
> + *
> + * Reports either TBROK or TCONF and exits the test immediately. When called
> + * all children in the same process group as the main test library process are
> + * killed. This function, unless in a test cleanup, calls _exit() and does not
> + * return.
> + *
> + * When test is in cleanup() function TBROK is converted into TWARN by the test
> + * library and we attempt to carry on with a cleanup even when tst_brk() was
> + * called. This makes it possible to use SAFE_FOO() macros in the test cleanup
> + * without interrupting the cleanup process on a failure.
> + */
>  #define tst_brk(ttype, arg_fmt, ...)						\
>  	({									\
>  		TST_BRK_SUPPORTS_ONLY_TCONF_TBROK(!((ttype) &			\
> -			(TBROK | TCONF | TFAIL))); 				\
> +			(TBROK | TCONF | TFAIL)));				\
>  		tst_brk_(__FILE__, __LINE__, (ttype), (arg_fmt), ##__VA_ARGS__);\
>  	})

>  void tst_printf(const char *const fmt, ...)
>  		__attribute__((nonnull(1), format (printf, 1, 2)));

> -/* flush stderr and stdout */
> +/**
> + * tst_flush() - Flushes the output file streams.
> + *
> + * There are rare cases when we want to flush the output file streams
> + * explicitly, e.g. before we do an action that may crash the test to ensure
> + * that the messages have been written out.
> + *
> + * This is also called by the SAFE_FORK() because otherwise each child would
> + * end up with the same copy of the file in it's memory and any messages in
> + * buffers would be multiplied.
> + */
>  void tst_flush(void);

>  pid_t safe_fork(const char *filename, unsigned int lineno);
> +/**
> + * SAFE_FORK() - Forks a test child.
> + *
> + * This call makes sure that output file streams are flushed and also handles
> + * errors from fork(). Use this instead of fork() whenever possible!
> + */
>  #define SAFE_FORK() \
>  	safe_fork(__FILE__, __LINE__)

> @@ -98,15 +151,30 @@ pid_t safe_fork(const char *filename, unsigned int lineno);
>  	({int ret = expr;                                           \
>  	  ret != 0 ? tst_res(TINFO, #expr " failed"), ret : ret; }) \

> -/*
> - * Functions to convert ERRNO to its name and SIGNAL to its name.
> +/**
> + * tst_strerrno() - Converts an errno number into a name.
> + *
> + * @err: An errno number.
> + * return: An errno name e.g. "EINVAL".
>   */
>  const char *tst_strerrno(int err);
> +
> +/**
> + * tst_strsig() - Converts a signal number into a name.
> + *
> + * @sig: A signal number.
> + * return: A signal name e.g. "SIGINT".
> + */
>  const char *tst_strsig(int sig);
> -/*
> - * Returns string describing status as returned by wait().
> +
> +
> +/**
> + * tst_strstatus() - Returns string describing status as returned by wait().
> + *
> + * WARNING: Not thread safe.
>   *
> - * BEWARE: Not thread safe.
> + * @status: A status as returned by wait()
> + * return: A string description for the status e.g. "killed by SIGKILL".
>   */
>  const char *tst_strstatus(int status);

> @@ -116,30 +184,49 @@ const char *tst_strstatus(int status);
>  #include "tst_clone.h"
>  #include "tst_cgroup.h"

> -/*
> - * Wait for all children and exit with TBROK if
> - * any of them returned a non-zero exit status.
> +/**
> + * tst_reap_children() - Waits for all child processes to exit.
> + *
> + * Wait for all children and exit with TBROK if any of them returned a non-zero
> + * exit status.
>   */
>  void tst_reap_children(void);

> +/**
> + * struct tst_option - Test command line option.
> + *
> + * @optstr: A short command line option, e.g. "a" or "a:".
> + * @arg: A pointer to store the option value to.
> + * @help: A help string for the option displayed when test is passed '-h' on
> + *        the command-line.
> + */
>  struct tst_option {
>  	char *optstr;
>  	char **arg;
>  	char *help;
>  };

> -/*
> - * Options parsing helpers.
> +/**
> + * struct tst_tag - A test tag.
>   *
> - * If str is NULL these are No-op.
> + * @name: A tag name.
> + * @value: A tag value.
>   *
> - * On failure non-zero (errno) is returned.
> + * This structure is used to encode pointers to upstream commits in regression
> + * tests as well as CVE numbers or any additional useful hints.
> + *
> + * The content of these tags is printed by the test on a failure to help the
> + * testers with debugging.
> + *
> + * The supported tags are:
> + *
> + * - "linux-git" with first 12 numbers from an upstream kernel git hash.
> + * - "CVE" with a CVE number e.g. "2000-1234".
> + * - "glibc-git" with first 12 numbers from an upstream glibc git hash.
> + * - "musl-git" with first 12 numbers from an upstream musl git hash.
> + * - "known-fail" a message describing something that is supposed to work but
> + *   rather than that produces a longstanding failures.
>   */
> -int tst_parse_int(const char *str, int *val, int min, int max);
> -int tst_parse_long(const char *str, long *val, long min, long max);
> -int tst_parse_float(const char *str, float *val, float min, float max);
> -int tst_parse_filesize(const char *str, long long *val, long long min, long long max);
> -
>  struct tst_tag {
>  	const char *name;
>  	const char *value;
> @@ -147,30 +234,246 @@ struct tst_tag {

>  extern unsigned int tst_variant;

> -#define TST_NO_HUGEPAGES ((unsigned long)-1)
> -
>  #define TST_UNLIMITED_RUNTIME (-1)

> +/**
> + * struct tst_ulimit_val - An ulimit resource and value.
> + *
> + * @resource: Which resource limits should be adjusted. See setrlimit(2) for
> + *            the list of the RLIMIT_* constants.
> + * @rlim_cur: A limit value.
> + */
>  struct tst_ulimit_val {
>  	int resource;
>  	rlim_t rlim_cur;
>  };

> -struct tst_test {
> -	/* number of tests available in test() function */
> +/**
> + * struct tst_test - A test description.
> + *
> + * @tcnt: A number of tests. If set the test() callback is called tcnt times
> + *        and each time passed an increasing counter value.

Very nit: I would prefer if the formatting would not force the indent, e.g.:

 * @tcnt: A number of tests. If set the test() callback is called tcnt times
 * and each time passed an increasing counter value.

Because variables with long name will require more lines, but feel free to
ignore it.

> + * @options: An NULL optstr terminated array of struct tst_option.
> + *
> + * @min_kver: A minimal kernel version the test can run on. e.g. "3.10".
> + *
> + * @supported_archs: A NULL terminated array of architectures the test runs on
> + *                   e.g. {"x86_64, "x86", NULL}. Calls tst_is_on_arch() to
> + *                   check if current CPU architecture is supported and exits
> + *                   the test with TCONF if it's not.
> + *

...
>  	void (*setup)(void);
>  	void (*cleanup)(void);
> -
>  	void (*test)(unsigned int test_nr);
>  	void (*test_all)(void);

> -	/* Syscall name used by the timer measurement library */
We decided to drop this comment. Isn't it useful?
>  	const char *scall;
> -
> -	/* Sampling function for timer measurement testcases */
>  	int (*sample)(int clk_id, long long usec);
And this one as well.

The rest LGTM. Thanks for working on this!
Reviewed-by: Petr Vorel <pvorel@suse.cz>

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp