grtrace 开发迭代计划

本文最后更新于：2025年9月16日 下午

grtrace 开发迭代计划（Roadmap）

配套架构文档： GPU Ring Buffer追踪架构深度分析：从blktrace到grtrace的设计演进

语义化版本约定：

  • v0.x 为快速迭代期（可能发生不兼容变更）
  • v1.0 起承诺基本事件语义与文件格式的稳定性

里程碑总览

  • v0.1 MVP：内核最小可用路径（relay 通道 + 基础事件 + 单供应商单 ring）
  • v0.2 多 ring/引擎支持＋单机时钟一致性（ktime、seq）
  • v0.3 事件模型稳定化（提交/完成/ctx 切换/fence 等）
  • v0.4 用户态工具链（grtrace、最小分析脚本） （含阻塞点报告：per-job 指标与标签）
  • v0.5 性能与开销治理（背压、采样、开关策略、热路径审计）
  • v0.6 固化持久化文件格式（format_version=1，紧凑二进制 + METADATA）
  • v0.7 供应商适配（amdgpu、i915、nouveau 首批覆盖）
  • v0.8 与 ftrace/perf/eBPF 联动（时间轴对齐、跨域关联）
  • v0.9 稳定化（kselftest、自测基准、文档与示例）
  • v1.0 基线发布（接口/格式稳定、兼容性承诺）

v0.1 MVP（最小可用）

目标：跑通从驱动 hook → 内核 relay → debugfs 消费 → 简单用户态读取的闭环。

  • 内核
  • 用户态
  • 文档/CI
  • 验收
  • 代码开发量预估：800 行

v0.1 详细拆解（Sprint 1–2，执行清单）

  • 内核（drivers/gpu/grtrace/grtrace.c）
    • 基础骨架：模块注册/卸载、debugfs 根目录、relay 通道创建/关闭
      • 函数：grtrace_create_channel、grtrace_emit、grtrace_init/grtrace_exit
      • DoD：M=drivers/gpu/grtrace 可编译；/sys/kernel/debug/grtrace 存在
    • 事件与公共 API（最小集：SUBMIT/COMPLETE/CTX_SWITCH）
      • 结构：grtrace_event_hdr、各 payload 结构
      • 函数：grtrace_submit/complete/ctx_switch（导出符号）、grtrace_write_event（最简写入）
      • DoD：emit 三类事件后，relay 有数据可读
    • 控制与统计视图（最小）
      • debugfs：control（start/stop）、stats（文本）、emit（测试注入）
      • DoD：start→emit×3→stop 后，stats 显示 written=3
    • 估计 LOC：内核侧 ~600–700 行（含结构/视图/控制）
  • 用户态（tools/grtrace/）
    • 最小控制：start/stop/status；最小 reader：顺序读出、打印计数
    • DoD：一条命令可启动采集，另一条可读出并统计事件数
    • 估计 LOC：~100–150 行
  • 冒烟用例（人工步骤）
    1. 加载模块
    2. echo start > /sys/kernel/debug/grtrace/control
    3. echo "submit CTX ENG RING SEQ" > /sys/kernel/debug/grtrace/emit （重复 3 次）
    4. cat /sys/kernel/debug/grtrace/stats 并看到 written=3
    5. echo stop > /sys/kernel/debug/grtrace/control
  • 提交与度量
    • 用 -F 文件方式提交英文标题+空行+分点；标题仅 ASCII
    • 每日净增 ≥150 行；失败次日补足；每晚跑一次冒烟

【v0.1 DoD 检查表】

  • 代码：grtrace.c 可编译；control/stats/emit 可读写；relay 可写入
  • 文档：config/视图说明与示例命令已补充
  • 冒烟：start→emit×3→stop，stats written=3 截图/日志
  • 提交：英文/多行/分点，使用 -F 文件；标题 ASCII
  • 度量：git numstat 展示新增/删除/净增；本周累计≥800 行

v0.2 多 ring/引擎 + 时钟一致性

  • 内核
  • 用户态
  • 验收
  • 代码开发量预估：700 行

