* FRSH/FORB FRAMEWORK

  FRSH/FORB is a contract-based resource reservation framework for
  distributed real-time applications. In general, it provides timing
  isolation between applications, i.e. multiple applications can use
  the same resources such as CPU, networks, etc., without influencing
  timing of the other applications. The main principle is that
  application developers use FRSH API to specify their resource
  requirements needed to achieve desired timeliness and the framework
  uses schedulability analysis to check these requirements. If the
  check is successful an application is granted a "virtual resource"
  which allow the application to use the requested resource while
  enforcing the application not to use more than requested.

  The development of the framework begun in FRESCOR project
  (http://frescor.org) and now it is developed as a stand-alone
  project on SourceForge (http://frsh-forb.sf.net).

* BUILDING FRSH/FORB FRAMEWORK

1) Initialize and download additional submodules:
   
   git submodule init
   git submodule update

2) Install prerequisites. On Debian/Ubuntu:

     apt-get install libidl-dev libcpufreq-dev libacpi-dev \
   		     libcgroup-dev libncurses5-dev

   To build camera demo, you need to:

     apt-get install freeglut3-dev

3) Go to build directory and configure the build:
   
   cd build/aquosa
   make default-config

   If you are not satisfied with configuration found in
   config.omk-default or config.target, you can override it in
   config.omk.

   To be able to use CPU reservations AQuoSA
   (http://aquosa.sourceforge.net) has to be installed. If you cannot
   use AQuoSA, the framework can also be compiled without CPU support
   or can use cgroups. Note, that cgroups support is not well tested,
   but we plan to work on it.

4) Compile it:

   make

5) Test it:

   ./_compiled/bin/fcb &
   ./_compiled/bin/frm_dummy &
   ./_compiled/bin/frm_gui &
   ./_compiled/bin-tests/dummy_renegotiation

* DIRECTORY STRUCTURE

  * build/* - configuration for different build targets

  * build/aquosa - default build for linux

  * build/marte - build for MarteOS. Not completely supported now.

  * src - all sources

  * src/forb - CORBA-like middle for interprocess and inter-node
    communication.

  * src/frsh - The core of resource reservation framework.

  * src/frsh-include - FRSH API headers from FRESCOR project. Our FRSH
    framework implements this API.

  * src/fosa - Operating system adaptation layer

  * src/ulut - library providing generic data types and algorithms
    (AVL trees etc.).

  * src/fna - Network adaptation layer = unified API for plugging in
    different network protocols.

  * src/fwp - Communication protocol and resource management for WiFi
    (also works with Ethernet).

* OLD HOWTO - may be out of date

    Linux + AQuoSA

     * Install AQuoSA (http://aquosa.sourceforge.net)
     * $HOME/frescor/src/omk-build/aquosa
     * Adjust symlinks to FRESCOR modules (fosa, frsh, utils, ...) or use ./create-links script
     * Create config.omk containing (or use a shell variable in your .bashrc)

  AQUOSA_ROOT=/path/to/aquosa/install/path

     * Actually, my preferred way of working is adding the following
       variables in .bashrc:

  # AQuoSA environment
 
  export AQUOSA_ROOT=/usr/local/aquosa
  export PATH="$PATH:$AQUOSA_ROOT/bin"
  export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$AQUOSA_ROOT/lib"
 
  # FRESCOR environment
 
  export PLATFORM=AQuoSA
  export FOSA_ROOT=$HOME/path/to/fosa
  export FRSH_ROOT=$HOME/path/to/frsh
  export UTILS_ROOT=$HOME/path/to/utils
  LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$FOSA_ROOT/lib:$FRSH_ROOT/lib:$UTILS_ROOT/lib"
 
  # OMK environment
 
  # Use `omk' for OMK-enabled sources
  alias omk="make -f $HOME/path/to/Makefile.rules"
  # link headers instead of copying them
  export LN_HEADERS=y

     * Create default-configuration by running

  make default-config

     * Run

  make

** Further remarks

- If we are not interested in compilation of some component (because
  it is currently in uncompilable state), we can simply delete the
  link to it.

- It might be possible that you will need to change some configuration
  value from config.target. You can override any variable declared
  there in config.omk. For example, if you have MARTE installed in a
  different directory that the one specified in config.target, you can
  put the following in config.omk:

  MARTE_PATH=/path/to/marte/

- To compile the FRESCOR for Marte, it is not necessary to set PATH
  variable to GNAT compiler since OMK uses full paths to call the
  compiler.

- Since there are many things in uncompilable state, you may want to
  use `make -k' to ignore compilation errors.

- Since we don't want to modify the original Makefiles, in order to
  compile only a part of the tree, you cannot simply run make in the
  desired directory, but you have to specify -f flag with the path to
  Makefile.rules. For this reason, we recommend defining the following
  alias:

  alias omk="make -f $HOME/frescor/src/omk-build/marte/Makefile.rules"

** Why is OMK good for FRESCOR

     * It is not easy to test FRESCOR simultaneously on multiple platforms.
       With OMK, you can have the same sources compiled for multiple
       platforms/targets at the same time because it uses out of source
       directory compilation.
     * Dependencies are not handled correctly in current Makefiles. For
       example headers (in most tests) and some libraries (fosa_xxx) are not
       specified as dependencies. OMK handles dependencies automatically, so
       developers don't have to care about them.
     * With OMK it is easy to combine multiple components/libraries (from
       different developers) together and compile them with the same
       configuration (e.g. PLATFORM variable). The structure of leaf
       makefiles (Makefile for every component) is very simple and *well
       specified*. Because of this it is easy to combine components from
       multiple developers.
     * Directory structure for compilation with current makefiles must be
       fixed. In makefiles there is many "..". This prevents the use of
       symbolic links to create desired directory structure because make
       always treats ".." physically (i.e. it don't respect the directory
       structure created by symbolic links). In OMK, the position of
       directories in the source tree is not important. This is another
       reason, why integration is simpler with OMK.
     * OMK already supports compilation for user-space programs/libraries,
       Linux and RTLinux modules, RTEMS and several other platforms. Now we
       have also added support for Marte. It works under MinGW and Cygwin, so
       it can be used to compile for OSE. In Pisa, they already use OMK for
       Aquosa.

** FAQ

- How do I debug my Makefile.omk set-up ?

   Just activate verbose compilation (V=1 or V=2):

  make -f /path/to/Makefile.rules binary-pass V=1

- How do I get back syntax highlighting in Emacs while editing .omk files ?

   Just add these lines to your $(HOME)/.emacs:

  (setq auto-mode-alist
    (append '(("\.omk$"  . makefile-mode))
      auto-mode-alist))