Imported Genode release 11.11

base-fiasco/doc/fiasco.txt

@@ -0,0 +1,130 @@
+
+        =============================================
+        How to use Genode with the Fiasco microkernel
+        =============================================
+
+
+               Norman Feske, Christian Helmuth
+
+Abstract
+########
+
+This documentation describes the process of building and booting the L4/Fiasco
+version of Genode. It assumes that you are familiar with basic concepts
+described in the introductory documentation of Genode, namely the "How to start
+exploring Genode" document.
+
+
+Preconditions
+#############
+
+The Fiasco version of Genode relies on the following components from
+the source tree of the Fiasco microkernel and the L4 environment (which also
+need additional tools).
+
+
+Tools
+=====
+
+* Gawk
+* Bison
+* Python
+
+
+The Fiasco microkernel
+======================
+
+Information about Fiasco are provided at its official website:
+
+! http://os.inf.tu-dresden.de/fiasco/prev/
+
+To download the kernel and integrate it with Genode, issue the following
+command from within the 'base-fiasco' directory:
+
+! make prepare
+
+This command will download a prepackaged version of the kernel tested
+with Genode. The build process of the kernel is integrated with Genode's
+build system. After creating a build directory using 'create_builddir'
+with 'fiasco_x86' as argument:
+
+! <genode-dir>/tool/create_builddir fiasco_x86 \
+!   BUILD_DIR=<build-dir>
+
+From within the new <build-dir>, the kernel can be compiled via
+
+! make kernel
+
+When using Genode's run mechanism, there is no need to explicitly
+build the kernel. The run environment (see 'base-fiasco/run/env')
+takes care of it. So you can simple execute run scripts from within
+the build directory, for example:
+
+! make run/demo
+
+
+Behind the scenes
+=================
+
+For using the L4/Fiasco kernel, some basic user-level components and libraries
+are needed. These are subsumed under the name L4 environment an are organized
+as a number of packages. These packages provide two types of components.  There
+are low-level components for booting up and interfacing to Fiasco and there are
+higher-level components that compose a basic OS infrastructure. For Genode, we
+only rely on the low-level packages.
+
+Previous versions of Genode included all necessary sources from the L4
+environment in the '3rd/fiasco/snapshot' subdirectory. From release 10.02, the
+'3rd' directory is no longer part of the release archive and also removed from
+the subversion repository. Please download the '3rd_fiasco.tar.bz2' archive.
+The source are organized as follows
+
+:'tool': contains the tools that are used by the build processes of
+  the L4 environment and Fiasco. For example, the build process of Fiasco
+  relies on the 'preprocess' tool.
+
+:'kernel': contains the Fiasco microkernel.
+
+:'l4': contains the L4-environment source tree. The single packages
+  are located at 'l4/pkg'.
+
+From all the packages of the L4 environment, the following three are of
+interest for using Genode:
+
+:'pkg/l4sys': contains the Fiasco system-call bindings.
+
+  The system-call bindings are a set of C-header files that define the
+  application-programming interface for invoking the system calls of
+  Fiasco.
+
+:'pkg/sigma0':
+
+  Sigma0 is the initial memory manager required to use Fiasco.
+
+:'pkg/bootstrap':
+
+  Bootstrap is the program that is started by the boot loader.
+  After being started, Bootstrap prepares the bare machine to
+  accommodate Fiasco. On many embedded architectures, bootstrap
+  is used to create a single binary image containing all boot-time
+  OS components.
+
+To build all components under '3rd/fiasco' after extracting the
+archive, issue the following commands:
+
+! mkdir <build-dir>
+! make -C 3rd/fiasco BUILD_DIR=<build-dir>/3rd build
+
+The specified '<build-dir>' must be the absolute path to the
+directory, which will contain the build directories for the third party
+software and the Genode build directory. After the build, your compound
+build directory contains the following subdirectories:
+
+:'fiasco_x86':
+
+  All generated files and the final binary of Fiasco reside here.
+
+:'l4env':
+
+  L4 environment binaries and header files.
+