llvm-remarkutil - Remark 工具¶
概要¶
llvm-remarkutil [子命令] [选项]
描述¶
用于显示来自不同 remark 格式的信息以及在它们之间进行转换的工具。
子命令¶
bitstream2yaml - 将 bitstream remark 重新序列化为 YAML。
yaml2bitstream - 将 YAML remark 重新序列化为 bitstream。
instruction-count - 输出函数指令计数。
annotation-count - 从注解 remark 输出 remark 类型计数。
size-diff - 计算大小 remark 的差异。
bitstream2yaml¶
用法: llvm-remarkutil bitstream2yaml <输入文件> -o <输出文件>
概要¶
接受 bitstream remark 文件作为输入,并将该文件重新序列化为 YAML。
yaml2bitstream¶
用法: llvm-remarkutil yaml2bitstream <输入文件> -o <输出文件>
概要¶
接受 YAML remark 文件作为输入,并将该文件重新序列化为 bitstream 格式。
instruction-count¶
用法: llvm-remarkutil instruction-count <输入文件> –parser=<bitstream|yaml> [–use-debug-loc] -o <输出文件>
概要¶
为每个函数输出指令计数 remark。指令计数 remark 编码函数在汇编打印时的指令数。
指令计数 remark 需要 asm-printer remark。
CSV 格式如下
Function,InstructionCount
foo,123
如果传递了 –use-debug-loc,则 CSV 将包含源路径、行号和列号。
Source,Function,InstructionCount
path:line:column,foo,3
annotation-count¶
用法: llvm-remarkutil annotation-count <输入文件> –parser=<bitstream|yaml> –annotation-type=<type> [–use-debug-loc] -o <输出文件>
概要¶
为每个函数输出注解类型为 <type> 的 remark 计数。该计数表示在函数中插入的 remark 检查的数量。
注解计数 remark 需要 AnnotationRemarksPass remark。
CSV 格式如下
Function,Count
foo,123
如果传递了 –use-debug-loc,则 CSV 将包含源路径、行号和列号。
Source,Function,Count
path:line:column,foo,3
count¶
用法: llvm-remarkutil count [选项] <输入文件>
概要¶
llvm-remarkutil count 基于指定的属性计数 remark。默认情况下,该工具根据 remark 在源文件或函数中出现的次数或生成的 remark 文件的总数来计数 remark。该工具还支持基于特定的 remark 参数收集计数。指定的参数应具有整数值才能报告计数。
该工具包含用于基于 remark 名称、pass 名称、参数值和 remark 类型过滤 remark 计数的实用程序。
选项¶
- --parser=<yaml|bitstream>¶
选择输入 remark 解析器的类型。必需。
yaml
: 该工具将解析 YAML remark。bitstream
: 该工具将解析 bitstream remark。
- --count-by=<value>¶
选择按其收集 remark 的选项。
remark-name
: 计数存在多少个单独的 remark。arg
: 基于通过 –(r)args 传递的指定参数计数 remark。参数值必须是数字。
- --group-by=<value>¶
按属性对 remark 计数进行分组。
source
: 计数将按源路径收集。没有调试位置的 remark 将不计数。function
: 计数按函数收集。function-with-loc
: 计数按每个源的函数收集。没有调试位置的 remark 将不计数。Total
: 报告提供的 remark 文件的计数。
- --args[=arguments]¶
如果 count-by 设置为 arg,则可以使用此标志从指定 remark 参数(表示为逗号分隔的字符串)收集计数。参数必须具有数字值才能按其计数 remark
- --rargs[=arguments]¶
如果 count-by 设置为 arg,则可以使用此标志使用正则表达式从指定的 remark 参数收集计数。参数必须具有数字值才能按其计数 remark
- --pass-name[=<string>]¶
按 pass 名称过滤计数。
- --rpass-name[=<string>]¶
使用正则表达式按 pass 名称过滤计数。
- --remark-name[=<string>]¶
按 remark 名称过滤计数。
- --rremark-name[=<string>]¶
使用正则表达式按 remark 名称过滤计数。
- --filter-arg-by[=<string>]¶
按参数值过滤计数。
- --rfilter-arg-by[=<string>]¶
使用正则表达式按参数值过滤计数。
- --remark-type=<value>¶
使用以下选项按类型过滤 remark。
unknown
passed
missed
analysis
analysis-fp-commute
analysis-aliasing
failure
size-diff¶
用法: llvm-remarkutil size-diff [选项] file_a file_b –parser parser
概要¶
llvm-remarkutil size-diff 比较两个 remark 文件 file_a
和 file_b
中的大小 remark。
llvm-remarkutil size-diff 可用于深入了解哪些函数受代码生成更改的影响最大。
在最常见的用例中,file_a
和 file_b
将是通过使用不同的编译器或不同的优化设置编译固定的源而输出的 remark。
选项¶
- --parser=<yaml|bitstream>¶
选择输入 remark 解析器的类型。必需。
yaml
: 该工具将解析 YAML remark。bitstream
: 该工具将解析 bitstream remark。
- --report-style=<human|json>¶
输出样式。
human
: 人类可读的文本报告。默认选项。json
: JSON 报告。
- --pretty¶
美化打印 JSON 输出。可选。
如果输出未设置为 JSON,则此操作无效。
- -o=<file>¶
报告的输出文件。默认输出到 stdout。
人类可读的输出¶
llvm-remarkutil size-diff 的人类可读格式由两个部分组成
每个函数的更改。
所有更改的高级摘要。
已更改函数部分¶
假设您正在比较两个 remark 文件 OLD 和 NEW。
对于 OLD 和 NEW 中指令计数已更改的每个函数,llvm-remarkutil size-diff 将发出如下所示的行
(++|--|==) (>|<) function_name, N instrs, M stack B
格式的分解如下
(++|--|==)
function_name
存在于 OLD 和 NEW 中的哪一个。++
: 仅在 NEW 中。(“已添加”)--
: 仅在 OLD 中。(“已删除”)==
: 两者都在。
(>|<)
表示
function_name
在第二个文件中是否具有更多指令或更少指令。>
: 第二个文件中的指令比第一个文件多。<
: 第二个文件中的指令比第一个文件少。
function_name
已更改函数的名称。
N instrs
第二个文件指令计数 - 第一个文件指令计数。
M stack B
第二个文件堆栈字节计数 - 第一个文件堆栈字节计数。
摘要部分¶
llvm-remarkutil size-diff 将在打印所有已更改的函数后输出高级摘要。
instruction count: N (inst_pct_change%)
stack byte usage: M (sb_pct_change%)
N
第二个文件和第一个文件之间所有指令计数更改的总和。
inst_pct_change%
第二个文件和第一个文件之间指令计数的百分比增加或减少。
M
第二个文件和第一个文件之间所有堆栈字节计数更改的总和。
sb_pct_change%
第二个文件和第一个文件之间堆栈字节使用量的百分比增加或减少。
JSON 输出¶
高级视图¶
假设我们正在比较两个文件 OLD 和 NEW。
llvm-remarkutil size-diff 将输出如下 JSON。
"Files": [
"A": "path/to/OLD",
"B": "path/to/NEW"
]
"InBoth": [
...
],
"OnlyInA": [
...
],
"OnlyInB": [
...
]
文件
remark 文件的原始路径。
A
: 第一个文件的路径。B
: 第二个文件的路径。
InBoth
两个文件中都存在的函数。
OnlyInA
仅在第一个文件中存在的函数。
OnlyInB
仅在第二个文件中存在的函数。
函数 JSON¶
InBoth
、OnlyInA
和 OnlyInB
部分包含输入 remark 文件中每个函数的大小信息。
{
"FunctionName" : "function_name"
"InstCount": [
INST_COUNT_A,
INST_COUNT_B
],
"StackSize": [
STACK_BYTES_A,
STACK_BYTES_B
],
}
FunctionName
函数名称。
InstCount
函数的指令计数。
INST_COUNT_A
: OLD 中的指令计数。INST_COUNT_B
: NEW 中的指令计数。
StackSize
函数的堆栈字节计数。
STACK_BYTES_A
: OLD 中的堆栈字节数。STACK_BYTES_B
: NEW 中的堆栈字节数。
从函数 JSON 计算差异¶
函数 JSON 不包含差异。llvm-remarkutil size-diff 的 JSON 输出的工具负责单独计算差异。
要计算差异
指令计数差异:
INST_COUNT_B - INST_COUNT_A
堆栈字节计数差异:
STACK_BYTES_B - STACK_BYTES_A
退出状态¶
llvm-remarkutil size-diff 成功时返回 0,否则返回非零值。