ChampSim: a trace-based simulator for cache and branch research

What ChampSim models and what it leaves out

ChampSim is described as a trace-based simulator for a microarchitecture study, and its evaluation metric is stated plainly: it measures IPC, the instructions per cycle value, as a performance metric, with other useful statistics printed at the end of a simulation. The scope is the cache hierarchy, not the whole machine.

The directory layout shows the modelling surface. There is a branch/ directory for branch predictors, a btb/ directory for the branch target buffer, a prefetcher/ directory for data prefetchers, a replacement/ directory for replacement policies, and a config/ directory for the per-module configuration. A module.options file and a global.options file sit at the root, and inc/ holds headers while src/ holds the simulator core.

The Makefile confirms the modularity, because it computes separate roots for each module family by appending a directory name to the module root, so a branch module and a prefetcher module compile as independent objects. The same file also carries three make-time customisation points, BIN_ROOT, OBJ_ROOT and DEP_ROOT, which decide where the binary and the intermediate objects go.

What is absent matters as much. There is no mention of power or energy modelling, no full-system simulation, and no timing accuracy claim, because a trace-driven design counts instructions and models memory hierarchy behaviour rather than cycles of wall clock time. That is a deliberate trade: a research harness that answers cache and prefetcher questions quickly, at the cost of fidelity in areas it does not attempt.

Dependencies through vcpkg and the build sequence

ChampSim manages its dependencies with vcpkg, and the repository ships vcpkg as a submodule, so the setup is three commands from a fresh clone.

git submodule update --init
vcpkg/bootstrap-vcpkg.sh
vcpkg/vcpkg install

The first command materialises the bundled vcpkg tree, the second bootstraps the vcpkg binary itself, and the third installs the libraries listed in vcpkg.json. The Makefile shows which libraries that is, linking against CLI11 for command line parsing, lzma, z and bz2 for compressed trace input, and fmt for formatting.

The build then needs a configuration. ChampSim takes a JSON configuration script, and the README points to champsim_config.json as a fully specified example. All options in that file are optional and fall back to defaults, and the configuration script can also be run with no input at all, in which case an empty file is assumed.

$ ./config.sh <configuration file>
$ make

The order matters. config.sh is what turns the JSON into the generated build configuration under the .csconfig object directory, and make then compiles the result. Running make without a prior config.sh invocation builds the default configuration, which is a reasonable starting point but not what you want when you are testing a specific policy.

Running a simulation and reading the statistics

The simulator runs as a plain binary with instruction counts for a warmup phase and a simulation phase, and a path to a trace file.

$ bin/champsim --warmup-instructions 200000000 --simulation-instructions 500000000 ~/path/to/traces/600.perlbench_s-210B.champsimtrace.xz

The counts are in instructions retired, not in cycles, and the README is explicit that the statistics printed at the end of the simulation cover only the simulation phase. The warmup phase exists to let the simulated state settle, so a run with a warmup of zero measures a cold machine that no real workload would resemble.

Trace files come from the competition archives. Traces for the 3rd Data Prefetching Championship are published at the DPC-3 site on Stony Brook's servers, and the traces for the 2nd Cache Replacement Championship come from a separate link. Storage for these is credited to Daniel Jimenez at Texas A&M University and Mike Ferdman at Stony Brook University. The README adds a warning worth repeating: frequent users are encouraged to maintain their own repository of traces, in case the links ever break. That is a practical instruction, since the simulator reads compressed trace files and depends on that archive remaining reachable.

For anyone who needs a trace of their own program, the README points to the tracer/ directory, which holds example tracing utilities.

Adding a prefetcher through the empty template

The extension workflow is three steps, and the README is clear that the template you copy is an L2 prefetcher, so if you are designing for a different cache level the template is only a starting point.

First, create the directory and copy the empty template into it.

$ mkdir prefetcher/mypref
$ cp prefetcher/no_l2c/no.cc prefetcher/mypref/mypref.cc

Then edit your own file with the editor of your choice.

$ vim prefetcher/mypref/mypref.cc

Finally, register the new component in the configuration file, where the prefetcher name matches the directory you created.

{
    "L2C": {
        "prefetcher": "mypref"
    }
}

The name mypref in the configuration is what links the JSON to the prefetcher/mypref directory, which is why the copy step insists on that exact naming. After registering it, the usual sequence applies: run config.sh with the configuration file, run make, then run the binary against a trace.

$ ./config.sh <configuration file>
$ make
$ bin/champsim --warmup-instructions 200000000 --simulation-instructions 500000000 600.perlbench_s-210B.champsimtrace.xz

The same pattern applies to branch predictors and replacement policies, since the Makefile treats branch, btb, prefetcher and replacement as parallel module families. The test/ directory holds the test targets, and the Makefile exposes test and pytest targets alongside clean, configclean and compile_commands.

Where ChampSim is the wrong instrument

The main limitation is the trace abstraction itself. Because ChampSim replays a recorded instruction stream, it cannot react to timing feedback, it cannot model a real operating system, and it cannot represent speculative execution effects that depend on a live microarchitecture. A result from ChampSim is a statement about a policy under a modelled memory hierarchy, not a prediction of how a specific machine will run.

Second, there is no power or energy model in the repository. Any conclusion about energy or thermal behaviour has to come from elsewhere, and the IPC metric gives no help there.

Third, the dependency chain is heavier than a single binary would be. A newcomer must initialise a submodule, bootstrap vcpkg, install libraries, generate a configuration and compile, and the first build can fail for reasons that have nothing to do with the model. The build also relies on a C++ toolchain plus the vendored libraries from vcpkg, so compiler and library version mismatches are a known class of friction in this layout.

Finally, results depend on trace choice. The competition traces are single fixed workloads, and a policy that wins on one trace can lose on another, so a single run tells you very little.

Licence, citation expectations and release cadence

The project is under the Apache-2.0 licence, with the LICENSE file at the root of the repository, and it is maintained at Texas A&M University with support from the computer architecture community.

The licensing comes with an expectation that the README states plainly: ChampSim is the result of academic research, and users are asked to cite it, with a specific reference given to the 2022 paper on the Championship Simulator, including a DOI pointing to an arXiv entry. There is also a mechanism for credit. Users who publish work with ChampSim may submit a pull request modifying PUBLICATIONS_USING_CHAMPSIM.bib to have their paper listed in the documentation.

Releases follow a dated calendar scheme rather than semantic versioning: 2026-04 dated 2026-04-10, 2024-12 dated 2024-12-05, and 2023-08 dated 2023-08-09. That makes sense for a competition-driven project, since the cycles are tied to the cache and prefetch championships, but it also means the version number tells you a date rather than a compatibility level.

The repository is not archived and its last push was on 2026-09-13, so the simulator is still being worked on. The 2026-04 release is a good target for a new user, since it is the most recent one and the last push is later than it.

Editorial conclusion

ChampSim fits graduate students, architecture competition entrants and anyone comparing cache, prefetcher or replacement policies against a common harness, and the vcpkg plus config.sh plus make path is quick to reproduce. It does not fit work that needs cycle-accurate timing, power or full-system behaviour, since the trace-driven design abstracts all of that away. Verify first that the trace you intend to use is still downloadable, since the README itself asks users to keep their own copy of trace data.

Frequently asked questions

Official sources

1. ChampSim/ChampSim on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases