Back to Details

hz-simpleperf-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Simpleperf Debug Skill

Simpleperf调试技巧

When to Use

使用场景

Use this skill when you need hardware-level CPU performance insights on Meta Quest devices:
  • Classifying whether an app is CPU-bound, memory-bound, or I/O-bound
  • Finding CPU hotspot functions consuming the most cycles
  • Measuring kernel vs userspace CPU overhead per thread
  • Identifying cache-thrashing or branch-prediction issues
  • Supplementing Perfetto trace analysis with hardware PMU counter data
This skill complements 
hz-perfetto-debug
. Perfetto shows what your app is doing over time. Simpleperf shows where the CPU is spending hardware cycles — cache misses, branch mispredictions, and instruction throughput that Perfetto can't see.
当你需要获取Meta Quest设备上硬件级别的CPU性能洞察时，可使用此技巧：
  • 分类应用是否为CPU-bound、memory-bound或I/O-bound
  • 找出占用最多周期的CPU热点函数
  • 测量每个线程的内核态与用户态CPU开销
  • 识别缓存抖动或分支预测问题
  • 用硬件PMU计数器数据补充Perfetto追踪分析
此技巧可与
hz-perfetto-debug
互补。Perfetto展示应用随时间的运行行为，而Simpleperf则展示CPU硬件周期的消耗位置——包括Perfetto无法捕捉的缓存未命中、分支预测错误和指令吞吐量情况。

VR Performance Context

VR性能背景

Quest devices run on mobile ARM SoCs with strict thermal and power budgets. CPU-bound apps hit frame drops when:
Refresh RateCPU Frame BudgetNotes
120 Hz8.3 msTight — simpleperf critical for finding hotspots
90 Hz11.1 msDefault target for most apps
72 Hz13.9 msFallback for heavier apps
Simpleperf's hardware counters reveal bottlenecks invisible to software tracing.
Quest设备运行在移动ARM SoC上，有着严格的散热和功耗预算。当应用受CPU限制时，会出现掉帧情况：
刷新率CPU帧预算说明
120 Hz8.3 ms预算紧张——simpleperf对查找热点至关重要
90 Hz11.1 ms多数应用的默认目标
72 Hz13.9 ms重型应用的 fallback 选项
Simpleperf的硬件计数器能揭示软件追踪无法发现的瓶颈。

metavr Setup

metavr设置

Simpleperf profiling is powered by the metavr CLI. Invoke via 
npx
— no install required:
bash
npx -y metavr --version
Examples below use the bare 
metavr
command for brevity. If 
metavr
is not on PATH, invoke the same CLI via 
npx -y metavr <args>
(the CLI is published under the npm package 
metavr
). Connect your Quest via USB with developer mode enabled.
Simpleperf分析由metavr CLI提供支持，可通过
npx
调用——无需安装：
bash
npx -y metavr --version
以下示例为简洁起见使用裸
metavr
命令。若
metavr
不在PATH中，可通过
npx -y metavr <args>
调用同一CLI（该CLI发布在npm包
metavr
下）。请通过USB连接Quest设备并启用开发者模式。

Quick Start Workflow

快速开始流程

1. Classify the Workload

1. 工作负载分类

Before optimizing, determine the bottleneck type:
bash
undefined
优化前，先确定瓶颈类型：
bash
undefined

Classify the foreground app's workload (10-second sample)

对前台应用的工作负载进行分类（采样10秒）

metavr perf simpleperf classify
metavr perf simpleperf classify

Target a specific app

针对特定应用

metavr perf simpleperf classify --app com.example.myapp
metavr perf simpleperf classify --app com.example.myapp

Custom duration

自定义时长

metavr perf simpleperf classify --duration 15

Returns a classification with evidence:

| Classification | Indicator | Optimization Strategy |
|---------------|-----------|----------------------|
| **CPU-bound** | High IPC, low stall ratio | Optimize algorithms, reduce draw calls, batch work |
| **Memory-bound** | High stall ratio (stalled-cycles-backend / cpu-cycles) | Reduce cache misses, improve data locality, shrink working set |
| **I/O-bound** | High context switches per second | Reduce blocking I/O, use async, minimize thread contention |
metavr perf simpleperf classify --duration 15

返回带依据的分类结果：

| 分类 | 指标 | 优化策略 |
|---------------|-----------|----------------------|
| **CPU-bound** | 高IPC、低停顿占比 | 优化算法、减少绘制调用、批量处理任务 |
| **Memory-bound** | 高停顿占比（stalled-cycles-backend / cpu-cycles） | 减少缓存未命中、提升数据局部性、缩小工作集 |
| **I/O-bound** | 每秒上下文切换次数高 | 减少阻塞式I/O、使用异步操作、最小化线程竞争 |

