CMSC421

Principals of Operating Systems

Sections 0101/0201/0301

Programming Project #1

Assigned: 19 Sep 2002
Project Due: 2 Oct 2002 at 11:59 pm
Design Document Due: 26 Sep 2002 at 11:50 pm

Extra credit: 26 Sep 2002 at 11:59 pm -- 10% of the graded earned.

Due date is extended to 8 Oct. Those who have it turned in on the original due date will get 15% extra credit of grade earned.

New Information 30 Sep

One student reported the following:

I built my project against the pristine kernel source for 2.4.19 
from kernel.org.  I have made several assumptions: 

/usr/src/linux is a symlink to the appropriate kernel source tree 
	(i.e. /usr/src/linux-<hatever your version is>)

/usr/include/linux is a symlink to /usr/src/linux/include/linux
	(I moved the old directory created during gcc's build to 
	/usr/include/stock_linux)

/usr/include/asm is a symlink to /usr/src/linux/include/asm
	(old directory moved as above)

Goals

This project is intended to get your feet wet with building a linux kernel, installing it, and making changes to the kernel. We assume that you have installed linux, or are in the process of doing so. This document will describe a new function that we want you to add to the kernel as a system call. The exercise is fairly straightforward. The idea is to make sure you understand the mechanics of modifying the kernel.

In the past couple of week, The Linix Users Group has helped people to install the GNU/Linux operating system. I am providing links with instructions on how to compile and install the kernel. I assume that you have installed linux, or are in the process of doing so. This document will describe a new function that we want you to add to the kernel as a system call. The exercise is fairly straightforward, and you'll add in no more than 50 lines of codes/headers etc -- probably less. The idea is to make sure you understand the mechanics of modifying the kernel.

I assume that you are already familiar with makefiles and debugging from classes such as CMSC 341. If not, this will be a considerably more difficult project because you will have to learn to use these tools as well. (Kernel debugging is different from normal debugging!)

Mechanics, and what to hand in

The project can be done in groups of up to two people, although you are welcome to work alone. If a group works on a project, then I will assign a common score to both participants. Remember that the team sinks or swims together. If there is a clash between team members, there is no way that I can tell who is correct or not. So both of you will the same grade.

Please make sure that the group is identified in the README you turn in, and that only one member of the group submits the project!

You will need to hand in all of your code and documentation using the Blackboard system available on the GL cluster. In particular, hand in the tar/gzipped version of your new kernel. To build the file to turn in, you have to make a patch file.

To submit project 1, you do the same thing that "real" software distributions do in the unix world -- create a patch. A patch is a file that notes differences between two files or directories. This file can be created via the diff command, and be used via the patch command. I encourage you to look up the man pages for both of these. In order to create the patch, assume that a "clean" version of the kernel (i.e. what you get when you untar the distribution with *no* changes) is in the directory /usr/src/linux, and your own modified kernel is in /usr/src/mylinux.

Use the command

diff -rcP /usr/src/linux /usr/src/mylinux > /tmp/diffout The /tmp/diffout file now contains all the information that the patch commands needs to transform a clean version of the linux kernel in our machine to the modified kernel you had created. Before you execute this command, you should use make clean or make mrproper to remove all the executables, since I am only interested in the changes you make to the sources. You will submit at least 2 files -- the file that has the output of the diff command, and a README file. The README file should contain all the information we need to evaluate your project, including such mundane stuff as who is in your group, and what kernel version you used. If there are any files that you had to change outside the kernel source, please submit them as well, with explanations/instructions in the README file.

I am enforcing both deadlines to ensure that people don't leave the project until the last minute. There is enough time to do the project, but not time to waste. (I guarenteee You are, of course, welcome to visit either the faculty or TA office hours for help; however, one of the first things we'll ask for is your design documentation (unless you're asking for help with that!!!). You may make changes to your documentation before the full Project #1 submission; however, the design portion of your grade will depend heavily on the design document you submit on Sep 26^th.

Your design documentation, typically 1-2 pages for a project of this size, should include the basic design of your software (what modules will you write, where will you make changes to the kernel etc.), a timeline, as well as details on the testing that you plan to do to ensure that your code works.

Version of the Kernel and Linux to Use

Because of the problems associated with the differences of hardware that everyone has, there will be no "specified version" to use. Use the one that you have installed. This will mean that some of you will have different problems that others, but we found that the Pentium 4's can not use the UMBC version of Red Hat 6.2. Those people must use a later version! We can not answer every question about all the different versions of Linux and the kernel, but there are several sources available on the Internet. Of course, the Lunix Users Group at UMBC is an excellent source of assistance. Remember though, these sources can not help you with homework specific questions! That is cheating! Whenever you seek their help, make sure you include a statement that this is to help you do a class project. Failure to do so will be considered cheating. Also, tell them what you have already tried and did not work. There is nothing worse that have some one asking for help and that person has not done the basic research first.

Specifics

You are to implement two new system calls named setSSN and getSSN. The value passed into the kernel must be stored in a kernel variable named kernelSSN which has the data type of int.

It is true that most kernels do not need a social security number for anything, but who knows, we might start a fad! =;-)
What is important that is that whenever the need to modify the kernel occurs, it is done the same way.

