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.

1. Build system & Project Structure
2. Starting configuration
3. Build system
   1. Adding new source files
   2. Configuration settings
   3. Network configuration
   4. SOS
   5. Applications
4. Libraries

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 Makefile if you have extensively changed it.

Starting configuration

This 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 development board that you will be using during the project. Documentation can be found in the wiki.
• seL4: This is the microkernel you will be developing your project on. You have the sources, but will not have dive into these. You also will not be using most of the interface directly, but you should still understand all of the basic concepts. Documentation is 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.

Build system

We use CMake and 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 CMakeLists.txt file in the directory hierarchy and add the file to the list in the add_executable command. ninja will then automatically detect changes to CMakeLists.txt files and rebuild your project correctly.

Note that CMake does support GLOB style detection of files, but there are significant downsides.

Configuration settings

To view and edit configuration settings, first enter the build directory and open the CMake configuration editor:

    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 c to regenerate the config. Once you are finished, use g to save the generated configuration and exit. Sometimes you must regenerate the config several times with c before g can be used, as CMake needs several iterations to resolve all dependencies. Further commands are listed at the bottom of the cmake UI.

Network configuration

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.

SOS

Most of the code you will write will be in the projects/aos/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 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 happens:

  1. Initialises the muslc C library
  2. Bootstrapping: initialisation of the cspace, untyped memory management, and DMA subsystems.
  3. Sets up a basic UART driver for serial output, and switches to use this for output (e.g. printf).
  4. Creates the endpoint and notification objects used for receiving IPC and interrupts, respectively.
  5. Allocates and switches to a new, bigger stack with a guard page.
  6. Initialises of the network drivers and libraries.
  7. Runs some unit tests to check the system is working.
  8. Spawn a thread in a new address space (the tty_test application).
  9. Start the interrupt, fault and IPC handling loop.

• elf.c & elfload.c

  A very basic (stub) elf loading implementation.

• mapping.[c|h]

  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.

• frame_table.[c|h]

  A simple implementation of a frame table that uses compact references to uniquely identify frames. Also maps managed frames into SOS.

• irq.[c|h]

  Provides a simple interface to register handlers for various IRQs.

• dma.[c|h]

  These files handles DMA for the network driver.

• network.[c|h]

  These files are responsible for setting up the network device drivers and initialising hardware for you.

• vmem_layout.[c|h]

  Defines the layout of virtual memory for SOS and it's applications.

• ut.[c|h]

  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.

  ut_alloc and ut_free both require sizebits as a parameter. The memory reserved or freed by these calls will have a size of 2^sizebits.

• 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 implementation of sys_brk used within SOS.

• bootstrap.[c|h]

  Bootstrapping code. You should not need to modify this.

• backtrace.[c|h]

  Provides print_backtrace, which you can use to generate a primitive stacktrace for debugging.

• tests.[c|h]

  Unit tests for SOS. We strongly recommend you build on these.

Applications

You have been provided with three applications; sos, tty_out and sosh. All applications are placed in the apps directory. See milestone 7 for details on how to add a new application.

Libraries

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.

• projects/aos/libaos

  This library provides basic functionality available to all apps and sos, including logging, C library support and debug routines.

• projects/aos/libclock

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

• projects/aos/libethernet

  Contains the ethernet driver used by SOS.

• projects/aos/libsel4cspace

  Capability space management library.

• projects/aos/libserial

  This library provides functionality for serial over LAN driver in M0

• projects/aos/libsosapi

  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.

• projects/aos/libsel4

  Interfaces for interacting with the seL4 kernel directly. Also contain handy macros and error codes.

• projects/libcpio

  A library for parsing the cpio archive that is linked to SOS. This archive will contain applications such as tty_test and sosh.

• projects/libelf

  A library for parsing ELF files.

• projects/libnfs

  A wrapper that integrates the top level libnfs library, which is an open source NFS client library.

• projects/libpicotcp

  A wrapper that integrates projects/picotcp and projects/picotcp-bsd, an open source network stack.

• projects/libsel4sync

  A basic synchronisation library for seL4. If you need sync primitives, this is where to look.

• projects/musllibc

  A fairly complete C library that is not thread safe, backed by functions set up by SOS and other applications using the init_muslc function. 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).

• projects/libutils

  A library of helper routines and macros.