如需了解 Magma 的概览（包括背景、硬件要求和架构说明），请参阅 Magma：概览。
如需简要了解 Fuchsia 跟踪，请参阅 Fuchsia 跟踪指南。
本页概述了应对 Magma 系统驱动程序插桩的轨迹事件。
目前，对 ICD 代码进行插桩并添加跟踪记录没有任何要求。
数据流事件
流事件非常重要，因为它们会将跨进程和线程的相关跟踪事件关联起来。它们还有助于在同一线程内跨时间关联跟踪事件。
gfx 事件
应使用特定流程事件对 MSD 进行插桩，以将应用请求连接到 GPU，并将 GPU 连接到显示屏。这些流程事件都属于 gfx 类别。
event_signal
每当 MSD 发出信号量时，都应启动包含以下信息的流事件：
- 轨迹类型：流程开始
- 类别：
gfx - 名称：
event_signal - 流 ID：信号量的 koid
此流事件应由等待此信号量的客户端结束。
信号量
当 MSD 从客户端收到命令缓冲区时，应使用以下信息结束流事件。应为命令缓冲区中存在的每个信号信号量添加流事件结束。
- 轨迹类型：流程结束
- 类别：
gfx - 名称：
semaphore - 流 ID：信号量的 koid
客户端应在发送命令缓冲区之前启动此流程事件。
Magma 事件
应使用流事件对 MSD 进行插桩，这些事件可跨时间和客户端线程关联相关工作。这些流程事件应属于 magma 类别。
命令缓冲区
MSD 应在收到命令缓冲区后启动流事件。应对以下内容进行插桩：
- 接收命令缓冲区
- 在 GPU 上调度命令缓冲区
- 在 GPU 上运行命令缓冲区
- 完成命令缓冲区
每个流事件的名称和跟踪信息由各个 MSD 自行决定。
Semaphores
MSD 应在等待任何信号量时启动流事件。应对以下内容进行插桩：
- 等待信号量
- 对信号量发出信号
- 完成信号量等待
时长
应添加哪些轨迹时长由每个 MSD 自行决定。每个 MSD 都应力求以下各项的持续时间：
- 安排和执行命令
- 映射和取消映射缓冲区
- 处理来自客户端的 FIDL 请求
- 任何缓慢的操作，例如阻塞或休眠
添加插桩时，最好获取现有轨迹并查看 MSD 线程的 CPU 调度。如果 MSD 在 CPU 上运行且没有活跃时长的时间很长，则应添加更多插桩。
命名惯例
通常，MSD 时长应使用 magma 类别。对函数使用时长是最常见的情况，时长名称应与类和函数名称一致。函数内的时长应命名为子函数。对于 C++，这意味着时长应采用 PascalCase 命名法，对于 Rust，则应采用 snake_case 命名法。
计数器
GPU 利用率
应有一个包含以下信息的计数器：
- 类别：
magma - 名称：
GPU Utilization - 计数器 ID：0
- 项：
utilization
utilization 项应为介于 0 到 1 之间的双精度值，表示 GPU 在过去 100 毫秒内活跃执行工作的时间所占的百分比。
虚拟线程
虚拟线程是一种可视化在 CPU 时间轴以外的时间轴上同步发生的工作的方式。它们非常有助于表示 GPU 上正在进行的工作。
作业槽
应为 GPU 上可以同时执行命令缓冲区的每块硬件创建一个虚拟线程。
虚拟线程时长应在命令缓冲区在 GPU 上执行时开始，并应在命令完成时结束。
虚拟线程流应将时长与提交工作和处理完成情况的设备线程上的时长相关联。