Download hw1_wet

Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)
Homework Wet 1
Due date: Sunday, 17/11/2010, 12:30 noon
Teaching assistant in charge:
Nir Hershko
E-mails regarding this exercise should be sent to [email protected]
with the subject line: cs234123hw1_wet (pay attention that the email address
is cs234120 and not cs234123).
Introduction
Your mission in this assignment will be to add a new system calls to the
interface of the kernel, and to update some internal structures. While doing
so you will gain extra knowledge in compiling the kernel.
Also in this exercise, we will use VMware to simulate a virtual machine on
which we will compile and run our "modified" Linux. You will submit only
changed\added source files of the Linux kernel.
General Description
In the last Mine-Sweeper AI championship, it was discovered that some
participants have cheated and directly accessed the location of the mines in
the process' memory.
Your task in this exercise is to implement the game in the kernel, so that no
user process will be able to access the data.
In the following section you will find a detailed description for what your
mission is.
Detailed Description
First, get acquainted with the game's rules. See
http://en.wikipedia.org/wiki/Minesweeper_(computer_game) for details.
Some definitions / clarifications regarding this exercise:

A minesweeper game is considered "won" if all of the cells without
mines were revealed. The game is considered "lost" if a cell with a
mine was revealed. In both cases, the game is considered "finished".

Every game is assigned to a process, and every process can have at
most one game – every process is either "running a game" or "not
running a game".
1
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)

You don’t need to de-allocate the game information until the process
ends or a new game starts on that process.

The board size is 10x10 cells, without any special wrap-around-s or
special cell structure – the classic minesweeper.

When a new process is created (using fork()), the son process should
not contain a game – whether the father is running a game or not.
In this exercise you need to implement code wrappers and the corresponding
system calls. For example: msgame_init is a code wrapper and
sys_msgame_init is a system call (see the slides for tutorial 2). Also, you will
need to change some other functions in the kernel accordingly.
Code wrappers:
The following describes the wrappers prototype and behavior. The actual
implementation of this behavior should be implemented in the system calls.
int msgame_init (char * board)
Description: Initializes a new game for the current process, using the
array board as input – specifying where to place the mines.
'board' is an array of 100 chars, representing a row-stacked board of
10*10, with every cell having a value of 0 or 1 (and not '0' or '1' or
anything else). For example, the array [0,1,1,0,0,0,0,0,…,0] has two
mines in row 0 (first row) – at columns 1 and 2 (the second and third).
Any previous game of that process, if exists - is discarded (whether it
is finished or not). After running this system call successfully, the
process is regarded as "running a game". If this system call failed, the
process' game is cleared ("not running a game") and therefore
subsequent calls to msgame_play or msgame_has_won for this
process should fail until successfully initializing a game.
Note: The parameter of this system call is a pointer to a board in the
user space. The system call implementation will need to allocate
memory for the board in the kernel, and initialize it accordingly.
Return values:
On failure: -1.
On success: 0
On failure 'errno' should contain one of following values:

'ENOMEM' (Out of memory): Cannot allocate memory for
managing the game.
2
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)

'EFAULT' (Bad address): incorrect data address for board –
the data can’t be read (e.g. doesn’t belong to the calling
process address space).

'EINVAL' (Invalid argument): The board array is invalid (its
values are not as specified above)
int msgame_play (int pid, int row, int col)
Description: Reveals one cell in the game of the process defined by
pid, and returns the result of this move.
If an empty cell was revealed, the return value is the amount of mines
around the chosen location (in all 8 directions). If the cell is located on
the border, only valid directions must be taken into account.
If a mine was revealed, the return value must be 9, regardless of the
cells around.
'row' and 'col' must have a value of 0-9.
This system call should not reveal any other cell – even if that cell is
empty and has no mines around. This means that msgame_play()
must be called for all cells that don't contain a mine in order to win the
game.
The same cell can be revealed twice.
Return values:
On failure: -1.
If the selected location does not contain a mine: 0-8
If the selected location does have a mine: 9
On failure 'errno' should contain one of following values:

'ESRCH' (No such process): There is no process with the
specified pid.

'EINVAL' (Invalid argument): The specified process is not
running a game, or the game was finished.

'EINVAL' (Invalid argument): 'row' or 'col' have invalid value.
int msgame_has_won(int pid)
Description: Returns whether the game on the specified process has
been won, lost, or not yet finished.
Return values:
On failure: -1.
The game was not finished: 0.
3
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)
The game has been won: 1.
The game has been lost: 2.
On failure 'errno' should contain one of following values:

'ESRCH' (No such process): No such process exists.

