SOS framework

This document describes the provided SOS framework. This is provided to make it easier for you to get started with the project. The source code itself should be reasonably well commented, and you should ensure that you understand the provided source code.

Build system & Project Structure

Note that the structure of the project and the build system are intimately linked. Although you are free to change the build system and layout of the project it is discouraged for the following reasons:

• Patches, and additional libraries will be provided throughout the course,
• You will be required to write additional documentation about your layout and build system if it is changed,
• Tutors won't spend time debugging your Makefile if you have extensively changed it.

Starting configuration

• Hardware: This is the nslu2 or 'Slug' that you will be using during the project. Documentation can be found here.
• seL4: This is the microkernel you will be developing your project on. You don't have the sources, and will not be using most of the interface directly, but you should still understand all of the basic concepts. Documentation is here.
• om_server: The object manager(OM) server is a server that starts your operating system, and provides an abstraction layer for seL4 memory and object management. The library for this server is provided in libs/sel4/libom_server and the sources are in apps/om_server. Documentation can be found here.
• sos: This is the stub operating system that you will build your project from. The starting configuration has one thread in one address space and contains functional networking libraries.
• tty_test: This is the first application that sos will run.

Make and the Kbuild build system

We have provided a fairly comprehensive build system for you, however you will need to edit the Makefiles and Kconfig/Kbuild files throughout your project as you add new libraries and applications. For the most part you should be able to work out how to alter them.

The root Makefile builds all of the separate applications as separate binaries. It then uses a program called dite to link all of these binaries into one image, bootimg.bin. All of the other Makefiles are used to specify source and header file locations for each library or application, which are then used in the common.mk general purpose Makefile.

The Kbuild/Kconfig files are used to manage dependencies and select libraries and applications for building. Whenever you change one of these files you need to make menuconfig to pick up the changes.

Applications

Executables are setup in a similar way to libraries. sos, tty_out, sosh and om_server are all applications. Applications are placed in the apps directory. See milestone 7 for details on how to add a new application.

sos/

Most of the code you will write will be in the sos directory. Currently there is a very minimal operating system implemented, which should help get you started. The following section presents a brief overview of each file. Find more details in the source!

main.c

This file is the driver and bulk of the minimal stub code you have been provided.The interesting thing here is the startup procedure, which should be fairly easy to follow in main.c. On startup the following happens:

1. Initialise the root_tcb and root_address_space that have been set up by the om_server for sos.
2. Start all of the network drivers and relevant libraries.
3. Initialise frame table.
4. Spawn a thread in a new address space (the tty_test application).
5. Start the syscall/interrupt/pager IPC loop.

dma_malloc.c

This file handles DMA for the various network drivers.

sys_*.c, k_r_malloc.h

These files define various functions for the standard C library to call when called from within SOS. For instance, it provides the implementation of sys_morecore used within SOS.

network.[c|h]

The provided network.c handles setting up the network device drivers and initialising hardware for you. It exports the single network_init function, which you should ensure is called on startup. You will need to edit this file at some stage to enable the nfs part of networking.

elf.[c|h]

A very basic (stub) elf loading implementation.

frametable.[c|h]

A frame table stub file.

pagetable.c/h

A pagetable stub file.

panic.[c|h]

Defines a macro for panic that prints out the file and location where the panic occured.

Libraries

All of the libraries are provided in the libs directory. Libraries depend on each other, so the Kconfig file in the root of each library directory defines any dependencies.

In order to add a new library, you need to do the following:

• First create a directory libs/sel4/<libname>.
• Create a top level library Kconfig. libs/sel4/<libname>/Kconfig. See libs/sel4/libserial/Makefile for a simple example.
• Create a top level library Makefile. libs/sel4/<libname>/Makefile. See libs/sel4/libserial/Makefile for a simple example.
• Add your library to the libs/Kconfig and libs/KBuild files.
• Use make menuconfig to select your library and include it in the build.
• Modify the application you want to use your library. This means including 'name' (no lib) in the LIBS list, and modifying the Kconfig depends on line to include your library.

So that you don't have to write everything from scratch, we provide you with some libraries to get you going. Some of the libraries are directly relevant to you, in that you will be implementing and extending them. Others are used by other components of the system, but you are free to investigate the source out of interest (or while debugging). All of the libraries are listed here with brief descriptions, in order of relevance to your project.

libs/sel4/libsos

This is the library that applications use to interface with SOS. You will extend and implement the interfaces present over the course of the project.

libs/sel4/libom_server

This is the library that SOS uses to interface with the om_server.

libs/sel4/libclock

This is the clock interface that you will implement in M1. Also contains useful constants.

libs/sel4/libsel4

Interfaces for interacting with sel4 directly. Also contains handy macros and error codes.

libs/sel4/libsel4c

A somewhat cut down libc, which includes string handling, malloc and assert.

libs/sel4/libsel4sync

A basic syncrhonisation library for sel4. If you need synch primitives, this is where to look.

libs/sel4/liblwip

A light-weight IP stack.

libs/sel4/libnfs

A simple NFS client.

libs/sel4/libsel4elf

A library for parsing ELF files.

libs/sel4/libixp_osal

The Intel IXP Operating System Access Layer(OSAL).

libs/sel4/libixp400_xscale_sw

The Intel provided driver code for the IXP420 platform.

libs/sel4/elfloader

Library for building the bootimage and loading up sel4.

libs/sel4/diteloader

Parsing library for the bootimage, which is constructed from several different images by the dite program.

libs/sel4/libsel4sos-allocator

Memory allocator used in om_server.

libs/sel4/libsel4csm

Cspace management library. Used by the backing allocator for om_server.

libs/sel4/libsel4vka

Interface for allocation used by libcsm.

libs/sel4/libsel4rootserver-sel4sos

Provides standard C library stubs for om_server (sys_exit, sys_morecore etc.)