llvm-remarkutil - Remark 工具

概要

llvm-remarkutil [子命令] [选项]

描述

用于显示来自不同 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_afile_b 中的大小 remark

llvm-remarkutil size-diff 可用于深入了解哪些函数受代码生成更改的影响最大。

在最常见的用例中,file_afile_b 将是通过使用不同的编译器不同的优化设置编译固定的源而输出的 remark。

llvm-remarkutil size-diff 处理 YAMLbitstream 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

InBothOnlyInAOnlyInB 部分包含输入 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,否则返回非零值。