v0.2 详细拆解（Sprint 3–4）

  • 内核（grtrace.c）
    • 多引擎标注：engine_class/ring_id 贯穿 payload 与过滤
    • 全局时间/序列：ktime_get_ns + gseq/cseq（已具备基础，完善 wrap/race 处理）
    • 丢弃/水位：最小丢包计数与短写计数（writes_short/bytes_dropped）
    • DoD：同一 GPU 多 ring 事件可按 gseq 有序；stats 能显示丢弃计数
    • 预估 LOC：~350–400
  • 用户态（tools/grtrace）
    • ring/engine 过滤与简单聚合输出
    • DoD：命令行可指定 ring/engine 并统计行数
    • 预估 LOC：~200–250
  • 冒烟：双 ring 同时 emit，用户态按 ring 聚合计数

【v0.2 DoD 检查表】

  • 代码：engine_class/ring_id 全路径打通；gseq/cseq 正常递增
  • 文档：新增字段与过滤用法说明
  • 冒烟：两 ring 并发，按 ring 计数一致
  • 提交：多行英文；包含 before/after 行为说明
  • 度量：本期净增 ≥700 行

实施任务（文件/函数/键）

  • 内核（drivers/gpu/grtrace/grtrace.c）
    • 字段与统计：engine_class/ring_id 贯穿 hdr/payload；补齐 writes_short/bytes_written/bytes_dropped；events_by_type[] 按 type 计数
    • 过滤：grtrace_should_drop_by_filter() 串接 filter_engine_mask、filter_ring_id；config_write 支持键：filter_engine_mask、filter_ring_id
    • 时间与序列：统一使用 ktime_get_ns()；gseq 为全局 64 位单调；cseq 为 per-CPU 32/64 位（当前实现存在）
    • 视图：events_by_type、pc_cseq、pc_stats（现已具备，需对齐字段）
  • 用户态（tools/grtrace）
    • CLI：--engine [MASK]、--ring [ID] 过滤参数；统计按 ring 聚合打印
    • 解析：保留对未知 type 的跳读（按 hdr.size）

契约与单位

  • ts：ns，monotonic；gseq：u64 单调递增；cseq：per-CPU 单调
  • engine_class：u16（bitmask）；ring_id：u16；ctx_id：u32
  • 计数与单位：使用通配后缀说明：bytes[...]=字节；writes[...]=次；filtered[...]=条

冒烟脚本（可复制）

  1. echo start > /sys/kernel/debug/grtrace/control
  2. echo "filter_ring_id=1" > /sys/kernel/debug/grtrace/config
  3. echo "emit submit 100 0 1 1" > /sys/kernel/debug/grtrace/emit
  4. echo "emit submit 100 0 2 1" > /sys/kernel/debug/grtrace/emit
  5. cat /sys/kernel/debug/grtrace/stats | grep -E "events_by_type|filtered_|writes_"
  6. echo stop > /sys/kernel/debug/grtrace/control

预期：ring=1 事件被计入，ring=2 被过滤或在聚合中区分；无内核错误日志。

风险与回退

  • 多 CPU 时间序列穿插导致全局顺序感知困难 → 以 gseq 兜底排序，按 ring 局部有序
  • engine/ring 枚举不一致 → 以 METADATA 导出枚举表；用户态按表映射

v0.3 事件模型稳定化

  • 内核
  • 用户态
  • 验收
  • 代码开发量预估：900 行

v0.3 详细拆解（Sprint 3–4 交叠）

  • 内核（grtrace.c）
    • 事件冻结：COMMIT/SUBMIT/START/END/IRQ/CTX_SWITCH/SYNC_WAIT_{ENTER,EXIT}/ERROR
    • STREAM_INFO + METADATA（现已实现）：feature bits/clock 源/版本
    • DoD：全部事件导出，用户态能解析并生成时间线
    • 预估 LOC：~500–600（含结构体、路径打通）
  • 用户态（tools/grtrace）
    • 解析并导出 per-job 指标（t_queue/t_exec 等）
    • DoD：对一组事件输出每 job 的关键时长
    • 预估 LOC：~250–300

