README, docs: clearly document how to avoid gem5 perf attach panic

README.md

@@ -58,21 +58,26 @@ dependencies. This command will run an interactive shell in a new ephemeral
 container (deleted after the shell exits):
 
 ```Shell
-docker run --rm -it simbricks/simbricks /bin/bash
+docker run --rm -it --device /dev/kvm --privileged simbricks/simbricks /bin/bash
 ```
 
 If you are running on a Linux system with KVM support enabled, we recommend
 passing `/dev/kvm` into the container to drastically speed up some of the
-simulators:
+simulators. It is even required for some of them, e.g. gem5.
+
+Further, if you plan to use gem5, the container needs to be started with
+`--privileged` since it requires access to the `perf_event_open` syscall. In
+addition, `/proc/sys/kernel/perf_event_paranoid` has to to be set to 1 or lower
+on your host system. You can do so with
 
 ```Shell
-docker run --rm -it --device /dev/kvm simbricks/simbricks /bin/bash
+sudo sysctl -w kernel.perf_event_paranoid=1
 ```
 
-Finally, some of our host simulators, e.g., gem5 and Simics, require raw
+Finally, some of our host simulators, e.g. gem5 and Simics, require raw
 disk images. Since Docker doesn't handle large, sparse files well leading to
 large Docker image sizes, we only include disk images in the qcow format. To
-convert these to raw, run the following:
+convert these to raw, run the following inside the container:
 
 ```Shell
 make convert-images-raw

doc/simulators/gem5.rst

@@ -119,4 +119,5 @@ Usage Notes
     will fail with an error and not silently fall back to something slower.
 
   * gem5-kvm configurations require ``/proc/sys/kernel/perf_event_paranoid`` to
-    be set to ``-1`` on the host system.
+    be set to ``1`` or lower on the host system. :ref:`sec-gem5-perf` describes
+    how to do so.

doc/user/troubleshooting.rst

@@ -68,6 +68,32 @@ qcow images by running the following (again, requires QEMU to be built first):
 
   $ make build-images-min
 
+.. _sec-gem5-perf:
+
+*********************************
+gem5 Panic PerfKvmCounter::attach
+*********************************
+
+gem5 needs access to the syscall ``perf_event_open``. To allow access,
+``/proc/sys/kernel/perf_event_paranoid`` has to be set to 1 or lower on the host
+system. You can check the current value with
+
+.. code-block:: bash
+
+  $ cat /proc/sys/kernel/perf_event_paranoid
+
+To change the setting, use this command:
+
+.. code-block:: bash
+
+  $ sudo sysctl -w kernel.perf_event_paranoid=1
+
+If you are using SimBricks from within a Docker container, you also need to
+start the container with the parameter ``--privileged`` for the
+``perf_event_open`` syscall to be accessible. Our VS Code dev container is
+configured to already do so, just start it as usual from within VS Code and you
+are good to go. Otherwise, add the parameter to your ``docker run`` command.
+
 ************************************
 Is My Simulation Stuck or Just Slow?
 ************************************