第7章：DRM内核调试技术：7.1 DRM DebugFS的使用

DeeplyMind2026-01-16 8:53

1. 概述

DRM DebugFS 是 Linux 内核 GPU 子系统通过 debugfs 虚拟文件系统向用户空间暴露的调试信息接口，可以实时查询 GPU 设备状态、驱动信息、硬件状态等。

访问路径： /sys/kernel/debug/dri/

文件系统结构：

复制代码 
/sys/kernel/debug/dri/
├── 0/                    # Card 0 (card0)
│   ├── name              # 设备名称和标识
│   ├── clients           # 当前连接的客户端
│   ├── gem_names         # GEM 对象名称映射
│   ├── state             # Atomic 显示状态
│   └── amdgpu_*          # AMDGPU 驱动特定文件
├── 1/                    # Card 1
├── 128/                  # Render 节点 (renderD128)
└── by-name/
    └── card0 -> ../0

2. DRM 核心提供的标准信息

DRM 核心自动为所有 GPU 创建以下标准调试文件：

2.1 name - 设备名称

路径： /sys/kernel/debug/dri/0/name

信息内容：

  • 驱动名称
  • PCI 设备标识
  • Master 状态
  • Unique 标识符

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/name
amdgpu dev=0000:03:00.0 master=:0 unique=0000:03:00.0

2.2 clients - 客户端列表

路径： /sys/kernel/debug/dri/0/clients

信息内容：

  • 进程命令名和 PID
  • 设备节点索引
  • Master 状态
  • 认证状态
  • 用户 UID
  • Magic 令牌
  • 客户端名称和 UUID

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/clients
             command  tgid dev master a   uid      magic     name                    id
                Xorg  1234   0 yes    y     0 0x12345678    Xorg    12345678-1234-1234-1234-123456789012
             firefox  5678   0 no     n  1000 0x23456789 firefox    23456789-2345-2345-2345-234567890123

2.3 gem_names - GEM 对象名称

路径： /sys/kernel/debug/dri/0/gem_names

信息内容： GEM buffer object 的 handle 到全局 name 的映射关系

2.4 state - Atomic 显示状态

路径： /sys/kernel/debug/dri/0/state

信息内容：

  • CRTC 状态（分辨率、刷新率）
  • Plane 状态（framebuffer 信息）
  • Connector 状态（连接器类型、连接状态）

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/state
plane[31]: card0-HDMI-A-1
        crtc=crtc[35]
        fb=140
                allocated by = Xorg
                refcount=2
                format=XR24 little-endian (0x34325258)
                size=1920x1080
        crtc-pos=1920x1080+0+0

3. AMDGPU 驱动提供的专有信息

AMDGPU 驱动在 /sys/kernel/debug/dri/0/ 目录下提供了大量 GPU 硬件和驱动状态信息。

3.1 硬件信息

amdgpu_firmware_info

功能： 显示 GPU 固件版本信息

信息内容：

  • SMC 固件版本
  • SDMA 固件版本
  • GFX 固件版本
  • MES 固件版本
  • 各个 IP 块的固件版本

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_firmware_info
SMC feature mask: 0x00000fff
SMC firmware version: 0x001e5600 (30.86.0)
SDMA0 firmware version: 0x0000001b (27)
GFX firmware version: 0x00000035 (53)
amdgpu_gpu_recover

功能： 触发 GPU 复位恢复

用法： 写入触发

bash 复制代码 
$ echo 1 > /sys/kernel/debug/dri/0/amdgpu_gpu_recover

3.2 显存信息

amdgpu_vram_mm

功能： VRAM 内存管理器状态

信息内容：

  • VRAM 总容量
  • 已使用 VRAM
  • 空闲 VRAM
  • VRAM 分配块列表

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_vram_mm
VRAM total size: 8589934592 bytes
VRAM used: 2147483648 bytes
VRAM free: 6442450944 bytes
amdgpu_gtt_mm

功能： GTT (Graphics Translation Table) 内存状态

信息内容：

  • GTT 总大小
  • GTT 已使用
  • GTT 空闲
amdgpu_gem_info

功能： GEM 对象信息

