1. 前言¶
1.1. 版权声明¶
以下条款适用于所有访问燧原产品和服务相关文档的用户或阅读者（以下统称“您”），本文档包括本文档提供的信息属于上海燧原科技股份有限公司和/或其子公司（以下统称“燧原”）或其许可方所有，且燧原保留不经通知随时对本文档信息或对本文档所述任何产品和服务做出修改的权利。本文档所含信息和本文档所引用燧原其他信息均“按原样”提供。燧原不担保信息、文本、图案、链接或本文档内所含其他项目的准确性或完整性。燧原不对本文档所述产品的可销售性、所有权、不侵犯知识产权、准确性、完整性、稳定性或特定用途适用性做任何暗示担保、保证。燧原可不经通知随时对本文档或本文档所述产品或服务做出更改，但不承诺因此更新本文档。
在任何情况下，燧原不对因使用或未使用本文档而导致的任何损害（包括但不限于利润损失、业务中断和信息损失等损害）承担任何责任。除非另行书面同意，燧原不对本文档承担任何责任，不论该责任因任何原因而产生或基于任何侵权理论。
本文档所列的规格参数、性能数据和等级基于特定芯片或计算机系统或组件测试所得。经该等测试，本文档所示结果反映了燧原产品在上述测试环境中的性能表现。测试系统配置及软硬件版本、环境变量等的任何变化都会影响产品或服务的实际性能，如产品或服务的实际效果与本文档描述存在差异的，均属正常现象。燧原不担保测试本文档中每种产品或服务的所有参数的准确性和稳定性。您自行承担对本文档中产品或服务是否适合并适用于您计划的应用进行评估以及进行必要测试的责任。您的使用环境、系统配置、产品设计等特性可能会影响燧原产品或服务的质量和可靠性并导致超出本文档范围的额外或不同的情况和/或要求，燧原对此不做任何担保或承担任何责任。
燧原®、Enflame ®和本文档中显示的其他所有商标、标志是上海燧原科技股份有限公司或其许可方申请和/或注册的商标。本文档并未明示或暗示地授予您任何专利、版权、商标、集成电路布图设计、商业秘密或任何其他燧原或其许可方知识产权的权利或许可。
本文档为燧原或其许可方版权所有并受全世界版权法律和条约条款的保护。未经燧原或其许可方的事先书面许可，任何人不可以任何方式复制、修改、出版、上传、发布、传输或分发本文档。为免疑义，除了允许您按照本文档要求使用本文档相关信息外，燧原或其许可方不授予其他任何明示或暗示的权利或许可。
本文档可能保留有与第三方网站或网址的链接，访问这些链接将由您自己作出决定，燧原并不保证这些链接上所提供的任何信息、数据、观点、图片、陈述或建议的准确性、完整性、充分性和可靠性。燧原提供这些链接仅仅在于提供方便，并不表示燧原对这些信息的认可和推荐，也不是用于宣传或广告目的。
您同意在使用本文档及其内容时，遵守国家法律法规、社会公共道德。您不得利用本文档及其内容从事制作、查阅、复制和传播任何违法、侵犯他人权益等扰乱社会秩序、破坏社会稳定的行为，亦不得利用本文档及其内容从事任何危害或试图危害计算机系统及网络安全的活动。
您同意，与您访问或使用本文档相关的所有事项，应根据中华人民共和国法律解释、理解和管辖。您同意，中国上海市有管辖权的法院具有相关的管辖权。
燧原对本文档享有最终解释权。
1.2. 版本记录¶
: 版本记录
| 时间 | 版本 | 作者 |
|---|---|---|
| 2022-1-18 | tosprof 2022.03 版本用户手册 | Enflame Tech |
| 2022-6-14 | tosprof 2022.06 版本用户手册 | Enflame Tech |
| 2022-9-28 | tosprof 2022.09 版本用户手册 | Enflame Tech |
| 2023-3-28 | tosprof 2023.03 版本用户手册 | Enflame Tech |
1.3. 名词解释¶
: 名词解释
| 术语 | 说明 |
|---|---|
| GCU | Deep Thinking Unit，面向深度学习领域推出的张量处理器。 |
| DMA | Direct Memory Access，是专门用于存储访问的硬件。 |
| DTE | Data Transformation Engine，数据转换引擎。 |
| SIP | 可扩展的智能处理器，GCU计算单元。 |
| CQM | Command Queue Micro-Control-Unit，GCU内部控制处理器。 |
| TS | Tops Scheduler，GCU 内部控制处理器。 |
| Profiling Meta | 在软件栈执行过程中，编译期搜集的数据，主要是指在Factor/LLIR两层搜集的Profiling行为的描述信息。 |
| Profiling Data | 在软件栈执行过程中，编译期搜集的数据，主要是指在通过硬件回报的Profiling行为的时间信息。 |
| VPD | visual profiler data，可用于visual profiler打开的文件格式。 |
1.4. 概述¶
topsprof分析工具使您能够从命令行收集和查看分析数据。topsprof支持在CPU和GCU上收集与tops相关的活动的时间线，包括内核执行、内存传输、内存集和tops API调用以及tops内核的事件或指标。分析选项通过命令行选项提供给topsprof。收集分析数据后，分析结果显示在控制台中，也可以保存以供topsprof或Tops Visual Profiler以后查看。
1.5. 使用方法¶
topsprof [options] [application] [application-arguments]
options需要以 – 或者 - 开头，示例 –print-api-summary，-print-api-summary。
options带参数可以用使用空格或者等号隔开，示例 –flag xxx 和 –flag=xxx 效果是等同的。
2. 命令行选项¶
2.1. GCU 采集选项¶
: GCU 采集选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| profile-from-start | on，off | on | 在启动时启用/禁用采集。如果禁用，稍后可以另启动一个topsprof进行控制。此选项不对api trace起作用。 |
| query-events | N/A | N/A | 列出设备所有事件。 |
| query-activities | N/A | N/A | 列出设备所有活动。 |
| query-trace | N/A | N/A | 列出设备所有的trace域。 |
| enable-events | {format event string} | N/A | 采集指定的事件。 |
| enable-activities | {format activity string} | N/A | 采集指定的活动。 |
| export-events | {filename} | N/A | 以json格式导出设备事件到文件。 |
| export-activities | {filename} | N/A | 以json格式导出设备活动到文件。 |
| import-events | {filename} | N/A | 从json格式文件导入设备事件。 |
| import-activities | {filename} | N/A | 从json格式文件导入设备活动。 |
| devices | {devices id} | N/A | 只采集指定设备的数据。输入‘,’分隔的设备id。注意：这里指定的设备列表要和enable-activities等选项指定设备的列表一致，除非enable-activities等选项指定的全部设备。 |
| metrics | {metric} | N/A | 设置Event/metric统计项。可以使用enable-events指定要采集的events。 |
| gcu-utilization | N/A | N/A | 开启gcu使用率采集。 |
| gcu-utilization-frequency | {frequency} | 100Hz | 设置gcu使用率采集频率，数据范围是 1 ~ 1000 Hz。 |
2.2. CPU 采集选项¶
: CPU 采集选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| trace | {format domain string} | N/A | 采集指定domain的trace。 |
| topstx-domain-include | {format domain string} | N/A | 如果使用trace指定的domain包含topstx，可以用topstx-domain-include指定采集自定义的domain的trace。 |
| cpu-profiling-callstack | N/A | N/A | 开启cpu堆栈采集，依赖perf工具，详情请参考附录。 |
| cpu-profiling-frequency | {frequency} | 100Hz | 设置cpu堆栈采集频率，数据范围是 1 ~ 100 Hz。 |
| cpu-utilization | N/A | N/A | 开启cpu使用率采集，依赖perf工具，详情请参考附录。 |
| memory-utilization | N/A | N/A | 开启cpu内存采集。 |
| utilization-frequency | {frequency} | 100Hz | 设置 memory-utilization 和 utilization-frequency 采集频率，数据范围是 1 ~ 100 Hz。 |
| kernel-callstack | N/A | N/A | 开启kernel堆栈采集，依赖内核工具ftrace。 |
| kernel-callstack-filter | {filter} | current | 开启kernel堆栈采集过滤, "all", "kmd", "current", 或"abc,def,ghi" |
2.3. 打印选项¶
: 打印选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| print-gcu-summary | N/A | N/A | 输出GCU数据的汇总报表。 |
| print-gcu-trace | N/A | N/A | 输出GCU数据并按时间排序。 |
| print-summary | N/A | N/A | 输出采集数据汇总报表。注意：如果没有指明打印格式，默认按此格式输出。 |
| print-summary-per-gcu | N/A | N/A | 输出采集数据汇总报表，并按设备区分。 |
| quiet | N/A | N/A | 安静模式，不做任何输出。 |
| print-app-log | N/A | N/A | 运行时打印应用输出。 |
2.4. 输入输出选项¶
: 输入输出选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| export-profile | {filename} | N/A | 导出采集数据。 |
| export-visual-profiler | {directory} | N/A | 导出采集数据，稍后可以在visual profiler中打开。 |
| import-profile | {filename} | N/A | 导入采集数据，可导入前一次export-profile或export-visual-profiler输出的数据。 |
| export-rawdata | {filename} | N/A | 导出原始数据。 |
| import-rawdata | {filename} | N/A | 导入原始数据。 |
| export-csv | {filename} | N/A | 以csv格式导出测试结果。 |
| visual-profiler-merge-from | {directory} | N/A | 选择一个目录，合并目录中的所有文件，目录中的所有文件都会被视为visual profiler(vpd)格式。 |
| visual-profiler-merge-to | {filename} | N/A | 合并多个visual profiler(vpd)格式，到一个文件，通过visual-profiler-merge-from指定输入项。 |
| log-file | {filename} | N/A | 开启后topsprof 所有输出会保存到文件。如果文件不存在，会自动创建。 |
| force-overwrite | N/A | N/A | 强制重写模式（已存在的文件会被覆盖）。 |
| help | N/A | N/A | 打印帮助信息。 |
| version | N/A | N/A | 打印版本信息。 |
| debug | N/A | N/A | 运行时会打印调试信息。 |
| debug-dump | N/A | N/A | 运行时会打印调试信息，并在当前目录生成dump文件供调试。 |
2.5. 控制选项¶
: 控制选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| session | {string} | N/A | 标记一个已存在的session。session名称只能是英文字符、数字、‘-’或‘_’。 |
| session-new | {string} | {pid} | 创建一个新的session，可用于控制标记。session名称只能是英文字符、数字、‘-’或‘_’。 |
| session-list | N/A | N/A | 列出系统上存在的session。 |
| start | N/A | N/A | 启动采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。 |
| stop | N/A | N/A | 停止采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。 |
| suspend | N/A | N/A | 暂停采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。 |
| resume | N/A | N/A | 恢复采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。 |
| cancel | N/A | N/A | 撤销采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。 |
2.6. 插件选项¶
: 插件选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| plugin | plugin_name args | N/A | 调用插件，--plugin "{plugin_name} args"。使用--plugin "{plugin_name} help"获得插件帮助。 |
| plugin-list | N/A | N/A | 列出所有支持的插件。 |
2.7. 高级选项¶
: 高级选项
| 选项 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| reset | N/A | N/A | 重置topsprof内部状态，并删除profiler配置文件(~/. |
| buffer | device，host | device | 设置采集buffer存放位置。 |
| device-buffer-size | {size in MBs} | 64 MB | 设置device memory大小(MBs)，数据范围是 1 ~ 64 。 |
| host-buffer-size | {size in MBs} | 1024 MB | 设置host memory大小(MBs)，数据范围是 1 ~ 1024 。 |
| host-ringbuffer-size | {size in MBs} | 16 MB | 设置host ringbuffer memory大小(MBs)，数据范围是 2 ~ 64 。 |
| watermark-threshold | {size in MBs} | 15 MB | 设置触发 host ringbuffer memory 搬运到 host memory 的阈值，数据范围是 1 ~ host-ring-buffer-size-1 。 |
2.8. 选项说明¶
启动应用采集必须项¶
以下选项在启动应用采集时必须指定其中一项：
enable-events, enable-activities, trace, import-events, import-activities, metrics, cpu-profiling-callstack, cpu-utilization, memory-utilization, memory-profile, gcu-utilization
冲突选项¶
以下每行内的选项不能同时使用：
import-rawdata, import-profile
import-profile, export-profile, export-visual-profiler
export-profile, export-visual-profiler
enable-events, import-events
enable-activities, import-activities
print-api-summary, print-gcu-summary, print-summary, print-summary-per-gcu
devices, import-events
devices, import-activities
session, session-new
单独使用选项¶
以下选项只能单独使用：
export-events, export-activities, query-events, query-activities, plugin-list, help, version, reset, session-list
控制选项¶
以下选项只能单独或配合session使用：
start, stop, suspend, resume, cancel
启动应用采集限制项¶
以下选项只能启动应用采集时使用：
devices, buffer, device-buffer-size, host-buffer-size, host-ringbuffer-size, watermark-threshold, profile-from-start, import-events, import-activities, enable-events, enable-activities, trace, topstx-domain-include, export-rawdata, print-app-log, cpu-profiling-callstack, cpu-profiling-frequency, cpu-utilization, memory-utilization, utilization-frequency, session-new, memory-profile, gcu-utilization
3. 采集模式¶
topsprof可以运行在以下任意一种模式中。
3.1. 统计模式¶
统计模式是topsprof的默认模式。在此模式，topsprof对每一个gcu算子或api输出一行结果。对每一行结果topsprof会输出最大值、最小值、平均值、调用信息等统计参数。topsprof输出会增加前缀 =={pid}==， {pid} 是被采集的应用程序进程id。 示例：
$ topsprof --enable-activities "*/general/operator" python3 ./r50.py
==14245== TOPSPROF is profiling process 14245, command: python3 ./r50.py
process profile data [=========================================] 100% 0.232s
==14245== ======== Profiling result:
==14245== Type Time(%) Time Calls Avg Min Max Name
==14245== GCU activities: 52.66% 514.88ms 250 2.06ms 364.54us 12.36ms common20_conv_dtu
==14245== 14.59% 142.66ms 857 166.46us 12.29us 2.74ms elementwise_fusion_dtu
==14245== 12.98% 126.92ms 106 1.20ms 195.84us 4.59ms batch_norm_grad_dtu
==14245== 9.04% 88.36ms 106 833.63us 248.83us 2.90ms batch_norm_training_dtu
==14245== 8.23% 80.44ms 66 1.22ms 511.23us 2.29ms dot_dtu
==14245== 0.62% 6.06ms 2 3.03ms 3.01ms 3.06ms common20_select_and_scatter
==14245== 0.48% 4.65ms 6 775.30us 354.30us 1.26ms slice_dtu
==14245== 0.36% 3.54ms 396 8.93us 3.33us 193.28us common20_copy
==14245== 0.29% 2.79ms 2 1.40ms 1.39ms 1.40ms common20_reduce_window
==14245== 0.22% 2.18ms 32 68.28us 5.63us 223.74us common20_reverse
==14245== 0.14% 1.39ms 6 230.87us 11.78us 669.44us elementwise_add_dtu
==14245== 0.10% 984.32us 44 22.37us 3.84us 161.28us common20_broadcast_in_dim
==14245== 0.08% 736.77us 6 122.79us 88.32us 157.70us cpu_convert
==14245== 0.07% 720.64us 60 12.01us 11.52us 15.10us elementwise_mul_dtu
==14245== 0.05% 526.59us 10 52.66us 7.94us 220.16us common20_reduce
==14245== 0.04% 399.62us 24 16.65us 13.06us 19.71us compare_dtu
==14245== 0.01% 103.94us 4 25.98us 19.20us 33.28us dot_general_dtu
==14245== 0.01% 97.28us 6 16.21us 15.36us 16.64us elementwise_and_dtu
==14245== 0.00% 47.87us 4 11.97us 11.78us 12.03us elementwise_div_dtu
==14245== 0.00% 36.61us 4 9.15us 4.35us 14.59us common20_convert
==14245== 0.00% 24.06us 2 12.03us 12.03us 12.03us elementwise_max_dtu
==14245== 0.00% 24.06us 2 12.03us 12.03us 12.03us elementwise_neg_dtu
==14245== 0.00% 23.81us 2 11.90us 11.78us 12.03us elementwise_abs_dtu
==14245== 0.00% 23.81us 2 11.90us 11.78us 12.03us elementwise_log_dtu
==14245== 0.00% 15.62us 1 15.62us 15.62us 15.62us common_rng_uniform
==14245== 0.00% 15.10us 2 7.55us 7.42us 7.68us common20_softmax_fusion
==14245== 0.00% 14.08us 2 7.04us 6.91us 7.17us concatenate_dtu
==14245== 0.00% 13.82us 2 6.91us 6.91us 6.91us common20_select
==14245== 0.00% 5.38us 2 2.69us 2.56us 2.82us common20_iota
3.2. 跟踪模式¶
跟踪模式提供一个时间轴显示发生的活动和持续时间，每次调用会显示为一行。topsprof输出会增加前缀 =={pid}==， {pid} 是被采集的应用程序进程id。 示例：
$ topsprof --print-gcu-trace --enable-activities "*/general/operator" python3 ./r50.py
==15202== TOPSPROF is profiling process 15202, command: python3 ./r50.py
process profile data [=========================================] 100% 0.247s
==15202== ======== Profiling result:
==15202== Start Duration Name
==15202== 0.00ns 15.62us common_rng_uniform
==15202== 16.13us 16.38us elementwise_fusion_dtu
==15202== 33.02us 4.61us common20_broadcast_in_dim
==15202== 38.14us 4.35us common20_copy
==15202== 43.01us 4.35us common20_copy
==15202== 47.87us 4.61us common20_copy
==15202== 52.74us 4.61us common20_broadcast_in_dim
==15202== 57.86us 4.10us common20_copy
==15202== 62.46us 4.61us common20_copy
==15202== 67.33us 4.61us common20_broadcast_in_dim
==15202== 72.45us 4.10us common20_copy
==15202== 77.06us 4.61us common20_copy
==15202== 82.18us 4.35us common20_copy
==15202== 87.04us 4.35us common20_copy
==15202== 91.90us 4.35us common20_copy
==15202== 96.77us 4.35us common20_copy
==15202== 101.63us 4.35us common20_copy
==15202== 106.24us 4.86us common20_broadcast_in_dim
==15202== 111.62us 4.35us common20_copy
==15202== 116.48us 4.61us common20_broadcast_in_dim
==15202== 121.60us 4.35us common20_copy
==15202== 126.46us 4.35us common20_copy
==15202== 131.33us 4.35us common20_copy
==15202== 136.19us 4.10us common20_copy
==15202== 140.80us 4.35us common20_copy
==15202== 145.66us 4.35us common20_copy
...
3.3. Event/metric 统计模式(Experimental T20 only)¶
Event/metric统计模式会输出硬件信息，并根据统计项输出不同列。topsprof输出会增加前缀 =={pid}==， {pid} 是被采集的应用程序进程id。 示例：
$ topsprof --metrics sip_busy_efficiency_per_op ./add.py
==16178== TOPSPROF is profiling process 16178, command: python3 ./add.py
process profile data [=========================================] 100% 0.046s
==16178== ======== Profiling result:
==16178== Type Time(%) Time Calls Avg Min Max Name
==16178== GCU activities: 100.00% 24.58us 1 24.58us 24.58us 24.58us elementwise_add_dtu
==16178== ======== Sip busy efficiency(Per-op Mode)
==16178== Index Name OP ID Duration
==16178== sip_busy_without_wait sip_busy_with_wait %
==16178== 0 elementwise_add_dtu 0 24.58us
==16178== sip:0:0:0 3094 7795 39.6921%
==16178== sip:0:0:1 2063 2063 100%
==16178== sip:0:0:2 2112 2112 100%
==16178== sip:0:0:3 2195 2195 100%
==16178== sip:0:0:4 2274 2274 100%
==16178== sip:0:0:5 2329 2329 100%
4. 采集控制¶
4.1. Session¶
topsprof启动应用时，会创建一个新session或者加入已有的session。 start/stop/suspend/resume/cancel通过–session，指定要控制topsprof进程。当前系统只存在一个session时，可以省略session选项。 topsprof –session-list 会列出当前系统所有session。
4.2. 查询采集项¶
选项query-activities或query-events可用来查询可控制的采集项。 示例：
$ topsprof --query-activities
==== Device(0 ~ 1):
Cluster(0 ~ 3):
CDMA(0 ~ 3):DMA VC Execution,DMA Busy
CQM(0 ~ 0):CQM Step Debug Packet,CQM Op Debug Packet,CQM Command Packet,CQM Loop Task,CQM Executable Execute,CQM Sleep
SDMA(0 ~ 5):DMA VC Execution,DMA Busy
SIP(0 ~ 5):SIP Busy
SIPPMC(0 ~ 5):
ClusterLite(0 ~ 1):
CDMA_LITE(0 ~ 1):DMA VC Execution,DMA Busy
SDMA_LITE(0 ~ 0):DMA VC Execution,DMA Busy
SIP_LITE(0 ~ 0):SIP Busy
General(0 ~ 0):Task Pipeline,Launch Kernel,Operator
TS(0 ~ 0):TS Record Stream,TS Wait Stream,TS VDEC Executable Launch,TS HCVG Executable Launch,TS CQM Executable Launch,TS Parse EDMA,TS VG Config,TS Memory Wait,TS Register Wait,TS Memory Write,TS Register Write,TS ISR,TS Parse GDMA,TS Read Packet,TS Command Packet
==== Api Trace:
RUNTIME(0 ~ 0):StreamExecutor_MemcpyD2DSync,StreamExecutor_MemcpyD2HSync,StreamExecutor_MemcpyH2DSync,StreamExecutor_GetOrCreateHostMemObj,Stream_LaunchCodeAsync,Stream_RunExecutableAsync,Stream_RunExecutablePerformance,Stream_MemcpyH2DAsync,Stream_MemcpyD2HAsync,TSStream_WaitMemory,TSStream_WaitEvent,TSStream_RunExecutablePerformanceMode,TSStream_RunExecutable,TSStream_Memset32,TSStream_MemcpyH2D,TSStream_MemcpyD2H,TSStream_MemcpyD2R,TSStream_MemcpyR2D,TSStream_MemcpyD2D,dtuMemcpyD2HASync,dtuWaitHostCallBackFunc,dtuRunExeAsync,FetchNodesData,dtuLaunchHostCallBackFunc,dtuGetExeDefaultStream
4.3. 使用字符串控制¶
topsprof支持使用传统流程或kernel profiling流程采集数据。kernel profiling流程不依赖于编译期收集数据，支持factor和topscc程序。 在S60上，kernel profiling流程支持采集gcu op、ODTE、CDTE和SDTE信息。 采用kernel profiling流程时，若需要采集CDTE或SDTE信息，对于factor程序，编译时需要export以下的环境变量：
export ENFLAME_GENERATE_PROFILE_META=true
对于topscc程序，使用topscc编译时需添加-fgcu-generate-profile-meta参数。
若使用传统流程，选项enable-activities使用字符串筛选指定要采集的activities，规则如下： 三层，由device/engine/activity组成。 四层，由device/cluster/engine/activity组成。 匹配规则如下：
使用名称：匹配名称符合的全部项。
使用名称 + 下标：匹配名称符合的第几项。
使用通配符 ‘.’ 或 ‘*’。
每层之中由 ‘,’ 分隔。
层与层之间由 ‘/’ 分隔。
多条匹配规则由 ‘|’ 符号相连。
all 匹配所有选项。
示例：
采集所有SIP Busy项
--enable-activities */*/*/SIP Busy
采集所有设备cluster1中所有SIP Busy项
--enable-activities */cluster1/*/SIP Busy
采集设备0/cluster1中所有sdma,cdma项
--enable-activities 0/cluster1/sdma,cdma/*
采集设备0中所有sdma,cdma的数据
--enable-activities 0/*/sdma,cdma/*
采集设备0/cluster1中所有sdma数据及设备1/cluster2中所有cdma
--enable-activities 0/cluster1/sdma/*|1/cluster2/cdma/*
采集所有数据
--enable-activities all
若使用kernel profiling流程，选项enable-activities的规则如下： 可指定的activities包括Operator、Memcpy、Memcpy_cdte、Memcpy_sdte，指定多个时用逗号分隔。 指定Operator表示采集gcu op；指定Memcpy表示采集ODTE；指定Memcpy_cdte表示采集CDTE；指定Memcpy_sdte表示采集SDTE。
示例：
指定采集CDTE和SDTE
--enable-activities Memcpy_cdte,Memcpy_sdte
选项trace及topstx-domain-include指定要采集trace events的domians，指定多个时用逗号分隔。其中trace指定已定义的domains；当trace指定的domains包含topstx时，可以用topstx-domain-include指定自定义的domains。
示例：
采集RUNTIME和TOPSPROFILER的trace events
--trace runtime,topsprofiler
4.4. 使用json文件控制¶
选项export-activities或export-events可以导出json格式文件，用于编辑。
json文件是树形节点，最末尾节点的type为activity或event。设置此节点isCheck项为true，即可开启相关采集项。
随后使用import-activities或import-events可以导入编辑后的json文件，用于采集项控制。
4.5. Event/metric项的控制¶
Event/metric 规则如下:
如果没有其他的采集项控制，Event/metric会使用内置的默认项进行采集。
如果使用enable-actities、import-actities等选项设置了要采集的activity，Event/metric的默认开启的actities会被覆盖。
如果使用enable-events、import-events等选项设置了要采集的events，Event/metric的默认开启的events会被覆盖。
4.6. 采集控制¶
首先启动一个topsprof用于采集，之后在另外的终端再开启topsprof进行控制；支持start/stop/suspend/resume/cancel。 一个常见的用法是先启动应用不采集，等合适时机手动开启采集，示例：
topsprof --profile-from-start off --enable-activities "*/general/operator" python xxx
等合适时机，启动新终端输入
topsprof start
5. 输出¶
5.1. Export/Import¶
选项export-profile可以用来生成结果文件；可以使用import-profile选项导入topsprof。 选项export-visual-profiler可以用来供visual-profiler使用的结果文件；可以用visual-profiler打开，也可以使用import-profile选项导入生成的vpd文件。 选项export-rawdata可以用来导出原始采集数据；可以使用import-rawdata选项导入topsprof。
5.2. 打印应用输出¶
启用选项print-app-log可以同时打印应用输出。
6. 分布式¶
6.1. 分布式启动采集¶
分布式支持通过mpirun和python ddp启动topsprof，示例如下：
mpirun [mpirun-arguments] topsprof [options] [application] [application-arguments]</br>
python -m torch.distributed.launch -no-python [python-arguments] topsprof [options] [application] [application-arguments]</br>
6.2. 合并输出结果¶
通过分布式调用，topsprof会为每个进程生成一份vpd文件；用户需要在运行结束后，将所有文件复制到一个文件夹，并调用topsprof进行合并。
topsprof --visual-profiler-merge-from {directory} --visual-profiler-merge-to {filename}
7. 附录¶
7.1. perf工具说明¶
perf是linux系统中提供的性能分析工具，常见的发行版都能提供安装；topsprof部分采集功能依赖perf。 topsprof会直接调用perf xxx进行分析，请确保perf在系统路径PATH中能够查找到。
ubuntu安装¶
sudo apt-get install linux-tools-common
sudo apt-get install linux-tools-"$(uname -r)"
sudo apt-get install linux-tools-generic
centos安装¶
yum install perf
从源码编译¶
git clone git://git.kernel.org/pub/scm/linux/kernel/git/acme/linux.git
cd linux/tools/perf
git checkout xxx #系统对应的内核版本
make
sudo make install
7.2. release note¶
2022.03 首次发布 2022.06 版本发布 2022.09 版本发布
增加visual-profiler-merge-from、visual-profiler-merge-to选项 2023.03 版本发布
增加T2x系列加速卡 AOT & HostProgram profiling support
增加S60系列launch kernel profiling support