docs: add generated tutorial compatibility matrix (#212)

* docs: declare tutorial compatibility requirements * docs: generate tutorial compatibility matrix * fix: correct BPF Arena minimum kernel * refactor: simplify compatibility validation --------- Co-authored-by: LinuxDev9002 <i@littlefisher.me>
2026-10-28 19:24:04 +08:00 · 2026-07-14 05:00:48 -07:00
parent e08f604769
commit 37375ff87e
78 changed files with 1167 additions and 13 deletions
--- a/.github/workflows/auto-generate-docs.yml
+++ b/.github/workflows/auto-generate-docs.yml
@@ -8,6 +8,7 @@ on:
      - 'src/**/README.zh.md'
      - 'src/**/.config'
      - 'scripts/generate_toc.py'
+      - 'scripts/generate_compatibility.py'
      - 'scripts/*.template'
  workflow_dispatch:

@@ -33,6 +34,7 @@ jobs:
      - name: Generate documentation
        run: |
          python3 scripts/generate_toc.py
+          python3 scripts/generate_compatibility.py

      - name: Check for changes
        id: check_changes
@@ -44,6 +46,6 @@ jobs:
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
-          git add README.md README.zh.md src/SUMMARY.md src/SUMMARY.zh.md
+          git add README.md README.zh.md src/SUMMARY.md src/SUMMARY.zh.md src/compatibility.md src/compatibility.zh.md
          git commit -m "docs: auto-generate documentation"
          git push
--- a/.github/workflows/check-docs.yml
+++ b/.github/workflows/check-docs.yml
@@ -14,10 +14,12 @@ jobs:
    steps:
      - uses: actions/checkout@v7
      - name: Test documentation scripts
-        run: python3 -m unittest scripts.test_check_internal_links scripts.test_generate_toc
+        run: python3 -m unittest scripts.test_check_internal_links scripts.test_generate_toc scripts.test_generate_compatibility
      - name: Regenerate documentation indexes
-        run: python3 scripts/generate_toc.py
+        run: |
+          python3 scripts/generate_toc.py
+          python3 scripts/generate_compatibility.py
      - name: Verify generated documentation is current
-        run: git diff --exit-code -- README.md README.zh.md src/SUMMARY.md src/SUMMARY.zh.md
+        run: git diff --exit-code -- README.md README.zh.md src/SUMMARY.md src/SUMMARY.zh.md src/compatibility.md src/compatibility.zh.md
      - name: Check relative Markdown links
        run: python3 scripts/check_internal_links.py
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@ The tutorial focuses on eBPF examples in observability, networking, security, an

 ## Table of Contents

+- [Tutorial compatibility matrix](src/compatibility.md)
+
 ### Getting Started Examples

 This section contains simple eBPF program examples and introductions. It primarily utilizes the `eunomia-bpf` framework to simplify development and introduces the basic usage and development process of eBPF.
--- a/README.zh.md
+++ b/README.zh.md
@@ -16,6 +16,8 @@

 ## 目录

+- [教程兼容性矩阵](src/compatibility.zh.md)
+
 ### 入门示例

 这一部分包含简单的 eBPF 程序示例和介绍。主要利用 `eunomia-bpf` 框架简化开发，介绍 eBPF 的基本用法和开发流程。
--- a/scripts/generate_compatibility.py
+++ b/scripts/generate_compatibility.py
@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""Validate tutorial compatibility metadata and generate compatibility tables."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+REQUIRED_FIELDS = (
+    "kernel_min",
+    "kernel_min_basis",
+    "architectures",
+    "btf",
+    "kernel_config",
+    "hardware",
+    "root",
+    "test_status",
+)
+ARCHITECTURES = {"all", "x86_64", "arm64"}
+BTF_VALUES = {"required", "optional", "not-required"}
+ROOT_VALUES = {"required", "not-required"}
+TEST_STATUSES = {"ci-runtime", "ci-build", "not-in-ci", "docs-only"}
+KERNEL_BASES = {
+    "documented",
+    "required-feature",
+    "repository-baseline",
+    "unverified",
+    "not-applicable",
+}
+HARDWARE_VALUES = {
+    "none",
+    "android-device-or-emulator",
+    "block-device",
+    "drm-gpu",
+    "gpu",
+    "intel-npu",
+    "network-interface",
+    "nvidia-cuda-gpu",
+}
+KERNEL_VERSION = re.compile(r"^\d+\.\d+$")
+ARCH_KERNEL_VERSION = re.compile(r"^(x86_64|arm64):\d+\.\d+$")
+KERNEL_CONFIG = re.compile(r"^CONFIG_[A-Z0-9_]+=(?:y|m|y\|m)$")
+REPOSITORY_BASELINE = "4.8"
+
+
+def sort_key(path: Path) -> tuple:
+    """Match the natural ordering used by the tutorial indexes."""
+    relative = path.parent.as_posix()
+    numbers = tuple(map(int, re.findall(r"\d+", relative)))
+    return (0, numbers, relative) if numbers else (1, (), relative)
+
+
+def parse_config(path: Path) -> dict[str, str]:
+    metadata: dict[str, str] = {}
+    for line_number, raw_line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise ValueError(f"{path}:{line_number}: expected key=value")
+        key, value = line.split("=", 1)
+        if key in metadata:
+            raise ValueError(f"{path}:{line_number}: duplicate field {key}")
+        metadata[key] = value
+    return metadata
+
+
+def _csv(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",")]
+
+
+def _validate_architectures(path: Path, value: str) -> list[str]:
+    architectures = _csv(value)
+    if (
+        not architectures
+        or len(architectures) != len(set(architectures))
+        or not set(architectures) <= ARCHITECTURES
+        or ("all" in architectures and len(architectures) != 1)
+    ):
+        raise ValueError(f"{path}: invalid architectures={value}")
+    return architectures
+
+
+def _validate_per_arch_kernel(path: Path, value: str, architectures: list[str]) -> None:
+    per_arch = _csv(value)
+    per_arch_names = [item.split(":", 1)[0] for item in per_arch]
+    valid = (
+        per_arch
+        and all(ARCH_KERNEL_VERSION.fullmatch(item) for item in per_arch)
+        and len(per_arch_names) == len(set(per_arch_names))
+        and set(per_arch_names) == set(architectures)
+    )
+    if not valid:
+        raise ValueError(f"{path}: invalid kernel_min={value}")
+
+
+def _validate_kernel(path: Path, kernel_min: str, basis: str, architectures: list[str]) -> None:
+    special_values = {"not-applicable", "unknown"}
+    if kernel_min not in special_values and not KERNEL_VERSION.fullmatch(kernel_min):
+        _validate_per_arch_kernel(path, kernel_min, architectures)
+    if basis not in KERNEL_BASES:
+        raise ValueError(f"{path}: invalid kernel_min_basis={basis}")
+    if (kernel_min == "not-applicable") != (basis == "not-applicable"):
+        raise ValueError(f"{path}: kernel_min and kernel_min_basis disagree")
+    if (kernel_min == "unknown") != (basis == "unverified"):
+        raise ValueError(f"{path}: unknown kernel_min must use an unverified basis")
+    if basis == "repository-baseline" and kernel_min != REPOSITORY_BASELINE:
+        raise ValueError(
+            f"{path}: repository-baseline must be {REPOSITORY_BASELINE}, got {kernel_min}"
+        )
+
+
+def _validate_choice(path: Path, field: str, value: str, allowed: set[str]) -> None:
+    if value not in allowed:
+        raise ValueError(f"{path}: invalid {field}={value}")
+
+
+def _validate_kernel_config(path: Path, metadata: dict[str, str]) -> None:
+    value = metadata["kernel_config"]
+    configs = _csv(value)
+    if value != "none" and (
+        not configs
+        or len(configs) != len(set(configs))
+        or not all(KERNEL_CONFIG.fullmatch(item) for item in configs)
+    ):
+        raise ValueError(f"{path}: invalid kernel_config={value}")
+    if metadata["btf"] == "required" and "CONFIG_DEBUG_INFO_BTF=y" not in configs:
+        raise ValueError(f"{path}: btf=required needs CONFIG_DEBUG_INFO_BTF=y")
+    if metadata["kernel_min"] != "not-applicable" and not {
+        "CONFIG_BPF=y",
+        "CONFIG_BPF_SYSCALL=y",
+    } <= set(configs):
+        raise ValueError(f"{path}: runnable tutorials need CONFIG_BPF=y and CONFIG_BPF_SYSCALL=y")
+
+
+def _validate_docs_only(path: Path, metadata: dict[str, str]) -> None:
+    is_not_applicable = metadata["kernel_min"] == "not-applicable"
+    if is_not_applicable != (metadata["test_status"] == "docs-only"):
+        raise ValueError(f"{path}: docs-only status and not-applicable kernel must agree")
+    defaults = {
+        "kernel_min_basis": "not-applicable",
+        "architectures": "all",
+        "btf": "not-required",
+        "kernel_config": "none",
+        "hardware": "none",
+        "root": "not-required",
+        "test_status": "docs-only",
+    }
+    if is_not_applicable and any(metadata[field] != value for field, value in defaults.items()):
+        raise ValueError(f"{path}: not-applicable tutorials must use docs-only defaults")
+
+
+def validate_metadata(path: Path, metadata: dict[str, str]) -> None:
+    missing = [field for field in REQUIRED_FIELDS if not metadata.get(field)]
+    if missing:
+        raise ValueError(f"{path}: missing required fields: {', '.join(missing)}")
+
+    architectures = _validate_architectures(path, metadata["architectures"])
+    _validate_kernel(
+        path, metadata["kernel_min"], metadata["kernel_min_basis"], architectures
+    )
+    _validate_choice(path, "btf", metadata["btf"], BTF_VALUES)
+    _validate_choice(path, "root", metadata["root"], ROOT_VALUES)
+    _validate_choice(path, "test_status", metadata["test_status"], TEST_STATUSES)
+    _validate_choice(path, "hardware", metadata["hardware"], HARDWARE_VALUES)
+    _validate_kernel_config(path, metadata)
+    _validate_docs_only(path, metadata)
+
+
+def _title(path: Path) -> str:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("#"):
+            return line.lstrip("#").strip()
+    raise ValueError(f"{path}: missing Markdown title")
+
+
+def collect_tutorials(src_dir: Path) -> list[dict[str, object]]:
+    tutorials = []
+    for config_path in sorted(
+        src_dir.rglob(".config"), key=lambda path: sort_key(path.relative_to(src_dir))
+    ):
+        metadata = parse_config(config_path)
+        validate_metadata(config_path, metadata)
+        lesson_dir = config_path.parent
+        english = lesson_dir / "README.md"
+        chinese = lesson_dir / "README.zh.md"
+        if not english.exists() or not chinese.exists():
+            raise ValueError(f"{lesson_dir}: both English and Chinese READMEs are required")
+        tutorials.append(
+            {
+                "relative": lesson_dir.relative_to(src_dir),
+                "title_en": _title(english),
+                "title_zh": _title(chinese),
+                "metadata": metadata,
+            }
+        )
+    return tutorials
+
+
+DISPLAY = {
+    "required": "Required",
+    "optional": "Optional",
+    "not-required": "Not required",
+    "not-applicable": "N/A",
+    "ci-runtime": "CI runtime",
+    "ci-build": "CI build",
+    "not-in-ci": "Not in CI",
+    "docs-only": "Docs only",
+    "none": "None",
+    "all": "All",
+    "documented": "Tutorial docs",
+    "required-feature": "Required feature",
+    "repository-baseline": "Repository baseline",
+    "unverified": "Unverified",
+    "unknown": "Unknown",
+    "android-device-or-emulator": "Android device or emulator",
+    "block-device": "Block device",
+    "drm-gpu": "DRM GPU",
+    "gpu": "GPU",
+    "intel-npu": "Intel NPU",
+    "network-interface": "Network interface",
+    "nvidia-cuda-gpu": "NVIDIA CUDA GPU",
+}
+DISPLAY_ZH = {
+    "required": "需要",
+    "optional": "可选",
+    "not-required": "不需要",
+    "not-applicable": "不适用",
+    "ci-runtime": "CI 运行测试",
+    "ci-build": "CI 构建测试",
+    "not-in-ci": "未纳入 CI",
+    "docs-only": "仅文档",
+    "none": "无",
+    "all": "全部",
+    "documented": "教程文档",
+    "required-feature": "必需特性",
+    "repository-baseline": "仓库基线",
+    "unverified": "尚未验证",
+    "unknown": "未知",
+    "android-device-or-emulator": "Android 设备或模拟器",
+    "block-device": "块设备",
+    "drm-gpu": "DRM GPU",
+    "gpu": "GPU",
+    "intel-npu": "Intel NPU",
+    "network-interface": "网络接口",
+    "nvidia-cuda-gpu": "NVIDIA CUDA GPU",
+}
+
+
+def _display(value: str, chinese: bool = False) -> str:
+    mapping = DISPLAY_ZH if chinese else DISPLAY
+    if "," in value:
+        return ", ".join(_display(item, chinese) for item in _csv(value))
+    return mapping.get(value, value.replace("-", " "))
+
+
+def render(tutorials: list[dict[str, object]], chinese: bool = False) -> str:
+    if chinese:
+        lines = [
+            "# 教程兼容性矩阵",
+            "",
+            "<!-- Generated by scripts/generate_compatibility.py; do not edit directly. -->",
+            "",
+            "本表由各教程的 `.config` 元数据生成。`最低内核` 表示教程按当前写法声明支持的最低版本；`依据` 标明该值来自教程文档、必需特性首次出现的版本，还是仓库声明的基线。`未纳入 CI` 不表示已做过手工验证。内核发行版可能禁用所列配置，因此版本号本身并不能保证兼容。",
+            "",
+            "| 教程 | 最低内核 | 依据 | 架构 | BTF | 核心内核配置 | 硬件 | Root | 测试状态 |",
+            "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+        ]
+    else:
+        lines = [
+            "# Tutorial compatibility matrix",
+            "",
+            "<!-- Generated by scripts/generate_compatibility.py; do not edit directly. -->",
+            "",
+            "This table is generated from each tutorial's `.config` metadata. `Minimum kernel` means the oldest kernel that the tutorial currently declares support for. `Basis` says whether that value comes from the tutorial documentation, the first version of a required feature, or the repository's declared baseline. `Not in CI` does not imply that a manual test was performed. Distribution kernels may disable a listed option, so a version number alone does not guarantee compatibility.",
+            "",
+            "| Tutorial | Minimum kernel | Basis | Architectures | BTF | Core kernel config | Hardware | Root | Test status |",
+            "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+        ]
+
+    for tutorial in tutorials:
+        relative = tutorial["relative"]
+        metadata = tutorial["metadata"]
+        assert isinstance(relative, Path)
+        assert isinstance(metadata, dict)
+        readme = "README.zh.md" if chinese else "README.md"
+        title_key = "title_zh" if chinese else "title_en"
+        title = str(tutorial[title_key]).replace("|", "\\|")
+        link = f"{relative.as_posix()}/{readme}"
+        values = [
+            metadata["kernel_min"],
+            metadata["kernel_min_basis"],
+            metadata["architectures"],
+            metadata["btf"],
+            metadata["kernel_config"],
+            metadata["hardware"],
+            metadata["root"],
+            metadata["test_status"],
+        ]
+        displayed = [_display(value, chinese).replace("|", "\\|") for value in values]
+        lines.append(f"| [{title}]({link}) | {' | '.join(displayed)} |")
+
+    lines.extend(["", "## Metadata fields" if not chinese else "## 元数据字段", ""])
+    if chinese:
+        lines.extend(
+            [
+                "- `kernel_min` 与 `kernel_min_basis`：教程声明的最低内核及其依据；按架构不同时使用 `架构:版本`。",
+                "- `architectures`：教程当前声明支持的架构。",
+                "- `btf` 与 `kernel_config`：BTF 要求以及各实现路径共有的核心内核选项；供应商或挂载点特有的条件请参阅对应教程。`y|m` 表示内建或模块均可。",
+                "- `hardware`：运行教程所需的专用硬件或环境；`none` 表示不需要专用硬件。",
+                "- `root`：运行教程是否需要 root 权限。",
+                "- `test_status`：`ci-runtime` 会在 CI 中实际运行，`ci-build` 仅验证构建，`not-in-ci` 表示没有 CI 证据，`docs-only` 表示纯文档。",
+                "",
+                "字段定义和允许值由 `scripts/generate_compatibility.py` 校验；修改教程要求时，请更新对应 `.config` 并重新运行生成脚本。",
+            ]
+        )
+    else:
+        lines.extend(
+            [
+                "- `kernel_min` and `kernel_min_basis`: the declared minimum kernel and its evidence basis; use `architecture:version` when architectures differ.",
+                "- `architectures`: architectures the tutorial currently declares support for.",
+                "- `btf` and `kernel_config`: the BTF requirement and core kernel options common to the implementation paths; see the tutorial for vendor- or hook-specific conditions. `y|m` means built in or loaded as a module.",
+                "- `hardware`: specialized hardware or environment required to run the tutorial; `none` means no specialized hardware.",
+                "- `root`: whether running the tutorial requires root privileges.",
+                "- `test_status`: `ci-runtime` executes in CI, `ci-build` checks only the build, `not-in-ci` means there is no CI evidence, and `docs-only` is documentation only.",
+                "",
+                "Field definitions and allowed values are validated by `scripts/generate_compatibility.py`. When a tutorial requirement changes, update its `.config` and rerun the generator.",
+            ]
+        )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def generate(project_root: Path, check: bool = False) -> None:
+    tutorials = collect_tutorials(project_root / "src")
+    outputs = {
+        project_root / "src" / "compatibility.md": render(tutorials),
+        project_root / "src" / "compatibility.zh.md": render(tutorials, chinese=True),
+    }
+    stale = []
+    for path, content in outputs.items():
+        if check:
+            if not path.exists() or path.read_text(encoding="utf-8") != content:
+                stale.append(path)
+        else:
+            path.write_text(content, encoding="utf-8")
+            print(f"Generated: {path}")
+    if stale:
+        names = ", ".join(str(path.relative_to(project_root)) for path in stale)
+        raise SystemExit(f"Generated compatibility documentation is stale: {names}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true", help="validate without rewriting files")
+    args = parser.parse_args()
+    generate(Path(__file__).resolve().parent.parent, check=args.check)
+
+
+if __name__ == "__main__":
+    main()
--- a/scripts/generate_toc.py
+++ b/scripts/generate_toc.py
@@ -3,7 +3,8 @@ import re

 # Define a function to walk through the directory and generate the TOC structure
 def generate_toc(base_dir, project_root, output_file_dir):
-    toc = "## Table of Contents\n\n"
+    compatibility = os.path.relpath(os.path.join(base_dir, "compatibility.md"), output_file_dir)
+    toc = f"## Table of Contents\n\n- [Tutorial compatibility matrix]({compatibility})\n\n"
    section_headers = {
        "Basic": "### Getting Started Examples\n\nThis section contains simple eBPF program examples and introductions. It primarily utilizes the `eunomia-bpf` framework to simplify development and introduces the basic usage and development process of eBPF.\n\n",
        "Advance": "### Advanced Documents and Examples\n\nWe start to build complete eBPF projects mainly based on `libbpf` and combine them with various application scenarios for practical use.\n\n",
@@ -135,7 +136,8 @@ def generate_toc(base_dir, project_root, output_file_dir):

 # Define a function to walk through the directory and generate the TOC structure in Chinese
 def generate_toc_cn(base_dir, project_root, output_file_dir):
-    toc = "## 目录\n\n"
+    compatibility = os.path.relpath(os.path.join(base_dir, "compatibility.zh.md"), output_file_dir)
+    toc = f"## 目录\n\n- [教程兼容性矩阵]({compatibility})\n\n"
    section_headers = {
        "Basic": "### 入门示例\n\n这一部分包含简单的 eBPF 程序示例和介绍。主要利用 `eunomia-bpf` 框架简化开发，介绍 eBPF 的基本用法和开发流程。\n\n",
        "Advance": "### 高级文档和示例\n\n我们开始构建完整的 eBPF 项目，主要基于 `libbpf`，并将其与各种应用场景结合起来，以便实际使用。\n\n",
--- a/scripts/test_generate_compatibility.py
+++ b/scripts/test_generate_compatibility.py
@@ -0,0 +1,129 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from scripts.generate_compatibility import (
+    REQUIRED_FIELDS,
+    collect_tutorials,
+    parse_config,
+    render,
+    validate_metadata,
+)
+
+
+class CompatibilityMetadataTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.project_root = Path(__file__).resolve().parent.parent
+        cls.tutorials = collect_tutorials(cls.project_root / "src")
+
+    def test_every_tutorial_has_valid_metadata(self):
+        config_paths = list((self.project_root / "src").rglob(".config"))
+        self.assertTrue(config_paths)
+        self.assertEqual(len(config_paths), len(self.tutorials))
+        for path in config_paths:
+            metadata = parse_config(path)
+            self.assertTrue(set(REQUIRED_FIELDS) <= set(metadata), path)
+
+    def test_bilingual_tables_contain_every_tutorial(self):
+        for chinese in (False, True):
+            table = render(self.tutorials, chinese=chinese)
+            self.assertEqual(len(self.tutorials), table.count("| ["))
+            for tutorial in self.tutorials:
+                readme = "README.zh.md" if chinese else "README.md"
+                expected = f"{tutorial['relative'].as_posix()}/{readme}"
+                self.assertIn(expected, table)
+
+    def test_missing_field_is_rejected(self):
+        metadata = {
+            "kernel_min": "5.15",
+            "kernel_min_basis": "required-feature",
+            "architectures": "x86_64",
+            "btf": "optional",
+            "kernel_config": "CONFIG_BPF=y",
+            "hardware": "none",
+            "root": "required",
+        }
+        with self.assertRaisesRegex(ValueError, "test_status"):
+            validate_metadata(Path("example/.config"), metadata)
+
+    def test_required_btf_config_is_enforced(self):
+        metadata = {
+            "kernel_min": "5.15",
+            "kernel_min_basis": "required-feature",
+            "architectures": "x86_64",
+            "btf": "required",
+            "kernel_config": "CONFIG_BPF=y",
+            "hardware": "none",
+            "root": "required",
+            "test_status": "not-in-ci",
+        }
+        with self.assertRaisesRegex(ValueError, "CONFIG_DEBUG_INFO_BTF"):
+            validate_metadata(Path("example/.config"), metadata)
+
+    def test_duplicate_config_field_is_rejected(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / ".config"
+            path.write_text("level=Basic\nlevel=Depth\n", encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "duplicate field level"):
+                parse_config(path)
+
+    def test_empty_csv_item_is_rejected(self):
+        metadata = {
+            "kernel_min": "5.15",
+            "kernel_min_basis": "repository-baseline",
+            "architectures": "x86_64,,arm64",
+            "btf": "optional",
+            "kernel_config": "CONFIG_BPF=y",
+            "hardware": "none",
+            "root": "required",
+            "test_status": "not-in-ci",
+        }
+        with self.assertRaisesRegex(ValueError, "architectures"):
+            validate_metadata(Path("example/.config"), metadata)
+
+    def test_per_arch_kernel_min_covers_all_architectures(self):
+        metadata = {
+            "kernel_min": "x86_64:5.5",
+            "kernel_min_basis": "documented",
+            "architectures": "x86_64,arm64",
+            "btf": "optional",
+            "kernel_config": "CONFIG_BPF=y",
+            "hardware": "none",
+            "root": "required",
+            "test_status": "not-in-ci",
+        }
+        with self.assertRaisesRegex(ValueError, "kernel_min"):
+            validate_metadata(Path("example/.config"), metadata)
+
+    def test_not_applicable_basis_requires_not_applicable_kernel(self):
+        metadata = {
+            "kernel_min": "5.15",
+            "kernel_min_basis": "not-applicable",
+            "architectures": "x86_64",
+            "btf": "optional",
+            "kernel_config": "CONFIG_BPF=y",
+            "hardware": "none",
+            "root": "required",
+            "test_status": "not-in-ci",
+        }
+        with self.assertRaisesRegex(ValueError, "disagree"):
+            validate_metadata(Path("example/.config"), metadata)
+
+    def test_repository_baseline_is_consistent(self):
+        metadata = {
+            "kernel_min": "5.15",
+            "kernel_min_basis": "repository-baseline",
+            "architectures": "x86_64",
+            "btf": "optional",
+            "kernel_config": "CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y",
+            "hardware": "none",
+            "root": "required",
+            "test_status": "not-in-ci",
+        }
+        with self.assertRaisesRegex(ValueError, "repository-baseline must be 4.8"):
+            validate_metadata(Path("example/.config"), metadata)
+
+
+if __name__ == "__main__":
+    unittest.main()
--- a/src/0-introduce/.config
+++ b/src/0-introduce/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=not-applicable
+kernel_min_basis=not-applicable
+architectures=all
+btf=not-required
+kernel_config=none
+hardware=none
+root=not-required
+test_status=docs-only
--- a/src/1-helloworld/.config
+++ b/src/1-helloworld/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=4.8
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=not-required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/10-hardirqs/.config
+++ b/src/10-hardirqs/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.5
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_CGROUPS=y,CONFIG_CGROUP_BPF=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/11-bootstrap/.config
+++ b/src/11-bootstrap/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/12-profile/.config
+++ b/src/12-profile/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_PERF_EVENTS=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/13-tcpconnlat/.config
+++ b/src/13-tcpconnlat/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_KPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/14-tcpstates/.config
+++ b/src/14-tcpstates/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.5
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE=y,CONFIG_TRACEPOINTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/15-javagc/.config
+++ b/src/15-javagc/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/16-memleak/.config
+++ b/src/16-memleak/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/17-biopattern/.config
+++ b/src/17-biopattern/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y
+hardware=block-device
+root=required
+test_status=ci-runtime
--- a/src/18-further-reading/.config
+++ b/src/18-further-reading/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=not-applicable
+kernel_min_basis=not-applicable
+architectures=all
+btf=not-required
+kernel_config=none
+hardware=none
+root=not-required
+test_status=docs-only
--- a/src/19-lsm-connect/.config
+++ b/src/19-lsm-connect/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.7
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_LSM=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/2-kprobe-unlink/.config
+++ b/src/2-kprobe-unlink/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_KPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/20-tc/.config
+++ b/src/20-tc/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_NET_CLS_BPF=y|m,CONFIG_NET_SCHED=y
+hardware=network-interface
+root=required
+test_status=ci-runtime
--- a/src/21-xdp/.config
+++ b/src/21-xdp/.config
@@ -1 +1,9 @@
 level=Advance
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=network-interface
+root=required
+test_status=not-in-ci
--- a/src/22-android/.config
+++ b/src/22-android/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Android
+kernel_min=5.15
+kernel_min_basis=documented
+architectures=x86_64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=android-device-or-emulator
+root=required
+test_status=not-in-ci
--- a/src/23-http/.config
+++ b/src/23-http/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=5.17
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/24-hide/.config
+++ b/src/24-hide/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/25-signal/.config
+++ b/src/25-signal/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/26-sudo/.config
+++ b/src/26-sudo/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/27-replace/.config
+++ b/src/27-replace/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.17
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/28-detach/.config
+++ b/src/28-detach/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/29-sockops/.config
+++ b/src/29-sockops/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_CGROUPS=y,CONFIG_CGROUP_BPF=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=network-interface
+root=required
+test_status=ci-build
--- a/src/3-fentry-unlink/.config
+++ b/src/3-fentry-unlink/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=x86_64:5.5,arm64:6.0
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_BPF_JIT=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/30-sslsniff/.config
+++ b/src/30-sslsniff/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/31-goroutine/.config
+++ b/src/31-goroutine/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/32-wallclock-profiler/.config
+++ b/src/32-wallclock-profiler/.config
@@ -1 +1,9 @@
 level=Depth
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_PERF_EVENTS=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/33-funclatency/.config
+++ b/src/33-funclatency/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_KPROBE_EVENTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/34-syscall/.config
+++ b/src/34-syscall/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Security
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/35-user-ringbuf/.config
+++ b/src/35-user-ringbuf/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=6.1
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/36-userspace-ebpf/.config
+++ b/src/36-userspace-ebpf/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=not-applicable
+kernel_min_basis=not-applicable
+architectures=all
+btf=not-required
+kernel_config=none
+hardware=none
+root=not-required
+test_status=docs-only
--- a/src/37-uprobe-rust/.config
+++ b/src/37-uprobe-rust/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64,arm64
+btf=not-required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/38-btf-uprobe/.config
+++ b/src/38-btf-uprobe/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/39-nginx/.config
+++ b/src/39-nginx/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64,arm64
+btf=not-required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/4-opensnoop/.config
+++ b/src/4-opensnoop/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64,arm64
+btf=not-required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/40-mysql/.config
+++ b/src/40-mysql/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64,arm64
+btf=not-required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/41-xdp-tcpdump/.config
+++ b/src/41-xdp-tcpdump/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=network-interface
+root=required
+test_status=ci-build
--- a/src/42-xdp-loadbalancer/.config
+++ b/src/42-xdp-loadbalancer/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=4.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y
+hardware=network-interface
+root=required
+test_status=ci-build
--- a/src/43-kfuncs/.config
+++ b/src/43-kfuncs/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=6.11
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_DEBUG_INFO_BTF_MODULES=y,CONFIG_KPROBE_EVENTS=y,CONFIG_MODULES=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/44-scx-simple/.config
+++ b/src/44-scx-simple/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Scheduler
+kernel_min=6.12
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_SCHED_CLASS_EXT=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/45-scx-nest/.config
+++ b/src/45-scx-nest/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Scheduler
+kernel_min=6.12
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_SCHED_CLASS_EXT=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/46-xdp-test/.config
+++ b/src/46-xdp-test/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=5.18
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_XDP_SOCKETS=y
+hardware=network-interface
+root=required
+test_status=ci-build
--- a/src/47-cuda-events/.config
+++ b/src/47-cuda-events/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=GPU
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=nvidia-cuda-gpu
+root=required
+test_status=not-in-ci
--- a/src/48-energy/.config
+++ b/src/48-energy/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Tracing
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/48-energy/README.md
+++ b/src/48-energy/README.md
@@ -315,7 +315,7 @@ static void print_stats(struct energy_monitor_bpf *skel)
 ### Prerequisites

 Before building, ensure you have:
- Linux kernel 5.4 or newer with BTF support
+- Linux kernel 5.8 or newer with BTF support (the eBPF monitor uses a BPF ring buffer)
 - libbpf development files
 - clang and llvm for eBPF compilation
 - Basic build tools (make, gcc)
--- a/src/48-energy/README.zh.md
+++ b/src/48-energy/README.zh.md
@@ -270,7 +270,7 @@ static void print_stats(struct energy_monitor_bpf *skel)

 ### 先决条件

-在构建之前，需要确保系统环境满足几个基本要求。首先需要 Linux 内核 5.4 或更新版本，且支持 BTF（BPF 类型格式）功能。其次要安装 libbpf 开发文件，这是 eBPF 程序开发的基础库。编译 eBPF 程序需要 clang 和 llvm 工具链。最后，还需要安装基本的构建工具，包括 make 和 gcc。
+在构建之前，需要确保系统环境满足几个基本要求。首先需要 Linux 内核 5.8 或更新版本（eBPF 监控器使用 BPF ring buffer），且支持 BTF（BPF 类型格式）功能。其次要安装 libbpf 开发文件，这是 eBPF 程序开发的基础库。编译 eBPF 程序需要 clang 和 llvm 工具链。最后，还需要安装基本的构建工具，包括 make 和 gcc。

 ### 编译

@@ -573,4 +573,4 @@ ls /sys/kernel/btf/vmlinux

 eBPF 的内核集成和高效事件处理的结合使其成为生产能源监控的理想选择。无论您是优化数据中心工作负载、延长移动设备的电池寿命，还是只是对应用程序的能源足迹感到好奇，eBPF 都提供了您进行详细分析所需的工具。

-随着生态系统的成熟，像 Kepler 这样的项目已经投入生产，cpufreq_ext 正在接近主线包含，我们正在进入一个能源感知计算成为默认而不是事后想法的时代。立即开始监控您的应用程序的能源消耗，为更可持续的计算未来做出贡献！
+随着生态系统的成熟，像 Kepler 这样的项目已经投入生产，cpufreq_ext 正在接近主线包含，我们正在进入一个能源感知计算成为默认而不是事后想法的时代。立即开始监控您的应用程序的能源消耗，为更可持续的计算未来做出贡献！
--- a/src/49-hid/.config
+++ b/src/49-hid/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Other
+kernel_min=6.3
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_HID_BPF=y,CONFIG_UHID=y|m
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/5-uprobe-bashreadline/.config
+++ b/src/5-uprobe-bashreadline/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_UPROBE_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/50-tcx/.config
+++ b/src/50-tcx/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Networking
+kernel_min=6.6
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_NET_XGRESS=y
+hardware=network-interface
+root=required
+test_status=ci-build
--- a/src/6-sigsnoop/.config
+++ b/src/6-sigsnoop/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/7-execsnoop/.config
+++ b/src/7-execsnoop/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE_SYSCALLS=y,CONFIG_PERF_EVENTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/8-exitsnoop/.config
+++ b/src/8-exitsnoop/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.8
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/9-runqlat/.config
+++ b/src/9-runqlat/.config
@@ -1 +1,9 @@
 level=Basic
+kernel_min=5.2
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_TRACEPOINTS=y
+hardware=none
+root=required
+test_status=ci-runtime
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -8,6 +8,8 @@ For the complete source code of the tutorial, please refer to the repo [https://

 ## Table of Contents

+- [Tutorial compatibility matrix](compatibility.md)
+
 ### Getting Started Examples

 This section contains simple eBPF program examples and introductions. It primarily utilizes the `eunomia-bpf` framework to simplify development and introduces the basic usage and development process of eBPF.
--- a/src/SUMMARY.zh.md
+++ b/src/SUMMARY.zh.md
@@ -8,6 +8,8 @@

 ## 目录

+- [教程兼容性矩阵](compatibility.zh.md)
+
 ### 入门示例

 这一部分包含简单的 eBPF 程序示例和介绍。主要利用 `eunomia-bpf` 框架简化开发，介绍 eBPF 的基本用法和开发流程。
--- a/src/cgroup/.config
+++ b/src/cgroup/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Other
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_CGROUPS=y,CONFIG_CGROUP_BPF=y,CONFIG_CGROUP_DEVICE=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/cgroup/README.md
+++ b/src/cgroup/README.md
@@ -602,4 +602,4 @@ This "policy guard" pattern can be extended to production use cases: container n
 - **eBPF docs:** [CGROUP_SYSCTL](https://docs.ebpf.io/linux/program-type/BPF_PROG_TYPE_CGROUP_SYSCTL/) - sysctl access control explained
 - **Tutorial repository:** <https://github.com/eunomia-bpf/bpf-developer-tutorial/tree/main/src/cgroup>

-Full source code is available in the tutorial repository. Requires Linux kernel 4.10+ (cgroup v2) and libbpf.
+Full source code is available in the tutorial repository. This implementation requires Linux kernel 5.8+ for BPF ring buffer event reporting, cgroup v2, and libbpf.
--- a/src/cgroup/README.zh.md
+++ b/src/cgroup/README.zh.md
@@ -603,4 +603,4 @@ cgroup eBPF 通过将策略与进程组绑定，解决了传统全局策略无
 - **eBPF 文档：** [CGROUP_SYSCTL](https://docs.ebpf.io/linux/program-type/BPF_PROG_TYPE_CGROUP_SYSCTL/) - sysctl 访问控制详解
 - **教程仓库：** <https://github.com/eunomia-bpf/bpf-developer-tutorial/tree/main/src/cgroup>

-完整源代码可在教程仓库中获得。需要 Linux 内核 4.10+（cgroup v2）和 libbpf。
+完整源代码可在教程仓库中获得。当前实现使用 BPF ring buffer 上报事件，因此需要 Linux 内核 5.8+、cgroup v2 和 libbpf。
--- a/src/compatibility.md
+++ b/src/compatibility.md
@@ -0,0 +1,80 @@
+# Tutorial compatibility matrix
+
+<!-- Generated by scripts/generate_compatibility.py; do not edit directly. -->
+
+This table is generated from each tutorial's `.config` metadata. `Minimum kernel` means the oldest kernel that the tutorial currently declares support for. `Basis` says whether that value comes from the tutorial documentation, the first version of a required feature, or the repository's declared baseline. `Not in CI` does not imply that a manual test was performed. Distribution kernels may disable a listed option, so a version number alone does not guarantee compatibility.
+
+| Tutorial | Minimum kernel | Basis | Architectures | BTF | Core kernel config | Hardware | Root | Test status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| [eBPF Tutorial by Example 0: Introduction to Core Concepts and Tools](0-introduce/README.md) | N/A | N/A | All | Not required | None | None | Not required | Docs only |
+| [eBPF Tutorial by Example 1: Hello World, Framework and Development](1-helloworld/README.md) | 4.8 | Tutorial docs | x86_64, arm64 | Not required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 2: Monitoring unlink System Calls with kprobe](2-kprobe-unlink/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_KPROBE_EVENTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 3: Monitoring unlink System Calls with fentry](3-fentry-unlink/README.md) | x86_64:5.5, arm64:6.0 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 4: Capturing Opening Files and Filter with Global Variables](4-opensnoop/README.md) | 4.8 | Repository baseline | x86_64, arm64 | Not required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 5: Capturing readline Function Calls with Uprobe](5-uprobe-bashreadline/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 6: Capturing Signal Sending and Store State with Hash Maps](6-sigsnoop/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 7: Capturing Process Execution, Output with perf event array](7-execsnoop/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y, CONFIG_PERF_EVENTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 8: Monitoring Process Exit Events, Output with Ring Buffer](8-exitsnoop/README.md) | 5.8 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 9: Capturing Scheduling Latency and Recording as Histogram](9-runqlat/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 10: Capturing Interrupts with hardirqs or softirqs](10-hardirqs/README.md) | 5.5 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 11: Develop User-Space Programs with libbpf and Trace exec() and exit()](11-bootstrap/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 12: Using eBPF Program Profile for Performance Analysis](12-profile/README.md) | 5.8 | Required feature | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_PERF_EVENTS=y | None | Required | CI build |
+| [eBPF Tutorial by Example 13: Statistics of TCP Connection Delay with libbpf](13-tcpconnlat/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_KPROBE_EVENTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 14: Recording TCP Connection Status and TCP RTT](14-tcpstates/README.md) | 5.5 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y, CONFIG_TRACEPOINTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 15: Capturing User-Space Java GC Duration Using USDT](15-javagc/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | None | Required | Not in CI |
+| [eBPF Tutorial by Example 16: Monitoring Memory Leaks](16-memleak/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI runtime |
+| [eBPF Tutorial by Example 17: Count Random/Sequential Disk I/O](17-biopattern/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | Block device | Required | CI runtime |
+| [More Reference Materials： papers, projects](18-further-reading/README.md) | N/A | N/A | All | Not required | None | None | Not required | Docs only |
+| [eBPF Tutorial by Example 19: Security Detection and Defense using LSM](19-lsm-connect/README.md) | 5.7 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_LSM=y, CONFIG_DEBUG_INFO_BTF=y | None | Required | Not in CI |
+| [eBPF Tutorial by Example 20: tc Traffic Control](20-tc/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_NET_CLS_BPF=y\|m, CONFIG_NET_SCHED=y | Network interface | Required | CI runtime |
+| [eBPF Tutorial by Example 21: Programmable Packet Processing with XDP](21-xdp/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | Network interface | Required | Not in CI |
+| [eBPF Tutorial by Example: Using eBPF Programs on Android](22-android/README.md) | 5.15 | Tutorial docs | x86_64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | Android device or emulator | Required | Not in CI |
+| [L7 Tracing with eBPF: HTTP and Beyond via Socket Filters and Syscall Tracepoints](23-http/README.md) | 5.17 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Practical Tutorial: Hiding Process or File Information](24-hide/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | Not in CI |
+| [Using bpf_send_signal to Terminate Malicious Processes in eBPF](25-signal/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Tutorial: Privilege Escalation via File Content Manipulation](26-sudo/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | Not in CI |
+| [eBPF Tutorial: Transparent Text Replacement in File Reads](27-replace/README.md) | 5.17 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | Not in CI |
+| [Running eBPF After Application Exits: The Lifecycle of eBPF Programs](28-detach/README.md) | 5.8 | Required feature | x86_64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | None | Required | CI build |
+| [eBPF Development Practices: Accelerating Network Request Forwarding with Sockops](29-sockops/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_DEBUG_INFO_BTF=y | Network interface | Required | CI build |
+| [eBPF Practical Tutorial: Capturing SSL/TLS Plain Text Data Using uprobe](30-sslsniff/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI runtime |
+| [eBPF Practical Tutorial: Using eBPF to Trace Go Routine States](31-goroutine/README.md) | 5.2 | Required feature | x86_64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI build |
+| [eBPF Tutorial by Example 32: Wall Clock Profiling with Combined On-CPU and Off-CPU Analysis](32-wallclock-profiler/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_PERF_EVENTS=y | None | Required | CI build |
+| [Measuring Function Latency with eBPF](33-funclatency/README.md) | 4.8 | Repository baseline | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_KPROBE_EVENTS=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI build |
+| [eBPF Development Practice: Modifying System Call Arguments with eBPF](34-syscall/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [eBPF Development Practices: Asynchronously Send to Kernel with User Ring Buffer](35-user-ringbuf/README.md) | 6.1 | Tutorial docs | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | None | Required | CI runtime |
+| [Userspace eBPF Runtimes: Overview and Applications](36-userspace-ebpf/README.md) | N/A | N/A | All | Not required | None | None | Not required | Docs only |
+| [eBPF Practice: Tracing User Space Rust Applications with Uprobe](37-uprobe-rust/README.md) | 4.8 | Repository baseline | x86_64, arm64 | Not required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | None | Required | CI runtime |
+| [Expanding eBPF Compile Once, Run Everywhere(CO-RE) to Userspace Compatibility](38-btf-uprobe/README.md) | 5.2 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | None | Required | Not in CI |
+| [Using eBPF to Trace Nginx Requests](39-nginx/README.md) | 4.8 | Repository baseline | x86_64, arm64 | Not required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | None | Required | Not in CI |
+| [Using eBPF to Trace MySQL Queries](40-mysql/README.md) | 4.8 | Repository baseline | x86_64, arm64 | Not required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | None | Required | Not in CI |
+| [eBPF Tutorial by Example: Capturing TCP Information with XDP](41-xdp-tcpdump/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | Network interface | Required | CI build |
+| [eBPF Developer Tutorial: XDP Load Balancer](42-xdp-loadbalancer/README.md) | 4.8 | Required feature | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y | Network interface | Required | CI build |
+| [Extending eBPF Beyond Its Limits: Custom kfuncs in Kernel Modules](43-kfuncs/README.md) | 6.11 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_DEBUG_INFO_BTF_MODULES=y, CONFIG_KPROBE_EVENTS=y, CONFIG_MODULES=y | None | Required | CI build |
+| [eBPF Tutorial: Introduction to the BPF Scheduler](44-scx-simple/README.md) | 6.12 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_SCHED_CLASS_EXT=y | None | Required | CI build |
+| [eBPF Tutorial by Example: Implementing the `scx_nest` Scheduler](45-scx-nest/README.md) | 6.12 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_SCHED_CLASS_EXT=y | None | Required | CI build |
+| [eBPF Tutorial by Example: Building a High-Performance XDP Packet Generator](46-xdp-test/README.md) | 5.18 | Tutorial docs | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_XDP_SOCKETS=y | Network interface | Required | CI build |
+| [eBPF Tutorial: Tracing CUDA GPU Operations](47-cuda-events/README.md) | 5.8 | Required feature | x86_64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | NVIDIA CUDA GPU | Required | Not in CI |
+| [eBPF Tutorial: Energy Monitoring for Process-Level Power Analysis](48-energy/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | None | Required | Not in CI |
+| [eBPF Tutorial: Fixing Broken HID Devices Without Kernel Patches](49-hid/README.md) | 6.3 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_HID_BPF=y, CONFIG_UHID=y\|m | None | Required | Not in CI |
+| [eBPF Tutorial by Example 50: Composable Traffic Control with TCX Links](50-tcx/README.md) | 6.6 | Tutorial docs | x86_64, arm64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_NET_XGRESS=y | Network interface | Required | CI build |
+| [eBPF Tutorial: cgroup-based Policy Control](cgroup/README.md) | 5.8 | Required feature | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_CGROUP_DEVICE=y, CONFIG_DEBUG_INFO_BTF=y | None | Required | Not in CI |
+| [eBPF Tutorial by Example: BPF Arena for Zero-Copy Shared Memory](features/bpf_arena/README.md) | 6.9 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y | None | Required | CI build |
+| [eBPF Tutorial: BPF Iterators for Kernel Data Export](features/bpf_iters/README.md) | 5.8 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | None | Required | CI build |
+| [eBPF Tutorial by Example: BPF Token for Delegated Privilege and Secure Program Loading](features/bpf_token/README.md) | 6.9 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_USER_NS=y | None | Required | CI build |
+| [eBPF Tutorial: BPF Workqueues for Asynchronous Sleepable Tasks](features/bpf_wq/README.md) | 6.10 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | None | Required | CI build |
+| [eBPF Tutorial by Example: BPF Dynamic Pointers for Variable-Length Data](features/dynptr/README.md) | 6.4 | Tutorial docs | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_NET_CLS_BPF=y\|m, CONFIG_NET_SCHED=y | Network interface | Required | Not in CI |
+| [eBPF Tutorial: Extending Kernel Subsystems with BPF struct_ops](features/struct_ops/README.md) | Unknown | Unverified | x86_64, arm64 | Required | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_DEBUG_INFO_BTF_MODULES=y, CONFIG_MODULES=y | None | Required | Not in CI |
+| [eBPF by Example: Building a GPU Flamegraph Profiler with CUPTI](xpu/flamegraph/README.md) | 5.8 | Required feature | x86_64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_PERF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | NVIDIA CUDA GPU | Required | Not in CI |
+| [eBPF Tutorial by Example: Monitoring GPU Driver Activity with Kernel Tracepoints](xpu/gpu-kernel-driver/README.md) | 4.8 | Repository baseline | x86_64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y | GPU | Required | Not in CI |
+| [eBPF Tutorial by Example: Tracing Intel NPU Kernel Driver Operations](xpu/npu-kernel-driver/README.md) | 6.2 | Tutorial docs | x86_64 | Optional | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DRM_ACCEL=y, CONFIG_DRM_ACCEL_IVPU=y\|m, CONFIG_TRACEPOINTS=y | Intel NPU | Required | Not in CI |
+
+## Metadata fields
+
+- `kernel_min` and `kernel_min_basis`: the declared minimum kernel and its evidence basis; use `architecture:version` when architectures differ.
+- `architectures`: architectures the tutorial currently declares support for.
+- `btf` and `kernel_config`: the BTF requirement and core kernel options common to the implementation paths; see the tutorial for vendor- or hook-specific conditions. `y|m` means built in or loaded as a module.
+- `hardware`: specialized hardware or environment required to run the tutorial; `none` means no specialized hardware.
+- `root`: whether running the tutorial requires root privileges.
+- `test_status`: `ci-runtime` executes in CI, `ci-build` checks only the build, `not-in-ci` means there is no CI evidence, and `docs-only` is documentation only.
+
+Field definitions and allowed values are validated by `scripts/generate_compatibility.py`. When a tutorial requirement changes, update its `.config` and rerun the generator.
--- a/src/compatibility.zh.md
+++ b/src/compatibility.zh.md
@@ -0,0 +1,80 @@
+# 教程兼容性矩阵
+
+<!-- Generated by scripts/generate_compatibility.py; do not edit directly. -->
+
+本表由各教程的 `.config` 元数据生成。`最低内核` 表示教程按当前写法声明支持的最低版本；`依据` 标明该值来自教程文档、必需特性首次出现的版本，还是仓库声明的基线。`未纳入 CI` 不表示已做过手工验证。内核发行版可能禁用所列配置，因此版本号本身并不能保证兼容。
+
+| 教程 | 最低内核 | 依据 | 架构 | BTF | 核心内核配置 | 硬件 | Root | 测试状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| [eBPF 示例教程 0：核心概念与工具简介](0-introduce/README.zh.md) | 不适用 | 不适用 | 全部 | 不需要 | 无 | 无 | 不需要 | 仅文档 |
+| [eBPF 入门开发实践教程一：Hello World，基本框架和开发流程](1-helloworld/README.zh.md) | 4.8 | 教程文档 | x86_64, arm64 | 不需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程二：在 eBPF 中使用 kprobe 监测捕获 unlink 系统调用](2-kprobe-unlink/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_KPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程三：在 eBPF 中使用 fentry 监测捕获 unlink 系统调用](3-fentry-unlink/README.zh.md) | x86_64:5.5, arm64:6.0 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程四：在 eBPF 中捕获进程打开文件的系统调用集合，使用全局变量过滤进程 pid](4-opensnoop/README.zh.md) | 4.8 | 仓库基线 | x86_64, arm64 | 不需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程五：在 eBPF 中使用  uprobe 捕获 bash 的 readline 函数调用](5-uprobe-bashreadline/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程六：捕获进程发送信号的系统调用集合，使用 hash map 保存状态](6-sigsnoop/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门实践教程七：捕获进程执行事件，通过 perf event array 向用户态打印输出](7-execsnoop/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y, CONFIG_PERF_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程八：在 eBPF 中使用 exitsnoop 监控进程退出事件，使用 ring buffer 向用户态打印输出](8-exitsnoop/README.zh.md) | 5.8 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程九：捕获进程调度延迟，以直方图方式记录](9-runqlat/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程十：在 eBPF 中使用 hardirqs 或 softirqs 捕获中断事件](10-hardirqs/README.zh.md) | 5.5 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门开发实践教程十一：在 eBPF 中使用 libbpf 开发用户态程序并跟踪 exec() 和 exit() 系统调用](11-bootstrap/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门实践教程十二：使用 eBPF 程序 profile 进行性能分析](12-profile/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_PERF_EVENTS=y | 无 | 需要 | CI 构建测试 |
+| [eBPF入门开发实践教程十三：统计 TCP 连接延时，并使用 libbpf 在用户态处理数据](13-tcpconnlat/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_KPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF入门实践教程十四：记录 TCP 连接状态与 TCP RTT](14-tcpstates/README.zh.md) | 5.5 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y, CONFIG_TRACEPOINTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门实践教程十五：使用 USDT 捕获用户态 Java GC 事件耗时](15-javagc/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 入门实践教程十六：编写 eBPF 程序 Memleak 监控内存泄漏](16-memleak/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 入门实践教程十七：编写 eBPF 程序统计随机/顺序磁盘 I/O](17-biopattern/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | 块设备 | 需要 | CI 运行测试 |
+| [更多的参考资料：论文、项目等等](18-further-reading/README.zh.md) | 不适用 | 不适用 | 全部 | 不需要 | 无 | 无 | 不需要 | 仅文档 |
+| [eBPF 入门实践教程：使用 LSM 进行安全检测防御](19-lsm-connect/README.zh.md) | 5.7 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_LSM=y, CONFIG_DEBUG_INFO_BTF=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 入门实践教程二十：使用 eBPF 进行 tc 流量控制](20-tc/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_NET_CLS_BPF=y\|m, CONFIG_NET_SCHED=y | 网络接口 | 需要 | CI 运行测试 |
+| [eBPF 入门实践教程二十一： 使用 XDP 进行可编程数据包处理](21-xdp/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | 网络接口 | 需要 | 未纳入 CI |
+| [在 Android 上使用 eBPF 程序](22-android/README.zh.md) | 5.15 | 教程文档 | x86_64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | Android 设备或模拟器 | 需要 | 未纳入 CI |
+| [通过 eBPF socket filter 或 syscall trace 追踪 HTTP 请求等七层协议 - eBPF 实践教程](23-http/README.zh.md) | 5.17 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 开发实践：使用 eBPF 隐藏进程或文件信息](24-hide/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 入门实践教程：用 bpf_send_signal 发送信号终止恶意进程](25-signal/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 教程: 文件操纵实现 sudo 权限提升](26-sudo/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 教程: 替换任意程序读取或者写入的文本](27-replace/README.zh.md) | 5.17 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | 未纳入 CI |
+| [在应用程序退出后运行 eBPF 程序：eBPF 程序的生命周期](28-detach/README.zh.md) | 5.8 | 必需特性 | x86_64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 开发实践：使用 sockops 加速网络请求转发](29-sockops/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_DEBUG_INFO_BTF=y | 网络接口 | 需要 | CI 构建测试 |
+| [eBPF 实践教程：使用 uprobe 捕获多种库的 SSL/TLS 明文数据](30-sslsniff/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF 实践教程：使用 eBPF 跟踪 Go 协程状态](31-goroutine/README.zh.md) | 5.2 | 必需特性 | x86_64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 开发实践教程：示例 32 - 结合 On-CPU 和 Off-CPU 分析的挂钟时间分析](32-wallclock-profiler/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_PERF_EVENTS=y | 无 | 需要 | CI 构建测试 |
+| [使用 eBPF 测量函数延迟](33-funclatency/README.zh.md) | 4.8 | 仓库基线 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_KPROBE_EVENTS=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 开发实践：使用 eBPF 修改系统调用参数](34-syscall/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [eBPF开发实践：使用 user ring buffer 向内核异步发送信息](35-user-ringbuf/README.zh.md) | 6.1 | 教程文档 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_FTRACE_SYSCALLS=y | 无 | 需要 | CI 运行测试 |
+| [用户空间 eBPF 运行时：深度解析与应用实践](36-userspace-ebpf/README.zh.md) | 不适用 | 不适用 | 全部 | 不需要 | 无 | 无 | 不需要 | 仅文档 |
+| [eBPF 实践：使用 Uprobe 追踪用户态 Rust 应用](37-uprobe-rust/README.zh.md) | 4.8 | 仓库基线 | x86_64, arm64 | 不需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | CI 运行测试 |
+| [借助 eBPF 和 BTF，让用户态也能一次编译、到处运行](38-btf-uprobe/README.zh.md) | 5.2 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | 未纳入 CI |
+| [使用 eBPF 跟踪 Nginx 请求](39-nginx/README.zh.md) | 4.8 | 仓库基线 | x86_64, arm64 | 不需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | 未纳入 CI |
+| [使用 eBPF 跟踪 MySQL 查询](40-mysql/README.zh.md) | 4.8 | 仓库基线 | x86_64, arm64 | 不需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 示例教程：使用 XDP 捕获 TCP 信息](41-xdp-tcpdump/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | 网络接口 | 需要 | CI 构建测试 |
+| [eBPF 开发者教程： 简单的 XDP 负载均衡器](42-xdp-loadbalancer/README.zh.md) | 4.8 | 必需特性 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y | 网络接口 | 需要 | CI 构建测试 |
+| [超越 eBPF 的极限：在内核模块中定义自定义 kfunc](43-kfuncs/README.zh.md) | 6.11 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_DEBUG_INFO_BTF_MODULES=y, CONFIG_KPROBE_EVENTS=y, CONFIG_MODULES=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 教程：BPF 调度器入门](44-scx-simple/README.zh.md) | 6.12 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_SCHED_CLASS_EXT=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 示例教程：实现 `scx_nest` 调度器](45-scx-nest/README.zh.md) | 6.12 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_SCHED_CLASS_EXT=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 实例教程：构建高性能 XDP 数据包生成器](46-xdp-test/README.zh.md) | 5.18 | 教程文档 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_XDP_SOCKETS=y | 网络接口 | 需要 | CI 构建测试 |
+| [eBPF 教程：追踪 CUDA GPU 操作](47-cuda-events/README.zh.md) | 5.8 | 必需特性 | x86_64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_UPROBE_EVENTS=y | NVIDIA CUDA GPU | 需要 | 未纳入 CI |
+| [eBPF 教程：进程级能源监控与功耗分析](48-energy/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_TRACEPOINTS=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 教程：无需内核补丁修复故障的 HID 设备](49-hid/README.zh.md) | 6.3 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_HID_BPF=y, CONFIG_UHID=y\|m | 无 | 需要 | 未纳入 CI |
+| [eBPF 入门实践教程第五十篇：使用 TCX Link 实现可组合的流量控制](50-tcx/README.zh.md) | 6.6 | 教程文档 | x86_64, arm64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_NET_XGRESS=y | 网络接口 | 需要 | CI 构建测试 |
+| [eBPF 实例教程：基于 cgroup 的策略控制](cgroup/README.zh.md) | 5.8 | 必需特性 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_CGROUPS=y, CONFIG_CGROUP_BPF=y, CONFIG_CGROUP_DEVICE=y, CONFIG_DEBUG_INFO_BTF=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 实例教程：BPF Arena 零拷贝共享内存](features/bpf_arena/README.zh.md) | 6.9 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 教程：BPF 迭代器用于内核数据导出](features/bpf_iters/README.zh.md) | 5.8 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 入门实践教程：BPF Token，安全的委托式权限与程序加载](features/bpf_token/README.zh.md) | 6.9 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_USER_NS=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 教程：BPF 工作队列用于异步可睡眠任务](features/bpf_wq/README.zh.md) | 6.10 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_FTRACE=y | 无 | 需要 | CI 构建测试 |
+| [eBPF 实例教程：BPF 动态指针处理可变长度数据](features/dynptr/README.zh.md) | 6.4 | 教程文档 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_NET_CLS_BPF=y\|m, CONFIG_NET_SCHED=y | 网络接口 | 需要 | 未纳入 CI |
+| [eBPF 教程：使用 BPF struct_ops 扩展内核子系统](features/struct_ops/README.zh.md) | 未知 | 尚未验证 | x86_64, arm64 | 需要 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_JIT=y, CONFIG_DEBUG_INFO_BTF=y, CONFIG_DEBUG_INFO_BTF_MODULES=y, CONFIG_MODULES=y | 无 | 需要 | 未纳入 CI |
+| [eBPF 示例：使用 CUPTI 构建 GPU 火焰图分析器](xpu/flamegraph/README.zh.md) | 5.8 | 必需特性 | x86_64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_PERF_EVENTS=y, CONFIG_UPROBE_EVENTS=y | NVIDIA CUDA GPU | 需要 | 未纳入 CI |
+| [eBPF 实例教程：使用内核跟踪点监控 GPU 驱动活动](xpu/gpu-kernel-driver/README.zh.md) | 4.8 | 仓库基线 | x86_64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y | GPU | 需要 | 未纳入 CI |
+| [eBPF 实例教程：跟踪 Intel NPU 内核驱动操作](xpu/npu-kernel-driver/README.zh.md) | 6.2 | 教程文档 | x86_64 | 可选 | CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y, CONFIG_BPF_EVENTS=y, CONFIG_DRM_ACCEL=y, CONFIG_DRM_ACCEL_IVPU=y\|m, CONFIG_TRACEPOINTS=y | Intel NPU | 需要 | 未纳入 CI |
+
+## 元数据字段
+
+- `kernel_min` 与 `kernel_min_basis`：教程声明的最低内核及其依据；按架构不同时使用 `架构:版本`。
+- `architectures`：教程当前声明支持的架构。
+- `btf` 与 `kernel_config`：BTF 要求以及各实现路径共有的核心内核选项；供应商或挂载点特有的条件请参阅对应教程。`y|m` 表示内建或模块均可。
+- `hardware`：运行教程所需的专用硬件或环境；`none` 表示不需要专用硬件。
+- `root`：运行教程是否需要 root 权限。
+- `test_status`：`ci-runtime` 会在 CI 中实际运行，`ci-build` 仅验证构建，`not-in-ci` 表示没有 CI 证据，`docs-only` 表示纯文档。
+
+字段定义和允许值由 `scripts/generate_compatibility.py` 校验；修改教程要求时，请更新对应 `.config` 并重新运行生成脚本。
--- a/src/features/bpf_arena/.config
+++ b/src/features/bpf_arena/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=6.9
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_JIT=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/features/bpf_arena/README.md
+++ b/src/features/bpf_arena/README.md
@@ -359,4 +359,4 @@ Our linked list example demonstrates the core arena concepts: defining an arena
 - **Linux Kernel Source:** `kernel/bpf/arena.c` - Arena implementation
 - **LLVM Address Spaces:** Documentation on `__arena` compiler support

-This example is adapted from Meta's arena_list.c in the Linux kernel samples, with educational enhancements. Requires Linux kernel 6.10+ with `CONFIG_BPF_ARENA=y` enabled. Complete source code available in the tutorial repository.
+This example is adapted from Meta's arena_list.c in the Linux kernel samples, with educational enhancements. It requires Linux kernel 6.9+ with BPF JIT support (`CONFIG_BPF_JIT=y`). BPF arena is not controlled by a separate `CONFIG_BPF_ARENA` option. Complete source code is available in the tutorial repository.
--- a/src/features/bpf_arena/README.zh.md
+++ b/src/features/bpf_arena/README.zh.md
@@ -357,4 +357,4 @@ BPF Arena 通过提供稀疏共享内存解决了传统 BPF map 的根本限制
 - **Linux 内核源码：** `kernel/bpf/arena.c` - Arena 实现
 - **LLVM 地址空间：** 关于 `__arena` 编译器支持的文档

-此示例改编自 Linux 内核示例中 Meta 的 arena_list.c，并增加了教育性增强。需要 Linux 内核 6.10+ 并启用 `CONFIG_BPF_ARENA=y`。完整源代码可在教程仓库中获得。
+此示例改编自 Linux 内核示例中 Meta 的 arena_list.c，并增加了教育性增强。它需要 Linux 内核 6.9+ 并启用 BPF JIT（`CONFIG_BPF_JIT=y`）；BPF arena 并没有独立的 `CONFIG_BPF_ARENA` 选项。完整源代码可在教程仓库中获得。
--- a/src/features/bpf_iters/.config
+++ b/src/features/bpf_iters/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=5.8
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/features/bpf_token/.config
+++ b/src/features/bpf_token/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=6.9
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_USER_NS=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/features/bpf_wq/.config
+++ b/src/features/bpf_wq/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=6.10
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_BPF_JIT=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_FTRACE=y
+hardware=none
+root=required
+test_status=ci-build
--- a/src/features/dynptr/.config
+++ b/src/features/dynptr/.config
@@ -1,3 +1,11 @@
 level=Depth
 type=Features
 desc=BPF Dynamic Pointers for Variable-Length Data
+kernel_min=6.4
+kernel_min_basis=documented
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_NET_CLS_BPF=y|m,CONFIG_NET_SCHED=y
+hardware=network-interface
+root=required
+test_status=not-in-ci
--- a/src/features/struct_ops/.config
+++ b/src/features/struct_ops/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=Features
+kernel_min=unknown
+kernel_min_basis=unverified
+architectures=x86_64,arm64
+btf=required
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_JIT=y,CONFIG_DEBUG_INFO_BTF=y,CONFIG_DEBUG_INFO_BTF_MODULES=y,CONFIG_MODULES=y
+hardware=none
+root=required
+test_status=not-in-ci
--- a/src/xpu/flamegraph/.config
+++ b/src/xpu/flamegraph/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=GPU
+kernel_min=5.8
+kernel_min_basis=required-feature
+architectures=x86_64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_PERF_EVENTS=y,CONFIG_UPROBE_EVENTS=y
+hardware=nvidia-cuda-gpu
+root=required
+test_status=not-in-ci
--- a/src/xpu/gpu-kernel-driver/.config
+++ b/src/xpu/gpu-kernel-driver/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=GPU
+kernel_min=4.8
+kernel_min_basis=repository-baseline
+architectures=x86_64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y
+hardware=gpu
+root=required
+test_status=not-in-ci
--- a/src/xpu/npu-kernel-driver/.config
+++ b/src/xpu/npu-kernel-driver/.config
@@ -1,2 +1,10 @@
 level=Depth
 type=GPU
+kernel_min=6.2
+kernel_min_basis=documented
+architectures=x86_64
+btf=optional
+kernel_config=CONFIG_BPF=y,CONFIG_BPF_SYSCALL=y,CONFIG_BPF_EVENTS=y,CONFIG_DRM_ACCEL=y,CONFIG_DRM_ACCEL_IVPU=y|m,CONFIG_TRACEPOINTS=y
+hardware=intel-npu
+root=required
+test_status=not-in-ci