* [PATCH v5 1/6] agents: add infrastructure for agent resources
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 2/6] agents: add a skill to determine Fixes tags Theodore Ts'o
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Sasha Levin, Bradley Morgan, Theodore Ts'o, linux-doc,
linux-kernel, Jonathan Corbet, Shuah Khan, Randy Dunlap,
Mark Brown, Laurent Pinchart, Greg Kroah-Hartman,
Leon Romanovsky, Konstantin Ryabitsev, Thorsten Leemhuis,
Michael S. Tsirkin, Kees Cook, Geert Uytterhoeven, Dan Carpenter,
Miguel Ojeda, Alexei Starovoitov, Julia Lawall, SJ Park, stable
From: Sasha Levin <sashal@kernel.org>
Add agents/ as a home for skills and other resources for
coding assistants. Describe the skill layout in coding-assistants.rst,
together with the rule that skills only inspect and report, and add a
MAINTAINERS entry covering the directory.
Signed-off-by: Sasha Levin <sashal@kernel.org>
Reviewed-by: Bradley Morgan <brads@mainlining.org>
Link: https://patch.msgid.link/20261020161642.3713052-2-sashal@kernel.org
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 14 ++++++++++++++
MAINTAINERS | 6 ++++++
2 files changed, 20 insertions(+)
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index 509dbf23a099..b8f2c74e46fc 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -19,6 +19,20 @@ For guidelines on content generated by AI coding assistants see:
* Documentation/process/generated-content.rst
+Agent resources
+===============
+
+Skills for coding assistants live under ``agents/skills/``, one directory per
+skill with a ``SKILL.md`` entry point in the `Agent Skills format
+<https://agentskills.io/specification>`_. Each skill points at the process
+documents that apply to its task and adds only what assistants tend to get
+wrong.
+
+Skills inspect and report. They do not change files, create commits or tags,
+or send mail. A skill returns its result with the evidence for it, or says what
+is missing. Do not fill a missing result with a guess or a placeholder, and do
+not finalize the work until it is resolved.
+
Licensing and Legal Requirements
================================
diff --git a/MAINTAINERS b/MAINTAINERS
index 222b7fc2c3aa..eb348cc9588f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -734,6 +734,12 @@ F: Documentation/filesystems/afs.rst
F: fs/afs/
F: include/trace/events/afs.h
+AGENT RESOURCES
+M: Sasha Levin <sashal@kernel.org>
+L: workflows@vger.kernel.org
+S: Maintained
+F: agents/
+
AGPGART DRIVER
M: David Airlie <airlied@redhat.com>
L: dri-devel@lists.freedesktop.org
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v5 2/6] agents: add a skill to determine Fixes tags
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 1/6] agents: add infrastructure for agent resources Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 3/6] agents: add a skill to determine stable tags Theodore Ts'o
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Sasha Levin, Theodore Ts'o, linux-doc, linux-kernel,
Jonathan Corbet, Shuah Khan, Randy Dunlap, Mark Brown,
Laurent Pinchart, Greg Kroah-Hartman, Leon Romanovsky,
Konstantin Ryabitsev, Thorsten Leemhuis, Michael S. Tsirkin,
Kees Cook, Geert Uytterhoeven, Dan Carpenter, Miguel Ojeda,
Alexei Starovoitov, Julia Lawall, SJ Park, Bradley Morgan,
stable
From: Sasha Levin <sashal@kernel.org>
Blame and existing Fixes tags can point to code movement instead of the
change that introduced a bug. Add a skill that sends the agent to the
description of the Fixes: tag in submitting-patches.rst, and adds the
checks agents tend to skip: pinning down the bug before searching,
following the code past moves and refactors, comparing each candidate
with its parent, tagging a later commit that only exposed the bug as
well, handling merges, reverts, backports and bugs older than the Git
history, and taking the commit ID and subject from the commit rather
than typing them.
If the origin cannot be established, the skill returns no tag. Point the
bug-fix procedure in coding-assistants.rst at the skill.
Signed-off-by: Sasha Levin <sashal@kernel.org>
Link: https://patch.msgid.link/20261020161642.3713052-3-sashal@kernel.org
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 8 ++++-
agents/skills/find-fixes/SKILL.md | 39 +++++++++++++++++++++
2 files changed, 46 insertions(+), 1 deletion(-)
create mode 100644 agents/skills/find-fixes/SKILL.md
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index b8f2c74e46fc..ca1cc255606b 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -33,6 +33,11 @@ or send mail. A skill returns its result with the evidence for it, or says what
is missing. Do not fill a missing result with a guess or a placeholder, and do
not finalize the work until it is resolved.
+The following skills are available:
+
+* agents/skills/find-fixes/SKILL.md determines the Fixes tag of a bug fix, or
+ checks an existing one.
+
Licensing and Legal Requirements
================================
@@ -78,7 +83,8 @@ these steps:
another one. The fix must not add build warnings and must pass the
checkpatch.pl checks (see submitting-patches.rst).
6. Commit the working fix with a detailed message describing the problem, the
- solution and a Fixes tag. Do not add a Signed-off-by tag.
+ solution and a Fixes tag determined with the find-fixes skill. Do not
+ add a Signed-off-by tag.
7. Identify the maintainers and lists using scripts/get_maintainer.pl.
Documentation/process/security-bugs.rst shows how to do that.
8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/find-fixes/SKILL.md b/agents/skills/find-fixes/SKILL.md
new file mode 100644
index 000000000000..12b6ea83876d
--- /dev/null
+++ b/agents/skills/find-fixes/SKILL.md
@@ -0,0 +1,39 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: find-fixes
+description: >-
+ Determine the bug-introducing commit and return a verified Fixes tag for
+ a Linux kernel fix. Use when preparing or reviewing bug-fix patches,
+ drafting their commit messages, or checking an existing Fixes tag.
+---
+
+# Determine a Fixes tag
+
+Read the description of the Fixes: tag in
+Documentation/process/submitting-patches.rst. It says which commit to name
+and how to format the tag. Follow the rules for skills in
+Documentation/process/coding-assistants.rst.
+
+- First establish exactly which bug the fix addresses: the failure, how it is
+ triggered and the code involved. Trace only that bug. If the search leads
+ to a different bug or subsystem, go back to the fix.
+- Name a commit from the history of the tree the fix applies to. A stable
+ backport of that commit, or a commit that exists only on another branch, is
+ not a valid tag.
+- Treat blame output, an existing Fixes tag and a bisection result as leads,
+ not answers. Follow the code back through moves, renames, file splits and
+ older implementations to the commit that made it wrong.
+- For each candidate, compare the commit with its parent and explain why the
+ code was correct before and wrong after. Keep apart the commit that added
+ the code, the commit that made it wrong, and a later commit that only made
+ the bug reachable, which gets a tag of its own.
+- Check each parent of a merge, whether the bug was reverted and later
+ reintroduced, and whether a backport differs from its upstream commit.
+- If the bug is already present in the first commit of the Git history, name
+ that commit: Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2"). Confirm that the bug
+ exists there instead of using it as a default. A shallow clone boundary is
+ not an introducing commit; report the limit instead.
+
+Take the commit ID and subject from the commit itself instead of typing them.
+Return the tags with that explanation and the candidates you rejected. If the
+origin cannot be established, return no tag and say what is missing.
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v5 3/6] agents: add a skill to determine stable tags
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 1/6] agents: add infrastructure for agent resources Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 2/6] agents: add a skill to determine Fixes tags Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 4/6] agents: add a skill to find other instances of a fixed bug Theodore Ts'o
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Sasha Levin, Bradley Morgan, Greg Kroah-Hartman,
Theodore Ts'o, linux-doc, linux-kernel, Jonathan Corbet,
Shuah Khan, Randy Dunlap, Mark Brown, Laurent Pinchart,
Leon Romanovsky, Konstantin Ryabitsev, Thorsten Leemhuis,
Michael S. Tsirkin, Kees Cook, Geert Uytterhoeven, Dan Carpenter,
Miguel Ojeda, Alexei Starovoitov, Julia Lawall, SJ Park, stable
From: Sasha Levin <sashal@kernel.org>
Whether a fix needs a stable tag, and which releases it should reach, is
decided by hand and is often missed or left too broad. Add a skill that
sends the agent to stable-kernel-rules.rst for the decision and the tag
format, lists the kinds of changes the stable trees take and leave out
in practice, and adds the checks agents tend to get wrong: finding the
first release that contains each introducing commit, checking that the
fix applies to the oldest affected release, giving every stable tag the
same version, and following the subsystem's stable policy.
If the decision cannot be made, the skill returns no tag. Point the
bug-fix procedure in coding-assistants.rst at the skill.
Signed-off-by: Sasha Levin <sashal@kernel.org>
Reviewed-by: Bradley Morgan <brads@mainlining.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://patch.msgid.link/20261020161642.3713052-4-sashal@kernel.org
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 6 +-
agents/skills/stable-tag/SKILL.md | 72 +++++++++++++++++++++
2 files changed, 76 insertions(+), 2 deletions(-)
create mode 100644 agents/skills/stable-tag/SKILL.md
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index ca1cc255606b..81ee530a8a7f 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -37,6 +37,8 @@ The following skills are available:
* agents/skills/find-fixes/SKILL.md determines the Fixes tag of a bug fix, or
checks an existing one.
+* agents/skills/stable-tag/SKILL.md decides whether a fix goes to stable and
+ returns its stable tag, or checks an existing one.
Licensing and Legal Requirements
================================
@@ -83,8 +85,8 @@ these steps:
another one. The fix must not add build warnings and must pass the
checkpatch.pl checks (see submitting-patches.rst).
6. Commit the working fix with a detailed message describing the problem, the
- solution and a Fixes tag determined with the find-fixes skill. Do not
- add a Signed-off-by tag.
+ solution, a Fixes tag determined with the find-fixes skill, and a stable
+ tag if the stable-tag skill calls for one. Do not add a Signed-off-by tag.
7. Identify the maintainers and lists using scripts/get_maintainer.pl.
Documentation/process/security-bugs.rst shows how to do that.
8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/stable-tag/SKILL.md b/agents/skills/stable-tag/SKILL.md
new file mode 100644
index 000000000000..d87bcc95089d
--- /dev/null
+++ b/agents/skills/stable-tag/SKILL.md
@@ -0,0 +1,72 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: stable-tag
+description: >-
+ Decide whether a Linux kernel fix should be backported to stable kernels
+ and return verified Cc: stable tag lines. Use when preparing or reviewing
+ bug-fix patches, drafting their commit messages, or checking an existing
+ stable tag.
+---
+
+# Determine a stable tag
+
+Read Documentation/process/stable-kernel-rules.rst. It says which changes go
+to stable and how to write the tag, its prerequisites and its version. Follow
+the rules for skills in Documentation/process/coding-assistants.rst.
+
+Judge a change by what it does, not by how its description labels it: a
+"cleanup" that releases a resource on an error path fixes a leak. In practice,
+the stable trees take:
+
+- Fixes for crashes, oopses, BUG and WARN splats, hangs, lockups, RCU stalls,
+ deadlocks, data corruption and security issues.
+- Fixes for use-after-free, double free, NULL pointer dereferences,
+ out-of-bounds accesses, integer overflows, uninitialized data, reference
+ counting errors, and memory or resource leaks.
+- Fixes for races, including data races.
+- Fixes for incorrect behavior, such as wrong results, wrong hardware
+ programming, or endianness and type errors.
+- Fixes for problems reported by syzbot, other fuzzers, or the KASAN, KMSAN,
+ KCSAN and UBSAN sanitizers.
+- New device IDs and quirks for drivers that exist in the stable trees, device
+ tree fixes, and device tree additions for hardware that existing drivers
+ support.
+- Corrections to documentation that is wrong.
+- Performance fixes that prevent lockups, stalls or hangs.
+- Reverts of commits that are in a released kernel.
+- Fixes for bugs introduced by commits that were backported to stable.
+
+They do not take the following, unless a fix that is taken depends on it:
+
+- New features, new user-visible interfaces or behavior, new drivers, and new
+ module parameters or sysfs attributes.
+- Refactoring, code movement and other preparation patches.
+- Optimizations that do not prevent lockups, stalls or hangs.
+- Cleanups that do not change behavior, such as style, renames and comment
+ changes.
+
+Then work out which releases need the fix:
+
+- Determine the Fixes tags with the find-fixes skill first. A change with no
+ introducing commit, such as a new device ID, a quirk or a build fix, or a
+ bug older than the available history, affects every release that contains
+ the code it changes. Otherwise, if the Fixes tags are unresolved, so is the
+ stable decision.
+- For each Fixes tag, find the first release that contains the commit, not the
+ release it was based on. If no release contains it, check whether the
+ commit was itself backported to stable.
+- Check that everything the fix uses exists in the oldest affected release.
+ If something is missing, list the commit that added it as a prerequisite
+ if it is small and fit for stable, or start the tag at the first release
+ that has it.
+- Give every stable tag in a commit the same version: a tag without a version
+ asks for every stable tree and overrides the versions in the other tags.
+ The stable tooling reads the first version number in a tag comment as the
+ version, so describe what older trees need in the commit message.
+- Follow the stable tag policy in the maintainer profiles, the `P:` entries in
+ MAINTAINERS, for the changed files.
+- Ask the caller whether the fix addresses an unpublished vulnerability, as
+ described in Documentation/process/threat-model.rst.
+
+Return the tag lines with the reasons for them, or the reasons for no tag. If
+the decision cannot be made, return no tag and say what is missing.
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v5 4/6] agents: add a skill to find other instances of a fixed bug
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
` (2 preceding siblings ...)
2026-11-11 22:59 ` [PATCH v5 3/6] agents: add a skill to determine stable tags Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 5/6] agents: add a skill to write commit messages Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 6/6] agents: add a skill to write KUnit tests Theodore Ts'o
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Sasha Levin, Theodore Ts'o, linux-doc, linux-kernel,
Jonathan Corbet, Shuah Khan, Randy Dunlap, Mark Brown,
Laurent Pinchart, Greg Kroah-Hartman, Leon Romanovsky,
Konstantin Ryabitsev, Thorsten Leemhuis, Michael S. Tsirkin,
Kees Cook, Geert Uytterhoeven, Dan Carpenter, Miguel Ojeda,
Alexei Starovoitov, Julia Lawall, SJ Park, Bradley Morgan,
stable
From: Sasha Levin <sashal@kernel.org>
A bug fixed in one place often exists elsewhere, in copied code, sibling
drivers, or other users of the same interface, and reviewers routinely
ask whether that was checked. Left alone, agents tend to audit the whole
tree by reading it. Add a skill that states the defect as a rule,
searches for it through shared interfaces, copied code, the introducing
series and earlier fixes, and verifies each candidate before reporting
it.
When Coccinelle is available, the skill searches with a semantic patch:
it looks for an existing one under scripts/coccinelle/, checks that the
rule marks the fixed site in the code before the fix, runs it over the
whole tree with coccicheck, and checks which code spatch could not
parse. These steps live in references/coccinelle.md, which the agent
reads only when it uses Coccinelle. The semantic patch is returned with
the results, so that the commit message of a fix can include it.
Tested on the parent of commit 989fe6771266 ("drm/nouveau/gsp: fix
mismatched alloc/free for kvmalloc()"): both the existing
api/kfree_mismatch.cocci and the example rule mark the two kfree() calls
that commit fixed, and a whole-tree run found the same bug in four other
drivers that were later fixed separately.
The sites found are reported, not fixed. When the same defect turns up
in several places, the skill also reports whether the interface invites
it. The missing of_node_put() calls that iterators/for_each_child.cocci
finds were fixed one driver at a time for years, until
commit 34af4554fb0c ("of: Introduce for_each_*_child_of_node_scoped() to
automate of_node_put() handling") made the put automatic. Whether to fix
the interface or each site is left to the developer.
Point the bug-fix procedure in coding-assistants.rst at the skill.
Link: https://lore.kernel.org/r/DM6DXZJSMPO3.J5PONDJ3HWNP@gmail.com
Signed-off-by: Sasha Levin <sashal@kernel.org>
Link: https://patch.msgid.link/20261020161642.3713052-5-sashal@kernel.org
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 5 +-
agents/skills/find-siblings/SKILL.md | 36 ++++++++++
.../find-siblings/references/coccinelle.md | 66 +++++++++++++++++++
3 files changed, 106 insertions(+), 1 deletion(-)
create mode 100644 agents/skills/find-siblings/SKILL.md
create mode 100644 agents/skills/find-siblings/references/coccinelle.md
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index 81ee530a8a7f..c2f9b71650c1 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -39,6 +39,8 @@ The following skills are available:
checks an existing one.
* agents/skills/stable-tag/SKILL.md decides whether a fix goes to stable and
returns its stable tag, or checks an existing one.
+* agents/skills/find-siblings/SKILL.md looks for the same bug elsewhere in the
+ tree.
Licensing and Legal Requirements
================================
@@ -83,7 +85,8 @@ these steps:
5. Build and verify that the fix works either using the reproducer or by
re-running a complete analysis; drop any fix that doesn't work and try
another one. The fix must not add build warnings and must pass the
- checkpatch.pl checks (see submitting-patches.rst).
+ checkpatch.pl checks (see submitting-patches.rst). Then look for the same
+ bug elsewhere with the find-siblings skill.
6. Commit the working fix with a detailed message describing the problem, the
solution, a Fixes tag determined with the find-fixes skill, and a stable
tag if the stable-tag skill calls for one. Do not add a Signed-off-by tag.
diff --git a/agents/skills/find-siblings/SKILL.md b/agents/skills/find-siblings/SKILL.md
new file mode 100644
index 000000000000..8d007472675d
--- /dev/null
+++ b/agents/skills/find-siblings/SKILL.md
@@ -0,0 +1,36 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: find-siblings
+description: >-
+ Find other places in the Linux kernel tree that have the same defect as a
+ bug being fixed, and verify each candidate. Use after fixing or reviewing
+ a bug fix, or when asked whether the same bug exists elsewhere.
+---
+
+# Find other instances of a bug
+
+Follow the rules for skills in Documentation/process/coding-assistants.rst.
+
+- State the defect as a rule that does not depend on local names, such as
+ "memory from kvmalloc() is released with kfree()".
+- Search the tree as it was before the fix, not the working tree. Look at
+ other users of the same interface, field or lock, code copied from the same
+ origin, the rest of the series that introduced the bug, and earlier fixes
+ for the same defect. Limit history searches to the relevant directories.
+- If Coccinelle is available (`spatch --version` works), search for the
+ defect with a semantic patch as
+ [references/coccinelle.md](references/coccinelle.md) describes. Otherwise
+ use text searches and report that limit.
+- A match is a lead. Read each candidate with its callers, locking and object
+ lifetimes, and classify it as confirmed, safe or undetermined, with the
+ reason. Check whether a confirmed site is already fixed in the current tree
+ or in a pending tree such as linux-next.
+- If several sites have the same defect, check whether the interface they use
+ invites it, for example by making every caller drop a reference by hand when
+ it leaves a loop early. If it does, report that the defect is better fixed
+ in the interface, along with the sites. The developer decides which way to
+ fix it.
+
+Return the searches you ran and their scope, with any semantic patch you
+used, and the classified sites with their maintainers. Do not fix the sites or
+the interface.
diff --git a/agents/skills/find-siblings/references/coccinelle.md b/agents/skills/find-siblings/references/coccinelle.md
new file mode 100644
index 000000000000..6b09ce9d04c8
--- /dev/null
+++ b/agents/skills/find-siblings/references/coccinelle.md
@@ -0,0 +1,66 @@
+<!-- SPDX-License-Identifier: GPL-2.0-only -->
+
+# Searching for a bug pattern with Coccinelle
+
+Documentation/dev-tools/coccinelle.rst describes `make coccicheck` and its
+options. The semantic patch language is documented at
+https://coccinelle.gitlabpages.inria.fr/website/docs/.
+
+1. Look under `scripts/coccinelle/` for a semantic patch that already covers
+ the defect. Read its rules rather than its name: `kfree()` of memory from
+ `kvmalloc()` is covered by `api/kfree_mismatch.cocci`, while
+ `api/kvmalloc.cocci` only flags an open-coded `is_vmalloc_addr()` test.
+
+2. Otherwise, write a semantic patch outside the repository. Match only what
+ the defect needs, not names or statements specific to the fixed site. Mark
+ the lines of interest with `*`, and declare `virtual context`: coccicheck
+ passes `-D context`, and spatch rejects a mode the file does not declare.
+ A minimal rule for memory from `kvmalloc()` released with `kfree()`, a
+ case that `api/kfree_mismatch.cocci` covers more completely:
+
+ virtual context
+
+ @@
+ expression E;
+ @@
+ E = \(kvmalloc\|kvzalloc\|kvcalloc\|kvmalloc_array\)(...);
+ ...
+ * kfree(E);
+
+3. Check that it finds the site you fixed. Coccinelle reads the files on
+ disk, where the fix is usually already applied, so copy the file as it was
+ before the fix to a directory outside the repository and run
+ `spatch -D <mode> --very-quiet --sp-file <rule> <copy>`, with a mode the
+ rule declares on a `virtual` line, such as `context` or `report`. Without
+ `-D`, rules that depend on a mode do not run and nothing is reported. The
+ rule must mark the fixed site in that copy, and nothing in the fixed
+ version. If it misses the site, correct the rule before searching further.
+
+4. Search the whole tree:
+
+ make coccicheck MODE=context COCCI=<rule> DEBUG_FILE=<new log file>
+
+ - Use a `MODE` the rule declares on a `virtual` line, as in step 3.
+ - In context mode the output is a diff, and each line starting with `-`
+ is a line the rule marked; report mode prints one warning per site.
+ coccicheck searches the files on disk, so a site you already fixed
+ there is not marked; step 3 covers it.
+ - The kernel's `.cocciconfig` makes spatch skip files that do not contain
+ the rule's identifiers, so a whole-tree search is usually quick when the
+ rule names distinctive functions. Add `M=<dir>/` only if it is not.
+ - Give `COCCI` and `DEBUG_FILE` as absolute paths. With `M=`, coccicheck
+ runs from that directory.
+ - Read the log. Without `DEBUG_FILE`, spatch errors are discarded and a
+ broken rule shows only as "coccicheck failed". coccicheck refuses to
+ reuse an existing log file.
+ - Header files are searched only with `SPFLAGS=--include-headers`, or with
+ a `// Options: --include-headers` line at the top of the rule.
+
+5. Check what was not searched. Coccinelle skips code it cannot parse without
+ saying so. Run `spatch --parse-c` on the searched files or directories: a
+ nonzero `nb bad` count means part of them was skipped. Search those files
+ another way and report the gap.
+
+If the rule marks many sites that turn out to be safe, tighten it, for example
+with `when !=` constraints, and run it again rather than discarding candidates
+by hand.
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v5 5/6] agents: add a skill to write commit messages
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
` (3 preceding siblings ...)
2026-11-11 22:59 ` [PATCH v5 4/6] agents: add a skill to find other instances of a fixed bug Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
2026-11-11 22:59 ` [PATCH v5 6/6] agents: add a skill to write KUnit tests Theodore Ts'o
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Sasha Levin, Theodore Ts'o, linux-doc, linux-kernel,
Jonathan Corbet, Shuah Khan, Randy Dunlap, Mark Brown,
Laurent Pinchart, Greg Kroah-Hartman, Leon Romanovsky,
Konstantin Ryabitsev, Thorsten Leemhuis, Michael S. Tsirkin,
Kees Cook, Geert Uytterhoeven, Dan Carpenter, Miguel Ojeda,
Alexei Starovoitov, Julia Lawall, SJ Park, Bradley Morgan,
stable
From: Sasha Levin <sashal@kernel.org>
Assistants are asked to commit a fix with a detailed message, and the
find-fixes and stable-tag skills leave their tags for that message, but
nothing says how to write it. Messages written by assistants tend to be
long, and Linus recently asked that pull request text written with an
LLM be less verbose and prefer the imperative voice.
Add a skill that sends the agent to the parts of submitting-patches.rst,
5.Posting.rst and the maintainer documentation that cover commit
messages, cover letters and pull requests, and to the P: profiles of the
changed files. It adds what agents get wrong: stating only what the
change and the supplied sources support, keeping the text short and in
the imperative mood, and adding no tags that were not supplied.
When a semantic patch found the bug, the message includes it, or its path
when it is under scripts/coccinelle/, so that reviewers and the
Coccinelle developers can see it and run it again.
Point the bug-fix procedure in coding-assistants.rst at the skill.
Link: https://lore.kernel.org/r/CAHk-=wgXU50=KgZNZc1JDxsSxg9Z+DjG1_2yU-fNXpZtUe4XDw@mail.gmail.com
Link: https://lore.kernel.org/r/50531bd9-f3ea-2d45-7b3a-a96a446a8fcc@inria.fr
Signed-off-by: Sasha Levin <sashal@kernel.org>
Link: https://patch.msgid.link/20261020161642.3713052-6-sashal@kernel.org
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 9 +++--
agents/skills/commit-message/SKILL.md | 45 +++++++++++++++++++++
2 files changed, 51 insertions(+), 3 deletions(-)
create mode 100644 agents/skills/commit-message/SKILL.md
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index c2f9b71650c1..f0bae6bfe9a0 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -41,6 +41,8 @@ The following skills are available:
returns its stable tag, or checks an existing one.
* agents/skills/find-siblings/SKILL.md looks for the same bug elsewhere in the
tree.
+* agents/skills/commit-message/SKILL.md writes, rewrites or reviews a commit
+ message or cover letter, and writes the text of a pull request.
Licensing and Legal Requirements
================================
@@ -87,9 +89,10 @@ these steps:
another one. The fix must not add build warnings and must pass the
checkpatch.pl checks (see submitting-patches.rst). Then look for the same
bug elsewhere with the find-siblings skill.
-6. Commit the working fix with a detailed message describing the problem, the
- solution, a Fixes tag determined with the find-fixes skill, and a stable
- tag if the stable-tag skill calls for one. Do not add a Signed-off-by tag.
+6. Commit the working fix with a message written with the commit-message skill,
+ describing the problem, the solution, a Fixes tag determined with the
+ find-fixes skill, and a stable tag if the stable-tag skill calls for one. Do
+ not add a Signed-off-by tag.
7. Identify the maintainers and lists using scripts/get_maintainer.pl.
Documentation/process/security-bugs.rst shows how to do that.
8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/commit-message/SKILL.md b/agents/skills/commit-message/SKILL.md
new file mode 100644
index 000000000000..c75f028c56da
--- /dev/null
+++ b/agents/skills/commit-message/SKILL.md
@@ -0,0 +1,45 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: commit-message
+description: >-
+ Write, rewrite or review the commit message for a Linux kernel change or
+ the cover letter for a patch series, and write the signed tag and pull
+ request text for a subsystem pull. Use when committing or preparing
+ patches, when asked to improve or check a commit message, or when
+ preparing a pull request for an upstream maintainer.
+---
+
+# Write a commit message
+
+Read "Describe your changes", the sections on tags, "The canonical patch
+format" and "Commentary" in Documentation/process/submitting-patches.rst, and
+Documentation/process/5.Posting.rst for cover letters. Follow the maintainer
+profiles, the `P:` entries in MAINTAINERS, for the changed files; they take
+precedence. Follow the rules for skills and for attribution in
+Documentation/process/coding-assistants.rst, and
+Documentation/process/generated-content.rst when a tool found the problem.
+When editing someone else's message, also follow
+Documentation/maintainer/modifying-patches.rst.
+
+- State only what the diff and the sources you were given support, such as a
+ bug report, a crash log, test results, or the list discussion found with
+ `lei q` on lore.kernel.org. If the reason for the change is not known,
+ return no message and say what is missing.
+- Take the Fixes and stable tags from the find-fixes and stable-tag skills.
+ Add other tags only when they were supplied or given on the list. Never add
+ a Signed-off-by.
+- If a semantic patch found the bug, include it in the message between
+ `// <smpl>` and `// </smpl>` lines. For one under scripts/coccinelle/, give
+ its path instead.
+- Use the imperative mood and keep the message as short as its content
+ allows. Leave out markdown, labels such as "Root cause:", intensifiers, a
+ restatement of the subject, and the story of the investigation.
+- Check the result with `scripts/checkpatch.pl --no-signoff`.
+
+For the signed tag and email of a pull request, follow
+Documentation/maintainer/pull-requests.rst,
+Documentation/maintainer/rebasing-and-merging.rst and
+Documentation/maintainer/messy-diffstat.rst. Summarize what the pull contains
+and why from the commit messages in the range, in the same voice, without
+repeating the shortlog. Ask the caller for conflict resolutions and testing
+that the history does not show.
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread* [PATCH v5 6/6] agents: add a skill to write KUnit tests
2026-11-11 22:59 [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages Theodore Ts'o
` (4 preceding siblings ...)
2026-11-11 22:59 ` [PATCH v5 5/6] agents: add a skill to write commit messages Theodore Ts'o
@ 2026-11-11 22:59 ` Theodore Ts'o
5 siblings, 0 replies; 7+ messages in thread
From: Theodore Ts'o @ 2026-11-11 22:59 UTC (permalink / raw)
To: workflows, ksummit
Cc: Theodore Ts'o, linux-doc, linux-kernel, Jonathan Corbet,
Shuah Khan, Randy Dunlap, Mark Brown, Laurent Pinchart,
Greg Kroah-Hartman, Leon Romanovsky, Konstantin Ryabitsev,
Thorsten Leemhuis, Michael S. Tsirkin, Kees Cook,
Geert Uytterhoeven, Dan Carpenter, Miguel Ojeda,
Alexei Starovoitov, Julia Lawall, SJ Park, Bradley Morgan,
Sasha Levin, stable
Add a skill under agents/skills/writing-kunit-tests/ to guide coding
assistants when designing, implementing, verifying, or reviewing KUnit
unit tests. Point the skill at the KUnit and process documentation and
cover unit testing principles (testing behaviors rather than
implementation details, keeping tests focused and DAMP, choosing
non-default and distinct test values, using narrow expectations, and
maintaining test isolation), KUnit resource management and static stub
idioms, and verification with kunit.py.
Update Documentation/process/coding-assistants.rst to list the new skill
and note that skills only inspect and report unless their task is to
write or modify code or tests.
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
---
Documentation/process/coding-assistants.rst | 11 +-
agents/skills/writing-kunit-tests/SKILL.md | 344 ++++++++++++++++++++
2 files changed, 351 insertions(+), 4 deletions(-)
create mode 100644 agents/skills/writing-kunit-tests/SKILL.md
diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index f0bae6bfe9a0..bb927fea5024 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -28,10 +28,11 @@ skill with a ``SKILL.md`` entry point in the `Agent Skills format
documents that apply to its task and adds only what assistants tend to get
wrong.
-Skills inspect and report. They do not change files, create commits or tags,
-or send mail. A skill returns its result with the evidence for it, or says what
-is missing. Do not fill a missing result with a guess or a placeholder, and do
-not finalize the work until it is resolved.
+Unless a skill's task is to write or modify code or tests, skills only inspect
+and report: they do not change files, create commits or tags, or send mail. A
+skill returns its result with the evidence for it, or says what is missing. Do
+not fill a missing result with a guess or a placeholder, and do not finalize
+the work until it is resolved.
The following skills are available:
@@ -43,6 +44,8 @@ The following skills are available:
tree.
* agents/skills/commit-message/SKILL.md writes, rewrites or reviews a commit
message or cover letter, and writes the text of a pull request.
+* agents/skills/writing-kunit-tests/SKILL.md designs, writes, verifies, or
+ reviews KUnit unit tests.
Licensing and Legal Requirements
================================
diff --git a/agents/skills/writing-kunit-tests/SKILL.md b/agents/skills/writing-kunit-tests/SKILL.md
new file mode 100644
index 000000000000..1f19b585b9b4
--- /dev/null
+++ b/agents/skills/writing-kunit-tests/SKILL.md
@@ -0,0 +1,344 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: writing-kunit-tests
+description: >-
+ Design, implement, verify, or review KUnit unit tests for the Linux kernel.
+ Use when writing new KUnit tests, expanding existing KUnit test suites,
+ adding regression tests with KUnit, or reviewing KUnit test patches.
+---
+
+# Write KUnit tests
+
+Before writing or modifying any code, read the relevant kernel documentation:
+- **KUnit Framework & Style**:
+ `Documentation/dev-tools/kunit/usage.rst`,
+ `Documentation/dev-tools/kunit/style.rst`,
+ `Documentation/dev-tools/kunit/start.rst`, and
+ `Documentation/dev-tools/kunit/api/functionredirection.rst`
+- **Kernel Development & Patch Submission**:
+ `Documentation/process/development-process.rst`,
+ `Documentation/process/coding-style.rst`,
+ `Documentation/process/submitting-patches.rst`, and
+ `Documentation/process/license-rules.rst`
+- **AI Coding Assistants & Tool-Generated Content**:
+ `Documentation/process/coding-assistants.rst` and
+ `Documentation/process/generated-content.rst`
+
+Also inspect existing KUnit tests in the target subsystem (e.g., `*-test.c` or
+`tests/*_kunit.c`) to follow established local conventions for file naming,
+symbol visibility, Kconfig, and Makefile integration.
+
+---
+
+## 1. Core Unit Testing Principles
+
+Apply the following software testing best practices to ensure KUnit tests have
+high **fidelity** (fail when code is broken), **resilience** (only fail when
+actual behavior breaks, not during internal refactoring), **precision**
+(pinpoint the exact defect on failure), and **clarity** (serve as executable
+documentation):
+
+### 1.1 Test Behaviors, Not Functions or Implementation Details
+- **Avoid a 1:1 function-to-test mapping**: A single C function often exhibits
+ multiple distinct behaviors (e.g., normal insertion, merging with left/right
+ neighbors, splitting an existing entry, error handling), and a single logical
+ behavior may span multiple functions (e.g., insert followed by lookup and
+ removal). Write separate test cases for each distinct behavior.
+- **Test public/subsystem APIs over internal details**: Exercise the unit
+ through its intended interface rather than testing private helper functions in
+ isolation whenever possible. If internal implementation details are
+ refactored without changing observable behavior, existing tests should
+ continue to pass.
+- **Do not write "change-detector" tests**: Never write tests that merely
+ mirror the implementation line-by-line or assert an exact sequence of
+ internal helper calls without checking the resulting state or output.
+
+### 1.2 Keep Tests Focused
+- **One scenario per test case**: Each `static void test_...(struct kunit *test)`
+ function should test a single scenario or behavior.
+- **Do not chain unrelated scenarios in one test**: Avoid mutating state across
+ a long sequence of unrelated scenarios in a single test function where side
+ effects from an earlier check can mask bugs or invalidate assumptions in
+ later checks.
+- **Include the scenario and expected outcome in test names**: Name test
+ functions so a developer can tell what scenario is being exercised and what
+ should happen from the function name alone (e.g.,
+ `test_es_insert_adjacent_same_status_merges_extents` or
+ `unpack_u32_with_null_name_fails` rather than just `test_insert` or
+ `test_unpack`).
+
+### 1.3 Make Tests DAMP, Not Overly DRY
+- **Prioritize readability by inspection (DAMP — Descriptive and Meaningful
+ Phrases)**: Because tests do not have their own tests, their correctness must
+ be obvious to a human reviewer reading top-to-bottom. Do not over-abstract
+ tests just to eliminate a few lines of duplication.
+- **Keep cause and effect together**: Set up the specific inputs that drive a
+ test's outcome directly inside the test case body right before the call under
+ test and its `KUNIT_EXPECT_*` checks. Never hide the critical input values
+ that determine an expected output inside a distant `.init` function.
+- **Include only relevant details (hide noise)**: Use helper functions to hide
+ irrelevant boilerplate setup (such as allocating a dummy `super_block`,
+ initializing locks, or zeroing unrelated struct fields), but pass the values
+ that actually matter to the test explicitly as arguments at the call site:
+
+ ```c
+ /* BAD: Critical values hidden inside helper, or noisy setup inline */
+ inode = create_test_inode();
+ KUNIT_EXPECT_EQ(test, get_quota_blocks(inode), 42); /* Where did 42 come from? */
+
+ /* GOOD: Helper hides boilerplate; test-relevant value is explicit */
+ inode = create_test_inode_with_reserved_blocks(test, 42);
+ KUNIT_EXPECT_EQ(test, get_quota_blocks(inode), 42);
+ ```
+
+### 1.4 Don't Put Logic in Tests & Prefer Literals/Constants
+- **State expected outputs directly**: Never compute expected values in
+ assertions using arithmetic, bit shifts, string concatenation, loops, or
+ conditionals that duplicate the production algorithm. Computing expectations
+ in tests can introduce bugs in the test itself or mask a shared bug in
+ production code.
+- **Prefer literals or named constants in assertions**: Compare actual results
+ against concrete literals or self-explanatory constants rather than dynamic
+ expressions derived from the system under test.
+
+### 1.5 Choose Robust Test Values & Think Beyond Line Coverage
+- **Test with non-default values**: In the kernel, structs are frequently
+ zero-allocated (`kzalloc` / `kunit_kzalloc`). If you test a setter, parser,
+ or lookup using `0`, `false`, `NULL`, or enum value `0`, a broken
+ implementation that never writes the field will still pass! Always use
+ non-zero, non-default test values for positive tests.
+- **Use distinct values for each parameter**: When calling a function that
+ takes multiple arguments of the same or compatible types (e.g.,
+ `ext4_es_insert_extent(inode, lblk, len, pblk, status, ...)`), use clearly
+ distinct values (e.g., `lblk = 10`, `len = 5`, `pblk = 1000`) so swapped
+ arguments or off-by-one mixups are caught immediately.
+- **Think beyond line coverage**:
+ - **Branch & Condition coverage**: For compound boolean conditions like
+ `if ((a && b) || !c)`, write test cases that exercise each condition
+ independently, not just a single path that executes the line.
+ - **Boundary & Edge cases**: Test `0`, `1`, exact power-of-two/cluster
+ boundaries, maximum legal limits (e.g., `INT_MAX`, `ULONG_MAX`,
+ `EXT_MAX_BLOCKS`), overflow/underflow boundaries, empty trees/lists,
+ single-element collections, and multi-element spans.
+ - **Error paths**: Test invalid inputs, `-EINVAL` / `-ENOMEM` / `-ENOSPC`
+ conditions, and verify that error paths leave data structures in a valid,
+ uncorrupted state without leaking resources.
+
+### 1.6 Prefer Narrow Assertions & Make Failures Actionable
+- **Actionable failure messages**: When a test fails, the test name and KUnit
+ failure log alone should be enough to start debugging without adding
+ `printk`s and re-running.
+- **Use specific KUnit expectation macros**:
+ - Use `KUNIT_EXPECT_EQ(test, actual, expected)`, `KUNIT_EXPECT_NE`,
+ `KUNIT_EXPECT_LT`, `KUNIT_EXPECT_LE`, `KUNIT_EXPECT_GT`, `KUNIT_EXPECT_GE`
+ for integers/enums (instead of `KUNIT_EXPECT_TRUE(test, a == b)`, which
+ only prints `Expected true, got false`).
+ - Use `KUNIT_EXPECT_PTR_EQ`, `KUNIT_EXPECT_NULL`, `KUNIT_EXPECT_NOT_NULL`,
+ `KUNIT_EXPECT_NOT_ERR_OR_NULL` for pointers.
+ - Use `KUNIT_EXPECT_STREQ` / `KUNIT_EXPECT_MEMEQ` for strings and buffers.
+- **Use `_MSG` variants in loops and helpers**: Whenever an expectation is
+ inside a helper function, loop, or table-driven check, use
+ `KUNIT_EXPECT_*_MSG(test, ..., "context fmt", ...)` so the failure output
+ identifies the exact case or index that failed.
+- **Prefer narrow assertions**: Assert only the struct fields or properties
+ relevant to the behavior under test, rather than asserting every unrelated
+ field of a large struct (which creates brittle tests that break whenever
+ unrelated fields change).
+
+### 1.7 Test Isolation, Order Independence, and Zero Flakiness
+- **Complete independence between test cases**: Every test case must pass when
+ run by itself (`kunit.py run suite.test`), in any order, or repeatedly.
+- **Never leak mutable shared state**: Avoid file-scope mutable globals. Prefer
+ allocating per-test context in `test->priv` via `kunit_kzalloc(test, ...)` in
+ `.init`. If a suite shares a fixture structure, ensure `.init` and `.exit`
+ completely reset all trees, lists, flags, and stub counters before and after
+ every single test case.
+- **No "sleep gambling"**: Never use `msleep()` or arbitrary delays to wait for
+ asynchronous work in unit tests. Test synchronous entry points, flush
+ workqueues deterministically, or inject synchronous stubs.
+
+### 1.8 High Fidelity & Smart Use of Test Doubles (Real > Fake > Stub > Mock)
+- **Prefer real implementations first**: Use real kernel data structures (e.g.,
+ `rbtree`, `xarray`, `list_head`, in-memory anonymous `super_block` / `inode`,
+ or `kunit_device_register()`) whenever they run fast and deterministically in
+ memory.
+- **Use fakes or stubs to isolate heavyweight dependencies**: When code under
+ test interacts with hardware, disk I/O, journals, block allocators, or global
+ kernel state, isolate it using:
+ 1. **Lightweight in-memory fakes** (e.g., an ops struct backed by a memory
+ buffer), or
+ 2. **KUnit static stubs** (`KUNIT_STATIC_STUB_REDIRECT` and
+ `kunit_activate_static_stub`).
+- **Avoid overusing mocks / interaction verification**:
+ - Prefer **state testing** (verifying return values and resulting data
+ structure state) over **interaction testing** (verifying that function X
+ was called).
+ - Only verify **state-changing** external calls (e.g., verifying that a
+ delayed-allocation block reservation was claimed or released), never
+ read-only query helpers.
+ - When verifying stub calls, only check arguments relevant to the behavior
+ being tested.
+
+### 1.9 Parameterize Repetitive Tests Judiciously
+- **Use parameterized or table-driven tests for input/output matrices**: When
+ testing the same behavior across many input combinations (e.g., extent
+ merge/split geometries, timestamp bit-decoding tables, hash test vectors),
+ use `KUNIT_ARRAY_PARAM` / `KUNIT_ARRAY_PARAM_DESC` with `KUNIT_CASE_PARAM`
+ (or a clean table-driven helper) to avoid copy-pasting identical test
+ functions.
+- **Do not put conditional logic inside parameterized tests**: If a
+ parameterized test requires `if (param->expect_error)` or
+ `switch (param->mode)` inside the test function to decide what assertions to
+ run, split it into separate parameterized or standalone tests instead.
+
+---
+
+## 2. KUnit Framework Idioms & Mechanics
+
+### 2.1 Expectations vs. Assertions
+- **`KUNIT_EXPECT_*`**: Records a test failure and logs diagnostic details, but
+ **continues** executing the rest of the test case. Use `KUNIT_EXPECT_*` for
+ the behavioral checks in your test.
+- **`KUNIT_ASSERT_*`**: Immediately **aborts** the current test case
+ (terminating the KUnit kthread) on failure. Use `KUNIT_ASSERT_*` for
+ preconditions whose failure makes continuing impossible or unsafe (e.g.,
+ `KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ptr)` after memory allocation or object
+ lookup before dereferencing `ptr`).
+- **CRITICAL**: **Never** use `KUNIT_ASSERT_*` in `.exit()`, `.suite_exit()`,
+ or `kunit_resource` / action cleanup callbacks. Aborting during teardown
+ skips subsequent cleanup steps and causes memory or resource leaks in the
+ running kernel.
+
+### 2.2 Resource & Memory Management
+- **Managed memory**: Always prefer `kunit_kmalloc()`, `kunit_kzalloc()`,
+ `kunit_kcalloc()`, `kunit_kmalloc_array()`, and `kunit_kstrdup()` over raw
+ `kmalloc`/`kzalloc`. KUnit automatically frees these allocations when the
+ test case exits—even if a `KUNIT_ASSERT_*` aborts the test midway.
+- **Deferred cleanup actions**: For non-memory resources (e.g., unregistering a
+ shrinker, freeing slab cache objects, releasing locks/superblocks, cleaning
+ up trees), either clean them up in `.exit` or register a deferred action
+ immediately after acquisition using `kunit_add_action_or_reset()`:
+
+ ```c
+ KUNIT_DEFINE_ACTION_WRAPPER(my_resource_cleanup, my_resource_cleanup_wrapper,
+ struct my_resource *);
+ ...
+ ret = kunit_add_action_or_reset(test, my_resource_cleanup_wrapper, res);
+ KUNIT_ASSERT_EQ(test, ret, 0);
+ ```
+ Always use `KUNIT_DEFINE_ACTION_WRAPPER()` rather than casting function
+ pointers to `kunit_action_t`, as casting function pointers breaks Control
+ Flow Integrity (CFI).
+- **Safe `.exit` functions**: Remember that `.exit` and `.suite_exit` run even
+ if `.init` or `.suite_init` failed or exited early. Always guard `.exit`
+ cleanup against NULL or partially initialized pointers.
+- **Fake devices**: When code under test requires a `struct device *` (e.g.,
+ for `devm_*` managed APIs), use `kunit_device_register(test, "name")` from
+ `<kunit/device.h>`.
+
+### 2.3 Testing Static Functions & Isolating Dependencies
+Check how the target subsystem exposes internal functions to KUnit tests and
+follow the local convention:
+
+1. **Subsystem export macros** (e.g., `EXPORT_SYMBOL_FOR_EXT4_TEST(fn)` or
+ `VISIBLE_IF_KUNIT` / `EXPORT_SYMBOL_IF_KUNIT(fn)` from
+ `<kunit/visibility.h>` paired with
+ `MODULE_IMPORT_NS("EXPORTED_FOR_KUNIT_TESTING");` in the test file).
+2. **Conditionally `#include`ing the test file** at the bottom of the `.c` file
+ under `#if IS_ENABLED(CONFIG_<SUBSYSTEM>_KUNIT_TEST)` if the subsystem
+ already uses that pattern to test `static` functions directly.
+3. **Function Redirection (Static Stubs)**: To intercept calls to external
+ functions during a test without refactoring production APIs:
+ - In the real function (right after variable declarations):
+ ```c
+ #include <kunit/static_stub.h>
+ ...
+ KUNIT_STATIC_STUB_REDIRECT(my_external_fn, arg1, arg2);
+ ```
+ - In the KUnit test:
+ ```c
+ kunit_activate_static_stub(test, my_external_fn, my_external_fn_stub);
+ ```
+ - If the stub needs the current `struct kunit *`, call
+ `kunit_get_current_test()` (`#include <kunit/test-bug.h>`).
+4. **Suppressing expected warning backtraces**: If a test intentionally
+ triggers `WARN()` / `WARN_ON()`, wrap the call in
+ `kunit_warning_suppress(test)` and verify with
+ `KUNIT_EXPECT_SUPPRESSED_WARNING_COUNT(test, 1)` so intentional warnings do
+ not pollute kernel logs.
+
+### 2.4 Suite, File, and Kconfig Nomenclature
+Unless the subsystem has an established convention (such as `fs/ext4/*-test.c`
+linked into `ext4-test.o`), follow `Documentation/dev-tools/kunit/style.rst`:
+
+- **Subsystem & Suite naming**: Name the suite `<subsystem>_<area>` using
+ underscores, without redundant `_kunit` or `_test` suffixes in `.name`
+ (unless matching existing suites in that directory).
+- **File naming**: Place new standalone test files in `tests/<suite>_kunit.c`
+ (or match the subsystem's existing `*-test.c` / `*_kunit.c` pattern).
+- **Kconfig**:
+ ```kconfig
+ config FOO_KUNIT_TEST
+ tristate "KUnit test for foo" if !KUNIT_ALL_TESTS
+ depends on FOO && KUNIT
+ default KUNIT_ALL_TESTS
+ help
+ This builds unit tests for foo.
+
+ For more information on KUnit and unit tests in general,
+ please refer to the KUnit documentation in
+ Documentation/dev-tools/kunit/.
+
+ If unsure, say N.
+ ```
+
+---
+
+## 3. Building, Running, and Verifying Tests
+
+Build and run the KUnit tests before finalizing or committing changes:
+
+1. **Run the test suite with `kunit.py`**:
+ ```bash
+ ./tools/testing/kunit/kunit.py run <suite_name>
+ ```
+ (If a `.kunitconfig` exists in the repo root or subsystem directory, pass
+ `--kunitconfig=.kunitconfig` or `--kunitconfig=<subdir>/.kunitconfig`, or
+ add needed configs via `--kconfig_add CONFIG_...=y`).
+2. **Verify zero build warnings**: Ensure the added or modified files compile
+ with zero compiler warnings or errors.
+3. **Verify test isolation**: Run individual test cases using glob filtering to
+ confirm no test depends on state left behind by an earlier test:
+ ```bash
+ ./tools/testing/kunit/kunit.py run "<suite_name>.<test_case_name>"
+ ```
+4. **Verify test fidelity**: Confirm that the tests actually exercise the
+ intended code paths (e.g., via GCOV/coverage if configured, or by
+ verifying that breaking the condition under test causes the KUnit
+ expectation to fail).
+
+---
+
+## 4. Coding Style, Licensing, and Commits
+
+Follow `Documentation/process/coding-style.rst`,
+`Documentation/process/submitting-patches.rst`,
+`Documentation/process/license-rules.rst`, and
+`Documentation/process/coding-assistants.rst`:
+
+- **SPDX & Module Macros**:
+ - Line 1 of every new `.c` test file must be
+ `// SPDX-License-Identifier: GPL-2.0` (or the appropriate
+ GPL-2.0-compatible identifier).
+ - Include `MODULE_LICENSE("GPL");` and `MODULE_DESCRIPTION("...");` at the
+ bottom of the test module.
+- **Checkpatch**: Run `./scripts/checkpatch.pl` on the changes and fix all
+ reported `ERROR`, `WARNING`, and `CHECK` issues.
+- **Commits**: When asked to create a commit, use the `commit-message` skill
+ (`agents/skills/commit-message/SKILL.md`). Explain what behaviors and edge
+ cases are covered, any minimal production code hooks added (such as
+ `KUNIT_STATIC_STUB_REDIRECT` or KUnit symbol exports), and how the tests were
+ verified. Never add a `Signed-off-by:` tag.
+- **Report verification status**: Clearly state what was built and tested
+ (including `kunit.py` and `checkpatch.pl` results), and explicitly note
+ anything that could not be built or verified.
--
2.53.0
^ permalink raw reply [flat|nested] 7+ messages in thread