[LTP] [PATCH v3] agents: Add AI agent configuration for code reviews
Andrea Cervesato
andrea.cervesato@suse.de
Tue Feb 17 09:26:54 CET 2026
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add agents/ directory with configuration files for automated code review
assistance. The configuration includes:
- ground-rules.md: Mandatory LTP development rules
- c-tests.md: C test writing guidelines and examples
- shell-tests.md: Shell test structure and style guide
- review.md: Review protocol for AI agents
AGENTS.md at root provides project overview and links to review protocol.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
Changes in v3:
- review and fix the agents review configuration
- Link to v2: https://lore.kernel.org/r/20260216-agents_file-v2-1-b6afff4195f2@suse.com
Changes in v2:
- rewrite the entire agents/ structure to reduce the LLM allucination
and to focus on reviews only
- AGENTS.md now is defining basic project usage and it points to the
agents/review.md for review requests
- Link to v1: https://lore.kernel.org/r/20260216-agents_file-v1-1-53ec6a8ecf32@suse.com
---
AGENTS.md | 104 ++++++++++++++++++++++++++++++++++++++++++
agents/c-tests.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++
agents/ground-rules.md | 69 ++++++++++++++++++++++++++++
agents/review.md | 50 ++++++++++++++++++++
agents/shell-tests.md | 95 ++++++++++++++++++++++++++++++++++++++
5 files changed, 439 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..7698ca2bb5288d720d39d4d5de71bed8fbfc647a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,104 @@
+# Linux Test Project (LTP)
+
+LTP delivers tests to the open source community that validate the
+reliability, robustness, and stability of the Linux kernel and related
+features. Tests are written in C or portable POSIX shell. The project uses
+GNU Autotools for its build system and follows the Linux kernel coding style.
+
+**License**: GPL-2.0-or-later (`SPDX-License-Identifier: GPL-2.0-or-later`)
+
+## Technology Stack
+
+- **Languages**: C (primary), portable POSIX shell
+- **Build system**: GNU Autotools (autoconf, automake, make)
+- **Compiler**: gcc (clang also supported in CI)
+- **Coding style**: Linux kernel coding style
+- **Test runner**: kirk (replacing legacy `runltp`)
+- **Documentation**: reStructuredText + Sphinx
+
+## Project Structure
+
+- `testcases/` - All test binaries (C and shell)
+ - `testcases/kernel/syscalls/` - Syscall and libc wrapper tests
+ - `testcases/open_posix_testsuite/` - Open POSIX testsuite fork
+ - `testcases/lib/` - Shell test library and shell loader
+- `include/` - LTP library headers (`tst_test.h` is the main API)
+ - `include/lapi/` - Fallback kernel API definitions for older systems
+ - `include/mk/` - Build system include files
+- `lib/` - LTP C library source (`tst_*.c` files)
+ - `lib/newlib_tests/` - LTP library self-tests
+- `runtest/` - Runtest files defining test suites (e.g. `syscalls`, `mm`)
+- `scenario_groups/` - Default sets of runtest files
+- `doc/` - Sphinx documentation (RST format)
+- `infrastructure/` - Terraform configs (if present)
+- `scripts/` - Helper scripts
+- `ci/` - CI dependency installation scripts
+- `.github/workflows/` - GitHub Actions CI workflows
+- `tools/` - Release and maintenance tools
+- `agents/` - AI Agents configurations
+
+## Environment Setup
+
+### Prerequisites
+
+- git
+- autoconf, automake, m4
+- make
+- gcc
+- pkgconf / pkg-config
+- libc headers
+- linux headers
+
+### Download Source
+
+```sh
+git clone --recurse-submodules https://github.com/linux-test-project/ltp.git
+cd ltp
+```
+
+### Build from Source
+
+```sh
+make autotools
+./configure
+make
+```
+
+### Install (default prefix: /opt/ltp)
+
+```sh
+make install
+```
+
+### Rebuild from Scratch (required after build system changes)
+
+```sh
+make autotools
+./configure
+make
+```
+
+## FILE LOADING INSTRUCTIONS
+
+### Code review (ALWAYS LOAD WHEN PATCH REVIEW IS REQUESTED)
+
+- `agents/review.md` - Entry point for the review agent
+
+## Additional Resources
+
+- Documentation: https://linux-test-project.readthedocs.io/
+- Source code: https://github.com/linux-test-project/ltp
+- Mailing list: https://lore.kernel.org/ltp/
+- Patchwork: https://patchwork.ozlabs.org/project/ltp/list/
+- Kirk (test runner): https://github.com/linux-test-project/kirk
+- Linux kernel coding style: https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+### Documentation
+
+- For full development documentation, see `doc/developers`.
+- For full maintenance documentation, see `doc/maintenance`.
+- For full users documentation, see `doc/users`.
+- For detailed API reference, see `doc/developers/api_c_tests.rst` and
+ `doc/developers/api_shell_tests.rst`.
+- For build system details, see `doc/developers/build_system.rst`.
+- For test writing tutorial, see `doc/developers/test_case_tutorial.rst`.
diff --git a/agents/c-tests.md b/agents/c-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..dd966ec723d5182eff422339174e01e4dab66983
--- /dev/null
+++ b/agents/c-tests.md
@@ -0,0 +1,121 @@
+# C Tests
+
+## Test Structure
+
+```c
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * Copyright (c) YYYY Your Name <email>
+ */
+
+/*\
+ * High-level RST-formatted test description goes here.
+ * Explain _what_ is being tested (exported to docs).
+ *
+ * The following part is OPTIONAL:
+ * [Algorithm]
+ *
+ * Explaination of how algorithm in the test works in a list (-) syntax.
+ */
+
+#include "tst_test.h"
+
+static void run(void)
+{
+ tst_res(TPASS, "Test passed");
+}
+
+static struct tst_test test = {
+ .test_all = run,
+};
+```
+
+## Mandatory Tests Rules
+
+- Follow Linux kernel coding style
+- Include `tst_test.h` as the main API header
+- `main()` is provided by the test library; do not define it, unless
+ `TST_NO_DEFAULT_MAIN` is used inside the test
+- Use `struct tst_test` to configure test callbacks, requirements, and metadata
+- Use `tst_res()` for reporting (TPASS, TFAIL, TCONF, TBROK, TINFO)
+- Use `tst_brk()` for fatal errors that abort the test
+- Use `SAFE_*` macros for system calls that must not fail
+- Use `TEST()` macro to capture return value in `TST_RET` and errno in `TST_ERR`
+- Keep handlers thin; use `.setup` and `.cleanup` callbacks
+- Cleanup must run on all exit paths (unmount, restore sysctls, delete temp
+ files, kill processes)
+- Do not use the old API (`test.h`); use only the new API (`tst_test.h`)
+- Syscall tests go under `testcases/kernel/syscalls/`
+- Each test must have an entry in the appropriate `runtest/` file
+- New test binaries must be added to the corresponding `.gitignore`
+- Datafiles go in a `datafiles/` subdirectory, installed to
+ `testcases/data/$TCID`
+- Sub-executables use `$TESTNAME_` prefix
+- Use `.needs_tmpdir = 1` and work in the current directory for temp files
+- Use `.min_kver` for kernel version gating; prefer runtime checks over
+ compile-time checks
+- Return `TCONF` when a feature is unavailable (not `TFAIL`)
+- If a test is a regression test it should include `.tags` in the
+ `struct tst_test` definition
+
+## Code Pattern Examples
+
+### ✅ Good Code (New API)
+
+```c
+#include <stdlib.h>
+#include "tst_test.h"
+
+static int fd;
+
+static void setup(void)
+{
+ // SAFE macro aborts test if it fails
+ fd = SAFE_OPEN("test_file", O_RDWR | O_CREAT, 0644);
+}
+
+static void cleanup(void)
+{
+ if (fd > 0)
+ SAFE_CLOSE(fd);
+}
+
+static void run(void)
+{
+ if (write(fd, "a", 1) != 1) {
+ tst_res(TFAIL | TERRNO, "write() failed");
+ return;
+ }
+ tst_res(TPASS, "write() succeeded");
+}
+
+static struct tst_test test = {
+ .test_all = run,
+ .setup = setup,
+ .cleanup = cleanup,
+ .needs_tmpdir = 1,
+ .needs_root = 1,
+};
+
+```
+
+### ❌ Bad Code (Legacy/Unsafe)
+
+```c
+/* WRONG HEADER */
+#include <stdio.h>
+#include "test.h"
+
+int main(void) /* WRONG: NO MAIN ALLOWED */
+{
+ int fd = open("/tmp/file", O_RDWR); /* WRONG: UNSAFE & HARDCODED PATH */
+
+ if (fd < 0) {
+ perror("open"); /* WRONG: USE tst_res OR SAFE_MACRO */
+ exit(1);
+ }
+
+ tst_resm(TPASS, "test passed"); /* WRONG: OLD PRINT FUNCTION */
+ tst_exit();
+}
+```
diff --git a/agents/ground-rules.md b/agents/ground-rules.md
new file mode 100644
index 0000000000000000000000000000000000000000..b6c1e0ba87a2f2be2a3603d1b904e8dcb25e51c9
--- /dev/null
+++ b/agents/ground-rules.md
@@ -0,0 +1,69 @@
+# Ground Rules
+
+These rules are **mandatory** and must never be violated when writing or
+modifying LTP code.
+
+## No kernel bug workarounds
+
+Never work around a known kernel bug in LTP test code. Workarounds mask
+failures for everyone else. If a test fails because a fix was not backported,
+that is the expected (correct) result.
+
+## No sleep-based synchronization
+
+Never use `sleep()` to synchronize between processes. It causes rare flaky
+failures, wastes CI time, and breaks under load. Use instead:
+
+- `waitpid()/SAFE_WAITPID()` — when parent just needs child to finish
+- `TST_CHECKPOINT_WAIT()` / `TST_CHECKPOINT_WAKE()` — when child must reach a
+ code point before parent continues (futex-based, shared memory)
+- `TST_PROCESS_STATE_WAIT()` — when child must be sleeping in a syscall
+ (polls `/proc/$PID/stat`)
+- Exponential-backoff polling loop — for async or deferred kernel actions
+
+## Runtime feature detection only
+
+Compile-time checks (`configure.ac`) may only enable fallback API definitions
+in `include/lapi/`. Never assume compile-time results reflect the running
+kernel. At runtime use: errno checks (`ENOSYS` / `EINVAL`), `.min_kver`,
+`.needs_kconfigs`, or kernel `.config` parsing.
+
+## Minimize root usage
+
+Do not require root unless the test truly needs it. If root is needed,
+document _why_ in the test's doc comment. Drop privileges for sections that
+do not need them.
+
+## Always clean up
+
+Every test must leave the system exactly as it found it, even on failure or
+early exit. Unmount filesystems, restore sysctls and `/proc`/`/sys` values,
+delete temp files/dirs, kill spawned processes, remove cgroups/namespaces,
+detach loop devices, restore ulimits. Prefer library helpers:
+`.needs_tmpdir`, `.save_restore`, `.needs_device`, `.restore_wallclock`,
+`.needs_cgroup_ctrls`.
+
+## Write portable code
+
+- No nonstandard libc APIs when a portable equivalent exists
+- No assumptions about 64-bit, page size, endianness, or tool versions
+- Architecture-specific tests must still compile everywhere; gate with
+ `.supported_archs`
+- Shell tests must be portable POSIX shell (no bash-isms); verify with
+ `make check`
+
+## One logical change per patch
+
+Split work into small, well-defined patches. Each patch must:
+
+- compile successfully on its own
+- keep all tests and tooling functional
+- not introduce intermediate breakage
+- have a clear commit message explaining the change
+ Patches mixing unrelated changes will be delayed or ignored.
+
+## Unreleased kernel features
+
+Tests for features not yet in a mainline kernel release use the `[STAGING]`
+subject prefix and go into `runtest/staging` only. They will not be merged
+into default test suites until the kernel code is finalized and released.
diff --git a/agents/review.md b/agents/review.md
new file mode 100644
index 0000000000000000000000000000000000000000..143aef5056023a9dd9314cdb56b60d62170c6ec5
--- /dev/null
+++ b/agents/review.md
@@ -0,0 +1,50 @@
+# LTP Patch Review Protocol
+
+You are an agent that performs a deep regression analysis on patches for the
+LTP - Linux Test Project.
+
+The review must be requested for one of the following:
+
+- Git commit
+- Git branch
+- Multiple git commits
+- URL to patchwork
+- URL to lore
+- Local patches file
+
+## Core Files (ALWAYS LOAD FIRST)
+
+1. `ground-rules.md` - Consolidate the rules for LTP tests
+
+## Review Git Commit
+
+- Commits must include `Signed-off-by:` tag
+- Commit messages must be clear, following kernel commit style
+- Use `[STAGING]` subject prefix for tests targeting unreleased kernel features
+- `Fixes: hash` if it fixes particular LTP commit
+- `Fixes: #N` if it fixes github issue number N, so it's automatically closed
+
+## Review C Tests
+
+- Always load `c-tests.md` before starting the review and make sure that tests
+ follow all the rules
+- Compare syscall usage with man pages and kernel code
+
+### C Tests Contribution Checklist (ALL MUST PASS)
+
+- Patches apply cleanly over latest git
+- Test compiles and runs fine (check with `-i 10` and `-i 0` too)
+- Runtest entries are in place
+- New test binaries are added to corresponding `.gitignore` files
+- Run `make check` or `make check-$TCID` in the test directory (uses vendored
+ `checkpatch.pl` from kernel tree)
+
+## Review Shell Tests
+
+Always load `shell-tests.md` before starting the review.
+
+### Shell Tests Contribution Checklist (ALL MUST PASS)
+
+- Patches apply cleanly over latest git
+- Make sure that shell tests rules are applied
+- `make check` emits no warnings for your test
diff --git a/agents/shell-tests.md b/agents/shell-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..0a93b54bddec9531e9a17291b5b8c2a9e525a540
--- /dev/null
+++ b/agents/shell-tests.md
@@ -0,0 +1,95 @@
+# Shell Test API
+
+## Mandatory file structure
+
+Every shell test must follow this exact layout, in order. Omitting or
+reordering these blocks will break the shell loader.
+
+```sh
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) YYYY Author Name <email@example.org>
+# ---
+# doc
+# Brief RST description of what the test verifies.
+#
+# Additional detail if needed (exported to generated docs).
+# ---
+# ---
+# env
+# {
+# "needs_root": true,
+# "needs_tmpdir": true
+# }
+# ---
+
+TST_SETUP=setup
+TST_CLEANUP=cleanup
+
+. tst_loader.sh
+
+setup()
+{
+ tst_res TINFO "setup executed"
+}
+
+cleanup()
+{
+ tst_res TINFO "cleanup executed"
+}
+
+tst_test()
+{
+ tst_res TPASS "Test passed"
+}
+
+. tst_run.sh
+```
+
+## Block-by-block rules
+
+1. **Shebang + license + copyright** — always `#!/bin/sh`, always
+ `GPL-2.0-or-later`.
+2. **`# --- doc`** block — RST-formatted comment describing _what_ is tested.
+ Parsed and exported to the online test catalog. Must be present.
+3. **`# --- env`** block — JSON serialization of `struct tst_test` fields.
+ Must be present even when empty (`{}`). Keys map nearly 1:1 to the C
+ struct (e.g. `"needs_root": true`, `"needs_tmpdir": true`,
+ `"needs_kconfigs": ["CONFIG_NUMA=y"]`, `"tags": {["linux-git", "<hash>"]}`).
+4. **`TST_SETUP` / `TST_CLEANUP` variables** — set _before_ sourcing
+ `tst_loader.sh`. Optional. Setup runs once before tests; cleanup runs
+ once after tests or on `tst_brk` interruption.
+5. **`. tst_loader.sh`** — sources the shell loader, which internally
+ launches `tst_run_shell.c` to parse the env block and initialize the C
+ test library. Must come after variable assignments and before function
+ definitions.
+6. **`setup()` / `cleanup()` functions** — defined after the loader is
+ sourced. Names must match the variables set above.
+7. **`tst_test()` function** — the actual test logic. Report results with
+ `tst_res` and `tst_brk`. Results are stored in shared memory so child
+ processes do not need to propagate them.
+8. **`. tst_run.sh`** — must be the very last line. Triggers test execution.
+
+## Shell coding style
+
+- **Portable POSIX shell only** — no bash-isms (no `[[ ]]`, no arrays,
+ no `function` keyword, no process substitution)
+- Allowed exceptions: `local` keyword inside functions, `-o` and `-a` test
+ operators
+- Code must support also `dash`
+- Keep lines under 80 characters
+- Use tabs for indentation
+- Quote all variable expansions
+- Avoid unnecessary subshells
+- Do not name functions after common shell commands
+
+## Running shell tests from the source tree
+
+```sh
+# From the test's directory (depth may vary)
+PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh
+```
+
+The `../../lib/` path must point to `testcases/lib/` where `tst_loader.sh`,
+`tst_run.sh`, and the compiled `tst_run_shell` binary reside. Adjust the
+number of `../` segments to match the test's depth relative to `testcases/`.
---
base-commit: c6e1d87b8a57b2387d0248a06fbb6a468b132849
change-id: 20260215-agents_file-344bdc3300d0
Best regards,
--
Andrea Cervesato <andrea.cervesato@suse.com>
More information about the ltp
mailing list