Additional libraries/packages/tools needed for Fail*:

	libprotobuf-dev
	libpthread
	libpcl1-dev
	libboost-dev
	libboost-all-dev (or at least libboost-thread-dev)
	protobuf-compiler

	cmake
	cmake-curses-gui

	AspectC++ (ag++, ac++) SVN
	  (2012-01-25 or newer is known to work and can be obtained from
          http://akut.aspectc.org/)

For distribution/parallelization:
	rsync
	tmux

32-bit FailBochs on x86_64 Linux machines:
	libc6-i386
	+ all libraries listed by "ldd bochs|awk '{print $3}'" in ~/bochslibs
	(client.sh will add these to LD_LIBRARY_PATH)

===========
Build steps
===========

Build Fail*
===========
For the first time
------------------
cd failbochs/

> (optional) Cleanup previous cmake remnants
find -name CMakeCache.txt | xargs rm

> Create out of source build directory
mkdir build

> Enter out-of-source build directory
> All generated files end up there.
cd build

>> Generate cmake environment. 
cmake ..
>> Setup build configuration
> Select BUILD_BOCHS or BUILD_OVP
> Select an experiment to enable by naming its experiments/ subdirectory under
>   EXPERIMENTS_ACTIVATED
> Press 'c', 'g' to regenerate the build system
> (alternatively use "cmake-gui ." for a Qt GUI)
ccmake .

> Additionally make sure Bochs is at least configured (see below).

After changes to Fail* code
---------------------------
> Compile (optionally add -jN for parallel building)
make

> cmake will build all fail* libraries, merge them into 
> a libfail.a and put it into failbochs/fail.
> (as the current Bochs Makefile expects it there..)

Debug build
-----------
> Choose "Debug" as the build type:
ccmake .

Add new (fail*) sources to build chain
--------------------------------------
To add new files to the build, see CMakeLists.txt in
failbochs/fail, which is hopefully self explanatory. :)

Add new user-defined experiment/campaign
----------------------------------------
Look at experiments/coolchecksum/ as a template.  After creating a new
subdirectory in experiments/, activate it in the cmake configuration step (see
above).


Build Bochs
===========
For the first time
------------------
cd ../bochs
./configure --prefix=$(echo ~/localroot/usr) --enable-{a20-pin,x86-64,cpu-level=6,ne2000,acpi,pci,usb,repeat-speedups,trace-cache,fast-function-calls,host-specific-asms,disasm,all-optimizations,readline,clgd54xx,fpu,vmx=2,monitor-mwait,cdrom,sb16=linux,gdb-stub} --disable-docbook --with-all-libs
> Instead of --with-all-libs, you could use --with-nogui for "headless"
> experiments, additionally 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 "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
> following flags before running larger campaigns:
> --disable-logging --disable-assert-checks
>
> FIXME remove more redundant flags/libraries

After changes to Bochs code or Bochs-affecting aspects
------------------------------------------------------
> The make call from the make-ag++.sh is now invokable by calling (still in
> your build dir, optionally adding -jN for parallel building):
cd ../build
make bochs

> The former make all-clean is now invokable by
make bochsallclean

> For installing the bochs executable (former make install)
make bochsinstall
> (see >make help< for a target listing.)

> You may use scripts/rebuild-bochs.sh to speed up repetitive tasks regarding
> Fail/Bochs builds.  This script contains a concise documentation on itself.

Debug build
-----------
> Configure Bochs to use debugging-related compiler flags:
cd ../bochs
CXXFLAGS="-g -O0" ./configure --prefix=... ... (see above)

Profiling-based optimization build
----------------------------------
> FIXME: ag++ needs to be run with --keep_woven
> Configure Bochs to use compiler flags to enable profiling:
cd ../bochs
CXXFLAGS="-fprofile-generate" LDFLAGS="-fprofile-generate" ./configure --prefix=... ... (see above)
> Build Bochs normally, and run it.
> Configure Bochs to use compiler flags to enable optimizations based on profiling results:
CXXFLAGS="-fprofile-use -Wcoverage-mismatch" LDFLAGS="-fprofile-use" ./configure --prefix=... ... (see above)

Benchmarking
------------
> Simple instructions/second measurement:
> - configure Bochs with --enable-show-ips (see above)
> - bochsrc: print_timestamps: enabled=1
> Comparison IPS numbers are shown in the default bochsrc.
> Headless bochsrc configuration, all aspects disabled, guest system executes
> endless loop, host CPU Xeon X5470 (3.33GHz): IPS: 66124283 average = 66964789

Steps to run a boot image in FailBochs:
---------------------------------------
Follow the Bochs documentation, and start your own "bochsrc" configuration file based on the
$PREFIX/share/doc/bochs/bochsrc-sample.txt template (or
/usr/share/doc/bochs/examples/bochsrc.gz on Debian systems with Bochs
installed).
 -  Add your floppy/cdrom/hdd image in the floppya/ata0-master/ata0-slave
    sections; configure the boot: section appropriately.
 -  Comment out com1 and parport1.
 -  For "headless" experiments:
    config_interface: textconfig
    display_library: nogui
 -  For an X11 GUI:
    config_interface: textconfig
    display_library: x
 -  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 FailBochs'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 FailBochs 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
    info: action=ignore
    debug: action=ignore
    pass: action=ignore
 -  If you need a quick-and-dirty way to pass data from the guest system to the
    outside world, and you don't want to write an experiment utilizing
    GuestEvents, you can use the "port e9 hack" that prints all outb's to port
    0xe9 to the console:
    port_e9_hack: enabled=1
 -  Determinism:  (Fail)Bochs is deterministic regarding timer interrupts,
    i.e., two experiment runs after calling simulator.restore() will count the
    same number of instructions between two interrupts.  Though, you need to be
    careful when running (Fail)Bochs with a GUI enabled:  Typing "bochs -q<return>"
    on the command line may lead to the GUI window receiving a "return key
    released" event, resulting in a keyboard interrupt for the guest system.
    This can be avoided by starting Bochs with "sleep 1; bochs -q", or
    disabling the GUI (see "headless experiments" above).


Build OVP for Cortex-M3
=======================
For the first time
------------------
> Get a license from ovpworld.org
> Download:
>  - Downloads -> Main OVP Download including OVPsim Simulator
>  - Downloads -> ARM -> ARM OVP Cortex-M Profile Model
>  -                  -> Self contained ARM Cortex-M examples
>  -                  -> ARM GNU GCC and GDB tools
> Install OVP by running the self-extracting archives.
>
> Get Sourcery CodeBench Lite Edition from
> http://www.mentor.com/embedded-software/codesourcery
>  - ARM processors -> EABI release
> Install the self-extracting archive, or use the installation in
> /fs/proj/compiler/codesourcery-arm-eabi (DO, ios/kos)
>
> TODO source setup.sh, setupImperas ...
> TODO hard-coded paths

=====================================
Example experiments and code snippets
=====================================

hscsimple
---------
A simple standalone experiment (without a separate campaign).

MHTestCampaign
--------------
An example for separate campaign/experiment implementations.

1. execute Campaign (job server):
 <your_build_dir>/core/experiments/MHTestCampaign/mhcampaign

2. run the FailBochs instance, in properly defined environment:
 bochs

Dwarf example (tests/dwarf.cc)
------------------------------
Dependencies: 
	LibDwarf: (debian/ubuntu package: libdwarf-dev)
	LibElf:	  (debian/ubuntu package: libelf-dev)

Build with cmake:
cd {your-out-of-source-dir}
cmake {path to fail dir}
	-> cmake checks if libelf and libdwarf are present

make dwarf
./tests/dwarf main.elf