test-suite 指南

快速入門

  1. 執行測試需要 lit 測試執行器。您可以使用 LLVM 建置版本中的執行器

    % <path to llvm build>/bin/llvm-lit --version
lit 20.0.0dev

    另一種方法是以 Python 套件的形式安裝在 Python 虛擬環境中

    % python3 -m venv .venv
% . .venv/bin/activate
% pip install git+https://github.com/llvm/llvm-project.git#subdirectory=llvm/utils/lit
% lit --version
lit 20.0.0dev

    安裝官方 Python 發行版本的 lit 在 Python 虛擬環境中也可能有效。這將安裝最新發行版本的 lit

    % python3 -m venv .venv
% . .venv/bin/activate
% pip install lit
% lit --version
lit 18.1.8

    請注意，最新的測試可能依賴於最新發行版 lit 中沒有的功能。如有疑問，請嘗試先前的其中一種方法。

  2. 使用以下命令檢視 test-suite 模組

    % git clone https://github.com/llvm/llvm-test-suite.git test-suite

  3. 建立建置目錄並使用 CMake 配置套件。使用 CMAKE_C_COMPILER 選項指定要測試的編譯器。使用快取檔案選擇典型的建置配置

    % mkdir test-suite-build
% cd test-suite-build
% cmake -DCMAKE_C_COMPILER=<path to llvm build>/bin/clang \
        -C../test-suite/cmake/caches/O3.cmake \
        ../test-suite

注意！ 如果您正在使用您建置的 clang，並且想要建置和執行 MicroBenchmarks/XRay 微基準測試，您需要將 compiler-rt 新增到您的 LLVM_ENABLE_RUNTIMES cmake 旗標中。

  1. 建置基準測試

    % make
Scanning dependencies of target timeit-target
[  0%] Building C object tools/CMakeFiles/timeit-target.dir/timeit.c.o
[  0%] Linking C executable timeit-target
...

  2. 使用 lit 執行測試

    % llvm-lit -v -j 1 -o results.json .
-- Testing: 474 tests, 1 threads --
PASS: test-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test (1 of 474)
********** TEST 'test-suite :: MultiSource/Applications/ALAC/decode/alacconvert-decode.test' RESULTS **********
compile_time: 0.2192
exec_time: 0.0462
hash: "59620e187c6ac38b36382685ccd2b63b"
size: 83348
**********
PASS: test-suite :: MultiSource/Applications/ALAC/encode/alacconvert-encode.test (2 of 474)
...

注意！ 即使在您只想取得編譯時結果（程式碼大小、llvm 統計資訊等）的情況下，您也需要使用上述 llvm-lit 命令執行測試。在這種情況下，results.json 檔案將包含編譯時指標。

  1. 顯示和比較結果檔案（可選）

    # Make sure pandas and scipy are installed. Prepend `sudo` if necessary.
% pip install pandas scipy
# Show a single result file:
% test-suite/utils/compare.py results.json
# Compare two result files:
% test-suite/utils/compare.py results_a.json results_b.json

結構

test-suite 包含基準測試和測試程式。這些程式帶有參考輸出，以便可以檢查其正確性。該套件附帶工具，用於收集指標，例如基準測試執行時間、編譯時間和程式碼大小。

test-suite 分為多個目錄

  • SingleSource/

    包含僅為單一原始檔大小的測試程式。一個子目錄可能包含多個程式。

  • MultiSource/

    包含子目錄，這些子目錄是具有多個原始檔的完整程式。大型基準測試和整個應用程式都放在這裡。

  • MicroBenchmarks/

    使用 google-benchmark 程式庫的程式。這些程式定義了多次執行的函數，直到測量結果在統計上顯著為止。

  • External/

    包含無法直接與 test-suite 一起發行的程式碼的描述和測試資料。此目錄中最突出的成員是 SPEC CPU 基準測試套件。請參閱外部套件。

  • Bitcode/

    這些測試大多以 LLVM 位元碼編寫。

  • CTMark/

    包含指向其他基準測試的符號連結，形成編譯效能測量的代表性樣本。

基準測試

每個程式都可以作為正確性測試。某些程式不適合效能測量。將 TEST_SUITE_BENCHMARKING_ONLY CMake 選項設定為 ON 將停用它們。

MultiSource 基準測試由以下應用程式和基準測試組成

