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-activities	N/A	N/A	列出设备所有活动。
query-trace	N/A	N/A	列出设备所有的trace域。
enable-activities	{format activity string}	operator,memcpy	采集指定的活动。
export-activities	{filename}	N/A	以json格式导出设备活动到文件。
import-activities	{filename}	N/A	从json格式文件导入设备活动。

2.2. CPU 采集选项¶

: CPU 采集选项

选项	参数	默认值	说明
trace	{format domain string}	topstx,runtime	采集指定domain的trace。
topstx-domain-include	{format domain string}	N/A	如果使用trace指定的domain包含topstx，可以用topstx-domain-include指定采集自定义的domain的trace。
topstx-max-bytes-size	{size}	4096B	限制采集api trace时字节流或字符串的长度，包括domain名称、string类型的message、string或byte类型的payload、category/thread/device名称、以及注册的string等，超出则截断，数据范围是 1 ~ 1024 * 1024 B。
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可指定进程。
cancel	N/A	N/A	撤销采集，用于控制一个之前启动的topsprof进程，使用session可指定进程。

2.6. 高级选项¶

: 高级选项

选项	参数	默认值	说明
reset	N/A	N/A	重置topsprof内部状态，并删除profiler配置文件(~/..trace.topspti.conf)。当topsprof异常退出后使用。

2.7. 选项说明¶

冲突选项¶

以下每行内的选项不能同时使用：

    import-rawdata, import-profile
    import-profile, export-profile, export-visual-profiler
    export-profile, export-visual-profiler
    enable-activities, import-activities
    print-api-summary, print-gcu-summary, print-summary, print-summary-per-gcu
    session, session-new

单独使用选项¶

以下选项只能单独使用：

    export-activities, query-activities, plugin-list, help, version, reset, session-list

控制选项¶

以下选项只能单独或配合session使用：

    start, stop, cancel

启动应用采集限制项¶

以下选项只能启动应用采集时使用：

    profile-from-start, import-activities, 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

3. 采集模式¶

topsprof可以运行在以下任意一种模式中。

3.1. 统计模式¶

统计模式是topsprof的默认模式。在此模式，topsprof对每一个gcu算子或api输出一行结果。对每一行结果topsprof会输出最大值、最小值、平均值、调用信息等统计参数。topsprof输出会增加前缀 =={pid}==， {pid} 是被采集的应用程序进程id。示例：

$ topsprof --enable-activities operator ./simpleElemwiseAdd
==499== TOPSPROF is profiling process 499, session: 451, command: ./simpleElemwiseAdd
==499== Acquiring tasks...
==499== Got task list
[03-15-30] LOCAL: success connect to server
==499== TOPSPROF is attach task 50000, session: 451
[03-15-30] LOCAL: profile agent config done: 11000
[03-15-30] LOCAL: profile agent created: 12000
ok echo
process profile data[==========================================] 100% 0.015s
==499==      Time(%)     Time  Calls      Avg      Min      Max  Name
==499== GCU activities:
==499==       86.86%  56.61ms      1  56.61ms  56.61ms  56.61ms scalar_add(float*, float*, float*, unsigned long)
==499==       13.12%   8.55ms      1   8.55ms   8.55ms   8.55ms vector_add(float*, float*, float*, unsigned long)
==499==        0.02%  13.44us      1  13.44us  13.44us  13.44us warm_up()
==499==     Accumulate Time 65.17ms, Total Calls 3
==499==     Total Time 636.73ms
==499==

==499== CPU activities:
==499==     does not contain cpu kernel data.

