Homework 3 - Description

Title	Date Posted	Date Due
Kernel Desires	3 / 13 / 18	4 / 2 / 18

It is time for you to embrace a rite of passage as a student of Operating Systems: you must add a system call to, and then build, your own Linux kernel.

This will give you hands-on practice manipulating a significant OS component, and give you a tour of how you might contribute to an open source OS.

To do so, you will download the current Ubuntu source, make some modifications, and then enjoy the fruits of your labor!

There is, of course, a relevant XKCD:

The above comic is entitled "Cautionary," and so it is only appropriate that we begin with some cautions and requirements:

[READ FIRST] Requirements:

Linux Version: to standardize this assignment, we will be working with the Ubuntu 16.04 distribution.
VirtualBox Settings:
- Storage: you may choose to work with your existing VirtualBox image, but note that building the kernel can require upwards of 15GB of FREE space. As such, it is suggested (for modularity, if nothing else) that you create a new VirtualBox image with at least 35GB of space for this assignment (Dynamically Sized may be the appropriate choice for the VirtualBox as you see fit).
- RAM / Processing: because kernel compilation can take so long, it is important to maximize your VirtualBox's available RAM and Processors -- this can be done in the VB settings.
- System Standby: in your Ubuntu system settings, ensure that the computer will never go on standby, lest it interrupt the kernel build process.
Patience: this assignment places a large onus of responsibility on you to investigate the means of building a Linux kernel for the latest version. Subtle differences between versions will cause many tutorial articles (including your textbook) to be slightly out-of-sync with the latest distributions. As such, Google is going to be your *best* friend on this assignment -- just like in the X-Files, "The Truth is Out There," but it's up to you to find it.
Time Management: the greatest investment you will need on this assignment is time management, not because your modifications of the kernel will take long, but because the compilation process can, for some systems, take many hours. If you leave this assignment to the last second, you will simply be out of luck.

With this cautionary tale spun, let's look at the specific requirements.

Specifications

In this assignment, you will modify an existing distribution of Ubuntu, add your own custom system call to the kernel, recompile it, boot from it, and then execute an example C program that employs your System call!

Your deliverables for this assignment are three-fold:

Tutorial PDF: along your journey in pursuit of the above, you will find that almost *no* existing tutorial has the precise steps necessary to build an Ubuntu 16.04 distribution with a custom system call. As such, you should compose a Tutorial PDF that details the steps you took in order to complete your task.
supworld.c: this will be your simple, custom, system call (supworld with identifier sys_supworld) that merely need print "Sup World" to the system log (printk will be your friend here). If you'd like it to do something more, be my guest, but this is all you are required to do for this assignment.
syscall_test.c: a simple C program demonstrating the use of your custom supworld system call.

What follows are a list of steps meant to help you to complete the above, but you should treat them with a couple of caveats:

1. The links below are meant to guide your solution, but may have incomplete or dated information -- part of your challenge for this assignment is to be self-reliant enough to bridge the gaps that the guides may have.

2. Make sure to detail every step that you take in your Tutorial PDF while accomplishing the below; make sure to annotate any deviations you take from the given guides.

Part I: Obtaining the Source

For this step, perform the steps up until, and including, "Build Environment" in the following link.

Ubuntu Kernel Build Instructions

Note: the apt-get method is the simpler of the two if you already have a running distribution of Ubuntu.

You may encounter your first issue during this part, at which point you should (1) do some Googling, and (2) see the Troubleshooting section below for a hint.

Part II: Adding Your System Call

For this step, complete step 3 (except for 3d) in the following link.

Adding a System Call to Linux Kernel

Warning: the paths in the above do not perfectly map to the most recent kernel version; Google and see Troubleshooting section once more to save thyself.

Moreover, the tutorial has you implement a service for the kernel, but we're just adding a simple system call as detailed above, so use your supworld.c implementation in the service's place (making sure to name all things along the way similarly).

Part III: Building and Booting

Warning: this step can take several hours to complete, but you can accelerate the process if you have multiple processors devoted to your VirtualBox distribution. To enable them for the build process, enter the following into the terminal in which you plan to execute the build process: export CONCURRENCY_LEVEL=2 if you have 2 processors devoted to the VirtualBox, which can be changed to more processors if they are available.

For this step, return to the Build Your Own Kernel instructions and complete the Building and Testing the Kernel steps (in the building step, you need only execute the first 2 commands).

Ubuntu Kernel Build Instructions

Some notes:

If everything went OK, you'll find several .deb files in the directory above the one you built from. You need only dpkg the three given in the tutorial above.
Once you sudo reboot, hold shift when you see the VirtualBox splash screen (to open the GRUB boot loader), go to Advanced Options, and find your custom kernel.

If you find that there is a bug during this step due to the changes you introduced in Step II, worry not: future builds will be accelerated from a previous build, but will still take quite a while to complete.

Another relevant XKCD:

Part IV: The Great Test

You've made it this far, the end is near! All you have to do now: test it.

Running your modified kernel (from the step above), write your syscall_test.c program to verify that your supworld system call is working as intended.

Some notes:

Your test will likely need only use the syscall function with your syscall index and second argument as NULL.
Because your syscall will printk its message, this prints to the kernel log. To access the log and verify that the message is being printed, use the dmesg command and then some other command (hint hint) to find your message. Screenshot this moment of victory for your Tutorial.

Troubleshooting

Having problems with any of the above? Here are a few helpful links that might unwedge you during the process (but I won't tell you what part each of them can be used to solve, and this is not a complete list -- just meant to give you some inspiration!)

Why is my apt-get not working? https://askubuntu.com/questions/496549/error-you-must-put-some-source-uris-in-your-sources-list
Where are the system call tables? https://askubuntu.com/questions/781951/adding-system-call-in-latest-kernel

Submission

What

Zip your Tutorial PDF, System Call implementation (supworld.c), and Test File (syscall_test.c) C programs and submit via Brightspace.

How

We will (unfortunately) be using Brightspace to submit this assignment, though you should always be using version control to organize your assignments (even text)!

To submit your assignment:

Find this assignment listing on Brightspace.
Upload the .zip file containing your submission.
Make sure to click "submit" after the upload is complete!