Value:       (See the Grading section of the Syllabus.)

Due Date and Time:       (See the Course Calendar.)

Summary:

This is your final project. You will be writing a new or improved device driver, or possibly another kernel module, working on a team of two or three people. You may propose a project that interests you. If you do not propose a project of your own, you will write an improved device driver for a video frame grabber device.

• Work on a real device driver or other kernel module, providing useful functionality that did not exist before.

• If you are working on a project chosen by your team, you will need to agree on a set of more detailed objectives within the team, and obtain approval of those objectives by the instructor. In general, the criteria for a project are:

  • It performs some useful practical or research purpose.
  • It requires you to write new code that executes in the kernel.
  • The new code requires you to demonstrate ability to use significant elements of the kernel internal programming interfaces and concepts covered in the course.
  • It appears likely that a team can complete it, or at make least enough progress to be evaluated, in three (3) weeks.

• One generic type of project would be to improve on the real-time performance of an existing device driver. This would start with testing the driver (either by internal instrumentation or by means of user-level benchmark tests) to obtain baseline performance data, then making improvements, and re-testing the driver to determine how the performance has been affected by your changes. Of particular interest would be improvements to the use of interrupts, to reduce the potential CPU time interference caused by the driver's interrupt-driven code. For example, the "NAPI" technique used by the E1000 driver might be applied to some other drivers. For another example, advanced features of the newer Intel Ethernet cards permit possible improvements over NAPI, by taking advantage of hardware features on the device to throttle interrupts. (A nice feature of the Intel cards is that they are fully documented by the vendor.) Mark Stanovic may be able to provide some test programs that might be re-used for performance analysis of network devices.

• If you work on the video frame grabber driver, you should improve on the drivers developed by students in previous summers. Target characteristics for the driver include:

  • Support the current Video4Linux API.
  • Support user-level (memory mapped) access to the device registers, so that a user could choose to access the device directly.
  • Support both polling and interrupt-driven I/O.
  • Support using both the PCI and ISA (PC104) address ranges.
  • Make use of kernel configuration parameters to only include PCI/ISA specific code if support for that option is enabled in the kernel. That is, the driver should still work correctly if the system does not support PCI, but only supports ISA bus, or vice versa.
  • Support restriction of the video input to a subwindow of the full device frame. This is needed for real-time access, where there is not enough PCI-bus or CPU bandwidth to transfer entire frames.
  • Support streaming at full speed, if possible.
  • More precisely synchronize the driver copying data from the device frame buffer, using advanced Linux kernel timer features, if present. If these features are not present, the driver should fall back to a less precise mode.
  • Support user-provided initialization sequence, so that the card comes up with a configuration different from the default.
  • Support both color and greyscale cards, in one driver.
  • Compilation correctly "out of the box" for multiple kernel versions, including both kernel 2.6.21.1 and other recent kernels.
  • Out-of-the box tests, that can be used to verify that all features of the driver are working.
  • Improved installation, including makefile and human-readable instructions, any any necessary scripts
  • ... More ideas are likely to turn up in class over the course of the project.

Tasks:

Pay attention and take notes in class, as more details will be given there than are written down here.

1. Form a team, and tell me who are your teammates. Be certain that the team members have compatible schedules, since you will need to communicate a lot. Meet and decide how you will first divide the work. Plan on revising this work breakdown repeatedly as you make progress and understand the task better. Do this by the end of the 3rd week of class.

2. Read the relevant references (see links below for the video frame grabber, and find your own references if you are working on a different device).

3. If you are working on the frame grabber, you should try to get one of the drivers from a prior term up and running, with a demonstration program, by the middle of the 4th week. If you are doing another driver, you should get the device up and running with whatever other driver may exist for it (either an existing Linux driver, or if there is no Linux driver then a Windows driver).

   Read through the existing driver code, if such is available, and design your changes; otherwise, if you are starting from scratch, design your driver.

   Submit short a document describing your design, and demonstrate that you have the older driver and demo program (if any) working, on Monday of the 5th week. Give a 5-10 minute presentation of your team's plans in class that day. It would be best if you have Web-readable notes to go with your presentations.

4. By the end of the 5th week of the course, develop a working prototype, with at least some of the (new) functionality you have planned. Give a team presentation on this in class that Friday.

5. Spend the 6th (last) week of the course refining your driver, and writing up the documentation. Plan on giving an extended team presentation and demonstration in class on Thursday or Friday of that week.