We should be able to invoke your function as:

setSSN (foo); or foo = getSSN( ); where foo is of the last four of a SSN. The functions are fairly straightforward, but there are several things you need to keep in mind.

You must also create two small C programs. The first one will simply get the user's SSN (only the last four digits), and set the kernel variable using the input value. The second one will retrieve the value from the kernel variable and print it out on the screen. Obviously, these are tiny programs. They simply verify that your modifications work. By having separate programs, there is no issue that you are correctly setting and getting the value. (Remember the user -- NOT YOU -- are providing the value to be stored and the TAs will be selecting that value!

Creating a Kernel Variable

The way to make a global kernel variable to:

First declare the variable, as normal (outside of any function), in one your files:
int kernelSSN;
Every other file that needs to know about will have a declaration that will pick it up:
extern int kernelSSN This includes kernel.h and ksyms.c
Put the the following into ksyms.c: EXPORT_SYMBOL(kernelSSN);

Helpful Hints

By default, code for linux exists in /usr/src/linux . If you have multiple versions of the kernel, the code may exist in /usr/src/linux-version instead. If you do not have the source code, you can download it from www.kernel.org/pub/linux/kernel There will will find all of the offical versions of the kernel. Find the one you want, such as v2.4.18.tar.gz You will have to unzip it and untar it (see the man pages for gunzip and tar) but it would be something like: gunzip linux-2.4.2.tar.gz
tar -xvf linux-2.4.2
Red Hat version is located at their ftp site ftp://ftp.redhat.com/pub/redhat/redhat-7.3-en/os/i386/SRPMS
You will probably need (though maybe not all of them):
kernel-2.4.18-3.src.rpm 33510 Kb Thu Apr 18 14:46:00 2002 kernel-pcmcia-cs-3.1.27-18.... 1197 Kb Wed Apr 17 04:35:00 2002 kernel-utils-2.4-7.4.src.rpm 238 Kb Wed Apr 17 04:35:00 2002
Create a copy of the directory for the version of the which you are going to modify. If you download the source, put it into the new directory and do all of your work in that directory. Name is something like /usr/src/linux-2.4.10-cmsc421. Keep track of the date and time that you do this. Then you will be able to find all the modified/created files that you want to turn in by using the find command. (See the man page for details on how to find files modified after a certain time.)
Recall that a system call is a software trap or interrupt. This means that when adding a new system call, you will need to update the system call table (i.e. the interrupt vector) with a new entry, and generate a stub that will be used by user programs. Look for files arch/i386/kernel/entry.S and include/asm/unistd.h, and look for the macro _syscall1 .
In the critical section of the code you write (e.g. when you access the kernel variable(s)), you should consider avoiding race conditions, perhaps by disabling and enabling the interrupts.
A kernel function is just like any other function. The header declaration has a minor difference -- the keyword asmlinkage preceeds the declaration, e.g. asmlinkage void sys_foo(void).
You will need to dereference a user space pointer in the kernel when trying to pass the value back in the argument. Look at the functions memcpy_fromfs, memcpy_tofs, and verify_area to help with this.
If you run a distribution such as Red Hat which applies many patches to its kernel, you should probably get a kernel source package from them, instead of straight from kernel.org.

Grading the Project

Remember that you can't pass this course without making a serious attempt at each of the assignments. Further, the grading is skewed so that you will get substantial credit, even if your implementation doesn't completely work, provided your design is logical and easy to understand. This means that you should first strive to come up with a clean design of your project on paper. Additionally, don't try to add fancy features because some other group is!

The grading for the project will be as follows: 40% design, 60% implementation. We have structured the grading in this way to encourage you to think through your solution before you start coding. If all you do is to work out a detailed design for what you would do to address the assignment (and if the design would work!), but you write no code, you will still get almost half of the credit for the assignment. The implementation portion of the grade considers whether you implemented your design, ran reasonable test cases, developed the two driver programs, and provided documentation that the TA could understand. Part of being a good computer scientist is coming up with simple designs and easy to understand code; a solution which works isn't necessarily the best that you can do. Thus, part of the design and implementation grade will be based on whether your solution is elegant, simple, and easy to understand.

5% of your implementation grade will come from adherring to the coding standards in the two following pages ( This will be all or none, so follow them consistently!):

Additional Resources

The following items are from the Linux Documentation Project (and others) and will provide you with additional information:

Linux Programmers Guide Link fixed! 30 Sep
How to Add a System Call
Kernel HOWTO Includes directions on how to compile the new kernel and how to modify lilo to boot the new kernel
Linux Kernel Internals
A recent article from Linux World on this subject,
Kernel Newbies
Red Hat's manual on making a custom kernel
Red Hat's manual on how to install an upgraded kernel
Configuring the Boot Loader Includes GRUB

Rules for Collaboration

This is a pretty straightforward project with a minimal amount of code to be written. Therefore I DO NOT expect that there will be occasion for you to discuss solution strategies with others. If you do not do this project yourself, then there is a good chance that you will not learn how to modify the kernel, and will certainly fail when we give you the next, more complex modification of the kernel. You are, of course, free to discuss problems relating to installing Linux. Please recall that academic dishonesty will be sternly dealt with.