@gracker/smartperfetto 1.0.13

package/strategies/knowledge-gc-dynamics.template.md

@@ -0,0 +1,65 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# ART Garbage Collection Dynamics
+
+## Mechanism
+
+Android Runtime (ART) uses a generational, mostly-concurrent garbage collector. Objects are allocated in managed heap regions and automatically reclaimed when no longer reachable.
+
+### GC Types
+
+| GC Type | Trigger | Typical Duration | Impact |
+|---------|---------|-----------------|--------|
+| **Young (minor)** | Young generation full | 1-5ms | Low -- only scans young objects |
+| **Full (major)** | Old generation pressure | 50-200ms | High -- scans entire heap |
+| **Explicit** | `System.gc()` call | 50-200ms | Avoidable -- developer triggered |
+| **Alloc** | Allocation failure (no free space) | Variable | Critical -- allocation blocked until GC completes |
+
+### Concurrent vs Stop-the-World
+
+Most of the GC work runs concurrently on a background thread. However, the **final marking phase** requires a brief stop-the-world pause where ALL application threads are suspended. During this pause:
+- No UI thread work proceeds
+- No RenderThread drawing
+- All threads frozen until marking completes
+
+## Impact on Frame Rendering
+
+When the main thread encounters `GC: Wait For Completion`, it is blocked waiting for a GC cycle to finish. This directly steals time from the frame budget. High heap pressure creates a vicious cycle: more allocations trigger more GCs, each stealing CPU time and causing thread pauses.
+
+**Allocation rate** is the key metric. A high allocation rate (e.g., during RecyclerView scrolling) triggers frequent young GCs, increasing cumulative CPU overhead and pause frequency.
+
+## Trace Signatures
+
+| What to Look For | Meaning |
+|-----------------|---------|
+| `android_garbage_collection_events` table | GC events with gc_type, duration, reclaimed_mb |
+| `GC: Wait For Completion` slice on main thread | Main thread blocked by GC |
+| `gc_running_dur` vs `gc_wall_dur` | Concurrent time vs total wall time |
+| gc_type = `young` with high frequency | Allocation pressure |
+| gc_type = `full` or `explicit` | Major collection -- significant pause risk |
+| Large `reclaimed_mb` | High allocation rate (allocating and discarding rapidly) |
+
+## Typical Solutions
+
+- **Reduce allocations in hot loops**: RecyclerView.onBindViewHolder, animation ticks, onDraw -- avoid creating objects per frame
+- **Use object pools**: Reuse Message, Rect, Paint objects instead of allocating new ones
+- **Avoid autoboxing**: Use SparseIntArray instead of HashMap<Integer, Integer>
+- **Remove explicit GC calls**: `System.gc()` forces a full collection -- almost never appropriate
+- **Avoid finalizers and weak references in hot paths**: They add GC pressure
+- **Increase heap if justified**: `android:largeHeap="true"` raises ceiling but does not fix the root cause
+- **Profile with allocation tracking**: Identify top allocating call sites and eliminate unnecessary allocations
+
+### Android 10+ CC GC (Concurrent Copying)
+
+Android 10+ 默认使用 CC GC，而非传统 CMS。
+
+**Trace 中的名称映射**：
+- `young concurrent copying GC` → Young (minor) GC 的 CC 实现
+- `concurrent copying GC` → Full GC 的 CC 实现
+- `GC: Wait For Completion` → CC GC 中等待并发标记/复制完成后的最终同步
+
+**CC GC 暂停模型**：
+- `FlipThreadRoots` 暂停：~1-3ms，所有线程短暂停顿完成根集翻转
+- 并发标记/复制阶段：不暂停应用线程，但消耗 CPU 和内存带宽
+- 频繁的 young CC GC（>5 次/秒）说明分配率过高

package/strategies/knowledge-harmonyos-rendering.template.md

