4. 测量偏移的工具链：Perfetto抓取、Systrace配置、自定义Hook工具

Choreographer vsync 偏移的精准测量依赖多维度的工具链。单一工具往往无法同时捕获内核级 vsync 时间戳、应用层回调延迟以及自定义插桩数据。本章构建完整的离线检测方案：Perfetto 用于高精度内核跟踪，Systrace 用于快速概览和旧版兼容，自定义 Hook 工具用于在关键路径注入毫秒级时间戳。三者协作形成下图所示的闭环数据流。

4.1 整体工具链与数据流

下图描述了从硬件 vsync 到用户态回调的完整数据采集链路，以及 Perfetto、Systrace、自定义 Hook 三路数据汇合后的脱敏对齐方式。

4.2 Perfetto 抓取 vsync 偏移数据

4.2.1 原理

Perfetto 通过 ftrace 捕获内核事件（如 drm_vblank_event、disp_vsync），同时通过 atrace 捕获应用层标记（Choreographer#doFrame）。两段时序在同一时间线上对齐后，可直接计算 vsync 信号到达与回调执行之间的差值。

4.2.2 配置抓取命令

使用 Perfetto 命令行工具抓取 5 秒数据，启用 GPU 与显示相关类别：

adb shell perfetto \
  -c - --txt \
  -o /data/misc/perfetto-traces/vsync_offset.pb \
  << 'EOF'
buffers: {
    size_kb: 65536
    fill_policy: RING_BUFFER
}
buffers: {
    size_kb: 8192
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
            ftrace_events: "drm/drm_vblank_event"
            ftrace_events: "power/cpu_frequency"
            atrace_categories: "am"
            atrace_categories: "gfx"
            atrace_apps: "com.android.systemui"
        }
    }
}
duration_ms: 5000
EOF

4.2.3 关键 Tracepoint 分析

抓取完成后，在 UI 中搜索 Choreographer#doFrame 和 drm_vblank_event，将事件时间戳导出为 CSV：

// Perfetto UI -> Export -> Trace as CSV
// 过滤后典型数据片段：
timestamp_ns,           name,                pid
5678912345678,          drm_vblank_event,    123
5678912351000,          Choreographer#doFrame, 456
// 偏移 = 5678912351000 - 5678912345678 = 5322 ns ≈ 5.3 μs

4.3 Systrace 配置快速排查

4.3.1 适用场景

Systrace 对 Android 8～11 支持良好，且可通过 systrace.py 一键开启 Choreographer 与 SurfaceFlinger 标签。适合首次接入项目时快速确认是否存在明显偏移（>5ms）。

4.3.2 命令行配置

python systrace.py \
  -t 10 \
  -a com.example.myapp \
  -o vsync_trace.html \
  gfx input view am wm freq idle

4.3.3 在 HTML 中定位偏移

打开生成的 HTML，使用 Ctrl+F 搜索 Choreographer#doFrame 标签，观察紧邻其上的 VSYNC-sf 或 VsyncDispatch 事件。若两者之间存在大于 16ms 的空隙，多为输入处理或 Binder 调度导致。

4.4 自定义 Hook 工具实现

4.4.1 设计思路

当 Perfetto/Systrace 无法覆盖某厂商的私有回调路径，或需要注入自定义日志逻辑时，使用 PLT Hook 或 inline Hook 劫持 Choreographer.postFrameCallback 或 android.view.Choreographer.nScheduleVsync。在 Hook 回调中调用 System.nanoTime() 记录时间戳，并通过 write(/sys/kernel/debug/tracing/trace_marker, ...) 写入 ftrace 缓冲区，使自定义时间戳自动出现在 Perfetto trace 中。

4.4.2 核心代码片段（PLT Hook 版）

// 使用 xHook 库实现 PLT Hook（仅演示，不包含完整错误检查）
#include "xhook.h"
#include <time.h>
#include <unistd.h>
#include <sys/syscall.h>

static int64_t (*original_nScheduleVsync)(JNIEnv*, jobject, jlong);

static int64_t hook_nScheduleVsync(JNIEnv* env, jobject thiz, jlong expectedVsyncTime) {
    int64_t hook_ts = get_nano_time();  // 自定义实现
    char buf[128];
    snprintf(buf, sizeof(buf), "C|%d|Hook_nScheduleVsync|%lld", getpid(), hook_ts / 1000);
    syscall(__NR_write, trace_marker_fd, buf, strlen(buf));  // 写入 ftrace mark
    return original_nScheduleVsync(env, thiz, expectedVsyncTime);
}

void install_hook() {
    xhook_register(".*\\.so$", "Java_android_view_Choreographer_nScheduleVsync",
                   (void*)hook_nScheduleVsync, (void**)&original_nScheduleVsync);
    xhook_refresh(0);
}

4.4.3 验证与调试

Hook 安装后，重新抓取 Perfetto trace，在 UI 中搜索 Hook_nScheduleVsync 标签。若未出现，检查：

• trace_marker_fd 是否以 O_WRONLY 打开（路径 /sys/kernel/debug/tracing/trace_marker）
• App 是否拥有 android.permission.TRACE_MARKER 或已 root
• Hook 时机需在 Zygote 之后、Choreographer 首次调用之前（推荐在 Application 构造函数中安装）

4.5 工具链常见问题速查

完成本章工具链搭建后，即可对 Choreographer vsync 偏移进行多维度测量，为后续第5章的“偏移量数学建模与阈值设定”提供准确数据输入。