CMSC 421 (Fall 2001) : Project #1

Programming Project #1

CMSC 421, Fall 2001

Assigned: 4 Oct 2001
Due: 19 Oct 1998 at 11:59 PM

Goals

This project is intended to get your feet wet with building a linux kernel, installing it, and making changes to the kernel. In the past couple of week, we have handed you a linux distribution on CD, and also provided a web page with instructions on how to compile and install 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, 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.

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 in general 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 your code and documentation using the submit programs available on the GL cluster. In particular, hand in the tar/gzipped version of your new kernel. We should simply be able to compile/install the kernel you hand in, and run our test program which calls your new system call

In addition, your design documentation is due one week before the final due date, by 11:59 PM on 12 Oct 2001 . We are enforcing this deadline to ensure that people don't leave the project until the last minute. 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 handin; however, the design portion of your grade will depend heavily on the design document you handin on October 12^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.

The assignment name to use with submit for the documentation is p1doc , and for the project code is p1code.

Specifics

We ask you to implement a new system call named mykerneltime that returns the current time in a variable that you pass to the function as an argument. In effect, it returns the value of the kernel variable xtime which is of type struct timeval. This function is similar to the already provided function gettimeofday, which you can find in the file time.c . We should be able to invoke your function as mykerneltime (&foo), where foo is of type struct timeval. The function itself is fairly straightforward, but there are several things you need to keep in mind.

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

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

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.