@@ -0,0 +1,54 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# HarmonyOS 渲染管线（RS 三级流水线）
+
+HarmonyOS 使用 RenderService (RS) 三级流水线架构，与 Android 的 SurfaceFlinger + Choreographer 模型有本质区别。Agent 分析 HarmonyOS 渲染性能时必须基于此模型。
+
+## 三级流水线
+
+```
+① App 侧（UI Thread）
+   → ArkTS/JS UI 框架构建组件树
+   → ace::Component::Build / ace::Component::Update
+   → 生成 RS 指令 (RSCommand) 并发送到 RS 进程
+
+② RS 侧（RenderService 进程）
+   → RSRenderThread 接收 App 的 RSCommand
+   → 分为 2D 和 3D 渲染路径
+   → 2D: CPU 渲染 (Skia CPU)
+   → 3D: GPU 渲染 (Skia GPU / Vulkan)
+   → RSRender::Process → RSRender::RenderFrame
+
+③ GPU 侧
+   → GPU 合成 (RS 直接提交 GPU 命令)
+   → 不经过独立 compositor 进程
+   → Direct rendering 到 display
+```
+
+## 与 Android 渲染的区别
+
+| 维度 | Android | HarmonyOS |
+|------|---------|-----------|
+| 渲染架构 | App → SurfaceFlinger → HWC | App → RS → GPU (无独立 compositor) |
+| UI 框架 | View 系统 / Jetpack Compose | ArkUI (ace:: 框架) |
+| 帧调度 | Choreographer + Vsync | Vsync + RS 调度 |
+| 动画 | android.animation | ArkUI 动画系统 |
+
+## 常见渲染瓶颈
+
+1. **App 侧慢**：组件树更新耗时，ace::Component::Update 超过 Vsync 间隔
+2. **RS 侧慢**：复杂效果（blur/shadow/effect）导致 RS 渲染帧超时
+3. **GPU 侧慢**：过度绘制、大纹理、shader 复杂度高
+
+## 关键 tracing_mark_write 标签
+
+HarmonyOS ftrace 文本中，Slice 表的 name 列包含以下独有标签：
+
+| 标签 | 含义 |
+|------|------|
+| `ace::Component::Build` | ArkUI 组件构建 |
+| `ace::Component::Update` | ArkUI 组件更新 |
+| `RSRender::RenderFrame` | RS 渲染帧 |
+| `FFRT::*` | FFRT 任务调度 |
+| `H:FunctionName` | hitrace 用户态函数标记 |

package/strategies/knowledge-harmonyos-tools.template.md

@@ -0,0 +1,73 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# HarmonyOS Trace 采集工具
+
+## 采集命令
+
+### hdc（HarmonyOS Device Connector）
+相当于 Android 的 adb，用于连接鸿蒙设备。
+
+```bash
+# 查看连接设备
+hdc list targets
+
+# 文件传输
+hdc file send <local> <remote>
+hdc file recv <remote> <local>
+```
+
+### hitrace（鸿蒙 trace 采集）
+相当于 Android 的 perfetto/atrace，用于采集系统 trace。
+
+```bash
+# 采集文本格式 trace（兼容 Perfetto trace_processor_shell 解析）
+hdc shell hitrace --text -t 5 tag1 tag2 tag3 > trace.ftrace
+
+# 查看支持的 tags
+hdc shell hitrace -l
+```
+
+### 常用 hitrace tags
+
+| Tag | 说明 |
+|-----|------|
+| `ace` | ACE UI 框架（ArkUI 渲染） |
+| `ark` | ArkTS/Ark 虚拟机 |
+| `ffrt` | FFRT 任务调度 |
+| `sched` | CPU 调度 |
+| `freq` | CPU 频率 |
+| `disk` | 磁盘 I/O |
+| `net` | 网络事件 |
+| `hilog` | 系统日志 |
+| `hisysevent` | 系统事件 |
+| `hiperf` | 性能采样 |
+| `graphic` | 图形渲染 |
+| `binder` | IPC 通信 |
+| `memory` | 内存分配 |
+| `window` | 窗口管理 |
+| `app` | 应用生命周期 |
+| `power` | 功耗管理 |
+| `workq` | 工作队列 |
+
+## 文件格式
+
+| 格式 | 后缀 | 解析器 |
+|------|------|--------|
+| hitrace 文本 | `.ftrace` / `.atrace` | Perfetto trace_processor_shell |
+| Perfetto protobuf | `.pftrace` / `.perfetto-trace` | Perfetto trace_processor_shell |
+
+## hidumper
+
+系统信息 dump 工具，用于采集快照数据：
+
+```bash
+# CPU 信息
+hdc shell hidumper --cpuusage
+
+# 内存信息
+hdc shell hidumper --meminfo <pid>
+
+# 功耗信息
+hdc shell hidumper --power
+```

