Skip to contentSkip to conversation

Complete the documentation adding missing headers

PATCH Superseded Andrea Cervesato 2 participants 5 messages Jun 2

v2 of 8 Superseded Latest is v8 →

lore
Share & tools
lore
#0 lore raw

v2 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

---
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 (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 | 382 +++++++++++++++++++++++++++++++++++++
 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           | 231 +++++++++++-----------
 include/tst_hugepage.h             |  35 +++-
 include/tst_kconfig.h              |  77 ++++----
 include/tst_taint.h                |  32 ++--
 12 files changed, 950 insertions(+), 291 deletions(-)

---
base-commit: fb3451954e9a16078d184e56a3b0b165fd95b24d
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 v2 1/3 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.

---
 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       | 231 ++++++++++++++++++++---------------------
 include/tst_hugepage.h         |  35 +++++--
 include/tst_kconfig.h          |  77 +++++++-------
 include/tst_taint.h            |  32 +++---
 8 files changed, 375 insertions(+), 289 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 +113 -118

465 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
#2 lore raw

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

Hi Andrea,

thank you for the documentation series. A few issues below.

---

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

Claim: "listing all 245 SAFE_* wrapper macros"
Verified: 252 unique SAFE_* macro names in include/; the 7 not listed are header guards (SAFE_MACROS_FN_H__, SAFE_NET_FN_H__, SAFE_STDIO_FN_H__, SAFE_RT_SIGNAL_H__) and internal helpers (SAFE_FILE_OPS, SAFE_FILE_OPS_FN, SAFE_IOCTL_). Count 245 is correct.

No other issues found in this commit.

---

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

Claim: "Add 8 missing struct tst_test fields"
Verified: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs, .runs_script — all present in include/tst_test.h. Count 8 is correct.

Alphabetical fixup (.mnt_flags ↔ .min_swap_avail): verified correct.

Shell API variables: spot-checked TST_NEEDS_KCONFIGS_IFS, TST_FS_TYPE (default ext2), TST_TEST_DATA_IFS (default space), checkpoint functions and retry helpers — all accurate.

No issues found in this commit.

---

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

Claim: "10 headers" added.
Verified in the api_c_tests.rst diff:
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 — count 10 is correct.

Claim: removing @param, @return, @relates, @sa Doxygen directives.
Verified: @param in tst_kconfig.h, @return in tst_device.h, @sa and @relates in tst_fuzzy_sync.h — all removed. Correct.

BUG 1 — include/tst_device.h: missing blank line

After the patch, tst_mount_has_opt()'s declaration is immediately followed by the kernel-doc comment for tst_is_mounted() with no blank line between them. Every other consecutive function pair in the file (tst_is_mounted / tst_is_mounted_ro, tst_is_mounted_ro / tst_is_mounted_rw, etc.) has a blank line separating the declaration from the next /** block. Please add the missing blank line:

Quoted 3 lines

int tst_mount_has_opt(const char *path, const char *opt); /**
* tst_is_mounted() - Check if a path is a mount point.

Should be:

  int tst_mount_has_opt(const char *path, const char *opt);

/**
* tst_is_mounted() - Check if a path is a mount point.

BUG 2 — include/tst_kconfig.h: TST_KCONFIG_INIT() drops string.h note

The original comment read:
"Initialization helper macro for struct tst_kconfig_var.
Requires <string.h>"

The new kernel-doc comment omits the <string.h> requirement:
"TST_KCONFIG_INIT() - Initialization helper macro for struct
tst_kconfig_var."

The macro expands to { .id_len = strlen(confname) }, which requires strlen(). tst_kconfig.h includes only <stdbool.h> and <stddef.h>, not <string.h>. The original "Requires <string.h>" note was there for a reason. Please preserve it, e.g.:

/**
* TST_KCONFIG_INIT() - Initialization helper macro for struct
* tst_kconfig_var. Requires <string.h> for strlen().
* @confname: Config variable name string.
*/

MINOR — include/tst_device.h: tst_device global uses /* not /**

The tst_device extern pointer:

/*
* tst_device - Pointer to the test block device.
* ...
*/
extern struct tst_device *tst_device;

uses a plain /* comment, so the kernel-doc extractor will not emit an entry for it even though api_c_tests.rst now includes
.. kernel-doc:: ../../include/tst_device.h. The struct tst_device doc block above already carries the "Automatically initialized if tst_test.needs_device is set." note, so this may be intentional. If the intent is to have the variable appear in the API docs, change /* to /**.

---

Verdict: Needs revision (BUG 1 and BUG 2 above).

LTP AI Reviewer

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

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

In reply to Andrea Cervesato

From: Andrea Cervesato <[email protected]>

Add 8 missing struct tst_test fields to the C/Shell API comparison table in writing_tests.rst: .filesystems, .forks_child, .min_runtime, .needs_abi_bits, .needs_cgroup_nsdelegate, .needs_cgroup_ver, .needs_hugetlbfs and .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..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
#4 lore raw

PATCH v2 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 245 SAFE_* wrapper macros grouped by header and category (file ops, memory, process, signals, networking, pthreads, IPC, cgroups, clocks, etc.).

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

---
 doc/developers/api_safe_macros.rst | 382 +++++++++++++++++++++++++++++++++++++
 doc/index.rst                      |   4 +
 2 files changed, 386 insertions(+)
doc/developers/api_safe_macros.rst new file +382 -0
new file mode 100644
index 0000000000000000000000000000000000000000..379394b2c2c5c9b7965cd95e6d602f774aa854d9
@@ -0,0 +1,382 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. Copyright (c) Linux Test Project, 2026
+
+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_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)``
+
+Filesystem creation (tst_mkfs.h)
+--------------------------------
+
+- ``SAFE_MKFS(device, fs_type, fs_opts, extra_opts)``
+
+Process creation (tst_clone.h, tst_test.h)
+------------------------------------------
+
+- ``SAFE_CLONE(args)``
+- ``SAFE_FORK()``
+
+Control groups (tst_cgroup.h)
+-----------------------------
+
+- ``SAFE_CG_HAS(cg, file_name)``
+- ``SAFE_CG_OPEN(cg, file_name, flags, fds)``
+- ``SAFE_CG_READ(cg, file_name, out, len)``
+- ``SAFE_CG_PRINT(cg, file_name, str)``
+- ``SAFE_CG_PRINTF(cg, file_name, fmt, ...)``
+- ``SAFE_CG_SCANF(cg, file_name, fmt, ...)``
+- ``SAFE_CG_LINES_SCANF(cg, file_name, fmt, ...)``
+- ``SAFE_CG_OCCURSIN(cg, file_name, needle)``
+- ``SAFE_CG_FCHOWN(cg, file_name, owner, group)``
+
+Epoll (tst_epoll.h)
+-------------------
+
+- ``SAFE_EPOLL_CREATE1(flags)``
+- ``SAFE_EPOLL_CTL(epfd, op, fd, ev)``
+- ``SAFE_EPOLL_WAIT(epfd, events, maxevents, timeout)``
+
+Swap files (tse_swap.h)
+-----------------------
+
+- ``SAFE_MAKE_SMALL_SWAPFILE(swapfile)``
+- ``SAFE_MAKE_SWAPFILE_SIZE(swapfile, size)``
+- ``SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks)``
+
+Realtime signals (lapi/safe_rt_signal.h)
+----------------------------------------
+
+- ``SAFE_RT_SIGACTION(signum, act, oldact, sigsetsize)``
+- ``SAFE_RT_SIGPROCMASK(how, set, oldset, sigsetsize)``
+
+Fallback syscall wrappers (include/lapi/)
+-----------------------------------------
+
+- ``SAFE_STATX(dirfd, pathname, flags, mask, buf)``
+- ``SAFE_FCHMODAT2(dfd, filename, mode, flags)``
+- ``SAFE_SPLICE(fd_in, off_in, fd_out, off_out, len, flags)``
+- ``SAFE_KEYCTL(cmd, arg2, arg3, arg4, arg5)``
+- ``SAFE_USERFAULTFD(flags, retry)``
+- ``SAFE_MODIFY_LDT(func, ptr, bytecount)``
+- ``SAFE_LANDLOCK_CREATE_RULESET(attr, size, flags)``
+- ``SAFE_LANDLOCK_ADD_RULE(ruleset_fd, rule_type, rule_attr, flags)``
+- ``SAFE_LANDLOCK_RESTRICT_SELF(ruleset_fd, flags)``
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