docs: pass over gem5.rst

doc/simulators/gem5.rst

@@ -25,11 +25,11 @@
 gem5
 ###################################
 
-`gem5 <https://www.gem5.org/>`_ is a modular computer architecture simulator that
-can be configured to simulate a very broad range of different systems. For now,
-we maintain our own fork of gem5 `on github
+`gem5 <https://www.gem5.org/>`_ is a modular computer architecture simulator
+that can be configured to simulate a very broad range of different systems. For
+now, we maintain our own fork of gem5 `on GitHub
 <https://github.com/simbricks/gem5>`_, which contains our SimBricks adapters, a
-python configuration script for full system x86 simulations with SimBricks
+Python configuration script for full system x86 simulations with SimBricks
 adapters, and a few other extensions, such as MSI-X support. In the long term,
 we hope to upstream these changes.
 
@@ -76,17 +76,17 @@ many more message types and interacts with the re st of gem5 in multiple ways
 To make matters worse, it also does some gymnastics to implement a PCI device in
 gem5 that uses the asynchronous timing memory protocol in gem5, instead of the
 default atomic protocol semantics for PCI devices in gem5. For this we override
-the MMIO port created by the pci device super class, and implement our own
-timing port. Hopefully in the future gem5 will offer a less backward way of
+the MMIO port created by the PCI device super class, and implement our own
+timing port. Hopefully, in the future, gem5 will offer a less backward way of
 doing this but for now it works without drastically changing gem5's abstractions
 and all the other devices using them.
 
 Configuration
 =============
-gem5 is configured through python scripts. These scripts can be parametrized
+gem5 is configured through Python scripts. These scripts can be parametrized
 through the command line. Part of the configuration can be specified and adapted
 by varying the command line parameters, while many will require you to directly
-change the python configurations. We include our reference configuration for x86
+change the Python configurations. We include our reference configuration for x86
 full system simulation capable of running Linux and with various SimBricks
 adapter configurations in ``configs/simbricks/simbricks.py``. This script
 heavily includes parts of the common gem5 configuration.
@@ -97,27 +97,25 @@ heavily includes parts of the common gem5 configuration.
 Checkpointing
 =============
 
-gem5 is currently the only simulator we use that supports checkpoint and
-restore. The most common use-case for this is accelerating repeated simulations
-by checkpointing system state after boot and running future simulations from
-there. Note that SimBricks does not currently support distributed checkpoints,
-and none of our other simulators support checkpointing either. To still leverage
-this feature for accelerating boot, we carefully configure our simulations to
-checkpoint before executing anything that affects state in other simulators, in
-particular before loading device drivers. On resume, each gem5 instance will
-restore from its own checkpoint while the rest of the simulators will just start
-again from their respective initial state. As this state never changed in the
-checkpointed system either for these components, this is still a consistent
-system state.
+gem5 supports checkpoint and restore. The most common use-case for this is
+accelerating repeated simulations by checkpointing system state after boot and
+running future simulations from there. Note that SimBricks does not currently
+support distributed checkpoints. To leverage this feature for accelerating boot,
+we carefully configure our simulations to checkpoint before executing anything
+that affects state in other simulators, in particular before loading device
+drivers. On resume, each gem5 instance will restore from its own checkpoint
+while the rest of the simulators will just start again from their respective
+initial state. As this state never changed in the checkpointed system either for
+these components, this is still a consistent system state.
 
 Usage Notes
 ===========
   * gem5 only supports raw hard disk images. The SimBricks Makefile contains
-    commands to build the raw images from the qcow2 images. (**TODO** link to
-    docker documentation). 
+    commands to build the raw images from the qcow2 images. (see section 
+    :ref:`sec-convert-qcow-images-to-raw`)
 
   * gem5-kvm simulations require ``kvm`` support on the host and appropriate
-    permissions for the user to access ``/dev/kvm``. Note that unlike qemu, gem5
+    permissions for the user to access ``/dev/kvm``. Note that unlike QEMU, gem5
     will fail with an error and not silently fall back to something slower.
 
   * gem5-kvm configurations require ``/proc/sys/kernel/perf_event_paranoid`` to

doc/user/troubleshooting.rst

@@ -28,6 +28,7 @@ Troubleshooting / FAQ
 This is a collection of common troubleshooting tips and answers to frequently
 asked questions.
 
+
 .. _sec-troubleshoot-getting-help:
 
 ******************************
@@ -41,6 +42,9 @@ for quick answers and interactive discussions. If you find bugs or want to
 request a feature, feel free to open an `issue on GitHub
 <https://github.com/simbricks/simbricks/issues>`_.
 
+
+.. _sec-convert-qcow-images-to-raw:
+
 *****************************************
 Error Opening images/output-base/base.raw
 *****************************************