llvm-profdata - 設定檔資料工具

概要

llvm-profdata command [args…]

描述

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

命令

合併

概要

llvm-profdata merge [options] [filename…]

描述

llvm-profdata merge 接受由 PGO instrumentation 產生的多個設定檔資料檔案，並將它們合併為單個索引設定檔資料檔案。

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

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

選項

--help

印出命令列選項摘要。

--output=<output>, -o

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

--weighted-input=<weight,filename>

指定輸入檔案名稱以及權重。提供的 filename 的設定檔計數將按提供的 weight 縮放（乘法），其中 weight 是十進制整數 >= 1。未使用此選項指定的輸入檔案會被指定預設權重 1。範例顯示如下。

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

指定一個檔案，其中包含要合併的檔案列表。此檔案中的項目以換行符號分隔。以 '＃' 開頭的行會被跳過。項目格式可以是 <filename> 或 <weight>,<filename>。

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

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

llvm-cxxmap 工具可用於產生符號重新對應檔案。

--instr (default)

指定輸入設定檔是基於檢測的設定檔。

--sample

指定輸入設定檔是基於採樣的設定檔。

產生檔案的格式可以透過以下三種方式之一產生

--binary (default)

使用二進制編碼發出設定檔。對於基於檢測的設定檔，輸出格式為索引二進制格式。

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

對於在檢測設定檔中為冷函數但在採樣設定檔中為熱函數的情況，如果零計數器數量除以計數器總數的比率高於閾值，則該函數的設定檔將被視為對效能有害並將被丟棄。

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

使用者指定的檢測設定檔的冷閾值，將覆蓋從設定檔摘要中取得的冷閾值。

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

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

--debug-info=<path>

指定包含原始設定檔偵錯資訊的可執行檔或 .dSYM。當 --debug-info-correlate 或 --profile-correlate=debug-info 用於檢測時，請使用此選項來關聯原始設定檔。

--binary-file=<path>

指定包含原始設定檔的設定檔資料和設定檔名稱區段的可執行檔。當 -profile-correlate=binary 用於檢測時，請使用此選項來關聯原始設定檔。

--debuginfod

使用 debuginfod 尋找相關的可執行檔，其中包含原始設定檔的設定檔資料和名稱區段以進行關聯。當 -profile-correlate=binary 用於檢測時，可以使用此選項進行關聯。

--debug-file-directory=<dir>

使用提供的本機目錄搜尋包含原始設定檔的設定檔資料和名稱區段的可執行檔，以進行關聯。當 -profile-correlate=binary 用於檢測時，可以使用此選項進行關聯。

--correlate=<kind>

當提供 -debuginfod 或 -debug-file-directory=<dir> 選項時，指定要使用的關聯種類（debug_info 或 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 [options] [filename]

描述

llvm-profdata show 接受設定檔資料檔案，並顯示此檔案以及任何指定的函數的設定檔計數器資訊。

如果省略 filename 或為 -，則 llvm-profdata show 會從標準輸入讀取其輸入。

選項

--all-functions

印出每個函數的詳細資訊。

--binary-ids

在設定檔中印出嵌入的二進制 ID。

--counts

印出顯示函數的計數器值。

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

如果提供的設定檔類型支援，則以選定的格式發出輸出。

--function=<string>

如果函數名稱包含給定的字串，則印出函數的詳細資訊。

--help

印出命令列選項摘要。

--output=<output>, -o

指定輸出檔案名稱。如果 output 為 - 或未指定，則輸出將發送到標準輸出。

--instr (default)

指定輸入設定檔是基於檢測的設定檔。

--text

指示設定檔傾印器以檢測設定檔資料表示的文字格式顯示設定檔計數。預設情況下，設定檔資訊以更易於人類閱讀的形式（也是文字）與註釋一起傾印。

--topn=<n>

指示設定檔傾印器在摘要區段中顯示具有最熱門基本區塊的前 n 個函數。預設情況下，不會傾印 topn 函數。

--sample

指定輸入設定檔是基於採樣的設定檔。

--memop-sizes

顯示顯示函數的記憶體內建呼叫的設定檔大小。

--value-cutoff=<n>

僅顯示最大計數值大於或等於 n 的函數。預設情況下，value-cutoff 設定為 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 [options] [base profile file] [test profile file]

描述

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

指定輸出檔案名稱。如果 output 為 - 或未指定，則輸出將發送到標準輸出。

--value-cutoff=<n>

僅顯示最大計數值大於或等於 n 的函數。預設情況下，value-cutoff 設定為 unsigned long long 的最大值。

--cs

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

排序

概要

llvm-profdata order [options] [filename]

描述

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

選項

--help

印出命令列選項摘要。

--output=<output>, -o

指定輸出檔案名稱。如果 output 為 - 或未指定，則輸出將發送到標準輸出。

結束狀態

llvm-profdata 如果省略或命令無效，如果無法讀取輸入檔案，或者如果其資料之間存在不匹配，則 llvm-profdata 會傳回 1。