doc: edit/add gem5-specific documentation

Change-Id: I3798780022123569f10448c7460e94be3d2530f6

doc/how-to-use.txt

@@ -197,6 +197,37 @@ instantiating the generic DatabaseCampaign.  The general workflow is as follows:
    created result table with columns corresponding to the fields in the Result
    group of the protobuf message.
 
+Experiment "weather-monitor" with gem5:
+**********************************************************************
+This experiment simulates a simple weather-station.
+To compile this experiment, the following steps are required:
+
+ 1.  Adapt fail/src/experiments/weather-monitor/experimentInfo.hpp
+ 2.  Enter ${FAIL_DIR}/build/
+ 3.  Add "weather-monitor" to ccmake's EXPERIMENTS_ACTIVATED.
+ 4.  Add "tracing" to ccmake's PLUGINS_ACTIVATED.
+ 5.  Enable BUILD_ARM, BUILD_GEM5, BUILD_IMPORT_TRACE, BUILD_PRUNE_TRACE,
+     CONFIG_EVENT_BREAKPOINTS, CONFIG_EVENT_BREAKPOINTS_RANGE, CONFIG_EVENT_GUESTSYS,
+     CONFIG_EVENT_MEMREAD, CONFIG_EVENT_MEMWRITE, CONFIG_EVENT_TRAP, CONFIG_SR_RESTORE
+     and CONFIG_SR_SAVE.
+ 6.  Enable STEP1 in fail/src/experiments/weather-monitor/experiment.cc
+ 7.  Build Fail* and gem5, see "how-to-build.txt" for details.
+ 8.  Start the gem5-fail-client by typing
+     "../scripts/run-gem5.sh ../../experiment_targets/weathermonitor_arm/weather.elf
+     weathermonitor_arm/weather.elf"
+ 9.  Import the trace with
+     "import-trace -t trace.tc.weather -d YOUR_DB -v baseline -b weather -i
+     BasicImporter -e ../../experiment_targets/weathermonitor_arm/weather.elf
+     --faultspace-rightmargin W"
+ 10. Prune the trace with
+     "prune-trace -d YOUR_DB -v baseline -b weather"
+ 11.  Enable STEP3 in fail/src/experiments/weather-monitor/experiment.cc
+ 12. Build Fail* and gem5, see "how-to-build.txt" for details.
+ 13. Start the campaign-server
+     "bin/weather-monitor-server -v baseline -b weather"
+ 14. Start the gem5-fail-client by typing
+     "../scripts/run-gem5.sh ../../experiment_targets/weathermonitor_arm/weather.elf
+
 =========================================================================================
 Parallelization
 =========================================================================================
@@ -234,6 +265,7 @@ themselves, they contain some documentation):
  - multiple-clients.sh: Is run on an experiment host by runcampaign.sh,
                         starts several instances of client.sh in a tmux session.
  - client.sh: (Repeatedly) Runs a single fail-client instance.
+ - run-gem5.sh: Runs a single gem5-fail-client instance.
 
 
 Some useful things to note:
@@ -268,6 +300,11 @@ Steps to run an experiment with gem5:
  4. Run gem5 in  $FAIL_DIR/simulators/gem5/  with:
       $ M5_PATH=$SYSTEM build/ARM/gem5.debug configs/example/fs.py --bare-metal --kernel kernelname
 
+Step 4 has been encapsulated in a shell script:
+ 1. Enter ${FAIL_DIR}/build/
+ 2. Run the run-gem5.sh script with the path of the elf-binary
+    ../scripts/run-gem5.sh path-to-elf-binary
+
 =========================================================================================
 Steps to run an experiment with the pandaboard/openocd backend:
 =========================================================================================