]> rtime.felk.cvut.cz Git - frescor/frsh-forb.git/blobdiff - README
forb: Do not compile inet_broadcast if it is not used
[frescor/frsh-forb.git] / README
diff --git a/README b/README
index 8b137891791fe96927ad78e64b0aad7bded08bdc..e2a0ee82d9ee8a1a0b1803d133f5d656d5780a56 100644 (file)
--- a/README
+++ b/README
@@ -1 +1,160 @@
+* 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) 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
+
+2) 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
+   (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.
+
+3) Compile it:
+
+   make
+
+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))