【v0.3 DoD 检查表】

  • 代码：全部事件类型落地；payload 与 hdr.size 对齐
  • 文档：事件语义/字段说明与时序示意图
  • 冒烟：生成每 job 关键时长 CSV
  • 提交：列出新增/修改事件与兼容性说明
  • 度量：本期净增 ≥900 行

v0.3 实施任务（文件/函数/键）

  • 内核（grtrace.c）
    • 事件枚举与结构：
      • COMMIT/SUBMIT/START/END/IRQ/CTX_SWITCH/SYNC_WAIT_{ENTER,EXIT}/ERROR
      • 结构统一以 hdr(size,u16) + payload，新增字段置于末尾，保持对齐
    • METADATA：增加 feature_bits（bit0: size-skip; bit1: token-bucket; bit2: watchlist; …）
    • 错误路径：ERROR 事件包含 code（reset/timeout）、ring、ctx、ts
    • 校验：编解码自测（大小端、对齐、size 校验）
  • 用户态（tools/grtrace）
    • 解析：按 hdr.size 跳读；未知 type 计数到 unknown_events
    • 导出：per-job 指标 CSV（submit_ts、start_ts、end_ts、complete_ts、t_queue、t_exec…）

v0.3 契约与单位

  • hdr.size：含头+payload，总是偶数对齐；payload 字段小端
  • job key：{ctx_id, ring_id, seqno}；允许 seqno 回绕（u32），以 gseq 协助 disambiguation
  • CTX_SWITCH：标记 preempt:boolean，from_ctx→to_ctx

v0.3 冒烟脚本（可复制）

  1. start + 发一组 submit/commit/start/end/irq + ctx_switch
  2. userspace 解析生成 per-job CSV
  3. 校验 t_exec = end-start，t_queue = start-submit 为正

v0.3 风险与回退

  • 事件缺失或乱序 → per-job 容错：缺失填 NA；乱序按 gseq 校正
  • 大 payload 引入对齐问题 → 统一 u8 填充，hdr.size 保障跳读

v0.4 工具链（grtrace）

  • 用户态
  • 文档
  • 验收
  • 代码开发量预估：1200 行

v0.4 详细拆解（Sprint 5–6）

  • 用户态（tools/grtrace）
    • 控制面：start/stop/status/config 一体化 CLI
    • 报告：Top-N 阻塞类别、直方图、简单时间线
    • DoD：一条命令采集、另一条生成报告；生成 CSV/文本
    • 预估 LOC：~700–800
  • 内核（grtrace.c）
    • 可选 CSV 视图（events_by_type、latency_hist、pc_*、sec_stats 已具备）
    • DoD：视图 read 有效，stats 与视图一致
    • 预估 LOC：~200–300（补齐）

【v0.4 DoD 检查表】

  • 代码：CLI 可 start/stop/status/config；报告可生成 Top-N/直方图
  • 文档：CLI 帮助与示例、典型场景
  • 冒烟：一条采集一条报告，文件产出可打开
  • 提交：分点描述 CLI 子命令与示例
  • 度量：本期净增 ≥1200 行

v0.4 实施任务（文件/函数/键）

  • 用户态（tools/grtrace）
    • 子命令：grtrace start|stop|status|config|report
    • report 选项：--topn N、--hist [lat|size|result]、--per-ring、--per-ctx
    • 输出：CSV（per-job、per-ring 汇总）、文本 Top-N；可选简单图（ASCII 直方图）
  • 内核（grtrace.c）
    • 视图对齐：latency_hist、events_by_type、pc_stats、sec_stats 与 stats 一致
    • config：保持键语义稳定；非法键返回 -EINVAL

v0.4 契约与单位

  • report 列：job_key、t_queue、t_exec、t_gpu_wait、t_complete、label（如长队列/执行慢/抢占多）
  • hist：默认 12 桶，2^k 对数刻度；桶边界输出在视图首行

