[LTP] [PATCH v8 0/2] doc: Add missing headers and complete API docs

[LTP] [PATCH v8 0/2] doc: Add missing headers and complete API docs

[Andrea Cervesato]

Add kernel-doc directives for 10 headers that were missing from the C
API documentation page and convert plain and Doxygen-style comments to
kernel-doc format so the documentation builder can extract them.

Complete the struct tst_test comparison table in writing_tests.rst and
add a shell API variables reference to api_shell_tests.rst.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
Changes in v8:
- PATCH 1: add usage pattern description linking tst_dev_sync() and
  tst_dev_bytes_written() in tst_device.h
- PATCH 1: remove duplicate inline comments from tst_fzsync_pair struct
  fields (already documented in the top-level kernel-doc block)
- PATCH 1: remove stray double '::' in tst_fzsync_pair_update() comment
- PATCH 2: remove Shell API variables
- Link to v7: https://lore.kernel.org/r/20260609-doc_add_missing_headers-v7-0-779c18caddef@suse.com

Changes in v7:
- Rewrite cover letter subject and body
- Drop the api_safe_macros.rst patch from the series
- Link to v6: https://lore.kernel.org/r/20260605-doc_add_missing_headers-v6-0-678aac302a60@suse.com

Changes in v6:
- PATCH 3: replace the U+2014 em-dash next to SAFE_CLOSE in
  api_safe_macros.rst with an ASCII '--' so doc/ stays ASCII-only
- Link to v5: https://lore.kernel.org/r/20260604-doc_add_missing_headers-v5-0-2e0adc082d5a@suse.com

Changes in v5:
- PATCH 1: drop the stray empty "Verdict:" line accidentally left in
  the commit message body
- PATCH 1: remove the leftover "@sa tst_fzsync_pair" Doxygen directive
  from the file-level overview comment in tst_fuzzy_sync.h
- PATCH 2: extend the shell API variables reference with the remaining
  public inputs (TST_DISABLE_APPARMOR, TST_DISABLE_SELINUX,
  TST_SKIP_LSM_WARNINGS, TST_NO_DEFAULT_RUN, TST_TMPDIR_RHOST)
- Link to v4: https://lore.kernel.org/r/20260603-doc_add_missing_headers-v4-0-1fe3a372c155@suse.com

Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/20260602-doc_add_missing_headers-v3-0-474deff77d2a@suse.com

Changes in v3:
- PATCH 3: add the missing blank line between tst_mount_has_opt() and
  the tst_is_mounted() kernel-doc block in tst_device.h
- PATCH 3: restore the "Requires <string.h>" note (for strlen()) in the
  TST_KCONFIG_INIT() kernel-doc comment in tst_kconfig.h
- Link to v2: https://lore.kernel.org/r/20260602-doc_add_missing_headers-v2-0-9ccd988c093d@suse.com

Changes in v2:
- PATCH 1: drop the incorrect claim about fixing the tse_numa.h
  kernel-doc reference (it was already correct) and correct the header
  count from 12 to 10 (tse_numa.h and tse_swap.h were already present)
- PATCH 1: remove leftover Doxygen directives (@param, @return,
  @relates, @sa) in tst_fuzzy_sync.h that the new kernel-doc comments
  superseded
- PATCH 2: drop the already-applied field-rename claims (.runtime,
  .hugepages, dev_* moves) from the commit message and correct the
  added-field count from 10 to 8
- PATCH 3: fix the copyright year (2025 -> 2026), remove the duplicate
  SAFE_MMAP entry from the core macros section, and correct the macro
  count from 217 to 216
- Link to v1: https://lore.kernel.org/r/20260601-doc_add_missing_headers-v1-0-6f1ee31945df@suse.com

---
Andrea Cervesato (2):
      doc: Add missing API references to api_c_tests.rst
      doc: complete struct tst_test documentation

 doc/developers/api_c_tests.rst   |  71 +++++++++---
 doc/developers/writing_tests.rst |  28 ++++-
 include/tse_uinput.h             |  30 ++---
 include/tst_clone.h              |  24 ++--
 include/tst_device.h             | 174 ++++++++++++++++++----------
 include/tst_fuzzy_sync.h         | 243 ++++++++++++++-------------------------
 include/tst_hugepage.h           |  35 ++++--
 include/tst_kconfig.h            |  78 ++++++-------
 include/tst_taint.h              |  32 ++----
 9 files changed, 387 insertions(+), 328 deletions(-)
