Linux Syscall Project

by: burt rosenberg
at: university of miami


Dissecting the kernel
This project will have you build a modified Linux kernel from source, adding several system calls and a file into the kernel code base.

  1. Review my information on building the linux kernel.
  2. Watch this You Tube presentation of adding a Linux syscall.
We are not going to do it exactly the way he does it. Our new file added to the kernel will be: 
/usr/src/linux-source-3.13.0/linux-source-3.13.0/kernel/mysystemcalls.c
and the makefile to modify will be in that directory, adding mysystemcalls.o to the list of obj-y files, except in the makefile in that kernel directory.

Look in the class/proj2 directory for a Makefile that should guide you. The diff target indicates what files need to be changed, and that all I wanted submitted is diffs. I do not want your new kernel checked into subversion! Just the result of make diff.

The Makefile also gives you two test programs: one that tests the simpler mysyslog sysytem call, that you should implement first, to get you started; and a second that tests a more complicated ring-buffer (like a system pipe) system call.

As before, the TDD file has commands and there is a reference output file as to how your program should respond to the commands. Matching the reference output is a minimal accomplishment. I might have my own, more extensive TDD file for grading. In particular, the point of the system call is that different processes can share information using the ring buffer, because it is a shared buffer in the kernel, and you must create an automated test to demonstrate this.

Specific Objectives

Detailed Directions

This project has templates in class/proj2. Using them will help you get started, and will make clear some of the requirements for a proper solution. Copy them to your _username_/proj2, add and make a first commit.

The Makefile

The Makefile provides a great deal of guidance as to what needs to be modified in the kernel, and how you are to submit proof of completion. You are to use diff's to show me what you changed.

Do not check in binaries, kernels sources that you did not write, or other build products! You are to create a single new file in the kernel source tree, mysyscalls.c, and modify three kernel files: a Makefile, the syscall table file, and an include/kernel file. See the diff target in the Makefile for specifics. Before modifying the original files, make a copy with a ".dist" suffix, as you can see in the diff target. That was, running make diff in your subversion tree will capture your changes to a .diff file that you will svn add and commit.

mysyslog: Do this function first. It is pretty much what is shown in the video.

Note that the very first build of the kernel you will need to run make modules_install. Afterwards this is not necessary. Modules_install will create a subdirectory of /lib/modules with a name that matches the kernel version. You can do an ls of /lib/modules to make sure all is well.

You will not need to reinstall the modules after this (I think! ... buyer beware!) However, changes to the system call table will cause a full build that will take about 2 hours. Don't forget to make install after the make, to move the new kernel and initrd into /boot.

Changes to just mysyscalls.c to correct bugs will only require rebuilding of a few files and a final relinking of the kernel. This will only take a few minutes. Still, don't forget to make install to move the new kernel into /boot and update the grub configuration.

ringbuffer calls: Three functions enqueue, dequeue and check for emptiness of a 15 character queue that is in the kernel. A 15 character queue will require a char buf[16], and two indices into the array, one pointing to the next place to read, and the other, the next place to write. If the indices are equal, then the buffer is empty.

Return -1 if a dequeue is called on an empty buffer, else return the character and remove it from the queue.

Return -1 if a enqueue is called on a full buffer, else return 0 and enqueue the character into the queue.

Have the empty queue predicate simply return the numerical value of == applied to the two indices.

The tdd test file and the response shown in the tdd.ref file should be used as a guide to the requirements of the API.

Subversion checkins

Once again, do not check in binaries, build products, or kernel code you did not write. The Makefile shows what to checkin, but in case that isn't clear, check in:
  1. mysyscalls.c. This file is written by you for scratch and is in the kernel subdirectory of the linux source tree. The make diff target makes a copy into your subversion proj2 folder, and you will add and commit it.
  2. diffs of the changes to the system table file, the kernel/Makefile, and the linux/syscalls.h file. Once again, the make diff target shows how to do this and saves the result in a file with .diff appended.
  3. You test C files, which will most likely be simply copies of what I wrote for you in class/proj2, as well as the test H header file.
  4. Your Makefile
  5. Your tdd.out file that matches the tdd.ref file.

This is minimal. You will need to modify the Makefile and add tdd files to prove further that your code works. In particular, because the ring buffer is in kernel space, all user programs share it. You should explore having one program enqueue data while another program dequeues data.

You should use the return values to determine for the writer of data when the buffer is full and it should sleep, and for the read of data when the buffer is empty and it should sleep.

In later projects we will discuss but the inefficiency of this "polling for data" method, and the synchronization problems that can occur when multiple readers and writers try to share this ring buffer. In fact, this discussion of synchronization is a major part of this course, so I am getting you set up for this discussion with this project.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Author: Burton Rosenberg
Created: September 21, 2014
Last Update: September 21, 2014