resources: Standardized README headers and subheaders
This commit fixes the README section headings to be more hierarchical
and dividing resource descriptions so each has clear build instructions
and pre-built binary/disk image links.
Change-Id: Icdd9044f352bbd7a5acb2a5aa0bfc7d6ecb02dc3
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5-resources/+/40041
Maintainer: Bobby R. Bruce <bbruce@ucdavis.edu>
Tested-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Reviewed-by: Hoa Nguyen <hoanguyen@ucdavis.edu>
diff --git a/README.md b/README.md
index 1354fca..eb1cf1f 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
The following sections outline our versioning policy, how to make changes
to this repository, and describe each resource and how they may be built.
-# Versioning
+## Versioning
We ensure that for each version of the [gem5 source](
https://gem5.googlesource.com/public/gem5/) there is a corresponding version of
@@ -39,7 +39,7 @@
**Note: Resource files for gem5 v19.0.0.0, our legacy release, can be found
under http://dist.gem5.org/dist/current**.
-# Making Changes
+## Making Changes
Changes to this repository are made to the develop branch via our Gerrit
code review system. Therefore, to make changes, first clone the repository
@@ -62,15 +62,18 @@
[bbruce@ucdavis.edu](mailto:bbruce@ucdavis.edu) to have the compiled sources
uploaded to the gem5 resources bucket.
-# Resource: RISCV Tests
+## Resource: RISCV Tests
-Origin: <https://github.com/riscv/riscv-tests.git>
+The RISCV Tests soruce can be found in the `src/riscv-tests` directory. More
+information about these tests can be found in `src/riscv-tests/README.md`.
-Revision: 19bfdab48c2a6da4a2c67d5779757da7b073811d
+### RISCV Tests Origins
-Local: `src/riscv-tests`
+The RISCV Tests in this repository were obtained from
+<https://github.com/riscv/riscv-tests.git>, revision
+19bfdab48c2a6da4a2c67d5779757da7b073811d.
-## Compilation
+### RISCV Tests Compilation
To compile the RISCV Tests the [RISCV GNU Compiler](
https://github.com/riscv/riscv-gnu-toolchain) must be installed.
@@ -87,7 +90,7 @@
This RISCV binaries can then be found within the `src/riscv-tests/benchmarks`
directory.
-## Pre-built binary
+### RISCV Tests Pre-built binaries
<http://dist.gem5.org/dist/v20-1/test-progs/riscv-tests/dhrystone.riscv>
@@ -113,7 +116,12 @@
<http://dist.gem5.org/dist/v20-1/test-progs/riscv-tests/vvadd.riscv>
-# Resource: simple
+## Resource: simple
+
+The simple resources are small binaries, often used to run quick tests and
+checks in gem5. Their bare-meltal
+
+### simple Compilation
Simple single source file per executable userland or baremetal examples.
@@ -227,7 +235,7 @@
Since this is a less common use case, squashfs images are not currently
generated by any single phony target all at once.
-## Pre-build binaries
+### simple Pre-built binaries
<http://dist.gem5.org/dist/v20-1/test-progs/pthreads/x86/test_pthread_create_seq>
@@ -310,9 +318,9 @@
<http://dist.gem5.org/dist/v20-1/test-progs/pthreads/sparc64/test_std_condition_variable>
-# Resource: Square
+## Resource: Square
-## Compilation
+### Square Compilation
To compile:
@@ -323,11 +331,11 @@
The compiled binary can be found in `src/square/bin`
-## Pre-built binary
+### Square Pre-built binary
<http://dist.gem5.org/dist/v20-1/test-progs/square/square.o>
-# Resource: SPEC 2006
+## Resource: SPEC 2006
The [Standard Performance Evaluation Corporation](
https://www.spec.org/benchmarks.html) (SPEC) CPU 2006 benchmarks are designed
@@ -342,7 +350,7 @@
**Please note, due to licensing issues, the SPEC 2006 iso cannot be provided
as part of this repository.**
-# Resource: SPEC 2017
+## Resource: SPEC 2017
The [Standard Performance Evaluation Corporation](
https://www.spec.org/benchmarks.html) (SPEC) CPU 2017 benchmarks are designed
@@ -359,45 +367,74 @@
**Please note, due to licensing issues, the SPEC 2017 iso cannot be provided
as part of this repository.**
-# Resource: GAP Benchmark Suite (GAPBS) tests
+## 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 Origin
+
+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/README.md` contains build and usage instructions.
-The pre-built GAPBS disk image can be found here:
+### GAPBS Pre-built disk image
+
<http://dist.gem5.org/dist/v20-1/images/x86/ubuntu-18-04/gapbs.img.gz>.
-# Resource: PARSEC Benchmark Suite
+## Resource: PARSEC Benchmark Suite
The [Princeton Application Repository for Shared-Memory Computers (PARSEC)](
https://parsec.cs.princeton.edu/) is a benchmark suite composed of
-multithreaded programs. In `src/parsec` we provide the source to build a disk
+multithreaded programs.
+
+### PARSEC Origins
+
+We used PARSEC 3.0, available from <https://parsec.cs.princeton.edu>.
+
+### Building the PARSEC image
+
+In `src/parsec` we provide the source to build a disk
image which may be used, alongside configuration files, to run the PARSEC
Benchmark Suite on gem5 architectural simulations. Please consult
`src/parsec/README.md` for build and execution information.
-A pre-built parsec benchmark image, for X86, can be found here:
+### GAPBS Pre-built disk image
+
<http://dist.gem5.org/dist/v20-1/images/x86/ubuntu-18-04/parsec.img.gz>.
-# Resource: NAS Parallel Benchmarks (NPB) Tests
+## Resource: NAS Parallel Benchmarks (NPB) Tests
-The [NAS Parallel Benchmarks] (NPB) are a small set of programs designed to
+The NAS Parallel Benchmarks (NPB) are a small set of programs designed to
help evaluate the performance of parallel supercomputers. The set consists of
five Lunux Kernels and three pseudo-applications. gem5 resources provides a
disk image, and scripts allowing for the NPB image to be run within gem5 X86
-simulations. A pre-built npb disk image can be downloaded here:
-<http://dist.gem5.org/dist/v20-1/images/x86/ubuntu-18-04/npb.img.gz>.
+simulations.
+
+### NPB Origins
+
+We use NPB 3.4.1, available from
+<https://www.nas.nasa.gov/publications/npb.html>.
+
+### NPB Building
The npb resources can be found in `src/npb`. It consists of:
- npb disk image resources
- gem5 run scripts to execute these tests
-The instructions to build the npb disk image, a Linux kernel binary, and how to use gem5 run scripts to run npb are available in the [README](src/npb-tests/README.md) file.
+The instructions to build the npb disk image, a Linux kernel binary, and how to
+use gem5 run scripts to run npb are available in the [README](
+src/npb-tests/README.md) file.
-# Resource: Linux Boot Tests
+### NPB Pre-built disk image
+
+<http://dist.gem5.org/dist/v20-1/images/x86/ubuntu-18-04/npb.img.gz>
+
+
+## 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).
@@ -409,7 +446,7 @@
The instructions to build the boot-tests disk image (`boot-exit`), the Linux binaries, and how to use gem5 run scripts to run boot-tests are available in this [README](src/boot-tests/README.md) file.
-# Resource: Insttest
+## Resource: Insttest
The Insttests test SPARC instructions.
@@ -417,7 +454,7 @@
on creating a cross compiler can be found [here](
https://preshing.com/20141119/how-to-build-a-gcc-cross-compiler).
-## Compilation
+### Insttest Compilation
To compile:
@@ -435,16 +472,27 @@
The compiled binary can be found in `src/insttest/bin`.
-## Prebuild Binary
+### Insttest Pre-built binary
<http://dist.gem5.org/dist/v20-1/test-progs/insttest/bin/sparc/linux/insttest>
-# Resource: Linux Kernel Binary
+## Resource: Linux Kernel Binary
Contains scripts to create a Linux kernel binary.
-Instructions on how to use the scripts can be found here `src/linux-kernel/README.md`.
-# Licensing
+### Linux Kernel Compilation
+
+Instructions on how to use the scripts can be found here
+`src/linux-kernel/README.md`.
+
+### Linux Kernel Pre-built binaries
+
+<http://dist.gem5.org/dist/v20-1/kernels/x86/static/vmlinux-4.4.186>
+<http://dist.gem5.org/dist/v20-1/kernels/x86/static/vmlinux-4.9.186>
+<http://dist.gem5.org/dist/v20-1/kernels/x86/static/vmlinux-4.14.134>
+<http://dist.gem5.org/dist/v20-1/kernels/x86/static/vmlinux-4.19.83>
+
+## Licensing
There is no universal license encompassing all this repository's contents.
The licences covering the individual gem5 resources are therefore highlighted
