linux-subsystems-update
Update and regenerate the Linux kernel subsystem list in pkg/subsystem/lists/linux.go (and custom rules in pkg/subsystem/linux/) using tools/syz-query-subsystems against a mainline (torvalds) Linux kernel checkout. Use when regenerating Linux subsystems for a new kernel release, adding custom subsystem rules, fixing MAINTAINERS parsing/naming errors, or associating syzkaller pseudo-syscalls with subsystems.
- License 许可
- Apache-2.0
- 所属仓库
- google/syzkaller
- 最近更新
- 2026-11-14
- Stars
- ★ 6.4k
- Forks
- 1.5k
01 前言 Front Matter
- name
- linux-subsystems-update
- description
- Update and regenerate the Linux kernel subsystem list in pkg/subsystem/lists/linux.go (and custom rules in pkg/subsystem/linux/) using tools/syz-query-subsystems against a mainline (torvalds) Linux kernel checkout. Use when regenerating Linux subsystems for a new kernel release, adding custom subsystem rules, fixing MAINTAINERS parsing/naming errors, or associating syzkaller pseudo-syscalls with subsystems.
03 SKILL.md 正文
Updating Linux Subsystems (pkg/subsystem/lists/linux.go)
Use this skill when updating or regenerating pkg/subsystem/lists/linux.go
or modifying the Linux subsystem extraction rules in pkg/subsystem/linux/.
Read the code in pkg/subsystem/linux/ (subsystems.go, rules.go, names.go, parents.go, maintainers.go)
as needed to understand how subsystems and hierarchies are inferred.
1. Obtaining a Linux Kernel Checkout (torvalds, NOT linux-next)
If the user has not provided a path to a Linux kernel checkout ($KERNEL_PATH), ask the user for one before running the generator.
[!IMPORTANT]
- Use upstream mainline (
torvalds/linux.git), NOTlinux-next. All subsystem list updates target mainline Linux, ideally checked out at the latest release or release candidate tag (e.g.,v6.19-rc6,v6.16-rc7) so the generated header comment and revision date reflect a mainline release tag.- Ensure the kernel working tree is clean. The generator walks source files in
$KERNEL_PATHto count files per subsystem and infer parent-child relationships. Untracked build artifacts or out-of-tree source files will skew file counts and parent inference.
2. Running syz-query-subsystems
Never hand-edit pkg/subsystem/lists/linux.go. Regenerate it via tools/syz-query-subsystems (run directly on the host so $KERNEL_PATH outside the repo is accessible):
go run ./tools/syz-query-subsystems \
-os linux \
-kernel "$KERNEL_PATH" \
-syzkaller . \
-name linux
- Pass
-debugto print the exact list of kernel source paths matched by each subsystem. - When investigating why a subsystem was dropped, merged, or assigned unexpected parents, it often helps to apply temporary debugging changes to
pkg/subsystem/linux/and re-runsyz-query-subsystemsto extract more information. Revert any temporary debugging code when done.
3. Caveats & Resolving Regeneration Errors
When MAINTAINERS or the kernel tree changes upstream, syz-query-subsystems may fail with errors or produce undesirable changes in pkg/subsystem/lists/linux.go:
-
Naming Failures or Collisions (
pkg/subsystem/linux/names.go):- First check if the new mailing list actually represents a distinct kernel subsystem. If it is a secondary/user list, a company/team catch-all (
kernel@collabora.com,coreteam@netfilter.org), or an overly broad cross-cutting list (x86@kernel.org), exclude it vianotSubsystemEmailsinpkg/subsystem/linux/rules.go. - If it is a genuine subsystem whose mailing list cannot be cleanly parsed by the generic rules or produces a name longer than 16 characters, add a mapping to
emailExceptionsinnames.go(and remove obsolete exceptions if a mailing list migrated upstream).
- First check if the new mailing list actually represents a distinct kernel subsystem. If it is a secondary/user list, a company/team catch-all (
-
Broken or Dangling Custom Rules (
pkg/subsystem/linux/rules.go):MAINTAINERS record not found: A section title inextraSubsystemswas renamed or removed upstream inMAINTAINERS. UpdateextraSubsystemswith the new title.unused keysin rule checks:- If the subsystem was removed from the kernel (e.g.,
bcachefs,reiserfs), remove it fromrules.go(if asyz_mount_image$*call still exists without a subsystem, move it to theTODOcomment insubsystemCalls). - If the subsystem was renamed or merged into another subsystem (e.g.,
ntfs->ntfs3,fat->exfat), move its rules to the new subsystem name. - If a still-existing subsystem vanished only because its
L:mailing list was removed or merged into a shared list (likelinux-fsdevel@vger.kernel.orgornetdev@vger.kernel.org), preserve it by adding itsMAINTAINERSsection title(s) toextraSubsystems.
- If the subsystem was removed from the kernel (e.g.,
-
MAINTAINERSParser Issues (pkg/subsystem/linux/maintainers.go):- Never edit
$KERNEL_PATH/MAINTAINERSto work around parsing errors. Fix the parser inmaintainers.goand add a unit test inmaintainers_test.go.
- Never edit
4. Reviewing the Generated Diff in pkg/subsystem/lists/linux.go
Even when syz-query-subsystems succeeds without errors, always inspect the diff of pkg/subsystem/lists/linux.go, especially the // The subsystem list: hierarchy comment at the top:
- Overly Broad New Subsystems: If a new mailing list covers a huge swath of the tree and swallows unrelated subsystems as children (check the
// Auto-inferred:parent comments), add the list tonotSubsystemEmailsinrules.go. - Important Subsystems Lost: If a major subsystem disappeared from the hierarchy tree because its dedicated mailing list was removed in
MAINTAINERS, add it toextraSubsystemsinrules.go. - Custom Hierarchy Adjustments: Use
addParents,noIndirectCc, andnoRemindersinrules.gowhen automatic parent inference or CC rules need manual overrides.
5. Testing and Committing
-
Run Subsystem and Dashboard Tests:
CI=true ./tools/syz-env go test ./pkg/subsystem/... ./dashboard/app/...- If
TestLinuxUpstreamSubsystemsfails after regeneration, investigate whether a subsystem's path rules or parent hierarchy regressed.
- If
-
Commit Conventions:
- Separate any parser/logic changes in
pkg/subsystem/ortools/syz-query-subsystems/into their own commit(s) first. - For the regeneration commit (including rule/name adjustments in
pkg/subsystem/linux/), use a commit message likepkg/subsystem: regenerate Linux subsystemsand mention the target kernel tag (e.g.,v6.19-rc6).
- Separate any parser/logic changes in
04 同仓库更多 Skills
syzlang-vm-testing
Verify syzkaller syscall descriptions (sys/linux/*.txt) and seed programs (sys/linux/test/*) inside a QEMU VM using syz-manager -mode run-tests, syzbot buildroot images, and kernel dynamic_debug/tracing.
linux-config-update
Update Linux kernel configurations in dashboard/config/linux (bits/*.yml, main.yml, and generated *.config files) using syz-kconf (`./tools/syz-env make configs`). Use when enabling or disabling kernel config options, bumping kernel tags (`bits/linux-upstream.yml`, `bits/linux-next.yml`), adding new config fragments or instances, or regenerating syzbot Linux kernel configs.