llvm-profdata - 設定檔資料工具

語法

llvm-profdata 指令 [參數…]

說明

llvm-profdata 工具是一個用於處理設定檔資料檔案的小型公用程式。

指令

合併

語法

llvm-profdata merge [選項] [檔名…]

說明

llvm-profdata merge 會取得數個由 PGO instrumentation 生成的設定檔資料檔案，並將它們合併成單一索引設定檔資料檔案。

根據預設，設定檔資料會在未經修改的情況下合併。這表示每個輸入檔案的相對重要性與其包含的樣本或計數數量成正比。一般來說，較長的訓練執行所產生的輸入會被解讀為比較短的執行更重要。根據訓練執行的性質，使用 -weighted-input 選項來調整每個輸入檔案的權重可能很有用。

透過 -weighted-input、-input-files 或透過位置參數傳入的設定檔，每次看到時都會處理一次。

選項

--help

列印命令列選項的摘要。

--output=<輸出>, -o

指定輸出檔名。 輸出不能是 -，因為產生的索引設定檔資料無法寫入標準輸出。

--weighted-input=<權重,檔名>

指定一個輸入檔案名稱以及權重。提供的 filename 的輪廓計數將會根據提供的 weight 進行縮放（乘法運算），其中 weight 是一個大於等於 1 的十進制整數。未透過此選項指定的輸入檔案會被指定預設權重 1。以下顯示範例。

--input-files=<path>, -f

指定一個檔案，其中包含要合併的檔案清單。此檔案中的項目以換行符號分隔。開頭為「#」的行會被跳過。項目可以是 <filename> 或 <weight>,<filename> 的形式。

--remapping-file=<path>, -r

指定一個檔案，其中包含從輸入設定檔中的符號名稱到輸出設定檔中應使用的符號名稱的重新映射。該檔案應包含以下形式的行：<input-symbol> <output-symbol>。空白行和以 # 開頭的行會被跳過。

可以使用 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」會在任何設定檔無效時導致 merge 命令失敗，「all」只會在所有設定檔都無效時導致 merge 命令失敗。如果設定為「all」，則來自任何無效設定檔的資訊會從最終合併的產品中排除。預設的失敗模式為「any」。

--prof-sym-list=<path>

指定一個檔案，其中包含要在設定檔中產生設定檔符號清單的符號清單。此選項只能與 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=<file>

使用範例設定檔補充檢測設定檔。範例設定檔是旗標的輸入。輸出將採用檢測格式（僅適用於 -instr）。

--zero-counter-threshold=<float>

對於在指令計數器profile中冷門但在樣本profile中熱門的函數，如果零計數器數量除以總計數器數量的比率超過閾值，則該函數的profile將被視為對效能有害，並將被丟棄。

--instr-prof-cold-threshold=<int>

使用者指定的指令計數器profile的冷門閾值，它將覆蓋從profile摘要中獲取的冷門閾值。

--suppl-min-size-threshold=<int>

如果函數的大小小於閾值，則假設它可以通過PGO早期內聯器進行內聯，並且不會根據樣本profile進行調整。

--debug-info=<path>

指定包含原始profile的偵錯資訊的可執行檔或 .dSYM 檔案。當使用 --debug-info-correlate 或 --profile-correlate=debug-info 進行程式碼插裝時，請使用此選項來關聯原始profile。

--binary-file=<path>

指定包含原始profile的profile資料和profile名稱區段的可執行檔。當使用 -profile-correlate=binary 進行程式碼插裝時，請使用此選項來關聯原始profile。

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

顯示

概要

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

描述

llvm-profdata show 接受一个性能分析数据文件，并显示该文件以及任何指定函数的性能分析计数器信息。

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

选项

--all-functions

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

--binary-ids

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

--counts

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

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

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

--function=<字符串>

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

--help

列印命令列選項的摘要。

--output=<输出>, -o

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

--instr (默认)

指定輸入設定檔是基於插裝的設定檔。

--text

指示性能分析转储程序以基于插桩的性能分析数据表示形式的文本格式显示性能分析计数。默认情况下，性能分析信息以更易于阅读的形式（也在文本中）进行转储，并带有注释。

--topn=<n>

指示性能分析转储程序在摘要部分显示最热门的基本块的前 n 个函数。默认情况下，不会转储前 n 个函数。

--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 的函式。預設情況下，值截止設定為無符號長整數的最大值。

--cs

僅顯示上下文相關設定檔計數的重疊。預設情況下會顯示非上下文相關設定檔計數。

順序

語法

llvm-profdata order [選項] [檔案名稱]

說明

llvm-profdata order 使用設定檔中的時間設定檔追蹤，並找出可減少這些追蹤的頁面錯誤數量的函式順序。此輸出可以直接透過 --symbol-ordering-file= 傳遞給 ELF 的 lld，或透過 -order-file 傳遞給 Mach-O。如果在設定檔中找到的追蹤代表真實世界，則此順序應該可以改善啟動效能。

選項

--help

列印命令列選項的摘要。

--output=<output>, -o

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

結束狀態

如果省略或無效指令、無法讀取輸入檔案，或資料之間有不符，llvm-profdata 會傳回 1。