CMSC421

PRINCIPALS OF OPERATING SYSTEMS

Section 0201/0301

Programming Project #1

Assigned: 6 March 2002
Due: 20 March 2002 at 11:59 PMM\
14 March 2002 at 11:59 PM for 10 per cent extra credit

New information 14 Mar

The way to make a global kernel variable to:

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

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.

We 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.

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 we will assign a common score to both participants. 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 the code you create or modify and documentation using the blackboard system available on the GL cluster.

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!

Specifics

We ask you to implement two new system calls named mysetkernel and mygetkernel. You will create an integer variable in the kernel space (to make sure we do not use a label alread in use, call it CMSC421_0201 or CMSC421_0301, based on which section you are in. mysetkernel will have one argument, which will be used to give the variable a new value. mygetkernel will return the current value. Additionally, you must provide a driver to show that the system calls work. The driver should have a set of five (5) set/get calls to show that the calls are working. The function are fairly straightforward, but there are several things you need to keep in mind.

There is one additional requirement! mygetkernel must be implemented as a loadable module. This requirement is not rocket science and the LDP Linux Kernel Module Programming Guide is a good reference.

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
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 inlude/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 must avoiding race conditions, perhaps by disabling and enabling the interrupts for the smallest amount of time possible.
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).
If you 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

The intent of the grading for the project is not to differentiate among those students who do a careful design and implementation of the assignments. Rather, the grading helps us identify those students who (i) don't do the assignments or (ii) don't think carefully about the design, and therefore end up with a messy and over-complicated solution. Remember that you can't pass this course without at least 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. Second, 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. The implementation portion of the grade considers whether you implemented your design, ran reasonable test cases, 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. Another critical success factor is ability to communicate! Thus, part of the design and implementation grade will be based on whether your solution is elegant, simple, and easy to understand.

As an extra incentative, there is a ten per cent (10%) extra credit if you have it turned in by 14 March at 11:59. There will also be an additional 5 per cent (5%) if you print out the variable before you return it

Additional Resources

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

A recent article from Linux World on this subject:

http://www.idg.net/go.cgi?id=638772

Rules for Collaboration

This is a pretty straightforward project with a minimal amount of code to be written. We therefore 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.

UMBC CMSC421