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

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

Summary:

This is your second exercise that involves writing and debugging code. The main new feature is that you will need to use the kernel timer and/or tasklet mechanism to schedule periodic output. You will be writing a new device driver, that uses the parallel port to drive a 7-bar LED display device. You may look for inspiration and bits of reusable code in the examples provided by the textbook author, such as jit, jiq, scull, scullp, and short.

• Read and comprehend an existing parallel port driver.
• Experience interfacing directly to real hardware.
• Improve your skill at testing and debugging your own kernel module code.
• Learn how to implement periodic polling behavior in a device driver, using a tasklet and/or kernel timer.
• Apply mutual exclusion and synchronization methods.

Tasks:

1. Find the source code for the short driver.

2. Attach one of the LED test devices provided in the lab (similar to the one described on page 246 of the text under "An I/O Port Example" — see description below) and attach it to the 25-pin parallel port D-connector of the machine on which you are working.

3. Use the provided makefile to compile the original version of short, and test it, as described on pages 246-248 under "A Sample Driver" in the text and demostrated in class.

   Check that all the LEDs on the device are working.

4. Using any relevant bits of code you like from short, write a new device driver of your own, called ledtimer, that displays a coundown timer on the LED test device. The idea is that you initialize the device to a time value and it then starts counting down. When it reaches zero it wraps around and reinitializes to the last value to which you set it. Since the hardware can display only one digit at a time, the driver must sequence through the digits from beginning to end, pause, and then repeat.

   The time value should be displayed in seconds. For example, a remaining time of 12 seconds should be displayed as "12  " and then (ideally) one second later should change to "11  ". The spacing is intended to indicate that there should be a short pause on each digit and a longer pause before repeating the time. At lower speeds (see variable speed below) it will take longer than one second to complete the digits than one second, so you may skip some output values.

   The initial value of the timer is set by the user doing a write operation to the device.

   Besides displaying the time, your driver should allow reading and writing the timer value (as a 16-bit integer) using the read and write methods. (Since read() and write() take char * parameters, this will involve type-casting between char * and unsigned short *.) The value copied into the user-provided buffer by read should be the full value that is currently displayed if the value of the count parameter of read is greater than or equal to 2, and just the low order byte if the value of count is one. The value provided by write should be used to reset the value of the clock. Once set, the clock should resume advancing as before.

   There will be some timing parameters, including how long the LED stays on (dwells) for each digit, and the durations of the pause between successive time values. You should provide a compile-time configurable default symbol for all such parameters, plus a driver parameter for start-up time configuration, and finally an ioctl command to allow the dwell and pause values to be changed at run time.

   The device should start up blank, and stay blank until a value is written to the timer. You should provide and ioctl call to start the device displaying, and one to stop it. Similarly, you should provide an ioctl to start and stop the timer from counting down. You may play with other ioctl commands for additional features.

   There may be wiring differences between the various LED devices that cause differences in the correspondence between bit positions in the output byte and LED element positions in the display. Therefore, instead of hard-coding the correspondence of digits to display bytes, it would be better to use a table and provide a way to replace the default table by a custom one via an ioctl call.

   Of course, you will need to implement init_module, cleanup_module and the other required methods, including open and release.

   Your cleanup_module method will need to stop the display tasklet/timer handler from rescheduling itself. This could be done by cancelling it, or you could write a flag that tells it not to reschedule, and then block in release until the tasklet/timer handler executes one last time.

   If you start from short be sure to put your own name and comments in, and delete any unused code, before you turn in your assignment.

5. Test and debug your modified code. You should devise your own tests.

Advice:

• The incremental development approach would work well for this assignment. That is, develop it in stages and test each of the stages as you go. For example, you could start out with just enough to statically display one digit (e.g. a few functions such as the init_module, cleamup_module, open, release, and write methods from short.c). You could then add a periodically rescheduled timer or tasklet to update the digit displayed. You could then add in the code to read and write the timer value, and to convert between 16-bit binary and a displayable sequence of digits. You could then add in some ioctl functions, etc. At each stage you add in a bit of functionality, test it, and debug it. That way you always have solid foundation, and verify that you understand what you are doing before you have written a lot of code. If you run out of time, you always have something that is at least partially functional to turn in.

• You are free to work out the unspecified details, according to your own best judgement. However, please note: The quality of such decisions will be taken into account in the assessment of your work. Keep in mind the objectives of the assignment. You are trying to make a useful device, as well as to develop your knowledge and skills in writing Linux device drivers. When you make design choices, choose in the direction of providing greater functionality and convenience for users, and in the direction of using more of the techniques we have been studying. If you have doubts, discuss design decisions with me. If issues that seem to be of general interest to the class come up in such discussions, they will be e-mailed or posted them on the course web pages so that other students may also benefit.

• Take care with code for shutting down timers, including both explicit shutdowns via IOCTL and implicit shutdowns via release() or module removal. If this is not done right, there is a possibility of a timer re-arming itself after you think you have stopped it. Be especially careful if you decide to use more than one timer, or a tasklet and a timer.

• Get started right away. You have only one week to do it.

