[LTP] [PATCH 0/3] Complete the documentation adding missing headers

[LTP] [PATCH 0/3] Complete the documentation adding missing headers

[Andrea Cervesato]

This conversion and fix has been done with Claude Code.
Complete this review before adding these changes:

https://patchwork.ozlabs.org/project/ltp/list/?series=506891

- add missing headers
- convert documentation from doxygen to kernel-doc
- add SAFE_* macro section

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
Andrea Cervesato (3):
      doc: Add missing API references to api_c_tests.rst
      doc: Complete struct tst_test table and shell API docs
      doc: Add SAFE_* macros reference page

 doc/developers/api_c_tests.rst     |  71 ++++++--
 doc/developers/api_safe_macros.rst | 326 +++++++++++++++++++++++++++++++++++++
 doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++
 doc/developers/writing_tests.rst   |  28 +++-
 doc/index.rst                      |   4 +
 include/tse_uinput.h               |  30 ++--
 include/tst_clone.h                |  23 ++-
 include/tst_device.h               | 165 ++++++++++++-------
 include/tst_fuzzy_sync.h           | 163 +++++++++++++------
 include/tst_hugepage.h             |  35 ++--
 include/tst_kconfig.h              |  77 ++++-----
 include/tst_taint.h                |  32 ++--
 12 files changed, 896 insertions(+), 221 deletions(-)
---
base-commit: 2ee13a3772ae4942597afa615b3cb411d380db86
change-id: 20260601-doc_add_missing_headers-ca51d98d32ac

Best regards,
-- 
Andrea Cervesato <andrea.cervesato@suse.com>


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

[LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Fix broken kernel-doc reference to renamed tse_numa.h header and add
kernel-doc directives for 12 headers that were missing from the C API
documentation page:

  tst_clone.h, tst_device.h, tst_fs.h, tst_fuzzy_sync.h,
  tst_hugepage.h, tst_kconfig.h, tst_memutils.h, tst_safe_file_ops.h,
  tst_taint.h, tse_numa.h, tse_swap.h, tse_uinput.h

Convert plain comments to kernel-doc format in tst_device.h,
tst_hugepage.h, tst_clone.h, and tst_taint.h so the documentation
builder can extract them.

Sort all sections alphabetically under LTP C API.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 doc/developers/api_c_tests.rst |  71 +++++++++++++-----
 include/tse_uinput.h           |  30 ++++----
 include/tst_clone.h            |  23 ++++--
 include/tst_device.h           | 165 ++++++++++++++++++++++++++---------------
 include/tst_fuzzy_sync.h       | 163 ++++++++++++++++++++++++++++------------
 include/tst_hugepage.h         |  35 ++++++---
 include/tst_kconfig.h          |  77 +++++++++----------
 include/tst_taint.h            |  32 +++-----
 8 files changed, 377 insertions(+), 219 deletions(-)

diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
index 65cf6d6cd0be5cb4cd9c986e09df021071d968f1..1e9e595dde24755817396deb2d78ae0a7c56a29a 100644
--- a/doc/developers/api_c_tests.rst
+++ b/doc/developers/api_c_tests.rst
@@ -7,46 +7,68 @@
 LTP C API
 =========
 
-Core LTP API
-------------
-.. kernel-doc:: ../../include/tst_res_flags.h
-.. kernel-doc:: ../../include/tst_test.h
-
-Test macros
------------
-.. kernel-doc:: ../../include/tst_test_macros.h
-
 Capabilities
 ------------
 .. kernel-doc:: ../../include/tst_capability.h
 
 Checkpoints
 -----------
-
 .. kernel-doc:: ../../include/tst_checkpoint.h
 
+Clone
+-----
+.. kernel-doc:: ../../include/tst_clone.h
+
 Commands
 --------
 .. kernel-doc:: ../../include/tst_cmd.h
 
+Core LTP API
+------------
+.. kernel-doc:: ../../include/tst_res_flags.h
+.. kernel-doc:: ../../include/tst_test.h
+
 Crypto
 ------
 .. kernel-doc:: ../../include/tst_crypto.h
 .. kernel-doc:: ../../include/tst_af_alg.h
 
+Devices
+-------
+.. kernel-doc:: ../../include/tst_device.h
+
+Filesystems
+-----------
+.. kernel-doc:: ../../include/tst_fs.h
+
+Fuzzy sync
+----------
+.. kernel-doc:: ../../include/tst_fuzzy_sync.h
+
 Guarded buffers
 ---------------
 .. kernel-doc:: ../../include/tst_buffers.h
 
+Hugepages
+---------
+.. kernel-doc:: ../../include/tst_hugepage.h
+
 Kernel
 ------
 .. kernel-doc:: ../../include/tst_kernel.h
 .. kernel-doc:: ../../include/tst_kvercmp.h
 
-Process state
--------------
+Kernel configuration
+--------------------
+.. kernel-doc:: ../../include/tst_kconfig.h
 
-.. kernel-doc:: ../../include/tst_process_state.h
+Kernel taint
+------------
+.. kernel-doc:: ../../include/tst_taint.h
+
+Memory
+------
+.. kernel-doc:: ../../include/tst_memutils.h
 
 NUMA
 ----
@@ -54,17 +76,32 @@ NUMA
 
 Option parsing
 --------------
-
 .. kernel-doc:: ../../include/tst_parse.h
 
+Process state
+-------------
+.. kernel-doc:: ../../include/tst_process_state.h
+
+Safe file operations
+--------------------
+.. kernel-doc:: ../../include/tst_safe_file_ops.h
+
 Saving and restoring /proc|sys values
 -------------------------------------
 .. kernel-doc:: ../../include/tst_sys_conf.h
 
+Swap
+----
+.. kernel-doc:: ../../include/tse_swap.h
+
 Temporary directory
 -------------------
 .. kernel-doc:: ../../include/tst_tmpdir.h
 
-LTP libraries
--------------
-.. kernel-doc:: ../../include/tse_swap.h
+Test macros
+-----------
+.. kernel-doc:: ../../include/tst_test_macros.h
+
+Uinput
+------
+.. kernel-doc:: ../../include/tse_uinput.h
diff --git a/include/tse_uinput.h b/include/tse_uinput.h
index e336de780b1c9ce2d9cd2977e15b287cadfb76a4..272cf16483643b5552f3f88a9b87211a6863c8f5 100644
--- a/include/tse_uinput.h
+++ b/include/tse_uinput.h
@@ -7,40 +7,40 @@
 #define TSE_UINPUT_H__
 
 /**
- * Tries to open the uinput device.
+ * open_uinput() - Try to open the uinput device.
  *
- * Returns file descriptor on success, -1 on failure.
+ * Return: File descriptor on success, -1 on failure.
  */
 int open_uinput(void);
 
 /**
- * Creates virtual input device.
- *
- * @fd File descriptor returned by open_uinput().
+ * create_input_device() - Create a virtual input device.
+ * @fd: File descriptor returned by open_uinput().
  */
 void create_input_device(int fd);
 
 /**
- * Parses /proc/bus/input/devices and returns the strings for our virtual device.
- * If passing 'H' to it, it returns HANDLERS string. If passing 'S' to it, it
- * returns SYSFS string.
+ * get_input_field_value() - Get a field string for the virtual device.
+ * @field: Field character ('H' for handlers, 'S' for sysfs).
+ *
+ * Parses /proc/bus/input/devices and returns the string for our
+ * virtual device matching the requested field.
  *
- * Returns newly allocated string, or NULL in a case of failure.
+ * Return: Newly allocated string, or NULL on failure.
  */
 char *get_input_field_value(char field);
 
 /**
- * Sets up the virtual device to appear as a mouse, this must be called before
- * the call to create_input_device().
+ * setup_mouse_events() - Set up the virtual device as a mouse.
+ * @fd: File descriptor as returned by open_uinput().
  *
- * @fd File descriptor as returned by open_uinput().
+ * Must be called before create_input_device().
  */
 void setup_mouse_events(int fd);
 
 /**
- * Destroys virtual input device.
- *
- * @fd File descriptor returned by open_uinput().
+ * destroy_input_device() - Destroy a virtual input device.
+ * @fd: File descriptor returned by open_uinput().
  */
 void destroy_input_device(int fd);
 
diff --git a/include/tst_clone.h b/include/tst_clone.h
index a07689c78f575ae6ca87c0952b3e48b3a626012c..1898c58f819f8eadc1468d2d2b86a9102f679eb9 100644
--- a/include/tst_clone.h
+++ b/include/tst_clone.h
@@ -9,7 +9,13 @@
 
 #ifdef TST_TEST_H__
 
-/* The parts of clone3's clone_args we support */
+/**
+ * struct tst_clone_args - Arguments for tst_clone().
+ * @flags: Clone flags (e.g. CLONE_NEWNS, CLONE_NEWPID).
+ * @pidfd: If CLONE_PIDFD is set, stores the pidfd here.
+ * @exit_signal: Signal sent to the parent when the child exits.
+ * @cgroup: Target cgroup fd (requires CLONE_INTO_CGROUP).
+ */
 struct tst_clone_args {
 	uint64_t flags;
 	uint64_t pidfd;
@@ -17,15 +23,16 @@ struct tst_clone_args {
 	uint64_t cgroup;
 };
 
-/* clone3 with fallbacks to clone when possible. Be aware that it
- * returns -1 if clone3 fails (except ENOSYS), but -2 if clone fails.
+/**
+ * tst_clone() - Create a child process via clone3 with clone fallback.
+ * @args: Clone arguments.
  *
- * Without CLONE_VM this acts like fork so you may want to set
- * tst_test.forks_child (safe_clone requires this).
+ * Without CLONE_VM this acts like fork(); set tst_test.forks_child
+ * accordingly (safe_clone requires it). Set exit_signal to SIGCHLD
+ * for tst_reap_children.
  *
- * You should set exit_signal to SIGCHLD for
- * tst_reap_children. Otherwise you must call wait with the
- * appropriate parameters.
+ * Return: Child PID in the parent, 0 in the child, -1 on clone3 failure
+ *         (except ENOSYS), -2 on clone failure.
  */
 pid_t tst_clone(const struct tst_clone_args *args);
 
diff --git a/include/tst_device.h b/include/tst_device.h
index 85150670de903f5d411efa255d75df4099ea1dd2..405c37423fe0737bd6fc3dc3138dee97f7a52db9 100644
--- a/include/tst_device.h
+++ b/include/tst_device.h
@@ -11,123 +11,170 @@
 #include <stdint.h>
 #include <sys/stat.h>
 
+/**
+ * struct tst_device - Block device used by a test.
+ * @dev: Device path (e.g. /dev/loop0).
+ * @fs_type: Filesystem type used to format the device.
+ * @size: Device size in bytes.
+ * @is_fuse: Set by the library when the mounted filesystem is FUSE-based.
+ */
 struct tst_device {
 	const char *dev;
 	const char *fs_type;
 	uint64_t size;
-	/* If device was mounted by the test library this flag is set for fuse fileystems. */
 	int is_fuse;
 };
 
 /*
- * Automatically initialized if test.needs_device is set.
+ * tst_device - Pointer to the test block device.
+ *
+ * Automatically initialized if tst_test.needs_device is set.
  */
 extern struct tst_device *tst_device;
 
-/*
- * Just like umount() but retries several times on failure.
- * @path: Path to umount
+/**
+ * tst_umount() - Unmount a filesystem, retrying on transient failures.
+ * @path: Mount point to unmount.
+ *
+ * Return: 0 on success, -1 on failure.
  */
 int tst_umount(const char *path);
 
-/*
- * Verifies if an earlier mount is successful or not.
- * @path: Mount path to verify
+/**
+ * tst_mount_has_opt() - Check if a mount point has a specific mount option.
+ * @path: Mount point to check.
+ * @opt: Mount option to look for.
+ *
+ * Return: 1 if found, 0 otherwise.
  */
 int tst_mount_has_opt(const char *path, const char *opt);
+/**
+ * tst_is_mounted() - Check if a path is a mount point.
+ * @path: Path to check.
+ *
+ * Return: 1 if mounted, 0 otherwise.
+ */
 int tst_is_mounted(const char *path);
+
+/**
+ * tst_is_mounted_ro() - Check if a path is mounted read-only.
+ * @path: Path to check.
+ *
+ * Return: 1 if mounted read-only, 0 otherwise.
+ */
 int tst_is_mounted_ro(const char *path);
+
+/**
+ * tst_is_mounted_rw() - Check if a path is mounted read-write.
+ * @path: Path to check.
+ *
+ * Return: 1 if mounted read-write, 0 otherwise.
+ */
 int tst_is_mounted_rw(const char *path);
+
+/**
+ * tst_is_mounted_at_tmpdir() - Check if a path is mounted at the test tmpdir.
+ * @path: Path to check.
+ *
+ * Return: 1 if mounted at tmpdir, 0 otherwise.
+ */
 int tst_is_mounted_at_tmpdir(const char *path);
 
-/*
- * Clears a first few blocks of the device. This is needed when device has
- * already been formatted with a filesystems, subset of mkfs.foo utils aborts
- * the operation if it finds a filesystem signature there.
+/**
+ * tst_clear_device() - Wipe filesystem signatures from a block device.
+ * @dev: Device path.
+ *
+ * Clears the first few blocks of the device so that mkfs utilities do not
+ * refuse to reformat it. Called automatically by tst_mkfs().
  *
- * Note that this is called from tst_mkfs() automatically, so you probably will
- * not need to use this from the test yourself.
+ * Return: 0 on success, -1 on failure.
  */
 int tst_clear_device(const char *dev);
 
-/*
- * Finds a free loop device for use and returns the free loopdev minor(-1 for no
- * free loopdev). If path is non-NULL, it will be filled with free loopdev path.
+/**
+ * tst_find_free_loopdev() - Find an unused loop device.
+ * @path: If non-NULL, filled with the loop device path.
+ * @path_len: Size of @path buffer.
  *
+ * Return: The loop device minor number, or -1 if none is free.
  */
 int tst_find_free_loopdev(char *path, size_t path_len);
 
-/*
- * Attaches a file to a loop device.
+/**
+ * tst_attach_device() - Attach a file to a loop device.
+ * @dev_path: Path to the loop device (e.g. /dev/loop0).
+ * @file_path: Path to a file (e.g. disk.img).
  *
- * @dev_path Path to the loop device e.g. /dev/loop0
- * @file_path Path to a file e.g. disk.img
- * @return Zero on success, non-zero otherwise.
+ * Return: Zero on success, non-zero otherwise.
  */
 int tst_attach_device(const char *dev_path, const char *file_path);
 
-/*
- * Get size (in MB) of the given device
+/**
+ * tst_get_device_size() - Get device size in megabytes.
+ * @dev_path: Device path.
+ *
+ * Return: Device size in MB.
  */
 uint64_t tst_get_device_size(const char *dev_path);
 
-/*
- * Detaches a file from a loop device by a fd.
+/**
+ * tst_detach_device_by_fd() - Detach a file from a loop device using an fd.
+ * @dev_path: Path to the loop device (e.g. /dev/loop0).
+ * @dev_fd: Open fd for the loop device; set to -1 on completion.
  *
- * The dev_fd needs to be the last file descriptor opened for the device. Call
- * to this function will close dev_fd and set it to -1 in order to avoid
- * incorrect usage after it's closed.
+ * The @dev_fd must be the last file descriptor opened for the device.
  *
- * @dev_path Path to the loop device e.g. /dev/loop0
- * @dev_fd An open fd for the loop device, set to -1 after the completion.
- * @return Zero on succes, non-zero otherwise.
+ * Return: Zero on success, non-zero otherwise.
  */
 int tst_detach_device_by_fd(const char *dev_path, int *dev_fd);
 
-/*
- * Detaches a file from a loop device.
+/**
+ * tst_detach_device() - Detach a file from a loop device.
+ * @dev_path: Path to the loop device (e.g. /dev/loop0).
  *
- * @dev_path Path to the loop device e.g. /dev/loop0
- * @return Zero on succes, non-zero otherwise.
+ * Opens the device internally and calls tst_detach_device_by_fd(). If the
+ * device fd is already open, use tst_detach_device_by_fd() instead.
  *
- * Internally this function opens the device and calls
- * tst_detach_device_by_fd(). If you keep device file descriptor open you
- * have to call the by_fd() variant since having the device open twice will
- * prevent it from being detached.
+ * Return: Zero on success, non-zero otherwise.
  */
 int tst_detach_device(const char *dev_path);
 
-/*
- * To avoid FS deferred IO metadata/cache interference, so we do syncfs
- * simply before the tst_dev_bytes_written invocation. For easy to use,
- * we create this inline function tst_dev_sync.
+/**
+ * tst_dev_sync() - Sync filesystem to avoid deferred IO interference.
+ * @fd: Open file descriptor on the filesystem to sync.
+ *
+ * Return: 0 on success, -1 on failure.
  */
 int tst_dev_sync(int fd);
 
-/*
- * Reads test block device stat file and returns the bytes written since the
- * last call of this function.
- * @dev: test block device
+/**
+ * tst_dev_bytes_written() - Get bytes written to a block device since last call.
+ * @dev: Test block device path.
+ *
+ * Return: Number of bytes written since the previous invocation.
  */
 unsigned long tst_dev_bytes_written(const char *dev);
 
-/*
- * Find the file or path belongs to which block dev
- * @path       Path to find the backing dev
- * @dev        The buffer to store the block dev in
- * @dev_size   The length of the block dev buffer
+/**
+ * tst_find_backing_dev() - Find the block device backing a path.
+ * @path: Path to look up.
+ * @dev: Buffer to store the block device path.
+ * @dev_size: Size of @dev buffer.
  */
 void tst_find_backing_dev(const char *path, char *dev, size_t dev_size);
 
-/*
- * Stat the device mounted on a given path.
+/**
+ * tst_stat_mount_dev() - Stat the device mounted at a given path.
+ * @mnt_path: Mount point path.
+ * @st: Stat buffer to fill.
  */
 void tst_stat_mount_dev(const char *const mnt_path, struct stat *const st);
 
-/*
- * Returns the size of a physical device block size for the specific path
- * @path   Path to find the block size
- * @return Size of the block size
+/**
+ * tst_dev_block_size() - Get physical block size for a device.
+ * @path: Path on the filesystem to query.
+ *
+ * Return: Physical block size in bytes.
  */
 int tst_dev_block_size(const char *path);
 
diff --git a/include/tst_fuzzy_sync.h b/include/tst_fuzzy_sync.h
index b22364cab2bdcfbc62585dc6fd142d10489a0528..503a0535e5611c9c01ced85dfab5e63ca5246c76 100644
--- a/include/tst_fuzzy_sync.h
+++ b/include/tst_fuzzy_sync.h
@@ -2,8 +2,7 @@
 /*
  * Copyright (c) 2017-2018 Richard Palethorpe <rpalethorpe@suse.com>
  */
-/**
- * @file tst_fuzzy_sync.h
+/*
  * Fuzzy Synchronisation - abbreviated to fzsync
  *
  * This library is intended to help reproduce race conditions by synchronising
@@ -83,7 +82,31 @@ struct tst_fzsync_stat {
 };
 
 /**
- * The state of a two way synchronisation or race.
+ * struct tst_fzsync_pair - The state of a two way synchronisation or race.
+ * @avg_alpha: Rate at which old diff samples are forgotten (default 0.25).
+ * @a_start: Internal; Thread A start time.
+ * @b_start: Internal; Thread B start time.
+ * @a_end: Internal; Thread A end time.
+ * @b_end: Internal; Thread B end time.
+ * @diff_ss: Internal; Avg. difference between a_start and b_start.
+ * @diff_sa: Internal; Avg. difference between a_start and a_end.
+ * @diff_sb: Internal; Avg. difference between b_start and b_end.
+ * @diff_ab: Internal; Avg. difference between a_end and b_end.
+ * @spins: Internal; Number of spins while waiting for the slower thread.
+ * @spins_avg: Internal; Average spins stat.
+ * @delay: Internal; Number of spins to use in the delay.
+ * @delay_bias: Internal; Bias added to delay.
+ * @sampling: Internal; Sampling state or remaining count.
+ * @min_samples: Minimum samples before random delays are calculated (default 1024).
+ * @max_dev_ratio: Maximum allowed proportional average deviation (default 0.1).
+ * @a_cntr: Internal; Atomic counter used by fzsync_pair_wait().
+ * @b_cntr: Internal; Atomic counter used by fzsync_pair_wait().
+ * @exit: Internal; Used by tst_fzsync_pair_exit() and fzsync_pair_wait().
+ * @exec_time_start: Internal; Test time remaining on tst_fzsync_pair_reset().
+ * @exec_loops: Maximum number of iterations to execute.
+ * @exec_loop: Internal; Current loop index.
+ * @thread_b: Internal; The second thread or 0.
+ * @yield_in_wait: Yield CPU while waiting on single-core machines.
  *
  * This contains all the necessary state for approximately synchronising two
  * sections of code in different threads.
@@ -96,53 +119,53 @@ struct tst_fzsync_stat {
  * Internal fields should only be accessed by library functions.
  */
 struct tst_fzsync_pair {
-	/**
+	/*
 	 * The rate at which old diff samples are forgotten
 	 *
 	 * Defaults to 0.25.
 	 */
 	float avg_alpha;
-	/** Internal; Thread A start time */
+	/* Internal; Thread A start time */
 	struct timespec a_start;
-	/** Internal; Thread B start time */
+	/* Internal; Thread B start time */
 	struct timespec b_start;
-	/** Internal; Thread A end time */
+	/* Internal; Thread A end time */
 	struct timespec a_end;
-	/** Internal; Thread B end time */
+	/* Internal; Thread B end time */
 	struct timespec b_end;
-	/** Internal; Avg. difference between a_start and b_start */
+	/* Internal; Avg. difference between a_start and b_start */
 	struct tst_fzsync_stat diff_ss;
-	/** Internal; Avg. difference between a_start and a_end */
+	/* Internal; Avg. difference between a_start and a_end */
 	struct tst_fzsync_stat diff_sa;
-	/** Internal; Avg. difference between b_start and b_end */
+	/* Internal; Avg. difference between b_start and b_end */
 	struct tst_fzsync_stat diff_sb;
-	/** Internal; Avg. difference between a_end and b_end */
+	/* Internal; Avg. difference between a_end and b_end */
 	struct tst_fzsync_stat diff_ab;
-	/** Internal; Number of spins while waiting for the slower thread */
+	/* Internal; Number of spins while waiting for the slower thread */
 	int spins;
 	struct tst_fzsync_stat spins_avg;
-	/**
+	/*
 	 * Internal; Number of spins to use in the delay.
 	 *
 	 * A negative value delays thread A and a positive delays thread B.
 	 */
 	int delay;
 	int delay_bias;
-	/**
+	/*
 	 *  Internal; The number of samples left or the sampling state.
 	 *
 	 *  A positive value is the number of remaining mandatory
 	 *  samples. Zero or a negative indicate some other state.
 	 */
 	int sampling;
-	/**
+	/*
 	 * The Minimum number of statistical samples which must be collected.
 	 *
 	 * The minimum number of iterations which must be performed before a
 	 * random delay can be calculated. Defaults to 1024.
 	 */
 	int min_samples;
-	/**
+	/*
 	 * The maximum allowed proportional average deviation.
 	 *
 	 * A value in the range (0, 1) which gives the maximum average
@@ -154,25 +177,25 @@ struct tst_fzsync_pair {
 	 */
 	float max_dev_ratio;
 
-	/** Internal; Atomic counter used by fzsync_pair_wait() */
+	/* Internal; Atomic counter used by fzsync_pair_wait() */
 	tst_atomic_t a_cntr;
-	/** Internal; Atomic counter used by fzsync_pair_wait() */
+	/* Internal; Atomic counter used by fzsync_pair_wait() */
 	tst_atomic_t b_cntr;
-	/** Internal; Used by tst_fzsync_pair_exit() and fzsync_pair_wait() */
+	/* Internal; Used by tst_fzsync_pair_exit() and fzsync_pair_wait() */
 	tst_atomic_t exit;
-	/** Internal; The test time remaining on tst_fzsync_pair_reset() */
+	/* Internal; The test time remaining on tst_fzsync_pair_reset() */
 	float exec_time_start;
-	/**
+	/*
 	 * The maximum number of iterations to execute during the test
 	 *
 	 * Defaults to a large number, but not too large.
 	 */
 	int exec_loops;
-	/** Internal; The current loop index  */
+	/* Internal; The current loop index  */
 	int exec_loop;
-	/** Internal; The second thread or 0 */
+	/* Internal; The second thread or 0 */
 	pthread_t thread_b;
-	/**
+	/*
 	 * The flag indicates single core machines or not
 	 *
 	 * If running on single core machines, it would take considerable
@@ -191,7 +214,8 @@ struct tst_fzsync_pair {
 		tst_brk(TBROK, #param " is more than the upper bound " #hi);  \
 	} while (0)
 /**
- * Ensures that any Fuzzy Sync parameters are properly set
+ * tst_fzsync_pair_init() - Ensure Fuzzy Sync parameters are properly set.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  *
@@ -213,7 +237,8 @@ static inline void tst_fzsync_pair_init(struct tst_fzsync_pair *pair)
 #undef CHK
 
 /**
- * Exit and join thread B if necessary.
+ * tst_fzsync_pair_cleanup() - Exit and join thread B if necessary.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  *
@@ -231,7 +256,8 @@ static inline void tst_fzsync_pair_cleanup(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Zero some stat fields
+ * tst_init_stat() - Zero some stat fields.
+ * @s: Stat structure to zero.
  *
  * @relates tst_fzsync_stat
  */
@@ -242,7 +268,9 @@ static inline void tst_init_stat(struct tst_fzsync_stat *s)
 }
 
 /**
- * Reset or initialise fzsync.
+ * tst_fzsync_pair_reset() - Reset or initialise fzsync.
+ * @pair: Fuzzy sync pair.
+ * @run_b: Thread B function pointer.
  *
  * @relates tst_fzsync_pair
  * @param pair The state structure initialised with TST_FZSYNC_PAIR_INIT.
@@ -285,7 +313,10 @@ static inline void tst_fzsync_pair_reset(struct tst_fzsync_pair *pair,
 }
 
 /**
- * Print stat
+ * tst_fzsync_stat_info() - Print stat.
+ * @stat: Stat to print.
+ * @unit: Unit string.
+ * @name: Name string.
  *
  * @relates tst_fzsync_stat
  */
@@ -298,7 +329,8 @@ static inline void tst_fzsync_stat_info(struct tst_fzsync_stat stat,
 }
 
 /**
- * Print some synchronisation statistics
+ * tst_fzsync_pair_info() - Print some synchronisation statistics.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  */
@@ -313,7 +345,10 @@ static inline void tst_fzsync_pair_info(struct tst_fzsync_pair *pair)
 	tst_fzsync_stat_info(pair->spins_avg, "  ", "spins");
 }
 
-/** Wraps clock_gettime */
+/**
+ * tst_fzsync_time() - Wrap clock_gettime.
+ * @t: Timespec to fill.
+ */
 static inline void tst_fzsync_time(struct timespec *t)
 {
 #ifdef CLOCK_MONOTONIC_RAW
@@ -324,7 +359,12 @@ static inline void tst_fzsync_time(struct timespec *t)
 }
 
 /**
- * Exponential moving average
+ * tst_exp_moving_avg() - Exponential moving average.
+ * @alpha: Smoothing factor.
+ * @sample: New sample value.
+ * @prev_avg: Previous average.
+ *
+ * Return: New average.
  *
  * @param alpha The preference for recent samples over old ones.
  * @param sample The current sample
@@ -340,7 +380,10 @@ static inline float tst_exp_moving_avg(float alpha,
 }
 
 /**
- * Update a stat with a new sample
+ * tst_upd_stat() - Update a stat with a new sample.
+ * @s: Stat structure.
+ * @alpha: Smoothing factor.
+ * @sample: New sample value.
  *
  * @relates tst_fzsync_stat
  */
@@ -355,7 +398,11 @@ static inline void tst_upd_stat(struct tst_fzsync_stat *s,
 }
 
 /**
- * Update a stat with a new diff sample
+ * tst_upd_diff_stat() - Update a stat with a new diff sample.
+ * @s: Stat structure.
+ * @alpha: Smoothing factor.
+ * @t1: First timespec.
+ * @t2: Second timespec.
  *
  * @relates tst_fzsync_stat
  */
@@ -368,10 +415,11 @@ static inline void tst_upd_diff_stat(struct tst_fzsync_stat *s,
 }
 
 /**
- * Calculate various statistics and the delay
+ * tst_fzsync_pair_update() - Calculate various statistics and the delay.
+ * @pair: Fuzzy sync pair.
  *
  * This function helps create the fuzz in fuzzy sync. Imagine we have the
- * following timelines in threads A and B:
+ * following timelines in threads A and B::
  *
  *  start_race_a
  *      ^                    end_race_a (a)
@@ -398,7 +446,7 @@ static inline void tst_upd_diff_stat(struct tst_fzsync_stat *s,
  * probability of hitting the race condition is close to zero. To solve this
  * scenario (and others) a randomised delay is introduced before the syscalls
  * in A and B. Given enough time the following should happen where the exit
- * paths are now synchronised:
+ * paths are now synchronised::
  *
  *  start_race_a
  *      ^                    end_race_a (a)
@@ -510,7 +558,12 @@ static inline void tst_fzsync_pair_update(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Wait for the other thread
+ * tst_fzsync_pair_wait() - Wait for the other thread.
+ * @our_cntr: Our atomic counter.
+ * @other_cntr: Other thread's atomic counter.
+ * @spins: Spin counter.
+ * @exit: Exit flag.
+ * @yield_in_wait: Whether to yield while waiting.
  *
  * @relates tst_fzsync_pair
  * @param our_cntr The counter for the thread we are on
@@ -598,7 +651,8 @@ static inline void tst_fzsync_pair_wait(int *our_cntr,
 }
 
 /**
- * Wait in thread A
+ * tst_fzsync_wait_a() - Wait in thread A.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_pair_wait
@@ -610,7 +664,8 @@ static inline void tst_fzsync_wait_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Wait in thread B
+ * tst_fzsync_wait_b() - Wait in thread B.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_pair_wait
@@ -622,7 +677,10 @@ static inline void tst_fzsync_wait_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Decide whether to continue running thread A
+ * tst_fzsync_run_a() - Decide whether to continue running thread A.
+ * @pair: Fuzzy sync pair.
+ *
+ * Return: Non-zero to continue, 0 to stop.
  *
  * @relates tst_fzsync_pair
  *
@@ -667,7 +725,10 @@ static inline int tst_fzsync_run_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Decide whether to continue running thread B
+ * tst_fzsync_run_b() - Decide whether to continue running thread B.
+ * @pair: Fuzzy sync pair.
+ *
+ * Return: Non-zero to continue, 0 to stop.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_run_a
@@ -679,7 +740,8 @@ static inline int tst_fzsync_run_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the start of a race region in thread A
+ * tst_fzsync_start_race_a() - Mark the start of a race region in thread A.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  *
@@ -719,7 +781,8 @@ static inline void tst_fzsync_start_race_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the end of a race region in thread A
+ * tst_fzsync_end_race_a() - Mark the end of a race region in thread A.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_start_race_a
@@ -732,7 +795,8 @@ static inline void tst_fzsync_end_race_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the start of a race region in thread B
+ * tst_fzsync_start_race_b() - Mark the start of a race region in thread B.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_start_race_a
@@ -758,7 +822,8 @@ static inline void tst_fzsync_start_race_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the end of a race region in thread B
+ * tst_fzsync_end_race_b() - Mark the end of a race region in thread B.
+ * @pair: Fuzzy sync pair.
  *
  * @relates tst_fzsync_pair
  * @sa tst_fzsync_start_race_a
@@ -771,7 +836,9 @@ static inline void tst_fzsync_end_race_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Add some amount to the delay bias
+ * tst_fzsync_pair_add_bias() - Add some amount to the delay bias.
+ * @pair: Fuzzy sync pair.
+ * @change: Amount to add to bias.
  *
  * @relates tst_fzsync_pair
  * @param change The amount to add, can be negative
diff --git a/include/tst_hugepage.h b/include/tst_hugepage.h
index 6b865b2f20b3deb3197638cff45a7a34b77e7d0e..6357e6ca9ff28572b687d6d15405b179cf8be6fa 100644
--- a/include/tst_hugepage.h
+++ b/include/tst_hugepage.h
@@ -19,6 +19,11 @@
 extern char *nr_opt; /* -s num   Set the number of the been allocated hugepages */
 extern char *Hopt;   /* -H /..   Location of hugetlbfs, i.e.  -H /var/hugetlbfs */
 
+/**
+ * enum tst_hp_policy - Hugepage reservation policy.
+ * @TST_REQUEST: Try to reserve hugepages; tst_hugepages may be 0.
+ * @TST_NEEDS: Fail with TCONF if the requested count cannot be reserved.
+ */
 enum tst_hp_policy {
 	TST_REQUEST,
 	TST_NEEDS,
@@ -26,30 +31,40 @@ enum tst_hp_policy {
 
 #define TST_NO_HUGEPAGES ((unsigned long)-1)
 
+/**
+ * struct tst_hugepage - Hugepage reservation request.
+ * @number: Number of hugepages to reserve.
+ * @policy: Reservation policy (TST_REQUEST or TST_NEEDS).
+ */
 struct tst_hugepage {
 	const unsigned long number;
 	enum  tst_hp_policy policy;
 };
 
-/*
- * Get the default hugepage size. Returns 0 if hugepages are not supported.
+/**
+ * tst_get_hugepage_size() - Get the default hugepage size.
+ *
+ * Return: Hugepage size in bytes, or 0 if hugepages are not supported.
  */
 size_t tst_get_hugepage_size(void);
 
-/*
- * Try the best to request a specified number of huge pages from system,
- * it will store the reserved hpage number in tst_hugepages.
+/**
+ * tst_reserve_hugepages() - Reserve hugepages from the system.
+ * @hp: Hugepage request describing count and policy.
+ *
+ * Stores the number of actually reserved hugepages in tst_hugepages.
+ * The result depends on system memory fragmentation.
  *
- * Note: this depend on the status of system memory fragmentation.
+ * Return: Number of hugepages reserved.
  */
 unsigned long tst_reserve_hugepages(struct tst_hugepage *hp);
 
 /*
- * This variable is used for recording the number of hugepages which system can
- * provides. It will be equal to 'hpages' if tst_reserve_hugepages on success,
- * otherwise set it to a number of hugepages that we were able to reserve.
+ * tst_hugepages - Number of hugepages actually reserved.
  *
- * If system does not support hugetlb, then it will be set to 0.
+ * Set by tst_reserve_hugepages(). Equals the requested count on success,
+ * or fewer if the system could not provide enough. Zero when hugepages
+ * are not supported.
  */
 extern unsigned long tst_hugepages;
 
diff --git a/include/tst_kconfig.h b/include/tst_kconfig.h
index b0608498d7e837e2c7b847fbef23334dcf2605c9..56711c4d06c216f4d5be412ee3780c850037bdfd 100644
--- a/include/tst_kconfig.h
+++ b/include/tst_kconfig.h
@@ -10,13 +10,21 @@
 #include <stddef.h>
 
 /**
- * Initialization helper macro for struct tst_kconfig_var. Requires <string.h>
+ * TST_KCONFIG_INIT() - Initialization helper macro for struct tst_kconfig_var.
+ * @confname: Config variable name string.
  */
 #define TST_KCONFIG_INIT(confname) { \
 	.id = confname, \
 	.id_len = strlen(confname) \
 }
 
+/**
+ * struct tst_kconfig_var - Kernel config variable lookup result.
+ * @id: Config variable name (e.g. CONFIG_FOO).
+ * @id_len: Length of @id string.
+ * @choice: Result: 'm', 'y', 'v', 'n', or 0 (not found).
+ * @val: Allocated value string when @choice is 'v'.
+ */
 struct tst_kconfig_var {
 	char id[64];
 	unsigned int id_len;
@@ -25,56 +33,39 @@ struct tst_kconfig_var {
 };
 
 /**
+ * tst_kconfig_read() - Read and parse kernel config.
+ * @vars: An array of caller initialized tst_kconfig_var structures.
+ * @vars_len: Length of the @vars array.
  *
- * Reads a kernel config, parses it and writes results into an array of
- * tst_kconfig_var structures.
- *
- * The path to the kernel config should be autodetected in most of the cases as
- * the code looks for know locations. It can be explicitly set/overridden with
- * the KCONFIG_PATH environment variable as well.
- *
- * The caller has to initialize the tst_kconfig_var structure. The id has to be
- * filled with config variable name such as 'CONFIG_FOO', the id_len should
- * hold the id string length and the choice and val has to be zeroed.
+ * The path to the kernel config is autodetected from known locations
+ * and can be overridden with the KCONFIG_PATH environment variable.
  *
- * After a call to this function each choice be set as follows:
+ * After a call to this function each choice is set as follows:
  *
- *  'm' - config option set to m
- *  'y' - config option set to y
- *  'v' - config option set to other value
- *  'n' - config option is not set
- *   0  - config option not found
+ *  - 'm' - config option set to m
+ *  - 'y' - config option set to y
+ *  - 'v' - config option set to other value
+ *  - 'n' - config option is not set
+ *  - 0   - config option not found
  *
- * In the case that match is set to 'v' the val pointer points to a newly
- * allocated string that holds the value.
- *
- * @param vars An array of caller initialized tst_kconfig_var structures.
- * @param vars_len Length of the vars array.
+ * When choice is 'v' the val pointer holds a newly allocated string.
  */
 void tst_kconfig_read(struct tst_kconfig_var vars[], size_t vars_len);
 
 /**
- * Checks if required kernel configuration options are set in the kernel
- * config. Return 0 if every config is satisfied and return 1 if at least
- * one is missing.
+ * tst_kconfig_check() - Check if required kernel config options are set.
+ * @kconfigs: NULL-terminated array of config strings needed for the testrun.
  *
- * The config options can be passed in two different formats, either
- * "CONFIG_FOO" in which case the option has to be set in order to continue the
- * test or with an explicit value "CONFIG_FOO=bar" in which case the value has
- * to match.
+ * Config options can be passed as "CONFIG_FOO" (must be set) or
+ * "CONFIG_FOO=bar" (value must match).
  *
- * @param kconfigs NULL-terminated array of config strings needed for the testrun.
+ * Return: 0 if every config is satisfied, 1 if at least one is missing.
  */
 int tst_kconfig_check(const char *const kconfigs[]);
 
 /**
- * Macro to prepare a tst_kcmdline_var structure with a given parameter name.
- *
- * It initializes the .key field with the provided name, sets the .value field
- * to an empty string, and marks the parameter as not found (.found = false).
- *
- * This macro is typically used to prepopulate an array with configuration
- * parameters before processing the actual command line arguments.
+ * TST_KCMDLINE_INIT() - Initialization helper macro for struct tst_kcmdline_var.
+ * @paraname: Kernel command-line parameter name.
  */
 #define TST_KCMDLINE_INIT(paraname) { \
 	.key = paraname, \
@@ -83,8 +74,10 @@ int tst_kconfig_check(const char *const kconfigs[]);
 }
 
 /**
- * Structure for storing command-line parameter key and its corresponding
- * value, and a flag indicating whether the parameter was found.
+ * struct tst_kcmdline_var - Kernel command-line parameter storage.
+ * @key: Parameter name.
+ * @value: Parameter value buffer.
+ * @found: Whether the parameter was found.
  */
 struct tst_kcmdline_var {
 	const char *key;
@@ -93,9 +86,9 @@ struct tst_kcmdline_var {
 };
 
 /**
- * Parses command-line parameters from /proc/cmdline and stores them in params array.
- * params: The array of tst_kcmdline_var structures to be filled with parsed key-value pairs.
- * params_len: The length of the params array, indicating how many parameters to parse.
+ * tst_kcmdline_parse() - Parse kernel command-line parameters from /proc/cmdline.
+ * @params: Array of tst_kcmdline_var structures to fill.
+ * @params_len: Length of the @params array.
  */
 void tst_kcmdline_parse(struct tst_kcmdline_var params[], size_t params_len);
 
diff --git a/include/tst_taint.h b/include/tst_taint.h
index b2b201688595cdfaf812e4fe7acc1760330199eb..e265fd50cc1fbb1613588200a331bdd8168d2741 100644
--- a/include/tst_taint.h
+++ b/include/tst_taint.h
@@ -66,32 +66,24 @@
 #define TST_TAINT_T     (1 << 17) /* kernel was built with the struct randomization plugin */
 #define TST_TAINT_N     (1 << 18) /* an in-kernel test has been run */
 
-/*
- * Initialize and prepare support for checking tainted kernel. Called
- * automatically by LTP library during test setup if tst_test.taint_check
- * is non-zero. The value of tst_test.taint_check will be passed as the mask
- * argument.
- *
- * supply the mask of TAINT-flags you want to check, for example
- * (TST_TAINT_W | TST_TAINT_D) when you want to check if the kernel issued
- * a warning or even reported it died.
- *
- * This function tests if the requested flags are supported on the
- * locally running kernel. In case the tainted-flags are already set by
- * the kernel, there is no reason to continue and TBROK is generated.
+/**
+ * tst_taint_init() - Set up kernel taint checking.
+ * @mask: Bitmask of TST_TAINT_* flags to monitor.
  *
- * The mask must not be zero.
+ * Called automatically by the LTP library during test setup when
+ * tst_test.taint_check is non-zero. Aborts with TBROK if any
+ * requested flags are already set.
  */
 void tst_taint_init(unsigned int mask);
 
 
-/*
- * check if the tainted flags handed to tst_taint_init() are still not set
- * during or after running the test.
- * Calling this function is only allowed after tst_taint_init() was called,
- * otherwise TBROK will be generated.
+/**
+ * tst_taint_check() - Check if monitored taint flags have been set.
+ *
+ * May only be called after tst_taint_init(). Also called automatically
+ * at the end of testing when tst_test.taint_check is non-zero.
  *
- * returns 0 or a bitmask of the flags that currently tainted the kernel.
+ * Return: 0 if clean, or a bitmask of newly set taint flags.
  */
 unsigned int tst_taint_check(void);
 

-- 
2.51.0


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

[LTP] [PATCH 2/3] doc: Complete struct tst_test table and shell API docs

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Fix incorrect field names in the C/Shell API comparison table in
writing_tests.rst:

- .max_runtime -> .runtime (renamed in a6a369c5eeb4)
- .tst_hugepage -> .hugepages (actual field name)
- .dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables,
  not C struct fields; move them to the 'not applicable' section

Add 10 missing struct tst_test fields to the table: .filesystems,
.forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate,
.needs_cgroup_ver, .needs_hugetlbfs, .runs_script, and fix the
alphabetical ordering of .mnt_flags and .min_swap_avail.

Add a shell API variables reference section to api_shell_tests.rst
documenting all public TST_* input/output variables, checkpoint
functions, and retry helpers.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++++++++++++++++++++
 doc/developers/writing_tests.rst   |  28 ++++++-
 2 files changed, 189 insertions(+), 2 deletions(-)

diff --git a/doc/developers/api_shell_tests.rst b/doc/developers/api_shell_tests.rst
index 937ffee2ea468552e5160775153990f13ea10f88..168e6c122730b4e9ace07a1f9d8554f8d8f9a290 100644
--- a/doc/developers/api_shell_tests.rst
+++ b/doc/developers/api_shell_tests.rst
@@ -93,3 +93,166 @@ interrupted by :ref:`tst_brk`.
 
    .. literalinclude:: ../../testcases/lib/tests/shell_loader_setup_cleanup.sh
       :language: shell
+
+Shell API variables
+-------------------
+
+The following variables are available to shell tests. Variables marked
+*input* are set by the test before sourcing ``tst_run.sh``; variables
+marked *output* are set by the library for tests to read.
+
+Test definition (input)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``TST_TESTFUNC``
+    Name of the test function (required).
+
+``TST_CNT``
+    Number of test cases. When set the test function is called
+    ``TST_CNT`` times with a counter argument.
+
+``TST_SETUP``
+    Name of the setup function (called once before tests).
+
+``TST_CLEANUP``
+    Name of the cleanup function (called once after tests or on
+    ``tst_brk``).
+
+``TST_OPTS``
+    Extra getopts option string.
+
+``TST_PARSE_ARGS``
+    Name of a function to parse extra options from ``TST_OPTS``.
+
+``TST_USAGE``
+    Name of a function printing extra usage information.
+
+``TST_POS_ARGS``
+    Number of expected positional arguments.
+
+``TST_TEST_DATA``
+    Space-separated data passed as a second argument to the test
+    function.
+
+``TST_TEST_DATA_IFS``
+    Custom delimiter for ``TST_TEST_DATA`` (default: space).
+
+Requirements (input)
+~~~~~~~~~~~~~~~~~~~~
+
+``TST_NEEDS_ROOT``
+    Set to 1 to require root privileges.
+
+``TST_NEEDS_TMPDIR``
+    Set to 1 to create a temporary directory.
+
+``TST_NEEDS_DEVICE``
+    Set to 1 to prepare a block device.
+
+``TST_NEEDS_CMDS``
+    Space-separated list of required commands.
+
+``TST_NEEDS_MODULE``
+    Kernel module name that must be loadable.
+
+``TST_NEEDS_DRIVERS``
+    Space-separated list of required kernel drivers.
+
+``TST_NEEDS_KCONFIGS``
+    Space-separated list of required kernel config options
+    (e.g. ``CONFIG_NUMA=y``).
+
+``TST_NEEDS_KCONFIGS_IFS``
+    Custom delimiter for ``TST_NEEDS_KCONFIGS`` (default: comma).
+
+``TST_NEEDS_CHECKPOINTS``
+    Set to 1 to enable checkpoint support.
+
+``TST_MIN_KVER``
+    Minimum kernel version string (e.g. ``4.18``).
+
+Device and filesystem (input)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``TST_FORMAT_DEVICE``
+    Set to 1 to format ``TST_DEVICE`` before the test.
+
+``TST_MOUNT_DEVICE``
+    Set to 1 to mount ``TST_DEVICE`` at ``TST_MNTPOINT``.
+
+``TST_DEV_EXTRA_OPTS``
+    Extra options passed to ``mkfs``.
+
+``TST_DEV_FS_OPTS``
+    Extra filesystem-specific ``mkfs`` options.
+
+``TST_FS_TYPE``
+    Filesystem type for formatting (default: ``ext2``).
+
+``TST_DEVICE_SIZE``
+    Device size in MB.
+
+``TST_ALL_FILESYSTEMS``
+    Set to 1 to repeat the test for each supported filesystem.
+
+``TST_SKIP_FILESYSTEMS``
+    Space-separated list of filesystems to skip.
+
+``TST_MNT_PARAMS``
+    Mount flags/options string.
+
+Miscellaneous (input)
+~~~~~~~~~~~~~~~~~~~~~
+
+``TST_SKIP_IN_LOCKDOWN``
+    Set to 1 to skip when kernel lockdown is active.
+
+``TST_SKIP_IN_SECUREBOOT``
+    Set to 1 to skip when Secure Boot is enabled.
+
+``TST_TIMEOUT``
+    Test timeout in seconds.
+
+Output variables
+~~~~~~~~~~~~~~~~
+
+``TST_TMPDIR``
+    Path to the temporary directory (when ``TST_NEEDS_TMPDIR=1``).
+
+``TST_STARTWD``
+    Original working directory before ``chdir`` to ``TST_TMPDIR``.
+
+``TST_DEVICE``
+    Block device path (when ``TST_NEEDS_DEVICE=1``).
+
+``TST_MNTPOINT``
+    Mount point path.
+
+``TST_MODPATH``
+    Path to the loaded kernel module.
+
+Checkpoint functions
+~~~~~~~~~~~~~~~~~~~~
+
+``TST_CHECKPOINT_WAIT``
+    Wait on checkpoint (argument: checkpoint id).
+
+``TST_CHECKPOINT_WAKE``
+    Wake one waiter on checkpoint (argument: checkpoint id).
+
+``TST_CHECKPOINT_WAKE2``
+    Wake multiple waiters (arguments: checkpoint id, count).
+
+``TST_CHECKPOINT_WAKE_AND_WAIT``
+    Wake one waiter and then wait (argument: checkpoint id).
+
+Retry helpers
+~~~~~~~~~~~~~
+
+``TST_RETRY_FUNC``
+    Retry a function until it succeeds or times out
+    (arguments: function, expected value).
+
+``TST_RETRY_FN_EXP_BACKOFF``
+    Like ``TST_RETRY_FUNC`` with exponential backoff
+    (arguments: function, expected value, max delay).
diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..2d7950be6d6b70afc69f96d99314effdd2e985da 100644
--- a/doc/developers/writing_tests.rst
+++ b/doc/developers/writing_tests.rst
@@ -382,6 +382,12 @@ LTP C And Shell Test API Comparison
     * - .dev_min_size
       - TST_DEVICE_SIZE
 
+    * - .filesystems
+      - \-
+
+    * - .forks_child
+      - not applicable
+
     * - .format_device
       - TST_FORMAT_DEVICE
 
@@ -399,12 +405,15 @@ LTP C And Shell Test API Comparison
     * - .min_mem_avail
       - not applicable
 
-    * - .mnt_flags
-      - TST_MNT_PARAMS
+    * - .min_runtime
+      - \-
 
     * - .min_swap_avail
       - not applicable
 
+    * - .mnt_flags
+      - TST_MNT_PARAMS
+
     * - .mntpoint | .mnt_data
       - TST_MNTPOINT
 
@@ -414,6 +423,12 @@ LTP C And Shell Test API Comparison
     * - .needs_cgroup_ctrls
       - \-
 
+    * - .needs_cgroup_nsdelegate
+      - \-
+
+    * - .needs_cgroup_ver
+      - \-
+
     * - .needs_checkpoints
       - TST_NEEDS_CHECKPOINTS
 
@@ -426,6 +441,9 @@ LTP C And Shell Test API Comparison
     * - .needs_device
       - TST_NEEDS_DEVICE
 
+    * - .needs_hugetlbfs
+      - \-
+
     * - removed
       - TST_NEEDS_DRIVERS
 
@@ -438,6 +456,9 @@ LTP C And Shell Test API Comparison
     * - .needs_rofs
       - \-
 
+    * - .needs_abi_bits
+      - not applicable
+
     * - .needs_root
       - TST_NEEDS_ROOT
 
@@ -453,6 +474,9 @@ LTP C And Shell Test API Comparison
     * - .restore_wallclock
       - not applicable
 
+    * - .runs_script
+      - not applicable
+
     * - .sample
       - \-
 

-- 
2.51.0


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

[LTP] [PATCH 3/3] doc: Add SAFE_* macros reference page

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Add doc/developers/api_safe_macros.rst listing all 217 SAFE_* wrapper
macros grouped by header and category (file ops, memory, process,
signals, networking, pthreads, IPC, clocks, etc.).

This gives test writers a single reference page to discover available
safe macros without grepping headers.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 doc/developers/api_safe_macros.rst | 326 +++++++++++++++++++++++++++++++++++++
 doc/index.rst                      |   4 +
 2 files changed, 330 insertions(+)

diff --git a/doc/developers/api_safe_macros.rst b/doc/developers/api_safe_macros.rst
new file mode 100644
index 0000000000000000000000000000000000000000..80a534ccabfeaa0b684a2bc738309e8ac91c4d0f
--- /dev/null
+++ b/doc/developers/api_safe_macros.rst
@@ -0,0 +1,326 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. Copyright (c) Linux Test Project, 2025
+
+Safe macros reference
+=====================
+
+LTP provides ``SAFE_*`` wrappers for common system calls and library
+functions. Each wrapper calls the underlying function and, on failure,
+invokes ``tst_brk(TBROK | TERRNO, ...)`` to abort the test. This
+eliminates repetitive error-checking boilerplate.
+
+**When NOT to use SAFE_\* macros:** when the syscall is the *subject*
+of the test (e.g. testing ``close()`` error paths). Use ``TEST()`` or
+``TST_EXP_*`` macros instead.
+
+Core macros (tst_safe_macros.h)
+-------------------------------
+
+File and directory operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``SAFE_ACCESS(path, mode)``
+- ``SAFE_CHMOD(path, mode)``
+- ``SAFE_CHOWN(path, owner, group)``
+- ``SAFE_CHDIR(path)``
+- ``SAFE_CHROOT(path)``
+- ``SAFE_CREAT(path, mode)``
+- ``SAFE_FCHMOD(fd, mode)``
+- ``SAFE_FCHOWN(fd, owner, group)``
+- ``SAFE_GETCWD(buf, size)``
+- ``SAFE_LCHOWN(path, owner, group)``
+- ``SAFE_LINK(oldpath, newpath)``
+- ``SAFE_LINKAT(olddirfd, oldpath, newdirfd, newpath, flags)``
+- ``SAFE_MKDIR(path, mode)``
+- ``SAFE_MKFIFO(path, mode)``
+- ``SAFE_MKNOD(path, mode, dev)``
+- ``SAFE_READLINK(path, buf, bufsiz)``
+- ``SAFE_RENAME(oldpath, newpath)``
+- ``SAFE_RMDIR(path)``
+- ``SAFE_SYMLINK(target, linkpath)``
+- ``SAFE_SYMLINKAT(target, newdirfd, linkpath)``
+- ``SAFE_UNLINK(path)``
+
+File descriptor operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``SAFE_CLOSE(fd)`` — also sets ``fd = -1``
+- ``SAFE_DUP(oldfd)``
+- ``SAFE_DUP2(oldfd, newfd)``
+- ``SAFE_FCNTL(fd, cmd, ...)``
+- ``SAFE_FSYNC(fd)``
+- ``SAFE_OPEN(path, oflag, ...)``
+- ``SAFE_OPENDIR(name)``
+- ``SAFE_CLOSEDIR(dirp)``
+- ``SAFE_READDIR(dirp)``
+- ``SAFE_PIPE(pipefd)``
+- ``SAFE_PIPE2(pipefd, flags)``
+- ``SAFE_PTSNAME(fd)``
+
+Reading and writing
+~~~~~~~~~~~~~~~~~~~
+
+- ``SAFE_READ(len_strict, fd, buf, count)``
+- ``SAFE_READV(fd, iov, iovcnt)``
+- ``SAFE_WRITE(len_strict, fd, buf, count)``
+- ``SAFE_WRITEV(fd, iov, iovcnt)``
+
+Memory management
+~~~~~~~~~~~~~~~~~
+
+- ``SAFE_CALLOC(nmemb, size)``
+- ``SAFE_MALLOC(size)``
+- ``SAFE_MEMALIGN(alignment, size)``
+- ``SAFE_REALLOC(ptr, size)``
+- ``SAFE_MMAP(addr, length, prot, flags, fd, offset)``
+- ``SAFE_MUNMAP(addr, length)``
+- ``SAFE_MLOCK(addr, len)``
+- ``SAFE_MUNLOCK(addr, len)``
+- ``SAFE_MPROTECT(addr, len, prot)``
+- ``SAFE_MSYNC(addr, length, flags)``
+- ``SAFE_MINCORE(addr, length, vec)``
+
+Process management
+~~~~~~~~~~~~~~~~~~
+
+- ``SAFE_EXECL(path, arg, ...)``
+- ``SAFE_EXECLP(file, arg, ...)``
+- ``SAFE_EXECVP(file, argv)``
+- ``SAFE_KILL(pid, sig)``
+- ``SAFE_WAIT(status)``
+- ``SAFE_WAITPID(pid, status, opts)``
+- ``SAFE_GETPGID(pid)``
+- ``SAFE_SETPGID(pid, pgid)``
+- ``SAFE_SETSID()``
+- ``SAFE_PRCTL(option, ...)``
+- ``SAFE_PTRACE(request, pid, addr, data)``
+- ``SAFE_PIDFD_OPEN(pid, flags)``
+
+User and group
+~~~~~~~~~~~~~~
+
+- ``SAFE_GETPWNAM(name)``
+- ``SAFE_GETGRNAM(name)``
+- ``SAFE_GETGRNAM_FALLBACK(name)``
+- ``SAFE_GETGRGID(gid)``
+- ``SAFE_GETGROUPS(size, list)``
+- ``SAFE_SETGROUPS(size, list)``
+- ``SAFE_SETUID(uid)``
+- ``SAFE_SETEUID(euid)``
+- ``SAFE_SETREUID(ruid, euid)``
+- ``SAFE_SETRESUID(ruid, euid, suid)``
+- ``SAFE_GETRESUID(ruid, euid, suid)``
+- ``SAFE_SETGID(gid)``
+- ``SAFE_SETEGID(egid)``
+- ``SAFE_SETREGID(rgid, egid)``
+- ``SAFE_SETRESGID(rgid, egid, sgid)``
+- ``SAFE_GETRESGID(rgid, egid, sgid)``
+
+Signals
+~~~~~~~
+
+- ``SAFE_SIGACTION(signum, act, oldact)``
+- ``SAFE_SIGADDSET(set, signum)``
+- ``SAFE_SIGDELSET(set, signum)``
+- ``SAFE_SIGEMPTYSET(set)``
+- ``SAFE_SIGFILLSET(set)``
+- ``SAFE_SIGNAL(signum, handler)``
+- ``SAFE_SIGPROCMASK(how, set, oldset)``
+- ``SAFE_SIGWAIT(set, sig)``
+
+Extended attributes
+~~~~~~~~~~~~~~~~~~~
+
+- ``SAFE_GETXATTR(path, name, value, size)``
+- ``SAFE_SETXATTR(path, name, value, size, flags)``
+- ``SAFE_REMOVEXATTR(path, name)``
+- ``SAFE_LSETXATTR(path, name, value, size, flags)``
+- ``SAFE_LREMOVEXATTR(path, name)``
+- ``SAFE_FSETXATTR(fd, name, value, size, flags)``
+- ``SAFE_FREMOVEXATTR(fd, name)``
+
+Mounting
+~~~~~~~~
+
+- ``SAFE_MOUNT(source, target, filesystemtype, mountflags, data)``
+- ``SAFE_MOUNT2(source, target, filesystemtype, mountflags, data)``
+- ``SAFE_UMOUNT(target)``
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+- ``SAFE_BASENAME(path)``
+- ``SAFE_CMD(argv, stdout_path, stderr_path)``
+- ``SAFE_DIRNAME(path)``
+- ``SAFE_GETPRIORITY(which, who)``
+- ``SAFE_GETRUSAGE(who, usage)``
+- ``SAFE_IOCTL(fd, request, ...)``
+- ``SAFE_PERSONALITY(persona)``
+- ``SAFE_SETENV(name, value, overwrite)``
+- ``SAFE_SETNS(fd, nstype)``
+- ``SAFE_SSCANF(str, format, ...)``
+- ``SAFE_STATVFS(path, buf)``
+- ``SAFE_SYSCONF(name)``
+- ``SAFE_SYSINFO(info)``
+- ``SAFE_UNSHARE(flags)``
+
+String conversion
+~~~~~~~~~~~~~~~~~
+
+- ``SAFE_STRTOL(str, min, max)``
+- ``SAFE_STRTOUL(str, min, max)``
+- ``SAFE_STRTOF(str, min, max)``
+
+Inline macros (tst_safe_macros_inline.h)
+----------------------------------------
+
+- ``SAFE_FSTAT(fd, statbuf)``
+- ``SAFE_FTRUNCATE(fd, length)``
+- ``SAFE_GETRLIMIT(resource, rlim)``
+- ``SAFE_LSEEK(fd, offset, whence)``
+- ``SAFE_LSTAT(path, statbuf)``
+- ``SAFE_MMAP(addr, length, prot, flags, fd, offset)``
+- ``SAFE_POSIX_FADVISE(fd, offset, len, advice)``
+- ``SAFE_SETRLIMIT(resource, rlim)``
+- ``SAFE_STAT(path, statbuf)``
+- ``SAFE_STATFS(path, buf)``
+- ``SAFE_TRUNCATE(path, length)``
+
+File content operations (tst_safe_file_ops.h)
+----------------------------------------------
+
+- ``SAFE_FILE_SCANF(path, fmt, ...)``
+- ``SAFE_FILE_LINES_SCANF(path, fmt, ...)``
+- ``SAFE_FILE_PRINTF(path, fmt, ...)``
+- ``SAFE_TRY_FILE_PRINTF(path, fmt, ...)``
+- ``SAFE_FILE_READ_STR(path, buf)``
+- ``SAFE_READ_MEMINFO(item)``
+- ``SAFE_READ_PROC_STATUS(pid, item)``
+- ``SAFE_CP(src, dst)``
+- ``SAFE_TOUCH(path, mode, times)``
+- ``SAFE_MOUNT_OVERLAY()``
+
+File-at operations (tst_safe_file_at.h)
+----------------------------------------
+
+- ``SAFE_OPENAT(dirfd, path, oflag, ...)``
+- ``SAFE_FILE_READAT(dirfd, path, buf, bufsiz)``
+- ``SAFE_FILE_PRINTFAT(dirfd, path, fmt, ...)``
+- ``SAFE_UNLINKAT(dirfd, path, flags)``
+- ``SAFE_FCHOWNAT(dirfd, path, owner, group, flags)``
+- ``SAFE_FSTATAT(dirfd, path, statbuf, flags)``
+
+Positioned I/O (tst_safe_prw.h)
+---------------------------------
+
+- ``SAFE_PREAD(len_strict, fd, buf, count, offset)``
+- ``SAFE_PREADV(fd, iov, iovcnt, offset)``
+- ``SAFE_PWRITE(len_strict, fd, buf, count, offset)``
+- ``SAFE_PWRITEV(fd, iov, iovcnt, offset)``
+
+Networking (tst_safe_net.h)
+----------------------------
+
+- ``SAFE_SOCKET(domain, type, protocol)``
+- ``SAFE_SOCKETPAIR(domain, type, protocol, sv)``
+- ``SAFE_BIND(sockfd, addr, addrlen)``
+- ``SAFE_CONNECT(sockfd, addr, addrlen)``
+- ``SAFE_LISTEN(sockfd, backlog)``
+- ``SAFE_ACCEPT(sockfd, addr, addrlen)``
+- ``SAFE_SEND(sockfd, buf, len, flags)``
+- ``SAFE_SENDTO(sockfd, buf, len, flags, dest_addr, addrlen)``
+- ``SAFE_SENDMSG(sockfd, msg, flags)``
+- ``SAFE_RECV(sockfd, buf, len, flags)``
+- ``SAFE_RECVMSG(sockfd, msg, flags)``
+- ``SAFE_GETSOCKNAME(sockfd, addr, addrlen)``
+- ``SAFE_GETSOCKOPT(sockfd, level, optname, optval, optlen)``
+- ``SAFE_SETSOCKOPT(sockfd, level, optname, optval, optlen)``
+- ``SAFE_SETSOCKOPT_INT(sockfd, level, optname, value)``
+- ``SAFE_GETHOSTNAME(name, len)``
+- ``SAFE_SETHOSTNAME(name, len)``
+- ``SAFE_GETADDRINFO(node, service, hints, res)``
+
+Pthreads (tst_safe_pthread.h)
+------------------------------
+
+- ``SAFE_PTHREAD_CREATE(thread, attr, start_routine, arg)``
+- ``SAFE_PTHREAD_JOIN(thread, retval)``
+- ``SAFE_PTHREAD_CANCEL(thread)``
+- ``SAFE_PTHREAD_KILL(thread, sig)``
+- ``SAFE_PTHREAD_BARRIER_INIT(barrier, attr, count)``
+- ``SAFE_PTHREAD_BARRIER_WAIT(barrier)``
+- ``SAFE_PTHREAD_BARRIER_DESTROY(barrier)``
+- ``SAFE_PTHREAD_MUTEX_INIT(mutex, attr)``
+- ``SAFE_PTHREAD_MUTEX_LOCK(mutex)``
+- ``SAFE_PTHREAD_MUTEX_TRYLOCK(mutex)``
+- ``SAFE_PTHREAD_MUTEX_TIMEDLOCK(mutex, abstime)``
+- ``SAFE_PTHREAD_MUTEX_UNLOCK(mutex)``
+- ``SAFE_PTHREAD_MUTEX_DESTROY(mutex)``
+- ``SAFE_PTHREAD_MUTEXATTR_INIT(attr)``
+- ``SAFE_PTHREAD_MUTEXATTR_SETTYPE(attr, type)``
+- ``SAFE_PTHREAD_MUTEXATTR_DESTROY(attr)``
+
+Standard I/O (tst_safe_stdio.h)
+--------------------------------
+
+- ``SAFE_FOPEN(path, mode)``
+- ``SAFE_FREOPEN(path, mode, stream)``
+- ``SAFE_FCLOSE(stream)``
+- ``SAFE_FREAD(ptr, size, nmemb, stream)``
+- ``SAFE_FWRITE(ptr, size, nmemb, stream)``
+- ``SAFE_FFLUSH(stream)``
+- ``SAFE_FSEEK(stream, offset, whence)``
+- ``SAFE_FTELL(stream)``
+- ``SAFE_FILENO(stream)``
+- ``SAFE_POPEN(command, type)``
+- ``SAFE_ASPRINTF(strp, fmt, ...)``
+
+SysV IPC (tst_safe_sysv_ipc.h)
+--------------------------------
+
+- ``SAFE_MSGGET(key, msgflg)``
+- ``SAFE_MSGSND(msqid, msgp, msgsz, msgflg)``
+- ``SAFE_MSGRCV(msqid, msgp, msgsz, msgtyp, msgflg)``
+- ``SAFE_MSGCTL(msqid, cmd, buf)``
+- ``SAFE_SEMGET(key, nsems, semflg)``
+- ``SAFE_SEMOP(semid, sops, nsops)``
+- ``SAFE_SEMCTL(semid, semnum, cmd, ...)``
+- ``SAFE_SHMGET(key, size, shmflg)``
+- ``SAFE_SHMAT(shmid, shmaddr, shmflg)``
+- ``SAFE_SHMDT(shmaddr)``
+- ``SAFE_SHMCTL(shmid, cmd, buf)``
+
+POSIX IPC (tst_safe_posix_ipc.h)
+----------------------------------
+
+- ``SAFE_MQ_OPEN(name, oflag, ...)``
+- ``SAFE_MQ_CLOSE(mqdes)``
+- ``SAFE_MQ_SEND(mqdes, msg_ptr, msg_len, msg_prio)``
+- ``SAFE_MQ_NOTIFY(mqdes, sevp)``
+- ``SAFE_MQ_UNLINK(name)``
+
+Clocks and timers (tst_safe_clocks.h)
+--------------------------------------
+
+- ``SAFE_CLOCK_GETRES(clk_id, res)``
+- ``SAFE_CLOCK_GETTIME(clk_id, tp)``
+- ``SAFE_CLOCK_SETTIME(clk_id, tp)``
+- ``SAFE_CLOCK_NANOSLEEP(clk_id, flags, request, remain)``
+- ``SAFE_TIMER_CREATE(clockid, sevp, timerid)``
+- ``SAFE_TIMER_SETTIME(timerid, flags, new_value, old_value)``
+- ``SAFE_TIMER_GETTIME(timerid, curr_value)``
+- ``SAFE_TIMER_DELETE(timerid)``
+
+Timer file descriptors (tst_safe_timerfd.h)
+--------------------------------------------
+
+- ``SAFE_TIMERFD_CREATE(clockid, flags)``
+- ``SAFE_TIMERFD_SETTIME(fd, flags, new_value, old_value)``
+- ``SAFE_TIMERFD_GETTIME(fd, curr_value)``
+
+io_uring (tst_safe_io_uring.h)
+-------------------------------
+
+- ``SAFE_IO_URING_INIT(entries, params, ring)``
+- ``SAFE_IO_URING_ENTER(fd, to_submit, min_complete, flags, sig)``
+- ``SAFE_IO_URING_CLOSE(ring)``
diff --git a/doc/index.rst b/doc/index.rst
index 58944a72da4c0a6d9362b0f85551683da03f5b72..c1252d34773e8411674fb143f5d871025b2fd96d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -25,6 +25,7 @@
    developers/writing_tests
    developers/test_case_tutorial
    developers/api_c_tests
+   developers/api_safe_macros
    developers/api_shell_tests
    developers/api_network_tests
    developers/api_kvm_tests
@@ -82,6 +83,9 @@ For developers
 :doc:`developers/api_c_tests`
    Walk through the C API features
 
+:doc:`developers/api_safe_macros`
+   Reference of all ``SAFE_*`` wrapper macros
+
 :doc:`developers/api_shell_tests`
    Walk through the Shell API features
 

-- 
2.51.0


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

Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst

[Petr Vorel]

Hi Andrea,

> Fix broken kernel-doc reference to renamed tse_numa.h header and add
Not only this patch but none of the other two actually fixes it. I suppose you
forget to amend git commit.

How about to fix this one in a separate commit (which you can merge right now,
no need to even send it to ML) with the usual tag?

Fixes: eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")

Specially because Cyril might want to review if all the docs is correct (which
takes time).

Also there are still some unresolved problems, but we can fix it afterwards:

include/tst_test.h:302: WARNING: undefined label: 'struct tst_option'
include/tst_test.h:325: WARNING: undefined label: 'struct tst_device'
include/tst_test.h:361: WARNING: undefined label: 'struct tst_device'
include/tst_test.h:502: WARNING: undefined label: 'struct tst_path_val'
include/tst_test.h:523: WARNING: undefined label: 'struct tst_buffers'
include/tst_test.h:528: WARNING: undefined label: 'struct tst_cap'
include/tst_test.h:531: WARNING: undefined label: 'struct tst_tag'
include/tst_test.h:533: WARNING: undefined label: 'struct tst_cmd'
include/tst_kvercmp.h:97: WARNING: undefined label: 'struct tst_kern_exv'
doc/developers/api_shell_tests.rst:30: WARNING: undefined label: 'struct tst_test'
doc/developers/test_case_tutorial.rst:140: WARNING: undefined label: 'struct tst_test'
doc/developers/todo.rst:62: WARNING: undefined label: 'struct tst_test'
doc/developers/writing_tests.rst:141: WARNING: undefined label: 'struct tst_test'
doc/developers/writing_tests.rst:364: WARNING: undefined label: 'struct tst_test'
doc/developers/writing_tests.rst:558: WARNING: undefined label: 'struct tst_device'

Generally changes are good, thanks for finishing the transition.
With fixed tse_numa.h (preferably in a separate commit) you may add:

Reviewed-by: Petr Vorel <pvorel@suse.cz>

> kernel-doc directives for 12 headers that were missing from the C API
> documentation page:

>   tst_clone.h, tst_device.h, tst_fs.h, tst_fuzzy_sync.h,
>   tst_hugepage.h, tst_kconfig.h, tst_memutils.h, tst_safe_file_ops.h,
>   tst_taint.h, tse_numa.h, tse_swap.h, tse_uinput.h

> Convert plain comments to kernel-doc format in tst_device.h,
> tst_hugepage.h, tst_clone.h, and tst_taint.h so the documentation
> builder can extract them.

> Sort all sections alphabetically under LTP C API.

FYI I quite liked that Core API was the first, but ok with the move.

Kind regards,
Petr

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

Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst

[Andrea Cervesato via ltp]

Hi Petr,

as mentioned inside the cover letter, this patch-set has to be
added on top of the " [PATCH 0/4] Fix documentation issues "
patch-set. Once done that it won't have issues anymore with
warnings etc.

> Hi Andrea,
> 
> > Fix broken kernel-doc reference to renamed tse_numa.h header and add
> Not only this patch but none of the other two actually fixes it. I suppose you
> forget to amend git commit.
> 
> How about to fix this one in a separate commit (which you can merge right now,
> no need to even send it to ML) with the usual tag?
> 
> Fixes: eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")
> 
> Specially because Cyril might want to review if all the docs is correct (which
> takes time).
> 
> Also there are still some unresolved problems, but we can fix it afterwards:
> 
> include/tst_test.h:302: WARNING: undefined label: 'struct tst_option'
> include/tst_test.h:325: WARNING: undefined label: 'struct tst_device'
> include/tst_test.h:361: WARNING: undefined label: 'struct tst_device'
> include/tst_test.h:502: WARNING: undefined label: 'struct tst_path_val'
> include/tst_test.h:523: WARNING: undefined label: 'struct tst_buffers'
> include/tst_test.h:528: WARNING: undefined label: 'struct tst_cap'
> include/tst_test.h:531: WARNING: undefined label: 'struct tst_tag'
> include/tst_test.h:533: WARNING: undefined label: 'struct tst_cmd'
> include/tst_kvercmp.h:97: WARNING: undefined label: 'struct tst_kern_exv'
> doc/developers/api_shell_tests.rst:30: WARNING: undefined label: 'struct tst_test'
> doc/developers/test_case_tutorial.rst:140: WARNING: undefined label: 'struct tst_test'
> doc/developers/todo.rst:62: WARNING: undefined label: 'struct tst_test'
> doc/developers/writing_tests.rst:141: WARNING: undefined label: 'struct tst_test'
> doc/developers/writing_tests.rst:364: WARNING: undefined label: 'struct tst_test'
> doc/developers/writing_tests.rst:558: WARNING: undefined label: 'struct tst_device'
> 
> Generally changes are good, thanks for finishing the transition.
> With fixed tse_numa.h (preferably in a separate commit) you may add:
> 
> Reviewed-by: Petr Vorel <pvorel@suse.cz>
> 
> > kernel-doc directives for 12 headers that were missing from the C API
> > documentation page:
> 
> >   tst_clone.h, tst_device.h, tst_fs.h, tst_fuzzy_sync.h,
> >   tst_hugepage.h, tst_kconfig.h, tst_memutils.h, tst_safe_file_ops.h,
> >   tst_taint.h, tse_numa.h, tse_swap.h, tse_uinput.h
> 
> > Convert plain comments to kernel-doc format in tst_device.h,
> > tst_hugepage.h, tst_clone.h, and tst_taint.h so the documentation
> > builder can extract them.
> 
> > Sort all sections alphabetically under LTP C API.
> 
> FYI I quite liked that Core API was the first, but ok with the move.
> 
> Kind regards,
> Petr

--
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com

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

Re: [LTP] [PATCH 2/3] doc: Complete struct tst_test table and shell API docs

[Petr Vorel]

Hi Andrea, Cyril, Li,

@Andrea I'd say you mixed 2 APIs: tst_test.sh API (used to be "the new API" but
now deprecated by shell loader) and shell loader API. And here come problems.

> Fix incorrect field names in the C/Shell API comparison table in
> writing_tests.rst:

> - .max_runtime -> .runtime (renamed in a6a369c5eeb4)
> - .tst_hugepage -> .hugepages (actual field name)
> - .dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables,
>   not C struct fields; move them to the 'not applicable' section

This part which fixes tst_test.c renames I'd merge right now.

But the rest which is in api_shell_tests.rst it's IMHO wrong because they are
for tst_test.sh. 


The problem is that since  3c82316c53 ("doc: Add basic shell test description")
we consider doc/developers/api_shell_tests.html home for shell loader. See
Cyril's feedback to not put there tst_test.sh doc [1]. That's why I rejected my
older patch converting tst_test.sh doc to the old file.

but that approach in 3c82316c53 wasn't consistent, because other doc still
consider as shell API tst_test.sh:
* doc/developers/ltp_library.rst (mentions tst_test.sh, tst_security.sh and
  tst_net.sh)
* doc/users/setup_tests.rst (comparison table)
* testcases/network/README.md (git source only, not part of readthedocs)
* Old github doc in doc/old/

@All We should fix it. So what are we going to do with tst_test.sh doc?
Maybe admit tst_test.sh etc exists in doc/developers/ltp_library.rst,
but document that shell loader is way to go?

And I wonder if the comparison table in doc/developers/api_shell_tests.rst
should be deleted or we should put a note that this API is deprecated and
users should use shell loader (clickable link to
doc/developers/api_shell_tests.html).

And yes, we should probably convert lib/README.md and
testcases/network/README.md to sphinx doc, but that's a completely different
problem.

[1] https://lore.kernel.org/ltp/aRSlUmoktYACJRV6@yuki.lan/
[2] https://lore.kernel.org/ltp/20251014145020.178840-2-pvorel@suse.cz/

> Add 10 missing struct tst_test fields to the table: .filesystems,
> .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate,
> .needs_cgroup_ver, .needs_hugetlbfs, .runs_script, and fix the
> alphabetical ordering of .mnt_flags and .min_swap_avail.

> Add a shell API variables reference section to api_shell_tests.rst
> documenting all public TST_* input/output variables, checkpoint
> functions, and retry helpers.

> Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
> ---
>  doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++++++++++++++++++++
>  doc/developers/writing_tests.rst   |  28 ++++++-
>  2 files changed, 189 insertions(+), 2 deletions(-)

> diff --git a/doc/developers/api_shell_tests.rst b/doc/developers/api_shell_tests.rst
> index 937ffee2ea468552e5160775153990f13ea10f88..168e6c122730b4e9ace07a1f9d8554f8d8f9a290 100644
> --- a/doc/developers/api_shell_tests.rst
> +++ b/doc/developers/api_shell_tests.rst

FYI given the above this doc is for a shell loader....

> @@ -93,3 +93,166 @@ interrupted by :ref:`tst_brk`.

>     .. literalinclude:: ../../testcases/lib/tests/shell_loader_setup_cleanup.sh
>        :language: shell
> +
> +Shell API variables
> +-------------------
> +
> +The following variables are available to shell tests. Variables marked
> +*input* are set by the test before sourcing ``tst_run.sh``; variables
nit: could you please use clickable link to sources?

:shell_lib:`tst_run.sh` (Cyril preferred it over :master:`testcases/lib/tst_run.sh`).

I dared to merge more rename now:
016134bf31 ("doc: Use shell_lib prefix to shorten printed file path")

> +marked *output* are set by the library for tests to read.
> +
> +Test definition (input)
> +~~~~~~~~~~~~~~~~~~~~~~~
nit: I'd remove "(input(". I did not get what you mean.

... which means many of these below aren't (yet) supported in shell loader.
ATM we support only TST_SETUP and TST_CLEANUP. Test function must be named
tst_test().

And my WIP "shell loader fixes + du01.sh rewrite"

[3] https://patchwork.ozlabs.org/project/ltp/list/?series=495792&state=*

> +
> +``TST_TESTFUNC``
> +    Name of the test function (required).
> +
> +``TST_CNT``
> +    Number of test cases. When set the test function is called
> +    ``TST_CNT`` times with a counter argument.
> +
> +``TST_SETUP``
> +    Name of the setup function (called once before tests).
> +
> +``TST_CLEANUP``
> +    Name of the cleanup function (called once after tests or on
> +    ``tst_brk``).
> +
> +``TST_OPTS``
> +    Extra getopts option string.
> +
> +``TST_PARSE_ARGS``
> +    Name of a function to parse extra options from ``TST_OPTS``.
> +
> +``TST_USAGE``
> +    Name of a function printing extra usage information.
> +
> +``TST_POS_ARGS``
> +    Number of expected positional arguments.
> +
> +``TST_TEST_DATA``
> +    Space-separated data passed as a second argument to the test
> +    function.
> +
> +``TST_TEST_DATA_IFS``
> +    Custom delimiter for ``TST_TEST_DATA`` (default: space).

To be honest, if 
> +
> +Requirements (input)
> +~~~~~~~~~~~~~~~~~~~~
> +
> +``TST_NEEDS_ROOT``
> +    Set to 1 to require root privileges.
> +
> +``TST_NEEDS_TMPDIR``
> +    Set to 1 to create a temporary directory.
> +
> +``TST_NEEDS_DEVICE``
> +    Set to 1 to prepare a block device.
> +
> +``TST_NEEDS_CMDS``
> +    Space-separated list of required commands.
> +
> +``TST_NEEDS_MODULE``
> +    Kernel module name that must be loadable.
> +
> +``TST_NEEDS_DRIVERS``
> +    Space-separated list of required kernel drivers.
> +
> +``TST_NEEDS_KCONFIGS``
> +    Space-separated list of required kernel config options
> +    (e.g. ``CONFIG_NUMA=y``).
> +
> +``TST_NEEDS_KCONFIGS_IFS``
> +    Custom delimiter for ``TST_NEEDS_KCONFIGS`` (default: comma).
> +
> +``TST_NEEDS_CHECKPOINTS``
> +    Set to 1 to enable checkpoint support.
> +
> +``TST_MIN_KVER``
> +    Minimum kernel version string (e.g. ``4.18``).
> +
> +Device and filesystem (input)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +``TST_FORMAT_DEVICE``
> +    Set to 1 to format ``TST_DEVICE`` before the test.
> +
> +``TST_MOUNT_DEVICE``
> +    Set to 1 to mount ``TST_DEVICE`` at ``TST_MNTPOINT``.
> +
> +``TST_DEV_EXTRA_OPTS``
> +    Extra options passed to ``mkfs``.
> +
> +``TST_DEV_FS_OPTS``
> +    Extra filesystem-specific ``mkfs`` options.
> +
> +``TST_FS_TYPE``
> +    Filesystem type for formatting (default: ``ext2``).
> +
> +``TST_DEVICE_SIZE``
> +    Device size in MB.
> +
> +``TST_ALL_FILESYSTEMS``
> +    Set to 1 to repeat the test for each supported filesystem.
> +
> +``TST_SKIP_FILESYSTEMS``
> +    Space-separated list of filesystems to skip.
> +
> +``TST_MNT_PARAMS``
> +    Mount flags/options string.
> +
> +Miscellaneous (input)
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +``TST_SKIP_IN_LOCKDOWN``
> +    Set to 1 to skip when kernel lockdown is active.
> +
> +``TST_SKIP_IN_SECUREBOOT``
> +    Set to 1 to skip when Secure Boot is enabled.
> +
> +``TST_TIMEOUT``
> +    Test timeout in seconds.
> +
> +Output variables
> +~~~~~~~~~~~~~~~~
> +
> +``TST_TMPDIR``
> +    Path to the temporary directory (when ``TST_NEEDS_TMPDIR=1``).
> +
> +``TST_STARTWD``
> +    Original working directory before ``chdir`` to ``TST_TMPDIR``.
> +
> +``TST_DEVICE``
> +    Block device path (when ``TST_NEEDS_DEVICE=1``).
> +
> +``TST_MNTPOINT``
> +    Mount point path.
> +
> +``TST_MODPATH``
> +    Path to the loaded kernel module.
> +
> +Checkpoint functions
> +~~~~~~~~~~~~~~~~~~~~
> +
> +``TST_CHECKPOINT_WAIT``
> +    Wait on checkpoint (argument: checkpoint id).
> +
> +``TST_CHECKPOINT_WAKE``
> +    Wake one waiter on checkpoint (argument: checkpoint id).
> +
> +``TST_CHECKPOINT_WAKE2``
> +    Wake multiple waiters (arguments: checkpoint id, count).
> +
> +``TST_CHECKPOINT_WAKE_AND_WAIT``
> +    Wake one waiter and then wait (argument: checkpoint id).
> +
> +Retry helpers
> +~~~~~~~~~~~~~
> +
> +``TST_RETRY_FUNC``
> +    Retry a function until it succeeds or times out
> +    (arguments: function, expected value).
> +
> +``TST_RETRY_FN_EXP_BACKOFF``
> +    Like ``TST_RETRY_FUNC`` with exponential backoff
> +    (arguments: function, expected value, max delay).

To be honest if we want to document tst_test.sh, I'd prefer the examples in my
original patch [2].

> diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
> index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..2d7950be6d6b70afc69f96d99314effdd2e985da 100644
> --- a/doc/developers/writing_tests.rst
> +++ b/doc/developers/writing_tests.rst
> @@ -382,6 +382,12 @@ LTP C And Shell Test API Comparison
>      * - .dev_min_size
>        - TST_DEVICE_SIZE

> +    * - .filesystems
> +      - \-
> +
> +    * - .forks_child
> +      - not applicable
> +
>      * - .format_device
>        - TST_FORMAT_DEVICE

> @@ -399,12 +405,15 @@ LTP C And Shell Test API Comparison
>      * - .min_mem_avail
>        - not applicable

> -    * - .mnt_flags
> -      - TST_MNT_PARAMS
> +    * - .min_runtime
> +      - \-

>      * - .min_swap_avail
>        - not applicable

> +    * - .mnt_flags
> +      - TST_MNT_PARAMS
> +
>      * - .mntpoint | .mnt_data
>        - TST_MNTPOINT

> @@ -414,6 +423,12 @@ LTP C And Shell Test API Comparison
>      * - .needs_cgroup_ctrls
>        - \-

> +    * - .needs_cgroup_nsdelegate
> +      - \-
> +
> +    * - .needs_cgroup_ver
> +      - \-
> +
>      * - .needs_checkpoints
>        - TST_NEEDS_CHECKPOINTS

> @@ -426,6 +441,9 @@ LTP C And Shell Test API Comparison
>      * - .needs_device
>        - TST_NEEDS_DEVICE

> +    * - .needs_hugetlbfs
> +      - \-
> +
>      * - removed
>        - TST_NEEDS_DRIVERS

> @@ -438,6 +456,9 @@ LTP C And Shell Test API Comparison
>      * - .needs_rofs
>        - \-

> +    * - .needs_abi_bits
> +      - not applicable
> +
>      * - .needs_root
>        - TST_NEEDS_ROOT

> @@ -453,6 +474,9 @@ LTP C And Shell Test API Comparison
>      * - .restore_wallclock
>        - not applicable

> +    * - .runs_script
> +      - not applicable
> +
>      * - .sample
>        - \-

And until we decide, I'm ok to update writing_tests.rst (i.e. merge
writing_tests.rst part).

Kind regards,
Petr

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

Re: [LTP] doc: Add missing API references to api_c_tests.rst

[linuxtestproject.agent]

Hi Andrea,

Thank you for this documentation series. The kernel-doc conversions and new
reference pages are a welcome addition. However, several commit message claims
do not match what the patches actually implement, and there are technical
issues in tst_fuzzy_sync.h that need to be fixed before merging.

---

[PATCH 1/3] doc: Add missing API references to api_c_tests.rst
04e9aa97059d1301f10954322074c7cb3d9fdd53

--- Commit message ---

> Fix broken kernel-doc reference to renamed tse_numa.h header

This claim is false. The api_c_tests.rst NUMA section still references
`../../include/tst_numa.h` (which does not exist) in both master and HEAD:

  $ cat doc/developers/api_c_tests.rst | grep -n numa
  73:NUMA
  75:.. kernel-doc:: ../../include/tst_numa.h

The actual file is include/tse_numa.h. The reference was not corrected by
this patch.

> Convert plain comments to kernel-doc format in tst_device.h,
> tst_hugepage.h, tst_clone.h, and tst_taint.h

tst_fuzzy_sync.h also receives kernel-doc conversions (old @param/@return
Doxygen style → new function() - description / @param: style) but is not
mentioned here.

--- include/tst_fuzzy_sync.h ---

The patch adds new-style kernel-doc parameters to several functions but fails
to remove the old Doxygen-style @param / @return lines. This leaves duplicate,
conflicting documentation in the following functions:

tst_exp_moving_avg():

  /**
   * tst_exp_moving_avg() - Exponential moving average.
   * @alpha: Smoothing factor.          ← new style
   * @sample: New sample value.
   * @prev_avg: Previous average.
   *
   * Return: New average.
   *
   * @param alpha The preference for recent samples over old ones.  ← stale
   * @param sample The current sample                               ← stale
   * @param prev_avg The average of the all the previous samples    ← stale
   *
   * @return The average including the current sample.              ← stale
   */

@param alpha and @param sample were removed by the patch, but @param prev_avg
and @return were not. They should be removed.

tst_fzsync_pair_reset():

  /**
   * tst_fzsync_pair_reset() - Reset or initialise fzsync.
   * @pair: Fuzzy sync pair.         ← new style
   * @run_b: Thread B function pointer.
   *
   * @relates tst_fzsync_pair
   * @param pair The state structure initialised with TST_FZSYNC_PAIR_INIT.  ← stale
   * @param run_b The function defining thread B or NULL.                    ← stale
   */

@param pair and @param run_b were not removed. They should be removed.

tst_fzsync_pair_wait():

  /**
   * tst_fzsync_pair_wait() - Wait for the other thread.
   * @our_cntr: Our atomic counter.        ← new style
   * @other_cntr: Other thread's atomic counter.
   * @spins: Spin counter.
   * @exit: Exit flag.
   * @yield_in_wait: Whether to yield while waiting.
   *
   * @relates tst_fzsync_pair
   * @param our_cntr The counter for the thread we are on    ← stale
   * @param other_cntr ...                                   ← stale
   * @param spins ...                                        ← stale
   * @param exit ...                                         ← stale
   * ...
   * @return A non-zero value if the thread should continue  ← stale
   */

All four @param lines and the @return line were not removed.

tst_fzsync_run_a():

  /**
   * tst_fzsync_run_a() - Decide whether to continue running thread A.
   * @pair: Fuzzy sync pair.
   *
   * Return: Non-zero to continue, 0 to stop.   ← new style
   *
   * ...
   * @return True to continue and false to break.  ← stale, not removed
   */

tst_fzsync_pair_add_bias():

  /**
   * tst_fzsync_pair_add_bias() - Add some amount to the delay bias.
   * @pair: Fuzzy sync pair.
   * @change: Amount to add to bias.    ← new style
   *
   * @relates tst_fzsync_pair
   * @param change The amount to add, can be negative  ← stale, not removed
   */

All stale @param / @return / @relates lines left after the conversion should
be removed.

---

[PATCH 2/3] doc: Complete struct tst_test table and shell API docs
f1c9189e4415389807671809f27d2b922e36e99b

--- Commit message ---

The body describes four fixes to writing_tests.rst that are NOT present in
the patch:

1. ".max_runtime -> .runtime (renamed in a6a369c5eeb4)"

   Not done. writing_tests.rst still has:

     * - .max_runtime
       - TST_TIMEOUT ...

   The actual struct field is `int runtime` (include/tst_test.h:599). The
   table entry should be `.runtime`, not `.max_runtime`.

2. ".tst_hugepage -> .hugepages (actual field name)"

   Not done. writing_tests.rst still has:

     * - .tst_hugepage
       - not applicable

   The actual struct field is `struct tst_hugepage hugepages`
   (include/tst_test.h:586). The table entry should be `.hugepages`.

3. ".dev_extra_opts, .dev_fs_opts, .dev_fs_type are shell-only variables,
   not C struct fields; move them to the 'not applicable' section"

   Not done. These three rows remain unchanged in the table, still listed
   as if they were C struct fields. None of these names appear in
   include/tst_test.h.

4. "Add 10 missing struct tst_test fields"

   Only 8 fields are added: .filesystems, .forks_child, .min_runtime,
   .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver,
   .needs_hugetlbfs, .runs_script. The commit body also lists exactly 8
   names. The subject and body should say 8, not 10.

The commit message must be corrected to describe only what the patch
actually does, and the four unimplemented fixes above must either be
implemented or dropped from the description.

---

[PATCH 3/3] doc: Add SAFE_* macros reference page
c9f08715e5e82b5a07d355c6c26313e4608cb3e4

--- doc/developers/api_safe_macros.rst ---

> +.. Copyright (c) Linux Test Project, 2025

This file is being created in 2026; the year should be 2026 (or 2025-2026
if the content dates to 2025, but for a new file 2026 is appropriate).
Compare api_c_tests.rst which uses "2024-2025".

> +- ``SAFE_MMAP(addr, length, prot, flags, fd, offset)``

This line appears in the "Core macros (tst_safe_macros.h)" Memory management
section. However, SAFE_MMAP is defined only in include/tst_safe_macros_inline.h,
not in tst_safe_macros.h. It is also correctly listed in the "Inline macros
(tst_safe_macros_inline.h)" section. Remove the duplicate entry from the
core macros section; it belongs only under "Inline macros".

Because of this duplicate, the "all 217 SAFE_* wrapper macros" claim in the
subject overstates by one; there are 216 unique macros. The count and subject
line should be corrected after removing the duplicate.

---

Verdict: Needs revision

LTP AI Reviewer

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

Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst

[Petr Vorel]

Hi Andrea,

> Hi Petr,

> as mentioned inside the cover letter, this patch-set has to be
> added on top of the " [PATCH 0/4] Fix documentation issues "
> patch-set. Once done that it won't have issues anymore with
> warnings etc.

Thanks for a hint.

> > Hi Andrea,

> > > Fix broken kernel-doc reference to renamed tse_numa.h header and add

But in that case this part of the commit message is wrong.

Kind regards,
Petr

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

Re: [LTP] doc: Add missing API references to api_c_tests.rst

[Andrea Cervesato via ltp]

Sigh, I should have sent this one with the previous documentation
fix patch-set . I will do it in the next iteration.

--
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com

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

Re: [LTP] [PATCH 1/3] doc: Add missing API references to api_c_tests.rst

[Cyril Hrubis]

Hi!
> Fix broken kernel-doc reference to renamed tse_numa.h header and add

That was actually fixed in the first patch of the previous patchset.

-- 
Cyril Hrubis
chrubis@suse.cz

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