christoph/fail
1
Fork 0
Code Releases Activity

globally rename Fail* to FAIL*

Browse Source 
Change-Id: Ief2cb687cc69dd92c2e04f9314f0f1347e0a84ed
This commit is contained in:
Horst Schirmeier
2016-03-15 23:38:49 +01:00
parent 94a56c43c8
commit d3d2faf680
43 changed files with 120 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/coding-style.txt
View File

@ -1,4 +1,4 @@
Coding Style for Fail*
Coding Style for FAIL*
======================
You may violate/break any of the following rules if you have a good reason to

21
doc/fail-structure.txt
View File

@ -4,21 +4,20 @@ Directory structure:
The folders are nested as follow:
**********************************************************************
fail: Fail* parent directory, containing all source & configuration files (${FAIL_DIR})
fail: FAIL* parent directory, containing all source & configuration files (${FAIL_DIR})
|-cmake: CMake-related configuration files (e.g. compiler-flags, dependencies, ...)
|-doc: Fail*-Framework documentation (e.g., diagrams, howtos, ...)
|-deprecated: temporal and old (source) files, which will probably be deleted
|-scripts: python/shell scripts for Fail*-compilation and experiment distribution
|-simulators: parent directory of simulators supported by Fail* (may still be WIP)
|-doc: FAIL*-Framework documentation (e.g., diagrams, howtos, ...)
|-scripts: python/shell scripts for FAIL*-compilation and experiment distribution
|-simulators: parent directory of simulators supported by FAIL* (may still be WIP)
|-bochs: source files of the (modified) Bochs x86 simulator backend
|-gem5: source files of the gem5 simulator backend
|-debuggers: parent directory of debuggers supported by Fail* (may still be WIP)
|-debuggers: parent directory of debuggers supported by FAIL* (may still be WIP)
|-gdb: source files related to the GNU gdb debugger
|-t32: source files related to the Lauterbach T32 debugger
|-src: C/C++/AspectC++ source files related to Fail*, experiments and plugins
|-core: core source files forming the Fail* framework
|-src: C/C++/AspectC++ source files related to FAIL*, experiments and plugins
|-core: core source files forming the FAIL* framework
|-util: utility classes and miscellaneous helper functions
|-config: CMake configuration files, defining the Fail* components and variant
|-config: CMake configuration files, defining the FAIL* components and variant
|-sal: source file forming the Simulator Abstraction Layer (backend-interface)
|-bochs: backend source files of the Bochs simulator
|-gem5: backend source files of the gem5 simulator
@ -27,14 +26,14 @@ fail: Fail* parent directory, containing all source & configuration files (${FA
|-arm: ARM-specific platform source files
|-x86: x86-specific platform source files
|-perf: performance-related source files (extensions); speeds up
Fail* <-> simulator interaction (e.g., when using breakpoints)
FAIL* <-> simulator interaction (e.g., when using breakpoints)
|-cpn: campaign- (and therefore server-)related source files
|-efw: experiment-framework- (and therefore client-)related source files
|-comm: communication related source files (these files are used by cpn and efw), incl.
protobuf message definitions used for communication purposes
|-experiments: experiment code files (within a new dir) need to be located here
|-plugins: plugin code files (within a new dir) need to be located here
|-tools: Fail*-related tools, e.g., for tracing or fault-space pruning
|-tools: FAIL*-related tools, e.g., for tracing or fault-space pruning
|-[build]: recommended location of your build-tree, generated files will be placed here

36
doc/how-to-build.txt
View File

@ -1,8 +1,8 @@
=========================================================================================
Additional libraries/packages/tools needed for Fail*:
Additional libraries/packages/tools needed for FAIL*:
=========================================================================================
Required for Fail*:
Required for FAIL*:
**********************************************************************
- libmysqlclient-dev or libmariadbclient-dev
- libprotobuf-dev
@ -79,10 +79,10 @@ For distribution/parallelization:
it exists.
=========================================================================================
Compiling, building and modifying: Simulators and Fail*
Compiling, building and modifying: Simulators and FAIL*
=========================================================================================
Building Fail*:
Building FAIL*:
**********************************************************************
For the first time:
@ -101,7 +101,7 @@ For the first time:
$ ccmake .
Select "BUILD_BOCHS" or "BUILD_GEM5". Select an experiment to enable by
naming its "experiments/" subdirectory under "EXPERIMENTS_ACTIVATED".
Configure Fail* features you need for this experiment by enabling
Configure FAIL* features you need for this experiment by enabling
"CONFIG_*" options. Press 'c', 'g' to regenerate the build system.
(Alternatively use
$ cmake-gui .
@ -111,18 +111,18 @@ For the first time:
for your need.
After changes to Fail* code:
After changes to FAIL* code:
------------------------------------------------------------
Compile (in ${BUILD_DIR}, optionally "add -jN" for parallel building):
$ make
CMake will build all Fail* libraries and link them with the simulator backend
CMake will build all FAIL* libraries and link them with the simulator backend
library to a binary called "fail-client". You may use the shell script
$ ${FAIL_DIR}/scripts/rebuild-bochs.sh [-]
to speed up repetitive tasks regarding Fail/Bochs builds. This script contains
a concise documentation on itself.
Add new Fail* sources to build chain:
Add new FAIL* sources to build chain:
------------------------------------------------------------
To add new source files to the build, see CMakeLists.txt in the subdirectory of the
corresponding component in "${FAIL_DIR}/src/core/", and probably consultate the
@ -136,7 +136,7 @@ new subdirectory in "experiments/", activate it in the CMake configuration step
above).
Generating the Doxygen documentation for Fail*:
Generating the Doxygen documentation for FAIL*:
**********************************************************************
To generate the Doxygen documentation, type:
$ make doc
@ -151,7 +151,7 @@ to be compiled previously:
FailBochs: Bochs configuration features
**********************************************************************
The autotools-based bochs is configured within the Fail* build run.
The autotools-based bochs is configured within the FAIL* build run.
The configuration flags can be set within the ccmake configuration (ccmake ${FAIL_DIR}/build)
- Sufficient:
--enable-cpu-level=6;--enable-ne2000;--enable-trace-cache;--enable-gdb-stub;--disable-docbook;--with-nogui
@ -160,7 +160,7 @@ FailBochs: Bochs configuration features
The --with-nogui flag suffices for for "headless" experiments, with the
advantage of removing lots of library dependencies (thus reducing startup
overhead). --with-x11 enables only the "x" (X11), --with-wx only the "wx"
(wxWidgets) GUI. Note that "wx" does not play well together with Fail*'s
(wxWidgets) GUI. Note that "wx" does not play well together with FAIL*'s
"restore" feature (FailBochs will fall back to "x" if available, or die
trying.)
Once you know everything works as it should, you may want to add the
@ -189,7 +189,7 @@ Debug build:
Configure Bochs to use debugging-related compiler flags (expects to be in ${BUILD_DIR}):
$ cd ../simulator/bochs
$ CFLAGS="-g -O0" CXXFLAGS="-g -O0" ./configure --prefix=... ... (see above)
You might additionally want to configure the rest of Fail* into debug mode by
You might additionally want to configure the rest of FAIL* into debug mode by
setting CMAKE_BUILD_TYPE to "Debug" (ccmake, see above).
FIXME: Does this still work?
@ -220,7 +220,7 @@ Building gem5:
For the first time (incl. selecting an experiment):
------------------------------------------------------------
1. Change to the Fail* directory (expects to be in ${FAIL_DIR}) and
1. Change to the FAIL* directory (expects to be in ${FAIL_DIR}) and
create a new build directory.
$ cd ${FAIL_DIR}; mkdir build; cd build
3. Start the configuration by typing
@ -233,7 +233,7 @@ For the first time (incl. selecting an experiment):
BUILD_BOCHS and BUILD_X86.
5. Typing
$ make (or nice make -jN)
will start the build process of Fail* and gem5. This automatically
will start the build process of FAIL* and gem5. This automatically
builds the debug variant for ARM targets. (Note that this build will
automatically include the ${FAIL_DIR}/src/core/sal/gem5 as an
"EXTRAS" feature, see gem5/scons build system documentation for
@ -248,13 +248,13 @@ For the first time (incl. selecting an experiment):
NOTE: gem5 currently does not compile with the newer clang-based daily builds
of AspectC++ (ac++). You may need to use the ac++ 1.2 release instead.
After changes to Fail*/gem5 code (incl. aspect headers):
After changes to FAIL*/gem5 code (incl. aspect headers):
------------------------------------------------------------
1. Clean the current build by typing
$ make gem5-allclean
(in your build dir ${FAIL_DIR}/build). This cleans the current
Fail* and gem5 build directories. Note that "make clean" only cleans
the Fail* build directory. Furthermore, all remaining CMake remnants
FAIL* and gem5 build directories. Note that "make clean" only cleans
the FAIL* build directory. Furthermore, all remaining CMake remnants
should be deleted:
$ find -name CMakeCache.txt | xargs rm
2. Rebuild by typing
@ -290,7 +290,7 @@ Database backend setup: MySQL / MariaDB
Building LLVM from sources
=========================================================================================
If your Linux distribution does not provide a library package for LLVM 3.3 or
newer, and you need LLVM support in Fail*, you may need to build LLVM from the
newer, and you need LLVM support in FAIL*, you may need to build LLVM from the
sources and install it, e.g., locally in your home.
1. Download the source tarball of LLVM 3.4 from http://llvm.org (or use the git

26
doc/how-to-use.txt
View File

@ -1,5 +1,5 @@
=========================================================================================
Steps to run a boot image in Fail* using the Bochs simulator backend:
Steps to run a boot image in FAIL* using the Bochs simulator backend:
=========================================================================================
Follow the Bochs documentation, and start your own "bochsrc" configuration file
based on the "${PREFIX}/share/doc/bochs/bochsrc-sample.txt" template (or
@ -15,17 +15,17 @@ based on the "${PREFIX}/share/doc/bochs/bochsrc-sample.txt" template (or
- For an X11 GUI:
config_interface: textconfig
display_library: x
- For a wxWidgets GUI (does not play well with Fail*'s "restore" feature):
- For a wxWidgets GUI (does not play well with FAIL*'s "restore" feature):
config_interface: wx
display_library: wx
- Reduce the guest system's RAM to a minimum to reduce Fail*'s memory footprint
- Reduce the guest system's RAM to a minimum to reduce FAIL*'s memory footprint
and save/restore overhead, e.g.:
memory: guest=16, host=16
- If you want to redirect FailBochs's output to a file using the shell's
redirection operator '>', make sure "/dev/stdout" is not used as a target
file for logging. (The Debian "bochsrc" template unfortunately does this
in two places. It suffices to comment out these entries.)
- To make Fail* terminate if something unexpected happens in a larger
- To make FAIL* terminate if something unexpected happens in a larger
campaign, be sure it doesn't "ask" in these cases, e.g.:
panic: action=fatal
error: action=fatal
@ -63,7 +63,7 @@ An example of a DatabaseCampaign with separate experiment.
CONFIG_EVENT_MEMWRITE, CONFIG_EVENT_TRAP, CONFIG_SR_RESTORE and CONFIG_SR_SAVE
The options BUILD_BOCHS, BUILD_X86 are needed as well, but are defaults.
3. In weather-monitor/experimentInfo.hpp set "PREREQUISITES" to 1 and build
Fail*/Bochs using e.g. fail/scripts/rebuild-bochs.sh (-> how-to-build.txt).
FAIL*/Bochs using e.g. fail/scripts/rebuild-bochs.sh (-> how-to-build.txt).
Upon minor changes (i.e. not e.g. to aspects), append " -" to the call to
the script. This will rebuild only parts that changed.
4. Enter experiment_targets/weathermonitor and run:
@ -76,7 +76,7 @@ An example of a DatabaseCampaign with separate experiment.
being VARIANT.trace
6. Use "import-trace" (using correct -b & -v, -t is VARIANT.trace) to get the
trace into the database and "prune-trace" to (obviously) prune the data.
7. Change PREREQUISITES (see 5) back to "0" and rebuild Fail*/Bochs.
7. Change PREREQUISITES (see 5) back to "0" and rebuild FAIL*/Bochs.
8. Run the "weather-monitor-server" (Don't forget -v & -b!) and "fail-client -q"
from within experiment_targets/weathermonitor/.
You'll need several clients to finish the campaign.
@ -87,7 +87,7 @@ A simple standalone experiment (without a separate campaign). To compile this
experiment, the following steps are required:
1. Add "hsc-simple" to ccmake's EXPERIMENTS_ACTIVATED.
2. Enable CONFIG_EVENT_BREAKPOINTS, CONFIG_SR_RESTORE and CONFIG_SR_SAVE.
3. Build Fail* and Bochs, see "how-to-build.txt" for details.
3. Build FAIL* and Bochs, see "how-to-build.txt" for details.
4. Enter experiment_targets/hscsimple/, bunzip2 -k *.bz2
5. Start the Bochs simulator by typing
$ fail-client -q
@ -130,7 +130,7 @@ fail-client for the next 2k experiments.
The experiments can be significantly sped up by
a) parallelization (run more FailBochs clients and
b) a headless (and more optimized) Fail* configuration (see above).
b) a headless (and more optimized) FAIL* configuration (see above).
Experiment "MHTestCampaign":
@ -211,7 +211,7 @@ To compile this experiment, the following steps are required:
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.
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"
@ -222,7 +222,7 @@ To compile this experiment, the following steps are required:
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.
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
@ -231,18 +231,18 @@ To compile this experiment, the following steps are required:
=========================================================================================
Parallelization
=========================================================================================
Fail* is designed to allow parallelization of experiment execution allowing to reduce
FAIL* is designed to allow parallelization of experiment execution allowing to reduce
the time needed to execute the experiments on a (larger) set of experiment data (aka
input parameters for the experiment execution, e.g. instruction pointer, registers, bit
numbers, ...). We call such "experiment data" the parameter sets. The so called "campaign"
is responsible for managing the parameter sets (i.e., the data to be used by the experiment
flows), inquired by the clients. As a consequence, the campaign is running on the server-
side and the experiment flows are running on the (distributed) clients.
First of all, the Fail* instances (and other required files, e.g. saved state) are
First of all, the FAIL* instances (and other required files, e.g. saved state) are
distributed to the clients. In the second step the campaign(-server) is started, preparing
its parameter sets in order to be able to answer the requests from the clients. (Once
there are available parameter sets, the clients can request them.) In the final step,
the distributed Fail* clients have to be started. As soon as this setup is finished,
the distributed FAIL* clients have to be started. As soon as this setup is finished,
the clients request new parameter sets, execute their experiment code and return their
results to the server (aka campaign) in an iterative way, until all paremeter sets have
been processed successfully. If all (new) parameter sets have been distributed, the

2
doc/todo.txt
View File

@ -211,7 +211,7 @@ Erledigt:
-> benenne Events um ("Listener")
-> Erstelle neue Klassenhierarchie, die den "Informationsanteil" der "Events"
repräsentiert. Diese kapseln dann die Informationen in den Events und
werden zudem intern im Fail*-Framework verwendet (genauer: kommuniziert).
werden zudem intern im FAIL*-Framework verwendet (genauer: kommuniziert).
==========================================================================================
Theorie TODO

6
doc/wishlist.txt
View File

@ -1,8 +1,8 @@
This file documents ideas/wishes especially from a Fail* *user* perspective.
This file documents ideas/wishes especially from a FAIL* *user* perspective.
- Recurring Fail* API usage patterns in experiment/campaign implementations
- Recurring FAIL* API usage patterns in experiment/campaign implementations
(that could be implemented in a reusable way, e.g. in a library that sits
between the Fail* API and the experiment)
between the FAIL* API and the experiment)
* Fault-space pruning (FIXME elaborate)
* Preparation vs. final experiment steps -> cmake-driven, automatically
build 2 fail-client binaries? (FIXME elaborate)