[LTP] [PATCH 1/1] include: doc: Convert comments into linuxdoc

Cyril Hrubis metan@ucw.cz
Fri Mar 22 13:07:00 CET 2024


Signed-off-by: Cyril Hrubis <metan@ucw.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_compiler.h             |  20 ++
 include/tst_hugepage.h             |   2 +
 include/tst_parse.h                |  65 ++++
 include/tst_res_flags.h            |  72 +++-
 include/tst_test.h                 | 505 +++++++++++++++++++++--------
 9 files changed, 720 insertions(+), 200 deletions(-)
 create mode 100644 include/tst_compiler.h
 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..f275bfdb8 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 guarded buffer.
+ *
+ * @str: A string to be duplicated.
+ * return: A pointer to the string duplicated in a guraded 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 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 an iovec structure with the buffers.
  *
- * @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..c24c8789c 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 succes, -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 succes, -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..62d87d60b 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 indefinitelly 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
+ * indefinitelly git 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 indefinitelly git 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 immediatelly 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_compiler.h b/include/tst_compiler.h
new file mode 100644
index 000000000..ec88213df
--- /dev/null
+++ b/include/tst_compiler.h
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+/**
+ * @file tst_compiler.h
+ * @brief Macros to support dump compilers.
+ *
+ * The doxygen parser (and possibly other C tooling) does not understand
+ * __attributes__ so we have to hide them with macros.
+ */
+
+#ifndef TST_COMPILER_H__
+#define TST_COMPILER_H__
+
+#ifdef __GNUC__
+# define TST_ATTRIBUTE(...) __attribute__((__VA_ARGS__))
+#else
+# define TST_ATTRIBUTE(...)
+#endif
+
+#endif	/* TST_COMPILER_H__ */
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..11c36e812
--- /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 an integer 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..8a2cf9a71 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 signle 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
+ *         usuall resasons 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 biwise 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 immediatelly 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..d83354b8e 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,13 +48,24 @@
 #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 funciton
