From 03c3040a1df588085375d6d03ee29cb17721f0da Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Tue, 7 Apr 2020 10:49:40 +0200 Subject: [PATCH] Remove stale documentation The topics are either covered by the Genode Founations book for by our tools, in particular the integration of the prepare_port mechanism with the run tool. --- repos/base-fiasco/doc/fiasco.txt | 119 --------------- repos/base-foc/doc/foc.txt | 78 ---------- repos/base-nova/doc/nova.txt | 195 ------------------------- repos/base-okl4/doc/okl4.txt | 128 ---------------- repos/base-pistachio/doc/pistachio.txt | 68 --------- 5 files changed, 588 deletions(-) delete mode 100644 repos/base-fiasco/doc/fiasco.txt delete mode 100644 repos/base-foc/doc/foc.txt delete mode 100644 repos/base-nova/doc/nova.txt delete mode 100644 repos/base-okl4/doc/okl4.txt delete mode 100644 repos/base-pistachio/doc/pistachio.txt diff --git a/repos/base-fiasco/doc/fiasco.txt b/repos/base-fiasco/doc/fiasco.txt deleted file mode 100644 index d4429958f..000000000 --- a/repos/base-fiasco/doc/fiasco.txt +++ /dev/null @@ -1,119 +0,0 @@ - - ============================================= - 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 -* Byacc -* 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 toplevel directory: - -! ./tool/ports/prepare_port fiasco - -For the vesa driver on x86 the x86emu library is required and can be downloaded -and prepared by invoking the following command: - -! ./tool/ports/prepare_port x86emu - -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: - -! /tool/create_builddir fiasco_x86 \ -! BUILD_DIR= - -From within the new , the kernel can be compiled via - -! make kernel/fiasco - -When using Genode's run mechanism, there is no need to explicitly build the -kernel. The run environment (see 'tool/run/boot_dir/fiasco') 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. - -Those components are implicitly built by the Genode build system when -issuing 'make kernel/fiasco'. diff --git a/repos/base-foc/doc/foc.txt b/repos/base-foc/doc/foc.txt deleted file mode 100644 index b55c60a70..000000000 --- a/repos/base-foc/doc/foc.txt +++ /dev/null @@ -1,78 +0,0 @@ - - =================================== - Genode on the Fiasco.OC microkernel - =================================== - - - Stefan Kalkowski - - -Fiasco.OC is a microkernel originally developed by the OS group of the -TU-Dresden. Nowadays, it is primarily maintained and developed by -the company Kernkonzept. It's an object-oriented capability-based system -for x86, ARM, PowerPC and MIPS platforms. - -This document provides brief instructions about downloading, building and -booting the Fiasco.OC version of Genode. - - -Prerequisites -############# - -You need certain tools to use the Fiasco.OC build system. On Debian/Ubuntu -systems you have to install the following packages: - -! apt-get install make gawk g++ binutils pkg-config g++-multilib subversion - -Moreover, you need to download and install the tool-chain used by Genode. Have -a look at this page: - -:[http://genode.org/download/tool-chain]: - Genode tool-chain - - -Building the Fiasco.OC version of Genode -######################################## - -The current version of Genode is available at the public Github repository: - -:http://github.com/genodelabs/genode: - Github repository of Genode - -After you've fetched the Genode source tree from the git repository, or -downloaded the latest release tar archive, you need the Fiasco.OC source code, -its kernel-bindings, additional bootstrap tools etc. To simplify that step, -you can use the 'prepare_port' tool: - -! ./tool/ports/prepare_port foc - -This will install all necessary third-party source code in the 'contrib' folder. - -Now, go to a directory where you want the Genode/Fiasco.OC build directory to -remain. Use the helper script in the 'tool' directory of the Genode -source tree to create the initial build environment. You need to state the -build directory you want to create, and the hardware architecture to run -Fiasco.OC/Genode on. Choose 'x86_32', 'x86_64', or one of the available ARM -boards. - -! /tool/create_builddir x86_64 - -Now, go to the newly created build directory and type make: - -! cd build/x86_64 -! make KERNEL=foc - -This will build the Fiasco.OC kernel, its bootstrap code, and every Genode component, -that runs on top of Fiasco.OC. - -If you just want to give Genode/Fiasco.OC a try, you can call e.g.: the demo run-script -instead of building everything: - -! make run/demo KERNEL=foc - - -Further Information -################### - -:[https://l4re.org/fiasco/]: - Official website for the Fiasco.OC microkernel. diff --git a/repos/base-nova/doc/nova.txt b/repos/base-nova/doc/nova.txt deleted file mode 100644 index e7fbf6cd5..000000000 --- a/repos/base-nova/doc/nova.txt +++ /dev/null @@ -1,195 +0,0 @@ - - ========================================== - How to use Genode with the NOVA hypervisor - ========================================== - - Norman Feske - - -When we started the development of Genode in 2006 at the OS Group of the TU -Dresden, it was originally designated to be the user land of a next-generation -and to-be-developed new kernel called NOVA. Because the kernel was not ready at -that time, we had to rely on intermediate solutions as kernel platform such as -L4/Fiasco and Linux during development. These circumstances led us to the -extremely portable design that Genode has today and motivated us to make Genode -available on the whole family of L4 microkernels. In December 2009, the day we -waited for a long time had come. The first version of NOVA was publicly -released: - -:Official website of the NOVA hypervisor: - [http://hypervisor.org] - -Besides the novel and modern kernel interface, NOVA has a list of features that -sets it apart from most other microkernels, in particular support for -virtualization hardware, multi-processor support, and capability-based -security. - - -Why bringing Genode to NOVA? -############################ - -NOVA is an acronym for NOVA OS Virtualization Architecture. It stands for a -radically new approach of combining full x86 virtualization with microkernel -design principles. Because NOVA is a microkernelized hypervisor, the term -microhypervisor was coined. In its current form, it successfully addresses -three main challenges. First, how to consolidate a microkernel system-call API -with a hypercall API in such a way that the API remains orthogonal? The answer -to this question lies in NOVA's unique IPC interface. Second, how to implement -a virtual machine monitor outside the hypervisor without spoiling -performance? The Vancouver virtual machine monitor that runs on top NOVA proves -that a decomposition at this system level is not only feasible but can yield -high performance. Third, being a modern microkernel, NOVA set out to pursue a -capability-based security model, which is a challenge on its own. - -Up to now, the NOVA developers were most concerned about optimizing and -evaluating NOVA for the execution of virtual machines, not so much about -running a fine-grained decomposed multi-server operating system. This is where -Genode comes into play. With our port of Genode to NOVA, we contribute the -workload to evaluate NOVA's kernel API against this use case. We are happy to -report that the results so far are overly positive. - -At this point, we want to thank the main developers of NOVA Udo Steinberg and -Bernhard Kauer for making their exceptional work and documentation publicly -available, and for being so responsive to our questions. We also greatly -enjoyed the technical discussions we had and look forward to the future -evolution of NOVA. - - -How to explore Genode on NOVA? -############################## - -To download the NOVA kernel and integrate it with Genode, issue the following -command from within toplevel directory: - -! ./tool/ports/prepare_port nova - -For the vesa driver on x86 the x86emu library is required and can be downloaded -and prepared by invoking the following command from within the 'libports' -directory: - -! ./tool/ports/prepare_port x86emu - -For creating a preconfigured build directory prepared for compiling Genode for -NOVA, use the 'create_builddir' tool: - -! /tool/create_builddir nova_x86_32 BUILD_DIR= - -This tool will create a fresh build directory at the location specified -as 'BUILD_DIR'. Provided that you have installed the -[http://genode.org/download/tool-chain - Genode tool chain], you can now build -the NOVA kernel via - -! make kernel - -For test driving Genode on NOVA directly from the build directory, you can use -Genode's run mechanism. For example, the following command builds and executes -Genode's graphical demo scenario on Qemu: - -! make run/demo - - -Challenges -########## - -From all currently supported base platforms of Genode, the port to NOVA was -the most venturesome effort. It is the first platform with kernel support for -capabilities and local names. That means no process except the kernel has -global knowledge. This raises a number of questions that seem extremely hard -to solve at the first sight. For example: There are no global IDs for threads -and other kernel objects. So how to address the destination for an IPC message? -Or another example: A thread does not know its own identity per se and there is -no system call similar to 'getpid' or 'l4_myself', not even a way to get a -pointer to a thread's own user-level thread-control block (UTCB). The UTCB, -however, is needed to invoke system calls. So how can a thread obtain its UTCB -in order to use system calls? The answers to these questions must be provided by -user-level concepts. Fortunately, Genode was designed for a capability kernel -right from the beginning so that we already had solutions to most of these -questions. In the following, we give a brief summary of the specifics of Genode -on NOVA: - -* We maintain our own system-call bindings for NOVA ('base-nova/include/nova/') - derived from the NOVA specification. We put the bindings under MIT license - to encourage their use outside of Genode. - -* Core runs directly as roottask on the NOVA hypervisor. On startup, core - maps the complete I/O port range to itself and implements debug output via - the serial/UART I/O ports defined by the BIOS data area. - -* Because NOVA does not allow rootask to have a BSS segment, we need a slightly - modified linker script for core (see 'src/core/core.ld'). - All other Genode programs use Genode's generic linker script. - -* The Genode 'Capability' type consists of a portal selector expressing the - destination of a capability invocation. - -* Thread-local data such as the UTCB pointer is provided by the new thread - context management introduced with the Genode release 10.02. It enables - each thread to determine its thread-local data using the current stack - pointer. - -* NOVA provides threads without time called local execution contexts (EC). - Local ECs are used as server-side RPC handlers. The processing time - needed to perform RPC requests is provided by the client during the RPC call. - This way, RPC semantics becomes very similar to function call semantics with - regard to the accounting of CPU time. Genode already distinguishes normal - threads (with CPU time) and server-side RPC handlers ('Rpc_entrypoint') - and, therefore, can fully utilize this elegant mechanism without changing the - Genode API. - -* On NOVA, there are no IPC send or IPC receive operations. Hence, this part - of Genode's IPC framework cannot be implemented on NOVA. However, the - corresponding classes 'Ipc_istream' and 'Ipc_ostream' are never used directly - but only as building blocks for the actually used 'Ipc_client' and - 'Ipc_server' classes. Compared with the other Genode base platforms, Genode's - API for synchronous IPC communication maps more directly onto the NOVA - system-call interface. - -* The Lock implementation utilizes NOVA's semaphore as a utility to let a - thread block in the attempt to get a contended lock. In contrast to the - intuitive way of using one kernel semaphore for each user lock, we use only - one kernel semaphore per thread and the peer-to-peer wake-up mechanism we - introduced in the release 9.08. This has two advantages: First, a lock does - not consume a kernel resource, and second, the full semantics of the Genode - lock including the 'cancel-blocking' semantics are preserved. - -* On the current version of NOVA, kernel capabilities are delegated using IPC. - Genode supports this scheme by being able to marshal 'Capability' objects as - RPC message payload. In contrast to all other Genode base platforms where - the 'Capability' object is just plain data, the NOVA version must marshal - 'Capability' objects such that the kernel translates the sender-local name to - the receiver-local name. This special treatment is achieved by overloading - the marshalling and unmarshalling operators of Genode's RPC framework. The - transfer of capabilities is completely transparent at API level and no - modification of existing RPC stub code was needed. - - -Manually booting Genode on NOVA -############################### - -NOVA supports multi-boot-compliant boot loaders such as GRUB, Pulsar, or gPXE. -For example, a GRUB configuration entry for booting the Genode demo scenario -with NOVA looks as follows, whereas 'genode/' is a symbolic link to the -'var/run/demo/genode' directory created by invoking the 'demo' run script. - -! title Genode demo scenario -! kernel /hypervisor iommu serial -! module /genode/core -! module /genode/config -! module /genode/init -! module /genode/timer -! module /genode/nitpicker -! ... - -Limitations -########### - -The current NOVA version of Genode is able to run the complete Genode demo -scenario including several device drivers (PIT, PS/2, VESA, PCI) and the GUI. -Still the NOVA support is not on par with some of the other platforms. -The current limitations are: - -* Threads (ECs) can not be migrated to another CPU once started. - -* For portals used as exception vectors for threads, the thread causing the - exception and the handler thread which is bound to the exception portal must - be on the same CPU. diff --git a/repos/base-okl4/doc/okl4.txt b/repos/base-okl4/doc/okl4.txt deleted file mode 100644 index c3dcd3fc7..000000000 --- a/repos/base-okl4/doc/okl4.txt +++ /dev/null @@ -1,128 +0,0 @@ - - ============================== - Genode on the OKL4 microkernel - ============================== - - - Stefan Kalkowski - - -OKl4 is a microkernel developed and distributed by Open Kernel Labs. It is -focused on embedded devices. Genode support the OKL4 kernel version 2.1 -on the x86_32 platform. - -This document provides brief instructions about downloading, building and -booting the OKL4 version of Genode. - - -Prerequisites -############# - -You need Python 2.4 to use the OKL4 build system. On Debian/Ubuntu systems -simply type: - -! apt-get install python2.4 - -Since Ubuntu 10.04, the python2.4 package is no longer part of the official -repositories. However, you can manually add the repository via: - -! add-apt-repository ppa:python24-team/python24 -! apt-get update - -Moreover, you need to download and install the tool-chain used by Genode. Have -a look at this page: - -:[http://genode.org/download/tool-chain]: - Genode tool-chain - - -Downloading and building the OKL4 kernel -######################################## - -To download the OKL4 source code, issue the following command: - -! /tool/ports/prepare_port okl4 - -It will take care of downloading the kernel's source code and applying the -patches found at 'base-okl4/patches'. - -For the VESA driver on x86, the x86emu library is required and can be downloaded -and prepared by invoking the following command: - -! /tool/ports/prepare_port x86emu - -To create a build directory for Genode running on OKL4, use the 'create_builddir' -tool: - -! /tool/create_builddir okl4_x86 - -Once you have created the build directory at '/build/okl4_x86', -the OKL4 kernel can be built from within the build directory via - -! make kernel - - -Running the Genode demonstration scenario -######################################### - -For a quick test drive of the OKL4 kernel, issue 'make run/demo' from the -build directory. - - -Manually building a boot image -############################## - -This section is not needed when using Genode's run-script mechanism. The manual -steps described below are automatically executed via the OKL4 run environment -as found at 'tool/run/boot_dir/okl4'. - -To practically use the OKL4 kernel and applications running on top of it, Open -Kernel Labs provide a tool called 'elfweaver', that is used to merge different -application binaries and the kernel itself into one single elf binary that can -be executed by your bootloader, e.g. Grub. - -To configure 'elfweaver' to merge the appropriated elf binaries you have to -provide an XML file. A good starting point is the 'weaver_x86.xml' file that -includes the Genode demo example. Simply copy that file to your Genode build -directory and adapt the 'file' attribute of the 'kernel' tag to the absolute -path of the OKL4 kernel we build previously. - -! cp /base-okl4/tool/weaver_x86.xml weaver.xml - -The corresponding line in your weaver.xml should look like this: - -! - -Before creating the image, we need to supply a Genode config file as well. -For a quick start, you can copy and rename the template provided 'os/config/demo' -to '/bin/config'. Alternatively, you can assign another file to the -'filename' of the 'memsection' declaration for the config file in 'weaver.xml'. -Now, we can use 'elfweaver' to create the image. Go to the 'bin' directory in -the Genode build directory that contains all the binaries and invoke the -script. - -! cd bin -! /tools/pyelf/elfweaver merge --output=weaver.elf ../weaver.xml -! strip weaver.elf - -Note: the given paths to the resulting elf file and the input xml file have to -be relative. - -*Bug alert:* Elfweaver triggers an assertion when too many memsections are -declared in the 'weaver.xml' file and just outputs the following message -! An error occurred: -Apparently, elfweaver has a problem with calculating the size of the boot info -section. As a quick fix, you can increase the value of 'BOOTINFO_GUESS_OPS' in -'/tools/pyelf/weaver/bootinfo.py'. - -The resulting elf image can be loaded by GRUB now. - - -Further Information -################### - -:[http://genode.org/documentation/articles/genode-on-okl4]: - Article about the porting work of Genode to OKL4, featuring many technical - insights that are useful to understand the peculiarities of this base - platform. - diff --git a/repos/base-pistachio/doc/pistachio.txt b/repos/base-pistachio/doc/pistachio.txt deleted file mode 100644 index 3f3ec6e51..000000000 --- a/repos/base-pistachio/doc/pistachio.txt +++ /dev/null @@ -1,68 +0,0 @@ - - ========================================= - Genode on the L4ka::Pistachio microkernel - ========================================= - - - Norman Feske - - -Pistachio is the reference implementation of the L4 API version x.2 (also -referred to a v4). It is developed by the System Architecture Group at the -University of Karlsruhe, Germany and the DiSy group at the University of -New South Wales, Australia. - -Because this kernel has been the experimentation platform for a lot of exciting -research experiments at the L4ka group and it is the basis for the commercial -version of L4 developed by OK-Labs, Pistachio is a very interesting base -platform for the Genode OS Framework. - -The original port of the Genode OS Framework to Pistachio is the work of Julian -Stecklina who wanted to elaborate on the portability of the framework and -explore the use of Pistachio's multi-processor capabilities with Genode. - -This document provides brief instructions about downloading, building and -booting the Pistachio version of Genode. - - -Downloading, building, and using L4ka::Pistachio -################################################ - -Please make sure that you haved downloaded and installed the tool chain, -which will be used for both, the L4ka::Pistachio kernel and Genode. - -:[http://genode.org/download/tool-chain]: - Preconfigured GNU tool chain for building Genode - -To download the kernel source codes, issue './tool/ports/prepare_port pistachio'. -This command will checkout the upstream Git repository of the kernel. Please -make sure to have Git installed. - -For the vesa driver on x86 the x86emu library is required and can be downloaded -and prepared by invoking the following command: - -! ./tool/ports/prepare_port x86emu - -After having successfully prepared the 'base-pistachio' repository and -'libports' you are ready to create a Genode build directory using the -'tool/create_builddir': - -! /tool/create_builddir pistachio_x86 \ -! BUILD_DIR= - -From within this directory, you can build the kernel by using 'make kernel'. -The kernel will be built within '/kernel/pistachio' using the Genode -tool chain. - -To build and start Genode directly from within the Genode build directory, -issue - -! make run/demo - -This command will execute the steps described in the run script located at -'os/run/demo.run'. It will build all Genode components needed for the demo -scenario, create a configuration, and start the scenario using Qemu. To inspect -the individual steps more closely or learn the steps needed to manually -integrate Genode with L4ka::Pistachio, please revisit the Pistachio-specific -run environment at 'tool/run/boot_dir/pistachio'. -