---
base-commit: 6e9798bd429f7f341db078388ddb7087b81fb67b
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 v8 1/2] doc: Add missing API references to api_c_tests.rst

[Andrea Cervesato]

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

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

  tse_uinput.h, 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

Convert plain and Doxygen-style comments to kernel-doc format in
tse_uinput.h, tst_clone.h, tst_device.h, tst_fuzzy_sync.h,
tst_hugepage.h, tst_kconfig.h and tst_taint.h so the documentation
builder can extract them. This includes removing leftover Doxygen
directives (@param, @return, @relates, @sa) superseded by the new
kernel-doc comments.

Sort all sections alphabetically under LTP C API.

Fixes: eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")
Reviewed-by: Petr Vorel <pvorel@suse.cz>
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            |  24 ++--
 include/tst_device.h           | 174 +++++++++++++++++++----------
 include/tst_fuzzy_sync.h       | 243 +++++++++++++++--------------------------
 include/tst_hugepage.h         |  35 ++++--
 include/tst_kconfig.h          |  78 ++++++-------
 include/tst_taint.h            |  32 ++----
 8 files changed, 361 insertions(+), 326 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..daae7562f46d78b0bbe24a7a5794f7b62d4e2364 100644
--- a/include/tst_clone.h
+++ b/include/tst_clone.h
@@ -9,7 +9,14 @@
 
 #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: Pointer (cast to u64) where the kernel stores the pidfd when
+ *         CLONE_PIDFD is set.
+ * @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 +24,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..30e558f2582cdf2ac61ed25b4b020829d70a8e3b 100644
--- a/include/tst_device.h
+++ b/include/tst_device.h
@@ -11,123 +11,179 @@
 #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.
+ *
+ * Should be called before tst_dev_bytes_written() to flush deferred I/O
+ * and ensure the first measurement is accurate.
+ *
+ * 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.
+ *
+ * The call is usually called twice to measure a number of bytes written
+ * during a certain operation. However in order to avoid interference from
+ * deferred I/O the tst_dev_sync() must be called before we take the first
+ * measurement.
+ *
+ * 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..44f1c70cd91f630ffccca2dbd899d84d7fa2b7ae 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
@@ -55,8 +54,6 @@
  *
  * For a usage example see testcases/cve/cve-2016-7117.c or just run
  * 'git grep tst_fuzzy_sync.h'
- *
- * @sa tst_fzsync_pair
  */
 
 #include <math.h>
@@ -83,7 +80,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,89 +117,30 @@ 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 */
 	struct timespec a_start;
-	/** Internal; Thread B start time */
 	struct timespec b_start;
-	/** Internal; Thread A end time */
 	struct timespec a_end;
-	/** Internal; Thread B end time */
 	struct timespec b_end;
-	/** Internal; Avg. difference between a_start and b_start */
 	struct tst_fzsync_stat diff_ss;
-	/** Internal; Avg. difference between a_start and a_end */
 	struct tst_fzsync_stat diff_sa;
-	/** Internal; Avg. difference between b_start and b_end */
 	struct tst_fzsync_stat diff_sb;
-	/** 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 */
 	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
-	 * deviation which must be attained before random delays can be
-	 * calculated.
-	 *
-	 * It is a ratio of (average_deviation / total_time). The default is
-	 * 0.1, so this allows an average deviation of at most 10%.
-	 */
 	float max_dev_ratio;
 
-	/** Internal; Atomic counter used by fzsync_pair_wait() */
 	tst_atomic_t a_cntr;
-	/** Internal; Atomic counter used by fzsync_pair_wait() */
 	tst_atomic_t b_cntr;
-	/** 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() */
 	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  */
 	int exec_loop;
-	/** 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
-	 * amount of time to run fuzzy sync library.
-	 * Thus call sched_yield to give up cpu to decrease the test time.
-	 */
 	bool yield_in_wait;
 
 };
@@ -191,14 +153,11 @@ 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
- *
- * @relates tst_fzsync_pair
+ * tst_fzsync_pair_init() - Ensure Fuzzy Sync parameters are properly set.
+ * @pair: Fuzzy sync pair.
  *
  * Usually called from the setup function, it sets default parameter values or
  * validates any existing non-defaults.