MultiSource

語言

應用領域

備註

7zip

C/C++

壓縮/解壓縮

ASCI_Purple

C

SMG2000 基準測試和求解器

記憶體密集型應用程式

ASC_Sequoia

C

模擬和求解器

BitBench

C

uudecode/uuencode 工具

用於函數式編譯器的位元流基準測試

Bullet

C++

Bullet 2.75 物理引擎

DOE-ProxyApps-C++

C++

HPC/科學應用程式

小型應用程式，代表我們較大的 DOE 工作負載

DOE-ProxyApps-C

C

HPC/科學應用程式

“

Fhourstones

C

遊戲/求解器

有效地解決 Connect-4 遊戲中位置的整數基準測試

Fhourstones-3.1

C

遊戲/求解器

“

FreeBench

C

基準測試套件

光線追蹤器、四子棋、神經網路、檔案壓縮器、快速傅立葉/餘弦/正弦變換

llubenchmark

C

連結串列微基準測試

mafft

C

生物資訊學

多序列比對程式

MallocBench

C

基準測試套件

cfrac、espresso、gawk、gs、make、p2c、perl

McCat

C

基準測試套件

快速排序、氣泡排序、特徵值

mediabench

C

基準測試套件

adpcm、g721、gsm、jpeg、mpeg2

MiBench

C

嵌入式基準測試套件

汽車、消費電子、辦公室、安全、電信應用程式

nbench

C

BYTE 雜誌的 BYTEmark 基準測試程式

NPB-serial

C

平行運算

NPB IS 程式的序列版本

Olden

C

資料結構

Olden 基準測試的 SGI 版本

OptimizerEval

C

求解器

Preston Brigg 的最佳化器評估框架

PAQ8p

C++

資料壓縮

Prolangs-C++

C++

基準測試套件

city、employ、life、NP、ocean、primes、simul、vcirc

Prolangs-C

C

基準測試套件

agrep、archie-client、bison、gnugo、unix-smail

Ptrdist

C

指標密集型基準測試套件

Rodinia

C

科學應用程式

backprop、pathfinder、srad

SciMark2-C

C

科學應用程式

FFT、LU、Montecarlo、稀疏矩陣乘法

sim

C

動態程式設計

一種時間效率高、線性空間的局部相似性演算法

tramp3d-v4

C++

數值分析

基於 FreePOOMA 的樣板密集型數值程式

Trimaran

C

加密

3des、md5、crc

TSVC

C

向量化基準測試

向量化編譯器測試套件 (TSVC)

VersaBench

C

基準測試套件

8b10b、beamformer、bmm、dbms、ecbdes

所有 MultiSource 應用程式都適用於效能測量，並且在設定 CMake 選項 TEST_SUITE_BENCHMARKING_ONLY 時將會執行。

配置

test-suite 具有配置選項，可自訂建置和執行基準測試。CMake 可以列印它們的列表

% cd test-suite-build
# Print basic options:
% cmake -LH
# Print all options:
% cmake -LAH

