AGENT SKILL

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), NOT linux-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_PATH to 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 -debug to 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-run syz-query-subsystems to 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:

  1. 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 via notSubsystemEmails in pkg/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 emailExceptions in names.go (and remove obsolete exceptions if a mailing list migrated upstream).
  2. Broken or Dangling Custom Rules (pkg/subsystem/linux/rules.go):

    • MAINTAINERS record not found: A section title in extraSubsystems was renamed or removed upstream in MAINTAINERS. Update extraSubsystems with the new title.
    • unused keys in rule checks:
      • If the subsystem was removed from the kernel (e.g., bcachefs, reiserfs), remove it from rules.go (if a syz_mount_image$* call still exists without a subsystem, move it to the TODO comment in subsystemCalls).
      • 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 (like linux-fsdevel@vger.kernel.org or netdev@vger.kernel.org), preserve it by adding its MAINTAINERS section title(s) to extraSubsystems.
  3. MAINTAINERS Parser Issues (pkg/subsystem/linux/maintainers.go):

    • Never edit $KERNEL_PATH/MAINTAINERS to work around parsing errors. Fix the parser in maintainers.go and add a unit test in maintainers_test.go.

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 to notSubsystemEmails in rules.go.
  • Important Subsystems Lost: If a major subsystem disappeared from the hierarchy tree because its dedicated mailing list was removed in MAINTAINERS, add it to extraSubsystems in rules.go.
  • Custom Hierarchy Adjustments: Use addParents, noIndirectCc, and noReminders in rules.go when automatic parent inference or CC rules need manual overrides.

5. Testing and Committing

  1. Run Subsystem and Dashboard Tests:

    CI=true ./tools/syz-env go test ./pkg/subsystem/... ./dashboard/app/...
    
  2. Commit Conventions:

    • Separate any parser/logic changes in pkg/subsystem/ or tools/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 like pkg/subsystem: regenerate Linux subsystems and mention the target kernel tag (e.g., v6.19-rc6).

04 同仓库更多 Skills