本系列全面介绍 Linux 内核 DebugFS 机制以及 AMD GPU 驱动中的 DebugFS 实现。

已更新文章的链接会点亮，专栏完结后，这里的描述会消失。请收藏以免走失。更新中…

---

第一部分：Linux DebugFS 机制与实现

1. DebugFS 概述

• 1.1 什么是 DebugFS
  • 虚拟文件系统的概念
  • DebugFS 的设计目标和应用场景
  • DebugFS vs SysFS vs ProcFS
• 1.2 DebugFS 的挂载和访问
  • 默认挂载点：/sys/kernel/debug/
  • 挂载方法和权限要求
  • 用户空间访问方式

2. DebugFS 核心 API

• 2.1 目录操作
  • debugfs_create_dir() - 创建目录
  • debugfs_remove() / debugfs_remove_recursive() - 删除
• 2.2 文件创建 API
  • debugfs_create_file() - 通用文件创建
  • debugfs_create_file_unsafe() - 不安全版本
  • debugfs_create_file_size() - 指定大小
• 2.3 简单数值类型接口
  • debugfs_create_u8/u16/u32/u64() - 无符号整数
  • debugfs_create_x8/x16/x32/x64() - 十六进制显示
  • debugfs_create_bool() - 布尔值
  • debugfs_create_atomic_t() - 原子变量
• 2.4 高级数据类型
  • debugfs_create_blob() - 二进制大对象
  • debugfs_create_regset32() - 寄存器集合
  • debugfs_create_devm_seqfile() - seq_file 接口

3. DebugFS 文件操作实现

• 3.1 案例分析：debugfs_create_u32() 实现
• 3.2 实现自定义 DebugFS 接口
• 3.3 seq_file 接口
• 3.4 DEFINE_DEBUGFS_ATTRIBUTE vs debugfs_create_u32()
• 3.5 实际应用案例：Dynamic Debug

4. DebugFS 安全性和并发控制

• 4.1 权限管理
  • 文件权限设置（mode参数）
  • 安全访问控制
• 4.2 并发保护
  • 互斥锁的使用
  • 电源管理同步（pm_runtime）
  • 防止竞态条件

---

第二部分：AMD 驱动中的 DebugFS 架构

5. AMDGPU DebugFS 整体架构

• 5.1 初始化流程
  • 驱动加载时的 debugfs 初始化
  • amdgpu_debugfs_init() 函数分析
  • 多级初始化调用链
• 5.2 目录结构组织
  • /sys/kernel/debug/dri/<card>/ 根目录
  • 子系统目录划分（ras/, proc/等）
  • 设备实例相关的目录
• 5.3 模块化设计
  • 各子系统独立的 debugfs 初始化函数
  • 统一的命名规范
  • 模块间的依赖关系

6. AMDGPU DebugFS 子系统分类

• 6.1 核心调试接口（amdgpu_debugfs.c）
  • 寄存器访问接口
  • GFX 状态查询
  • 内存管理相关
• 6.2 KFD（Kernel Fusion Driver）
  • HSA 相关的调试接口
  • 进程管理和队列调试
• 6.3 Display Manager
  • 显示管道调试
  • 连接器和显示器信息
  • PSR/Replay 状态监控
• 6.4 电源管理（PM）
  • 频率和电压监控
  • 传感器读取
  • SMU 调试接口
• 6.5 其他子系统
  • RAS、VCN、SDMA、Ring等
  • 安全功能相关

---

第三部分：AMDGPU DebugFS 接口详解

7. 寄存器访问接口

• 7.1 amdgpu_regs - MMIO 寄存器访问
  • 特殊 offset 编码机制
  • GRBM/SRBM 银行切换
  • SE/SH/CU 选择机制
  • 电源门控锁定
  • 使用示例和注意事项
• 7.2 amdgpu_regs2 - 增强型寄存器访问
  • ioctl 控制接口设计
  • 状态保持机制
  • 与 regs 的区别
• 7.3 专用寄存器接口
  • amdgpu_regs_pcie - PCIE 配置空间
  • amdgpu_regs_smc - SMC 寄存器
  • amdgpu_regs_didt - DIDT 寄存器

8. GPU 状态查询接口

• 8.1 GFX 配置信息
  • amdgpu_gca_config - 图形配置导出
  • SE/SH/CU 拓扑信息
  • 版本化设计