==499== RUNTIME activities:
==499==       36.19% 171.85ms      5  34.37ms  11.53ms 122.74ms Stream_Synchronize
==499==       25.82% 122.58ms      3  40.86ms  28.77us 122.51ms TSStream_LaunchKernel
==499==       25.78% 122.38ms      1 122.38ms 122.38ms 122.38ms TSExecutor_ProfilerInit
==499==        3.11%  14.77ms      5   2.95ms  64.77us   4.14ms StreamExecutor_GetOrCreateHostMemObj
==499==        1.74%   8.27ms      2   4.14ms   4.09ms   4.19ms TSStream_MemcpyH2D
==499==        1.42%   6.72ms     18 373.40us   2.88us   1.94ms Context_SubmitTSStreamSyncTask
==499==        1.41%   6.72ms      2   3.36ms   3.28ms   3.44ms TSStream_MemcpyD2H
==499==        1.39%   6.60ms     95  69.46us   2.25us   2.25ms MemoryMgr_CreateBo
==499==        1.29%   6.10ms     95  64.24us   1.41us   2.24ms Driver_BoAlloc
==499==        1.21%   5.73ms     17 336.88us  23.70us   2.25ms MemoryMgr_AllocHost
==499==        0.21%   1.00ms     79  12.66us   2.77us 234.90us MemoryMgr_AllocDevice
==499==        0.10% 459.01us      3 153.00us   9.03us 432.70us Stream_LaunchKernelAsync
==499==        0.06% 299.12us     94   3.18us   1.31us  37.49us OsInterface_DtuMmap
==499==        0.06% 294.41us      2 147.20us 100.83us 193.58us StreamExecutor_MemcpyH2DSync
==499==        0.04% 200.26us     12  16.69us 461.00ns  41.31us TSStream_AutoReleaseResource
==499==        0.03% 165.10us      4  41.28us  23.45us  63.52us TSStream_CommandEmitWithReleaseFunc
==499==        0.03% 155.92us      4  38.98us  10.29us  82.41us TSStream_RecordEvent
==499==        0.03% 150.41us     33   4.56us   2.60us  22.78us MappedQueue_Emit
==499==        0.03% 130.98us     10  13.10us   8.81us  37.77us TSStream_DoHostCallback
==499==        0.02%  92.20us      4  23.05us  13.92us  40.88us TSStream_ProfilerTraceMemcpyInfo
==499==        0.01%  52.31us      3  17.44us   1.26us  41.60us TSExecutor_GetCachedOrCreateResourceBundle
==499==        0.01%  26.15us      4   6.54us 300.00ns  13.15us Stream_RecordEventAsync
==499==        0.00%  17.02us      3   5.67us   2.94us  10.69us Stream_LaunchKernel_CaptureParam
==499==        0.00%  15.32us      2   7.66us   2.62us  12.69us Stream_MemcpyH2DAsync
==499==        0.00%   6.46us      2   3.23us   2.79us   3.68us Stream_MemcpyD2HAsync
==499==        0.00%   4.15us      4   1.04us 280.00ns   2.01us Stream_DoHostCallbackAsync
==499==        0.00%   3.69us      3   1.23us 952.00ns   1.50us Stream_UpdateImplicitParameter
==499==     Accumulate Time 474.79ms, Total Calls 509
==499==

3.2. 跟踪模式¶

跟踪模式提供一个时间轴显示发生的活动和持续时间，每次调用会显示为一行。topsprof输出会增加前缀 =={pid}==， {pid} 是被采集的应用程序进程id。示例：

$ topsprof --enable-activities operator --print-gcu-trace ./simpleElemwiseAdd
==880== TOPSPROF is profiling process 880, session: 832, command: ./simpleElemwiseAdd
==880== Acquiring tasks...
==880== Got task list
[03-17-42] LOCAL: success connect to server
==880== TOPSPROF is attach task 50000, session: 832
[03-17-42] LOCAL: profile agent config done: 11000
[03-17-42] LOCAL: profile agent created: 12000
ok echo
process profile data[==========================================] 100% 0.014s
==880==      Start   Duration                        Node Name Name
==880== GCU trace:
==880==     0.00ns    13.32us                                  warm_up()
==880==   424.48ms    56.61ms                                  scalar_add(float*, float*, float*, unsigned long)
==880==   629.17ms     8.54ms                                  vector_add(float*, float*, float*, unsigned long)
==880==     Accumulate Time 65.16ms, Total Calls 3
==880==     Total Time 637.72ms

4. 采集控制¶

4.1. Session¶

topsprof启动应用时，会创建一个新session或者加入已有的session。 start/stop/cancel通过--session，指定要控制topsprof进程。当前系统只存在一个session时，可以省略session选项。 topsprof --session-list 会列出当前系统所有session。

4.2. 查询采集项¶

选项query-activities可用来查询可控制的采集项。示例：

$ topsprof --query-activities
==== User Activities:
    Memcpy,Memcpy_cdte,Memcpy_sdte,Operator

4.3. 使用字符串控制¶

topsprof支持使用kernel profiling流程采集数据。kernel profiling流程不依赖于编译期收集数据，支持factor和topscc程序，支持采集GCU kernel、ODTE、CDTE和SDTE信息。选项enable-activities的规则如下：可指定的activities包括Operator、Memcpy、Memcpy_cdte、Memcpy_sdte，指定多个时用逗号分隔。指定Operator表示采集GCU kernel；指定Memcpy表示采集ODTE；指定Memcpy_cdte表示采集CDTE；指定Memcpy_sdte表示采集SDTE。若需要采集CDTE或SDTE信息，对于factor程序，编译时需要export以下的环境变量：

export ENFLAME_GENERATE_PROFILE_META=true

对于topscc程序，使用topscc编译时需添加-fgcu-generate-profile-meta参数。注意：采集 Memcpy_sdte、Memcpy_cdte 会较大增加算子运行时候的采集性能信息的Overhead，导致算子整体运行时间变长，建议根据实际情况，开启该选项。

示例：

指定采集GCU kernel和ODTE

--enable-activities Operator,Memcpy

选项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可以导出json格式文件，用于编辑。json文件是树形节点，最末尾节点的type为activity。设置此节点isCheck项为true，即可开启相关采集项。随后使用import-activities可以导入编辑后的json文件，用于采集项控制。

4.5. 采集控制¶

首先启动一个topsprof用于采集，之后在另外的终端再开启topsprof进行控制；支持start/stop/cancel。一个常见的用法是先启动应用不采集，等合适时机手动开启采集，示例：

topsprof --profile-from-start off --enable-activities 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]

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