Separated how-to-build -> how-to-build + how-to-use, added details on experiment parallelization, updated fail-structure docs.
git-svn-id: https://www4.informatik.uni-erlangen.de/i4svn/danceos/trunk/devel/fail@1348 8c4709b5-6ec9-48aa-a5cd-a96041d1645a
This commit is contained in:
adrian
186
doc/how-to-build.txt
Normal file
186
doc/how-to-build.txt
Normal file
@ -0,0 +1,186 @@
|
||||
=========================================================================================
|
||||
Additional libraries/packages/tools needed for Fail*:
|
||||
=========================================================================================
|
||||
|
||||
Required anyway:
|
||||
**********************************************************************
|
||||
- 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++): AspectC++ 1.1 or newer is known to work and can be
|
||||
obtained from http://www.aspectc.org; nightlies can be downloaded 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)
|
||||
|
||||
=========================================================================================
|
||||
Compiling, building and modifying: Simulators and Fail*
|
||||
=========================================================================================
|
||||
|
||||
Building Fail*:
|
||||
**********************************************************************
|
||||
|
||||
For the first time:
|
||||
------------------------------------------------------------
|
||||
1. Enter the "fail/" directory (${FAIL_DIR}, see also "fail-structure.txt"):
|
||||
$ cd fail/
|
||||
2. (Optional) Cleanup previous CMake remnants:
|
||||
$ find -name CMakeCache.txt | xargs rm
|
||||
3. Create out of source build directory (${BUILD_DIR}, see also "fail-structure.txt"):
|
||||
$ mkdir build
|
||||
4. Enter out-of-source build directory. All generated files end up there.
|
||||
$ cd build
|
||||
5. Generate CMake environment.
|
||||
$ cmake ..
|
||||
6. Setup build configuration by opening the CMake configuration tool
|
||||
$ ccmake .
|
||||
Select "BUILD_BOCHS" or "BUILD_OVP". Select an experiment to enable by naming its
|
||||
"experiments/" subdirectory under "EXPERIMENTS_ACTIVATED". Configure Fail* features
|
||||
you need for this experiment by enabling "CONFIG_*" options. Press 'c', 'g' to
|
||||
regenerate the build system. (Alternatively use
|
||||
$ cmake-gui .
|
||||
for a Qt GUI.) To enable a Debug build, choose "Debug" as the build type.
|
||||
7. Additionally make sure Bochs is at least configured (see below).
|
||||
|
||||
|
||||
After changes to Fail* code:
|
||||
------------------------------------------------------------
|
||||
Prerequisite, if you're building with Bochs: configure Bochs (see below).
|
||||
Compile (in ${BUILD_DIR}, optionally "add -jN" for parallel building):
|
||||
$ make
|
||||
CMake will build all Fail* libraries, merge them into a libfail.a and put it into
|
||||
"${FAIL_DIR}/src". (As the current Bochs Makefile expects it there.) The static
|
||||
library contains all core components and activated experiments/plugings.
|
||||
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:
|
||||
------------------------------------------------------------
|
||||
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
|
||||
CMake docs: http://cmake.org/cmake/help/documentation.html
|
||||
|
||||
|
||||
Add new experiment/plugin/campaign:
|
||||
------------------------------------------------------------
|
||||
Look at "${FAIL_DIR}/src/experiments/coolchecksum/" as a template. After creating a
|
||||
new subdirectory in "experiments/", activate it in the CMake configuration step (see
|
||||
above).
|
||||
|
||||
|
||||
Generating the Doxygen documentation for Fail*:
|
||||
**********************************************************************
|
||||
To generate the Doxygen documentation, type:
|
||||
$ make doc
|
||||
The documentation files (HTML and LaTeX) are located in "${BUILD_DIR}/src/core/doc/".
|
||||
To open the HTML documentation, type:
|
||||
$ firefox src/core/doc/html/index.html
|
||||
(You may want to replace "firefox" with your favourite browser.) The LaTeX docs need
|
||||
to be compiled previously:
|
||||
$ cd src/core/doc/latex; make
|
||||
|
||||
|
||||
Building Bochs:
|
||||
**********************************************************************
|
||||
|
||||
For the first time:
|
||||
------------------------------------------------------------
|
||||
1. Change to the Bochs simulator directory (expects to be in ${FAIL_DIR}):
|
||||
$ cd simulators/bochs
|
||||
2. Configure the Bochs simulator (auto-tools).
|
||||
- Sufficient:
|
||||
$ ./configure --prefix=$(echo ~/localroot/usr) --enable-{cpu-level=6,ne2000,trace-cache,gdb-stub} --disable-docbook
|
||||
- More optimised:
|
||||
$ ./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:
|
||||
------------------------------------------------------------
|
||||
- Compiling: The make call from the make-ag++.sh is now invokable by calling
|
||||
(still in ${BUILD_DIR}, optionally adding -jN for parallel building):
|
||||
$ cd ../build %% FIXME: involviert make bochs (im build-Ver.) wirklich make-ag++.sh?
|
||||
$ make bochs
|
||||
(Of course, this requires a configured Bochs/Fail*.)
|
||||
- Cleaning up: The former make all-clean is now invokable by
|
||||
$ make bochsallclean
|
||||
- Installing: For installing the bochs executable (former "make install")
|
||||
$ make bochsinstall
|
||||
(See "make help" for a target listing.)
|
||||
- Note: 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 (expects to be in ${BUILD_DIR}):
|
||||
$ cd ../simulator/bochs
|
||||
$ CFLAGS="-g -O0" 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 ../simulator/bochs
|
||||
$ CFLAGS="-fprofile-generate" 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:
|
||||
$ CFLAGS="-fprofile-use -Wcoverage-mismatch" 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)
|
||||
- Modify the 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
|
||||
|
||||
Building OVP for ARM Cortex-M3:
|
||||
**********************************************************************
|
||||
|
||||
For the first time:
|
||||
------------------------------------------------------------
|
||||
1. Get a license from http://www.ovpworld.org/
|
||||
2. Download the following files:
|
||||
- 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
|
||||
3. Install OVP by running the self-extracting archives.
|
||||
4. Get Sourcery CodeBench Lite Edition from
|
||||
http://www.mentor.com/embedded-software/codesourcery
|
||||
(ARM processors -> EABI release)
|
||||
5. 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: Fix Hard-coded paths
|
||||
Reference in New Issue
Block a user