Skip to contentSkip to conversation

Complete the documentation adding missing headers

PATCH Superseded Andrea Cervesato 5 participants 11 messages Jun 1

v1 of 8 Superseded Latest is v8 →

lore
Share & tools
lore
#0 lore raw

cover Complete the documentation adding missing headers

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

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

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


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

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

From: Andrea Cervesato <[email protected]>

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.

---
 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(-)
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 +15 -8
index a07689c78f575ae6ca87c0952b3e48b3a626012c..1898c58f819f8eadc1468d2d2b86a9102f679eb9 100644
@@ -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);
 
include/tst_device.h +106 -59

229 lines not on this page · raw message

include/tst_fuzzy_sync.h +115 -48

365 lines not on this page · raw message

include/tst_hugepage.h +25 -10
index 6b865b2f20b3deb3197638cff45a7a34b77e7d0e..6357e6ca9ff28572b687d6d15405b179cf8be6fa 100644
@@ -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;
 
include/tst_kconfig.h +35 -42

121 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 v1 1/3
#2 lore raw

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

Hi Andrea,

Quoted 1 line

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:

Quoted 7 lines

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

Quoted 5 lines

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

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

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

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.

Quoted 48 lines

Hi Andrea,

Quoted 1 line

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:

Quoted 10 lines

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.

Quoted 6 lines
Quoted 1 line

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

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

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

Hi Andrea,

Quoted 6 lines

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.

Quoted 3 lines
Quoted 3 lines

Hi Andrea,

Quoted 1 line

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

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

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

In reply to Andrea Cervesato

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

Quoted 1 line

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.

Quoted 2 lines

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

Quoted 1 line

+.. 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".

Quoted 1 line

+- ``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

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

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

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

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

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

In reply to Andrea Cervesato

Hi!

Quoted 1 line

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.

Signature · 5 lines
Cyril Hrubis
[email protected]

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

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

In reply to Andrea Cervesato

From: Andrea Cervesato <[email protected]>

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.

---
 doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++++++++++++++++++++
 doc/developers/writing_tests.rst   |  28 ++++++-
 2 files changed, 189 insertions(+), 2 deletions(-)
doc/developers/api_shell_tests.rst +163 -0
index 937ffee2ea468552e5160775153990f13ea10f88..168e6c122730b4e9ace07a1f9d8554f8d8f9a290 100644
@@ -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).
doc/developers/writing_tests.rst +26 -2
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..2d7950be6d6b70afc69f96d99314effdd2e985da 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,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
       - \-
 
Signature · 5 lines
2.51.0


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

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

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.

Quoted 7 lines

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/[email protected]/
[2] https://lore.kernel.org/ltp/[email protected]/

doc/developers/api_shell_tests.rst

Quoted 19 lines

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.

---
 doc/developers/api_shell_tests.rst | 163 +++++++++++++++++++++++++++++++++++++
 doc/developers/writing_tests.rst   |  28 ++++++-
 2 files changed, 189 insertions(+), 2 deletions(-)
doc/developers/api_shell_tests.rst +0 -0
index 937ffee2ea468552e5160775153990f13ea10f88..168e6c122730b4e9ace07a1f9d8554f8d8f9a290 100644

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

doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 101

Quoted 10 lines
doc/developers/api_shell_tests.rst +6 -0
@@ -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")

doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 105

Quoted 4 lines
doc/developers/api_shell_tests.rst +4 -0
+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=*

Quoted 23 lines
doc/developers/api_shell_tests.rst +23 -0
+
+``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.

doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 138

Quoted 10 lines
doc/developers/api_shell_tests.rst +10 -0
+
+``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

Quoted 110 lines
doc/developers/api_shell_tests.rst +110 -0
+
+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).
+

doc/developers/api_shell_tests.rst interrupted by :ref:`tst_brk`. · line 258

Quoted 10 lines
doc/developers/api_shell_tests.rst +10 -0
+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].

Quoted 69 lines
doc/developers/writing_tests.rst +23 -2
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..2d7950be6d6b70afc69f96d99314effdd2e985da 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,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
 

doc/developers/writing_tests.rst LTP C And Shell Test API Comparison · line 481

Quoted 8 lines
doc/developers/writing_tests.rst +3 -0
@@ -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

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

PATCH 3/3 doc: Add SAFE_* macros reference page

In reply to Andrea Cervesato

From: Andrea Cervesato <[email protected]>

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.

---
 doc/developers/api_safe_macros.rst | 326 +++++++++++++++++++++++++++++++++++++
 doc/index.rst                      |   4 +
 2 files changed, 330 insertions(+)
doc/developers/api_safe_macros.rst new file +326 -0
new file mode 100644
index 0000000000000000000000000000000000000000..80a534ccabfeaa0b684a2bc738309e8ac91c4d0f
@@ -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)``
doc/index.rst +4 -0
index 58944a72da4c0a6d9362b0f85551683da03f5b72..c1252d34773e8411674fb143f5d871025b2fd96d 100644
@@ -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
 
Signature · 5 lines
2.51.0


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