Project: A Simple Operating System

These pages outline what you will be expected to implement for the project. While some minor details may change during session, this has been a successful format for a number of years. It is a good idea to start thinking early and try to understand the full assignment and ask any questions you have about structure and problems early.

Overview

The aim of the assignment is to implement a simple operating system (SOS) server on top of the seL4 microkernel. The SOS server is expected to provide a specified system call interface to its clients (Specified in libs/libsosapi/include/sos.h).

The project will be completed by groups of 2 students. This is a challenging project. You have been warned! The project is to be completed using the facilities in the OdroidC2 Lab.

Assessment

About half the marks for the project are obtained for timely and complete submission and demonstration of intermediate milestones (M0–M6). These milestones will be demonstrated in the lab each week. When demonstrating your solution you should be able to:

show a working solution,
explain how the code you have written works, and
explain any design decisions you made.

The remaining marks will be determined by our assessment of your overall project and documentation. The assessment involves:

testing your code and its conformance with the specifications,
inspecting your code as to how well and efficiently it is written, and
perusing your documentation as to its completeness, appropriateness and consistency with your implementation.

Project Late Penalty Policy

The late penalty for all project milestones is 5% per weekday late, up to a maximum of 10 weekdays late.

Some clarifying examples, given a hypothetical Friday 6pm deadline.

Submitted Friday 5pm,no penalty.
Submitted Friday 6:30 pm, 1 weekday late, 5% penalty.
Submitted Monday the following week at 5 pm, 1 weekday late, 5% penalty.
Submitted Monday the following week at 6:30 pm, 2 weekdays late, 10% penalty.
Submitted Friday the following week at 5 pm, 5 weekdays late, 25% penalty.
Submitted Friday the following week at 6:30 pm, 6 weekdays late, 30% penalty.
Submitted Friday two weeks after the deadline at 6:01 pm, which is greater than 10 weekdays late, zero marks.

Milestones

All milestones must be submitted via give and are due at 6:00 pm, Friday of the respective week! The demonstrations of what was submitted must be completed within 7 days (168 hours) from the submission time. Details of how to submit can be found here.

M0: Familiarisation: Due: Friday, 6:00 pm, Week 1
Marks: 5 (we recommend discontinuing the course if more than one week late)
Milestone 0 involves familiarising yourself with the provided source code and build system, and then writing a simple IPC protocol. This milestone should be done individually. Further milestones are done in groups.
M1: A timer driver: Due: Week 2
Marks: 5 (we recommend discontinuing the course if more than one week late)
Write a simple device driver for the timers available on the Odroid C2.
M2: System call interface: Due: Week 3
Marks: 5
Design and implement the system call interface for your operating system.
M3: A virtual memory manager: Due: Week 4
Marks: 5
Design and implement a virtual memory management system to manage mapping and fault handling of processes within your operating system.
M4: The filesystem: Due: Week 5
Marks: 5
Using the provided code implement the filesystem related system calls. Use your timer driver to benchmark your implementation.
M5: Demand paging: Due: Week 7
Marks: 5
Implement demand paging in your operating system.
M6: Process management: Due: Week 9
Marks: 5
Design and implement process loading and management. You should implement the process_* system calls.
M7: Documentation and final system: Due: Friday 6pm, Week 10
Marks: 10 docs, 20 code
Complete the documentation for your project. You also have a chance to clean up your codebase for your final submission. This milestone does not involve a lab demo.

Advanced Components (aka Stuff for Masochists)

The following features, if submitted together with your Milestone 7, will give bonus marks. (2 marks each)

Note: the bonuses must also be demonstrated at a to-be-arranged time in week 9 or 10.

Shared memory

Implement shared memory via the share_vm() system call and demonstrate operation with some application which has processes communicating via shared memory.

mmap and munmap

Implement the mmap() and munmap() system calls to allow malloc() and free() to support dynamic allocations greater than 112KiB.

Clock driver loaded from file system

Rather than loading your clock driver from the boot image, load it from the file system and run it as a separate seL4 task.

Filesystem caching

Reserve a part of RAM as a file system cache. Implement caching of directory information and file data, as well as read-ahead, to improve file system performance.

Dynamic filesystem (only valid with file system caching)

Have your SOS file system behave correctly even if files are added/removed in the Unix file system while your SOS is running. Do this without significantly degrading performance.