v0.4 冒烟脚本（可复制）

  1. grtrace start
  2. 运行示例 workload（或 emit 注入）
  3. grtrace report --topn 5 --hist lat --per-ring > report.txt
  4. 打开 report.txt 检查列/非空

v0.4 风险与回退

  • CLI 行为变化影响脚本 → 保持向后兼容的别名（如 --engine-mask 与 --engine）
  • 大文件输出耗时 → 加 --limit / --since / --until 选项

v0.5 性能与开销治理

  • 内核
  • 用户态
  • 验收
  • 代码开发量预估：800 行

v0.5 详细拆解（Sprint 5–6 交叠）

  • 内核（grtrace.c）
    • 采样/级别（level/sample/verbose）、回压阈值、自适应采样
    • 速率限制（窗口/令牌桶，已实现）、细分丢弃计数（已实现）
    • 写入耗时直方图/最大值/总时长（已实现）
    • DoD：高事件率下可控丢弃；stats 能量化治理效果
    • 预估 LOC：~300–400（补齐/优化）
  • 用户态（tools/grtrace）
    • 采集开销报告与阈值/规则开关
    • DoD：报告中可见事件率、丢弃率、直方图
    • 预估 LOC：~250–300

【v0.5 DoD 检查表】

  • 代码：level/sample/限速/回压/直方图均可配置/可观测
  • 文档：参数与指标定义、调优指南
  • 冒烟：高事件率场景下，丢弃率与直方图随配置变化
  • 提交：列出新增配置键及默认值
  • 度量：本期净增 ≥800 行

v0.5 实施任务（文件/函数/键）

  • 内核（grtrace.c）
    • 限速：窗口与令牌桶（rate_limiter_mode=0/1）；配置键 max_events_per_sec、rate_limiter_mode
    • 回压：backpressure_threshold；自适应采样 adaptive_sampling
    • 直方图：写入耗时 latency_hist；新增 result_hist（ok/short/disabled/reserve_fail）
    • stats：rate_limited_drops、backpressure_drops、filtered_、writes_short/ok、bytes_
  • 用户态（tools/grtrace）
    • 开销报告：事件率、丢弃率、平均写入耗时、直方图导出

v0.5 契约与单位

  • max_events_per_sec：整数，0 表示不限速；令牌桶补充速率与余量
  • backpressure_threshold：0–100（百分比），> 阈值触发自适应采样

v0.5 冒烟脚本（可复制）

  1. echo "max_events_per_sec=1000" > .../config
  2. 高速 emit N 条；观察 stats 中 rate_limited_drops > 0
  3. 设置 backpressure_threshold=30；再次压测，观察 writes_short 比例与 sampled 变化

v0.5 风险与回退

  • 令牌补给计算误差 → 使用 ktime_get_ns 基于纳秒计算补给量，饱和裁剪
  • 回压判定抖动 → 增加滑动窗口平滑（sec_stats 聚合）

v0.6 持久化格式

  • 设计
  • 验收
  • 代码开发量预估：400 行

v0.6 详细拆解（Sprint 7）

  • 内核（grtrace.c）
    • 发送顺序：先 STREAM_INFO，紧接 METADATA（已实现）；依赖 hdr.size 做 forward-compat 跳读
    • DoD：参考解析器可跳读未知 payload，用户态工具零修改可读
    • 预估 LOC：~50–100（补注释/一致性）
  • 用户态（tools/grtrace）
    • 参考解析器完善与单测
    • DoD：面对 METADATA/STREAM_INFO 顺序仍正确
    • 预估 LOC：~150–200

【v0.6 DoD 检查表】

  • 代码：STREAM_INFO→METADATA 顺序正确；hdr.size 驱动兼容
  • 文档：格式描述与兼容性说明
  • 冒烟：带 METADATA 的流用户态零改动解析通过
  • 提交：说明兼容策略与保留字段
  • 度量：本期净增 ≥400 行

