llvm-profdata - 代码剖析数据工具

概要

llvm-profdata 命令 [参数…]

描述

llvm-profdata 工具是一个用于处理代码剖析数据文件的实用程序。

命令

合并

概要

llvm-profdata merge [选项] [文件名…]

描述

llvm-profdata merge 命令接收由 PGO 检测生成的多个代码剖析数据文件，并将它们合并成一个索引化的代码剖析数据文件。

默认情况下，代码剖析数据在合并时不会被修改。这意味着每个输入文件的相对重要性与其包含的样本数或计数成正比。通常，较长时间训练运行的输入会被解释为比较短时间的运行更重要。根据训练运行的性质，可能需要使用 -weighted-input 选项调整分配给每个输入文件的权重。

通过 -weighted-input、-input-files 或位置参数传递的代码剖析文件会在每次出现时都进行一次处理。

选项

--help

打印命令行选项的摘要。

--output=<输出文件名>, -o

指定输出文件名。输出文件名 不能是 -，因为生成的索引化代码剖析数据无法写入标准输出。

--weighted-input=<权重,文件名>

指定一个输入文件名及其权重。提供的 文件名 的代码剖析计数将按提供的 权重 进行缩放（乘法），其中 权重 是一个十进制整数，大于或等于 1。未使用此选项指定的输入文件将分配默认权重 1。下面显示了示例。

--input-files=<路径>, -f

指定一个包含要合并的文件列表的文件。此文件中的条目以换行符分隔。以 ‘#’ 开头的行将被跳过。条目可以是 <文件名> 或 <权重>,<文件名> 的形式。

--remapping-file=<路径>, -r

指定一个包含输入代码剖析文件中的符号名称到输出代码剖析文件中的符号名称映射的文件。该文件应由 <输入符号> <输出符号> 形式的行组成。空行和以 # 开头的行将被跳过。

llvm-cxxmap 工具可用于生成符号映射文件。

--instr (默认)

指定输入代码剖析文件是基于检测的代码剖析文件。

--sample

指定输入代码剖析文件是基于样本的代码剖析文件。

生成的代码剖析文件格式可以通过以下三种方式之一生成

--binary (默认)

使用二进制编码输出代码剖析文件。对于基于检测的代码剖析文件，输出格式为索引化二进制格式。

--extbinary

使用可扩展二进制编码输出代码剖析文件。此选项只能与基于样本的代码剖析文件一起使用。启用压缩时，可扩展二进制编码可以更紧凑，并且加载速度比默认的二进制编码更快。

--text

以文本模式输出代码剖析文件。此选项也可用于基于样本和基于检测的代码剖析文件。使用此选项时，代码剖析文件将以代码剖析读取器可解析的文本格式转储。

--gcc

使用 GCC 的 gcov 格式输出代码剖析文件（尚未支持）。

--sparse[=true|false]

不输出执行计数为 0 的函数记录。只能与 -instr 结合使用。默认为 false，因为它可能会抑制 PGO 期间的编译器优化。

--num-threads=<N>, -j

使用 N 个线程执行代码剖析文件合并。当 N=0 时，llvm-profdata 会自动检测要使用的线程数。这是默认设置。

--failure-mode=[any|all]

设置失败模式。有两个选项：'any' 表示如果任何代码剖析文件无效，则合并命令将失败；'all' 表示仅当所有代码剖析文件均无效时，合并命令才会失败。如果设置了 'all'，则来自任何无效代码剖析文件的信息都将从最终合并的产品中排除。默认失败模式为 'any'。

--prof-sym-list=<路径>

指定一个包含符号列表的文件，用于在代码剖析文件中生成代码剖析符号列表。此选项只能与 extbinary 格式的基于样本的代码剖析文件一起使用。此文件中的条目以换行符分隔。

--compress-all-sections[=true|false]

在写入代码剖析文件时压缩所有部分。此选项只能与 extbinary 格式的基于样本的代码剖析文件一起使用。

--use-md5[=true|false]

在写入代码剖析文件时使用 MD5 表示名称表中的字符串。此选项只能与 extbinary 格式的基于样本的代码剖析文件一起使用。

--gen-partial-profile[=true|false]

将代码剖析文件标记为部分代码剖析文件，它仅为优化的目标提供部分代码剖析覆盖率。此选项只能与 extbinary 格式的基于样本的代码剖析文件一起使用。

--split-layout[=true|false]

将代码剖析数据部分拆分为两个，一个包含包含内联函数的样本代码剖析文件，另一个不包含。此选项只能与 extbinary 格式的基于样本的代码剖析文件一起使用。

--convert-sample-profile-layout=[nest|flat]

将合并后的代码剖析文件转换为具有新布局的代码剖析文件。支持的布局为 nest（嵌套代码剖析文件，输入应为 CS 平坦代码剖析文件）和 flat（具有扁平化内联函数的代码剖析文件）。

--supplement-instr-with-sample=<文件>

用样本代码剖析文件补充检测代码剖析文件。样本代码剖析文件是该标志的输入。输出将采用检测格式（仅适用于 -instr）。

--zero-counter-threshold=<浮点数>

对于在检测代码剖析文件中是冷的但在样本代码剖析文件中是热的函数，如果零计数器数量与计数器总数之比超过阈值，则该函数的代码剖析文件将被视为对性能有害，并将被丢弃。

--instr-prof-cold-threshold=<整数>

用户为检测代码剖析文件指定的冷阈值，它将覆盖从代码剖析摘要中获取的冷阈值。

--suppl-min-size-threshold=<整数>