'EINVAL' (Invalid argument): The specified process has no
game.
The System calls:
int sys_msgame_init (char * board) (system call #243)
Description: same as the wrapper
Return values:

On success: 0

On failure: '-ENOMEM', '-EFAULT' or '-EINVAL'
int sys_msgame_play (int pid, int row, int col) (system call #244)
Description: same as the wrapper
Return values:

On success: 0-9

On failure: '-ESRCH' or '-EINVAL'
int sys_msgame_has_won(int pid) (system call #245)
Description: same as the wrapper
Return values:

On success: 0/1/2

On failure: '-ESRCH' or '-EINVAL'
4
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)
Example Wrapper
Here is an example of the code wrapper for my_system_call (#244). Follow
this example to write the wrappers.
int my_system_call (int p1, char *p2,int p3)
{
unsigned int res;
__asm__
(
"movl $244, %%eax;"
"movl %1, %%ebx;"
"movl %2, %%ecx;"
"movl %3, %%edx;"
"int $0x80;"
"movl %%eax,%0"
: "=m" (res)
: "m" (p1), "m" (p2), "m" (p3)
: "%eax","%ebx","%ecx","%edx"
);
if (res >= (unsigned long)(-125))
{
errno = -res;
res = -1;
}
return (int) res;
}
Explanation of inline assembler:
1) "movl $244, %%eax;" - copy system call number to register eax.
2) "movl %1, %%ebx;" - copy first parameter (p1) to register ebx.
3) "movl %2, %%ecx;" - copy second parameter (p2) to register ecx.
4) "movl %3, %%edx;" - copy third parameter (p3) to register ecx.
5) "int $0x80;" – system call invocation via interrupt 0x80.
6) "movl %%eax,%0" – copy value that was returned by system call
to res.
7) : "=m" (res) - output operands. Tell to gcc to use res as %0.
8) : "m" (p1) ,"m" (p2) ,"m"(p3) – input operands (p1 as %1, p2 as
%2, p3 as %3).
9) : "%eax","%ebx","%ecx","%edx" – list of clobbered registers.
Inform gcc that we use eax, ebx, ecx, edx registers.
Useful link: http://www-106.ibm.com/developerworks/linux/library/l-ia.html
5
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)
What should you do?
Use VMware, like you learned in the preliminary assignment, in order to make
the following changes in the Linux kernel:
1. Define a struct that contains the game information (for one process)
and declare the system call prototypes in a new .h file,
include/linux/msgame.h.
2. Update the process descriptor (task_struct) in sched.h, adding a
pointer to your game struct, which you will use to implement the
system calls. (Pay attention that the process descriptor size is limited,
so you cannot add too many new fields)
3. Implement the system calls in a new .c file, named
kernel/msgame.c. Update the Makefile in that directory to compile
your new file too. (Tip: add it to obj-y).
4. Update entry.S (add system call numbers)
5. Find the function in sched.c that is responsible for initializing the first
process task structure (init_idle) and initialize your game pointer for
that process.
6. Make necessary changes in file fork.c.
7. Recompile and run the new kernel like you did in the preliminary
assignment.
8. Write the user-mode wrapper functions in minesweeper.h (not as
part of the kernel)
9. Write a user-mode test for your system calls using the attached
execution_sample.c file.
10. Boot with your new Linux, and try to compile and run the test program
to make sure the new system calls work as expected.
Notes and Tips

You are not allowed to use syscall functions to implement code wrappers,
or to write the code wrappers for your system calls using the macro
_syscall1. You should write the code wrappers according to the example of
the code wrapper given above.

You can assume that the system is with a single CPU.

You should use kmalloc and kfree in the kernel in order to allocate and
release memory. If kmalloc fails you should return ENOMEM. For the
kmalloc function use flag GFP_KERNEL for the regular "memory for kernel
use". Include <linux/slab.h>. See the man page for more information.
6
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)

You should use the function copy_from_user in order to copy data from
user space to kernel space. The function copy_to_user is not to be used in
this exercise. Include <asm/uaccess.h>. See the man page for more
information.

When a process is being killed, don't forget to release the memory related
to the game.

Don’t forget that the task_struct and the kernel stack share the same 8KB.
This means that you cannot put too much data in the task_struct, that you
cannot use a too-deep function call tree (no recursion), and that local
(function) variables shouldn't be too large either.

'-EINVAL' stands for 'minus EINVAL'

Don't forget to initialize your data structures.

Use a #defined constant for the number of rows and columns.

Use your test to run several different game concurrently. Write other tests
to check for other possible issues. We will check your assignment with our
test program.

Linux is case-sensitive. entry.S means entry.S, not Entry.s, Entry.S or
entry.s.

Start working on the assignment as soon as possible. The deadline is final,
NO postponements will be given, and high load on the VMWare machines
or t2 will not be accepted as an excuse for late submissions.

No need to print your code as part of the wet HW paper submission to the
course's cell. You need only to explain what you have been done in the
code.
Did it all? Good work, Submit your assignment. 
Submission
The submission of this assignment has two parts:

A printed submission. You should write a short (less than 1 page)
summary explaining what you have done in this assignment, which
changes to the kernel data structures you have done and which
functions have been modified and how.
Do not print the code!

An electronic submission – you should create a zip file (use zip only,
not gzip, tar, rar, 7z or anything else) containing the following files:
7
Operating Systems (234123) – Winter 2010-2011
(Homework Wet 1)
a. A tarball named kernel.tar.gz containing all the files in the
kernel that you created or modified (including any source,
assembly or makefile) – Do not add files that were not modified!
To create the tarball run (inside VMWare):
cd /usr/src/linux-2.4.18-14custom
tar -czf kernel.tar.gz <list of modified or
added files>
For example, if the only files you changed are
arch/i386/kernel/entry.S and kernel/msgame.c you should run:
cd /usr/src/linux-2.4.18-14custom
tar –czf kernel.tar.gz arch/i386/kernel/entry.S
kernel/msgame.c
Make sure you don't forget any file and that you use relative
paths in the tar command, i.e., use kernel/msgame.c and not
/usr/src/linux-2.4.18-14custom/kernel/msgame.c
b. A file named submitters.txt which includes the ID, name and
email of the participating students. The following format should
be used:
Bill Gates [email protected] 123456789
Linus Torvalds [email protected] 234567890
Steve Jobs jobs@os_is_best.com 345678901
c. The user-mode minesweeper.h header file that contains the
wrapper functions.
Important Note: Make the outlined zip structure exactly. In
particular, the zip should contain only the following files (no
directories!). You can create the zip by running (inside VMware):
zip final.zip kernel.tar.gz submitters.txt
minesweeper.h
The zip should look as follows:
zipfile -+
|
+- kernel.tar.gz
|
+- submitters.txt
|
+- minesweeper.h
Good Luck,
The course staff
8