Specifications

Building the Driver:
The mp2/module directory contains a framework for the driver you will be implementing for the Tux controller. A
module is similar to a dynamically-loaded user-level lib rary but instead of being used by an application it is used by
the kernel to extend functionality. Modules allow for dr ivers to be loaded without having to reco mpile (or even reboot)
the whole kernel. This simplifies the pr ocess of debugging as well. Modules can also be unloaded and a new version
loaded into the kernel assuming that nothing catastrophic happened tha t would crash the kernel. Your driver code, of
course, is running in the kernel, and bugs th a t are severe enough to crash the kernel are not impossible to produce.
The module directory uses a separate Makefile to compile a device driver module fo r use with Tux controller, thus
building a module is similar to building a user level program: Change directories in to the module d irectory and type
make.
To load the module into the kerne l, type sudo /sbin/insmod ./tuxctl.ko while in the modu le directory. A line
should print out saying the tuxctl line discipline has been registered. You can safely ignore the “module license
‘unspecified’ taints the kernel” message.
1
If you want to remove the module, issue the sudo /sbin/rmmod tuxctl command. This removes the module
from kernel space and should print a line stating the tuxctl line discipline was removed. You can use these commands
to install and remove the kernel module repeatedly during your development. If your mo dule corrupts the kernel,
however, you may eventually crash the system and have to reboot. If all else fails, try rebooting the test machine and
then loading your module to see if it is r eally your latest code that is failing.
The module we have given you implements a tty line discipline. A line discipline is a driver that receives commands
from the tty or serial port driver. In other words, it acts as a middle man between the serial port and the cod e you
will imple ment to actually interpre t the Tux c ontroller commands. The code you will be implementing is in the
tuxctl-ioctl.c file. You may add anything you deem necessary to the header files to make your implementation
work. We also recommend you look at the mtcp.h file for a description of how the Tux controller works and some
predefined constants, and at the appendix at the end of this document.
Writing Your Driver:
You will write portions of both the device driver which communicate s with the Tux c ontroller and the user-level
application code to make use of the driver. On the driver side, you will need to add c onstants and definitions for
the abstracted bit format to the header file. These constants (located in tuxctl-ioctl.h) will shared by the kernel and
user-level code, ensuring that no inconsistencies arise. There is no user-level test harness for MP2. We advise you to
write a simple test program to test your driver outside the game. We suggest that you write a test progra m to test the
basic functionality (open, close, ioctls) bef ore trying to make the game use the dr iver. We have provided input.c as
a starting point for your user-level testing. To compile input.c type make input. We will test your driver with our
own testing code, so b e su re to test your d river’s functionality thoroughly and adhering strictly to the spec. For the
checkpoint, you must add the Tux controller functio ns (op en, ioctls, close) to the input control in input.c and test it
by compiling the file by itself. You will need to include tuxctl-ioctl.h. Only once you have debugged you r input
control completely as a stand alone pro gram sh ould you try it with the full game. To interface with the game you will
need to create a new thread to take input from the Tux controller (you must support keyboard input simultaneously.
Opening the Tux controller is fairly simp le . You may use the following code as an example to ope n the serial port and
set the Tux controller line discipline:
fd = open("/dev/ttyS0", O
RDWR | O NOCTTY);
int ldsic num = N MOUSE;
ioctl(fd, TIOCSETD, &ldisc
num);
This code simply opens the tty port and sets the line discip line. You will want to add some error checking and whatever
else you see fit to make this work with your co de.
What Your Driver Has To Do:
Your device driver transforms the protocol supported by the Tux controller into a simpler abstraction for use by user-
1
This simply indicates that the module you have loaded has not been designated as GPL and therefore taints the kernel so don’t try to submit
any bug reports to Linus.