图形模块调试
本文档介绍如何使用 SDK 已提供的 GPU AT 调试命令和各模块 PROC 信息定位图形显示、VAU 合成、DPU 输出、JPEG 处理和视频显示问题。开发者可先验证屏幕和 DPU 基础输出，再采集 VAU、DPU、JPEG、VENC、VDEC、VICAP 的状态与帧数据，逐步缩小故障范围。
图形视频驱动调试背景知识
只有在图形业务已创建 VAU、DPU、JPEG 等模块时，PROC 才会包含有效状态。GPU AT 命令入口位于 /src/middleware/utils/at/at_gpu_cmd/at/at_gpu.c，用于触发冒烟、颜色条、截屏、PROC 查询和帧数据保存等调测动作；VENC 和 VDEC 的 PROC 入口分别位于 /src/middleware/utils/at/at_venc_cmd/at/at_venc.c 和 /src/middleware/utils/at/at_vdec_cmd/at/at_vdec.c。
快速跑通图形视频调试 Demo
功能说明
本节以屏幕无显示、花屏或颜色异常为例，使用 AT+GPU=smoke、颜色条、PROC 和截屏证据，在不修改业务代码的情况下判断问题位于屏幕/DPU 输出、VAU 合成还是上游 JPEG/视频数据。
准备工作
说明：本文示例命令以一站式 CLI 为主。实际开发可从以下三种环境中选择，推荐使用一站式 CLI。
| 开发环境 | 适用场景 | 使用指南 |
|---|---|---|
| 一站式 CLI（推荐） | 快速完成目标选择、构建、烧录和串口监视 | 一站式 CLI 开发环境使用指南 |
| HiSpark Studio for VS Code | 图形化编辑、编译、烧录和调试 | HiSpark Studio for VS Code 开发环境使用指南 |
| WSL 与 Docker | 在 Windows 上使用一致的 Linux 容器构建环境 | WSL 与 Docker 环境使用指南 |
按一站式 CLI 开发环境使用指南准备环境、构建和烧录。先确认屏幕供电、背光、MIPI/QSPI 配置和待测图形业务已经启动。
调试步骤与代码走读
推荐按“DPU 基础输出 → VAU 任务状态 → 截屏证据 → JPEG/视频支路”的顺序定位：
- 使用
AT+GPU=smoke验证基础颜色填充和显示；失败优先检查屏幕、DPU 与基础初始化。 - 使用
AT+GPU=dpu_cbar,1打开颜色条、使用AT+GPU=dpu_cbar,0关闭颜色条，区分 UI 图层问题与物理输出问题。 - 使用
AT+GPU=vau_proc、AT+GPU=jpeg_proc等命令读取模块状态，确认任务是否创建、提交并完成。 - 使用
AT+GPU=screen_cap,layer_id截屏；将输出路径、stride 和 height 与当前 Surface 格式核对，判断异常发生在合成前还是显示后。
AT+GPU 的参数解析和分发由 at_gpu_sample_process()、at_gpu_process() 和 g_at_gpu_func_map 完成。screen_cap 对应 wstp_gpu_dpu_screen_cap()：读取 DPU 层的物理地址、stride 和 height，将帧缓冲区保存为 /user/dpu_screen_cap.bin。VAU、DPU、JPEG 的 PROC 命令分别调用 uapi_vau_dfx_proc_read()、uapi_dpu_dfx_proc_read()、uapi_jpeg_dfx_proc_read()；声明可参考 /src/middleware/utils/common_headers/gpu/internal/drv_gpu_dfx.h。截屏文件或帧数据写入失败时，还应检查文件系统路径和剩余空间。
运行结果与判定
AT+GPU=smoke 或颜色条能正常显示，说明屏幕、基础 DPU 输出和显示接口基本可用；业务画面仍异常时，继续检查 VAU PROC、业务 Surface 参数和上游数据。截屏文件内容正常但实屏异常时，优先检查 DPU 到 LCD 的接口、面板时序或屏幕配置；截屏内容已异常时，优先检查 VAU、JPEG、视频帧和输入 Surface。
按模块查询 AT 命令与 PROC
本节列出的 PROC 均为 SDK 已提供的调试能力，不需要先为它们新增应用代码。VAU、DPU、JPEG 的命令由 /src/middleware/utils/at/at_gpu_cmd/at/at_gpu.c 分发；VENC 和 VDEC 的命令分别由 /src/middleware/utils/at/at_venc_cmd/at/at_venc.c 与 /src/middleware/utils/at/at_vdec_cmd/at/at_vdec.c 分发。VICAP 使用独立的 AT+ISP 调试入口，不经过 AT+GPU 分发。
| 模块 | 现有调试入口 | 查询内容 |
|---|---|---|
| VAU | AT+GPU=vau_proc |
合成任务与输出状态。 |
| DPU | AT+GPU=dpu_proc |
图层、输出与显示状态。 |
| JPEG | AT+GPU=jpeg_proc |
JPEG 编解码实例状态。 |
| VENC | AT+VENC=venc_proc,cat,... |
视频编码实例状态。 |
| VDEC | AT+VDEC=vdec_proc,...、AT+VDEC=vfmw_proc,... |
视频解码与帧管理状态。 |
| VICAP | AT+ISP=test_isp_dfx_show |
视频采集设备和 Pipe 状态。 |
调试概述
通过下发命令查询图形驱动各模块基本信息、状态。
只有在有对应图形业务的时候，抓取的proc信息才有实际内容，否则为空。
各模块 AT 命令汇总
下表列出 GPU 调试入口和参数。smoke、lcd_fill、颜色条、PROC、screen_cap、dpu_print 与 dpu_save_fb 由当前 g_at_gpu_func_map 直接分发；dpu_test_layer_destroy、dpu_test_layer_show 等测试用例命令依赖 SUPPORT_GPU_TEST 测试分支，使用前应确认对应配置已启用。
表 1 各模块AT命令
命令 |
功能 |
参数说明 |
|---|---|---|
AT+GPU=smoke |
GPU冒烟用例：颜色填充＋显示。 |
无参。 |
AT+GPU=dpu_cbar,0/1 |
color_bar使能控制。 |
使能标记。 0：不使能； 1：使能。 |
AT+GPU=screen_cap,layer_id |
DPU截屏，截屏成功后会输出文件路径和stride\height信息。 |
layer_id：DPU 图层号，未传入时默认读取图层 0。 |
AT+GPU=vau_proc |
输出VAU的DFX信息。 |
无参。 |
AT+GPU=jpeg_proc |
输出JPEG的DFX信息。 |
无参。 |
AT+GPU=dpu_proc,layer_id |
输出DPU层的信息。 |
layer_id范围为0~2。 |
AT+GPU=dpu_print,0/1/2/3 |
送显接口耗时统计输出使能。 |
打印模式。 0：关闭；1：仅打印FPS； 2：仅打印参数；3：全部打印。 |
AT+GPU=dpu_test_layer_destroy,0/1 |
销毁layer 0/1 |
0/1代表layer_id。 |
AT+GPU=dpu_test_layer_show,layer,show |
打开或关闭layer 0/1 |
layer：0/1。 show：0：关闭；1：打开。 |
AT+GPU=dpu_save_fb,0,1,1,10 |
保存DPU送显前FB数据。 |
参数1：layer_id取值0/1。 参数2：数据保存使能标记：0/1。 参数3：全屏保存标记：对局刷场景来说，填0只保存局刷区域数据，填1保存全屏数据，对全局送显场景，保存数据无差别。取值范围0/1。 参数4：save_cnt：保存的帧数。 |
VAU PROC
代码与接口参考： AT 命令分发位于 /src/middleware/utils/at/at_gpu_cmd/at/at_gpu.c，DFX 接口声明位于 /src/middleware/utils/common_headers/gpu/internal/drv_gpu_dfx.h，uapi_vau_dfx_proc_read() 的实现位于 /src/middleware/services/gpu/drv/vau/dfx/vau_dfx.c。
VAU PROC 简介
查询VAU主要函数耗时、主要函数调用次数、任务链表相关信息。
VAU PROC 信息
下发命令： AT+GPU=vau_proc
VAU模块的proc信息如图1所示。
VAU PROC 详解
uapi_vau_dfx_proc_read() 从 g_vau_dfx_info 输出以下三组累计信息；除时长外，计数在模块初始化后持续累加，不能把单次读取的计数直接当作帧率。
| 输出组/字段 | 代码中的含义与判读方法 |
|---|---|
*_cost |
create、destroy、blit、compose、submit、wait_done、wait_all 的接口耗时，单位为 μs。输出时由浮点值转换为整数；应在相同场景下比较多次采样，持续升高的 submit_cost 或 wait_done_cost 表示提交或等待完成变慢。 |
list pfcnt/time、vau_clk、axi_clk |
list pfcnt 是链表处理的性能计数，代码按 200 MHz AXI 时钟换算为时间；后两项是 VAU 与 AXI 时钟信息。比较性能前应确认时钟条件一致。 |
*_cnt |
create、cancel、destroy、blit、compose、submit、wait_done、wait_all 是对应接口调用次数；submit_cnt 后的 usr、drv 和 submit_from_int/user 用于区分提交来源；tasklet_*、execute_node_cnt 反映下半部处理和节点执行次数。 |
isr_cnt 及括号内子项 |
中断总次数及原因分布。node_end、tunl_done、list_end、disp_done 为完成类事件；timeout、bus_err、conflict、draw_err、*_oversize、dcmp_*_err 为异常类事件，业务稳定运行时不应持续增加。 |
suspend/resume |
VAU 电源管理挂起/恢复次数；显示或合成中断后应结合该计数确认是否发生过电源状态切换。 |
表 1 VAU proc信息说明
类别 |
参数 |
说明 |
|---|---|---|
time info 主要函数单次运行时长，单位：μs |
create_cost |
vau_create函数运行时长。 |
destroy_cost |
vau_destroy函数运行时长。 |
|
blit_cost |
vau_blit函数运行时长。 |
|
compose_cost |
vau_compose函数运行时长。 |
|
submit_cost |
vau_submit函数运行时长。 |
|
wait_done_cost |
vau_wait_for_done函数运行时长。 |
|
list pfcnt/time_us |
链表性能统计（时钟周期）/链表性能统计（μs）。 |
|
suspend/resume |
suspend/resume次数。 |
|
call count info 主要函数调用次数 |
create_cnt |
vau_create函数调用次数。 |
cancel_cnt |
vau_cancel函数调用次数。 |
|
destroy_cnt |
vau_destroy函数调用次数。 |
|
blit_cnt |
vau_blit函数调用次数。 |
|
compose_cnt |
vau_compose函数调用次数。 |
|
submit_cnt |
vau_submit函数调用次数。 |
|
usr |
vau_submit函数被用户调用次数。 |
|
drv |
vau_submit函数被驱动调用次数。 |
|
submit from int |
中断触发的submit次数。 |
|
submit from user |
用户触发的submit次数。 |
|
wait_done_cnt |
vau_wait_for_doen函数调用次数。 |
|
isr_cnt |
中断触发次数。 |
|
node_end |
节点完成中断次数。 |
|
tunl_done |
低时延中断次数。 |
|
timeout |
中断超时次数。 |
|
bus_err |
总线错误中断次数。 |
|
list_end |
链表结束中断次数。 |
|
disp_done |
送显node完成中断次数。 |
|
conflict |
中断冲突次数。 |
|
isr zero value |
中断状态为0次数。 |
|
tasklet_func_cnt |
tasklet_func函数调用次数。 |
|
execute_node_cnt |
节点执行次数。 |
|
hard int cnt |
寄存器值读取：VAU中断个数的计数。 |
|
hard start cnt |
寄存器值读取：链表start的个数计数。 |
|
hard list finish cnt |
寄存器值读取：链表完成的个数计数。 |
|
job_list 任务信息查询 |
last finished handle |
最后一次任务完成的handle号。 |
job create num |
任务创建总次数。 |
|
job submit(delay) |
延迟递交次数。 |
|
job unfinish |
等待递交任务个数。 |
|
job resume num |
硬件处理超时导致的resume次数。 |
|
job timeout num |
软件超时次数。 |
|
workqueen start |
workqueen start次数。 |
|
workqueen end |
workqueen end次数。 |
DPU PROC
代码与接口参考： AT 命令分发位于 /src/middleware/utils/at/at_gpu_cmd/at/at_gpu.c，DFX 接口声明位于 /src/middleware/utils/common_headers/gpu/internal/drv_gpu_dfx.h，uapi_dpu_dfx_proc_read() 的实现位于 /src/middleware/services/gpu/drv/dpu/dfx/dpu_dfx.c。
DPU PROC 简介
支持查询DPU层的相关信息，并且支持实时打印当前送显帧率与TE帧率等。
DPU PROC 信息
下发命令：
AT+GPU=dpu_proc,layer_id（layer_id范围：0~2）
AT+GPU=dpu_print,0/1/2/3（0：关闭；1：仅打印FPS；2：仅打印参数；3：全部打印）
DPU模块的proc信息如图1所示。
DPU PROC 详解
uapi_dpu_dfx_proc_read() 先输出指定图层，再输出显示设备状态。命令中的 layer_id 是图层号，当前代码检查范围为 0~2；dpu_print 的参数 0/1/2/3 分别表示关闭、仅 FPS、仅参数和全部实时打印。
| 输出组/字段 | 代码中的含义与判读方法 |
|---|---|
create、create_cnt |
图层是否已创建及其创建次数。create=0 时没有可显示的图层，后续宽高和地址不应作为有效业务画面分析。 |
width、height、stride、uv_stride、uv_offset |
当前运行 Surface 的尺寸、Y/RGB 行间距、UV 行间距及 UV 平面偏移。必须与送显 Surface 的实际格式匹配；YUV 格式中 uv_stride、uv_offset 异常会造成颜色或下半屏异常。 |
format、cmp_mode、canvas_addr |
分别来自图层颜色格式、压缩模式和当前帧物理地址。数值应与创建图层/送帧时配置一致；地址变化表示图层正在切换帧，静态画面下地址异常跳变需结合业务缓冲区生命周期排查。 |
disp_rect、crop_rect |
输出显示区域和源裁剪区域，顺序为 x/y/width/height。裁剪区域超出源 Surface 或显示区域超出面板有效区域会导致画面被截断、错位或无显示。 |
draw/flip/te(fps) 与 draw/flip/te(t) |
draw_fps 是刷新帧率，flip_fps 是显示帧率，te_fps 是 TE 信号帧率；后三项是对应累计次数。稳定显示时三者应与业务目标帧率及面板刷新率相符。 |
lowband_cnt、bus_err_cnt、dcmp_*_err_cnt、timeout_total |
低带宽、总线、解压配置/码流和超时等异常计数；稳定运行中不应持续增加。refresh_total、frm_done_total、wbc_done_total、frm_end_total、te_signal_total 是刷新和中断总计数，可用来检查链路是否持续推进。 |
表 1 DPU proc信息说明
类别 |
参数 |
说明 |
|---|---|---|
layer 0~2 proc |
create |
layer 0~2是否创建。 |
create_cnt |
创建次数。 |
|
width |
宽。 |
|
height |
高。 |
|
stride |
buffer行间距。 |
|
uv_stride |
uv数据行间距。 |
|
uv_offset |
uv数据偏移量。 |
|
format |
颜色格式。 |
|
cmp_mode |
压缩模式。 |
|
vblank |
是否开启vblank。 true：单buffer同步送显。false：双buffer异步送显。 |
|
chksum[ar/gb] |
输入checksum值。 |
|
disp_rect |
显示区域。 |
|
crop_rect |
剪切区域。 |
|
DISP proc |
work_mode |
是否cmd_mode。 |
disp_open |
打开标志。 |
|
open_cnt |
打开次数。 |
|
pixel_clk |
像素时钟。 |
|
refresh_rate |
刷新率。 |
|
hact/vact |
水平/垂直有效显示区。 |
|
hfb/vfb |
水平/垂直前向消隐区。 |
|
hbb/vbb |
水平/垂直后向消隐区。 |
|
hpw/vpw |
水平/垂直脉冲宽度。 |
|
dhd0_region |
显示区域。 |
|
lowband_cnt |
低带宽次数。 |
|
bus_err_cnt |
总线错误次数。 |
|
te_signal |
TE信号次数。 |
|
fresh/frm_done |
refresh次数/frm_done中断次数。 |
|
draw/flip/te(t) |
刷新/显示/TE中断的次数。 |
|
suspend/resume |
suspemd/resume次数。 |
|
chksum[RGB] |
输出checksum值。 |
|
送显接口耗时统计 |
wait_frm_done(us) |
函数wait_frm_done耗时。 |
fresh_intf_cost(us) |
函数dpu_layer_refresh耗时。 |
|
te_interrupt(us) |
两次TE中断的间隔时间。 |
|
draw/flip/te(fps) |
刷新/显示/TE中断的帧率。 |
JPEG PROC
代码与接口参考： AT 命令分发位于 /src/middleware/utils/at/at_gpu_cmd/at/at_gpu.c，DFX 接口声明位于 /src/middleware/utils/common_headers/gpu/internal/drv_gpu_dfx.h，uapi_jpeg_dfx_proc_read() 的实现位于 /src/middleware/services/gpu/drv/jpeg/dfx/jpeg_dfx.c。
JPEG PROC 简介
查询JPEG模块基本信息。
JPEG PROC 信息
下发命令：AT+GPU=jpeg_proc
JPEG模块的proc信息如图1所示。
JPEG PROC 详解
uapi_jpeg_dfx_proc_read() 直接打印 g_jpeg_dfx_info 中记录的 JPEG 缓冲区、颜色空间、缩放与接口耗时。
| 输出组/字段 | 代码中的含义与判读方法 |
|---|---|
open_times、close_times |
JPEG 设备打开和关闭累计次数。长时间运行后两者应基本配对；持续增大的差值通常表示仍有未关闭的使用实例，需要结合业务资源释放路径确认。 |
stream_buf_size、data_buf_size |
分别为压缩 JPEG 码流缓冲区和解码/输出数据缓冲区大小。缓冲区不足可能导致处理失败或输出不完整。 |
y_buf_stride、y_mcu_height、uv_buf_stride、uv_mcu_height |
Y、UV 平面的行间距与按 MCU 对齐后的高度；MCU 高度可能大于原图可见高度，解析或拷贝数据时必须使用输出的 stride/MCU 高度而非仅用图片宽高。 |
jpeg_color_space、output_color_space |
输入 JPEG 颜色空间和输出像素颜色空间的枚举值；应与解码配置和后续 VAU/DPU Surface 格式对应，二者不一致时优先检查颜色转换配置。 |
scale |
代码输出 1 << scale，即实际缩放因子为 1、2、4 等。它表示缩小倍率，而不是原始枚举值。 |
init_cost、start_cost、get_status_cost |
初始化、启动和查询状态的接口耗时，单位为 μs；输出时由浮点值转换为整数。应在同一图片尺寸和缩放配置下比较。 |
表 1 JPEG proc信息说明
类别 |
参数 |
说明 |
|---|---|---|
jpeg_proc |
open_times |
设备打开次数。 |
close_times |
设备关闭次数。 |
|
stream_buf_size |
流buf大小。 |
|
data_buf_size |
数据buf大小。 |
|
y_buf_stride |
y数据buf的stride。 |
|
y_mcu_height |
y MCU的高。 |
|
uv_buf_stride |
uv数据buf的stride。 |
|
uv_mcu_height |
uv MCU的高。 |
|
jpeg_color_space |
输入颜色格式。 |
|
output_color_space |
输出颜色格式。 |
|
scale |
缩放系数。 |
|
time info |
init_cost(us) |
函数jpeg_ioctl_decompress_init耗时。 |
start_cost(us) |
函数jpeg_ioctl_start_decompress耗时。 |
|
get_status_cost(us) |
函数jpeg_ioctl_get_decompress_status耗时。 |