llvm-remarkutil - Remark 工具¶

概要¶

llvm-remarkutil [子命令] [選項]

描述¶

用於顯示來自不同 remark 格式的資訊以及在不同格式之間轉換的工具。

子命令¶

bitstream2yaml - 將位元流 remarks 重新序列化為 YAML。

yaml2bitstream - 將 YAML remarks 重新序列化為位元流。

instruction-count - 輸出函數指令計數。

annotation-count - 從註解 remarks 輸出 remark 類型計數。

size-diff - 計算大小 remarks 的差異。

bitstream2yaml¶

用法：llvm-remarkutil bitstream2yaml <輸入檔案> -o <輸出檔案>

摘要¶

接受位元流 remark 檔案作為輸入，並將該檔案重新序列化為 YAML。

yaml2bitstream¶

用法：llvm-remarkutil yaml2bitstream <輸入檔案> -o <輸出檔案>

摘要¶

接受 YAML remark 檔案作為輸入，並將該檔案以位元流格式重新序列化。

instruction-count¶

用法：llvm-remarkutil instruction-count <輸入檔案> –parser=<bitstream|yaml> [–use-debug-loc] -o <輸出檔案>

摘要¶

為每個函數輸出指令計數 remarks。指令計數 remarks 編碼函數在組語列印時的指令數量。

指令計數 remarks 需要 asm-printer remarks。

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=<類型> [–use-debug-loc] -o <輸出檔案>

摘要¶

為每個函數輸出註解類型 <類型> remark 的計數。該計數表示在函數中插入的 remark 檢查的數量。

註解計數 remarks 需要 AnnotationRemarksPass remarks。

CSV 格式如下

Function,Count
foo,123

如果傳遞 –use-debug-loc，則 CSV 將包含原始碼路徑、行號和列號。

Source,Function,Count
path:line:column,foo,3

count¶

用法：llvm-remarkutil count [選項] <輸入檔案>

摘要¶

llvm-remarkutil count 根據指定的屬性計算 remarks。預設情況下，此工具根據 remarks 在原始碼檔案或函數中出現的次數或產生的 remark 檔案的總次數來計算 remarks。此工具還支援根據特定的 remark 引數收集計數。指定的引數應具有整數值才能報告計數。

此工具包含用於根據 remark 名稱、pass 名稱、引數值和 remark 類型篩選 remark 計數的實用程式。

選項¶

--parser=<yaml|bitstream>¶

選擇輸入 remark 解析器的類型。必填。

yaml : 此工具將解析 YAML remarks。
bitstream : 此工具將解析位元流 remarks。

--count-by=<value>¶

選擇按選項收集 remarks。

remark-name : 計算存在多少個個別的 remarks。
arg : 根據 –(r)args 傳遞的指定引數計算 remarks。引數值必須是數字。

--group-by=<value>¶

依屬性群組 remarks 計數。

source : 計數將按原始碼路徑收集。沒有偵錯位置的 remarks 將不被計數。
function : 計數是按函數收集。
function-with-loc : 計數是按函數和原始碼收集。沒有偵錯位置的 remarks 將不被計數。
Total : 報告所提供的 remark 檔案的計數。

--args[=arguments]¶: 如果 count-by 設定為 arg，則可以使用此標誌從指定為逗號分隔字串的 remark 引數中收集。引數必須具有數字值才能按 remarks 計數

--rargs[=arguments]¶: 如果 count-by 設定為 arg，則可以使用此標誌使用正則表達式從指定的 remark 引數中收集。引數必須具有數字值才能按 remarks 計數

--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>¶

依類型篩選 remarks，選項如下。

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）中的大小 remarks。

llvm-remarkutil size-diff 可用於深入了解哪些函數受到程式碼產生變更的影響最大。

在最常見的使用案例中，file_a 和 file_b 將是透過使用不同的編譯器或不同的最佳化設定編譯固定的原始碼輸出的 remarks。

llvm-remarkutil size-diff 處理 YAML 和位元流 remarks。

選項¶

--parser=<yaml|bitstream>¶

選擇輸入 remark 解析器的類型。必填。

yaml : 此工具將解析 YAML remarks。
bitstream : 此工具將解析位元流 remarks。

--report-style=<human|json>¶

輸出樣式。

human : 人類可讀的文字報告。預設選項。
json : JSON 報告。

--pretty¶

美化列印 JSON 輸出。選項。

如果輸出未設定為 JSON，則此操作無效。

-o=<file>¶: 報告的輸出檔案。預設輸出到標準輸出。

人類可讀的輸出¶

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，否則傳回非零值。

文件

參與貢獻

其他連結

本頁