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.
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.
To find a specific resource with the gem5 Resources, we recommend using the gem5 Resources Website. Detailed information on how searching, filtering and sorting works on this website is on this help page.
The gem5 Resources are hosted on our Google Cloud Bucket. Links to the resources can be found gem5 resources README.md file. The resource metadata is stored in a MongoDB database hosted on MongoDB Atlas. To request updates to gem5 resources, create an issue or mail gem5-dev.
When you find the Resource that you want to use in your simulation, navigate to the ‘Usage’ tab of that Resource.
For the purpose of this tutorial, let's assume that the Resource you are looking for is riscv-hello, found here.In the ‘Usage’ tab of this Resource, you will find the code that can be pasted in a gem5 simulation to use this Resource.
In this case, the code is obtain_resource(resource_id="riscv-hello").
To use the obtain_resource function, you require the following import statement:
from gem5.resources.resource import obtain_resource
The obtain_resource function accepts the following parameters:
resource_id: The ID of the Resource you want to use.resource_version: An optional parameter that specifies the version of the Resource you want to use. If not specified, the latest version of the Resource compatible with the version of gem5 being used will be used.clients: An optional parameter that specifies the list of clients that gem5 would search for the Resource in. If not specified, gem5 will search for the Resource in all clients specified in the src/python/gem5_default_config.py file. By default, gem5 will use the public MongoDB metadata database to find resources. This can be overridden to specify your own local resource metadata.When you find the Workload that you want to use in your simulation, navigate to the ‘Usage’ tab of that Workload.
For the purpose of this tutorial, let's assume that the Workload you are looking for is riscv-ubuntu-20.04-boot, found here. In the ‘Usage’ tab of this Workload, you will find the code that can be pasted in a gem5 simulation to use this Workload.
In this case, the code is Workload("riscv-ubuntu-20.04-boot").
To use the Workload class, you require the following import statement:
from gem5.resources.workload import Workload
The Workload class accepts the following parameters:
workload_name: The name of the Workload you want to use.resource_directory: An optional parameter that specifies where any resources should be download and accessed from.resource_version: An optional parameter that specifies the version of the Resource that should be used. If not specified, the latest version of the Resource compatible with the version of gem5 being used will be used.clients: An optional parameter that specifies a list of clients that gem5 would search for the Resource in. If not specified, gem5 will search for the Resource in all clients specified in the src/python/gem5_default_config.py file.To use a Custom Resource in gem5, we recommend using one of the supported data sources formats in gem5. Currently, we support MongoDB Atlas, local JSON files and remote JSON files.
You can use your own config file by overriding the GEM5_DEFAULT_CONFIG variable while running a file.
NOTE: Any Custom Resource you add must be compliant with the gem5 Resources Schema.
There is a utility in utils/gem5-resources-manager which provides a GUI for updating and creating resources for both the public resources (only modifiable by gem5 admins) and local resource metadata. You can find more information on the gem5 Resources Manager in the README file.
gem5 resources sources may be obtained from https://github.com/gem5/gem5-resources:
git clone https://github.com/gem5/gem5-resources
The HEAD of the stable branch will point towards a set of resource sources compatible with the latest release of gem5 (which can be obtained via git clone https://github.com/gem5/gem5.git).
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.
The structure of this repository is as follows:
Each resource can have multiple versions. A version is in the form of <major>.<minor>.<patch>. The versioning scheme is based on Semantic Versioning. Each version of a resource is linked to one or more gem5 versions (e.g., v20.0, v20.1, v20.2, etc.).
By default, gem5 uses the latest version of a resource compatible with the version of gem5 being used. However, users may specify a particular version of a resource to use. If a user specifies a version of a resource that is not compatible with the version of gem5 being used, gem5 will throw a warning. You may still use the resource at your own risk.
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://github.com/gem5/gem5-resources/<revision>/src/<resource> # For the git repository at a particular tag: https://github.com/gem5/gem5-resources/tree/<branch>/src/<resource>
Alternatively, as BibTex:
@misc{gem5-resources,
title = {gem5 Resources. Resource: <resource>},
howpublished = {\url{https://github.com/gem5/gem5-resources/<revision>/src/<resource>}},
note = {Git repository at revision '<revision>'}
}
@misc{gem5-resources,
title = {gem5 Resources. Resource: <resource>},
howpublished = {\url{https://github.com/gem5/gem5-resources/tree/<branch>/src/<resource>}},
note = {Git repository at tag '<tag>'}
}
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://github.com/gem5/gem5-resources.git
Then make changes and commit. When ready, push to Gerrit with:
git push origin HEAD:refs/for/stable
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://github.com/gem5/gem5-resources.git 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.