package/strategies/knowledge-lock-contention.template.md

@@ -0,0 +1,61 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# Lock Contention on Android
+
+## Mechanism
+
+When multiple threads compete for the same lock, all but the holder must wait. On Android, lock contention follows an escalation path:
+
+1. **Thin lock (fast path)**: ART uses a CAS (compare-and-swap) operation. If uncontended, acquisition costs ~1 instruction. No kernel involvement.
+2. **Fat lock (contended)**: When a thin lock is contended, ART inflates it to a fat lock backed by a **futex** (Fast Userspace muTEX). The waiting thread enters kernel sleep via `futex_wait`.
+3. **Kernel wait**: The blocked thread is removed from the CPU run queue entirely. It cannot do any work until the lock holder releases and the kernel wakes it.
+
+When lock contention occurs on the main thread, it directly steals frame budget time. The main thread cannot process input, run animations, or draw while waiting for a lock.
+
+## Monitor Contention (Java Locks)
+
+Java `synchronized` blocks use ART monitor locks. When contended:
+- A `monitor contention with <owner>` slice appears on the blocked thread
+- The `android_monitor_contention` table provides structured data: blocking_method, blocked_method, waiter_count, blocking_thread_name
+- High waiter_count indicates a hot lock with multiple threads competing
+
+## Futex Contention (Native/Kernel Level)
+
+Native locks (pthread_mutex, std::mutex) and inflated Java monitors both use futex under the hood:
+- blocked_function = `futex_wait_queue` in thread_state indicates kernel-level lock wait
+- Longer futex waits suggest the lock holder is doing significant work while holding the lock
+
+## Deadlock Pattern
+
+When Thread A holds Lock1 and waits for Lock2, while Thread B holds Lock2 and waits for Lock1, both threads enter `S(futex)` state indefinitely. In traces, look for two threads both showing extended `futex_wait_queue` states pointing at each other. The `android_monitor_contention_chain` table can reveal these circular dependencies.
+
+## Common Causes
+
+| Source | Why It's Contended |
+|--------|-------------------|
+| ContentProvider.onCreate() | Holds a global lock during initialization; queries from other threads block |
+| synchronized database access | Single-writer lock on SQLite; UI thread queries block on background writes |
+| SharedPreferences commit() | Holds lock during disk I/O; other reads/writes block |
+| Room database transactions | Write transactions hold exclusive lock; concurrent reads wait |
+| Custom singletons with synchronized | Any shared state guarded by a single lock |
+
+## Trace Signatures
+
+| What to Look For | Meaning |
+|-----------------|---------|
+| `monitor contention with <owner>` slice | Java monitor lock blocked, shows who holds it |
+| `android_monitor_contention` table | Structured contention data with methods and thread names |
+| `android_monitor_contention_chain` | Multi-hop blocking chains (A blocks B blocks C) |
+| blocked_function = `futex_wait_queue` | Kernel-level lock wait |
+| Thread state = `S` with futex blocked_function | Thread sleeping on contended lock |
+
+## Typical Solutions
+
+- **Reduce synchronized scope**: Hold locks for the minimum necessary duration. Move I/O and computation outside locked sections.
+- **Use concurrent data structures**: Replace synchronized HashMap with ConcurrentHashMap, synchronized List with CopyOnWriteArrayList for read-heavy access.
+- **Move I/O out of locked sections**: Never perform disk reads, network calls, or binder IPC while holding a lock.
+- **Use ReadWriteLock**: For read-heavy patterns, ReentrantReadWriteLock allows concurrent reads while serializing writes.
+- **Use StrictMode**: Enable `detectAll()` during development to catch lock contention and disk I/O on the main thread.
+- **Avoid nested locks**: Acquire locks in a consistent order across all threads to prevent deadlocks.
+- **Use async patterns**: Replace synchronized access with coroutines + Mutex or Channel for structured concurrency.