v0.6 实施任务（文件/函数/键）

  • 内核（grtrace.c）
    • STREAM_INFO：version、session_id、feature_bits、clock_src、start_ts
    • METADATA：驱动名、GPU 型号、ring/engine 枚举表、字段尺寸
    • 发送顺序：先 STREAM_INFO，紧接 METADATA（已实现），每次 start 发送一次
  • 用户态（tools/grtrace）
    • 参考解析器：顺序无关（按 hdr.type 识别），未知字段按 size 跳过
    • 单元测试：构造含未知扩展字段的缓冲并验证解析

v0.6 契约与单位

  • 向后兼容：新字段仅追加在尾部；旧解析器依赖 hdr.size 跳过
  • feature_bits：bit0:size-skip、bit1:token-bucket、bit2:watchlist、bit3:sec_stats…

v0.6 冒烟脚本（可复制）

  1. start 后立即抓取缓冲前两条记录，确认 STREAM_INFO→METADATA 顺序
  2. 使用旧版本用户态解析，验证不崩并能读主体事件

v0.6 风险与回退

  • 多次 start/stop 的元信息重复 → 约定每次 start 发送；用户态以 session_id 分段
  • 大版本不兼容 → 提前预留 version/feature_bits 并文档化

v0.7 供应商适配

  • 内核
  • 验收
  • 代码开发量预估：900 行

v0.7 详细拆解（Sprint 8–9）

  • 内核（新增文件）
    • grtrace_i915.c：提交/完成/ctxsw 钩子骨架，能编译，后续逐步实现
    • grtrace_amdgpu.c：gfx/comp/copy 钩子骨架，能编译
    • DoD：至少两家驱动骨架合入并可编译
    • 预估 LOC：~800–1000

【v0.7 DoD 检查表】

  • 代码：i915/amdgpu 骨架文件可编译，导出符号正确
  • 文档：各驱动挂钩点与最小示例
  • 冒烟：构建通过，加载后核心路径不崩
  • 提交：每驱动单独提交，清晰描述挂钩范围
  • 度量：本期净增 ≥900 行

v0.8 与系统追踪联动

  • 集成
  • 验收
  • 代码开发量预估：500 行

v0.8 详细拆解（Sprint 8–9 交叠）

  • 内核
    • 对时标记事件、必要的 pid/tid/ctx/engine 关联字段
    • DoD：与 ftrace/perf 时间轴对齐的示例
    • 预估 LOC：~200–300
  • 用户态
    • 合并 CPU/GPU 事件的时间线对齐脚本
    • DoD：出一张对齐图或文本报告
    • 预估 LOC：~200–250

【v0.8 DoD 检查表】

  • 代码：对时标记事件与 PID/TID/CTX 关联字段就绪
  • 文档：对齐方法与示例输出
  • 冒烟：CPU/GPU 时间线对齐展示
  • 提交：描述对时来源与误差
  • 度量：本期净增 ≥500 行

v0.9 稳定化

  • 测试
  • 文档
  • 验收
  • 代码开发量预估：200 行

v0.9 详细拆解（Sprint 10）

  • 测试
    • kselftest：功能/回归/压力覆盖主要路径
    • DoD：CI 中自测通过率 100%，关键路径无回归
    • 预估 LOC：~150–200
  • 内核
    • 锁/RCU 审核、热路径微优化、常量折叠
    • DoD：无性能回退，风格/静态检查干净
    • 预估 LOC：~50–100

【v0.9 DoD 检查表】

  • 代码：kselftest 覆盖主路径；锁/RCU 审核通过
  • 文档：FAQ/故障排查更新
  • 冒烟：CI 自测 100% 通过
  • 提交：仅修复/性能提交，避免大改
  • 度量：本期净增 ≥200 行

v1.0 基线发布

  • 承诺
  • 发布物
  • 代码开发量预估：100 行

v1.0 详细拆解（Sprint 11）

  • 发布标准
    • 接口/格式冻结，minor 版本向后兼容承诺
    • 完整文档（架构、接口、格式、FAQ、Troubleshooting）
    • DoD：在干净环境 1 小时内完成“构建→加载→采集→报告”演示
    • 预估 LOC：~100（文档/脚手架）

