From 9f2533b1ae25c6524459ad316343f380c0adc5f3 Mon Sep 17 00:00:00 2001 From: Jason Lowe-Power Date: Tue, 20 Aug 2024 14:31:04 -0700 Subject: [PATCH] Update the readme to be correct Signed-off-by: Jason Lowe-Power --- README.md | 88 +++++++------------------------------------------------ 1 file changed, 10 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 7cf7a46..c43afb7 100644 --- a/README.md +++ b/README.md @@ -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: (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 ``` @@ -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.