NAME

llvm-exegesis - LLVM Machine Instruction Benchmark

SYNOPSIS

llvm-exegesis [options]

DESCRIPTION

llvm-exegesis is a benchmarking tool that uses information available in LLVM to measure host machine instruction characteristics like latency, throughput, or port decomposition.

Given an LLVM opcode name and a benchmarking mode, llvm-exegesis generates a code snippet that makes execution as serial (resp. as parallel) as possible so that we can measure the latency (resp. inverse throughput/uop decomposition) of the instruction. The code snippet is jitted and, unless requested not to, executed on the host subtarget. The time taken (resp. resource usage) is measured using hardware performance counters. The result is printed out as YAML to the standard output.

The main goal of this tool is to automatically (in)validate the LLVM's TableDef scheduling models. To that end, we also provide analysis of the results.

llvm-exegesis can also benchmark arbitrary user-provided code snippets.

SUPPORTED PLATFORMS

llvm-exegesis currently only supports X86 (64-bit only), ARM (AArch64 only, snippet generation is sparse), MIPS, and PowerPC (PowerPC64LE only) on Linux for benchmarking. Not all benchmarking functionality is guaranteed to work on every platform. llvm-exegesis also has a separate analysis mode that is supported on every platform that LLVM is.

To enable benchmarking in llvm-exegesis, LLVM must be configured and built with LLVM_ENABLE_LIBPFM enabled, as llvm-exegesis depends on libpfm4 for accessing performance counters. Benchmarking may fail if the target CPU is unsupported by libpfm. This can be verified by setting LIBPFM_VERBOSE and LIBPFM_DEBUG environment variables to enable verbose or debug mode for libpfm. If libpfm is installed in a non-standard directory, LLVM can be configured to locate the necessary library and header files by setting LIBRARY_PATH, C_INCLUDE_PATH, and CPLUS_INCLUDE_PATH environment variables. Additionally, LD_LIBRARY_PATH should be set so that llvm-exegesis can locate the libpfm library during execution.

SNIPPET ANNOTATIONS

llvm-exegesis supports benchmarking arbitrary snippets of assembly. However, benchmarking these snippets often requires some setup so that they can execute properly. llvm-exegesis has five annotations and some additional utilities to help with setup so that snippets can be benchmarked properly.

EXAMPLE 1: BENCHMARKING INSTRUCTIONS

Assume you have an X86-64 machine. To measure the latency of a single instruction, run:

$ llvm-exegesis --mode=latency --opcode-name=ADD64rr

Measuring the uop decomposition or inverse throughput of an instruction works similarly:

$ llvm-exegesis --mode=uops --opcode-name=ADD64rr
$ llvm-exegesis --mode=inverse_throughput --opcode-name=ADD64rr

The output is a YAML document (the default is to write to stdout, but you can redirect the output to a file using --benchmarks-file):

---
key:


  opcode_name:     ADD64rr


  mode:            latency


  config:          ''
cpu_name:        haswell
llvm_triple:     x86_64-unknown-linux-gnu
num_repetitions: 10000
measurements:


  - { key: latency, value: 1.0058, debug_string: '' }
error:           ''
info:            'explicit self cycles, selecting one aliasing configuration.
Snippet:
ADD64rr R8, R8, R10
'
...

To measure the latency of all instructions for the host architecture, run:

$ llvm-exegesis --mode=latency --opcode-index=-1

EXAMPLE 2: BENCHMARKING A CUSTOM CODE SNIPPET

To measure the latency/uops of a custom piece of code, you can specify the snippets-file option (- reads from standard input).

$ echo "vzeroupper" | llvm-exegesis --mode=uops --snippets-file=-

Real-life code snippets typically depend on registers or memory. llvm-exegesis checks the liveliness of registers (i.e. any register use has a corresponding def or is a "live in"). If your code depends on the value of some registers, you need to use snippet annotations to ensure setup is performed properly.

For example, the following code snippet depends on the values of XMM1 (which will be set by the tool) and the memory buffer passed in RDI (live in).

# LLVM-EXEGESIS-LIVEIN RDI
# LLVM-EXEGESIS-DEFREG XMM1 42
vmulps        (%rdi), %xmm1, %xmm2
vhaddps       %xmm2, %xmm2, %xmm3
addq $0x10, %rdi

EXAMPLE 3: BENCHMARKING WITH MEMORY ANNOTATIONS

Some snippets require memory setup in specific places to execute without crashing. Setting up memory can be accomplished with the LLVM-EXEGESIS-MEM-DEF and LLVM-EXEGESIS-MEM-MAP annotations. To execute the following snippet:

movq $8192, %rax
movq (%rax), %rdi

We need to have at least eight bytes of memory allocated starting 0x2000. We can create the necessary execution environment with the following annotations added to the snippet:

# LLVM-EXEGESIS-MEM-DEF test1 4096 7fffffff
# LLVM-EXEGESIS-MEM-MAP test1 8192
movq $8192, %rax
movq (%rax), %rdi

EXAMPLE 4: ANALYSIS

Assuming you have a set of benchmarked instructions (either latency or uops) as YAML in file /tmp/benchmarks.yaml, you can analyze the results using the following command:

  $ llvm-exegesis --mode=analysis \
--benchmarks-file=/tmp/benchmarks.yaml \
--analysis-clusters-output-file=/tmp/clusters.csv \
--analysis-inconsistencies-output-file=/tmp/inconsistencies.html

This will group the instructions into clusters with the same performance characteristics. The clusters will be written out to /tmp/clusters.csv in the following format:

cluster_id,opcode_name,config,sched_class
...
2,ADD32ri8_DB,,WriteALU,1.00
2,ADD32ri_DB,,WriteALU,1.01
2,ADD32rr,,WriteALU,1.01
2,ADD32rr_DB,,WriteALU,1.00
2,ADD32rr_REV,,WriteALU,1.00
2,ADD64i32,,WriteALU,1.01
2,ADD64ri32,,WriteALU,1.01
2,MOVSX64rr32,,BSWAP32r_BSWAP64r_MOVSX64rr32,1.00
2,VPADDQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.02
2,VPSUBQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.01
2,ADD64ri8,,WriteALU,1.00
2,SETBr,,WriteSETCC,1.01
...

llvm-exegesis will also analyze the clusters to point out inconsistencies in the scheduling information. The output is an html file. For example, /tmp/inconsistencies.html will contain messages like the following : [image]

Note that the scheduling class names will be resolved only when llvm-exegesis is compiled in debug mode, else only the class id will be shown. This does not invalidate any of the analysis results though.

OPTIONS

EXIT STATUS

llvm-exegesis returns 0 on success. Otherwise, an error message is printed to standard error, and the tool returns a non 0 value.

AUTHOR

Maintained by the LLVM Team (https://llvm.org/).

COPYRIGHT

2003-2025, LLVM Project