CSC 352 – Project 5: /dev/cards
Due: Wednesday, May 6, 2020, at 11:59pm
Project Description
In this project, we will perform our first alteration of how Linux works by writing a specific implementation of the read() system call for a device which we will make up and emulate in software. We
can see the system calls of our OS as a device-independent interface that user space programs can use to request the OS do various task we are not permitted to do ourselves. As we have seen,
we can read and write all sorts of “files” like stdin and stdout. How does the OS know to turn our write request into the proper commands to draw text to the screen as opposed to changing file data
on a hard drive? The OS uses the passed file descriptor to determine which implementation of the read system call it should invoke. The multitude of implementations of system calls like read() and
write() live in software modules called device drivers.
What we need then is a filename (so we can open it and get a file descriptor) that represents our device. The /dev virtual filesystem holds “fake” files that represent hardware devices attached to
our system. Sometimes these files do not even represent “real” hardware devices. Standard UNIX and Linux systems come with a few special files already like /dev/zero, which appears to be filled
with an infinite number of zeros when it is read, and /dev/random, which yields random bytes. In this project, you will write a device driver to create a new device, /dev/cards which yields random card
values from a shuffled deck.
How It Will Work
For this project we will need to create three parts: the device driver, the special file /dev/cards, and a test program to convince ourselves it works
The test program will be a solitaire implementation of the game of blackjack.
Driver Implementation
Our device driver will be a character device that will implement a read function (which is the implementation of the read() syscall) and returns via the buf parameter, the requested number of card
deals (each a 1 byte value from 0 to 51). Make sure that each card is dealt from the deck until the deck is exhausted. When the deck is exhausted, “shuffle” a new complete 52-card deck to use for
further card deals.
The kernel does not link against the full C Standard library due to not using most of its functionality and parts of it being implemented via system calls whose job we said it was to take us from
userspace into the kernel. Well, we’re in the kernel already.
Practically, this means we will need to get use different functions to do some common tasks, like printing (for debugging) or to get random numbers. By #including
we can use the
function get_random_bytes(), which you can turn into a helper function to get a single byte:
unsigned char get_random_byte(int max) {
unsigned char c;
get_random_bytes(c, 1);
return c%max;
}
To print, we may not use printf(), but instead the kernel provided an equivalent function, printk(). The arguments of a format string and values to interpolate are the same. What is different is the fact
that the kernel doesn’t like printing to the screen when other code is running, so by default we will not see the output of our printk()s unless we use the dmesg command to examine a message log file.
We can tell the kernel what we are printing is really important by prefixing our format string with various values, the most urgent is KERN_ALERT:
printk(KERN_ALERT “Hello, World!\n”);
Will show our message on the screen immediately. When we are done debugging, our driver should have no printk()s in it, so make sure to remove them.
Blackjack Solitaire Implementation
Blackjack is normally a two-player card game, with fairly simple rules. For this assignment, you will be implementing a solitaire version where a user plays a version of the game by themself.
For our game, 5 piles will be available for the player to place a card in. Show a card to the player and have them choose which pile to place the card in. A card can be placed in any pile so long as
the new pile total will not exceed 21 points.
Each card is worth its face value, except for face cards (K, Q, J) that are all worth 10 and aces (A). Aces are worth either 11 or 1. Have your program automatically determine the proper value of an
ace in the pile by initially assuming it is worth 11 points, until the total of the pile exceeds 21. Then reduce the ace to be worth 1 point.
When placing a card in a pile, check for and score the following events:
Event Score
Blackjack (pile total is 21) +21 points
Natural blackjack (pile total is 21 with 2 cards) +35 points
Clearing the board (all piles are empty after the game has begun) +45 points
Cleared the deck (Dealt all 52 cards, repeatable) +60 points
“Five Card Charlie” (a pile contains 5 cards that are less than 21) +total points in pile
When blackjack, natural blackjack, or a 5-card Charlie occurs, clear that pile.
Example Run:
Score: 0
Pile (1): = 0
Pile (2): = 0
Pile (3): = 0
Pile (4): = 0
Pile (5): = 0
Drawn Card: K
Which pile to place card in? 1
Score: 0
Pile (1): K = 10
Pile (2): = 0
Pile (3): = 0
Pile (4): = 0
Pile (5): = 0
Drawn Card: 3
Which pile to place card in? 1
Score: 0
…
Pile (1): K 3 = 13
Pile (2): = 0
Pile (3): 6 = 6
Pile (4): 9 2 = 11
Pile (5): A = 11
Drawn Card: 8
Which pile to place card in? 1
Blackjack! +21 points
Score: 21
Pile (1): = 0
Pile (2): = 0
Pile (3): 6 = 6
Pile (4): 9 2 = 11
Pile (5): A = 11
Drawn Card: 2
Which pile to place card in? 1
The game ends when there is no place to play the next card without exceeding 21 points.
Implement high score tracking by using a text file named “highscore.dat” that simply has the previous high score. If the file does not exist, assume the high score is 0.
When the game ends, display the final score and indicate if this is an all-time high score by comparing to the file’s value, and updating the file if necessary.
For this assignment you need to do the following:
· Write a program that allows a player to play blackjack solitaire according to the rules above
· Gets a card to display by reading in from the /dev/cards file.
· Allows for any other program to use /dev/cards by not making any assumptions as to the range of cards or the number being requested per read
Blackjack Hints and Suggestions
You may write the blackjack program using stdlib’s rand() for testing, but make sure you eventually replace it with reads of /dev/cards
Installation and Example
1. We will be reusing the VM image from project 4 since you need to be an administrator to install drivers.
2. Once again, you log in with the username of root and a password of root
3. Download the following two files from lectura, replacing USERNAME with your username:
scp :~jmisurda/original/Makefile .
scp :~jmisurda/original/hello_dev.c .
4. Build the kernel object:
make
5. Load the driver using insmod:
insmod hello_dev.ko
6. When we load the driver, the udev system of Linux will automatically create the “fake” /dev/hello file. We can now read the data out of /dev/hello with a simple call to cat:
cat /dev/hello
7. You should see “Hello, world!” which came from the driver. We can clean up by unloading the module (removing the device):
rmmod hello_dev.ko
What to Do Next
The code for the example we went through comes from http://www.linuxdevcenter.com/pub/a/linux/2007/07/05/devhelloworld-a-simple-introduction-to-device-drivers-under-linux.html?page=2 which
I’ve mirrored at: http://www.u.arizona.edu/~jmisurda/teaching/csc352/valerie-henson-device-drivers-hello.pdf Read that while going through the source to get an idea of what the Module is doing.
Start with the third section entitled “Hello, World! Using /dev/hello_world” and read up until the author starts describing udev rules; we will only run our code as root, avoiding this issue.
When you have an idea of what is going on, copy and rename the hello_dev.c from the example, and copy over the Makefile. Edit the Makefile to build your new file. Change all the references of “hello”
to “card_driver”.
Building the Driver
To build any changes you have made simply:
make
If you want to force a rebuild of everything you may want to remove the object files first:
rm *.o
Copying Files In and Out of VirtualBox
Once again, you can use scp (secure copy) to transfer files in and out of our virtual machine.
You can backup a file named hello_dev.c to your private folder with:
scp hello_dev.c :private
Backup all the files you change under VirtualBox to your ~/private/ directory frequently!
Loss of work not backed up is not grounds for an extension. YOU HAVE BEEN WARNED
Loading the Driver into the Kernel in VirtualBox
As root:
insmod card_driver.ko
Driver Requirements and Hints
The provided hello world example sometimes assumes too much about the parameters it was given. You should not necessarily enforce all of the constraints it does. The parameters are:
· buf is our output (in the algorithmic sense) – it is where we will place the requested card deals
· count is the number of card deals we’ve been asked to produce. buf is promised to be at least count bytes in size.
· *ppos represents the file pointer (the generic concept, not the FILE * type from C). The file pointer is where the next sequential read or write should take place, so we do not reread data
we have already. Note that we have a C pointer parameter that is not pointing to some large allocation we’re trying not to copy, so it must be that this is mean to be an algorithmic output
as well (i.e., you must update *ppos).
Like most of the C Standard Library functions, system calls return an integer whose value is interpreted as success or failure. A negative value always means failure, but positive numbers
mean different things for different functions and syscalls. For read, success is defined to be that you were able to read as much data as you were asked for. If you return less than this, the OS
interprets your return value as indicating the End Of File was reached on that read, and will never call your read function for that open file again.
printk() is the version of printf() you can use for debugging messages from the kernel.
In the driver, you can use some standard C functions, but not all. They must be part of the kernel to work.
In the blackjack program, you may use any of the C standard library functions.
As root, typing poweroff in VirtualBox will shut it down cleanly.
If anything goes so wrong that the virtual machine doesn’t work, just replace the disk image with the original from the downloaded zip file and start over. It’s why we’re developing in a virtual
machine as opposed to a real one.
Requirements and Submission
You need to submit:
Your card_driver.c file and the Makefile
Your well-commented blackjack program’s source
Anything else necessary to build or grade your project
We will use the turnin program on lectura to turn in your project. If your files are named card_driver.c, blackjack.c, and Makefile execute the following command from lectura in the directory that
contains them:
turnin csc352-fall2020-p5 card_driver.c blackjack.c Makefile