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 bitcode 编写。

  • 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, sparse matmul

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.com.cn/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html

  • CMAKE_C_COMPILER

    选择要使用的 C 编译器可执行文件。请注意，C++ 编译器是自动推断的，即当指定 path/to/clang 时，CMake 将自动使用 path/to/clang++ 作为 C++ 编译器。请参阅 https://cmake.com.cn/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.com.cn/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

    要包含的目录的分号分隔列表。这可以用于仅构建 test-suite 的部分或包含外部套件。此选项对于更深的子目录无法可靠地工作，因为它会跳过可能需要的中间 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.net.cn/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 文件。如果放置在 test-suite 的子目录中或设置 TEST_SUITE_SUBDIRS 变量，则会自动拾取 CMakeLists.txt

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

Profile Guided Optimization

Profile guided optimization 需要编译和运行两次。首先，应该在启用配置文件生成检测并设置为训练数据的情况下编译基准测试。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.net.cn/docs/lnt/tests.html#llvm-cmake-test-suite。

通过 Makefiles 运行 test-suite（已弃用）

注意：test-suite 附带一组被认为已弃用的 Makefiles。它们不支持较新的测试模式，例如 Bitcode 或 Microbenchmarks，并且更难使用。

旧文档可在 test-suite Makefile 指南 中找到。