package/strategies/knowledge-pipeline-anchors.template.md

@@ -0,0 +1,136 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# 12 锚点详解（Article-Grounded）
+
+本模板是 S01 §12 个锚点的完整详解。Agent 在 jank 归因时应明确把症状定位到具体锚点。
+
+## 生产阶段（App 这一半）
+
+### ① vsync-app
+
+- **触发**：Display 给出下一次刷新节奏 → SF Scheduler 按 app workDuration 通过 EventThread 回调给订阅者（DisplayEventReceiver）
+- **现代实现**（Android 10+）：`VSyncTracker` / `VSyncDispatch` / `VSyncReactor`，基于预测 present time 反推应用工作起点（旧称 `app offset`，已是过时口径）
+- **观察点**：SF 进程的 `vsync-app` counter（注意：不代表你的 App 一定开始跑这一帧）；更可靠是 App 进程的 `Choreographer#doFrame` slice
+- **常见问题**：App 没注册 vsync（看不到 `Choreographer#doFrame`）、节奏不稳（counter 间隔抖动）
+
+### ② Choreographer.doFrame（5 callbacks）
+
+- **顺序**：`CALLBACK_INPUT → CALLBACK_ANIMATION → CALLBACK_INSETS_ANIMATION（Android 11+） → CALLBACK_TRAVERSAL → CALLBACK_COMMIT`
+- **CALLBACK_INPUT**：batched motion events 的帧同步重采样（不是普通输入排队）
+- **CALLBACK_ANIMATION**：属性动画、`OverScroller` 物理推进、插值器；fling 时这里推位移而非 Input
+- **CALLBACK_INSETS_ANIMATION**：系统栏 / 键盘动画引发的 insets 变化合并
+- **CALLBACK_TRAVERSAL**：`measure → layout → draw`（HWUI 路径）；末尾通过 `syncAndDrawFrame()` 交接 RenderThread
+- **CALLBACK_COMMIT**：本帧收尾，可用于厂商 pre-animation 提前计算下一帧
+- **常见问题**：某段独占预算（典型 TRAVERSAL 因深嵌套 ViewGroup measure 反复触发）
+
+### ③ syncAndDrawFrame
+
+- **位置**：`CALLBACK_TRAVERSAL` 执行栈末尾（不是独立 callback 类型）
+- **机制**：UI Thread 调用 `syncAndDrawFrame()` → native 经 `RenderProxy` 投递 `DrawFrameTask` 到 RenderThread
+- **同步边界**：UI Thread 可以 block 在 RenderThread 上，RenderThread 不能反过来 block UI Thread
+- **常见问题**：UI Thread 等 RenderThread 时间过长（DrawFrameTask 起跑晚 + sync 边界等不到放行）
+
+### ④ dequeueBuffer
+
+- **位置**：RenderThread `CanvasContext::draw()` 内部
+- **机制**：RT 从 BBQ 取一个可写 buffer slot，可能等 release fence signal
+- **BufferSlot 4 状态**：FREE → DEQUEUED → QUEUED → ACQUIRED（再回到 FREE）
+- **常见问题**：dequeueBuffer 长等通常不是 GPU 慢——是上一帧 slot 卡 ACQUIRED 状态（HWC 还在显示 / SF 没采纳 / 可用 slot 数不够深）
+
+### ⑤ Skia/GPU
+
+- **位置**：RenderThread `CanvasContext::draw()` 内部
+- **机制**：dirty 区域计算 → 准备 frame/surface → render pipeline `draw(...)` → GPU 命令下发 → `swapBuffers(...)`
+- **关键：CPU 侧 `queueBuffer` 返回 ≠ GPU 已写完**，由 acquire fence 异步保护
+- **常见问题**：GPU 慢（shader 复杂、overdraw、texture 重）、driver 反压（GPU stall）、swap 等待 vsync
+
+### ⑥ queueBuffer → Transaction
+
+- **关键事实**：`queueBuffer` 是 Producer 侧结束信号，**buffer 进入 BBQ**；不是直接到 SF
+- **BLAST 路径**：BBQ 把 buffer + 窗口状态打包成 Transaction → SF
+- **Legacy 路径**（Android 12 之前）：跨进程独立 BufferQueue 直接送 SF
+- **⚠️ BufferTx counter +1 时机**：在 SF 进程 Transaction 到达时，**不是** queueBuffer 返回时
+- **常见问题**：几何变化与 buffer 提交不同帧（Legacy 易撕裂；BLAST 用 sync transaction 解决）
+
+## 系统这一半
+
+### ⑦ vsync-sf
+
+- **触发**：SF Scheduler 按 sf workDuration 起跑（与 vsync-app 错开 phase）
+- **现代实现**：同 vsync-app，由 `VSyncTracker`/`VSyncDispatch` 基于预测 present time 反推
+- **观察点**：SF 进程的 `vsync-sf` counter
+- **常见问题**：SF Duration 抬升导致 sf phase 不够（多 layer 场景 / HWC 决策成本高）
+
+### ⑧ latch
+
+- **机制**：SF 进入本轮合成，对每个 target layer 等 acquire fence signal 后 `acquireBuffer`
+- **latch unsignaled buffer 优化**（AutoSingleLayer 模式）：单 layer 单 pending buffer + 无 sync transaction 时可先 latch 推进流程，到读取 buffer 内容更后面阶段再等 fence
+- **常见问题**：
+  - 没 latch 成功 → 沿用旧 buffer（多帧没采纳 = 用户看到旧画面，可能是 acquire fence 安全边界）
+  - 多 layer 场景：本轮 SF 只采纳部分 layer 新内容 → 用户看到"新旧混合"
+
+### ⑨ HWC validate / acceptChanges
+
+- **5 步谈判**：
+  1. SF 为每个 layer 声明期望 composition type（DEVICE/CLIENT/SOLID_COLOR/CURSOR/SIDEBAND）
+  2. SF 调 `validateDisplay()`，HWC 评估硬件能力
+  3. SF 调 `getChangedCompositionTypes()` 查 HWC 把哪些 layer 从 DEVICE 降级为 CLIENT
+  4. SF 对降级 layer 补做 client composition（⑩）
+  5. SF 调 `acceptDisplayChanges()` + `presentDisplay()` 送显
+- **HWC2 优化**：`skipValidate` 满足条件可跳过 validate 直接 present
+- **HWC 决策因素**：透明混合 / 旋转/缩放 / 受保护内容 / 视频字幕叠加 / 硬件 plane 数量上限 / 色彩空间 HDR
+- **常见问题**：layer 数量过多 / 包含 alpha / 旋转 → 触发 client composition 降级
+
+### ⑩ client composition（按需）
+
+- **触发**：HWC 把不能 device composition 的 layer 打回 SF
+- **机制**：SF 用 GPU 把这些 layer 合到 client target buffer，再交回 HWC 走 device composition
+- **代价**：GPU 工作压在 SF 进程，挤占应用自己的 GPU 预算 + 带宽
+- **常见问题**：相邻几帧 device ↔ client 反复抖动（HWC 决策不稳）→ 功耗周期性抬升
+
+### ⑪ presentDisplay
+
+- **HWC 调用**：实际把帧交给 display controller
+- **per-display per-frame**：每个 display 一份
+- **产出**：present fence（每次 present 一份）+ release fences（每个 layer 一份）
+
+### ⑫ scan-out + present fence
+
+- **scan-out**：display controller 把帧扫到 panel 像素
+- **present fence signal**：表示扫描输出真正完成
+- **关键**：用户什么时候看到 = present fence signal 时刻
+- **panel 因素**：刷新率切换、Panel 模式切换、扫描输出本身延迟（DSI / DP）
+- **常见问题**：present fence 持续偏晚但 latch 不晚 → 系统收尾段问题（panel/DVFS/扫描输出）
+
+## 锚点偏离表（17+ 类型）
+
+每个 pipeline yaml 的 `meta.deviation_anchors` 字段标注了相对 12 锚点的偏离描述。常见模式：
+
+| 偏离描述 | 类型 | 说明 |
+|---------|------|------|
+| `baseline_complete_1_to_12` | ANDROID_VIEW_STANDARD_BLAST | 完整覆盖 12 锚点 |
+| `baseline_legacy_no_blast_anchor_6` | ANDROID_VIEW_STANDARD_LEGACY | ⑥ 用 Binder BufferQueue，无 Transaction 原子性 |
+| `skips_renderthread_anchor_5` | ANDROID_VIEW_SOFTWARE | ⑤ 在 main thread 做 CPU 栅格化 |
+| `multi_path_anchor_4_5_6` | ANDROID_VIEW_MIXED | 多条 ④⑤⑥ 并行；⑧ 多 layer latch |
+| `serialized_multi_viewroot_anchor_2_3_4_5` | ANDROID_VIEW_MULTI_WINDOW | 同进程多窗口 ②③④⑤ 串行 |
+| `independent_anchor_4_5_6_join_at_8` | SURFACEVIEW_BLAST | 独立 ④⑤⑥；⑧ 多 layer latch |
+| `host_resample_anchor_4_5_anchor_5_anchor_6` | TEXTUREVIEW_STANDARD | 双次 ⑤（外部 GPU + 宿主 RT 重采样） |
+| `engine_anchor_2_3_4_5_6_at_engine_threads` | FLUTTER_SURFACEVIEW_* | Engine 接管 ②③④⑤⑥ |
+| `engine_to_host_resample_*` | FLUTTER_TEXTUREVIEW | Engine + 宿主 RT 双层处理 |
+| `host_rt_replay_anchor_5_at_host_rt` | WEBVIEW_GL_FUNCTOR | Chromium DDL 在宿主 RT replay |
+| `multiprocess_chromium_arch_*` | CHROME_BROWSER_VIZ | 多进程 Chromium 链路 |
+| `engine_main_loop_anchor_2_3_4_5_6` | GAME_ENGINE | 引擎主循环代替 Choreographer |
+| `no_vsync_app_hardware_sensor_trigger` | CAMERA_PIPELINE | sensor 节奏，不等 vsync-app |
+| `tunneled_skips_anchor_10_or_overlay_*` | VIDEO_OVERLAY_HWC | Tunneled 跳过 ⑩ client composition |
+| `ndk_direct_anchor_4_5_6_no_view_root` | SURFACE_CONTROL_API | NDK 绕过 ViewRootImpl |
+| `cross_cutting_feature_at_anchor_7_to_12` | VARIABLE_REFRESH_RATE | 显示策略改进，不是独立 pipeline |
+| `anchor_10_client_composition_when_hwc_rejects` | SOFTWARE_COMPOSITING | SF 侧 client composition 路径 |
+
+## 用法
+
+Agent 在归因时应：
+1. 先用 `pipeline_result` 选定 primary pipeline
+2. 查该 pipeline yaml 的 `meta.deviation_anchors` 知道正常情况下哪些锚点是基线、哪些已偏离
+3. 把症状定位到具体锚点（① doFrame 起晚？④ dequeue 卡？⑧ latch 失败？⑫ present 偏晚？）
+4. 再追该锚点的常见根因

