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 12th.
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 _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.
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.