Skip to content

Commit

Permalink
Update the readme to be correct
Browse files Browse the repository at this point in the history
Signed-off-by: Jason Lowe-Power <jason@lowepower.com>
  • Loading branch information
powerjg committed Aug 20, 2024
1 parent f86711c commit 9f2533b
Showing 1 changed file with 10 additions and 78 deletions.
88 changes: 10 additions & 78 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,30 @@ It has been built with the assumption users will utilize [Codespaces](https://gi

The repository contains the following directories:

* [docker](docker) :
The source code for the Docker image used by the [Dockerfile](gem5/util/dockerfiles/devcontainer/Dockerfile) to create the Codespace Docker container.
* gem5 :
v24.0.0.0 of gem5.
* gem5-resources :
gem5-resources which may be used with v24.0 of gem5.
* materials: Example materials used as part of the tutorial.
* modules: Source for the accompanying website: <https://gem5bootcamp.github.io/gem5-bootcamp-env> (This link is not up to date.)
The website contains links to slides, presentation videos, and notes for the tutorials.

**Note:** 'gem5' and 'gem5-resources' are submodules though the [.devcontainer/devcontainer.json](.devcontainer/devcontainer.json) file specifies that a `git submodule update --init --recursive` command is executed when the Codespace Docker container is created.

**Note:** The `.devcontainer/on_create.sh` script is executed the first time the codespace is created.
This will pre-download much of the resources (disk images, etc.) that are used in the gem5 tutorials.
It can take a while to do this.
A pre-built devcontainer is set up for the bootcamp and should be used to avoid this delay.

The container used by Codespaces is built from [Dockerfile](gem5/util/dockerfiles/devcontainer/Dockerfile).
It contains:

* All gem5 dependencies (inc. optional dependencies).
* Prebuilt gem5 binaries:
* `/usr/local/bin/gem5` (gem5 ALL ISAs with CHI protocol)
* `/usr/local/bin/gem5-default` (default gem5 ALL build with MESI_Two_Level)
* `/usr/local/bin/gem5-chi` (`/usr/local/bin/gem5`) (gem5 ALL ISAs with CHI protocol)
* `/usr/local/bin/gem5-mesi` (default gem5 ALL build with MESI_Two_Level)
* `/usr/local/bin/gem5-vega` (x86-only with GPU protocol)
* `/usr/local/bin/gem5-vega-se` (same as above, but compiled with 20.04)
* A RISCV64 and an AARCH64 GNU cross-compiler:
* RISCV64 GNU cross-compiler found in `/opt/cross-compiler/riscv64-linux/`.
* AARCH64 GNU cross-compiler found in `/opt/cross-compiler/aarch64-linux/`.
* ROCm development environment 6.1.2 (note, this is why the container is based on 22.04 instead of 24.04)

## Beginners' example

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

```
```sh
gem5 gem5/configs/example/gem5_library/arm-hello.py
```

Expand Down Expand Up @@ -64,67 +57,6 @@ git commit -m "git submodules updated"
git push
```

## Best practices

### 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.

```sh
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.

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

3. Checkout this branch:

```sh
git checkout example-1
```

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

```sh
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.

```sh
git checkout stable
```

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

```sh
git checkout example-1
```

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

```sh
git branch
```

## Note on running GPU SE

You can use docker.
Below is an example command

```sh
docker run -v $PWD:$PWD -v /usr/local/bin:/usr/local/bin -w $PWD ghcr.io/gem5/gcn-gpu:v24-0 gem5-vega-se gem5/configs/example/apu_se.py -n 3 -c square
```
See [creating-content.md](creating-content.md) for more information on how to create content for the gem5 bootcamp.

0 comments on commit 9f2533b

Please sign in to comment.