• If you encounter problems, please ask for help, either in the lab after class, by e-mail, or by telephone.

• If you run into problems, let me know. I will try to help. If we learn something that may be useful to the entire class I will send the entire class an e-mail with the information.

References:

• short example, for code to put a value out to the parallel port.
• jiq.c, for code to use kernel timers and tasklets

Delivery Method:

1. Turn in the following, as hard copy, in class on the due date:

   • Copies of the files that you modified, with the parts you modified pointed out in some clear way (e.g. marked colored highlighter).
   • Copies of test scripts and/or programs you used.

2. Also e-mail Ted Baker the electronic copies of the above. For simplicity, please send a uuencoded gzipped tarfile. If your code is in directory prog3, you can do this on a Linux machine that supports mail (e.g., quake) as follows:

   tar cvpf - prog3 | gzip -c | uuencode prog3.tgz | mail -s "prog3" baker@cs.fsu.edu

   This uses tar to create an archive, which it pipes for compression to gzip, which pipes the compressed file to uuencode for conversion to ASCII characters, which pipes it to mail < named "prog3.tar".

   The code above worked fine on websrv, and it should work equally well on other Linux boxes that support e-mail, but if you are doing this on a Solaris machine (do we have any of those left?) you will either need to leave out the -s "prog3" argument to mail, or use mailx instead. You may also need another argument for uuencode.

   The electronic copy can be later than the hard copy, but be sure to bring a hard copy and the demo for evaluation purposes. The electronic copy is mainly for archival purposes, including accreditation. The outside reviews always ask for copies of student work in each course.

3. In class, on the due date, sign up of a time slot to demonstrate your code.

The LED Device:

For this exercise you will need a hardware device to connect to the parallel port of your machine, similar to the device described in the text, in the section under the heading "A Sample Driver". There will be almost enough of these devices for all the machines in the lab. As an alternative, you can construct a device of your own using parts that you can buy from from Radio Shack.

If you are working at home and want to check out one device for your personal use, please see me to sign an accountability form. The other devices should be left in the lab.

If you are interested in making your own unit, here are the parts we used:

• a "printer cable" having "male" 25-pin D connectors on each end
• a 25-pin female D connector
• an 8-element LED digital display module (has seven bar elements, plus a decimal point)
• one 150-ohm resistor
• a socket to hold the LED module
• a small piece of perf-board to hold the components
• glue, solder, a soldering iron, small bits of wire

You use the perfboard, solder, and wire to hook up one of pins 2-8 of the 25-pin connector to each of the seven pins of the LED bars. You then hook up pin 20 of the 25-pin connector to the common (ground) connector of the LED display, with the 150 Ohm resistor in between. The 25-pin connector is plugged into one end of the parallel cable, and the other end goes into the computer. The hardest part is finding a 25-pin connector and attaching it to the perfboard. If you are doing this yourself you can attach a cable-end 25-pin connector to the perfboard with wires. If you do this, consider using thread to sew down the wires to the board for strain relief, or the solder connections will break. You can look at the various examples in the lab for details.

Assessment:

Your work will be judged primarily on well it performs during the demonstration, and how well you can explain what you did. Remember that the development of tests is part of the assignment. I will also ask you to show me through the code, and explain it. The ideal is for your code to be as simple as possible, for the functionality you implement. Including unused or inappropriate bits of code from the examples in the text will be interpreted as an indication that you either were not willing to make the effort to delete useless code, or that you do not understand the code well enough to decide what is needed and what is not. The latter pitfall is sometimes called cargo-cult programming.

When you demonstrate your code you should expect to show at least the following:

• When it starts up the display should be blank.
• When you write a time to the device, it should begin displaying the time, in a circular fashion, with a blank pause at the end before it cycles around and counts down to the next value.
• It should wrap around to the last set value, after displaying zero.
• You should be able to read back the time, as a 16-bit binary integer, from the device.
• You should be able to change the speed of the display, so that it sequences through the digits faster and slower.
• You should be able to pause and restart the timer
• You should be able blank the display (and stop any kernel timers and/or tasklets) without removing the driver, via ioctl()x.
• After completion of rmmod the device should become blank.

You will also be asked to show where, in your code, you provide for the following:

• Appropriate control over timing. (In the past, some students have failed to use an appropriate kernel scheduling mechanism, and have instead tried to code this using a loop.)
• Protection of critical sections, of two kinds:
  1. Between multiple user processes accessing the device (e.g, for open, read, write, ioctl, release)
  2. Between a timer/tasklet and a user process
  3. Between multiple timers/tasklets if you have more than one. (It is strongly recommended that you have only one.)
  (In the past, many students have forgotten to protect some critical sections, or used the wrong kind of lock, e.g., a semaphore where a spinlock is needed, or vice versa.)
• Safe shutting down of any kernel timers or tasklets you are using, without races. (For example, in the past, students have often gotten into a race between the shutting down of a kernel timer and the timer rescheduling itself. This is more likely to be a problem if you have more than one, so try to design to use only one.)

More items may be added to the above check-list, in response to e-mails and in-class discussions.