README

   1 * FRSH/FORB FRAMEWORK
   2
   3   FRSH/FORB is a contract-based resource reservation framework for
   4   distributed real-time applications. In general, it provides timing
   5   isolation between applications, i.e. multiple applications can use
   6   the same resources such as CPU, networks, etc., without influencing
   7   timing of the other applications. The main principle is that
   8   application developers use FRSH API to specify their resource
   9   requirements needed to achieve desired timeliness and the framework
  10   uses schedulability analysis to check these requirements. If the
  11   check is successful an application is granted a "virtual resource"
  12   which allow the application to use the requested resource while
  13   enforcing the application not to use more than requested.
  14
  15   The development of the framework begun in FRESCOR project
  16   (http://frescor.org) and now it is developed as a stand-alone
  17   project on SourceForge (http://frsh-forb.sf.net).
  18
  19 * BUILDING FRSH/FORB FRAMEWORK
  20
  21 1) Initialize and download additional submodules:
  22
  23    git submodule init
  24    git submodule update
  25
  26 2) Install prerequisites. On Debian/Ubuntu:
  27
  28      apt-get install libidl-dev libcpufreq-dev libacpi-dev \
  29                      libcgroup-dev libncurses5-dev
  30
  31    To build camera demo, you need to:
  32
  33      apt-get install freeglut3-dev
  34
  35 3) Go to build directory and configure the build:
  36
  37    cd build/aquosa
  38    make default-config
  39
  40    If you are not satisfied with configuration found in
  41    config.omk-default or config.target, you can override it in
  42    config.omk.
  43
  44    To be able to use CPU reservations AQuoSA
  45    (http://aquosa.sourceforge.net) has to be installed. If you cannot
  46    use AQuoSA, the framework can also be compiled without CPU support
  47    (echo CONFIG_AQUOSA=n >> config.omk) or can use cgroups (echo
  48    CONFIG_CPUCG=y >> config.omk). Note, that cgroups support is not
  49    well tested, but we plan to work on it.
  50
  51 4) Compile it:
  52
  53    make
  54
  55 5) Test it:
  56
  57    ./_compiled/bin/fcb &
  58    ./_compiled/bin/frm_dummy &
  59    ./_compiled/bin/frm_gui &
  60    ./_compiled/bin-tests/dummy_renegotiation
  61
  62 * DIRECTORY STRUCTURE
  63
  64   * build/* - configuration for different build targets
  65
  66   * build/aquosa - default build for linux
  67
  68   * build/marte - build for MarteOS. Not completely supported now.
  69
  70   * src - all sources
  71
  72   * src/forb - CORBA-like middle for interprocess and inter-node
  73     communication.
  74
  75   * src/frsh - The core of resource reservation framework.
  76
  77   * src/frsh-include - FRSH API headers from FRESCOR project. Our FRSH
  78     framework implements this API.
  79
  80   * src/fosa - Operating system adaptation layer
  81
  82   * src/ulut - library providing generic data types and algorithms
  83     (AVL trees etc.).
  84
  85   * src/fna - Network adaptation layer = unified API for plugging in
  86     different network protocols.
  87
  88   * src/fwp - Communication protocol and resource management for WiFi
  89     (also works with Ethernet).
  90
  91 * OLD HOWTO - may be out of date
  92
  93     Linux + AQuoSA
  94
  95      * Install AQuoSA (http://aquosa.sourceforge.net)
  96      * $HOME/frescor/src/omk-build/aquosa
  97      * Adjust symlinks to FRESCOR modules (fosa, frsh, utils, ...) or use ./create-links script
  98      * Create config.omk containing (or use a shell variable in your .bashrc)
  99
 100   AQUOSA_ROOT=/path/to/aquosa/install/path
 101
 102      * Actually, my preferred way of working is adding the following
 103        variables in .bashrc:
 104
 105   # AQuoSA environment
 106
 107   export AQUOSA_ROOT=/usr/local/aquosa
 108   export PATH="$PATH:$AQUOSA_ROOT/bin"
 109   export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$AQUOSA_ROOT/lib"
 110
 111   # FRESCOR environment
 112
 113   export PLATFORM=AQuoSA
 114   export FOSA_ROOT=$HOME/path/to/fosa
 115   export FRSH_ROOT=$HOME/path/to/frsh
 116   export UTILS_ROOT=$HOME/path/to/utils
 117   LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$FOSA_ROOT/lib:$FRSH_ROOT/lib:$UTILS_ROOT/lib"
 118
 119   # OMK environment
 120
 121   # Use `omk' for OMK-enabled sources
 122   alias omk="make -f $HOME/path/to/Makefile.rules"
 123   # link headers instead of copying them
 124   export LN_HEADERS=y
 125
 126      * Create default-configuration by running
 127
 128   make default-config
 129
 130      * Run
 131
 132   make
 133
 134 ** Further remarks
 135
 136 - If we are not interested in compilation of some component (because
 137   it is currently in uncompilable state), we can simply delete the
 138   link to it.
 139
 140 - It might be possible that you will need to change some configuration
 141   value from config.target. You can override any variable declared
 142   there in config.omk. For example, if you have MARTE installed in a
 143   different directory that the one specified in config.target, you can
 144   put the following in config.omk:
 145
 146   MARTE_PATH=/path/to/marte/
 147
 148 - To compile the FRESCOR for Marte, it is not necessary to set PATH
 149   variable to GNAT compiler since OMK uses full paths to call the
 150   compiler.
 151
 152 - Since there are many things in uncompilable state, you may want to
 153   use `make -k' to ignore compilation errors.
 154
 155 - Since we don't want to modify the original Makefiles, in order to
 156   compile only a part of the tree, you cannot simply run make in the
 157   desired directory, but you have to specify -f flag with the path to
 158   Makefile.rules. For this reason, we recommend defining the following
 159   alias:
 160
 161   alias omk="make -f $HOME/frescor/src/omk-build/marte/Makefile.rules"
 162
 163 ** Why is OMK good for FRESCOR
 164
 165      * It is not easy to test FRESCOR simultaneously on multiple platforms.
 166        With OMK, you can have the same sources compiled for multiple
 167        platforms/targets at the same time because it uses out of source
 168        directory compilation.
 169      * Dependencies are not handled correctly in current Makefiles. For
 170        example headers (in most tests) and some libraries (fosa_xxx) are not
 171        specified as dependencies. OMK handles dependencies automatically, so
 172        developers don't have to care about them.
 173      * With OMK it is easy to combine multiple components/libraries (from
 174        different developers) together and compile them with the same
 175        configuration (e.g. PLATFORM variable). The structure of leaf
 176        makefiles (Makefile for every component) is very simple and *well
 177        specified*. Because of this it is easy to combine components from
 178        multiple developers.
 179      * Directory structure for compilation with current makefiles must be
 180        fixed. In makefiles there is many "..". This prevents the use of
 181        symbolic links to create desired directory structure because make
 182        always treats ".." physically (i.e. it don't respect the directory
 183        structure created by symbolic links). In OMK, the position of
 184        directories in the source tree is not important. This is another
 185        reason, why integration is simpler with OMK.
 186      * OMK already supports compilation for user-space programs/libraries,
 187        Linux and RTLinux modules, RTEMS and several other platforms. Now we
 188        have also added support for Marte. It works under MinGW and Cygwin, so
 189        it can be used to compile for OSE. In Pisa, they already use OMK for
 190        Aquosa.
 191
 192 ** FAQ
 193
 194 - How do I debug my Makefile.omk set-up ?
 195
 196    Just activate verbose compilation (V=1 or V=2):
 197
 198   make -f /path/to/Makefile.rules binary-pass V=1
 199
 200 - How do I get back syntax highlighting in Emacs while editing .omk files ?
 201
 202    Just add these lines to your $(HOME)/.emacs:
 203
 204   (setq auto-mode-alist
 205     (append '(("\.omk$"  . makefile-mode))
 206       auto-mode-alist))