gem5 Resources

gem5 resources is a repository providing sources for artifacts known and proven compatible with the gem5 architecture simulator. These resources are not necessary for the compilation or running of gem5, but may aid users in producing certain simulations.

Why gem5 Resources?

gem5 has been designed with flexibility in mind. Users may simulate a wide variety of hardware, with an equally wide variety of workloads. However, requiring users to find and configure workloads for gem5 (their own disk images, their own OS boots, their own tests, etc.) is a significant investment, and a hurdle to many.

The purpose of gem5 resources is therefore to provide a stable set of commonly used resources, with proven and documented compatibility with gem5. In addition to this, gem5 resources also puts emphasis on reproducibility of experiments by providing citable, stable resources, tied to a particular release of gem5.

Where can I obtain the gem5 resources?

The gem5 resources are hosted on our Google Cloud Bucket. Listed below are the compiled resources presently available, as well as links to their sources in the gem5 resources repository. These are resources sources for gem5 20.0.

Resource Compiled/Built Resource Source
asmtest 351 test binaries, downloadable with https://dist.gem5.org/dist/v20/test-progs/asmtest/bin/<binary> here
riscv-tests dhryston.riscv, median.riscv, mm.riscv, mt-matmul.riscv, mt-vvadd.riscv, multiply.riscv, pmp.riscv, qsort.riscv, rsort.riscv, spmv.riscv, towers.riscv, vvadd.riscv here
insttests insttest-rv64a, insttest-rv64c, insttest-rv64d, insttest-rv64f, insttest-rv64i, insttest-rv64m here
pthreads here
square here
spec-2006 here
spec-2017 here
gapbs Disk Image here
parsec Disk Image here
npb Disk Image here
Linux boot-exit Disk Image here

How do I obtain the gem5 resource sources?

gem5 resources sources may be obtained from https://gem5.googlesource.com/public/gem5-resources:

git clone https://gem5.googlesource.com/public/gem5-resources

The HEAD of the master branch will point towards a set of resource sources compatible with the latest release of gem5 (which can be obtained via git clone https://gem5.googlesource.com/public/gem5).

Please consult the README.md file for information on compiling individual gem5 resources. Where license permits, the README.md file will provide a link to download the compiled resource from our dist.gem5.org Google Cloud Bucket.

How is gem5 Resources repository constructed?

The structure of this repository is as follows:

Versioning

The HEAD of the master branch will contain resources that can be built and run with the latest release of gem5 (that at the HEAD of the master branch on https://gem5.googlesource.com/public/gem5).

If you wish to use resources for an older release of gem5, then you must checkout the version of gem5 resources for that release. We tag the repository at specific versions. E.g., for gem5 20.0, there will be a tag for gem5 20.0. Checking out the gem5 resources at that tag will give the resources confirmed to work for that version.

To list all the tags in the repository: git tag.

To checkout a specific tag: git checkout <tag name>.

It should noted that there will be no tag for the most recent release of gem5, as the most recent resources for the latest release are found at the HEAD of the master branch. The reason for this is resources may be added continually during the course of a gem5 release. Upon the next release of a gem5 version, gem5 resources is tagged.

For example, assuming the current version of gem5 is v20.2. The gem5 resources will contain tags for v20.0 and v20.1. The current HEAD of the master branch will contain resources for gem5 v20.2. If new resources are added, they will be added as commits on top of the master branch. During this time, the next major version of gem5 will be under develop on the gem5 develop branch. The gem5 resources repository also has a develop branch for resources developed, expanded, and/or modified for the upcoming gem5 release. Upon the release of this new major version of gem5 (v20.3), the master branch is tagged (in this case, as v20.2) and the develop branch is merged into the master.

Citing a resource

We strongly recommend gem5 resources are cited in publications to aid in replication of experiments, tutorials, etc.

To cite as a URL, please use the following formats:

# For the git repository at a particular revision:
https://gem5.googlesource.com/public/gem5-resources/+/<revision>/src/<resource>

# For the git repository at a particular tag:
https://gem5.googlesource.com/public/gem5-resources/+/refs/heads/<tag>/src/<resource>

Alternatively, as BibTex:

@misc{gem5-resources,
  title = {gem5 Resources. Resource: <resource>},
  howpublished = {\url{https://gem5.googlesource.com/public/gem5-resources/+/<revision>/src/<resource>}},
  note = {Git repository at revision '<revision>'}
}

@misc{gem5-resources,
  title = {gem5 Resources. Resource: <resource>},
  howpublished = {\url{https://gem5.googlesource.com/public/gem5-resources/+/refs/heads/<tag>/src/<resource>}},
  note = {Git repository at tag '<tag>'}
}

How to I contribute to gem5 Resources?

Changes to the gem5 resources repository are made to the develop branch via our Gerrit code review system. Therefore, to make changes, first clone the repository:

git clone https://gem5.googlesource.com/public/gem5-resources

Then make changes and commit. When ready, push to Gerrit with:

git push origin HEAD:refs/for/master

This will add resources to be used in the latest release of gem5.

To contribute resources to the next release of gem5,

git clone https://gem5.googlesource.com/public/gem5-resources
git checkout --track origin/develop

Then make changes, commit, and push with:

git push origin HEAD:refs/for/develop

Commit message heads should not exceed 65 characters and start with the tag resources:. The description after the header must not exceed 72 characters.

E.g.:

resources: Adding a new resources X

This is where the description of this commit will occur taking into
note the 72 character line limit.

We strongly advise contributors follow our Style Guide where possible and appropriate.

Any change will then be reviewed via our Gerrit code review system. Once fully accepted and merged into the gem5 resources repository, please contact Bobby R. Bruce (bbruce@ucdavis.edu) to have any compiled sources uploaded to the gem5 resources bucket.