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    make test
  53
  54 * DIRECTORY STRUCTURE
  55
  56   * build/* - configuration for different build targets
  57
  58   * build/aquosa - default build for linux
  59
  60   * build/marte - build for MarteOS. Not completely supported now.
  61
  62   * src - all sources
  63
  64   * src/forb - CORBA-like middle for interprocess and inter-node
  65     communication.
  66
  67   * src/frsh - The core of resource reservation framework.
  68
  69   * src/frsh-include - FRSH API headers from FRESCOR project. Our FRSH
  70     framework implements this API.
  71
  72   * src/fosa - Operating system adaptation layer
  73
  74   * src/ulut - library providing generic data types and algorithms
  75     (AVL trees etc.).
  76
  77   * src/fna - Network adaptation layer = unified API for plugging in
  78     different network protocols.
  79
  80   * src/fwp - Communication protocol and resource management for WiFi
  81     (also works with Ethernet).
  82
  83 * MISCELLANEOUS
  84
  85 ** Advantages of OMK make system
  86
  87      * It is not easy to test FRSH/FORB simultaneously on multiple
  88        platforms. With OMK, you can have the same sources compiled for
  89        multiple platforms/targets at the same time because it uses out
  90        of source directory compilation.
  91      * Automatic handling of dependencies. When a file is changed,
  92        only the files dependent on it are rebuilt. Developers don't
  93        have to care about this.
  94      * With OMK it is easy to combine multiple components/libraries (from
  95        different developers) together and compile them with the same
  96        configuration (e.g. PLATFORM variable). The structure of leaf
  97        makefiles (Makefile for every component) is very simple and *well
  98        specified*. Because of this it is easy to combine components from
  99        multiple developers.
 100      * OMK already supports compilation for user-space
 101        programs/libraries, Linux and RTLinux modules, RTEMS and
 102        several other platforms. Now we have also added support for
 103        Marte. OMK works under MinGW and Cygwin, so it can be used to
 104        compile for OSE. In Pisa, they already use OMK for Aquosa.
 105
 106 ** Further remarks
 107
 108 - If you are not interested in compilation of some component (e.g .
 109   because it is currently in uncompilable state), you can simply
 110   delete the link to it.
 111
 112 - It might be possible that you will need to change some configuration
 113   value from config.target. You can override any variable declared
 114   there in config.omk - just create it and put variable definitions to
 115   it. For example, if you have MARTE installed in a different
 116   directory that the one specified in config.target, you can put the
 117   following in config.omk:
 118
 119   MARTE_PATH=/path/to/marte/
 120
 121 - FRSH/FORB support for Marte OS is not maintained. However, if you
 122   want to try it, it is not necessary to set PATH variable to GNAT
 123   compiler since OMK uses full paths to call the compiler.
 124
 125 - Since we don't want to modify the Makefiles developed for Marte OS,
 126   in order to compile only a part of the tree, you cannot simply run
 127   make in the desired directory, but you have to specify -f flag with
 128   the path to Makefile.rules. For this reason, we recommend using omk
 129   script instead of make. The script can be obtained from
 130   http://rtime.felk.cvut.cz/gitweb/omk.git/blob_plain/HEAD:/omk.
 131
 132 ** FAQ
 133
 134 - How do I debug my Makefile.omk set-up ?
 135
 136    Just activate verbose compilation (V=1 or V=2):
 137
 138   make V=1
 139
 140   or
 141
 142   make -f /path/to/Makefile.rules binary-pass V=1
 143
 144 - How do I get back syntax highlighting in Emacs while editing .omk files ?
 145
 146    Just add these lines to your $(HOME)/.emacs:
 147
 148   (setq auto-mode-alist
 149     (append '(("\.omk$"  . makefile-mode))
 150       auto-mode-alist))