2. Record CPU Hotspots

2. 记录CPU热点

Capture a CPU cycle profile to find the most expensive functions:
bash
undefined
捕获CPU周期分析数据，找出最耗时的函数：
bash
undefined

Record CPU hotspots for the foreground app

记录前台应用的CPU热点

metavr perf simpleperf record
metavr perf simpleperf record

Custom frequency and duration

自定义采样频率和时长

metavr perf simpleperf record --frequency 4000 --duration 10
metavr perf simpleperf record --frequency 4000 --duration 10

Target a specific app

针对特定应用

metavr perf simpleperf record --app com.example.myapp

The recording samples CPU cycles at the specified frequency (default 4000 Hz) and generates a profile showing which functions consume the most CPU time.
metavr perf simpleperf record --app com.example.myapp

记录会按指定频率（默认4000 Hz）采样CPU周期，并生成分析报告，展示哪些函数消耗最多CPU时间。

3. Measure Kernel Overhead

3. 测量内核开销

Determine how much CPU time is spent in kernel vs userspace per thread:
bash
undefined
确定每个线程在内核态与用户态的CPU时间占比：
bash
undefined

Measure kernel overhead for the foreground app

测量前台应用的内核开销

metavr perf simpleperf kernel-overhead
metavr perf simpleperf kernel-overhead

Custom duration

自定义时长

metavr perf simpleperf kernel-overhead --app com.example.myapp --duration 10

Returns per-thread breakdown of user-mode vs kernel-mode CPU cycles. High kernel overhead (>20%) in a thread suggests:

- Excessive syscalls (file I/O, memory allocation)
- Driver overhead (GPU command submission, sensor access)
- Lock contention in kernel synchronization primitives
metavr perf simpleperf kernel-overhead --app com.example.myapp --duration 10

返回每个线程的用户态与内核态CPU周期细分结果。线程的内核开销过高（>20%）可能表明：

- 系统调用过多（文件I/O、内存分配）
- 驱动开销过大（GPU命令提交、传感器访问）
- 内核同步原语中的锁竞争

Analysis Workflow

分析流程

Step 1: Classify First

步骤1：先进行分类

Always start with classification. This prevents wasting time optimizing the wrong thing.
bash
metavr perf simpleperf classify --app com.example.myapp --duration 10
Decision tree based on results:
  • CPU-bound → Record hotspots (Step 2a), look at top functions
  • Memory-bound → Record with cache-miss events, check data access patterns
  • I/O-bound → Check kernel overhead, look at thread contention in Perfetto
始终从分类开始，避免在错误方向上浪费时间。
bash
metavr perf simpleperf classify --app com.example.myapp --duration 10
基于结果的决策树：
  • CPU-bound → 记录热点（步骤2a），查看顶级耗时函数
  • Memory-bound → 记录缓存未命中事件，检查数据访问模式
  • I/O-bound → 检查内核开销，在Perfetto中查看线程竞争情况

Step 2a: CPU-Bound Apps — Find Hotspots

步骤2a：CPU-bound应用——查找热点

bash
metavr perf simpleperf record --app com.example.myapp --duration 10
Review the top functions by CPU cycle consumption. Common VR hotspots:
Function PatternLikely CauseFix
Physics.*
/ 
PhysX
Complex physics simulationReduce collider count, simplify meshes, increase fixed timestep
Render*
/ 
Draw*
Too many draw callsBatch materials, use GPU instancing, reduce unique materials
GC_*
/ 
gc_alloc
Garbage collection pressurePool allocations, avoid per-frame allocations
memcpy
/ 
memmove
Large data copiesUse references, reduce buffer sizes, avoid unnecessary copies
LZ4_*
/ 
compress
Asset decompressionPre-decompress, use lighter compression, cache results
bash
metavr perf simpleperf record --app com.example.myapp --duration 10
查看按CPU周期消耗排序的顶级函数。VR应用中常见的热点：
函数模式可能原因修复方案
Physics.*
/ 
PhysX
复杂物理模拟减少碰撞体数量、简化网格、增加固定时间步长
Render*
/ 
Draw*
绘制调用过多批处理材质、使用GPU实例化、减少独特材质数量
GC_*
/ 
gc_alloc
垃圾回收压力对象池化、避免每帧分配
memcpy
/ 
memmove
大数据拷贝使用引用、减小缓冲区大小、避免不必要的拷贝
LZ4_*
/ 
compress
资源解压缩预解压缩、使用轻量压缩、缓存结果

