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