package/strategies/knowledge-pipeline-fences.template.md

@@ -0,0 +1,158 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# 3 种 Fence 详解（Article-Grounded）
+
+本模板是 S01 §"三条 fence 的流向" + S05/S06 fence 三分法的完整详解。Agent 在涉及 fence 的诊断中必须明确用哪一种。
+
+## 总览对比
+
+| Fence | 方向 | 粒度 | 回答的问题 | 信号来源 |
+|-------|------|------|-----------|---------|
+| **acquire fence** | Producer → Consumer | per-buffer | GPU 写入完成？Consumer 何时安全读 | RT `queueBuffer` 时附上，SF latch 时等它 signal |
+| **present fence** | HWC → SF | per-display per-frame | 这一整轮 present 何时扫描到屏幕 | HWC `getPresentFence()` 每次 present 一份 |
+| **release fence** | HWC → Producer (经 SF/BQ) | per-layer per-frame | 上一帧 buffer 何时能被 Producer 安全复用 | HWC `getReleaseFences()` 每个 layer 一份，关联到上一轮 latch 的那块 buffer |
+
+⚠️ **关键认知**：三种 fence 方向不同、粒度不同、问题不同——**不能混用**。
+
+## 1. acquire fence
+
+### 含义
+Producer GPU 写入这块 buffer 何时完成。Consumer 读之前必须等它 signal，否则可能读到 GPU 半成品。
+
+### 流向
+```
+RenderThread (Producer)
+    ↓ queueBuffer 时附上 fence FD
+BufferQueue
+    ↓ buffer + fence 一起入队
+SurfaceFlinger (Consumer)
+    ↓ latch 时等 fence signal → acquireBuffer
+```
+
+### 触发等待
+- 在 ⑧ latch 阶段：SF 等 acquire fence signal 后才把这层新内容采纳为本轮合成输入
+- **latch unsignaled buffer 优化**（AutoSingleLayer）：单 layer 单 pending buffer 时可先 latch 推进流程，到读取 buffer 内容更后面阶段再等 fence——等待没消失，时机后移
+
+### 常见问题
+- **Producer GPU 写入慢** → acquire fence 晚 signal → SF latch 等待 → 该 layer 沿用旧内容
+- **多 layer 场景**：某条独立 layer 的 acquire fence 晚 signal，SF 选择沿用该 layer 旧 buffer，引发"新旧混合"
+- **TextureView 路径双层**：外部 Producer 的 acquire fence + 宿主自己窗口的 acquire fence 不能混淆
+
+### 不适用场景
+- **Software 路径**（lockCanvas/unlockCanvasAndPost）：acquire fence = `NO_FENCE`（CPU 写完即 ready，无 GPU 同步原语）
+- **MediaCodec Tunneled**：HAL sideband stream 不经 App BufferQueue，无 acquire fence
+
+## 2. present fence
+
+### 含义
+这一整轮 present 真正扫描到 panel 的时刻。这是端到端显示延迟最可靠的锚点。
+
+### 流向
+```
+HWC presentDisplay()
+    ↓ 每次 present 一份
+HWC getPresentFence()
+    ↓
+SurfaceFlinger
+    ↓ 用于回写"这一帧真正什么时候显示"
+FrameTimeline / FrameMetrics / JankStats
+```
+
+### 关键事实
+- **per-display per-frame**：每个 display 一份，每帧一份。多 layer / 多窗口场景下**不分 layer**——`present fence` 还是只有一份
+- **回答的不是 buffer 状态**，是 display 控制器的扫描输出完成时刻
+
+### 用途
+- **分析"用户什么时候看到这一帧"**：必须用 present fence，不能用 queueBuffer 或 latch 时刻
+- **校准系统帧节奏**：SF 根据真正显示完成时刻调整后续显示调度
+
+### 常见问题
+- **present fence 偏晚但 latch 不晚** → 问题在系统收尾阶段（Panel 模式切换 / 刷新率切换 / 扫描输出本身延迟 / DSI/DP 链路）
+- **多窗口 / 多 layer 场景**：present fence 仍然只有一份，不要按对象去找
+
+## 3. release fence
+
+### 含义
+HWC 何时不再使用上一轮 latch 的 buffer，buffer 何时可以被 Producer 安全复用。
+
+### 流向
+```
+HWC presentDisplay() 完成后
+    ↓ getReleaseFences() per-layer
+SurfaceFlinger
+    ↓ 经 BufferQueue 回传
+Producer (App / Camera HAL / MediaCodec / etc)
+    ↓ 下一次 dequeueBuffer 等它 signal 后才复用 slot
+```
+
+### 关键事实
+- **per-layer per-frame**：每个 layer 一份，关联到**上一轮**已 latch 的那块 buffer
+- **决定 dequeueBuffer 是否阻塞**：BufferSlot 4 状态（FREE/DEQUEUED/QUEUED/ACQUIRED）中 ACQUIRED → FREE 的转换由 release fence 触发
+
+### 用途
+- **分析"App 的 dequeueBuffer 为什么一直等"**：必须用 release fence，不能用 acquire/present fence
+- **诊断多 Producer back-pressure**（Camera 多路输出场景）：哪个 consumer 的 release fence 晚回，哪条 capture pipeline 就 back-pressure
+
+### 常见问题
+- **dequeueBuffer 长等** → 上一帧 slot 卡 ACQUIRED 状态：HWC 还在显示该 layer / SF 这一轮没释放 / 可用 slot 数不够深
+- **Camera ImageReader back-pressure**：App 不及时 `Image.close()` → ImageReader pool 满 → release fence 不回 → HAL 拿不到 buffer → capture pipeline 整体停摆
+
+## 共同 fence 注意事项
+
+### Software 路径不一定无 fence
+- `unlockAndPost()` 提交时 acquire fence = NO_FENCE（CPU 写完即 ready），SF latch 不等
+- **但 release fence 仍然存在**：HWC presentDisplay 后 getReleaseFences 仍返回，SF 经 BQ 回传给 Producer
+- Producer 仍可能卡 dequeueBuffer 等 release（即使是软件路径）
+
+### latch unsignaled buffer 不是跨 Surface 同步原语
+- 仅适用于"单 layer 单 pending buffer + 无 sync transaction / geometry change"等条件
+- 多 layer 同时更新、跨 Surface 同步场景下**不适用**
+- 不能替多条 Producer 做同帧协调
+
+### TextureView 双层 fence
+- **外部 Producer 侧 fence**：保护"宿主 updateTexImage 时不读到 GPU 没写完的外部内容"
+- **宿主窗口侧 fence**：保护"SF latch 时不读到宿主 GPU 没合成完的最终窗口结果"
+- 两层不能混淆，问题诊断要分别追
+
+### Tunneled 视频
+- MediaCodec → HAL sideband stream → HWC（App 进程不参与）
+- App 看不到 acquire/release fence——这些都在 HAL 层面
+- 排查需要 HAL trace tag + HWC trace tag
+
+## 诊断决策树
+
+```
+症状："用户看到画面晚"
+    ↓
+查 present fence 时刻 vs 应用 queueBuffer 时刻
+    ↓
+present fence 偏晚？
+    ├─ Yes (latch 不晚) → 系统收尾段问题（panel/DVFS/扫描输出/HWC client composition）
+    └─ No → 不是 fence 层面，是更早段问题
+
+症状："App dequeueBuffer 阻塞"
+    ↓
+查上一帧 slot 状态 + release fence 时刻
+    ↓
+release fence 晚回？
+    ├─ Yes → HWC 还在显示该 buffer / SF 没释放 / triple buffer 不足
+    └─ No → 不是 release fence，是 BBQ depth 配置问题
+
+症状："SF 读到半成品 / 跳帧"
+    ↓
+查 acquire fence signal 时刻 vs latch 时刻
+    ↓
+acquire fence 晚？
+    ├─ Yes → Producer GPU 写入慢
+    └─ No → 不是 acquire fence，是其他（latch unsignaled 时 fence 检查时机不同）
+```
+
+## 用法
+
+Agent 在涉及 fence 的诊断中应：
+1. **明确说哪一种 fence**（不能笼统说"fence 慢"）
+2. **回到对应的方向、粒度、问题**
+3. 区分 **TextureView 双层 fence**（外部 + 宿主）
+4. **Software 路径不要忘 release fence 仍存在**
+5. **Tunneled / 多 layer 场景下查 fence 要看对地方**