Step 2b: Memory-Bound Apps — Check Cache Behavior

步骤2b：Memory-bound应用——检查缓存行为

If classification shows memory-bound, the issue is likely cache misses or memory bandwidth:
  • Large working sets thrashing L1/L2 cache
  • Random access patterns defeating prefetcher
  • False sharing between threads on adjacent cache lines
Use Perfetto 
hz-perfetto-debug
to correlate memory-bound regions with specific code paths.
若分类结果为memory-bound，问题通常出在缓存未命中或内存带宽：
  • 大工作集导致L1/L2缓存抖动
  • 随机访问模式破坏预取机制
  • 线程间相邻缓存行的伪共享
使用Perfetto的
hz-perfetto-debug
将内存受限区域与特定代码路径关联起来。

Step 3: Measure Kernel Overhead

步骤3：测量内核开销

bash
metavr perf simpleperf kernel-overhead --app com.example.myapp
Interpreting results by thread:
ThreadExpected Kernel %High Kernel % Indicates
Main/Game thread< 5%Excessive file I/O, logging, or allocations
Render thread5-15%Normal (GPU driver overhead). >20% = driver issue
Worker threads< 5%Thread synchronization overhead
Audio thread< 10%Normal for audio HAL calls
bash
metavr perf simpleperf kernel-overhead --app com.example.myapp
按线程解读结果：
线程预期内核占比内核占比过高表明
主线程/游戏线程< 5%文件I/O、日志或分配操作过多
渲染线程5-15%正常（GPU驱动开销）。>20% = 驱动问题
工作线程< 5%线程同步开销过大
音频线程< 10%音频HAL调用的正常情况

Step 4: Combine with Perfetto

步骤4：与Perfetto结合使用

Simpleperf tells you where cycles go. Perfetto tells you when and in what context. Use together:
  1. Simpleperf classification reveals the bottleneck type
  2. Simpleperf hotspot recording identifies the expensive functions
  3. Perfetto trace (
    metavr perf capture
    ) shows when those functions run relative to frame boundaries
  4. Use 
    metavr perf query
    to correlate function timing with frame drops
Simpleperf告诉你周期消耗在哪里，Perfetto告诉你何时消耗以及在什么上下文下消耗。结合使用：
  1. Simpleperf分类揭示瓶颈类型
  2. Simpleperf热点记录识别耗时函数
  3. Perfetto追踪（
    metavr perf capture
    ）展示这些函数相对于帧边界的运行时机
  4. 使用
    metavr perf query
    将函数时序与掉帧关联起来

Common Pitfalls

常见陷阱

  • Don't profile in thermal throttling. Let the device cool before recording — throttled clocks distort cycle counts. Check thermal state first with 
    metavr device info
    .
  • Sample duration matters. Short recordings (<5s) may not capture representative behavior. Use at least 10 seconds for classification.
  • simpleperf requires shell access. If 
    adb shell simpleperf
    fails, ensure developer mode is enabled and USB debugging is authorized.
  • Frequency vs accuracy tradeoff. Higher sampling frequency (>8000 Hz) can perturb the workload on mobile SoCs. Default 4000 Hz is a good balance.
  • Classification is a snapshot. An app can be CPU-bound during gameplay and I/O-bound during scene loads. Profile the specific scenario you're optimizing.
  • 不要在热节流状态下分析。记录前让设备冷却——降频会扭曲周期计数。先用
    metavr device info
    检查热状态。
  • 采样时长很重要。短时间记录（<5秒）可能无法捕捉代表性行为。分类至少使用10秒采样。
  • simpleperf需要shell权限。若
    adb shell simpleperf
    失败，请确保已启用开发者模式并授权USB调试。
  • 频率与精度的权衡。高采样频率（>8000 Hz）可能干扰移动SoC的工作负载。默认4000 Hz是较好的平衡。
  • 分类只是快照。应用在游戏过程中可能是CPU-bound，在场景加载时可能是I/O-bound。针对你要优化的特定场景进行分析。

References

参考资料

For detailed guides on specific topics, see:
  • Workload Classification — PMU counter interpretation and bottleneck identification
  • CPU Hotspot Analysis — Recording and analyzing CPU cycle profiles
  • Kernel Overhead — Measuring and reducing kernel-mode CPU usage
有关特定主题的详细指南，请参阅：
  • Workload Classification — PMU计数器解读与瓶颈识别
  • CPU Hotspot Analysis — 记录与分析CPU周期分析报告
  • Kernel Overhead — 测量与减少内核态CPU使用率