website: Minor updates to stdlib docs
- Convert from reST formats to pure markdown
- Fix some typos/formatting errors
- Add a couple of comments for future improvement
- Standardize SE/FS
- Make it more clear that you don't have to compile the new component
into the gem5 binary
Signed-off-by: Jason Lowe-Power <jason@lowepower.com>
Change-Id: I2399ee25f3a683dd1bfd50204497edbd0383d04e
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5-website/+/55563
Reviewed-by: Bobby Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby Bruce <bbruce@ucdavis.edu>
Tested-by: Bobby Bruce <bbruce@ucdavis.edu>
diff --git a/_pages/documentation/gem5-stdlib/0-overview.md b/_pages/documentation/gem5-stdlib/0-overview.md
index 89b2ea3..823d65d 100644
--- a/_pages/documentation/gem5-stdlib/0-overview.md
+++ b/_pages/documentation/gem5-stdlib/0-overview.md
@@ -7,14 +7,13 @@
author: Bobby R. Bruce
---
-An overview of the gem5 standard library
-========================================
+## An overview of the gem5 standard library
Similar to standard libraries in programming languages, the gem5 standard library is designed to provide users of gem5 with commonly used components, features, and functionality with the goal of improving their productivity.
The gem5 stdlib was introduced in [v21.1](https://gem5.googlesource.com/public/gem5/+/refs/tags/v21.1.0.0) in an alpha-release state (then referred to as "gem5 components"), and has been fully released as of [v21.2](https://gem5.googlesource.com/public/gem5/+/refs/tags/v21.2.0.0).
For users new to the gem5 standard library, the following tutorials may be of help in understanding how the gem5 stdlib may be used to improve the creation of gem5 simulations.
-They include a tutorial on building SE and FS simulations, as well as a guide on how to extend the library and contribute.
+They include a tutorial on building syscall emulation and full-system simulations, as well as a guide on how to extend the library and contribute.
The [`configs/examples/gem5_library`](https://gem5.googlesource.com/public/gem5/+/refs/heads/stable/configs/example/gem5_library/) directory in the gem5 repository also contains example scripts which use the library.
The following subsections give a broad overview of the gem5 stdlib packages and what there intended purposes are.
@@ -22,22 +21,22 @@
**Note: The documentation/tutorial/etc. related to the standard library are for the v21.2 release.
Please ensure you have the correct version of gem5 before proceeding.**
+<!-- Could use a nice picture here showing the main modules of the stdlib and how they relate -->
-The gem5 stdlib components package and its design philosophy
-------------------------------------------------------------
+## The gem5 stdlib components package and its design philosophy
The gem5 stdlib components package is the central part of the gem5 stdlib.
With it users can built complex systems from simple components which connect together using standardized APIs.
The metaphor that guided the components package development was that of building a computer using off-the-shelf components.
-When building a computer, someone may select components, plug them into a board, and assume the interface between the board and the component have been designed in a way in which they will "just work".
+When building a computer, someone may select components, plug them into a board, and assume the interface between the board and the component have been designed in a way in which they will "just work."
For example, someone can remove a processor from a board and add a different one, compatible with the same socket, without needing to change everything else in their setup.
-While there are always limitations to this design philosophy, the components package has a highly modular design with components of the same type being interchangeable with one another as much as is possible.
+While there are always limitations to this design philosophy, the components package has a highly modular and extensible design with components of the same type being interchangeable with one another as much as is possible.
At the core of the components package is the idea of a _board_.
This plays a similar role to the motherboard in a real-world system.
While it may contain embedded caches, controllers, and other complex components, its main purpose is to expose standardized interfaces for other hardware to be added and handle communication between them.
-For example, a memory stick and a processor may be added to a board with the board responsible for communication without the designer of the memory or the processor having to consider this assuming they conform to known APIs.
+For example, a memory device and a processor may be added to a board with the board responsible for communication without the designer of the memory or the processor having to consider this assuming they conform to known APIs.
Typically, a gem5 components package _board_ requires declaration of these three components:
@@ -45,6 +44,8 @@
2. The _memory_ system: The memory system, for example, a DDR3_1600.
3. The _cache hierarchies_: This component defines any and all components between the processor and main memory, most notably the cache setup. In the simplest of setups this will connect memory directly to the processor.
+The other devices required for full-system simulation, which rarely change between simulations, are handled by the board.
+
A typical usage of the components may therefore look like:
```python
@@ -73,8 +74,7 @@
The following tutorials go into greater detail on how to use the components package to create gem5 simulations.
-The gem5 resources package
---------------------------
+## The gem5 resources package
The gem5 stdlib's resource package is used to obtain and incorporate resources.
A resource, in the context of gem5, is something used in a simulation, or by a simulation, but not directly used to construct a system to be simulated.
@@ -103,8 +103,7 @@
While this is a machine-readable JSON file, users may use it to lookup the resources available.
**We hope in the near future to have a website which renders this in a more human-readable manner**.
-The Simulate package
---------------------
+## The Simulate package
**WARNING: The Simulate package is still in a BETA state. APIs in this package may change in future releases of gem5**.
diff --git a/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md b/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md
index 4fac2d3..4fd80f2 100644
--- a/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md
+++ b/_pages/documentation/gem5-stdlib/1-tutorial-hello-world.md
@@ -7,17 +7,16 @@
author: Bobby R. Bruce
---
-Building a "Hello World" example with the gem5 standard library
-===============================================================
+## Building a "Hello World" example with the gem5 standard library
In this tutorial we will cover how to create a very basic simulation using gem5 components.
This simulation will setup a system consisting of a single-core processor, running in Atomic mode, connected directly to main memory with no caches, I/O, or other components.
-The system will run an X86 binary in Syscall Execution (SE) mode.
+The system will run an X86 binary in syscall emulation (SE) mode.
The binary will be obtained from gem5-resources and which will print a "Hello World!" string to stdout upon execution.
To start we must compile gem5 to simulate the X86 ISA:
-```
+```sh
# In the root of the gem5 directory
scons build/X86/gem5.opt -j <number of threads>
```
@@ -62,9 +61,9 @@
```
There exists many memory components to choose from within `gem5.components.memory`.
-Here we are using a single-channel DDR3 1600, and setting its size to 1GiB.
+Here we are using a single-channel DDR3 1600, and setting its size to 1 GiB.
It should be noted that setting the size here is technically optional.
-If not set, the `SingleChannelDDR3_1600` will default to 8GiB.
+If not set, the `SingleChannelDDR3_1600` will default to 8 GiB.
Then we consider the _processor_:
@@ -72,7 +71,7 @@
processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1)
```
-A processor in `gem5.components` is an object which contains a number of gem5 CPU cores, of a particular or varying type (`ATOMIC`, `TIMING`, `KVM`, or `O3`).
+A processor in `gem5.components` is an object which contains a number of gem5 CPU cores, of a particular or varying type (`ATOMIC`, `TIMING`, `KVM`, `O3`, etc.).
The `SimpleProcessor` used in this example is a processor where all the CPU Cores are of an identical type.
It requires two arguments: the `cpu_type`, which we set to `ATOMIC`, and `num_cores`, the number of cores, which we set to one.
@@ -89,7 +88,7 @@
While the constructor of each board may vary, they will typically require the user to specify the _processor_, _memory system_, and _cache hierarchy_, as well as the clock frequency to use.
In this example we use the `SimpleBoard`.
-The `SimpleBoard` is a very basic system with no I/O which only supports SE mode and can only work with classic cache hierarchy setups.
+The `SimpleBoard` is a very basic system with no I/O which only supports SE-mode and can only work with "classic" cache hierarchies.
At this point in the script we have specified everything we require to simulate our system.
Of course, in order to run a meaningful simulation, we must specify a workload for this system to run.
@@ -108,6 +107,8 @@
After specifying the resource we set the workload via the board's `set_se_binary_workload` function.
As the name suggests `set_se_binary_workload` is a function used to set a binary to be executed in Syscall Execution mode.
+<!-- It would be nice to describe here how to find out what resources are available -->
+
This is all that is required to setup your simulation.
From this you simply need to construct and run the `Simulator`:
@@ -215,7 +216,7 @@
* A system can be built with the gem5 components package using _processor_, _cache hierarchy_, _memory system_, and _board_ components.
* Generally speaking, components of the same type are interchangeable as much as is possible. E.g., different _cache hierarchy_ components may be swapped in and out of a design without reconfiguration needed in other components.
-* _board_s contain functions to set workloads.
+* _boards_ contain functions to set workloads.
* The resources package may be used to obtain prebuilt resources from gem5-resources.
These are typically workloads that may be run via set workload functions.
* The simulate package can be used to run a board within a gem5 simulation.
diff --git a/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md b/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md
index 0d73292..80a0ded 100644
--- a/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md
+++ b/_pages/documentation/gem5-stdlib/2-tutorial-x86-fs.md
@@ -7,15 +7,15 @@
author: Bobby R. Bruce
---
-Building an x86 full-system simulation with the gem5 standard library
-=====================================================================
+## Building an x86 full-system simulation with the gem5 standard library
One of the key ideas behind the gem5 standard library is to allow users to simulate, big, complex systems, with minimal effort.
-This is done by making sensible assumptions about the nature of the system to simulate and connecting components in a manner which "makes sense".
+This is done by making sensible assumptions about the nature of the system to simulate and connecting components in a manner which "makes sense."
While this takes away some flexibility, it massively simplifies simulating typical hardware setups in gem5.
+The overarching philosophy is to make the _common case_ simple.
-In this tutorial we will build an X86 simulation, capable of running a full-system simulation, booting an Ubuntu operating system, and running a script.
-This system will utilize gem5's ability to switch cores, allowing booting of the operating system in KVM mode and switching to a detailed CPU model to run the script, and utilize a MESI Two Level Ruby cache hierarchy in a dual-core setup.
+In this tutorial we will build an X86 simulation, capable of running a full-system simulation, booting an Ubuntu operating system, and running a benchmark.
+This system will utilize gem5's ability to switch cores, allowing booting of the operating system in KVM fast-forward mode and switching to a detailed CPU model to run the benchmark, and use a MESI Two Level Ruby cache hierarchy in a dual-core setup.
Without using the gem5 library this would take several hundred lines of Python, forcing the user to specify details such as every IO component and exactly how the cache hierarchy is setup.
Here, we will demonstrate how simple this task can be with using the gem5 standard library.
@@ -49,7 +49,7 @@
A good start is to use the `requires` function to specify what kind of gem5 binary/setup is required to run the script:
-```
+```python
requires(
isa_required=ISA.X86,
coherence_protocol_required=CoherenceProtocol.MESI_TWO_LEVEL,
@@ -60,6 +60,9 @@
Here we state that we need gem5 compiled to run the X86 ISA and support the MESI Two Level protocol.
We also require the host system to have KVM.
**NOTE: Please ensure your host system supports KVM. If your system does not please remove the `kvm_required` check here**.
+KVM will only work if the host platform and the simulated ISA are the same (e.g., X86 host and X86 simulation).
+
+<!-- Can we provide a link to how to know if you have kvm? Related:https://gem5.atlassian.net/browse/GEM5-684-->
This `requires` call is not required but provides a good safety net to those running the script.
Errors that occur due to incompatible gem5 binaries may not make much sense otherwise.
@@ -69,20 +72,20 @@
```python
cache_hierarchy = MESITwoLevelCacheHierarchy(
- l1d_size="16kB",
+ l1d_size="32KiB",
l1d_assoc=8,
- l1i_size="16kB",
+ l1i_size="32KiB",
l1i_assoc=8,
- l2_size="256kB",
+ l2_size="256KiB",
l2_assoc=16,
num_l2_banks=1,
)
```
Here we setup a MESI Two Level (ruby) cache hierarchy.
-Via the constructor we set the L1 data cache and L1 instruction cache to 16kB, and the L2 cache to 256kB.
+Via the constructor we set the L1 data cache and L1 instruction cache to 32 KiB, and the L2 cache to 256 KiB.
-Next we setup the `memory system`:
+Next we setup the _memory system_:
```python
memory = SingleChannelDDR3_1600(size="2GiB")
@@ -155,7 +158,8 @@
The `m5 readfile` will read a file and execute it.
The contents of this file are specified via the `readfile_contents` parameter.
Therefore the value of` readfile_contents` will be executed on system startup.
-**(Note: `readfile_contents` is an optional argument. If it is not specified in `set_kernel_disk_workload` the simulation will exit after boot)**.
+**Note: `readfile_contents` is an optional argument. If it is not specified in `set_kernel_disk_workload` the simulation will exit after boot**.
+This behavior is specific to the `x86-ubuntu-18.04-img` disk image and is not true for all disk images.
In this tutorial the script first runs `m5 exit`.
This temporarily exits the simulation allowing us to switch the CPUs from `KVM` to `TIMING`.
@@ -220,9 +224,9 @@
# Here we setup a MESI Two Level Cache Hierarchy.
cache_hierarchy = MESITwoLevelCacheHierarchy(
- l1d_size="16kB",
+ l1d_size="32KiB",
l1d_assoc=8,
- l1i_size="16kB",
+ l1i_size="32KiB",
l1i_assoc=8,
l2_size="256kB",
l2_assoc=16,
diff --git a/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md b/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md
index 772b555..2dda145 100644
--- a/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md
+++ b/_pages/documentation/gem5-stdlib/3-tutorial-developing-own-components.md
@@ -7,10 +7,9 @@
author: Bobby R. Bruce
---
-Developing your own gem5 standard library components
-===========================================
+## Developing your own gem5 standard library components
-
+
The above diagram shows the basic design of the gem5 library components.
There are four important abstract classes: `AbstractBoard`, `AbstractProcessor`, `AbstractMemorySystem`, and `AbstractCacheHierarchy`.
@@ -28,7 +27,6 @@
To begin, we should create a new Python class which inherits from the `AbstractClassicCacheHierarchy`.
In this example we will call this `UniqueCacheHierarchy`, contained within a file `unique_cache_hierarchy.py`:
-
```python
from gem5.components.cachehierarchies.classic.abstract_classic_cache_hierarchy import AbstractClassicCacheHierarchy
from gem5.components.boards.abstract_board import AbstractBoard
@@ -184,9 +182,14 @@
This completes the code we'd need to create our own cache hierarchy.
To use this code, a user can import it as they would any other Python module.
+As long as this code is in gem5's python search path, you can import it.
+You can also add `import sys; sys.path.append(<path to new component>)` at the beginning of your gem5 runscript to add the path of this new component to the python search path.
-Compiling your component into the gem5 standard library
--------------------------------------------------------
+## Contributing your component to the gem5 stdlib
+
+Before contributing your component, you will need to move it into the `src/` directory so that it is compiled into the gem5 binary.
+
+### Compiling your component into the gem5 standard library
The gem5 standard library code resides in `src/python/gem5`.
The basic directory structure is as follows:
@@ -232,8 +235,7 @@
```
-Contributing your component to the gem5 stdlib
-----------------------------------------------
+### gem5 Code contribution and review
If you believe your addition to the gem5 stdlib would be beneficial to the gem5 community, you may submit it as a patch.
Please follow our [Contributing Guidelines](/contributing) if you have not contributed to gem5 before or need a reminder on our procedures.
@@ -249,7 +251,6 @@
For example, it will not reduce string lengths.
You may have to manually reduce the length of some lines.
-
Code will be reviewed via our [Gerrit code review system](https://gem5-review.googlesource.com/) like all other contributions.
We would, however, emphasize that we will not accept patches to the library for simply being functional and tested;
we require some persuasion that the contribution improves the library and benefits the community.
