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