Kernel bugs

Note that your kernel is not verified, although it shares most of the code with the verified kernel. As such, it is highly unlikely that you trigger a bug. Should you be able to demonstrate a (not yet known) bug, you'll also get bonus marks, but the bug must supply code that can reliably reproduce the bug, and have the bug confirmed by a developer.

If you find a bug in the verified code you'll get a lifelong supply of beer at Gerwin's expense ;-)

Notes on Bonus Marks

No bonus marks will be awarded on a “sympathy” basis for a well-intended attempt — your code implementing a bonus feature must completely work (except for maybe some minor details) in order to qualify for a bonus.
The maximum number of bonus marks that can be accumulated is 10, no matter how they have been earned.
Bonus marks (for doing a bonus component of the project) can be used to make up for lost project marks, up to the maximum project mark possible (65). If your total project marks, including bonus, exceeds 65, the surplus can be used at half face value for marks lost in the exam.
Bonus marks cannot be used if the raw exam mark is less than 40%, a 40% raw exam mark is an absolute prerequisite for passing the course!

Resources

Warning!

Some students are tempted to write some tricky or obscure code for these projects. Other students run into problems by trying to do too much.

I can only reiterate that the debugging environment you have on the Odroid-C2 is extremely spartan. You will not do yourself a favour by writing obscure or particularly tricky code. You'll most likely end up getting hopelessly tangled up in your own code. Don't do this.

Write your code as clearly, obviously and straightforward as possible. This is the best safeguard against obscure bugs. I believe that the project is challenging enough as it is, there is no need to make it harder.

Furthermore, when doing the final project marking I will obviously not look with much sympathy upon code I find difficult to understand.

The same applies for implementing features beyond the project specifications. You are welcome to do this, but, in your own interest, you are strongly advised to implement the required features first. First make it work, then go for the extras! Most of the (very few) students who have failed the course to date have ignored this rule — at their peril!

Demonstration and Submission of Milestones

Details on how to submit each milestone as well as how to set up a repository for submission can be found on the submission page.

You will need to set up an initial repository to submit milestone 0, which is to be complete individually, as well as a group repository for all subsequent milestones.

Additionally, you are to show that your project passes the milestone requirements by demonstrating its operation to a demonstrator during one of the allocated times during the week after the milestone is due!.

You can only demonstrate the specific code that was submitted. You will be asked to check out the exact commit in your repository that was submitted. Any changes or bug fixes that are made after the submission can only be marked if a new submission is made which can incur a late penalty.

You will be required to submit a version of your code from your git repository. See our submission guidelines for details.

For milestone 7, in addition to submitting the code, you will also need to submit the documentation for the design of your system.

Only one member of the group needs to submit milestones 1–7.

Notes

All students belonging to the group must be present during the demonstration.
Only one group member needs to submit the source code electronically.
The demonstrator will ask you questions on your implementation to make sure that you understand what you are presenting. Your responses to this questioning will have a major impact on the mark you will be receiving.
Zero marks will be awarded if you cannot demonstrate a basic understanding of your solution. A trial-and-error approach will not get you anywhere.
In most cases all members of a group will receive the same mark. However, in cases where there is a clear difference in understanding of the problem and its solution between the group members, we will differentiate the marks awarded.
All of the project milestones build upon each other. The assessment strategy aims to keep you on track by ensuring your project meets a reasonable standard as you progress. As such, we generally don't mark your milestone in a traditional sense. Instead, if your milestone does not meet a minimum standard, it is rejected and you are encouraged to resubmit an improved version and demonstrate again. Obviously, the late penalty applies for (re)submission after the milestone deadline. Observe that submitting and demonstrating as early as practical (e.g. before the deadline) maximises your chances of avoiding late penalties.
Marks for milestones 0 to 6 are awarded at demonstration time. Marks for milestone 7 are only awarded after our testing and code inspection. Bonuses are submitted with milestone 7 and marked via demo.
Milestone 7 will require you to submit the full code in a form we can use for automatic testing. This means that you will have removed all debugging output, none of your OS or library code should write anything (other than what clients write to the console).
Milestone 7, the documentation, will be submitted electronically as a PDF file. We also tolerate ASCII text files (with or without LaTeX or HTML formatting commands), but definitively not a word/ODF/XML document or anything the like).