【v1.0 DoD 检查表】

  • 代码：接口/格式冻结；版本协商健壮
  • 文档：完整发布文档与示例
  • 冒烟：1 小时演示链路可复现
  • 提交：Release notes 与标签
  • 度量：收尾净增 ≥100 行

按职能拆分的任务清单

  • 内核（core）
  • 驱动适配（vendors）
  • 用户态工具
  • 测试/CI
  • 文档

时间线建议（示例）

  • Sprint 1-2（v0.1）：MVP 闭环（单供应商单 ring）
  • Sprint 3-4（v0.2-0.3）：多 ring/时钟一致性 + 事件模型冻结
  • Sprint 5-6（v0.4-0.5）：工具链 + 开销治理
  • Sprint 7（v0.6）：格式 v1 固化
  • Sprint 8-9（v0.7-0.8）：供应商适配 + 系统联动
  • Sprint 10（v0.9）：稳定化
  • Sprint 11（v1.0）：发布

累计代码量（按 Sprint）

说明：将每个里程碑的小节“代码开发量预估”按上节时间线对应的 Sprint 平均分摊，统计每个 Sprint 的新增 LOC 与累计 LOC。

Sprint 对应版本范围 当期新增 LOC 累计 LOC
1 v0.1 400 400
2 v0.1 400 800
3 v0.2–v0.3 800 1600
4 v0.2–v0.3 800 2400
5 v0.4–v0.5 1000 3400
6 v0.4–v0.5 1000 4400
7 v0.6 400 4800
8 v0.7–v0.8 700 5500
9 v0.7–v0.8 700 6200
10 v0.9 200 6400
11 v1.0 100 6500

开发周期预估

  • 假设
    • 起始日期：2025-09-01
    • 一周一 Sprint；团队 2–3 人（内核/驱动/用户态），70–80% 投入
  • 总体
    • 11 个 Sprint ≈ 11 周 ≈ 2.5 个月；含 20% 缓冲 ≈ 3 个月
  • 里程碑分配（与上节时间线一致）
    • v0.1：2 Sprint（2 周）
    • v0.2–0.3：2 Sprint（2 周）
    • v0.4–0.5：2 Sprint（2 周）
    • v0.6：1 Sprint（1 周）
    • v0.7–0.8：2 Sprint（2 周）
    • v0.9：1 Sprint（1 周）
    • v1.0：1 Sprint（1 周）
  • 其他节奏（参考）
    • 1 周一 Sprint：≈ 11 周；含 20% 缓冲 ≈ 3 个月
    • 3 周一 Sprint：≈ 33 周；含 20% 缓冲 ≈ 7.5–8 个月
    • 单人全栈（两周节奏）：在基线基础上 +60–80% → ≈ 9–10 个月
  • 风险缓冲建议
    • 供应商适配、性能开销治理、系统联动不确定性较高；建议预留 2–3 个 Sprint 风险缓冲，并从 Sprint 4 起并行推进适配以降低尾部风险

冲刺提速计划（方案 B）

目标：在保持 11 个 Sprint 不变的前提下，集中提升 Sprint 8–11 的产出以逼近最初 6500 行目标。

  • 现状与差距（截至 v0.6 / Sprint 7）
    • 实际净增约 1585 行（作者口径，自 8eacb27 起）
    • 计划累计应为 4800 行 → 差距 ≈ 3215 行
  • 调整后的 Sprint 目标（每周净增目标）
    • Sprint 8：≥ 1000 行
    • Sprint 9：≥ 1000 行
    • Sprint 10：≥ 700 行
    • Sprint 11：≥ 700 行
    • 合计新增 ≥ 3400 行（在现状基础上逼近或达到 6500 总目标）
  • 高产出任务池（优先投入，可并行）
    • 供应商适配（amdgpu/i915）：核心 hook 覆盖 + 最小闭环（每家 ≈ 800–1000 行）
    • 用户态工具链增强（report/分析）：Top-N、标签器、直方图与时间线（≈ 600–800 行/周）
    • 自测与基准（kselftest/压力脚本）：功能/回归/基准（≈ 500–800 行/周）
    • 系统联动（ftrace/perf/eBPF）：时间对齐与关联字段（≈ 400–600 行/周）
  • 保障措施
    • 明确模块 Owner 与合并窗口，日更进度板；每日提交净增 ≥ 150–200 行
    • 代码评审 fast-track：< 24 小时首评，< 48 小时合入或反馈
    • 度量上报：以 git numstat 为准的新增/删除/净增与通过率（周累计）