如果函数的大小小于阈值，则假设它可以在 PGO 早期内联器中内联，并且不会根据样本配置文件进行调整。

--debug-info=<path>

指定包含原始配置文件调试信息的可执行文件或.dSYM。当--debug-info-correlate或--profile-correlate=debug-info用于插桩时，使用此选项关联原始配置文件。

--binary-file=<path>

指定包含原始配置文件中配置文件数据和配置文件名称部分的可执行文件。当-profile-correlate=binary用于插桩时，使用此选项关联原始配置文件。

--temporal-profile-trace-reservoir-size

输出配置文件中要存储的时间配置文件跟踪的最大数量。如果添加了更多跟踪，我们将使用蓄水池采样来选择要保留的跟踪。请注意，在同一个索引配置文件上不同合并调用之间更改此值可能会导致样本偏差。默认值为 100。

--temporal-profile-max-trace-length

单个时间配置文件跟踪中的函数最大数量。较长的跟踪将被截断。默认值为 1000。

--function=<string>

仅保留与输出中正则表达式匹配的函数，其他所有函数都将从配置文件中删除。

--no-function=<string>

从配置文件中删除与正则表达式匹配的函数。如果同时指定了 –function 和 –no-function，并且某个函数与两者都匹配，则将其删除。

示例

基本用法

合并三个配置文件

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

显示

概要

llvm-profdata show [选项] [文件名]

描述

llvm-profdata show 获取配置文件数据文件并显示有关此文件以及任何指定函数的配置文件计数器的信息。

如果省略了文件名或为-，则llvm-profdata show 从标准输入读取其输入。

选项

--all-functions

打印每个函数的详细信息。

--binary-ids

打印配置文件中嵌入的二进制 ID。

--counts

打印显示函数的计数器值。

--show-format=<text|json|yaml>

如果提供的配置文件类型支持，则以选定的格式发出输出。

--function=<string>

如果函数的名称包含给定的字符串，则打印该函数的详细信息。

--help

打印命令行选项的摘要。

--output=<output>, -o

指定输出文件名。如果输出为-或未指定，则输出将发送到标准输出。

--instr (default)

指定输入代码剖析文件是基于检测的代码剖析文件。

--text

指示配置文件转储程序以插桩式配置文件数据表示的文本格式显示配置文件计数。默认情况下，配置文件信息以更易于人类阅读的形式（也以文本形式）转储，并带有注释。

--topn=<n>

指示配置文件转储程序在摘要部分显示具有最热基本块的前n个函数。默认情况下，不会转储 topn 函数。

--sample

指定输入代码剖析文件是基于样本的代码剖析文件。

--memop-sizes

显示显示函数的内存内在函数调用的概要大小。

--value-cutoff=<n>

仅显示最大计数值大于或等于n的那些函数。默认情况下，值截止设置为 0。

--list-below-cutoff

仅输出最大计数值低于截止值的函数的名称。

--profile-version

打印配置文件版本。

--showcs

仅显示上下文相关的配置文件计数。默认情况下，会过滤所有上下文相关的配置文件计数。

--show-prof-sym-list=[true|false]

如果配置文件中存在，则显示配置文件符号列表。此选项仅对 extbinary 格式的基于样本的配置文件有意义。

--show-sec-info-only=[true|false]

显示配置文件中每个部分的基本信息。此选项仅对 extbinary 格式的基于样本的配置文件有意义。

--debug-info=<path>

指定包含原始配置文件调试信息的可执行文件或.dSYM。当--debug-info-correlate或--profile-correlate=debug-info用于插桩时，使用此选项显示原始配置文件中的相关函数。

--covered

仅显示已执行的函数，即计数不为零的函数。

重叠

概要

llvm-profdata overlap [选项] [基本配置文件文件] [测试配置文件文件]

描述

llvm-profdata overlap 获取两个配置文件数据文件并显示整个文件之间以及任何指定函数之间计数器分布的重叠。

在此命令中，重叠定义如下：假设基本配置文件文件具有以下计数：{c1_1, c1_2, …, c1_n, c1_u_1, c2_u_2, …, c2_u_s}，而测试配置文件文件具有{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）是不匹配的计数器（或仅存在于）基本配置文件文件和测试配置文件文件中，分别。令 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% 表示完美重叠。

以下是一个示例，如果基本配置文件文件的计数为 {400, 600}，而测试配置文件文件的匹配计数为 {60000, 40000}。则重叠为 80%。

选项

--function=<string>

如果函数的名称包含给定的字符串，则打印该函数的详细信息。

--help

打印命令行选项的摘要。

--output=<output>, -o

指定输出文件名。如果输出为-或未指定，则输出将发送到标准输出。

--value-cutoff=<n>

仅显示最大计数值大于或等于n的函数。默认情况下，value-cutoff 设置为无符号长长的最大值。

--cs

仅显示上下文相关概要计数的重叠。默认情况下显示非上下文相关概要计数。

排序

概要

llvm-profdata order [选项] [文件名]

描述

llvm-profdata order 使用概要中的时间概要跟踪并找到一个减少这些跟踪页面错误数量的函数顺序。此输出可以通过 --symbol-ordering-file=（用于 ELF）或 -order-file（用于 Mach-O）直接传递给 lld。如果概要中找到的跟踪代表真实世界，则此顺序应提高启动性能。

选项

--help

打印命令行选项的摘要。

--output=<output>, -o

指定输出文件名。如果输出为-或未指定，则输出将发送到标准输出。

退出状态

llvm-profdata 如果命令被省略或无效，如果无法读取输入文件，或者如果它们的数据之间存在不匹配，则返回 1。