-Introduction
-============
+* FRSH/FORB FRAMEWORK
-This is the development trunk of FOSA Fresh OS Adaption), a library to
-port FRSH to POSIX and non-POSIX platforms.
+ 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).
-This directory holds the C API and test examples. Specific
-achievements or milestones will be reflected with static tags at:
+* BUILDING FRSH/FORB FRAMEWORK
- http://www.frescor.org/private/svn/frescor/fosa/snapshots
+1) Install prerequisites. On Debian/Ubuntu:
-Extensive documentation about FOSA can be found in the D-EP3
-deliverable series.
+ apt-get install libidl-dev libcpufreq-dev libacpi-dev \
+ libcgroup-dev libncurses5-dev
+ To build camera demo, you need to:
-Directory Overview
-==================
+ apt-get install freeglut3-dev
-- README: This file.
+2) Go to build directory and configure the build:
+
+ cd build/aquosa
+ make default-config
-- COPYING: GNU GENERAL PUBLIC LICENSE
+ If you are not satisfied with configuration found in
+ config.omk-default or config.target, you can override it in
+ config.omk.
-- include/: FOSA API C header files.
+ 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
+ (echo CONFIG_AQUOSA=n >> config.omk) or can use cgroups (echo
+ CONFIG_CPUCG=y >> config.omk). Note, that cgroups support is not
+ well tested, but we plan to work on it.
-- src_marte/ : source code of FOSA for MaRTE-OS
-- src_ose: source code of FOSA for OSE
-- src_partikle/: source code of FOSA for ParTiKle
-- src_aquosa/: source code of FOSA for AQuoSA
-- src_rtlinux/: source code of FOSA for RT-Linux
+3) Compile it:
-- marte_non_local_jump: temporary place holder for MaRTE-OS longjump
- implementation
-- lib/: libraries.
+ make
-- doc/: Extra Documentation (TODO, INSTALL, changelog and API_reference.pdf)
+4) 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
+
+** 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))