信息内容：

  • Buffer object 列表
  • 每个 BO 的大小、位置、标志
  • BO 引用计数

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_gem_info
Total Buffer Objects: 1234
Total Size: 2048 MB

Object 1:
  Handle: 0x12345678
  Size: 4096 KB
  Domain: VRAM
  Flags: 0x0
  Refcount: 2

3.3 性能和电源管理

amdgpu_pm_info

功能： 电源管理信息

信息内容：

  • GPU 时钟频率（当前/最小/最大）
  • 内存时钟频率
  • GPU 负载百分比
  • GPU 温度
  • 功耗

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_pm_info
GFX Clocks and Power:
        600 MHz (SCLK)
        167 MHz (MCLK)
        GPU Load: 23%
        GPU Temperature: 45 C
        GPU Power: 35 W
amdgpu_gpu_metrics

功能： GPU 度量数据

信息内容：

  • 温度（GPU、HotSpot、Memory）
  • 功耗
  • 时钟频率
  • 风扇转速
  • Throttle 状态

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics
GPU Temperature: 45 C
GPU HotSpot Temperature: 48 C
GPU Memory Temperature: 42 C
GPU Power: 35 W
GPU Average Power: 33 W
GFX Clock: 600 MHz
Memory Clock: 167 MHz
Fan Speed: 1200 RPM (30%)
Throttle Status: 0

3.4 命令提交和调度

amdgpu_ring_gfx

功能： Graphics ring buffer 状态

信息内容：

  • Ring buffer 读写指针
  • 已使用空间
  • Fence 序号

示例：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_ring_gfx
GFX Ring:
  Ready: yes
  Read pointer: 0x12345678
  Write pointer: 0x12345680
  Driver read pointer: 0x12345678
  Fence driver initialized: yes
  Fence driver last seq: 0x12345
amdgpu_fence_info

功能： Fence 同步信息

信息内容：

  • 各个 ring 的 fence 状态
  • 已完成的 fence 序号
  • 最后提交的 fence 序号

3.5 寄存器访问

amdgpu_regs

功能： 读取 GPU 寄存器

用法：

bash 复制代码 
# 读取寄存器（地址 0x1234）
$ echo 0x1234 > /sys/kernel/debug/dri/0/amdgpu_regs
$ cat /sys/kernel/debug/dri/0/amdgpu_regs
0x1234: 0xabcdef01
amdgpu_regs_didt

功能： DIDT (Digital Interface Detection Test) 寄存器

amdgpu_regs_pcie

功能： PCIe 配置空间寄存器

3.6 虚拟化和 VM

amdgpu_vm_info

功能： 虚拟内存管理信息

信息内容：

  • Page table 信息
  • VM 大小和范围
  • Page directory 地址
amdgpu_sa_info

功能： Sub-allocator 信息（用于小内存分配）

3.7 错误和调试

amdgpu_ras_eeprom_reset

功能： RAS (Reliability, Availability, Serviceability) 错误计数器复位

amdgpu_gpu_recover

功能： 触发 GPU 恢复

amdgpu_reset_dump_register_list

功能： 重置时转储的寄存器列表

4. 实际应用示例

4.1 监控 GPU 状态

bash 复制代码 
#!/bin/bash
# gpu_monitor.sh - GPU 监控脚本

while true; do
    clear
    echo "========== GPU 监控 =========="
    echo ""
    
    echo "设备信息:"
    cat /sys/kernel/debug/dri/0/name
    echo ""
    
    echo "性能指标:"
    cat /sys/kernel/debug/dri/0/amdgpu_pm_info | grep -E "MHz|Load|Temperature|Power"
    echo ""
    
    echo "显存使用:"
    cat /sys/kernel/debug/dri/0/amdgpu_vram_mm | grep -E "total|used|free"
    echo ""
    
    echo "活动客户端:"
    cat /sys/kernel/debug/dri/0/clients | tail -n +2 | wc -l
    
    sleep 1
done

4.2 故障排查

场景 1：GPU 挂起检测

bash 复制代码 
# 检查 fence 是否正常推进
$ watch -n 1 cat /sys/kernel/debug/dri/0/amdgpu_fence_info

