School of Computer Science & Engineering
University of New South Wales
Advanced Operating Systems
COMP9242 2018/S2
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 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 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 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.
Build system
We use CMake
and ninja
to construct a comprehensive
build system that manages depdenencies, 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.
- Startup application name: Once SOS is initialised, SOS
will proceed to load an initial process from its
cpio image.
This configuration options provides the name of the
application to load. In later milestones, this option will
need to be changed to
sosh
or to the name of a
testing application that you may have created.
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:
- 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
(e.g.
printf
).
- 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
(the
tty_test
application).
- Start the interrupt, fault and IPC handling loop.
- elf.c & elfload.h
-
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.
- 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.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 2sizebits
.
- 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
Applications that sos runs are in the projects/aos/apps
folder. You have been provided
with two applications; tty_out
and sosh
.
See milestone 7 for details on how to add a new application.
Libraries
Existing 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.
Last modified:
19 Jul 2018.