Codezero Jumpstart Guide

Here is a list of bare minimum details you need for building, running and also, understanding Codezero.

This guide assumes you have SCons >= 1.0, Python 2.6, QEMU binary provided on the Getting Started page, CodeSourcery or similar arm-eabi cross compiler, and cross-gdb Insight installed on your machine.

Download the latest master branch by:

% git clone git://git.l4dev.org/codezero.git

Master branch is always stable, and updated very regularly. But if you want to go for the cutting edge:

% git checkout -b devel --track origin/devel

You may configure codezero by:

% ./build.py --configure

This would create a configuration template that may be used for up to 4 containers.

It is already configured for a single, empty project. See conts/empty0 directory to start hacking. empty0 is the project name and project sources are created upon configuration.

You have 2 other quick options:

a.) Create multiple baremetal projects:

• In the configuration window, change number of containers to 2.

• → Container Setup → Container 0 Parameters → Container Options → Baremetal Project

• Select Hello world. Do the same for Container 1.

• Quit by typing 'x'.

b.) Run the posix container to see some more action:

• Simply run the configure.py command as:

% ./build.py -f config/cml/examples/posix/two_posix.cml

• Quit by typing 'x'.

This would configure 2 separate POSIX containers, in a pager/client format with lots of IPC, page fault handling, demand paging, file IO etc.

You can direct configure utility to use an existing configuration by supplying it the -f <cml filename> option.

Run the following command:

% ./build.py

If you would like to do configuration first, run:

% ./build.py -C

On baremetal projects, you may test your build by changing to the project directory (e.g. conts/empty0), and typing 'scons' at top-level.

You must have QEMU and Insight set up for this stage. Simply type:

% ./tools/run-qemu-insight

Make sure to copy ./tools/gdbinit file to your home directory renamed as .gdbinit beforehand.

To look at all up-to-date man pages, please run in the top-level dir:

% man -M docs/man <man-page-name>

where the man page name may be any page provided under docs/man. E.g. l4_map, l4_thread_control, capability, utcb. Strongly recommended read.

In a nutshell, Codezero is a hypervisor for embedded systems, and it is a flagship L4 microkernel evolving the L4 API to the future.

There are a few fundamental notions that needs to be understood:

INTRODUCTION

Codezero provides the bare minimum kernel mechanisms that are needed to run services on top. These are threads, address spaces who contain threads inside them, and containers who contain many address spaces.

Codezero provides fast and flexible IPC mechanisms for thread communication. It provides system calls for thread manipulation, address space manipulation (e.g. mapping devices, physical memory, virtual memory). See here for more. It also acts has a hardware abstraction layer with a simple and highly generalized API. It allows control operations over the CPU such as architecture specific cache operations and irq handling.

CONTAINERS

Containers are an important notion in Codezero. Containers allow the system to be partitioned into multiple rooms of execution, or virtual environments. Each container has its own set of threads, address spaces, and resources.

Each container provides enough mechanism for development of any software setup:

• In a client server model, a designated pager produces child threads and address spaces, and manages them. A virtualized operating system kernel and its applications model this behaviour.

• In a standalone application model, the application is the pager itself, and it creates multiple threads in the same address space. Such stand-alone multi-threaded applications are also possible to develop.

CAPABILITIES

Codezero is a fully capability-checked kernel. In essence, this means that the system is controlled and secured by a flexible security model. All system calls, all kernel resources such as memory regions, memory pools, and interprocess communication is protected by capabilities.

Capabilities may be dynamically changed and transferred by the l4_capability_control system call. Normally this call is not needed as everything may be configured statically at configuration time.

Capabilities are important as they provide the fine-grain resource management privileges on top of the abstract notion of containers. In a nutshell, containers provide the rough skeleton for secure system partitioning, and capabilities finely adjust them by providing dynamically manageable fine-grain access control. Read the capability manual page for more information.

SYSTEM CONFIGURATION

System configuration may be done using the CML kernel configurator mentioned earlier, by simply running ./configure.py script.

System configuration is important as each container and each container's memory resources, number of threads, memory pools, the capabilities of who to call for inter-process communication may be all configured flexibly using the configuration system. It is important to understand how the configuration options work.

That's it! In a nutshell Codezero provides all the basic mechanism to abstract away the hardware, build OS services, isolate applications and fine-grain security in a single package.