# 如果 fence 长时间不变，可能 GPU 挂起
# 触发 GPU 恢复
$ echo 1 > /sys/kernel/debug/dri/0/amdgpu_gpu_recover

场景 2：显存泄漏检测

bash 复制代码 
# 持续监控显存使用
$ watch -d -n 1 'cat /sys/kernel/debug/dri/0/amdgpu_vram_mm | head -3'

# 查看详细的 GEM 对象分配
$ cat /sys/kernel/debug/dri/0/amdgpu_gem_info

场景 3：温度过热调试

bash 复制代码 
# 实时监控温度和功耗
$ watch -n 1 'cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics | grep Temperature'

# 查看 throttle 状态
$ cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics | grep Throttle

4.3 性能分析

查看 GPU 负载分布：

bash 复制代码 
# 监控 GPU 利用率
$ cat /sys/kernel/debug/dri/0/amdgpu_pm_info | grep "GPU Load"

# 查看活动的客户端
$ cat /sys/kernel/debug/dri/0/clients

分析时钟频率：

bash 复制代码 
# 当前时钟频率
$ cat /sys/kernel/debug/dri/0/amdgpu_pm_info | grep "MHz"

# GPU metrics 详细数据
$ cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics

4.4 开发调试

固件版本确认：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_firmware_info

虚拟内存调试：

bash 复制代码 
$ cat /sys/kernel/debug/dri/0/amdgpu_vm_info

寄存器调试：

bash 复制代码 
# 读取特定寄存器
$ echo 0x2000 > /sys/kernel/debug/dri/0/amdgpu_regs
$ cat /sys/kernel/debug/dri/0/amdgpu_regs

5. 常用查询命令参考

5.1 快速状态查询

bash 复制代码 
# 设备名称
cat /sys/kernel/debug/dri/0/name

# GPU 温度和负载
cat /sys/kernel/debug/dri/0/amdgpu_pm_info | grep -E "Temperature|Load"

# 显存使用
cat /sys/kernel/debug/dri/0/amdgpu_vram_mm | head -3

# 客户端数量
cat /sys/kernel/debug/dri/0/clients | tail -n +2 | wc -l

# 固件版本
cat /sys/kernel/debug/dri/0/amdgpu_firmware_info | grep "version"

5.2 持续监控命令

bash 复制代码 
# 实时监控温度
watch -n 1 'cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics | grep Temperature'

# 实时监控显存
watch -n 1 'cat /sys/kernel/debug/dri/0/amdgpu_vram_mm | head -3'

# 实时监控客户端
watch -n 1 'cat /sys/kernel/debug/dri/0/clients'

# 实时监控功耗
watch -n 1 'cat /sys/kernel/debug/dri/0/amdgpu_gpu_metrics | grep Power'

5.3 故障诊断命令

bash 复制代码 
# 检查 GPU 是否响应
cat /sys/kernel/debug/dri/0/amdgpu_fence_info

# 查看错误日志
dmesg | grep -i amdgpu | tail -20

# 触发 GPU 复位
echo 1 > /sys/kernel/debug/dri/0/amdgpu_gpu_recover

# 检查 RAS 错误
cat /sys/kernel/debug/dri/0/amdgpu_ras_eeprom_reset

6. AMDGPU DebugFS 文件完整列表

文件名 功能 读/写
name 设备名称 R
clients 客户端列表 R
gem_names GEM 名称映射 R
state Atomic 状态 R
amdgpu_firmware_info 固件版本 R
amdgpu_gpu_recover GPU 恢复 W
amdgpu_vram_mm VRAM 状态 R
amdgpu_gtt_mm GTT 状态 R
amdgpu_gem_info GEM 对象信息 R
amdgpu_pm_info 电源管理信息 R
amdgpu_gpu_metrics GPU 度量数据 R
amdgpu_ring_gfx GFX ring 状态 R
amdgpu_ring_compute Compute ring 状态 R
amdgpu_ring_sdma SDMA ring 状态 R
amdgpu_fence_info Fence 信息 R
amdgpu_vm_info 虚拟内存信息 R
amdgpu_sa_info Sub-allocator 信息 R
amdgpu_regs 寄存器访问 R/W
amdgpu_regs_didt DIDT 寄存器 R/W
amdgpu_regs_pcie PCIe 寄存器 R
amdgpu_sensors 传感器数据 R
amdgpu_test_ib IB 测试 W
amdgpu_evict_vram 驱逐 VRAM W
amdgpu_evict_gtt 驱逐 GTT W
amdgpu_ras_eeprom_reset RAS 复位 W

