diff --git a/README.md b/README.md index b78abd4be..a6d30d5b7 100644 --- a/README.md +++ b/README.md @@ -43,28 +43,66 @@ regular usage. **Note: Resource files for gem5 v19.0.0.0, our legacy release, can be found under http://dist.gem5.org/dist/current**. -## Making Changes +## Submitting a contribution -Changes to this repository are made to the develop branch via our Gerrit -code review system. Therefore, to make changes, first clone the repository -checkout the develop branch: +We utilize GitHub to review changes made to the gem5-resources. To make changes, +follow the steps below. -``` -git clone https://gem5.googlesource.com/public/gem5-resources -git checkout --track origin/develop -``` +1. Fork the gem5 repository on GitHub from https://github.com/gem5/gem5-resources/. +2. Create a new branch in your forked repository for your changes. +3. Commit your changes to the new branch. +4. Push the branch to your forked repository. +5. Open a pull request from your branch in your forked repository to the main gem5 +resources repository. -Then make changes and commit. When ready, push to Gerrit with: +If you have not signed up for an account on the github +(https://github.com/), you first have to create an account. + + 1. Go to https://github.com/ + 2. Click "Sign up" in the upper right corner. + +Changes are required to have a `Change-ID`, which can be added using the +pre-commit hook. This can be installed via the following: + +``` bash +pip install pre-commit +pre-commit install ``` -git push origin HEAD:refs/for/develop -``` -The change will then be reviewed via our [Gerrit code review system]( -https://gem5-review.googlesource.com). Once fully accepted and merged into -the gem5-resources repository, please contact Bobby R. Bruce -[bbruce@ucdavis.edu](mailto:bbruce@ucdavis.edu) to have the compiled sources -uploaded to the gem5 resources bucket. +### Stable vs. Develop branch + +The rule for when to work on the stable vs. develop branch is as follows: + +* If the change applies to the current gem5 stable, then the change should be +on the stable branch of gem5-resources. + +* If the change cannot work on gem5 stable and requires updates to gem5 that +are only found on gem5 develop, then the change should be on the develop branch +of gem5-resources. + +When a new version of gem5 is released, the develop branch is merged into the +stable branch. When gem5-resources's stable and develop branches diverge, we +merge stable into develop. + +### Code Review + +Once a change has been submitted to GitHub, you may view the change at +. + +Through the GitHub pull request we strongly advise you add reviewers to your +change. GitHub will automatically notify those you assign. We recommend you add +both **Bobby R. Bruce ** (@BobbyRBruce) and +**Jason Lowe-Power ** (@powerjg) as reviewers. + +Reviewers will review the change. For non-trivial edits, it is not unusual for +a change to receive feedback from reviewers that they want incorporated before +flagging as acceptable for merging into the gem5-resources repository. +**All communications between reviewers and contributors should be done in a +polite manner. Rude and/or dismissive remarks will not be tolerated.** + +Once your change has been accepted by reviewers a maintainer will squash and +merge your pull request into the gem5-resources repository. ## Resource: RISCV Tests @@ -155,14 +193,14 @@ The ISA names are meant to match `uname -m`, e.g.: - `x86_64` - `sparc64` -You have to specify the path to the gem5 source code with `GEM5_ROOT` variable so that -m5ops can be used from there. For example for a native build: +You have to specify the path to the gem5 source code with `GEM5_ROOT` variable +so that `m5ops` can be used from there. For example for a native build: cd src/simple make -j`nproc` GEM5_ROOT=../../../ -The default of that variable is such that if you place this repository and the gem5 -repository in the same directory: +The default of that variable is such that if you place this repository and the +gem5 repository in the same directory: ./gem5/ ./gem5-resources/ @@ -205,7 +243,7 @@ A sample baremetal executable generated by this is: Only ISAs that have a corresponding `src/simple/bootloader/` file can build for baremetal, e.g. `src/simple/bootloader/aarch64.S`. -Note that a some C source files can produce both a baremetal and an userland. +Note that some C source files can produce both a baremetal and an userland. For example `m5_exit.c` produces both: out/aarch64/bare/m5_exit.out @@ -214,7 +252,7 @@ For example `m5_exit.c` produces both: However, since the regular userland toolchain is used rather than a more specialized baremetal toolchain, the C standard library is not available. Therefore, only very few C examples can build for baremetal, notably the ones -that use m5ops. +that use `m5ops`. There are also examples that can only build for baremetal, e.g. `aarch64/semihost_exit` only builds for baremetal, as semihosting is not @@ -331,11 +369,12 @@ generated by any single phony target all at once. To compile: -**Note**: Make sure you are in gem5-resources directory (resources like square are not present in the gem5 repository) -To clone the gem5-resources repository, run the following command: +**Note**: Make sure you are in gem5-resources directory (resources like square +are not present in the gem5 repository). To clone the gem5-resources repository, +run the following command: ``` -git clone https://gem5.googlesource.com/public/gem5-resources +git clone https://github.com/gem5/gem5-resources.git ``` @@ -453,10 +492,11 @@ cd src/gpu/lulesh docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu make ``` -By default, the Makefile builds for gfx801, and is placed in the `src/gpu/lulesh/bin` folder. +By default, the Makefile builds for gfx801, and is placed in the +`src/gpu/lulesh/bin` folder. -lulesh is a GPU application, which requires that gem5 is built with the GCN3_X86 architecture. -To build GCN3_X86: +lulesh is a GPU application, which requires that gem5 is built with the GCN3_X86 +architecture. To build GCN3_X86: ``` # Working directory is your gem5 directory @@ -465,9 +505,10 @@ docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu The following command shows how to run lulesh -Note: lulesh has two optional command-line arguments, to specify the stop time and number -of iterations. To set the arguments, add `--options=" ` -to the run command. The default arguments are equivalent to `--options="1.0e-2 10"` +Note: lulesh has two optional command-line arguments, to specify the stop time +and number of iterations. To set the arguments, add +`--options=" ` to the run command. The default arguments +are equivalent to `--options="1.0e-2 10"`. ``` @@ -481,20 +522,22 @@ docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu # Resource: halo-finder (HACC) -[HACC](https://asc.llnl.gov/coral-2-benchmarks) is a DoE application designed to simulate the -evolution of the universe by simulating the formation of structure in collisionless fluids -under the influence of gravity. The halo-finder code can be GPU accelerated by using -the code in RCBForceTree.cxx +[HACC](https://asc.llnl.gov/coral-2-benchmarks) is a DoE application designed +to simulate the evolution of the universe by simulating the formation of +structure in collisionless fluids under the influence of gravity. The halo-finder +code can be GPU accelerated by using the code in RCBForceTree.cxx. -`src/gpu/halo-finder/src` contains the code required to build and run ForceTreeTest from `src/halo_finder` in the main HACC codebase. -`src/gpu/halo-finder/src/dfft` contains the dfft code from `src/dfft` in the main HACC codebase. +`src/gpu/halo-finder/src` contains the code required to build and run +ForceTreeTest from `src/halo_finder` in the main HACC codebase. +`src/gpu/halo-finder/src/dfft` contains the dfft code from `src/dfft` in the +main HACC codebase. ## Compilation and Running -halo-finder requires that certain libraries that aren't installed by default in the -GCN3 docker container provided by gem5, and that the environment is configured properly -in order to build. We provide a Dockerfile that installs those libraries and -sets the environment. +halo-finder requires that certain libraries that aren't installed by default in +the GCN3 docker container provided by gem5, and that the environment is +configured properly in order to build. We provide a Dockerfile that installs +those libraries and sets the environment. In order to test the GPU code in halo-finder, we compile and run ForceTreeTest. @@ -505,9 +548,11 @@ docker build -t . docker run --rm -v ${PWD}:${PWD} -w ${PWD}/src -u $UID:$GID make hip/ForceTreeTest ``` -The binary is built for gfx801 by default and is placed at `src/gpu/halo-finder/src/hip/ForceTreeTest` +The binary is built for gfx801 by default and is placed at +`src/gpu/halo-finder/src/hip/ForceTreeTest` -ForceTreeTest is a GPU application, which requires that gem5 is built with the GCN3_X86 architecture. +ForceTreeTest is a GPU application, which requires that gem5 is built with the +GCN3_X86 architecture. To build GCN3_X86: ``` # Working directory is your gem5 directory @@ -533,9 +578,10 @@ to characterize the performance of deep neural network (DNN) primitive workloads To build DNNMark: **NOTE**: Due to DNNMark building a library, it's important to mount gem5-resources -to the same directory within the docker container when building and running, as otherwise the benchmarks -won't be able to link against the library. The example commands do this by using -`-v ${PWD}:${PWD}` in the docker run commands +to the same directory within the docker container when building and running, as +otherwise the benchmarks won't be able to link against the library. The example +commands do this by using `-v ${PWD}:${PWD}` in the docker run commands + ``` cd src/gpu/DNNMark docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu ./setup.sh HIP @@ -563,7 +609,8 @@ g++ -std=c++0x generate_rand_data.cpp -o generate_rand_data ./generate_rand_data ``` -DNNMark is a GPU application, which requires that gem5 is built with the GCN3_X86 architecture. +DNNMark is a GPU application, which requires that gem5 is built with the +GCN3_X86 architecture. To build GCN3_X86: ``` # Working directory is your gem5 directory @@ -591,11 +638,13 @@ cd src/gpu/pennant docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu make ``` -By default, the binary is built for gfx801 and is placed in `src/gpu/pennant/build` +By default, the binary is built for gfx801 and is placed in `src/gpu/pennant/build`. -pennant is a GPU application, which requires that gem5 is built with the GCN3_X86 architecture. +pennant is a GPU application, which requires that gem5 is built with the +GCN3_X86 architecture. -pennant has sample input files located at `src/gpu/pennant/test`. The following command shows how to run the sample `noh` +pennant has sample input files located at `src/gpu/pennant/test`. The following +command shows how to run the sample `noh`: ``` # Assuming gem5 and gem5-resources are in your working directory @@ -603,8 +652,11 @@ docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu ``` The output gets placed in `src/gpu/pennant/test/noh/`, and the file `noh.xy` -against the `noh.xy.std` file. Note: Only some tests have `.xy.std` files to -compare against, and there may be slight differences due to floating-point rounding +against the `noh.xy.std` file. + +Note: Only some tests have `.xy.std` files to +compare against, and there may be slight differences due to floating-point +rounding. ## Pre-built binary @@ -644,21 +696,25 @@ as part of this repository.** ## Resource: GAP Benchmark Suite (GAPBS) tests -[GAPBS](http://gap.cs.berkeley.edu/benchmark.html) is a graph processing benchmark suite and it contains 6 kernels: Breadth-First Search, PageRank, Connected Components, Betweenness Centrality, Single-Source Shortest Paths, and Triangle Counting. +[GAPBS](http://gap.cs.berkeley.edu/benchmark.html) is a graph processing +benchmark suite and it contains 6 kernels: Breadth-First Search, PageRank, +Connected Components, Betweenness Centrality, Single-Source Shortest Paths, +and Triangle Counting. ### GAPBS Origin -We obtained the GAPBS benchmark suite from http://gap.cs.berkeley.edu/benchmark.html +We obtained the GAPBS benchmark suite from + ### Building the GAPBS image -`src/gapbs` contains resources to build a GAPBS disk image which may -be used to run the benchmark on gem5 X86 simulations. +`src/gapbs` contains resources to build a GAPBS disk image which may be used to +run the benchmark on gem5 X86 simulations. `src/gapbs/README.md` contains build and usage instructions. ### GAPBS Pre-built disk image -. + ## Resource: PARSEC Benchmark Suite @@ -711,22 +767,31 @@ src/npb-tests/README.md) file. ## Resource: Linux Boot Tests -The Linux boot tests refer to the tests performed with different gem5 configurations to check its ability to boot a Linux kernel. -More information on Linux boot tests can be found [here](https://www.gem5.org/project/2020/03/09/boot-tests.html). +The Linux boot tests refer to the tests performed with different gem5 +configurations to check its ability to boot a Linux kernel. +More information on Linux boot tests can be found +[here](https://www.gem5.org/project/2020/03/09/boot-tests.html). The boot-tests resources consist of three main components: - x86-ubuntu disk image - gem5 run scripts to execute boot tests - linux kernel configuration files -The instructions to build the x86-ubuntu disk image, the Linux binaries, and how to use gem5 run scripts to run boot-tests are available in this [README](src/x86-ubuntu/README.md) file. +The instructions to build the x86-ubuntu disk image, the Linux binaries, and +how to use gem5 run scripts to run boot-tests are available in this +[README](src/x86-ubuntu/README.md) file. ## Resource: RISCV Full System -The RISCV Full System resource includes a RISCV boot loader (`berkeley bootloader (bbl)`) to boot the Linux 5.10 kernel on a RISCV system, and an image which includes the BusyBox software suite. -The resource also contains simple gem5 run/config scripts to run Linux full system simulations in which a user may telnet into. +The RISCV Full System resource includes a RISCV boot loader +(`berkeley bootloader (bbl)`) to boot the Linux 5.10 kernel on a RISCV system, +and an image which includes the BusyBox software suite. +The resource also contains simple gem5 run/config scripts to run Linux full +system simulations in which a user may telnet into. -Further information on building a riscv disk image, a riscv boot loader, and how to use gem5 scripts to run riscv Linux full system simulations, is available in the [README](src/riscv-fs/README.md) file. +Further information on building a riscv disk image, a riscv boot loader, and +how to use gem5 scripts to run riscv Linux full system simulations, is +available in the [README](src/riscv-fs/README.md) file. ### RISCV Full System pre-built disk image @@ -739,11 +804,15 @@ Further information on building a riscv disk image, a riscv boot loader, and how ## Resource: RISCV Full System with Disk Image -The RISCV Full System resource includes a RISCV bootloader (`berkeley bootloader (bbl)`) to boot the Linux 5.10 kernel on a RISCV system. -The workload and the Linux utils (provided by BusyBox) are also included in the bootloader. -The resource also contains simple gem5 run/config scripts to run Linux full system simulations in which a user may telnet into. +The RISCV Full System resource includes a RISCV bootloader +(`berkeley bootloader (bbl)`) to boot the Linux 5.10 kernel on a RISCV system. +The workload and the Linux utils (provided by BusyBox) are also included in +the bootloader. +The resource also contains simple gem5 run/config scripts to run Linux full +system simulations in which a user may telnet into. -More details on building such a RISCV bootloader and hwo does it work are available in the [README.md](src/riscv-boot-exit-nodisk/README.md) file. +More details on building such a RISCV bootloader and hwo does it work are +available in the [README.md](src/riscv-boot-exit-nodisk/README.md) file. ### RISCV Full System pre-built Linux bootloader with embedded workload @@ -802,7 +871,8 @@ Instructions on how to use the scripts can be found here [gem5 supports LupIO](https://www.gem5.org/project/2022/02/07/lupio.html). An example of using gem5 with LupIO can be found in [`configs/example/lupv`](https://gem5.googlesource.com/public/gem5/+/refs/tags/v22.0.0.0/configs/example/lupv/). -The sources to build a LupV (LupIO with RISC-V) disk image (based on busybox) and a LupV bootloader/kernel can be found in `src/lupv`. +The sources to build a LupV (LupIO with RISC-V) disk image (based on busybox) +and a LupV bootloader/kernel can be found in `src/lupv`. ### LupV Pre-built disk image