常用配置選項

  • CMAKE_C_FLAGS

    指定要傳遞給 C 編譯器調用的額外旗標。這些旗標也傳遞給 C++ 編譯器和連結器調用。請參閱 https://cmake.dev.org.tw/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html

  • CMAKE_C_COMPILER

    選擇要使用的 C 編譯器可執行檔。請注意，C++ 編譯器是自動推斷的，即當指定 path/to/clang 時，CMake 將自動使用 path/to/clang++ 作為 C++ 編譯器。請參閱 https://cmake.dev.org.tw/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html

  • CMAKE_Fortran_COMPILER

    選擇要使用的 Fortran 編譯器可執行檔。預設情況下未設定，除非執行 Fortran 測試套件，否則不需要。

  • CMAKE_BUILD_TYPE

    選擇建置類型，例如 OPTIMIZE 或 DEBUG，選擇一組預定義的編譯器旗標。無論 CMAKE_C_FLAGS 選項如何，都會應用這些旗標，並且可以透過修改 CMAKE_C_FLAGS_OPTIMIZE 等來變更這些旗標。請參閱 https://cmake.dev.org.tw/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html

  • TEST_SUITE_FORTRAN

    啟用 Fortran 測試。這是一項進行中的工作。更多資訊可以在 Flang 文件中找到

  • TEST_SUITE_RUN_UNDER

    使用給定的工具為測試調用加上前綴。這通常用於在模擬器工具中執行交叉編譯的測試。

  • TEST_SUITE_BENCHMARKING_ONLY

    停用不適合效能測量的測試。停用的測試要么運行時間非常短，要么受 I/O 效能主導，使其不適合作為編譯器效能測試。

  • TEST_SUITE_SUBDIRS

    要包含的目錄的以分號分隔的列表。這可以用於僅建置測試套件的一部分或包含外部套件。此選項對於更深的子目錄不可靠，因為它會跳過可能需要的中間 CMakeLists.txt 檔案。

  • TEST_SUITE_COLLECT_STATS

    收集內部 LLVM 統計資訊。在調用編譯器時附加 -save-stats=obj，並使 lit 執行器收集和合併統計資訊檔案。

  • TEST_SUITE_RUN_BENCHMARKS

    如果此項設定為 OFF，則 lit 實際上不會執行測試，而只會收集建置統計資訊，例如編譯時間和程式碼大小。

  • TEST_SUITE_USE_PERF

    使用 perf 工具進行時間測量，而不是 test-suite 附帶的 timeit 工具。perf 通常在 linux 系統上可用。

  • TEST_SUITE_SPEC2000_ROOT、TEST_SUITE_SPEC2006_ROOT、TEST_SUITE_SPEC2017_ROOT、…

    指定外部基準測試套件的安裝目錄。您可以在 External 目錄中的 README 檔案中找到有關預期版本或用法的更多資訊（例如 External/SPEC/README）

常用 CMake 旗標

  • -GNinja

    為 ninja 建置工具產生建置檔案。

  • -Ctest-suite/cmake/caches/<cachefile.cmake>

    使用 CMake 快取。test-suite 附帶多個 CMake 快取，這些快取預定義了常見或棘手的建置配置。

顯示和分析結果

compare.py 腳本顯示和比較結果檔案。當使用 -o filename.json 旗標調用 lit 時，會產生結果檔案。

使用範例

  • 基本用法

    % test-suite/utils/compare.py baseline.json
Warning: 'test-suite :: External/SPEC/CINT2006/403.gcc/403.gcc.test' has No metrics!
Tests: 508
Metric: exec_time

Program                                         baseline

INT2006/456.hmmer/456.hmmer                   1222.90
INT2006/464.h264ref/464.h264ref               928.70
...
             baseline
count  506.000000
mean   20.563098
std    111.423325
min    0.003400
25%    0.011200
50%    0.339450
75%    4.067200
max    1222.896800

  • 顯示 compile_time 或文字段大小指標

    % test-suite/utils/compare.py -m compile_time baseline.json
% test-suite/utils/compare.py -m size.__text baseline.json

  • 比較兩個結果檔案並篩選短時間運行的測試

    % test-suite/utils/compare.py --filter-short baseline.json experiment.json
...
Program                                         baseline  experiment  diff

SingleSour.../Benchmarks/Linpack/linpack-pc     5.16      4.30        -16.5%
MultiSourc...erolling-dbl/LoopRerolling-dbl     7.01      7.86         12.2%
SingleSour...UnitTests/Vectorizer/gcc-loops     3.89      3.54        -9.0%
...

  • 透過取每個結果檔案的最小運行時間來合併多個基準和實驗結果檔案

    % test-suite/utils/compare.py base0.json base1.json base2.json vs exp0.json exp1.json exp2.json

使用 LNT 進行持續追蹤

LNT 是一組用於持續監控效能的用戶端和伺服器工具。您可以在 https://llvm.dev.org.tw/docs/lnt 找到更多資訊。LLVM 專案的官方 LNT 實例託管在 http://lnt.llvm.org。

外部套件

可以透過以下方式啟用外部套件，例如 SPEC

  • 將它們放置（或連結）到 test-suite/test-suite-externals/xxx 目錄中（範例：test-suite/test-suite-externals/speccpu2000）

  • 使用配置選項，例如 -D TEST_SUITE_SPEC2000_ROOT=path/to/speccpu2000

您可以在各自的 README 檔案中找到更多資訊，例如 test-suite/External/SPEC/README。

對於 SPEC 基準測試，您可以透過 TEST_SUITE_RUN_TYPE 配置選項在 test、train 和 ref 輸入資料集之間切換。預設情況下使用 train 資料集。