注意： 具体可用的文件取决于 GPU 型号和驱动版本

7. 驱动开发者 API

如果你是驱动开发者，需要添加自定义 debugfs 文件，可以使用以下 API：

7.1 Per-Device API（推荐）

c 复制代码 
/* 添加单个文件 */
void drm_debugfs_add_file(struct drm_device *dev,
                         const char *name,
                         int (*show)(struct seq_file*, void*),
                         void *data);

/* 批量添加文件 */
void drm_debugfs_add_files(struct drm_device *dev,
                          const struct drm_debugfs_info *files,
                          int count);

示例：

c 复制代码 
static int my_info_show(struct seq_file *m, void *unused)
{
    struct drm_debugfs_entry *entry = m->private;
    struct drm_device *dev = entry->dev;
    
    seq_printf(m, "Custom Info: %d\n", 42);
    return 0;
}

void my_driver_init(struct drm_device *dev)
{
    drm_debugfs_add_file(dev, "my_info", my_info_show, NULL);
}

7.2 数据结构

c 复制代码 
struct drm_debugfs_info {
    const char *name;                          /* 文件名 */
    int (*show)(struct seq_file*, void*);      /* 显示回调 */
    u32 driver_features;                       /* 特性要求 */
    void *data;                                /* 私有数据 */
};

8. 总结

核心要点

  1. DRM 核心提供标准信息：name、clients、gem_names、state
  2. AMDGPU 扩展信息丰富：固件、显存、性能、ring、fence、VM 等
  3. 主要用途：监控、调试、性能分析、故障排查
  4. 访问简单：直接用 cat 命令读取文件

典型使用场景

  • 日常监控：温度、负载、显存使用
  • 性能分析：时钟频率、功耗、客户端活动
  • 故障排查：fence 状态、错误计数、GPU 恢复
  • 开发调试：固件版本、寄存器访问、VM 状态

如果想深入理解debugfs的原理，请查看专栏：第0章：DebugFS机制与AMDGPU应用分析--专栏目录。

相关推荐
提伯斯6461 小时前
Fast-LIO到MAVROS视觉定位转换
linux·ros·无人机·mid360·fasltlio
天码-行空1 小时前
Oracle 19c（19.3.0.0）完整安装教程（Windows+Linux双环境）
linux·运维·数据库·oracle
搞全栈小苏2 小时前
使用 nvm（不破坏系统）Linux 上把 Node.js / npm 升级到你指定版本（Node v23.x、npm 10.x）
linux·npm·node.js
ONLYOFFICE2 小时前
ONLYOFFICE 桌面编辑器现已推出 Linux ARM 版本
linux·运维·arm开发
阿钱真强道2 小时前
04 ubuntu20下 OpenHarmony-3.0-LTS qemu mps2-an386 运行 liteos_m
linux·嵌入式硬件·ubuntu·harmonyos
zl_dfq2 小时前
Linux 之 【文件】（C语言文件缓冲区）
linux
yuanmenghao2 小时前
车载Linux 系统问题定位方法论与实战系列 - 系统 reset / reboot 问题定位
linux·服务器·数据结构·c++·自动驾驶
n***33352 小时前
Linux命令组合大赛：创意与效率的终极对决
linux·运维·服务器
一个平凡而乐于分享的小比特2 小时前
Linux内核核心组件详解
linux·内存管理·进程间通信·虚拟文件系统·系统调用接口·网络接口
热门推荐
01GitHub 镜像站点02Linux下V2Ray安装配置指南03Labelme从安装到标注：零基础完整指南04网站改了域名，如何查找？05AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南06Claude Code Skills 实用使用手册07UV安装并设置国内源08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09百度网盘偷偷给电脑“降频”？102025年大语言模型技术全景报告