+ * thread-safe.
+ */
 #define tst_res(ttype, arg_fmt, ...) \
 	({									\
 		TST_RES_SUPPORTS_TCONF_TDEBUG_TFAIL_TINFO_TPASS_TWARN(\
@@ -65,18 +77,43 @@ void tst_res_(const char *file, const int lineno, int ttype,
 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 hexdump 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 immediatelly. 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) &			\
@@ -87,10 +124,26 @@ void tst_brk_(const char *file, const int lineno, int ttype,
 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 commandline.
+ */
 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.
+ * @options: An NULL opstr 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.
+ *
+ * @tconf_msg: If set the test exits with TCONF right after entering the test
+ *             library. This is used by the TST_TEST_TCONF() macro to disable
+ *             tests at compile time.
+ *
+ * @needs_tmpdir: If set a temporary directory is prepared for the test inside
+ *                $TMPDIR and the test $CWD is set to point to it. The content
+ *                of the temporary directory is removed automatically after
+ *                the test is finished.
+ *
+ * @needs_root: If set the test exit with TCONF unless it's executed under root
+ *              user.
+ *
+ * @forks_child: Has to be set if the test intends to fork children.
+ *
+ * @needs_device: If set a block device is prepared for the test, the device
+ *                path and size are set in the struct tst_device variable
+ *                called tst_device. If $LTP_DEV variable exists in the test
+ *                environment the test attempts to use that device first and
+ *                only if that fails the test falls back to use loop devices.
+ *                This flag implies needs_tmpdir flag because loop device
+ *                backing files are created in the test temporary directory.
+ *
+ * @needs_checkpoints: Has to be set if the test wants to use checkpoint
+ *                     synchronization primitives.
+ *
+ * @needs_overlay: If set overlay filesystem is mounted on the top of the
+ *                 filesystem at tst_test.mntpoint.
+ *
+ * @format_device: Does all tst_test.needs_device would do and also formats
+ *                 the device with tst_test.dev_fs_type filesystem as well.
+ *
+ * @mount_device: Does all tst_test.format_device would do and also mounts the
+ *                device at tst_test.mntpoint.
+ *
+ * @needs_rofs: If set a read-only filesystem is mounted at tst_test.mntpoint.
+ *
+ * @child_needs_reinit: Has to be set if the test needs to call tst_reinit()
+ *                      from a process started by exec().
+ *
+ * @needs_devfs: If set the devfs is mounted at tst_test.mntpoint. This is
+ *               needed for tests that need to create device files since tmpfs
+ *               at /tmp is usually mounted with 'nodev' option.
+ *
+ * @restore_wallclock: Saves wall clock at the start of the test and restores
+ *                     it at the end with the help of monotonic timers.
+ *                     Testcases that modify system wallclock use this to
+ *                     restore the system to the previous state.
+ *
+ * @all_filesystems: If set the test is executed for all supported filesytems,
+ *                   i.e. filesystem that is supported by the kernel and has
+ *                   mkfs installed on the system. The filesystem is mounted at
+ *                   tst_test.tmpdir and filesytem details, e.g. type are set
+ *                   in the struct tst_device. Each execution is independent,
+ *                   that means that for each iteration tst_test.setup() is
+ *                   called at the test start and tst_test.cleanup() is called
+ *                   at the end and tst_brk() exit only test for a single
+ *                   filesystem. That especially means that calling
+ *                   tst_brk(TCONF, ...) in the test setup will skip the
+ *                   current filesystem.
+ *
+ * @skip_in_lockdown: Skip the test if kernel lockdown is enabled.
+ *
+ * @skip_in_secureboot: Skip the test if secureboot is enabled.
+ *
+ * @skip_in_compat: Skip the test if we are executing 32bit binary on a 64bit
+ *                  kernel, i.e. we are testing the kernel compat layer.
+ *
+ * @needs_hugetlbfs: If set hugetlbfs is mounted at tst_test.mntpoint.
+ *
+ * @skip_filesystems: A NULL terminated array of unsupported filesystems. The
+ *                    test reports TCONF if the filesystem to be tested is
+ *                    present in the array. This is especially useful to filter
+ *                    out unsupported filesystem when tst_test.all_filesystems
+ *                    is enabled.
+ *
+ * @min_cpus: Minimal number of online CPUs the test needs to run.
+ *
+ * @min_mem_avail: Minimal amount of available RAM memory in megabytes required
+ *                 for the test to run.
+ *
+ * @min_swap_avail: Minimal amount of available swap memory in megabytes
+ *                  required for the test to run.
+ *
+ * @hugepages: An interface to reserve hugepages prior running the test.
+ *             Request how many hugepages should be reserved in the global
+ *             pool and also if having hugepages is required for the test run
+ *             or not, i.e. if test should exit with TCONF if the requested
+ *             amount of hugepages cannot be reserved. If TST_REQUEST is set
+ *             the library will try it's best to reserve the hugepages and
+ *             return the number of available hugepages in tst_hugepages, which
+ *             may be 0 if there is no free memory or hugepages are not
+ *             supported at all. If TST_NEEDS the requested hugepages are
+ *             required for the test and the test exits if it couldn't be
+ *             required. It can also be used to disable hugepages by setting
+ *             .hugepages = {TST_NO_HUGEPAGES}. The test library restores the
+ *             original poll allocations after the test has finished.
+ *
+ * @taint_check: If set the test fails if kernel is tainted during the test run.
+ *               That means tst_taint_init() is called during the test setup
+ *               and tst_taint_check() at the end of the test. If all_filesystems
+ *               is set taint check will be performed after each iteration and
+ *               testing will be terminated by TBROK if taint is detected.
+ *
+ * @test_variants: If set denotes number of test variant, the test is executed
+ *                 variants times each time with tst_variant set to different
+ *                 number. This allows us to run the same test for different
+ *                 settings. The intended use is to test different syscall
+ *                 wrappers/variants but the API is generic and does not limit
+ *                 usage in any way.
+ *
+ * @dev_min_size: A minimal device size in megabytes.
+ *
+ * @dev_fs_type: If set overrides the default filesystem type for the device and
+ *               sets the tst_device.fs_type.
+ *
+ * @dev_fs_opts: A NULL terminated array of options passed to mkfs in the case
+ *               of 'tst_test.format_device'. These options are passed to mkfs
+ *               before the device path.
+ *
+ * @dev_extra_opts: A NULL terminated array of extra options passed to mkfs in
+ *                  the case of 'tst_test.format_device'. Extra options are
+ *                  passed to mkfs after the device path. Commonly the option
+ *                  after mkfs is the number of blocks and can be used to limit
+ *                  the filesystem not to use the whole block device.
+ *
+ * @mntpoint: A mount point where the test library mounts requested filesystem.
+ *            The directory is created by the library, the test must not create
+ *            it itself.
+ *
+ * @mnt_flags: MS_* flags passed to mount(2) when the test library mounts a
+ *             device in the case of 'tst_test.mount_device'.
+ *
+ * @mnt_data: The data passed to mount(2) when the test library mounts a device
+ *            in the case of 'tst_test.mount_device'.
+ *
+ * @max_runtime: Maximal test runtime in seconds. Any test that runs for more
+ *               than a second or two should set this and also use
+ *               tst_remaining_runtime() to exit when runtime was used up.
+ *               Tests may finish sooner, for example if requested number of
+ *               iterations was reached before the runtime runs out. If test
+ *               runtime cannot be know in advance it should be set to
+ *               TST_UNLIMITED_RUNTIME.
+ *
+ * @setup: Setup callback is called once at the start of the test in order to
+ *         prepare the test environment.
+ *
+ * @cleanup: Cleanup callback is either called at the end of the test, or in a
+ *           case that tst_brk() was called. That means that cleanup must be
+ *           able to handle all possible states the test can be in. This
+ *           usually means that we have to check if file descriptor was opened
+ *           before we attempt to close it in the setup, etc.
+ *
+ *
+ * @test: A main test function, only one of the tst_test.test and test_all can
+ *        be set. When this function is set the tst_test.tcnt must be set to a
+ *        positive integer and this function will be executed tcnt times
+ *        during a single test iteration. May be executed several times if test
+ *        was passed '-i' or '-d' command line parameters.
+ *
+ * @test_all: A main test function, only one of the tst_test.test and test_all
+ *            can be set. May be executed several times if test was passed '-i'
+ *            or '-d' command line parameters.
+ *
+ * @resource_files: A NULL terminated array of filenames that will be copied
+ *                  to the test temporary directory from the LTP datafiles
+ *                  directory.
+ *
+ * @needs_drivers: A NULL terminated array of kernel modules required to run
+ *                 the test. The module has to be build in or present in order
+ *                 for the test to run.
+ *
+ * @save_restore: A {} terminated array of /proc or /sys files that should
+ *                saved at the start of the test and restored at the end. See
+ *                tst_sys_conf_save() and struct tst_path_val for details.
+ *
+ * @ulimit: A {} terminated array of process limits RLIMIT_* to be adjusted for
+ *          the test.
+ *
+ * @needs_kconfigs: A NULL terminated array of kernel config options that are
+ *                  required for the test. All strings in the array have to be
+ *                  evaluated to true for the test to run. Boolean opearors
+ *                  and parenthesis are supported, e.g.
+ *                  "CONFIG_X86_INTEL_UMIP=y | CONFIG_X86_UIMP=y" is evaluated
+ *                  to true if at least one of the options is present.
+ *
+ * @bufs: A description of guarded buffers to be allocated for the test. Guarded
+ *        buffers are buffers with poisoned page allocated right before the start
+ *        of the buffer and canary right after the end of the buffer. See
+ *        struct tst_buffers and tst_buffer_alloc() for details.
+ *
+ * @caps: A {} terminated array of capabilities to change before the start of
+ *        the test. See struct tst_cap and tst_cap_setup() for details.
+ *
+ * @tags: A {} terminated array of test tags. See struct tst_tag for details.
+ *
+ * @needs_cmds: A NULL terminated array of commands required for the test to run.
+ *
+ * @needs_cgroup_ver: If set the test will run only if the specified cgroup
+ *                    version is present on the system.
+ *
+ * @needs_cgroup_ctrls: List of cgroup controllers the test needs to run.
+ */
+
+ struct tst_test {
 	unsigned int tcnt;
 
 	struct tst_option *options;
 
 	const char *min_kver;
 
-	/*
-	 * The supported_archs is a NULL terminated list of archs the test
-	 * does support.
-	 */
 	const char *const *supported_archs;
 
-	/* If set the test is compiled out */
 	const char *tconf_msg;
 
 	int needs_tmpdir:1;
@@ -186,182 +489,98 @@ struct tst_test {
 	int needs_devfs:1;
 	int restore_wallclock:1;
 
-	/*
-	 * If set the test function will be executed for all available
-	 * filesystems and the current filesystem type would be set in the
-	 * tst_device->fs_type.
-	 *
-	 * The test setup and cleanup are executed before/after __EACH__ call
-	 * to the test function.
-	 */
 	int all_filesystems:1;
 
 	int skip_in_lockdown:1;
 	int skip_in_secureboot:1;
 	int skip_in_compat:1;
 
-	/*
-	 * If set, the hugetlbfs will be mounted at .mntpoint.
-	 */
 	int needs_hugetlbfs:1;
 
-	/*
-	 * The skip_filesystems is a NULL terminated list of filesystems the
-	 * test does not support. It can also be used to disable whole class of
-	 * filesystems with a special keywords such as "fuse".
-	 */
 	const char *const *skip_filesystems;
 
-	/* Minimum number of online CPU required by the test */
 	unsigned long min_cpus;
-
-	/* Minimum size(MB) of MemAvailable required by the test */
 	unsigned long min_mem_avail;
-
-	/* Minimum size(MB) of SwapFree required by the test */
 	unsigned long min_swap_avail;
 
-	/*
-	 * Two policies for reserving hugepage:
-	 *
-	 * TST_REQUEST:
-	 *   It will try the best to reserve available huge pages and return the number
-	 *   of available hugepages in tst_hugepages, which may be 0 if hugepages are
-	 *   not supported at all.
-	 *
-	 * TST_NEEDS:
-	 *   This is an enforced requirement, LTP should strictly do hpages applying and
-	 *   guarantee the 'HugePages_Free' no less than pages which makes that test can
-	 *   use these specified numbers correctly. Otherwise, test exits with TCONF if
-	 *   the attempt to reserve hugepages fails or reserves less than requested.
-	 *
-	 * With success test stores the reserved hugepage number in 'tst_hugepages. For
-	 * the system without hugetlb supporting, variable 'tst_hugepages' will be set to 0.
-	 * If the hugepage number needs to be set to 0 on supported hugetlb system, please
-	 * use '.hugepages = {TST_NO_HUGEPAGES}'.
-	 *
-	 * Also, we do cleanup and restore work for the hpages resetting automatically.
-	 */
 	struct tst_hugepage hugepages;
 
-	/*
-	 * If set to non-zero, call tst_taint_init(taint_check) during setup
-	 * and check kernel taint at the end of the test. If all_filesystems
-	 * is non-zero, taint check will be performed after each FS test and
-	 * testing will be terminated by TBROK if taint is detected.
-	 */
 	unsigned int taint_check;
 
-	/*
-	 * If set non-zero denotes number of test variant, the test is executed
-	 * variants times each time with tst_variant set to different number.
-	 *
-	 * This allows us to run the same test for different settings. The
-	 * intended use is to test different syscall wrappers/variants but the
-	 * API is generic and does not limit the usage in any way.
-	 */
 	unsigned int test_variants;
 
-	/* Minimal device size in megabytes */
 	unsigned int dev_min_size;
 
-	/* Device filesystem type override NULL == default */
 	const char *dev_fs_type;
 
-	/* Options passed to SAFE_MKFS() when format_device is set */
 	const char *const *dev_fs_opts;
 	const char *const *dev_extra_opts;
 
-	/* Device mount options, used if mount_device is set */
 	const char *mntpoint;
 	unsigned int mnt_flags;
 	void *mnt_data;
 
-	/*
-	 * Maximal test runtime in seconds.
-	 *
-	 * Any test that runs for more than a second or two should set this and
-	 * also use tst_remaining_runtime() to exit when runtime was used up.
-	 * Tests may finish sooner, for example if requested number of
-	 * iterations was reached before the runtime runs out.
-	 *
-	 * If test runtime cannot be know in advance it should be set to
-	 * TST_UNLIMITED_RUNTIME.
-	 */
 	int max_runtime;
 
 	void (*setup)(void);
 	void (*cleanup)(void);
-
 	void (*test)(unsigned int test_nr);
 	void (*test_all)(void);
 
-	/* Syscall name used by the timer measurement library */
 	const char *scall;
-
-	/* Sampling function for timer measurement testcases */
 	int (*sample)(int clk_id, long long usec);
 
-	/* NULL terminated array of resource file names */
 	const char *const *resource_files;
-
-	/* NULL terminated array of needed kernel drivers */
 	const char * const *needs_drivers;
 
-	/*
-	 * {NULL, NULL} terminated array of (/proc, /sys) files to save
-	 * before setup and restore after cleanup
-	 */
 	const struct tst_path_val *save_restore;
 
-	/*
-	 * {} terminated array of ulimit resource type and value.
-	 */
 	const struct tst_ulimit_val *ulimit;
 
-	/*
-	 * NULL terminated array of kernel config options required for the
-	 * test.
-	 */
 	const char *const *needs_kconfigs;
 
-	/*
-	 * {NULL, NULL} terminated array to be allocated buffers.
-	 */
 	struct tst_buffers *bufs;
 
-	/*
-	 * {NULL, NULL} terminated array of capability settings
-	 */
 	struct tst_cap *caps;
 
-	/*
-	 * {NULL, NULL} terminated array of tags.
-	 */
 	const struct tst_tag *tags;
 
-	/* NULL terminated array of required commands */
 	const char *const *needs_cmds;
 
-	/* Requires a particular CGroup API version. */
 	const enum tst_cg_ver needs_cgroup_ver;
 
 	/* {} terminated array of required CGroup controllers */
 	const char *const *needs_cgroup_ctrls;
 };
 
-/*
- * Runs tests.
+/**
+ * tst_run_tcases() - Entry point to the test library.
+ *
+ * @argc: An argc that was passed to the main().
+ * @argv: An argv that was passed to the main().
+ * @self: The test description and callbacks packed in the struct tst_test
+ *        structure.
+ *
+ * A main() function which calls this function is added to each test
+ * automatically by including the tst_test.h header. The test has to define the
+ * struct tst_test called tst_test.
+ *
+ * This fuction does not return, i.e. calls exit() after the test has finished.
  */
 void tst_run_tcases(int argc, char *argv[], struct tst_test *self)
                     __attribute__ ((noreturn));
 
 #define IPC_ENV_VAR "LTP_IPC_PATH"
 
-/*
- * Does library initialization for child processes started by exec()
+/**
+ * tst_reinit() - Reinitialize the test library.
  *
- * The LTP_IPC_PATH variable must be passed to the program environment.
+ * In a cases where a test child process calls exec() it no longer can access
+ * the test library shared memory and therefore use the test reporting
+ * functions, checkpoint library, etc. This function reinitializes the test
+ * library so that it can be used again.
+ *
+ * @important The LTP_IPC_PATH variable must be passed to the program environment.
  */
 void tst_reinit(void);
 
@@ -416,6 +635,12 @@ int main(int argc, char *argv[])
 
 #endif /* TST_NO_DEFAULT_MAIN */
 
+/**
+ * TST_TEST_TCONF() - Exit tests with a TCONF message.
+ *
+ * This macro is used in test that couldn't be compiled either because current
+ * CPU architecture is unsupported or because of missing development libraries.
+ */
 #define TST_TEST_TCONF(message)                                 \
         static struct tst_test test = { .tconf_msg = message  } \
 
-- 
2.43.2



More information about the ltp mailing list