除了 SPEC 之外，多媒體框架 ffmpeg 和 dav1d 也可以以相同的方式作為外部專案連結。透過將它們包含在 llvm-test-suite 中，可以編譯更多潛在可向量化的程式碼

  • 這僅僅透過觸發程式碼產生斷言就可以捕獲編譯器錯誤。包含它們還會增加小的程式碼正確性測試，這些測試會將編譯器產生的函數的輸出與手寫組合語言函數進行比較。（在 x86 上，建置組合語言需要安裝 nasm 工具。）整合到 llvm-test-suite 中並不會運行專案的完整測試套件。這些專案還包含用於測量某些函數效能的微基準測試。請參閱 llvm-test-suite/External 下各自的 ffmpeg 和 dav1d 目錄中的 README.md 檔案以了解更多詳細資訊。

自訂套件

您可以使用 test-suite 基礎設施建置自訂套件。自訂套件在頂層目錄中具有 CMakeLists.txt 檔案。如果 CMakeLists.txt 放置在 test-suite 的子目錄中或設定 TEST_SUITE_SUBDIRS 變數時，將會自動選取它

% cmake -DTEST_SUITE_SUBDIRS=path/to/my/benchmark-suite ../test-suite

設定檔導向最佳化

設定檔導向最佳化需要編譯和執行兩次。首先，應使用啟用了設定檔產生檢測的工具和訓練資料設定來編譯基準測試。lit 執行器將使用 llvm-profdata 合併設定檔，以便它們可以用於第二次編譯運行。

範例

# Profile generation run using LLVM IR PGO:
% cmake -DTEST_SUITE_PROFILE_GENERATE=ON \
        -DTEST_SUITE_USE_IR_PGO=ON \
        -DTEST_SUITE_RUN_TYPE=train \
        ../test-suite
% make
% llvm-lit .
# Use the profile data for compilation and actual benchmark run:
% cmake -DTEST_SUITE_PROFILE_GENERATE=OFF \
        -DTEST_SUITE_PROFILE_USE=ON \
        -DTEST_SUITE_RUN_TYPE=ref \
        .
% make
% llvm-lit -o result.json .

若要使用 Clang 前端的 PGO 而不是 LLVM IR PGO，請設定 -DTEST_SUITE_USE_IR_PGO=OFF。

TEST_SUITE_RUN_TYPE 設定僅影響 SPEC 基準測試套件。

交叉編譯和外部裝置

編譯

CMake 允許透過工具鏈檔案交叉編譯到不同的目標。更多資訊可以在這裡找到

使用 test-suite/cmake/caches/target-target-*-iphoneos-internal.cmake CMake 快取檔案可以從 macOS 交叉編譯到 iOS；這需要內部 iOS SDK。

執行

在交叉編譯設定中執行測試有兩種方法

  • 透過 SSH 連線到外部裝置：TEST_SUITE_REMOTE_HOST 選項應設定為 SSH 主機名稱。可執行檔和資料檔案需要在編譯後傳輸到裝置。這通常透過 rsync make 目標完成。在此之後，lit 執行器可以在主機上使用。它將在基準測試和驗證命令列前面加上 ssh 命令。

    範例

    % cmake -G Ninja -D CMAKE_C_COMPILER=path/to/clang \
        -C ../test-suite/cmake/caches/target-arm64-iphoneos-internal.cmake \
        -D CMAKE_BUILD_TYPE=Release \
        -D TEST_SUITE_REMOTE_HOST=mydevice \
        ../test-suite
% ninja
% ninja rsync
% llvm-lit -j1 -o result.json .

  • 您可以使用 TEST_SUITE_RUN_UNDER 設定為目標機器指定模擬器。lit 執行器將在所有基準測試調用前面加上它。

透過 LNT 執行 test-suite

LNT 工具可以執行 test-suite。當向 LNT 實例提交測試結果時使用此項。請參閱 https://llvm.dev.org.tw/docs/lnt/tests.html#llvm-cmake-test-suite 以了解詳細資訊。

透過 Makefiles 執行 test-suite（已棄用）

注意：test-suite 附帶一組被認為已棄用的 Makefiles。它們不支援較新的測試模式，例如 Bitcode 或 Microbenchmarks，並且更難以使用。

舊文件可在test-suite Makefile 指南中找到。