* [LTP] [PATCH v2 1/9] doc: Fix examples and generated links
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 2/9] doc: Correct guide and API descriptions Andrea Cervesato
` (9 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Correct invalid tags array syntax and the missing block terminator in
the shell API example. Fix the musl git commit URL and the getdents64
path in Sphinx configuration. Replace a hardcoded HTML anchor with a
Sphinx reference so it resolves across all documentation builders.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
doc/conf.py | 4 ++--
doc/developers/api_shell_tests.rst | 7 ++++---
doc/users/testers_guide.rst | 4 ++--
3 files changed, 8 insertions(+), 7 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index c28db7af1..2854fe199 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -89,7 +89,7 @@ def generate_supported_syscalls(_):
'file_getattr': f'{ltp_syscalls_path}/file_attr',
'file_setattr': f'{ltp_syscalls_path}/file_attr',
'futex': f'{ltp_syscalls_path}/futex',
- 'getdents64': f'{ltp_syscalls_path}/gettdents',
+ 'getdents64': f'{ltp_syscalls_path}/getdents',
'inotify_add_watch': f'{ltp_syscalls_path}/inotify',
'inotify_init': f'{ltp_syscalls_path}/inotify',
'inotify_rm_watch': f'{ltp_syscalls_path}/inotify',
@@ -293,7 +293,7 @@ def _generate_tags_table(tags):
"linux-git": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=",
"linux-stable-git": "https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/?id=",
"glibc-git": "https://sourceware.org/git/?p=glibc.git;a=commit;h=",
- "musl-git": "https://git.musl-libc.org/cgit/musl/commit/src/linux/clone.c?id=",
+ "musl-git": "https://git.musl-libc.org/cgit/musl/commit/?id=",
"CVE": cve_url + 'CVE-',
}
diff --git a/doc/developers/api_shell_tests.rst b/doc/developers/api_shell_tests.rst
index 937ffee2e..a972900b1 100644
--- a/doc/developers/api_shell_tests.rst
+++ b/doc/developers/api_shell_tests.rst
@@ -41,10 +41,11 @@ when it's empty.
# "needs_root": true,
# "needs_tmpdir": true,
# "needs_kconfigs": ["CONFIG_NUMA=y"],
- # "tags": {
- # ["linux-git", "432fd03240fa"]
- # }
+ # "tags": [
+ # ["linux-git", "cf01fb9985e8deb25ccf0ea54d916b8871ae0e62"]
+ # ]
# }
+ # ---
After the documentation and environment has been laid out we finally import the
:shell_lib:`tst_loader.sh`. This will, among other things, start the
diff --git a/doc/users/testers_guide.rst b/doc/users/testers_guide.rst
index c0eba64bf..b30b7ac7a 100644
--- a/doc/users/testers_guide.rst
+++ b/doc/users/testers_guide.rst
@@ -61,8 +61,8 @@ devices for these testcases, that can be changed with environment variables as
well. Lastly but not least a few testcases repeat the test for all supported
filesystem, if you are interested in testing on a single filesystem only, you
can limit these tests to a single filesystem too. See the tests setup for a
-comprehensive list of the `environment variables
-<setup_tests.html#library-environment-variables>`_.
+comprehensive list of the :ref:`environment variables
+<users/setup_tests:Library environment variables>`.
Then you also have to decide if you are going to run tests in virtual machine
e.g. `qemu-kvm`, on bare metal or both. Testing in virtual machine will give you
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* [LTP] [PATCH v2 2/9] doc: Correct guide and API descriptions
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 1/9] doc: Fix examples and generated links Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 10:59 ` Petr Vorel
2026-09-11 7:04 ` [LTP] [PATCH v2 3/9] doc: Clarify API coverage and navigation Andrea Cervesato
` (8 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Fix tutorial command options, the cleanup descriptor handling example,
and typo fixes. Correct the CPP variable name in the build system guide
and fix grammar and section references in INSTALL. Complete the argv
documentation for tst_cmd(), fix /proc paths and exit condition in
process state documentation, and correct comparison macro and NUMA types.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
INSTALL | 10 +++++-----
doc/developers/build_system.rst | 2 +-
doc/developers/test_case_tutorial.rst | 27 +++++++++++++++------------
include/tse_numa.h | 2 +-
include/tst_cmd.h | 2 ++
include/tst_process_state.h | 8 ++++----
include/tst_test_macros.h | 24 ++++++++++++------------
7 files changed, 40 insertions(+), 35 deletions(-)
diff --git a/INSTALL b/INSTALL
index b5c89de32..2a6b5aac2 100644
--- a/INSTALL
+++ b/INSTALL
@@ -113,7 +113,7 @@ groups. If these IDs do not exist, certain tests will fail. The respective
user and group IDs should be the same, i.e. if `nobody's' user ID is 99, then
its group ID should also be 99. The names of the groups are irrelevant.
- The installation directory is /opt/ltp by default. Please see
-"Using autoconf" above and specify the appropriate path via --prefix.
+"Configuration" above and specify the appropriate path via --prefix.
DESTDIR= is also honored for install and will install into $DESTDIR/$prefix,
if you want to install into a chroot or a rootfs for instance.
@@ -139,7 +139,7 @@ contributions are welcome.
3. Build and install everything, as described above. Note the minimum software
requirements above before doing so.
-4. The network tests related installation see testcases/network/README.md.
+4. For network test installation, see testcases/network/README.md.
Cross compiling
---------------
@@ -150,7 +150,7 @@ For correct pkgconf / pkg-config detection you need to set
PKG_CONFIG_SYSROOT_DIR=$SYSROOT
After configure has run, it will generate include/mk/config.mk. You can tweak
-settings in there if need be, but you should not specificy settings on the
+settings in there if need be, but you should not specify settings on the
command-line when running make.
32 bit build on 64 bit machine
@@ -161,7 +161,7 @@ You need to set CFLAGS=-m32 LDFLAGS=-m32 and PKG_CONFIG_LIBDIR
* RPM based distributions (openSUSE, Fedora, etc.)
PKG_CONFIG_LIBDIR=/usr/lib/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure
-* Debian / Ubuntu and derivates
+* Debian / Ubuntu and derivatives
PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig CFLAGS=-m32 LDFLAGS=-m32 ./configure
* Arch Linux
@@ -174,7 +174,7 @@ LTP contains few kernel modules and tests which are using them.
These require to be built with the same kernel headers as the running kernel (SUT).
Sometimes the best way to achieve this is to compile them on the SUT.
-Due Linux Kernel Driver Interface unstability [1], error during building kernel
+Due to Linux Kernel Driver Interface instability [1], an error during building kernel
modules does not break the build. Make errors fatal can be done by FORCE_MODULES=1
make variable.
diff --git a/doc/developers/build_system.rst b/doc/developers/build_system.rst
index 8af431517..e62db7d97 100644
--- a/doc/developers/build_system.rst
+++ b/doc/developers/build_system.rst
@@ -135,7 +135,7 @@ been fulfilled (libraries, headers, etc).
* - $(CC)
- The system C compiler
- * - $(CCP)
+ * - $(CPP)
- The system C preprocessor
* - $(CFLAGS)
diff --git a/doc/developers/test_case_tutorial.rst b/doc/developers/test_case_tutorial.rst
index 930e0f989..679de7cde 100644
--- a/doc/developers/test_case_tutorial.rst
+++ b/doc/developers/test_case_tutorial.rst
@@ -205,7 +205,7 @@ please do:
This should build the test and then run it. However, even though the test is
in :master:`testcases/kernel/syscalls` directory it won't be automatically run
-as part of the syscalls test group (e.g. not run via ``kirk -f math``).
+as part of the syscalls test group (e.g. not run via ``kirk -f syscalls``).
For this we need to add it to the runtest file. So open :master:`runtest/syscalls`
and add the lines starting with a ``+``.
@@ -292,7 +292,7 @@ Check coding style with ``make check``.
Install the LTP and run the test with runtest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Run ``statx01`` on its own, also using ``-I0`` amd ``-I10``.
+Run ``statx01`` on its own, also using ``-i 0`` and ``-i 10``.
Call the system call
--------------------
@@ -435,7 +435,7 @@ there is a system in place to handle it.
.min_kver = "4.11",
};
-The ``TEST`` macro sets ``TST_RET`` to the return value of ``tst_statx()`` and
+The ``TEST`` macro sets ``TST_RET`` to the return value of ``sys_statx()`` and
``TST_ERR`` to the value of ``errno`` immediately after the functions
return. This is mainly just for convenience, although it potentially could
have other uses.
@@ -589,6 +589,9 @@ again on the hard-link, then ``stat`` the file".
#define LNAME "file_to_stat_link"
+ static int fd = -1;
+ static int lfd = -1;
+
...
static void setup(void)
@@ -600,16 +603,16 @@ again on the hard-link, then ``stat`` the file".
static void cleanup(void)
{
- if (lfd != 0)
+ if (lfd != -1)
SAFE_CLOSE(lfd);
- if (fd != 0)
+ if (fd != -1)
SAFE_CLOSE(fd);
}
static void run(void)
{
- ...
+ ...
TEST(sys_statx(AT_FDCWD, LNAME, 0, STATX_BASIC_STATS, &statxbuf));
if (TST_RET == 0)
@@ -646,8 +649,8 @@ Nor do we want to call ``cleanup`` recursively. So during ``cleanup``
``tst_brk``, and consequently the ``SAFE`` functions, do not cause the test to
exit with ``TBROK``. Instead they just print an error message with ``TWARN``.
-It is not entirely necessary to check if the file descriptors have a none zero
-value before attempting to close them. However it avoids a bunch of spurious
+It is not entirely necessary to check if the file descriptors are not -1
+before attempting to close them. However it avoids a bunch of spurious
warning messages if we fail to open ``file_to_stat``. Test case failures can be
difficult to interpret at the best of times, so avoid filling the log with
noise.
@@ -804,7 +807,7 @@ branch is ``tutorial-rebase2`` which I just created. I have already done one
``tutorial``.
As usual my commit history is starting to look like a bit of mess! There is
-even a commit in there which should not be in the this branch (Remove old API
+even a commit in there which should not be in this branch (Remove old API
argument), however it can be ignored for now and 'cherry picked' into a new branch
later.
@@ -821,7 +824,7 @@ of all I want to 'squash' (amalgamate) all the commits appended with
This begins an interactive ``rebase`` where commit ``5ca6427b78`` is the earliest
commit we want to edit. The ``^`` symbol after the commit hash, specifies the
commit before this one. The interactive ``rebase`` command takes the last commit
-we want to keep unaltered as it's argument (in other words it takes a
+we want to keep unaltered as its argument (in other words it takes a
non-inclusive range).
Upon entering a similar command you will be presented with a text file
@@ -993,8 +996,8 @@ Obviously testing the patch is one way of finding errors. You can apply patches
using :manpage:`git-am(1)`. Then it is just a case of compiling and running the
tests.
-Finally, reading and attempting to comment on other peoples patches, gives
-you a better understanding of the reviewers perspective. This is better for
+Finally, reading and attempting to comment on other people's patches, gives
+you a better understanding of the reviewer's perspective. This is better for
the project and for you.
Style and organizational issues are best left to after you have found logical
diff --git a/include/tse_numa.h b/include/tse_numa.h
index 839512b2a..4cbef63b7 100644
--- a/include/tse_numa.h
+++ b/include/tse_numa.h
@@ -109,7 +109,7 @@ enum tse_numa_types {
* tse_get_nodemap() - Allocates and returns numa node map, which is an array of numa nodes which
* contain desired resources e.g. memory.
*
- * @type: Bitflags of enum tst_numa_types specifying desired resources.
+ * @type: Bitflags of enum tse_numa_types specifying desired resources.
* @min_mem_kb: Minimal free RAM on memory nodes, if given node has less than
* requested amount of free+buffers memory it's not included in
* the resulting list of nodes.
diff --git a/include/tst_cmd.h b/include/tst_cmd.h
index 77fbbbc86..4829d0aed 100644
--- a/include/tst_cmd.h
+++ b/include/tst_cmd.h
@@ -72,6 +72,8 @@ static inline int tst_cmd_fds(const char *const argv[],
* tst_cmd() - Executes tst_cmd_fds() and redirects its output to a file.
*
* @argv: A list of two (at least program name + NULL) or more pointers that
+ * represent the argument list to the new program. The array of pointers
+ * must be terminated by a NULL pointer.
* @stdout_path: Path where to redirect stdout. Set NULL if redirection is
* not needed.
* @stderr_path: Path where to redirect stderr. Set NULL if redirection is
diff --git a/include/tst_process_state.h b/include/tst_process_state.h
index b0f640b06..674c54b0f 100644
--- a/include/tst_process_state.h
+++ b/include/tst_process_state.h
@@ -22,7 +22,7 @@
* @state: A state to wait for.
* @msec_timeout: A timeout for the wait.
*
- * Polls `/proc/$PID/state` for a process state changes.
+ * Polls `/proc/$PID/stat` for process state changes.
*
* Possible process states (see :manpage:`ps(1)`):
*
@@ -32,7 +32,7 @@
* - **Z** Zombie process.
* - **T** Process is traced.
* - **t** Tracing stopped.
- * - **X** Process id dead.
+ * - **X** Process is dead.
*/
#define TST_PROCESS_STATE_WAIT(pid, state, msec_timeout) \
tst_process_state_wait(__FILE__, __LINE__, NULL, \
@@ -41,7 +41,7 @@
/**
* TST_PROCESS_EXIT_WAIT() - Waits while pid is present on the system.
*
- * Loops until `kill($PID, 0)` succeds or timeout is reached.
+ * Loops until `kill($PID, 0)` fails with `ESRCH`, or timeout is reached.
*
* @pid: A process pid.
* @msec_timeout: A timeout for the wait.
@@ -52,7 +52,7 @@
/**
* TST_THREAD_STATE_WAIT() - Waits for a thread state change.
*
- * Polls `/proc/self/task/$TID/state` for a thread state change.
+ * Polls `/proc/self/task/$TID/stat` for a thread state change.
*
* Possible thread states are the same as for TST_PROCESS_STATE_WAIT().
*
diff --git a/include/tst_test_macros.h b/include/tst_test_macros.h
index 12bd9d47e..9a93331d5 100644
--- a/include/tst_test_macros.h
+++ b/include/tst_test_macros.h
@@ -880,10 +880,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, unsigned long long, "%llu")
/**
- * TST_EXP_EQ_SZ() - Compare two unsigned size_t values.
+ * TST_EXP_EQ_SZ() - Compare two size_t values.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: size_t value A.
+ * @VAL_B: size_t value B.
*
* Reports a pass if values are equal and a fail otherwise.
*/
@@ -898,10 +898,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} while (0)
/**
- * TST_EXP_EQ_SZ_SILENT() - Compare two unsigned size_t values, silent variant.
+ * TST_EXP_EQ_SZ_SILENT() - Compare two size_t values, silent variant.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: size_t value A.
+ * @VAL_B: size_t value B.
*
* Unlike TST_EXP_EQ_SZ() does not print :c:enum:`TPASS <tst_res_flags>` on
* success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
@@ -910,10 +910,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
TST_EXP_EQ_SILENT_(VAL_A, #VAL_A, VAL_B, #VAL_B, size_t, "%zu")
/**
- * TST_EXP_EQ_SSZ() - Compare two unsigned ssize_t values.
+ * TST_EXP_EQ_SSZ() - Compare two ssize_t values.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: ssize_t value A.
+ * @VAL_B: ssize_t value B.
*
* Reports a pass if values are equal and a fail otherwise.
*/
@@ -928,10 +928,10 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
} while (0)
/**
- * TST_EXP_EQ_SSZ_SILENT() - Compare two unsigned ssize_t values, silent variant.
+ * TST_EXP_EQ_SSZ_SILENT() - Compare two ssize_t values, silent variant.
*
- * @VAL_A: unsigned long long value A.
- * @VAL_B: unsigned long long value B.
+ * @VAL_A: ssize_t value A.
+ * @VAL_B: ssize_t value B.
*
* Unlike TST_EXP_EQ_SSZ() does not print :c:enum:`TPASS <tst_res_flags>` on
* success, only prints :c:enum:`TFAIL <tst_res_flags>` on failure.
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 2/9] doc: Correct guide and API descriptions
2026-09-11 7:04 ` [LTP] [PATCH v2 2/9] doc: Correct guide and API descriptions Andrea Cervesato
@ 2026-09-11 10:59 ` Petr Vorel
0 siblings, 0 replies; 18+ messages in thread
From: Petr Vorel @ 2026-09-11 10:59 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Andrea,
> +++ b/doc/developers/test_case_tutorial.rst
...
> @@ -292,7 +292,7 @@ Check coding style with ``make check``.
> Install the LTP and run the test with runtest
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -Run ``statx01`` on its own, also using ``-I0`` amd ``-I10``.
> +Run ``statx01`` on its own, also using ``-i 0`` and ``-i 10``.
I would still use -i0 and -i10 (without space).
BTW We have -i and -I, usually we use only -i, but -I would also be working.
In maintainers/patch_review.rst we propose -i, it's probably better to be
consistent.
Maybe it'd make sense to link maintainers/patch_review.rst here (how to check
your patchset before sending).
Anyway:
Reviewed-by: Petr Vorel <pvorel@suse.cz>
Kind regards,
Petr
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 18+ messages in thread
* [LTP] [PATCH v2 3/9] doc: Clarify API coverage and navigation
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 1/9] doc: Fix examples and generated links Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 2/9] doc: Correct guide and API descriptions Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 4/9] include: Document assertion API macros Andrea Cervesato
` (7 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add the testers guide description to the user documentation index.
Expand the network API page stub with single-host and two-host
overviews and references. Clarify the legacy shell API comparison table
and add the missing needs_cpu_vendor field.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
doc/developers/api_network_tests.rst | 5 ++---
doc/developers/writing_tests.rst | 8 ++++++++
doc/index.rst | 3 +++
3 files changed, 13 insertions(+), 3 deletions(-)
diff --git a/doc/developers/api_network_tests.rst b/doc/developers/api_network_tests.rst
index 3e487d7f2..116b56510 100644
--- a/doc/developers/api_network_tests.rst
+++ b/doc/developers/api_network_tests.rst
@@ -1,7 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
-.. Include headers in this file with:
-.. .. kernel-doc:: ../../include/tst_test.h
-
Developing using network API
============================
+
+Network tests are documented in :master:`testcases/network/README.md`.
diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
index 0edf101ff..9a56c0265 100644
--- a/doc/developers/writing_tests.rst
+++ b/doc/developers/writing_tests.rst
@@ -360,6 +360,11 @@ check :master:`.github/workflows/ci-docker-build.yml`.
LTP C And Shell Test API Comparison
-----------------------------------
+This table compares :c:struct:`tst_test` members in the C API with
+corresponding ``$TST_*`` variables in the legacy :shell_lib:`tst_test.sh`
+shell API. For tests using the new shell loader library, see
+:doc:`api_shell_tests`.
+
.. list-table::
:header-rows: 1
@@ -440,6 +445,9 @@ LTP C And Shell Test API Comparison
* - .needs_cmds
- TST_NEEDS_CMDS
+ * - .needs_cpu_vendor
+ - \-
+
* - .needs_devfs
- \-
diff --git a/doc/index.rst b/doc/index.rst
index 58944a72d..5f886eed2 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -53,6 +53,9 @@ For users
:doc:`users/setup_tests`
How to set up tests execution
+:doc:`users/testers_guide`
+ Guidelines and considerations when testing the Linux kernel with LTP
+
:doc:`users/supported_systems`
A list of supported technologies by the LTP framework
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* [LTP] [PATCH v2 4/9] include: Document assertion API macros
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (2 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 3/9] doc: Clarify API coverage and navigation Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 11:10 ` Petr Vorel
2026-09-11 7:04 ` [LTP] [PATCH v2 5/9] include: Document filesystem test utilities Andrea Cervesato
` (6 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add kernel-doc comments for the public assertion macros in
include/tst_assert.h to populate the Assertion section in the generated
C API documentation.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
include/tst_assert.h | 85 ++++++++++++++++++++++++++++++++++------------------
1 file changed, 56 insertions(+), 29 deletions(-)
diff --git a/include/tst_assert.h b/include/tst_assert.h
index dcb62dfea..e952f612f 100644
--- a/include/tst_assert.h
+++ b/include/tst_assert.h
@@ -7,58 +7,85 @@
#ifndef TST_ASSERT_H__
#define TST_ASSERT_H__
+/**
+ * TST_ASSERT_INT() - Asserts that integer value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected integer value.
+ *
+ * Reads an integer from the file at path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
#define TST_ASSERT_INT(path, val) \
tst_assert_int(__FILE__, __LINE__, path, val)
-/*
- * Asserts that integer value stored in file pointed by path equals to the
- * value passed to this function. This is mostly useful for asserting correct
- * values in sysfs, procfs, etc.
- */
void tst_assert_int(const char *file, const int lineno,
const char *path, int val);
+/**
+ * TST_ASSERT_FILE_INT() - Asserts that integer value for field in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @prefix: Field name or line prefix preceding the integer value.
+ * @val: Expected integer value.
+ *
+ * Scans lines in path for prefix followed by an integer.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
#define TST_ASSERT_FILE_INT(path, prefix, val) \
tst_assert_file_int(__FILE__, __LINE__, path, prefix, val)
-/*
- * Same as tst_assert_int() but for unsigned long.
- */
-void tst_assert_ulong(const char *file, const int lineno,
- const char *path, unsigned long val);
+void tst_assert_file_int(const char *file, const int lineno,
+ const char *path, const char *prefix, int val);
+/**
+ * TST_ASSERT_ULONG() - Asserts that unsigned long value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected unsigned long value.
+ *
+ * Reads an unsigned long from the file at path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
#define TST_ASSERT_ULONG(path, val) \
tst_assert_ulong(__FILE__, __LINE__, path, val)
-/*
- * Asserts that integer value stored in the prefix field of file pointed by path
- * equals to the value passed to this function. This is mostly useful for
- * asserting correct field values in sysfs, procfs, etc.
- */
-
-void tst_assert_file_int(const char *file, const int lineno,
- const char *path, const char *prefix, int val);
-
+void tst_assert_ulong(const char *file, const int lineno,
+ const char *path, unsigned long val);
+/**
+ * TST_ASSERT_STR() - Asserts that string value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected string value.
+ *
+ * Reads a whitespace-delimited string from path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
#define TST_ASSERT_STR(path, val) \
tst_assert_str(__FILE__, __LINE__, path, val)
-/*
- * Asserts that a string value stored in file pointed by path equals to the
- * value passed to this function. This is mostly useful for asserting correct
- * values in sysfs, procfs, etc.
- */
void tst_assert_str(const char *file, const int lineno,
const char *path, const char *val);
+/**
+ * TST_ASSERT_FILE_STR() - Asserts that string value for field in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @prefix: Field name or prefix preceding the string value.
+ * @val: Expected string value.
+ *
+ * Scans lines in path for prefix followed by ": " and a string value.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
#define TST_ASSERT_FILE_STR(path, prefix, val) \
tst_assert_file_str(__FILE__, __LINE__, path, prefix, val)
-/*
- * Asserts that a string value stored in the prefix field of file pointed by path
- * equals to the value passed to this function. This is mostly useful for
- * asserting correct field values in sysfs, procfs, etc.
- */
void tst_assert_file_str(const char *file, const int lineno,
const char *path, const char *prefix, const char *val);
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 4/9] include: Document assertion API macros
2026-09-11 7:04 ` [LTP] [PATCH v2 4/9] include: Document assertion API macros Andrea Cervesato
@ 2026-09-11 11:10 ` Petr Vorel
0 siblings, 0 replies; 18+ messages in thread
From: Petr Vorel @ 2026-09-11 11:10 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Andrea,
..
> +/**
> + * TST_ASSERT_FILE_STR() - Asserts that string value for field in file equals val.
> + *
> + * @path: Path to the file to check.
> + * @prefix: Field name or prefix preceding the string value.
> + * @val: Expected string value.
> + *
> + * Scans lines in path for prefix followed by ": " and a string value.
nit: there might be more whitespace chars after ":". Also formatting by `` ``
might be better.
* Scans lines in path for prefix followed by ``:`` followed by whitespace and a string value.
Otherwise LGTM.
Reviewed-by: Petr Vorel <pvorel@suse.cz>
> + * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
> + * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
> + */
> #define TST_ASSERT_FILE_STR(path, prefix, val) \
> tst_assert_file_str(__FILE__, __LINE__, path, prefix, val)
> -/*
> - * Asserts that a string value stored in the prefix field of file pointed by path
> - * equals to the value passed to this function. This is mostly useful for
> - * asserting correct field values in sysfs, procfs, etc.
> - */
> void tst_assert_file_str(const char *file, const int lineno,
> const char *path, const char *prefix, const char *val);
I guess it's safe to expect the readers will be using macros, not the functions
themselves (that's for use in LTP library itself) => good to move kerneldoc from
functions to macros.
Kind regards,
Petr
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 18+ messages in thread
* [LTP] [PATCH v2 5/9] include: Document filesystem test utilities
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (3 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 4/9] include: Document assertion API macros Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 11:19 ` Petr Vorel
2026-09-11 7:04 ` [LTP] [PATCH v2 6/9] include: Document memory " Andrea Cervesato
` (5 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add kernel-doc comments for filesystem query and file creation helpers
in include/tst_fs.h. Document new-API wrappers so they render properly
in the generated documentation.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
include/tst_fs.h | 186 +++++++++++++++++++++++++++++++++++++------------------
1 file changed, 127 insertions(+), 59 deletions(-)
diff --git a/include/tst_fs.h b/include/tst_fs.h
index c55f8a646..80eb1292e 100644
--- a/include/tst_fs.h
+++ b/include/tst_fs.h
@@ -67,32 +67,21 @@ int tst_fs_has_free_(void (*cleanup)(void), const char *path, uint64_t size,
unsigned int mult);
/*
- * Returns filesystem magick for a given path.
+ * Returns filesystem magic for a given path.
*
* The expected usage is:
*
- * if (tst_fs_type(cleanup, ".") == TST_NFS_MAGIC) {
- * tst_brkm(TCONF, cleanup,
- * "Test not supported on NFS filesystem");
- * }
- *
- * Or:
- *
- * long type;
- *
- * switch ((type = tst_fs_type(cleanup, "."))) {
- * case TST_NFS_MAGIC:
- * case TST_TMPFS_MAGIC:
- * case TST_RAMFS_MAGIC:
- * tst_brkm(TCONF, cleanup, "Test not supported on %s filesystem",
- * tst_fs_type_name(type));
- * break;
- * }
+ * if (tst_fs_type(".") == TST_NFS_MAGIC)
+ * tst_brk(TCONF, "Test not supported on NFS filesystem");
*/
long tst_fs_type_(void (*cleanup)(void), const char *path);
-/*
- * Returns filesystem name given magic.
+/**
+ * tst_fs_type_name() - Returns filesystem name given magic.
+ *
+ * @f_type: Filesystem magic number.
+ *
+ * Return: Name of the filesystem as a string.
*/
const char *tst_fs_type_name(long f_type);
@@ -139,10 +128,14 @@ int tst_fs_fill_subdirs_(void (*cleanup) (void), const char *dir);
*/
int tst_dir_is_empty_(void (*cleanup)(void), const char *name, int verbose);
-/*
- * Search $PATH for prog_name and fills buf with absolute path if found.
+/**
+ * tst_get_path() - Searches PATH for program and returns its absolute path.
+ *
+ * @prog_name: Name of executable to look up.
+ * @buf: Buffer to store the absolute path.
+ * @buf_len: Size of the buffer in bytes.
*
- * Returns -1 on failure, either command was not found or buffer was too small.
+ * Return: 0 on success, -1 on failure (command not found or buffer too small).
*/
int tst_get_path(const char *prog_name, char *buf, size_t buf_len);
@@ -156,38 +149,53 @@ int tst_get_path(const char *prog_name, char *buf, size_t buf_len);
int tst_path_exists(const char *fmt, ...)
__attribute__ ((format (printf, 1, 2)));
-/*
- * Fill a file with specified pattern
- * @fd: file descriptor
- * @pattern: pattern
- * @bs: block size
- * @bcount: blocks count
+/**
+ * tst_fill_fd() - Fills an open file descriptor with pattern.
+ *
+ * @fd: File descriptor to write to.
+ * @pattern: Byte pattern to fill with.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Return: 0 on success, non-zero on error.
*/
int tst_fill_fd(int fd, char pattern, size_t bs, size_t bcount);
-/*
- * Preallocate space in open file. If fallocate() fails, falls back to
- * using tst_fill_fd().
- * @fd: file descriptor
- * @bs: block size
- * @bcount: blocks count
+/**
+ * tst_prealloc_size_fd() - Preallocates space in open file descriptor.
+ *
+ * @fd: File descriptor to preallocate space in.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * If fallocate() fails, falls back to using tst_fill_fd().
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_prealloc_size_fd(int fd, size_t bs, size_t bcount);
-/*
- * Creates/ovewrites a file with specified pattern
- * @path: path to file
- * @pattern: pattern
- * @bs: block size
- * @bcount: blocks amount
+/**
+ * tst_fill_file() - Creates or overwrites a file with pattern.
+ *
+ * @path: Path to the file.
+ * @pattern: Byte pattern to fill with.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_fill_file(const char *path, char pattern, size_t bs, size_t bcount);
-/*
- * Creates file of specified size. Space will be only preallocated if possible.
- * @path: path to file
- * @bs: block size
- * @bcount: blocks amount
+/**
+ * tst_prealloc_file() - Creates file of specified size.
+ *
+ * @path: Path to the file.
+ * @bs: Block size in bytes.
+ * @bcount: Number of blocks.
+ *
+ * Space will be preallocated if supported, otherwise filled with zeroes.
+ *
+ * Return: 0 on success, non-zero on failure.
*/
int tst_prealloc_file(const char *path, size_t bs, size_t bcount);
@@ -197,56 +205,116 @@ enum tst_fs_impl {
TST_FS_FUSE = 2,
};
-/*
- * Returns if filesystem is supported and if driver is in kernel or FUSE.
+/**
+ * tst_fs_is_supported() - Checks if filesystem is supported.
*
- * @fs_type A filesystem name to check the support for.
+ * @fs_type: Filesystem name to check support for.
+ *
+ * Return: TST_FS_KERNEL if driver is in kernel, TST_FS_FUSE if driver is
+ * in FUSE, or TST_FS_UNSUPPORTED otherwise.
*/
enum tst_fs_impl tst_fs_is_supported(const char *fs_type);
-/*
- * Returns 1 if filesystem is in skiplist 0 otherwise.
+/**
+ * tst_fs_in_skiplist() - Checks if filesystem is in skiplist.
+ *
+ * @fs_type: Filesystem type to look up.
+ * @skiplist: NULL-terminated array of filesystems to skip.
*
- * @fs_type A filesystem type to lookup.
- * @skiplist A NULL terminated array of filesystems to skip.
+ * Return: 1 if filesystem is in skiplist, 0 otherwise.
*/
int tst_fs_in_skiplist(const char *fs_type, const char *const *skiplist);
-/*
- * Creates and writes to files on given path until write fails with ENOSPC
+/**
+ * tst_fill_fs() - Writes to files on given path until ENOSPC.
+ *
+ * @path: Path to directory on filesystem.
+ * @verbose: If non-zero, prints information messages.
+ * @pattern: Pattern access type (TST_FILL_BLOCKS or TST_FILL_RANDOM).
*/
void tst_fill_fs(const char *path, int verbose, enum tst_fill_access_pattern pattern);
-/*
- * Check if FIBMAP ioctl is supported.
- * Tests needs to set .needs_root = 1 in order to avoid EPERM.
+/**
+ * tst_fibmap() - Checks if FIBMAP ioctl is supported.
+ *
+ * @filename: Path to file to check.
*
- * @return 0: FIBMAP is supported, 1: FIBMAP is *not* supported.
+ * Tests need to set .needs_root = 1 in order to avoid EPERM.
+ *
+ * Return: 0 if FIBMAP is supported, 1 if FIBMAP is not supported.
*/
int tst_fibmap(const char *filename);
#ifdef TST_TEST_H__
+/**
+ * tst_fs_type() - Returns filesystem magic for a given path.
+ *
+ * @path: Path to inspect.
+ *
+ * Return: Filesystem magic number.
+ */
static inline long tst_fs_type(const char *path)
{
return tst_fs_type_(NULL, path);
}
+/**
+ * tst_fs_has_free() - Checks if filesystem has sufficient free space.
+ *
+ * @path: Pathname of any file within the mounted filesystem.
+ * @size: Space amount.
+ * @mult: Multiplier for size (TST_BYTES, TST_KB, TST_MB, or TST_GB).
+ *
+ * Return: 1 if required free space is available, 0 otherwise.
+ */
static inline int tst_fs_has_free(const char *path, uint64_t size,
unsigned int mult)
{
return tst_fs_has_free_(NULL, path, size, mult);
}
+/**
+ * tst_fs_fill_hardlinks() - Creates maximum number of hard links in directory.
+ *
+ * @dir: Directory path where hard links are created.
+ *
+ * Creates hard links to a single file inside dir until EMLINK or 65535 links
+ * is reached. If the limit is reached, created files are left in dir and the
+ * count is returned. If no limit is reached or link() fails with ENOSPC or
+ * EDQUOT, previously created files are removed and 0 is returned.
+ *
+ * Return: Number of hard links on success, 0 on failure or no limit.
+ */
static inline int tst_fs_fill_hardlinks(const char *dir)
{
return tst_fs_fill_hardlinks_(NULL, dir);
}
+/**
+ * tst_fs_fill_subdirs() - Creates maximum number of subdirectories in directory.
+ *
+ * @dir: Directory path where subdirectories are created.
+ *
+ * Creates subdirectories in dir until EMLINK or 65535 directories is reached.
+ * If the limit is reached, created directories are left in dir and the count
+ * is returned. If no limit is reached or mkdir() fails with ENOSPC or EDQUOT,
+ * previously created directories are removed and 0 is returned.
+ *
+ * Return: Number of subdirectories on success, 0 on failure or no limit.
+ */
static inline int tst_fs_fill_subdirs(const char *dir)
{
return tst_fs_fill_subdirs_(NULL, dir);
}
+/**
+ * tst_dir_is_empty() - Checks if directory contains any entries.
+ *
+ * @name: Path to the directory.
+ * @verbose: If non-zero, prints messages about directory contents.
+ *
+ * Return: 1 if directory is empty (only '.' and '..'), 0 otherwise.
+ */
static inline int tst_dir_is_empty(const char *name, int verbose)
{
return tst_dir_is_empty_(NULL, name, verbose);
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* [LTP] [PATCH v2 6/9] include: Document memory test utilities
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (4 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 5/9] include: Document filesystem test utilities Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 11:39 ` Petr Vorel
2026-09-11 7:04 ` [LTP] [PATCH v2 7/9] include: Document safe file operations Andrea Cervesato
` (4 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add kernel-doc comments for memory pollution, available memory/swap
queries, and OOM protection helpers in include/tst_memutils.h.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
include/tst_memutils.h | 70 ++++++++++++++++++++++++--------------------------
1 file changed, 33 insertions(+), 37 deletions(-)
diff --git a/include/tst_memutils.h b/include/tst_memutils.h
index 57c90c4a9..e3f18c45e 100644
--- a/include/tst_memutils.h
+++ b/include/tst_memutils.h
@@ -6,55 +6,51 @@
#ifndef TST_MEMUTILS_H__
#define TST_MEMUTILS_H__
-/*
- * Fill up to maxsize physical memory with fillchar, then free it for reuse.
- * If maxsize is zero, fill as much memory as possible. This function is
- * intended for data disclosure vulnerability tests to reduce the probability
- * that a vulnerable kernel will leak a block of memory that was full of
- * zeroes by chance.
+/**
+ * tst_pollute_memory() - Fills physical memory with a byte pattern.
+ *
+ * @maxsize: Maximum memory size in bytes to fill (0 for maximum possible).
+ * @fillchar: Byte value to write into allocated memory.
*
- * The function keeps a safety margin to avoid invoking OOM killer and
- * respects the limitations of available address space. (Less than 3GB can be
- * polluted on a 32bit system regardless of available physical RAM.)
+ * Fills up to maxsize physical memory with fillchar, then frees it for reuse.
+ * Keeps a safety margin to avoid invoking the OOM killer and respects address
+ * space limits.
*/
void tst_pollute_memory(size_t maxsize, int fillchar);
-/*
- * Read the value of MemAvailable from /proc/meminfo, if no support on
- * older kernels, return 'MemFree + Cached' for instead.
+/**
+ * tst_available_mem() - Reads available memory from /proc/meminfo.
+ *
+ * Reads MemAvailable from /proc/meminfo. On older kernels without MemAvailable,
+ * falls back to MemFree + Cached.
+ *
+ * Return: Available memory in KiB.
*/
long long tst_available_mem(void);
-/*
- * Read the value of SwapFree from /proc/meminfo.
+/**
+ * tst_available_swap() - Reads free swap from /proc/meminfo.
+ *
+ * Return: Available swap space in KiB.
*/
long long tst_available_swap(void);
-/*
- * Enable OOM protection to prevent process($PID) being killed by OOM Killer.
- * echo -1000 >/proc/$PID/oom_score_adj
- *
- * If the pid is 0 which means it will set on current(self) process.
- *
- * Unless the process has CAP_SYS_RESOURCE this call will be no-op because
- * setting adj value < 0 requires it.
+/**
+ * tst_enable_oom_protection() - Protects process from OOM killer.
*
- * CAP_SYS_RESOURCE:
- * set /proc/[pid]/oom_score_adj to a value lower than the value last set
- * by a process with CAP_SYS_RESOURCE.
+ * @pid: Process PID to protect, or 0 for the calling process.
*
- * Note:
- * This exported tst_enable_oom_protection function can be used at anywhere
- * you want to protect, but please remember that if you do enable protection
- * on a process($PID) that all the children will inherit its score and be
- * ignored by OOM Killer as well. So that's why tst_disable_oom_protection()
- * to be used in combination.
+ * Sets /proc/[pid]/oom_score_adj to -1000. Requires CAP_SYS_RESOURCE; no-op
+ * without this capability. Child processes inherit the OOM score.
*/
void tst_enable_oom_protection(pid_t pid);
-/*
- * Disable the OOM protection for the process($PID).
- * echo 0 >/proc/$PID/oom_score_adj
+/**
+ * tst_disable_oom_protection() - Disables OOM protection for process.
+ *
+ * @pid: Process PID, or 0 for the calling process.
+ *
+ * Sets /proc/[pid]/oom_score_adj to 0.
*/
void tst_disable_oom_protection(pid_t pid);
@@ -63,10 +59,10 @@ void tst_disable_oom_protection(pid_t pid);
/**
* tst_mapping_in_range() - Returns true if there is a mapping provided range.
*
- * @low: A lower address inside of the processe address space.
- * @high: A higher address inside of the processe address space.
+ * @low: A lower address inside of the process address space.
+ * @high: A higher address inside of the process address space.
*
- * return: Returns true if there is a mapping between low and high addresses in
+ * Return: Returns true if there is a mapping between low and high addresses in
* the process address space.
*/
int tst_mapping_in_range(unsigned long low, unsigned long high);
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 6/9] include: Document memory test utilities
2026-09-11 7:04 ` [LTP] [PATCH v2 6/9] include: Document memory " Andrea Cervesato
@ 2026-09-11 11:39 ` Petr Vorel
0 siblings, 0 replies; 18+ messages in thread
From: Petr Vorel @ 2026-09-11 11:39 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Andrea,
> +++ b/include/tst_memutils.h
...
> -/*
> - * Read the value of SwapFree from /proc/meminfo.
> +/**
> + * tst_available_swap() - Reads free swap from /proc/meminfo.
Maybe worth tho note SwapFree:
* tst_available_swap() - Reads free swap from /proc/meminfo using SwapFree.
> + *
> + * Return: Available swap space in KiB.
> */
> long long tst_available_swap(void);
...
> @@ -63,10 +59,10 @@ void tst_disable_oom_protection(pid_t pid);
> /**
> * tst_mapping_in_range() - Returns true if there is a mapping provided range.
> *
> - * @low: A lower address inside of the processe address space.
> - * @high: A higher address inside of the processe address space.
> + * @low: A lower address inside of the process address space.
> + * @high: A higher address inside of the process address space.
> *
> - * return: Returns true if there is a mapping between low and high addresses in
> + * Return: Returns true if there is a mapping between low and high addresses in
> * the process address space.
This is causes wrong formatting: "Returns true if there is a mapping between low
and high addresses in" being bold. Please adjust before merge.
Reviewed-by: Petr Vorel <pvorel@suse.cz>
Kind regards,
Petr
diff --git include/tst_memutils.h include/tst_memutils.h
index e3f18c45ef..2be476191f 100644
--- include/tst_memutils.h
+++ include/tst_memutils.h
@@ -63,7 +63,7 @@ void tst_disable_oom_protection(pid_t pid);
* @high: A higher address inside of the process address space.
*
* Return: Returns true if there is a mapping between low and high addresses in
- * the process address space.
+ * the process address space.
*/
int tst_mapping_in_range(unsigned long low, unsigned long high);
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [LTP] [PATCH v2 7/9] include: Document safe file operations
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (5 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 6/9] include: Document memory " Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 7:04 ` [LTP] [PATCH v2 8/9] doc: Document CPU and common test helpers Andrea Cervesato
` (3 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add kernel-doc comments for safe file scanning, formatted writing,
file copying, touching, and overlayfs mounting in
include/tst_safe_file_ops.h.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
include/tst_safe_file_ops.h | 59 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/include/tst_safe_file_ops.h b/include/tst_safe_file_ops.h
index 0fc1a160c..c620d0dec 100644
--- a/include/tst_safe_file_ops.h
+++ b/include/tst_safe_file_ops.h
@@ -10,6 +10,17 @@
#define FILE_SCANF(path, fmt, ...) \
file_scanf(__FILE__, __LINE__, (path), (fmt), ## __VA_ARGS__)
+/**
+ * SAFE_FILE_SCANF() - Reads formatted data from a file.
+ *
+ * @path: Path to the file to read.
+ * @fmt: scanf format string.
+ * @...: Pointers to variables to store parsed values into.
+ *
+ * Scans formatted data from path. If opening the file fails or the number of
+ * conversions does not match the format string, exits with
+ * :c:enum:`TBROK <tst_res_flags>`.
+ */
#define SAFE_FILE_SCANF(path, fmt, ...) \
safe_file_scanf(__FILE__, __LINE__, NULL, \
(path), (fmt), ## __VA_ARGS__)
@@ -39,6 +50,17 @@ void safe_file_read_str(const char *file, const int lineno,
file_lines_scanf(__FILE__, __LINE__, NULL, 0,\
(path), (fmt), ## __VA_ARGS__)
+/**
+ * SAFE_FILE_LINES_SCANF() - Searches lines of a file for formatted data.
+ *
+ * @path: Path to the file to read.
+ * @fmt: scanf format string to match against each line.
+ * @...: Pointers to variables to store parsed values into.
+ *
+ * Reads lines from path one by one until a line matches all format
+ * conversions in fmt. If the file cannot be opened or no line matches,
+ * exits with :c:enum:`TBROK <tst_res_flags>`.
+ */
#define SAFE_FILE_LINES_SCANF(path, fmt, ...) \
file_lines_scanf(__FILE__, __LINE__, NULL, 1,\
(path), (fmt), ## __VA_ARGS__)
@@ -61,6 +83,16 @@ void safe_file_read_str(const char *file, const int lineno,
file_printf(__FILE__, __LINE__, \
(path), (fmt), ## __VA_ARGS__)
+/**
+ * SAFE_FILE_PRINTF() - Writes formatted data to a file.
+ *
+ * @path: Path to the file to write.
+ * @fmt: printf format string.
+ * @...: Arguments for the format string.
+ *
+ * Writes formatted output to path. Exits with :c:enum:`TBROK <tst_res_flags>`
+ * if the file cannot be opened or written.
+ */
#define SAFE_FILE_PRINTF(path, fmt, ...) \
safe_file_printf(__FILE__, __LINE__, NULL, \
(path), (fmt), ## __VA_ARGS__)
@@ -84,9 +116,29 @@ void safe_file_read_str(const char *file, const int lineno,
safe_try_file_printf(__FILE__, __LINE__, NULL, \
(path), (fmt), ## __VA_ARGS__)
+/**
+ * SAFE_CP() - Copies a file from source to destination.
+ *
+ * @src: Source file path.
+ * @dst: Destination file path.
+ *
+ * Copies the file from src to dst. Exits with :c:enum:`TBROK <tst_res_flags>`
+ * on failure.
+ */
#define SAFE_CP(src, dst) \
safe_cp(__FILE__, __LINE__, NULL, (src), (dst))
+/**
+ * SAFE_TOUCH() - Creates or updates timestamp on a file.
+ *
+ * @pathname: Path to the file.
+ * @mode: File permissions mode (0 to use default 0666 & ~umask).
+ * @times: Array of two struct timespec for atime and mtime (NULL for current time).
+ *
+ * Creates the file if it does not exist with the specified mode, or updates
+ * its access and modification times. Exits with :c:enum:`TBROK <tst_res_flags>`
+ * on failure.
+ */
#define SAFE_TOUCH(pathname, mode, times) \
safe_touch(__FILE__, __LINE__, NULL, \
(pathname), (mode), (times))
@@ -97,6 +149,13 @@ void safe_file_read_str(const char *file, const int lineno,
void tst_create_overlay_dirs(void);
int tst_mount_overlay(const char *file, const int lineno, int strict);
+/**
+ * SAFE_MOUNT_OVERLAY() - Mounts overlayfs at OVL_MNT mount point.
+ *
+ * Creates lower, upper, work, and mnt directories, then mounts overlayfs
+ * at OVL_MNT. Exits with :c:enum:`TCONF <tst_res_flags>` if overlayfs is not
+ * supported by kernel, or :c:enum:`TBROK <tst_res_flags>` on mount failure.
+ */
#define SAFE_MOUNT_OVERLAY() \
((void) tst_mount_overlay(__FILE__, __LINE__, 1))
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* [LTP] [PATCH v2 8/9] doc: Document CPU and common test helpers
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (6 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 7/9] include: Document safe file operations Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 11:56 ` Petr Vorel
2026-09-11 7:04 ` [LTP] [PATCH v2 9/9] include: Fix API comment spelling and style Andrea Cervesato
` (2 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Fix the kernel-doc formatting in include/tst_common.h and include
both tst_common.h and tst_cpu.h in the C API reference documentation.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
doc/developers/api_c_tests.rst | 5 +++++
include/tst_common.h | 18 ++++++++++--------
2 files changed, 15 insertions(+), 8 deletions(-)
diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
index d4d06df0a..af7d84ce1 100644
--- a/doc/developers/api_c_tests.rst
+++ b/doc/developers/api_c_tests.rst
@@ -29,9 +29,14 @@ Commands
Core LTP API
------------
+.. kernel-doc:: ../../include/tst_common.h
.. kernel-doc:: ../../include/tst_res_flags.h
.. kernel-doc:: ../../include/tst_test.h
+CPU
+---
+.. kernel-doc:: ../../include/tst_cpu.h
+
Crypto
------
.. kernel-doc:: ../../include/tst_crypto.h
diff --git a/include/tst_common.h b/include/tst_common.h
index d09edbbbe..b7a0e6734 100644
--- a/include/tst_common.h
+++ b/include/tst_common.h
@@ -30,15 +30,17 @@ unsigned int tst_multiply_timeout(unsigned int timeout);
/**
* TST_RETRY_FUNC() - Repeatedly retry a function with an increasing delay.
- * @FUNC - The function which will be retried
- * @ECHCK - Function/macro for validating @FUNC return value
*
- * This macro will call @FUNC in a loop with a delay between retries.
- * If ECHCK(ret) evaluates to non-zero, the loop ends. The delay between
- * retries starts at one microsecond and is then doubled each iteration until
- * it exceeds one second (the total time sleeping will be approximately one
- * second as well). When the delay exceeds one second, the loop will end.
- * The TST_RETRY_FUNC() macro returns the last value returned by @FUNC.
+ * @FUNC: The function which will be retried.
+ * @ECHCK: Function or macro for validating @FUNC return value.
+ *
+ * This macro will call @FUNC in a loop with an exponential delay between
+ * retries. If ECHCK(ret) evaluates to non-zero, the loop ends. The delay
+ * starts at one microsecond and doubles each iteration until it exceeds
+ * one second (scaled by tst_multiply_timeout()). When the maximum delay
+ * is exceeded, the loop ends.
+ *
+ * Return: The last value returned by @FUNC.
*/
#define TST_RETRY_FUNC(FUNC, ECHCK) \
TST_RETRY_FN_EXP_BACKOFF(FUNC, ECHCK, 1)
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 8/9] doc: Document CPU and common test helpers
2026-09-11 7:04 ` [LTP] [PATCH v2 8/9] doc: Document CPU and common test helpers Andrea Cervesato
@ 2026-09-11 11:56 ` Petr Vorel
0 siblings, 0 replies; 18+ messages in thread
From: Petr Vorel @ 2026-09-11 11:56 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Andrea,
...
> +++ b/include/tst_common.h
> /**
> * TST_RETRY_FUNC() - Repeatedly retry a function with an increasing delay.
> - * @FUNC - The function which will be retried
> - * @ECHCK - Function/macro for validating @FUNC return value
> *
> - * This macro will call @FUNC in a loop with a delay between retries.
> - * If ECHCK(ret) evaluates to non-zero, the loop ends. The delay between
> - * retries starts at one microsecond and is then doubled each iteration until
> - * it exceeds one second (the total time sleeping will be approximately one
> - * second as well). When the delay exceeds one second, the loop will end.
> - * The TST_RETRY_FUNC() macro returns the last value returned by @FUNC.
> + * @FUNC: The function which will be retried.
> + * @ECHCK: Function or macro for validating @FUNC return value.
> + *
> + * This macro will call @FUNC in a loop with an exponential delay between
Interesting @FUNC seems to do the same formatting as ``FUNC`` (@ is maybe less
obvious formatting, but shorter than ``...``).
> + * retries. If ECHCK(ret) evaluates to non-zero, the loop ends. The delay
But it works only on a first item, i.e ECHCK(ret) would have to be formatted
with the usual ``ECHCK(ret)`` (maybe worth to change before merge).
Reviewed-by: Petr Vorel <pvorel@suse.cz>
Kind regards,
Petr
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 18+ messages in thread
* [LTP] [PATCH v2 9/9] include: Fix API comment spelling and style
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (7 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 8/9] doc: Document CPU and common test helpers Andrea Cervesato
@ 2026-09-11 7:04 ` Andrea Cervesato
2026-09-11 12:21 ` Petr Vorel
2026-09-11 12:34 ` [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato via ltp
2026-09-11 13:06 ` Andrea Cervesato via ltp
10 siblings, 1 reply; 18+ messages in thread
From: Andrea Cervesato @ 2026-09-11 7:04 UTC (permalink / raw)
To: Linux Test Project
From: Andrea Cervesato <andrea.cervesato@suse.com>
Correct typos in test macros, test harness headers, checkpoints,
buffers, NUMA, and ujson headers. Normalize Return: tags for consistency
with kernel-doc conventions.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
Reviewed-by: Petr Vorel <pvorel@suse.cz>
---
include/tse_numa.h | 8 ++++----
include/tst_buffers.h | 10 +++++-----
include/tst_checkpoint.h | 6 +++---
include/tst_test.h | 20 ++++++++++----------
include/tst_test_macros.h | 34 +++++++++++++++++-----------------
include/ujson_common.h | 2 +-
include/ujson_reader.h | 8 ++++----
include/ujson_utf.h | 2 +-
include/ujson_writer.h | 2 +-
9 files changed, 46 insertions(+), 46 deletions(-)
diff --git a/include/tse_numa.h b/include/tse_numa.h
index 4cbef63b7..add048eb4 100644
--- a/include/tse_numa.h
+++ b/include/tse_numa.h
@@ -39,7 +39,7 @@ void tse_nodemap_print_counters(struct tse_nodemap *nodes);
*
* @mode: Numa mempolicy mode.
*
- * return: a name for a mempolicy/mbind mode.
+ * Return: a name for a mempolicy/mbind mode.
*/
const char *tse_mempolicy_mode_name(int mode);
@@ -49,7 +49,7 @@ const char *tse_mempolicy_mode_name(int mode);
* @path: Path to a file, if not NULL mapping is file based.
* @size: Mapping size.
*
- * return: a pointer to a mapped file.
+ * Return: a pointer to a mapped file.
*/
void *tse_numa_map(const char *path, size_t size);
@@ -76,7 +76,7 @@ static inline void tse_numa_unmap(void *ptr, size_t size)
}
/**
- * tse_nodemap_count_pages() - Check which numa node resides each page.
+ * tse_nodemap_count_pages() - Check on which NUMA node each page resides.
*
* Check on which numa node resides each page of the mapping starting at ptr
* and continuing pages long and increases nodemap counters accordingly.
@@ -114,7 +114,7 @@ enum tse_numa_types {
* requested amount of free+buffers memory it's not included in
* the resulting list of nodes.
*
- * return: On success returns allocated and initialized struct tse_nodemap which contains
+ * Return: On success returns allocated and initialized struct tse_nodemap which contains
* array of numa node ids that contains desired resources.
*/
struct tse_nodemap *tse_get_nodemap(int type, size_t min_mem_kb);
diff --git a/include/tst_buffers.h b/include/tst_buffers.h
index bd1a112a2..c354e2eca 100644
--- a/include/tst_buffers.h
+++ b/include/tst_buffers.h
@@ -22,7 +22,7 @@
/**
* struct tst_buffers - A guarded buffer description for allocator.
*
- * Buffer description consist of a pointer to a pointer and buffer type/size
+ * Buffer description consists of a pointer to a pointer and buffer type/size
* encoded as a different structure members.
*
* @ptr: A pointer to the pointer to buffer. This is dereferenced and set by the
@@ -53,7 +53,7 @@ void tst_buffers_alloc(struct tst_buffers bufs[]);
* tst_strdup() - Copies a string into a newly allocated guarded buffer.
*
* @str: A string to be duplicated.
- * return: A pointer to the string duplicated in a guarded buffer.
+ * Return: A pointer to the string duplicated in a guarded buffer.
*
* Allocates a buffer with tst_alloc() and copies the string into it.
*/
@@ -63,7 +63,7 @@ char *tst_strdup(const char *str);
* tst_alloc() - Allocates a guarded buffer.
*
* @size: A size of the buffer.
- * return: A newly allocated guarded buffer.
+ * Return: A newly allocated guarded buffer.
*/
void *tst_alloc(size_t size);
@@ -72,7 +72,7 @@ void *tst_alloc(size_t size);
*
* @fmt: A printf-like format.
* @...: A printf-like parameters.
- * return: A newly allocated buffer.
+ * Return: A newly allocated buffer.
*
* Allocates a buffer with tst_alloc() then prints the data into it.
*/
@@ -83,7 +83,7 @@ char *tst_aprintf(const char *fmt, ...)
* tst_iovec_alloc() - Allocates a complete iovec structure.
*
* @sizes: A -1 terminated array of buffer sizes.
- * return: Newly allocated iovec structure.
+ * Return: Newly allocated iovec structure.
*/
struct iovec *tst_iovec_alloc(int sizes[]);
diff --git a/include/tst_checkpoint.h b/include/tst_checkpoint.h
index f202dd03d..d93667b36 100644
--- a/include/tst_checkpoint.h
+++ b/include/tst_checkpoint.h
@@ -6,10 +6,10 @@
/**
* DOC: Checkpoints introduction
*
- * Checkpoints implements a futex based synchronization primitive for threads
+ * Checkpoints implement a futex based synchronization primitive for threads
* and processes. When a process calls wait function its execution is suspended
* until wake is called for a corresponding checkpoint. Checkpoints are
- * numbered from 0 and process can use at least hundred of them.
+ * numbered from 0 and process can use at least a hundred of them.
*
* In order to use checkpoints the test must set the tst_test.needs_checkpoints
* flag.
@@ -66,7 +66,7 @@
* @nr_wake: A number of processes to wake.
*
* Wakes up nr_wake processes suspended on a checkpoint and retries if there
- * wasn't enough process suspended on the checkpoint yet. The call does not
+ * were not enough processes suspended on the checkpoint yet. The call does not
* retry indefinitely but gives up if it does not wake nr_wake processes after
* 10 seconds. If an error happened or timeout was reached the function calls
* tst_brk(TBROK, ...) which exits the test.
diff --git a/include/tst_test.h b/include/tst_test.h
index 7d03014d4..53f58180f 100644
--- a/include/tst_test.h
+++ b/include/tst_test.h
@@ -160,7 +160,7 @@ pid_t safe_fork(const char *filename, unsigned int lineno);
* tst_strerrno() - Converts an errno number into a name.
*
* @err: An errno number.
- * return: An errno name e.g. "EINVAL".
+ * Return: An errno name e.g. "EINVAL".
*/
const char *tst_strerrno(int err);
@@ -168,7 +168,7 @@ const char *tst_strerrno(int err);
* tst_strsig() - Converts a signal number into a name.
*
* @sig: A signal number.
- * return: A signal name e.g. "SIGINT".
+ * Return: A signal name e.g. "SIGINT".
*/
const char *tst_strsig(int sig);
@@ -181,7 +181,7 @@ const char *tst_strsig(int sig);
* Not thread safe.
*
* @status: A status as returned by wait()
- * return: A string description for the status e.g. "killed by SIGKILL".
+ * Return: A string description for the status e.g. "killed by SIGKILL".
*/
const char *tst_strstatus(int status);
@@ -436,8 +436,8 @@ struct tst_fs {
*
* @filesystems: A NULL type terminated array of per file system type
* parameters for mkfs and mount. If the first entry type is NULL
- * it describes a default parameters for all file system tests.
- * The rest of the entries the describes per file system type
+ * it describes default parameters for all file system tests.
+ * The remaining entries describe per file system type
* parameters. If tst_test.all_filesystems is set, the test runs
* for all filesystems and uses the array to lookup the mkfs
* and mount options. If tst_test.all_filesystems is not set
@@ -546,7 +546,7 @@ struct tst_fs {
* @needs_cgroup_ctrls: A {} terminated array of cgroup controllers the test
* needs to run.
*
- * @needs_cgroup_nsdelegate: If set test the will run only if cgroup2 is mounted
+ * @needs_cgroup_nsdelegate: If set the test will run only if cgroup2 is mounted
* with nsdelegate option.
*/
@@ -663,7 +663,7 @@ void tst_run_tcases(int argc, char *argv[], struct tst_test *self)
/**
* tst_reinit() - Reinitialize the test library.
*
- * In a cases where a test child process calls exec() it no longer can access
+ * In cases where a test child process calls exec() it no longer can access
* the test library shared memory and therefore use the test reporting
* functions, checkpoint library, etc. This function re-initializes the test
* library so that it can be used again.
@@ -701,7 +701,7 @@ void tst_reinit(void);
* of the script yourself. If you do not need to check the return value
* yourself you can use tst_reap_children() to wait for the completion. Or let
* the test library collect the child automatically, just be wary that the
- * script and the test both runs concurently at the same time in this case.
+ * script and the test both run concurrently at the same time in this case.
*
* Return: A pid of the (shell) script process.
*/
@@ -794,7 +794,7 @@ int tst_creat_unlinked(const char *path, int flags, mode_t mode);
/**
* tst_get_tmpdir_root() - Returns path to the test temporary directory root.
*
- * The path is either hardcoded as /tmp or could be overrided by a TMPDIR
+ * The path is either hardcoded as /tmp or could be overridden by a TMPDIR
* environment variable.
*
* Return: A path to the test temporary directory root.
@@ -840,7 +840,7 @@ int main(int argc, char *argv[])
*
* @message: Error message (the reason to skip test).
*
- * This macro is used in test that couldn't be compiled either because current
+ * This macro is used in tests that couldn't be compiled either because current
* CPU architecture is unsupported or because of missing development libraries.
*/
#define TST_TEST_TCONF(message) \
diff --git a/include/tst_test_macros.h b/include/tst_test_macros.h
index 9a93331d5..fcecf7f82 100644
--- a/include/tst_test_macros.h
+++ b/include/tst_test_macros.h
@@ -115,7 +115,7 @@ extern int TST_PASS;
* @SCALL: Tested syscall.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TEST() macro and additionaly prints pass
+ * This macro calls the SCALL with a TEST() macro and additionally prints pass
* or fail message. Apart from TST_ERR and TST_RET set by the TEST() macro
* TST_PASS global variable is set as well based on the outcome.
*
@@ -258,8 +258,8 @@ extern int TST_PASS;
* @VAL: Expected return value.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TEST() macro and additionaly prints pass
- * or fail message after comparing the returned value againts the expected
+ * This macro calls the SCALL with a TEST() macro and additionally prints pass
+ * or fail message after comparing the returned value against the expected
* value. Apart from TST_ERR and TST_RET set by the TEST() macro TST_PASS
* global variable is set as well based on the outcome.
*
@@ -337,8 +337,8 @@ extern int TST_PASS;
* @SCALL: Tested syscall.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TEST() macro and additionaly prints pass
- * or fail message after checking the return value againts zero. Apart from
+ * This macro calls the SCALL with a TEST() macro and additionally prints pass
+ * or fail message after checking the return value against zero. Apart from
* TST_ERR and TST_RET set by the TEST() macro TST_PASS global variable is set
* as well based on the outcome.
*
@@ -395,7 +395,7 @@ extern int TST_PASS;
* @SCALL: Tested syscall.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TESTPTR() macro and additionaly prints
+ * This macro calls the SCALL with a TESTPTR() macro and additionally prints
* pass or fail message after checking the return value against (void \*)-1.
* Apart from TST_ERR and TST_RET_PTR set by the TESTPTR() macro TST_PASS
* global variable is set as well based on the outcome.
@@ -509,7 +509,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
* @EXP_ERR: Expected errno.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TEST() macro and additionaly prints pass
+ * This macro calls the SCALL with a TEST() macro and additionally prints pass
* or fail message. The check passes if syscall has returned -1 and failed with
* the specified errno.
*
@@ -538,7 +538,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* This is a variant of TST_EXP_FAIL() with an array of possible errors.
@@ -560,7 +560,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* This is a variant of TST_EXP_FAIL2() with an array of possible errors.
@@ -576,7 +576,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
* @EXP_ERR: Expected errno.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TESTPTR() macro and additionaly prints
+ * This macro calls the SCALL with a TESTPTR() macro and additionally prints
* pass or fail message after checking the return value against NULL and errno.
*
* Apart from TST_ERR and TST_RET_PTR set by the TESTPTR() macro TST_PASS
@@ -598,7 +598,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* This is a variant of TST_EXP_FAIL_PTR_NULL() with an array of possible
@@ -617,7 +617,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
* @EXP_ERR: Expected errno.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TESTPTR() macro and additionaly prints
+ * This macro calls the SCALL with a TESTPTR() macro and additionally prints
* pass or fail message after checking the return value against (void \*)-1 and
* errno.
*
@@ -640,7 +640,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* This is a variant of TST_EXP_FAIL_PTR_VOID() with an array of possible
@@ -657,11 +657,11 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
* @EXP_ERR: Expected errno.
* @...: A printf-like parameters.
*
- * This macro calls the SCALL with a TEST() macro and additionaly prints pass
+ * This macro calls the SCALL with a TEST() macro and additionally prints pass
* or fail message. The check passes if syscall has returned -1 and failed with
* the specified errno.
*
- * The SCALL is supposed to return possitive number on success e.g. pid or file
+ * The SCALL is supposed to return positive number on success e.g. pid or file
* descriptor. For syscalls that return zero on success TST_EXP_FAIL() has to
* be used instead.
*
@@ -718,7 +718,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* Unlike TST_EXP_FAIL_ARR() does not print :c:enum:`TPASS <tst_res_flags>` on
@@ -733,7 +733,7 @@ const char *tst_errno_names(char *buf, const int *exp_errs, int exp_errs_cnt);
*
* @SCALL: Tested syscall.
* @EXP_ERRS: Array of expected errnos.
- * @EXP_ERRS_CNT: Lenght of EXP_ERRS.
+ * @EXP_ERRS_CNT: Length of EXP_ERRS.
* @...: A printf-like parameters.
*
* Unlike TST_EXP_FAIL2_ARR() does not print :c:enum:`TPASS <tst_res_flags>` on
diff --git a/include/ujson_common.h b/include/ujson_common.h
index 11382c4fb..1eaf3fc72 100644
--- a/include/ujson_common.h
+++ b/include/ujson_common.h
@@ -13,7 +13,7 @@
/** @brief Maximal error message length. */
#define UJSON_ERR_MAX 128
-/** @brief Maximal id string lenght including terminating null element. */
+/** @brief Maximal id string length including terminating null element. */
#define UJSON_ID_MAX 64
/** @brief Maximal recursion depth allowed. */
#define UJSON_RECURSION_MAX 128
diff --git a/include/ujson_reader.h b/include/ujson_reader.h
index 8608b6c81..3722fffea 100644
--- a/include/ujson_reader.h
+++ b/include/ujson_reader.h
@@ -24,7 +24,7 @@
* @brief An ujson_reader initializer with default values.
*
* @param buf A pointer to a buffer with JSON data.
- * @param buf_len A JSON data buffer lenght.
+ * @param buf_len A JSON data buffer length.
* @param rflags enum ujson_reader_flags.
*
* @return An ujson_reader initialized with default values.
@@ -96,7 +96,7 @@ struct ujson_val {
*/
enum ujson_type type;
- /** An user supplied buffer and size to store a string values to. */
+ /** A user supplied buffer and size to store a string values to. */
char *buf;
size_t buf_size;
@@ -108,7 +108,7 @@ struct ujson_val {
*/
size_t idx;
- /** An union to store the parsed value into. */
+ /** A union to store the parsed value into. */
union {
/** @brief A boolean value. */
int val_bool;
@@ -311,7 +311,7 @@ static inline size_t ujson_obj_lookup(const ujson_obj *obj, const char *key)
#define UJSON_OBJ_ATTR(keyv, typev) \
{.key = keyv, .type = typev}
-/** @brief An ujson_obj_attr intializer with an array index. */
+/** @brief An ujson_obj_attr initializer with an array index. */
#define UJSON_OBJ_ATTR_IDX(key_idx, keyv, typev) \
[key_idx] = {.key = keyv, .type = typev}
diff --git a/include/ujson_utf.h b/include/ujson_utf.h
index 313213d8e..83fe8ab09 100644
--- a/include/ujson_utf.h
+++ b/include/ujson_utf.h
@@ -130,7 +130,7 @@ static inline unsigned int ujson_utf8_bytes(uint32_t unicode)
}
/**
- * @brief Writes an unicode character into a UTF-8 buffer.
+ * @brief Writes a Unicode character into a UTF-8 buffer.
*
* The buffer _must_ be large enough!
*
diff --git a/include/ujson_writer.h b/include/ujson_writer.h
index dfcc95053..30d2e92f6 100644
--- a/include/ujson_writer.h
+++ b/include/ujson_writer.h
@@ -46,7 +46,7 @@ struct ujson_writer {
* @brief An ujson_writer initializer with default values.
*
* @param vout A pointer to function to write out the data.
- * @param vout_priv An user pointer passed to the out function.
+ * @param vout_priv A user pointer passed to the out function.
*
* @return An ujson_writer initialized with default values.
*/
--
2.51.0
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 9/9] include: Fix API comment spelling and style
2026-09-11 7:04 ` [LTP] [PATCH v2 9/9] include: Fix API comment spelling and style Andrea Cervesato
@ 2026-09-11 12:21 ` Petr Vorel
0 siblings, 0 replies; 18+ messages in thread
From: Petr Vorel @ 2026-09-11 12:21 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Andrea,
> /**
> - * tse_nodemap_count_pages() - Check which numa node resides each page.
> + * tse_nodemap_count_pages() - Check on which NUMA node each page resides.
> *
> * Check on which numa node resides each page of the mapping starting at ptr
> * and continuing pages long and increases nodemap counters accordingly.
> @@ -114,7 +114,7 @@ enum tse_numa_types {
> * requested amount of free+buffers memory it's not included in
> * the resulting list of nodes.
> *
> - * return: On success returns allocated and initialized struct tse_nodemap which contains
> + * Return: On success returns allocated and initialized struct tse_nodemap which contains
> * array of numa node ids that contains desired resources.
Although lowercase 'r' on return also works as expected (but it's indeed better
to unify), again: whitespace on the second line breaks formatting (first line is
bold, second line is shifted.
Unfortunately Return: does not work like struct members, which allow shifting
without any formatting (OTOH other formating e.g. lists does not work on them).
The rest hopefully LGTM.
Reviewed-by: Petr Vorel <pvorel@suse.cz>
Thanks for whole patchset.
Kind regards,
Petr
diff --git include/tse_numa.h include/tse_numa.h
index add048eb4c..ac6aab41b8 100644
--- include/tse_numa.h
+++ include/tse_numa.h
@@ -114,8 +114,8 @@ enum tse_numa_types {
* requested amount of free+buffers memory it's not included in
* the resulting list of nodes.
*
- * Return: On success returns allocated and initialized struct tse_nodemap which contains
- * array of numa node ids that contains desired resources.
+ * Return: On success returns allocated and initialized struct tse_nodemap which
+ * contains array of numa node ids that contains desired resources.
*/
struct tse_nodemap *tse_get_nodemap(int type, size_t min_mem_kb);
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (8 preceding siblings ...)
2026-09-11 7:04 ` [LTP] [PATCH v2 9/9] include: Fix API comment spelling and style Andrea Cervesato
@ 2026-09-11 12:34 ` Andrea Cervesato via ltp
2026-09-11 13:06 ` Andrea Cervesato via ltp
10 siblings, 0 replies; 18+ messages in thread
From: Andrea Cervesato via ltp @ 2026-09-11 12:34 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Hi Petr,
thanks for the review. If it's ok, since updating documentation is not
a blocking thing for the release, I would fix the whole patch-set with
the requested fix and merge it.
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments
2026-09-11 7:04 [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato
` (9 preceding siblings ...)
2026-09-11 12:34 ` [LTP] [PATCH v2 0/9] doc: Improve and fix documentation and API comments Andrea Cervesato via ltp
@ 2026-09-11 13:06 ` Andrea Cervesato via ltp
10 siblings, 0 replies; 18+ messages in thread
From: Andrea Cervesato via ltp @ 2026-09-11 13:06 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: Linux Test Project
Merged, Thanks!
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 18+ messages in thread