Complete the documentation adding missing headers
PATCH v3 2/3 doc: Complete struct tst_test table and shell API docs
In reply to Andrea CervesatoFrom: 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
@@ -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
@@ -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
v3 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 v3:
- PATCH 3: add the missing blank line between tst_mount_has_opt() and
the tst_is_mounted() kernel-doc block in tst_device.h
- PATCH 3: restore the "Requires <string.h>" note (for strlen()) in the TST_KCONFIG_INIT() kernel-doc comment in tst_kconfig.h
- Link to v2: https://lore.kernel.org/r/[email protected]
Changes in v2:
- PATCH 1: drop the incorrect claim about fixing the tse_numa.h
kernel-doc reference (it was already correct) and correct the header
count from 12 to 10 (tse_numa.h and tse_swap.h were already present)
- PATCH 1: remove leftover Doxygen directives (@param, @return,
@relates, @sa) in tst_fuzzy_sync.h that the new kernel-doc comments
superseded
- PATCH 2: drop the already-applied field-rename claims (.runtime,
.hugepages, dev_* moves) from the commit message and correct the
added-field count from 10 to 8
- PATCH 3: fix the copyright year (2025 -> 2026), remove the duplicate
SAFE_MMAP entry from the core macros section, and correct the macro
count from 217 to 216
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Andrea Cervesato (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 | 166 ++++++++++------ include/tst_fuzzy_sync.h | 231 +++++++++++----------- include/tst_hugepage.h | 35 +++- include/tst_kconfig.h | 78 ++++---- include/tst_taint.h | 32 ++-- 12 files changed, 952 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
PATCH v3 3/3 doc: Add SAFE_* macros reference page
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
@@ -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
@@ -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
PATCH v3 1/3 doc: Add missing API references to api_c_tests.rst
In reply to Andrea CervesatoFrom: 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 | 166 ++++++++++++++++++----------- include/tst_fuzzy_sync.h | 231 ++++++++++++++++++++--------------------- include/tst_hugepage.h | 35 +++++-- include/tst_kconfig.h | 78 +++++++------- include/tst_taint.h | 32 +++--- 8 files changed, 377 insertions(+), 289 deletions(-)
doc/developers/api_c_tests.rst +54 -17
@@ -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
@@ -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
@@ -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 +107 -59
230 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
@@ -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 +36 -42
122 lines not on this page · raw message
include/tst_taint.h +12 -20
@@ -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
The whole patch-set is failing the CI. I need to send a new one. Please don't review it.
Regards,
--
Andrea Cervesato
SUSE QE Automation Engineer Linux
[email protected]
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
Re: [LTP] doc: Add missing API references to api_c_tests.rst
In reply to Andrea CervesatoHi,
[PATCH 1/3] doc: Add missing API references to api_c_tests.rst
The commit message accurately describes the changes. The Fixes: tag is correct. The kernel-doc format conversions look good overall, but there is one bug (see below).
include/tst_fuzzy_sync.h static inline void tst_fzsync_pair_wait(int *our_cntr, · line 619
Quoted 8 lines
include/tst_fuzzy_sync.h +4
-0+/** +* tst_fzsync_wait_a() - Wait in thread A. +* @pair: Fuzzy sync pair. +*/ */static inline void tst_fzsync_wait_a (struct tst_fzsync_pair *pair)
BUG: The patch adds a new closing `*/` at line 617 but does not remove
the pre-existing */ at line 618 (the old comment's closing marker). The result in the file is two consecutive */ lines:
614: /**
615: * tst_fzsync_wait_a() - Wait in thread A. 616: * @pair: Fuzzy sync pair. 617: */ 618: */ <-- stray; causes a compilation error
619: static inline void tst_fzsync_wait_a(struct tst_fzsync_pair *pair)
A bare */ at file scope is invalid C and will fail to compile. Please drop line 618.
Verdict: Needs revision ✗
---
[PATCH 2/3] doc: Complete struct tst_test table and shell API docs
The eight new .struct tst_test rows all correspond to real fields in include/tst_test.h. The mnt_flags / min_swap_avail re-ordering is correct (alphabetical order is now min_r < min_s < mnt_f). The shell API variable reference section has been verified against the implementation in testcases/lib/tst_test.sh:
- TST_CHECKPOINT_WAIT/WAKE/WAKE2/WAKE_AND_WAIT signatures are accurate.
- TST_RETRY_FUNC (2 args) and TST_RETRY_FN_EXP_BACKOFF (3 args) match.
- TST_NEEDS_KCONFIGS_IFS default delimiter (comma) is correct.
- TST_DEVICE_SIZE, TST_SKIP_IN_LOCKDOWN, TST_SKIP_IN_SECUREBOOT, TST_TIMEOUT all match the shell library.
- .forks_child / .runs_script as "not applicable" in shell is correct.
- .min_runtime / .needs_abi_bits as \- (no shell equivalent) is correct.
Verdict: Reviewed-by: LTP AI Reviewer <[email protected]> ✓
---
[PATCH 3/3] doc: Add SAFE_* macros reference page
The new api_safe_macros.rst file lists 245 SAFE_* entries, matching the count in the commit message. The SAFE_MMAP signature was verified against tst_safe_macros_inline.h. The toctree placement in doc/index.rst (after api_c_tests, before api_shell_tests) is logical. The For Developers section blurb is accurate.
Verdict: Reviewed-by: LTP AI Reviewer <[email protected]> ✓
---
Series verdict: Needs revision
The only blocking issue is in patch 1/3: the duplicate */ on line 618 of include/tst_fuzzy_sync.h, introduced when converting the tst_fzsync_wait_a() comment to kernel-doc format. This is a compilation error. Patches 2/3 and 3/3 look good.
LTP AI Reviewer
Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp