CS 453: Operating Systems Programming Project 5 (100 points) Linux Device Driver 1 Setup In this assignment, we will write a simple character driver called booga. Please do a git pull --rebase in your backpack to get the p5 project folder that contains the starter code and scripts for this project. Note that, you will only be able to test this assignment on your own VM as you will need to have root access. 2 Caution NOTE: You MUST build against the Kernel version specified in class. If you are unclear what version to build against please ask do NOT just assume. The only time you will need to use root in this project is to load and unload the drivers. You should not use the root account for building, test, etc. 3 The Booga Driver 3.1 The main driver (60 points) The booga driver is a simple character driver that supports the open, read and write operations. The driver supports four minor numbers: 0, 1, 2, and 3. The device files are: /dev/booga0, /dev/- booga1, dev/booga2, /dev/booga3. You can also create a link from /dev/booga to /dev/booga0. On reading from /dev/booga0, /dev/booga1, /dev/booga2 and /dev/booga3 the driver gives a stream of one of the following phrases: booga! booga! googoo! gaagaa! neka! maka! wooga! wooga! Note that the driver may only output part of a phrase if the number of bytes requested by the user is not a multiple of the length of the chosen phrase. Also each new phrase is separated from the previous one by a single space. The driver is unpredictable as to what phrase it says. In order to do this we will use a random number generator. However, we cannot call any standard C library functions in the kernel (e.g.
random()). Linux actually has a device driver that generates strong random numbers by observing hardware noise, interrupts and other system activity. In the user space, the random device driver can be accessed via /dev/random. In your device driver code, you will need to include the header file <linux/random.h and the function that you will call has the following prototype. extern void get random bytes(void *buf, int nbytes); Here is a sample code on how to use the above function. char randval; get_random_bytes(&randval, 1); choice = (randval & 0x7F) % 4; /* the bitwise AND is to guarantee positive numbers */ On writing to booga devices /dev/booga0, /dev/booga1, /dev/booga2, the booga device driver works like /dev/null (so it pretends to write the buffer but doesn t actually write to any device). However if a process tries to write to /dev/booga3, it suffers from sudden death! You cannot call the system call kill() from inside the kernel space so you will have to figure out how to terminate a process from inside the kernel. Search the kernel sources for ideas. Use the SIGTERM signal instead of SIGKILL for terminating the process. 3.2 Get Booga Stats from /proc (10 points) Create /proc entries for the booga driver. It reports on the number of bytes read/written since the driver was loaded, number of times it was opened from each supported minor number, and the number of times each of the four strings was selected. So if we output 1000 characters with the string booga! booga! in it, then we count that as one more instance of the phrase for this purpose. If the driver outputs an incomplete phrase, we will still count it as another instance of that phrase being selected. Here is a sample output. [amit@kohinoor booga]# cat /proc/driver/booga bytes read = 300 bytes written = 200 number of opens: /dev/booga0 = 4 times /dev/booga1 = 0 times /dev/booga2 = 1 times /dev/booga3 = 1 times strings output: booga! booga! = 0 times googoo! gaagaa! = 1 times wooga! wooga! = 1 times neka! maka! = 1 times 3.3 Thread-safety (10 points) Protect the updating of structure used to track the statistics using semaphores. See the example in lab/device-management/linux-device-drivers/example4 for an example on how to use a 2
semaphore in kernel code. 3.4 Testing (20 points) For testing, use the provided test-booga.c program, which lets you read or write n bytes from the booga device. Develop and use a plan for fully testing your driver and document it as part of your submission. 4 Notes Here are the prototypes of the functions that your driver would need to implement. static int booga_open (struct inode *inode, struct file *filp); static int booga_release (struct inode *inode, struct file *filp); static ssize_t booga_read (struct file *filp, char *buf, size_t count, loff_t *f_pos); static ssize_t booga_write (struct file *filp, const char *buf, size_t count, loff_t *f_pos); static int init booga_init(void); static void exit booga_exit(void); Note that the print messages will not show on the screen if you are testing under X Windows. The messages are, however, logged in the file /var/log/messages. You can open another terminal and watch the output to the system messages file with the command: tail -f /var/log/messages Another approach would be to invoke a virtual system console. following keys: Ctrl-Alt-F2 to use a virtual test console Ctrl-Alt-F1 to go back to the X Windows console In the virtual system console, the system messages will show up on screen. Under Linux, you can use the In the directory linux device drivers/booga, I have provided a test program called test-booga.c. You should use this program to test your driver. While testing your program, the following situations may arise: The system hangs and you have to hit the reset button. The system spontaneously reboots. Oops! The kernel prints an oops message (a milder version of the infamous General Protection Fault). You will get a stack trace with it that should help in narrowing down the cause. Here is a sample session with the booga driver. Note that the characters returned by the driver do not contain any newline characters. The output shown below was modified to fit the width of this page. 3
[amit@kohinoor booga]# ls Makefile booga.o booga_unload main.o test-booga booga.h booga_load main.c oops test-booga.c [amit@kohinoor booga]# sudo./booga_load [amit@kohinoor booga]# /sbin/lsmod Module Size Used by booga 1172 0 (unused) nfsd 144060 8 (autoclean) lockd 30984 0 (autoclean) [nfsd] sunrpc 52516 0 (autoclean) [nfsd lockd] 3c59x 19112 1 (autoclean) opl3 11208 0 (unused) sb 33620 0 uart401 5968 0 [sb] sound 57240 0 [opl3 sb uart401] soundlow 300 0 [sound] soundcore 2372 6 [sb sound] [amit@kohinoor booga]# test-booga 0 100 read neka! maka! neka! maka! neka! maka! neka! maka! neka! maka! neka! maka! neka! maka! neka! maka! neka [root@kohinoor booga]# test-booga 0 100 read wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wooga! wo [amit@kohinoor booga]# sudo./booga_unload [amit@kohinoor booga]# /sbin/lsmod Module Size Used by nfsd 144060 8 (autoclean) lockd 30984 0 (autoclean) [nfsd] sunrpc 52516 0 (autoclean) [nfsd lockd] 3c59x 19112 1 (autoclean) opl3 11208 0 (unused) sb 33620 0 uart401 5968 0 [sb] sound 57240 0 [opl3 sb uart401] soundlow 300 0 [sound] soundcore 2372 6 [sb sound] [root@kohinoor booga]# Here is a sample write session. [amit@kohinoor booga]: test-booga 4
Usage: test-booga <minor number> <buffersize> <read write> [amit@kohinoor booga]: test-booga 0 100 write Attempting to write to booga device Wrote 100 bytes. [amit@kohinoor booga]: test-booga 1 100 write Attempting to write to booga device Wrote 100 bytes. [amit@kohinoor booga]: test-booga 2 100 write Attempting to write to booga device Wrote 100 bytes. [amit@kohinoor booga]: test-booga 3 100 write Attempting to write to booga device Terminated [amit@kohinoor booga]: 5 Recommended Plan You may find it easier to start from one of the driver examples from the linux driver examples folder. Define the file operations struct (similar to the example driver). Define booga init and booga exit. Let the booga read, booga open, booga release functions be stubs for now. Compile and check if you can load and unload the module successfully. Now decide how you will represent the booga device. One way is to define a struct that keeps track of some of the information. typedef struct Booga_Dev { char *data; unsigned int number; /* minor number */ } The space for this structure would need to be allocated (typically in booga init()). The data points to a buffer that is allocated and filled in booga read(). Remember that you need to use the user space. Do not use memcpy(). copy to user(...) kernel function to copy the data to Test the writing part of the booga driver separately and as the last step. 5
6 Required files for submission Make sure to include a README file that contains your name, date, assignment number and observations about the assignment. The test plan can be part of the README file or in a separate file that you mention in the README file. Please submit the files below. README Makefile booga.c booga.h booga load booga unload test-booga.c Additional test scripts or programs that you may have created 7 Submitting the Project Open up a terminal or console and navigate to the backpack folder for the class. Navigate to the subdirectory that contains the source files that you worked on for the project/homework. Suppose that we are submitting three files README.md, main.c and utility.c and one folder named include. Clean up your directory make clean Remove any other unnecessary files that were generated by you or the auto-grader. Add all your changes to Git (this would be specific to your project) git add main.c utility.c include/ README.md Commit your changes to Git git commit -a -m "Finished project p5" Create a new branch for you code git branch p5_branch Switch to working with this new branch git checkout p5_branch (You can do both steps in one command with git checkout -b p5_branch ) Push your files to the Backpack server git push origin p5_branch Switch back to the master branch git checkout master Here is an example workflow for submitting your project. Replace p1 with p5 in the example below. [spanter@valkyrie shane(master) ]$ git checkout -b p1_branch Switched to a new branch p1_branch 6
[spanter@valkyrie shane(p1_branch) ]$ git push origin p1_branch Total 0 (delta 0), reused 0 (delta 0) To git@nullptr.boisestate.edu:shane * [new branch] p1_branch -> p1_branch [spanter@valkyrie shane(p1_branch) ]$ git checkout master Switched to branch master Your branch is up-to-date with origin/master. Help! I want to submit my code again! No problem just checkout the branch and hack away! [spanter@valkyrie shane(master) ]$ git branch -r origin/head -> origin/master origin/master origin/p1_branch [spanter@valkyrie shane(master) ]$ git checkout p1_branch Branch p1_branch set up to track remote branch p1_branch from origin. Switched to a new branch p1_branch [spanter@valkyrie shane(p1_branch) ]$ touch foo.txt [spanter@valkyrie shane(p1_branch) ]$ git add foo.txt [spanter@valkyrie shane(p1_branch) ]$ git commit -am "Adding change to branch" [p1_branch 1e32709] Adding change to branch 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 foo.txt [spanter@valkyrie shane(p1_branch) ]$ git push origin p1_branch Counting objects: 3, done. Delta compression using up to 4 threads. Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 286 bytes 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) To git@nullptr.boisestate.edu:shane 36139d1..1e32709 p1_branch -> p1_branch [spanter@valkyrie shane(p1_branch) ]$ git checkout master Switched to branch master Your branch is up-to-date with origin/master. [spanter@valkyrie shane(master) ]$ We highly recommend reading the section on branches from the Git book here: Git Branches in a Nutshell 7
8 Reference Linux Device Drivers, 3rd edition by Alessandro Rubini and Jonathan Corbet (O Reilly, www.ora.com). Can be downloaded from the Internet. You may find the material from the first three chapters useful for this assignment. 8