依赖与前置

  • 内核最低版本与配置：relay、debugfs、RCU、ktime
  • 目标驱动版本（amdgpu/i915/nouveau）与开启的调试选项
  • 构建与 CI 环境：编译器版本、静态检查工具、kselftest 框架

风险与缓解

  • 热路径开销过高 → 采样/级别控制、批量写入、预分配、缓存友好
  • 不同驱动差异大 → 事件语义抽象、分层适配、先覆盖主路径
  • 时间戳/序列一致性问题 → 明确源、统一转换、一致性校验
  • 数据量与磁盘压力 → 可调环形缓冲、滚动文件、阈值报警

更新策略：每个里程碑结束后补充“变更记录/经验教训/后续计划”，并滚动维护本路线图。

Definition of Done（DoD）与执行准则（强约束）

  • DoD（每个交付最少满足）
    • 代码：可编译（内核模块 M=drivers/gpu/grtrace）、无未定义符号、静态检查无新增严重告警
    • 文档：debugfs 接口与新配置项在文档中有说明与示例（读/写示例）
    • 演示：1 个最小化冒烟步骤（加载模块→start→发 3 条事件→stop→读取 stats/视图）
    • 提交：英文、分点、无转义“”；使用 commit 模板文件 -F 提交
  • 实施节奏
    • 每日净增 ≥ 150 行（以 git numstat 为准），失败则下日补足；每晚 1 次最小冒烟
    • 每新增核心行为（过滤/限速/计数/视图）必须：代码+文档+冒烟三联，同时完成
    • 功能优先于输出花样：先内核核心路径（事件→过滤→速率→写入→统计）

可执行 WBS（按文件/函数）

  • 内核核心（drivers/gpu/grtrace/grtrace.c）
    • 事件发射：grtrace_write_event()（采样/过滤/限速/回压/写入/计时/直方图/计数）
    • 过滤：grtrace_should_drop_by_filter()（engine/ring/type + watchlist）
    • 控制面：ctrl_fops/config_fops/emit_fops（start/stop、配置读写、手动发射）
    • 视图：events_by_type_fops/latency_hist_fops/pc_*_fops/sec_stats_fops
    • 每秒统计：grtrace_stats_workfn() + sec_stats ring
    • 新增（已落地）：
      • type 掩码过滤（filter_type_mask）
      • ctx watchlist（watch_ctx_add/clear、watch_allow_mode）
      • 速率限制：窗口/令牌桶（rate_limiter_mode=0/1）
      • 丢弃细分：disabled/payload_oversize/reserve_fail
  • 供应商适配（新增文件，按里程碑推进）
    • drivers/gpu/grtrace/grtrace_i915.c（挂钩提交/完成/ctx 切换）
    • drivers/gpu/grtrace/grtrace_amdgpu.c（gfx/comp/copy 提交/完成/irq）

API/数据契约（片段）

  • 事件头 grtrace_event_hdr：{type,u16 size,cpu,ts,gseq,cseq}
  • STREAM_INFO 紧随 METADATA（现已实现）；向后兼容：用户态按 size 跳读
  • debugfs/config 支持键：
    • level, sample, profile, max_events_per_sec,
    • rate_limiter_mode, backpressure_threshold, adaptive_sampling,
    • filter_engine_mask, filter_ring_id, filter_type_mask,
    • watch_allow_mode, watch_ctx_add, watch_ctx_clear, reset_stats
  • stats 增量字段：filtered_type, filtered_watch, rate_limited_drops, backpressure_drops

