This repository has been designed for use in gem5 tutorials. It has been built with the assumption users will utilize Codespaces to learn gem5.

The repository contains the following directories:

• docker : The source code for the Docker image used by .devcontainer/Dockerfile to create the Codespace Docker container.
• gem5 : gem5 checkedout at revision 'cd35c9a6'.
• gem5-resources : gem5-resources checked out at 'dbac39a'.

Note: 'gem5' and 'gem5-resources' are submodules though the .devcontainer/devcontainer.json file specifies that a git module update --init --recursive command is executed when the Codespace Docker container is created.

The container used by Codespaces is built from .devcontainer/Dockerfile. It contains:

• All gem5 dependencies (inc. optional dependencies).
• The 'gem5.fast' binary for v22.1 of gem5, compiled for with scons build/ALL/gem5.fast.. This exists in PATH, stored in /usr/local/bin/gem5.fast

Beginners' example

The following can be used within the Codespace container to run a basic gem5 simulation straight away:

gem5-all gem5/configs/example/gem5_library/arm-hello.py

This will execute a "Hello world!" program inside a simulated ARM system.

Updating submodules

In this project we have two submodules: 'gem5' and 'gem5-resources'. These are automatically obtained when the codespaces is initialized.

To update the git submodules to be in-sync with their remote origins (that hosted on our googlesource), execute the following command:

git submodule update --remote

This repository may be updated to these in-sync submodules by running the following (this assumes you have correct permissions to do so):

git add gem5 gem5-resources
git commit -m "git submodules updated"
git push

Best practises

Using branches

A good strategy when working with gem5 is to use branches. In the 'gem5' directory, you can use branches to segregate your development. A typical workflow would be as follows.

1. Start from the stable branch. This will ensure you are starting from a clean, stable version of gem5.

git checkout stable

2. Create another branch to work on. Initially this branch will be idential to stable but with a name of your choosing.

git branch example-1 # Creating a new branch named 'example-1'.

3. Checkout this branch:

git checkout example-`

4. Make changes on this branch and commit the changes. For example:

echo "Create a test commit" >test.txt
git add test.txt
git commit -m "misc: Adding a test commit"

5. When done, or wishing to move onto something else, checkout stable. This effectively reverts the changes made on the branch.

git checkout stable

6. You may return to this branch whenever you want.

git checkout example-1

To see a list of all available branches you can execute:

git branch