llvm-profdata - Profile 数据工具¶
概要¶
llvm-profdata command [args…]
描述¶
llvm-profdata 工具是一个用于处理 Profile 数据文件的小型实用程序。
命令¶
MERGE¶
概要¶
llvm-profdata merge [options] [filename…]
描述¶
llvm-profdata merge 接受由 PGO Instrumentation 生成的多个 Profile 数据文件，并将它们合并成一个单独的索引 Profile 数据文件。
默认情况下，Profile 数据在不修改的情况下合并。这意味着每个输入文件的相对重要性与其包含的样本或计数数量成正比。一般来说，较长训练运行的输入将被解释为比短训练运行更重要。根据训练运行的性质，通过使用 -weighted-input 选项调整每个输入文件的权重可能很有用。
通过 -weighted-input、-input-files 或通过位置参数传入的 Profile 文件，每次看到它们时都会被处理一次。
选项¶
- --help¶
打印命令行选项的摘要。
- --output=<output>, -o¶
指定输出文件名。Output 不能是
-，因为生成的索引 Profile 数据无法写入标准输出。
- --weighted-input=<weight,filename>¶
指定输入文件名以及权重。提供的
filename的 Profile 计数将按提供的weight缩放（乘法），其中weight是十进制整数 >= 1。未使用此选项指定的输入文件将分配默认权重 1。示例如下所示。
- --input-files=<path>, -f¶
指定一个文件，其中包含要合并的文件列表。此文件中的条目以换行符分隔。以 ‘#’ 开头的行将被跳过。条目的格式可以是 <filename> 或 <weight>,<filename>。
- --remapping-file=<path>, -r¶
指定一个文件，其中包含从输入 Profile 中的符号名称到应在输出 Profile 中使用的符号名称的重映射。该文件应包含
<input-symbol> <output-symbol>形式的行。空白行和以#开头的行将被跳过。llvm-cxxmap 工具可用于生成符号重映射文件。
- --instr (默认)¶
指定输入 Profile 是基于 Instrumentation 的 Profile。
- --sample¶
指定输入 Profile 是基于采样的 Profile。
生成文件的格式可以通过以下三种方式之一生成
- --binary (默认)¶
使用二进制编码发出 Profile。对于基于 Instrumentation 的 Profile，输出格式是索引二进制格式。
- --extbinary¶
使用可扩展二进制编码发出 Profile。此选项只能与基于采样的 Profile 一起使用。启用压缩后，可扩展二进制编码可以更紧凑，并且加载速度比默认二进制编码更快。
- --text¶
以文本模式发出 Profile。此选项也可用于基于采样和基于 Instrumentation 的 Profile。当使用此选项时，Profile 将以文本格式转储，该格式可由 Profile 读取器解析。
- --gcc¶
使用 GCC 的 gcov 格式发出 Profile（尚不支持）。
- --sparse[=true|false]¶
不发出执行计数为 0 的函数记录。只能与 -instr 结合使用。默认为 false，因为它可能会抑制 PGO 期间的编译器优化。
- --num-threads=<N>, -j¶
使用 N 个线程执行 Profile 合并。当 N=0 时，llvm-profdata 会自动检测要使用的适当线程数。这是默认设置。
- --failure-mode=[any|all]¶
设置失败模式。有两个选项：“any” 导致合并命令在任何 Profile 无效时失败，“all” 导致合并命令仅在所有 Profile 都无效时失败。如果设置了“all”，则来自任何无效 Profile 的信息将从最终合并的产品中排除。默认失败模式为“any”。
- --prof-sym-list=<path>¶
指定一个文件，其中包含要在 Profile 中生成的 Profile 符号列表。此选项只能与 extbinary 格式的基于采样的 Profile 一起使用。此文件中的条目以换行符分隔。
- --compress-all-sections=[true|false]¶
在写入 Profile 时压缩所有 section。此选项只能与 extbinary 格式的基于采样的 Profile 一起使用。
- --use-md5=[true|false]¶
在写入 Profile 时，使用 MD5 表示名称表中的字符串。此选项只能与 extbinary 格式的基于采样的 Profile 一起使用。
- --gen-partial-profile=[true|false]¶
将 Profile 标记为部分 Profile，该 Profile 仅为优化的目标提供部分 Profile 覆盖率。此选项只能与 extbinary 格式的基于采样的 Profile 一起使用。
- --split-layout=[true|false]¶
将 Profile 数据 section 拆分为两个，一个包含带有内联函数的样本 Profile，另一个不包含。此选项只能与 extbinary 格式的基于采样的 Profile 一起使用。
- --convert-sample-profile-layout=[nest|flat]¶
将合并的 Profile 转换为具有新布局的 Profile。支持的布局为
nest（嵌套 Profile，输入应为 CS 平面 Profile）和flat（具有展平的嵌套内联的 Profile）。
- --supplement-instr-with-sample=<file>¶
使用样本 Profile 补充 Instrumentation Profile。样本 Profile 是标志的输入。输出将为 Instrumentation 格式（仅适用于 -instr）。
- --zero-counter-threshold=<float>¶
对于在 Instr Profile 中为冷函数但在样本 Profile 中为热函数的函数，如果零计数器数除以计数器总数的比率高于阈值，则该函数的 Profile 将被视为对性能有害并将被删除。
- --instr-prof-cold-threshold=<int>¶
用户指定的 Instr Profile 冷阈值，将覆盖从 Profile 摘要中获取的冷阈值。
- --suppl-min-size-threshold=<int>¶
如果函数的大小小于阈值，则假定它可以被 PGO 早期内联器内联，并且不会根据样本 Profile 进行调整。
- --debug-info=<path>¶
指定包含原始 Profile 的调试信息的执行文件或
.dSYM。当--debug-info-correlate或--profile-correlate=debug-info用于 Instrumentation 时，请使用此选项来关联原始 Profile。
- --binary-file=<path>¶
指定包含原始 Profile 的 Profile 数据和 Profile 名称 section 的可执行文件。当
-profile-correlate=binary用于 Instrumentation 时，请使用此选项来关联原始 Profile。
- --debuginfod¶
使用 debuginfod 查找包含原始 Profile 的 Profile 数据和名称 section 的关联可执行文件，以关联它们。当 -profile-correlate=binary 用于 Instrumentation 时，可以使用此选项进行关联。
- --debug-file-directory=<dir>¶
使用提供的本地目录搜索包含原始 Profile 的 Profile 数据和名称 section 的可执行文件，以关联它们。当 -profile-correlate=binary 用于 Instrumentation 时，可以使用此选项进行关联。
- --correlate=<kind>¶
指定在使用 -debuginfod 或 -debug-file-directory=<dir> 选项时要使用的关联类型（debug_info 或 binary）。
- --temporal-profile-trace-reservoir-size¶
输出 Profile 中要存储的最大时间 Profile 跟踪数。如果添加了更多跟踪，我们将使用蓄水池采样来选择要保留的跟踪。请注意，在同一索引 Profile 上的不同合并调用之间更改此值可能会导致样本偏差。默认值为 100。
- --temporal-profile-max-trace-length¶
单个时间 Profile 跟踪中的最大函数数。更长的跟踪将被截断。默认值为 1000。
- --function=<string>¶
仅保留输出中与正则表达式匹配的函数，所有其他函数都将从 Profile 中删除。
- --no-function=<string>¶
从 Profile 中删除与正则表达式匹配的函数。如果同时指定了 –function 和 –no-function 且函数同时匹配两者，则该函数将被删除。
示例¶
基本用法¶
合并三个 Profile
llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
加权输入¶
输入文件 foo.profdata 特别重要，将其计数乘以 10
llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
与之前的调用完全等效（显式形式；对于程序化调用很有用）
llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
SHOW¶
概要¶
llvm-profdata show [options] [filename]
描述¶
llvm-profdata show 接受 Profile 数据文件，并显示有关此文件和任何指定函数的 Profile 计数器信息。
如果省略 filename 或为 -，则 llvm-profdata show 从标准输入读取其输入。
选项¶
- --all-functions¶
打印每个函数的详细信息。
- --binary-ids¶
打印 Profile 中嵌入的二进制 ID。
- --counts¶
打印显示函数的计数器值。
- --show-format=<text|json|yaml>¶
如果提供的 Profile 类型支持，则以选定的格式发出输出。
- --function=<string>¶
如果函数名称包含给定的字符串，则打印该函数的详细信息。
- --help¶
打印命令行选项的摘要。
- --output=<output>, -o¶
指定输出文件名。如果 output 为
-或未指定，则输出将发送到标准输出。
- --instr (默认)¶
指定输入 Profile 是基于 Instrumentation 的 Profile。
- --text¶
指示 Profile 转储器以基于 Instrumentation 的 Profile 数据表示的文本格式显示 Profile 计数。默认情况下，Profile 信息以更易于人阅读的形式（也是文本形式）与注释一起转储。
- --topn=<n>¶
指示 Profile 转储器在摘要 section 中显示具有最热基本块的前
n个函数。默认情况下，不转储 topn 函数。
- --sample¶
指定输入 Profile 是基于采样的 Profile。
- --memop-sizes¶
显示所示函数的内存内联函数调用的 Profile 大小。
- --value-cutoff=<n>¶
仅显示最大计数值大于或等于
n的函数。默认情况下，value-cutoff 设置为 0。
- --list-below-cutoff¶
仅输出最大计数值低于截止值的函数的名称。
- --profile-version¶
打印 Profile 版本。
- --showcs¶
仅显示上下文敏感的 Profile 计数。默认值是过滤掉所有上下文敏感的 Profile 计数。
- --show-prof-sym-list=[true|false]¶
如果 Profile 中存在 Profile 符号列表，则显示该列表。此选项仅对 extbinary 格式的基于采样的 Profile 有意义。
- --show-sec-info-only=[true|false]¶
显示有关 Profile 中每个 section 的基本信息。此选项仅对 extbinary 格式的基于采样的 Profile 有意义。
- --debug-info=<path>¶
指定包含原始 Profile 的调试信息的执行文件或
.dSYM。当--debug-info-correlate或--profile-correlate=debug-info用于 Instrumentation 时，请使用此选项显示来自原始 Profile 的关联函数。
- --covered¶
仅显示已执行的函数，即具有非零计数的函数。
OVERLAP¶
概要¶
llvm-profdata overlap [options] [base profile file] [test profile file]
描述¶
llvm-profdata overlap 接受两个 Profile 数据文件，并显示整个文件之间以及任何指定函数之间的计数器分布的重叠。
在此命令中，重叠定义如下：假设基本 Profile 文件具有以下计数：{c1_1, c1_2, …, c1_n, c1_u_1, c2_u_2, …, c2_u_s}，测试 Profile 文件具有 {c2_1, c2_2, …, c2_n, c2_v_1, c2_v_2, …, c2_v_t}。这里 c{1|2}_i (i = 1 .. n) 是匹配的计数器，c1_u_i (i = 1 .. s) 和 c2_v_i (i = 1 .. v) 是不匹配的计数器（或仅存在于）基本 Profile 文件和测试 Profile 文件中的计数器。令 sum_1 = c1_1 + c1_2 + … + c1_n + c1_u_1 + c2_u_2 + … + c2_u_s，sum_2 = c2_1 + c2_2 + … + c2_n + c2_v_1 + c2_v_2 + … + c2_v_t。重叠 = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + … + min(c1_n/sum_1, c2_n/sum_2)。
结果重叠分布是一个百分比数字，范围从 0.0% 到 100.0%，其中 0.0% 表示没有重叠，100.0% 表示完美重叠。
这是一个示例，如果基本 Profile 文件的计数为 {400, 600}，而测试 Profile 文件的匹配计数为 {60000, 40000}。重叠为 80%。
选项¶
- --function=<string>¶
如果函数名称包含给定的字符串，则打印该函数的详细信息。
- --help¶
打印命令行选项的摘要。
- --output=<output>, -o¶
指定输出文件名。如果 output 为
-或未指定，则输出将发送到标准输出。
- --value-cutoff=<n>¶
仅显示最大计数值大于或等于
n的函数。默认情况下，value-cutoff 设置为 unsigned long long 的最大值。
- --cs¶
仅显示上下文敏感的 Profile 计数的重叠。默认值是显示非上下文敏感的 Profile 计数。
ORDER¶
概要¶
llvm-profdata order [options] [filename]
描述¶
llvm-profdata order 使用来自 Profile 的时间 Profile 跟踪，并找到一个函数顺序，以减少这些跟踪的页面错误数。此输出可以直接通过 --symbol-ordering-file= 用于 ELF 或 -order-file 用于 Mach-O 传递给 lld。如果在 Profile 中找到的跟踪代表真实世界，那么此顺序应提高启动性能。
选项¶
- --help¶
打印命令行选项的摘要。
- --output=<output>, -o¶
指定输出文件名。如果 output 为
-或未指定，则输出将发送到标准输出。
退出状态¶
llvm-profdata 如果命令被省略或无效、无法读取输入文件或者它们的数据之间存在不匹配，则返回 1。