[LTP] [PATCH v5 2/3] doc: Complete struct tst_test table and shell API docs
Andrea Cervesato
andrea.cervesato@suse.de
Thu Jun 4 10:45:09 CEST 2026
From: Andrea Cervesato <andrea.cervesato@suse.com>
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.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
doc/developers/api_shell_tests.rst | 183 +++++++++++++++++++++++++++++++++++++
doc/developers/writing_tests.rst | 28 +++++-
2 files changed, 209 insertions(+), 2 deletions(-)
diff --git a/doc/developers/api_shell_tests.rst b/doc/developers/api_shell_tests.rst
index 937ffee2ea468552e5160775153990f13ea10f88..a70b118db544137850368bb4502c4e93ab1a1589 100644
--- a/doc/developers/api_shell_tests.rst
+++ b/doc/developers/api_shell_tests.rst
@@ -93,3 +93,186 @@ 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_DISABLE_APPARMOR``
+ Set to 1 to disable AppArmor before the test runs (requires root).
+
+``TST_DISABLE_SELINUX``
+ Set to 1 to put SELinux in permissive mode before the test runs
+ (requires root).
+
+``TST_SKIP_LSM_WARNINGS``
+ Set to 1 to suppress the library's warnings about active LSMs
+ (AppArmor, SELinux) at startup.
+
+``TST_NO_DEFAULT_RUN``
+ Set to a non-empty value to source ``tst_test.sh`` without invoking
+ ``tst_run`` automatically. Useful for shell libraries that build on
+ top of the test API.
+
+``TST_TIMEOUT``
+ Test timeout in seconds.
+
+``TST_TMPDIR_RHOST``
+ Set to 1 to also clean up the temporary directory on the remote
+ host (used by network tests).
+
+Output variables
+~~~~~~~~~~~~~~~~
+
+``TST_TMPDIR``
+ Path to the temporary directory (when ``TST_NEEDS_TMPDIR=1``).
+
+``TST_STARTWD``
+ Original working directory before ``chdir`` to ``TST_TMPDIR``.
+
+``TST_DEVICE``
+ Block device path (when ``TST_NEEDS_DEVICE=1``).
+
+``TST_MNTPOINT``
+ Mount point path.
+
+``TST_MODPATH``
+ Path to the loaded kernel module.
+
+Checkpoint functions
+~~~~~~~~~~~~~~~~~~~~
+
+``TST_CHECKPOINT_WAIT``
+ Wait on checkpoint (argument: checkpoint id).
+
+``TST_CHECKPOINT_WAKE``
+ Wake one waiter on checkpoint (argument: checkpoint id).
+
+``TST_CHECKPOINT_WAKE2``
+ Wake multiple waiters (arguments: checkpoint id, count).
+
+``TST_CHECKPOINT_WAKE_AND_WAIT``
+ Wake one waiter and then wait (argument: checkpoint id).
+
+Retry helpers
+~~~~~~~~~~~~~
+
+``TST_RETRY_FUNC``
+ Retry a function until it succeeds or times out
+ (arguments: function, expected value).
+
+``TST_RETRY_FN_EXP_BACKOFF``
+ Like ``TST_RETRY_FUNC`` with exponential backoff
+ (arguments: function, expected value, max delay).
diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
index dc40324b16d40c4d210fe0dfa6b311b5b3337c7a..4db57898fcf08b83e68be996f666e91c418838fc 100644
--- a/doc/developers/writing_tests.rst
+++ b/doc/developers/writing_tests.rst
@@ -382,6 +382,12 @@ LTP C And Shell Test API Comparison
* - .dev_min_size
- TST_DEVICE_SIZE
+ * - .filesystems
+ - \-
+
+ * - .forks_child
+ - not applicable
+
* - .format_device
- TST_FORMAT_DEVICE
@@ -399,21 +405,33 @@ LTP C And Shell Test API Comparison
* - .min_mem_avail
- not applicable
- * - .mnt_flags
- - TST_MNT_PARAMS
+ * - .min_runtime
+ - \-
* - .min_swap_avail
- not applicable
+ * - .mnt_flags
+ - TST_MNT_PARAMS
+
* - .mntpoint | .mnt_data
- TST_MNTPOINT
* - .mount_device
- TST_MOUNT_DEVICE
+ * - .needs_abi_bits
+ - not applicable
+
* - .needs_cgroup_ctrls
- \-
+ * - .needs_cgroup_nsdelegate
+ - \-
+
+ * - .needs_cgroup_ver
+ - \-
+
* - .needs_checkpoints
- TST_NEEDS_CHECKPOINTS
@@ -426,6 +444,9 @@ LTP C And Shell Test API Comparison
* - .needs_device
- TST_NEEDS_DEVICE
+ * - .needs_hugetlbfs
+ - \-
+
* - removed
- TST_NEEDS_DRIVERS
@@ -453,6 +474,9 @@ LTP C And Shell Test API Comparison
* - .restore_wallclock
- not applicable
+ * - .runs_script
+ - not applicable
+
* - .sample
- \-
--
2.51.0
More information about the ltp
mailing list