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.

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.

SConstruct and the SCons build system

We have provided a fairly comprehensive build system for you, however you will need to edit the SConstruct (found in projects/sos/) throughout your project as you add new libraries and applications. The SConstruct itself is commented, this documentation is meant to supplement those comments.

The SConstruct basically does the following:

• Initialise the scons build environment for kernel engenerring 'Kenge'.
• Set up three build environments: the kernel_env, the rootserver_env and the app_env.
• For each environment the appropriate libraries are enumerated.
• Creates at least one application in all of these environments.
• Creates a boot_image with all of the applications listed earlier.

Libraries

Each library needs to be enumerated and added to each build context, note some libraries are actually used multiple times in multiple envirnments. For instance the libs/c library is included in the rootserver_env, the tools_env and the app_env and will be built three times too. To create a library you will need to complete a number of steps:

• First create a directory libs/<libname>.
• Create a top level library SConscript (not SConstruct!) file, libs/<libname>/SConscript. See libs/serial/SConscript for a simple example.
• Call Package("<libpath>") on the appropriate build environments in the top level SConstruct file.
• Finally you will need add the library to your application's SConscript file, there are several examples of how to do this in sos, tty_test and sosh

Apps

Executables are setup in a similar way to libraries. However instead of living in the libs directory they live at the top level of the project.

You should note that the sos app is special, as this is your privileged server. It is linked with different libc code, and is inserted into your boot image differently. You should always ensure that sos is the first application after the l4kernel in the apps list passed to elfweaver_env.LayoutVirtual().

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 implementation has been kept very simple, (you wouldn't want us to do all the fun bits would you!). 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 L4 helper "library".
2. Initialise frame table.
3. Spawn a thread (init_thread) to finish initialisation.
4. Start the syscall/interrupt/pager IPC loop.

init_thread

You may be wondering why we spawn a separate thread to handle most of the initialisation. The main reason for this is so that we can keep things simple (no really!). In the init_thread you may wish to execute some code that waits for interrupts, or possibly waits to IPC to a user-level program. Now both interrupts and user-level code rely on the IPC loop being able to respond to IPC.

There are of course other ways you could structure your start-up protocol and operating system so that this is not required. For example, you may want to have a separate thread for each interrupt handler. Or you may wish to restrict init_thread so that it doesn't rely on user-level code or interrupts. You are free to explore these ideas in the design of you system.

libsos.c

Is a simple L4 environment library to make some of the calls to L4 simpler, L4 helper "library". At some stage you will need to modify it to re-implement the sos_usleep function on your clock driver.

network_init

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.

libs/

So that you don't have to write everything from scratch, we provide you with some libraries to get you going.

libs/c

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

libs/serial

A pseudo serial driver for the slug, actually uses UDP/IP.

libs/lwip

A light-weight IP stack.

libs/nfs

A simple NFS client.

libs/elf

A library for parsing ELF files.

libs/ixp_osal

The Intel IXP Operating System Access Layer(OSAL).

libs/ixp400_xscale_sw

The Intel provided driver code for the IXP420 platform.