Skip to content

Commit

Permalink
resources: Update README.md file (#16)
Browse files Browse the repository at this point in the history 
This PR adds an explanation of when to use the stable vs. develop
branch. Also, it redirects mentions of Gerrit to GitHub and fixes some
minor things.
  • Loading branch information
@ivanaamit
ivanaamit authored Nov 17, 2023
1 parent 6fb5a12 commit c8f01b7
Showing 1 changed file with 138 additions and 68 deletions.
206 changes: 138 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://github.com/gem5/gem5-resources/pulls>.

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 <bbruce@ucdavis.edu>** (@BobbyRBruce) and
**Jason Lowe-Power <jason@lowepower.com>** (@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

Expand Down Expand Up @@ -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/
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
```


Expand Down Expand Up @@ -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
Expand All @@ -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="<stop_time> <num_iters>`
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="<stop_time> <num_iters>` to the run command. The default arguments
are equivalent to `--options="1.0e-2 10"`.


```
Expand All @@ -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.

Expand All @@ -505,9 +548,11 @@ docker build -t <image_name> .
docker run --rm -v ${PWD}:${PWD} -w ${PWD}/src -u $UID:$GID <image_name> 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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -591,20 +638,25 @@ 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
docker run --rm -v ${PWD}:${PWD} -w ${PWD} -u $UID:$GID gcr.io/gem5-test/gcn-gpu gem5/build/GCN3_X86/gem5.opt gem5/configs/example/apu_se.py -n3 --benchmark-root=gem5-resources/src/gpu/pennant/build -cpennant --options="gem5-resources/src/gpu/pennant/test/noh/noh.pnt"
```

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

Expand Down Expand Up @@ -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
<http://gap.cs.berkeley.edu/benchmark.html>

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

<http://dist.gem5.org/dist/v22-0/images/x86/ubuntu-18-04/gapbs.img.gz>.
<http://dist.gem5.org/dist/v22-0/images/x86/ubuntu-18-04/gapbs.img.gz>

## Resource: PARSEC Benchmark Suite

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down

0 comments on commit c8f01b7

Please sign in to comment.