- *
- * @sa tst_fzsync_pair_reset()
  */
 static inline void tst_fzsync_pair_init(struct tst_fzsync_pair *pair)
 {
@@ -213,9 +172,8 @@ static inline void tst_fzsync_pair_init(struct tst_fzsync_pair *pair)
 #undef CHK
 
 /**
- * Exit and join thread B if necessary.
- *
- * @relates tst_fzsync_pair
+ * tst_fzsync_pair_cleanup() - Exit and join thread B if necessary.
+ * @pair: Fuzzy sync pair.
  *
  * Call this from your cleanup function.
  */
@@ -231,9 +189,8 @@ static inline void tst_fzsync_pair_cleanup(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Zero some stat fields
- *
- * @relates tst_fzsync_stat
+ * tst_init_stat() - Zero some stat fields.
+ * @s: Stat structure to zero.
  */
 static inline void tst_init_stat(struct tst_fzsync_stat *s)
 {
@@ -242,11 +199,9 @@ static inline void tst_init_stat(struct tst_fzsync_stat *s)
 }
 
 /**
- * Reset or initialise fzsync.
- *
- * @relates tst_fzsync_pair
- * @param pair The state structure initialised with TST_FZSYNC_PAIR_INIT.
- * @param run_b The function defining thread B or NULL.
+ * tst_fzsync_pair_reset() - Reset or initialise fzsync.
+ * @pair: Fuzzy sync pair.
+ * @run_b: Thread B function pointer.
  *
  * Call this from your main test function (thread A), just before entering the
  * main loop. It will (re)set any variables needed by fzsync and (re)start
@@ -256,8 +211,6 @@ static inline void tst_init_stat(struct tst_fzsync_stat *s)
  * you can pass NULL to run_b and handle starting and stopping thread B
  * yourself. You may need to place tst_fzsync_pair in some shared memory as
  * well.
- *
- * @sa tst_fzsync_pair_init()
  */
 static inline void tst_fzsync_pair_reset(struct tst_fzsync_pair *pair,
 				  void *(*run_b)(void *))
@@ -285,9 +238,10 @@ static inline void tst_fzsync_pair_reset(struct tst_fzsync_pair *pair,
 }
 
 /**
- * Print stat
- *
- * @relates tst_fzsync_stat
+ * tst_fzsync_stat_info() - Print stat.
+ * @stat: Stat to print.
+ * @unit: Unit string.
+ * @name: Name string.
  */
 static inline void tst_fzsync_stat_info(struct tst_fzsync_stat stat,
 					char *unit, char *name)
@@ -298,9 +252,8 @@ static inline void tst_fzsync_stat_info(struct tst_fzsync_stat stat,
 }
 
 /**
- * Print some synchronisation statistics
- *
- * @relates tst_fzsync_pair
+ * tst_fzsync_pair_info() - Print some synchronisation statistics.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_pair_info(struct tst_fzsync_pair *pair)
 {
@@ -313,7 +266,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,13 +280,12 @@ static inline void tst_fzsync_time(struct timespec *t)
 }
 
 /**
- * Exponential moving average
- *
- * @param alpha The preference for recent samples over old ones.
- * @param sample The current sample
- * @param prev_avg The average of the all the previous samples
+ * tst_exp_moving_avg() - Exponential moving average.
+ * @alpha: Smoothing factor.
+ * @sample: New sample value.
+ * @prev_avg: Previous average.
  *
- * @return The average including the current sample.
+ * Return: New average.
  */
 static inline float tst_exp_moving_avg(float alpha,
 					float sample,
@@ -340,9 +295,10 @@ static inline float tst_exp_moving_avg(float alpha,
 }
 
 /**
- * Update a stat with a new sample
- *
- * @relates tst_fzsync_stat
+ * tst_upd_stat() - Update a stat with a new sample.
+ * @s: Stat structure.
+ * @alpha: Smoothing factor.
+ * @sample: New sample value.
  */
 static inline void tst_upd_stat(struct tst_fzsync_stat *s,
 				 float alpha,
@@ -355,9 +311,11 @@ static inline void tst_upd_stat(struct tst_fzsync_stat *s,
 }
 
 /**
- * Update a stat with a new diff sample
- *
- * @relates tst_fzsync_stat
+ * tst_upd_diff_stat() - Update a stat with a new diff sample.
+ * @s: Stat structure.
+ * @alpha: Smoothing factor.
+ * @t1: First timespec.
+ * @t2: Second timespec.
  */
 static inline void tst_upd_diff_stat(struct tst_fzsync_stat *s,
 				     float alpha,
@@ -368,7 +326,8 @@ 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:
@@ -452,8 +411,6 @@ static inline void tst_upd_diff_stat(struct tst_fzsync_stat *s,
  * [1] This assumes there is always a significant difference. The algorithm
  * may fail to introduce a delay (when one is needed) in situations where
  * Syscall A and B finish at approximately the same time.
- *
- * @relates tst_fzsync_pair
  */
 static inline void tst_fzsync_pair_update(struct tst_fzsync_pair *pair)
 {
@@ -510,21 +467,17 @@ static inline void tst_fzsync_pair_update(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Wait for the other thread
- *
- * @relates tst_fzsync_pair
- * @param our_cntr The counter for the thread we are on
- * @param other_cntr The counter for the thread we are synchronising with
- * @param spins A pointer to the spin counter or NULL
- * @param exit Exit flag when we need to break out of the wait loop
+ * 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.
  *
  * Used by tst_fzsync_pair_wait_a(), tst_fzsync_pair_wait_b(),
  * tst_fzsync_start_race_a(), etc. If the calling thread is ahead of the other
  * thread, then it will spin wait. Unlike pthread_barrier_wait it will never
  * use futex and can count the number of spins spent waiting.
- *
- * @return A non-zero value if the thread should continue otherwise the
- * calling thread should exit.
  */
 static inline void tst_fzsync_pair_wait(int *our_cntr,
 					int *other_cntr,
@@ -598,10 +551,8 @@ static inline void tst_fzsync_pair_wait(int *our_cntr,
 }
 
 /**
- * Wait in thread A
- *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_pair_wait
+ * tst_fzsync_wait_a() - Wait in thread A.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_wait_a(struct tst_fzsync_pair *pair)
 {
@@ -610,10 +561,8 @@ static inline void tst_fzsync_wait_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Wait in thread B
- *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_pair_wait
+ * tst_fzsync_wait_b() - Wait in thread B.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_wait_b(struct tst_fzsync_pair *pair)
 {
@@ -622,15 +571,13 @@ 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.
  *
- * @relates tst_fzsync_pair
+ * Return: Non-zero to continue, 0 to stop.
  *
  * Checks some values and decides whether it is time to break the loop of
  * thread A.
- *
- * @return True to continue and false to break.
- * @sa tst_fzsync_run_a
  */
 static inline int tst_fzsync_run_a(struct tst_fzsync_pair *pair)
 {
@@ -667,10 +614,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.
  *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_run_a
+ * Return: Non-zero to continue, 0 to stop.
  */
 static inline int tst_fzsync_run_b(struct tst_fzsync_pair *pair)
 {
@@ -679,9 +626,8 @@ static inline int tst_fzsync_run_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the start of a race region in thread A
- *
- * @relates tst_fzsync_pair
+ * tst_fzsync_start_race_a() - Mark the start of a race region in thread A.
+ * @pair: Fuzzy sync pair.
  *
  * This should be placed just before performing whatever action can cause a
  * race condition. Usually it is placed just before a syscall and
@@ -689,12 +635,6 @@ static inline int tst_fzsync_run_b(struct tst_fzsync_pair *pair)
  *
  * A corresponding call to tst_fzsync_start_race_b() should be made in thread
  * B.
- *
- * @return A non-zero value if the calling thread should continue to loop. If
- * it returns zero then tst_fzsync_exit() has been called and you must exit
- * the thread.
- *
- * @sa tst_fzsync_pair_update
  */
 static inline void tst_fzsync_start_race_a(struct tst_fzsync_pair *pair)
 {
@@ -719,10 +659,8 @@ static inline void tst_fzsync_start_race_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the end of a race region in thread A
- *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_start_race_a
+ * tst_fzsync_end_race_a() - Mark the end of a race region in thread A.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_end_race_a(struct tst_fzsync_pair *pair)
 {
@@ -732,10 +670,8 @@ static inline void tst_fzsync_end_race_a(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the start of a race region in thread B
- *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_start_race_a
+ * tst_fzsync_start_race_b() - Mark the start of a race region in thread B.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_start_race_b(struct tst_fzsync_pair *pair)
 {
@@ -758,10 +694,8 @@ static inline void tst_fzsync_start_race_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Marks the end of a race region in thread B
- *
- * @relates tst_fzsync_pair
- * @sa tst_fzsync_start_race_a
+ * tst_fzsync_end_race_b() - Mark the end of a race region in thread B.
+ * @pair: Fuzzy sync pair.
  */
 static inline void tst_fzsync_end_race_b(struct tst_fzsync_pair *pair)
 {
@@ -771,10 +705,9 @@ static inline void tst_fzsync_end_race_b(struct tst_fzsync_pair *pair)
 }
 
 /**
- * Add some amount to the delay bias
- *
- * @relates tst_fzsync_pair
- * @param change The amount to add, can be negative
+ * tst_fzsync_pair_add_bias() - Add some amount to the delay bias.
+ * @pair: Fuzzy sync pair.
+ * @change: Amount to add to bias.
  *
  * A positive change delays thread B and a negative one delays thread
  * A.
diff --git a/include/tst_hugepage.h b/include/tst_hugepage.h
index f3f1ec0320a1038509212e603a9699fa090329f2..27ee36399ff4e111108872e89ce3b3bc51a78a14 100644
--- a/include/tst_hugepage.h
+++ b/include/tst_hugepage.h
@@ -11,6 +11,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,
@@ -18,30 +23,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..c454f346761394a258c7e3b2ab8a6d1ad580c893 100644
--- a/include/tst_kconfig.h
+++ b/include/tst_kconfig.h
@@ -10,13 +10,22 @@
 #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. Requires <string.h> for strlen().
+ * @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 +34,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 +75,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 +87,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 v8 2/2] doc: complete struct tst_test documentation

[Andrea Cervesato]

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

Add missing struct tst_test fields in the C API.

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

diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..4db57898fcf08b83e68be996f666e91c418838fc 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,21 +405,33 @@ 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
 
     * - .mount_device
       - TST_MOUNT_DEVICE
 
+    * - .needs_abi_bits
+      - not applicable
+
     * - .needs_cgroup_ctrls
       - \-
 
+    * - .needs_cgroup_nsdelegate
+      - \-
+
+    * - .needs_cgroup_ver
+      - \-
+
     * - .needs_checkpoints
       - TST_NEEDS_CHECKPOINTS
 
@@ -426,6 +444,9 @@ LTP C And Shell Test API Comparison
     * - .needs_device
       - TST_NEEDS_DEVICE
 
+    * - .needs_hugetlbfs
+      - \-
+
     * - removed
       - TST_NEEDS_DRIVERS
 
@@ -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

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

[Cyril Hrubis]

Hi!
Some of the fuzzy sync struct member descriptions were simplified too
much. Suggestions below.

>  /**
> - * 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.

We need to add this here (otherwise the information is lost):

A negative value delays thread A and a positive delays thread B.

> + * @delay_bias: Internal; Bias added to delay.  + * @sampling:
> Internal; Sampling state or remaining count.

			     ^ If possitive stores the number of samples
			     left. If zero or negative stores sampling
			     state.

> + * @min_samples: Minimum samples before random delays are calculated (default 1024).
> + * @max_dev_ratio: Maximum allowed proportional average deviation (default 0.1).
                          ^

Maximum allowed proportional average deviation, in range (0.0, 1.0),
before random delays are applied. It's ratio of average_deviation /
total_time (default 0.1 i.e. avg deviation at most 10%).


> + * @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.
                         ^
	              Yield CPU while waiting, set automatically on single-core
		      machines.


With these adjusted:

Reviewed-by: Cyril Hrubis <chrubis@suse.cz>

-- 
Cyril Hrubis
chrubis@suse.cz

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

Re: [LTP] [PATCH v8 2/2] doc: complete struct tst_test documentation

[Cyril Hrubis]

Hi!
This is again the old shell API. But since it's already there we may as
well update it.

Reviewed-by: Cyril Hrubis <chrubis@suse.cz>

-- 
Cyril Hrubis
chrubis@suse.cz

-- 
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,

On Fri, 12 Jun 2026 10:27:20 +0200, Andrea Cervesato wrote:
> doc: Add missing API references to api_c_tests.rst

--- [PATCH 1/2] ---

> +/**
> + * 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.
> + */

The @size description says "in bytes", but tst_get_device_size() returns
size/1024/1024 (megabytes), and tst_device->size is assigned from it in
tst_test.c:

    tdev.size = tst_get_device_size(tdev.dev);

Should @size say "Device size in megabytes" instead?

Verdict: Needs revision

---
Note:

The agent can sometimes produce false positives although often its
findings are genuine. If you find issues with the review, please
comment this email or ignore the suggestions.

Regards,
LTP AI Reviewer

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

Re: [LTP] [PATCH v8 0/2] doc: Add missing headers and complete API docs

[Andrea Cervesato via ltp]

Merged, with suggested @cyril suggestions and agent error
discovery.

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

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