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 might be provided through 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 build system if you have extensively changed it.
Starting configurationThis section describes each part of the system as it is when you get the code. The image below shows how the system is set up.
Figure 1: System startup configuration diagram
- hardware: This is the Odroid-C2 development board that you will be using during the project. See the Odroid-C2 Lab page for more details on the hardware.
- seL4: This is the microkernel you will be developing your project on. See the seL4 manual for further detail.
- 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 SOS will run.
ninja to construct a comprehensive
build system that manages dependencies, configuration options and building the project.
Milestone 0 provides info on how to
use the build system. Milestones that require you to modify the build system provide
instructions on how to do so.
Adding new source files
CMake does not automatically detect new source files (
*.c) are added
to a project. When you add new files, find the closest
file in the directory hierarchy and add the file to the list in the
ninja will then automatically
CMakeLists.txt files and rebuild your project correctly.
CMake does support
GLOB style detection of files,
but there are significant downsides.
Configuration settingsTo view and edit configuration settings, first enter the build directory and open the
cd build ccmake ..You can use less-style searching (eg.
/Sos) to find the configuration option to change. Hit enter to change an option, then
cto regenerate the config. Once you are finished, use
gto save the generated configuration and exit. Sometimes you must regenerate the config several times with
gcan be used, as
CMakeneeds several iterations to resolve all dependencies. Further commands are listed at the bottom of the cmake UI.
The network configuration of SOS is setup via CMake, as above. The following options are available:
- Network mask: This configuration option will set the network mask.
- IP address: This configuration option will set the IP address of the Odroid-C2. This option is dependant on the configuration of the host computer.
- Gateway IP address: This configuration option sets the destination IP address of network packets sent from the Odroid-C2.
- NFS directory: This configuration option can be used to set an alternate NFS directory to mount in case the default mount point was not found.
Most of the code you will write will be in the
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!
- This file is the driver of the minimal stub code you have been
provided. The interesting thing here is the startup procedure,
which should be fairly easy to follow. On startup the following
- Initialises the muslc c library
- Bootstrapping: initialisation of the cspace, untyped memory management, and DMA subsystems.
- Sets up a basic UART driver for serial output, and switches to use this for output
- Creates the endpoint and notification objects used for receiving IPC and interrupts, respectively.
- Allocates and switches to a new, bigger stack with a guard page.
- Initialises of the network drivers and libraries.
- Runs some unit tests to check the system is working.
- Spawn a thread in a new address space
- Start the interrupt, fault and IPC handling loop.
- elf.c & elfload.h
- A very basic (stub) elf loading implementation.
- Provides a helper functions which can be used to map frames into the virtual memory space of SOS. Kernel page table objects are created as they are needed, however, the allocation of the frame to be mapped is left to the caller. Note: The current code "leaks" the page tables, something you will need to fix in later milestones.
- A simple implementation of a frame table that uses compact references to uniquely identify frames. Also maps managed frames into SOS.
- Provides a simple interface to register handlers for various IRQs.
- These files handles DMA for the network driver.
- These files are responsible for setting up the network device drivers and initialising hardware for you.
- Defines the layout of virtual memory for SOS and it's applications.
These files implement the untyped memory management subsystem.
During bootstrapping, all available untyped memory is broken into 4K objects. The ut manager allows for allocation and freeing of 4K objects and smaller. When an object smaller than 4K is allocated, a 4K untyped is broken into smaller untypeds until the allocation can be made. A free list per untyped size is maintained by the ut manager.
Note that while the allocate can allocate objects less than 4K, it does not recombine freed smaller objects into 4K frames. So, if you allocate all of memory as < 4K objects, you will not be able to allocate further 4K objects.
sizebitsas a parameter. The memory reserved or freed by these calls will have a size of
- syscalls.h & sys/*.c
- These files define various functions for the C library to
call when called from within SOS. For instance, it provides the
sys_brkused within SOS.
- Bootstrapping code. You should not need to modify this.
print_backtrace, which you can use to generate a primitive stacktrace for debugging.
- Unit tests for SOS. We strongly recommend you build on these.
- This library provides basic functionality available to all apps and sos, including logging, C library support and debug routines.
- This is the clock interface that you will implement in M1. Also contains useful constants for the timer driver.
- Contains the ethernet driver used by SOS.
- Capability space management library.
- This library provides functionality for serial over LAN driver in M0
- 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.
- Interfaces for interacting with the seL4 kernel directly. Also contain handy macros and error codes.
- A library for parsing the cpio archive that is linked to SOS.
This archive will contain applications such as
- A library for parsing ELF files.
- A wrapper that integrates the top level
libnfslibrary, which is an open source NFS client library.
- A wrapper that integrates
projects/picotcp-bsd, an open source network stack.
- A basic synchronisation library for seL4. If you need sync primitives, this is where to look.
- A fairly complete C library that is not thread safe, backed by functions set up by SOS and
other applications using the
init_muslcfunction. Note that support for muslc in SOS and the apps is not complete: if "Syscall not implemented" is output then muslc has called a backing function which is not implemented. This includes any advanced functionality (pthreads for example).
- A library of helper routines and macros.
Applications that sos runs are in the
projects/aos/apps folder. You have been provided
with two applications;
See milestone 7 for details on how to add a new application.
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.