Advice:

• I intend for you to follow an incremental and iterative development approach on this assignment. That is, you will start with an overall design of where you want to go with the driver, but develop it in stages. You will produce successive "releases" of the driver. Each release will provide a bit more functionality. This way you can code, test, and debug in small chunks. That way you should always have something that is at least partially functional, and will be continuously improving it. By coding and testing in stages you verify that you understand what you are doing before you have written a lot of new code. Inevitably, you will discover that you made some mistakes in your early design, but you will have a chance to revise your plans before you have written out a huge amount of code, and so reduce the amount of rewriting you need to do. If you run out of time, you should always have something that is at least partially functional to turn in.

• For this incremental approach to work, source code control is critical. If an incremental changes turns out to be a bad idea, you need to be able to roll back to the previous version.

• Take advantage of having a team by doing code design and walk-throughs. One person writes down a piece of the design, and later of the code. The others read it, ask critical questions, and make suggestions for improvements. You then reverse roles.

• Dividing up the work among the team members will be a challenge. To make effective progress you need to either work very closely together, or split up the work into pieces that are sufficiently independent that they can be done in parallel. One tempting way is to split off the documentation from the coding, and the development of tests from the development of the device driver itself. I recommend against this, at least at first. If one person does all the coding and debugging, that person will do most of the learning. That person will also make mistakes that go undetected because only one pair of eyes and one mind are looking at the code critically. A person who writes documentation only will risk not writing it correctly, from lack of understanding. I would recommend doing nearly everything "hand in hand" up to a point where you have a working framework and everyone understands it. You can then assign different individuals to add more methods, and more options/parameters to the methods. For the documentation, I suggest you together develop an outline, have each person draft a portion of the document, and then each swap pieces to do the editing, until everyone has approved every line of text.

• As in the previous assignment, you are free to work out the unspecified details, according to your own best judgement, but remember that the quality of such decisions will be taken into account in the assessment of your work. Always keep in mind the objectives of the assignment. You are trying to make a useful device driver, good enough that other people will use it. This means not just good in functionality, but easy to compile and install, and compatible with all kernel versions currently in use. When you make design choices, choose in the direction of providing greater efficiency, functionality, portability, and convenience for users. There may be ways you can reduce the amount of work you have to do, at the expense of some other consideration. If you chose that path, do so with the understanding that you may also reduce your score. If you have doubts or questions, ask me . If you bring up issues that I think are of general interest to the class I will post them on the course web pages so that other students may also benefit.

• Get started right away. You don't have long to do it.

References:

The following references may be augmented during the course of the project.

• class notes on this subject

• hrt resource directory, containing drivers produced by students in Summer 2003 and 2004, along with various files provided by the frame grabber manufacturer

• http://linuxtv.org/v4lwiki - Video for Linux Wiki

• http://www.videouniversity.com/engineer.htm - general introduction to video terminology

• http://en.tldp.org/HOWTO/XFree86-Video-Timings-HOWTO/index.html - instructions on how set up timing parameters for a Linux video display driver. (This is described from the point of view of a display driver, a video output device, and you are working on a frame grabber, which is a video input device. The direction of transmission is different, but the nature of the signal is the same.)

Delivery Method:

1. Please follow instructions given in class for details, including turn-ins and reviews of intermediate results at the end of each week.

2. Your team will be expected to give a final presentation and demonstration of your project in the last two days of classes.

3. Each person is required to individually provide me with a signed sheet of paper indicating your estimation of the percentage contribution of each team member to the project, something like this:

   Your name:
   	member #1	member #2	member #3
   Team member name
   Percentage contribution

4. Before the final grade is turned in, each team is required to turn in a tar archive of the team web page, including:

   1. The names of the team members
   2. A description of your project goals and accomplishments.
   3. A journal of your progress
   4. The code that you wrote, including any test programs.

Assessment:

Your work will be judged according to quality of function (including the number of the deficiences of the older driver mentioned above that you correct), quality of design, quality of coding, quality of testing, and quality of documentation.

Quality of coding will include (but need not be limited to) consideration of simplicity, readability, portability, efficiency, and robustness.

The documentation includes not just comments in the code, but also the user-level documentation (how an application uses the driver).

Your design should provide access to all the functionality of the hardware, and also make the device as convienent to use as you are able.

You may be asked to demonstrate the installation and compilation of your software "out of the box" on an "out of the box" Linux distribution.