Skip to contentSkip to conversation

doc: Add missing headers and complete API docs

PATCH In review Andrea Cervesato 4 participants 7 messages Jun 12

lore
Share & tools
lore
#0 lore raw

v8 cover doc: Add missing headers and complete API docs

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.

---
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/[email protected]

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/[email protected]

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/[email protected]

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/[email protected]

Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/[email protected]

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/[email protected]

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/[email protected]

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

Signature · 5 lines
Andrea Cervesato <[email protected]>


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#1 lore raw

PATCH v8 1/2 doc: Add missing API references to api_c_tests.rst

From: Andrea Cervesato <[email protected]>

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")
---
 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(-)
doc/developers/api_c_tests.rst +54 -17
index 65cf6d6cd0be5cb4cd9c986e09df021071d968f1..1e9e595dde24755817396deb2d78ae0a7c56a29a 100644
@@ -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
include/tse_uinput.h +15 -15
index e336de780b1c9ce2d9cd2977e15b287cadfb76a4..272cf16483643b5552f3f88a9b87211a6863c8f5 100644
@@ -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);
 
include/tst_clone.h +16 -8
index a07689c78f575ae6ca87c0952b3e48b3a626012c..daae7562f46d78b0bbe24a7a5794f7b62d4e2364 100644
@@ -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);
 
include/tst_device.h +115 -59

238 lines not on this page · raw message

include/tst_fuzzy_sync.h +88 -155

449 lines not on this page · raw message

include/tst_hugepage.h +25 -10
index f3f1ec0320a1038509212e603a9699fa090329f2..27ee36399ff4e111108872e89ce3b3bc51a78a14 100644
@@ -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;
 
include/tst_kconfig.h +36 -42

122 lines not on this page · raw message

include/tst_taint.h +12 -20
index b2b201688595cdfaf812e4fe7acc1760330199eb..e265fd50cc1fbb1613588200a331bdd8168d2741 100644
@@ -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);
 
Signature · 5 lines
2.51.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
Reviewed-by on v8 1/2
#2 lore raw

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

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

Quoted 7 lines

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

Quoted 8 lines

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

Quoted 2 lines

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

Quoted 2 lines

+ * @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%).

Quoted 8 lines

+ * @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:

Signature · 5 lines
Cyril Hrubis
[email protected]

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#3 lore raw

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

In reply to Andrea Cervesato

Hi Andrea,

Quoted 1 line · Andrea Cervesato

doc: Add missing API references to api_c_tests.rst

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

Quoted 7 lines

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

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#4 lore raw

PATCH v8 2/2 doc: complete struct tst_test documentation

In reply to Andrea Cervesato

From: Andrea Cervesato <[email protected]>

Add missing struct tst_test fields in the C API.

---
 doc/developers/writing_tests.rst | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)
doc/developers/writing_tests.rst +26 -2
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..4db57898fcf08b83e68be996f666e91c418838fc 100644
@@ -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
       - \-
 
Signature · 5 lines
2.51.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
Reviewed-by on v8 2/2
#5 lore raw

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

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

Signature · 5 lines
Cyril Hrubis
[email protected]

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