Sprint 8–11 可执行 Backlog（文件/函数级，含 LOC 预估）

  • Sprint 8（≥1000 LOC）
    • [core] 事件大小直方图（payload buckets）与写入结果直方图（ok/short/disabled/reserve_fail）
      • grtrace_write_event()/stats_read（+120 LOC）
    • [core] ring_id 观察名单（allow/deny + AND/OR 与 ctx）
      • config_fops + grtrace_should_drop_by_filter（+180 LOC）
    • [core] STREAM_INFO 增加 session_id/feature bits（用户态兼容不变）（+80 LOC）
    • [vendor] i915 最小闭环（提交/完成/ctxsw）骨架文件与空实现（可编译占位）（+350 LOC）
    • [kselftest] 最小用例：加载→start→emit→读取→断言计数（tools/testing/selftests/grtrace/）（+300 LOC）
  • Sprint 9（≥1000 LOC）
    • [vendor] amdgpu 最小闭环（gfx 提交/完成/irq 钩子骨架）（+500 LOC）
    • [core] 规则引擎雏形（简单阈值：t_queue/t_exec 超阈置标记字段）
      • 在 submit/complete 路径增加规则命中计数与 debugfs 视图（+250 LOC）
    • [core] sec_stats 扩展：支持 burst/max_rate 观测、token 槽位（+120 LOC）
    • [userspace] tools/grtrace 增加统计打印选项（可选）（+200 LOC）
  • Sprint 10（≥700 LOC）
    • [core] ftrace/perf 对时标记事件（对齐 CPU 调度）（+200 LOC）
    • [vendor] i915/AMDGPU 补齐 ring/引擎维度与错误事件（+300 LOC）
    • [kselftest] 压测用例：高事件率/采样/限速/回压组合（+200 LOC）
  • Sprint 11（≥700 LOC）
    • [core] 稳定化：锁/RCU 审核、热路径微优化、直方图常量优化（+250 LOC）
    • [doc+test] 文档齐套、FAQ、kselftest 覆盖到主要路径（+250 LOC）
    • [vendor] nouveau 骨架（可选）（+200 LOC）

说明：每项包含 DoD（三联）与 commit 模板，按日推进并校验净增 LOC。

最小冒烟脚本（人工步骤）

  1. modprobe grtrace 或 insmod grtrace.ko
  2. echo start > /sys/kernel/debug/grtrace/control
  3. echo "submit CTX ENG RING SEQ" > /sys/kernel/debug/grtrace/emit （x3）
  4. cat /sys/kernel/debug/grtrace/stats | grep -E "^(written|filtered_)"
  5. echo stop > /sys/kernel/debug/grtrace/control

提交/分支规范（避免“糊成一坨”）

  • 一律使用文件 -F 方式提交信息（含标题 + 空行 + 列表）
  • 标题只用 ASCII 字符（避免长破折号等 Unicode）
  • 示例：

grtrace: add ctx watchlist and token-bucket mode

  • Add ctx_id watchlist (allow/deny) wired into filter path.
  • Add token-bucket rate limiter alongside windowed limiter.
  • Extend stats with filtered_watch, update sec_stats ring.

风险到行动（具体化）

  • 高事件率导致短写：令牌桶/回压阈值→在 sec_stats 观察 short/write_calls 比例并自适应采样
  • 供应商接口差异：先提交空骨架 + 编译通过，再逐步替换钩子实现
  • LOC 产出不足：每日净增达不到时，从“骨架/占位”切入（视图、kselftest、vendor 空函数）填充
linux > kernel > drivers > gpu > grtrace > docs
#git #bpf
grtrace 开发迭代计划
https://realwujing.github.io/linux/kernel/drivers/gpu/grtrace/docs/grtrace 开发迭代计划/
作者
Wu Jing
发布于
2025年9月8日
许可协议