• 8.2 波形和寄存器调试
  • amdgpu_wave - 波形数据读取
  • amdgpu_gpr - GPR 寄存器内容
  • amdgpu_gprwave - 统一接口
  • 着色器调试应用
• 8.3 GFXOFF 电源管理
  • amdgpu_gfxoff - 控制接口
  • amdgpu_gfxoff_status - 状态查询
  • amdgpu_gfxoff_count - 统计计数
  • amdgpu_gfxoff_residency - 驻留时间

9. 内存管理调试接口

• 9.1 VRAM/GTT 管理
  • amdgpu_evict_vram - VRAM 驱逐
  • amdgpu_evict_gtt - GTT 驱逐
  • TTM 统计信息
• 9.2 虚拟内存调试
  • amdgpu_vm_info - 全局 VM 信息
  • vm_pagetable_info - 页表详情
  • GEM 对象信息
• 9.3 内存测试工具
  • amdgpu_benchmark - 带宽测试
  • 测试场景和性能分析

10. 固件和硬件信息

• 10.1 固件版本查询
  • amdgpu_firmware_info - 所有固件版本
  • 各 IP 块的固件状态
• 10.2 VBIOS 和发现表
  • amdgpu_vbios - BIOS 镜像导出
  • amdgpu_discovery - GPU 发现表
  • 硬件配置解析

11. 测试和诊断接口

• 11.1 功能测试
  • amdgpu_test_ib - IB 环测试
  • amdgpu_preempt_ib - 抢占测试
• 11.2 电源和时钟控制
  • amdgpu_force_sclk - 强制时钟频率
  • amdgpu_smu_debug - SMU 调试掩码
• 11.3 传感器读取
  • amdgpu_sensors - 多传感器接口
  • 温度、电压、功耗监控

12. Ring 和调度器接口

• 12.1 Ring 状态监控
  • 每个 ring 的详细信息
  • 读写指针、fence 值
  • 错误注入接口
• 12.2 调度器掩码控制
  • amdgpu_gfx_sched_mask - GFX 调度
  • amdgpu_compute_sched_mask - Compute 调度
  • amdgpu_vcn_sched_mask - VCN 调度
  • amdgpu_jpeg_sched_mask - JPEG 调度
  • amdgpu_sdma_sched_mask - SDMA 调度

13. RAS（可靠性）接口

• 13.1 RAS 控制
  • ras_ctrl - 错误注入和查询
  • ras_eeprom_table - 错误记录表
  • RAS 配置和阈值
• 13.2 各 IP 块的 RAS 统计
  • UMC、GFX、MMHUB 等
  • 可纠正和不可纠正错误
  • 自动重启机制

14. KFD 调试接口

• 14.1 队列调试
  • mqds - 内存队列描述符
  • hqds - 硬件队列描述符
  • rls - 运行列表
• 14.2 进程管理
  • proc//pasid_
  • 内存限制控制
  • hang_hws - 挂起调试

15. Display Manager 接口

• 15.1 显示管道信息
  • amdgpu_mst_topology - MST 拓扑
  • amdgpu_dm_capabilities - 能力查询
  • amdgpu_dm_dtn_log - 技术日志
• 15.2 连接器调试
  • DP 链路训练和测试
  • HDMI 相关控制
  • EDID 和显示模式
• 15.3 PSR 和 Replay
  • 能力、状态、驻留时间
  • 控制和统计接口
• 15.4 DMUB 调试
  • 固件跟踪缓冲区
  • 状态查询和事件日志
• 15.5 CRC 和显示验证
  • CRC 窗口设置
  • 像素格式验证

---

第四部分：实践指南与最佳实践

16. 开发者指南

• 16.1 添加新的 debugfs 接口
  • 步骤和代码模板
  • 命名规范
  • 注册流程
• 16.2 调试技巧
  • 常用命令和脚本
  • 问题定位方法
  • 性能分析工具

17. 用户使用指南

• 17.1 常见使用场景
  • GPU 性能监控
  • 问题诊断和日志收集
  • 驱动开发和测试
• 17.2 安全注意事项
  • 权限要求
  • 风险操作警告
  • 生产环境使用建议

---

附录

附录 A：DebugFS 接口速查表

• A.1 核心接口列表
• A.2 接口分类索引
• A.3 常用操作示例

附录 B：数据结构参考

• B.1 关键结构体定义
• B.2 IOCTL 命令定义
• B.3 编码格式说明

附录 C：参考资源

• C.1 内核文档链接
• C.2 AMD GPU 文档
• C.3 社区资源

---