Contents
Changelog:
- 30 August 2018: Under “Adding the system call” indicate that
syscall.c
andsyscall.h
is where system call dispatching is implemented, and mention the files where the actual individual system calls are implemented. - 31 August 2018: Add some additional notes about options for testing correctness and debugging under “Testing your system call”.
- 1 September 2018: Correct link to xv6 book to link to the commentary book, not the (much less useful) source code book.
- 1 September 2018: Add note that we don’t care how
writecount()
works with multiple processors, which are not used by default in our version of xv6. - 2 September 2018: More careful phrasing of not caring about multiple processors; add explanation of locks not being required to hints, and note this alongside referencing
uptime
. - 3 Septmeber 2018: Mention user.h in hints.
- 18 August 2019: add section re: this assignment being based on Arpaci-Dusseau’s
Your task
- Obtain a copy of a VM or another Linux environment (most likely not OS X, see below) with:
- a working C and C++ compiler
- a recent copy of qemu installed (configured to support full 32-bit x86 emulation).
We have supplied a suitable VM image here (login with username ‘user’, password ‘password; use with virtaulbox), or you can use your own.
-
Download and get xv6 to boot in an emulated machine. For how to do this, see the instructions below. Run it and make sure you can run some simple commands in a shell in the emulated machine.
-
Add a new system call
writecount()
that takes no arguments and returns the number of times thewrite
system call has been called across all processes. See below for hints about how to do this.(We do not care how your
writecount()
system call counts calls towrite
that fail, such as from having invalid arguments. We also don’t care how it treats simulataneous calls to write() and/or writecount() on multiple processors (not used by default in our version of xv6).) -
Write a program that uses and tests this new system call. See below for hints on how to do this.
- Run
make submit
to create a.tar.gz
archive and upload it to the 4414-002 submission site. (For 4414-001, submit on Collab.)
xv6 information
Hints
Getting xv6 running
-
Download our version of xv6 using git:
git clone https://github.com/uva-reiss-cs4414/xv6.git
-
In the newly created
xv6
directory, runmake
. -
Boot xv6 in an emulator using one of the following methods:
-
To boot the OS in an emulator with a graphical user interface, run
make qemu
. -
To boot the OS in an emulator without a graphical user interface, run
make qemu-nox
. (nox
probably standards for “no X”; X is short for the X windowing system, the primary graphics system on Unix-like operating systems.)
-
Adding the system call
For this task, you might want to read
-
Chapter 3 of the xv6 book (PDF) describing how exceptions, traps, interrupts, etc. See also note on terminology below. (The book refers to line numbers in this print out of the xv6 source code.)
-
how system call dispatching is implemented in
syscall.c
andsyscall.h
, and how the handlers for individual system calls are implemented insysproc.c
andsysfile.c
.
Basic steps for adding system calls:
-
Create a
sys_writecount
function based on an existing simple system call function likesys_uptime
. (For this assignment, you do not need to (but are allowed to) use a spinlock andacquire
orrelease
likeuptime
does since we do not care how your code works with multiple processors.) -
Add a system call number for your new system call to
syscall.h
. -
Add your
sys_writecount
to the table insyscall.c
. -
Edit
sys_write
. You can use a command likegrep sys_write *.c
to find out where it is. -
Edit
usys.S
anduser.h
to create a system call wrapper function that invokes your system call from a normal user program.
Testing your system call
-
Using
echo.c
as a template, create a new program to run your writecount system call and print the results. -
Edit
Makefile
by adding your program toUPROGS
, similar to howecho
is included on this list. -
Run
make
and thenmake qemu
to boot the OS with your new program included. -
If your test program crashes after finishing, you may have forgotten to
exit()
at the end. (Returning frommain()
will not work.) -
You could run other programs that call
write()
(e.g. by outputting anything to the console) and/or have your test program make writes (using thewrite()
system call wrapping function directly or by taking advantage ofprintf()
calling write) to verify that the count make sense. -
In kernel code, you can do debug printing using the
cprintf()
function. You can use this to help debug any problems with your code, or get a better idea what’s going on.
Locks not required
-
sys_uptime
uses a spinlock, which it uses to handle the case where xv6 is running on multiple processors. For this assignment, you don’t need to worry about this problem. -
An implementation of
writecount
that correctly handled multiple procesors would probably use a spinlock around accesses to the counter (from bothwrite
andwritecount
).
xv6 book: note on terminology
CS 3330 and the xv6 book and source code use slightly different terminology related to exceptions:
CS 3330 Term | most common xv6 term | description |
---|---|---|
exception | trap | any event in which the processor transfers control from whatever program was running to the OS (to the “kernel”) at a location chosen by the OS |
fault | exception | a program performs an illegal action, causing control to be transferred to the OS to decide what to do |
interrupt | interrupt | an event external to the program, such as a timer or an input/output device needs the OS’s attention |
trap | (specific kind) trap | an exception deliberately triggered by an instruction; on x86 this is via the int instruction |
a note on OS X
Because xv6 expects ELF format binaries, xv6 will require a cross-compiler on OS X. We recommend (and will support) using a Linux environment instead (such as through a VM) instead, but if you can get it working natively on OS X using a cross-compiler, that’s great (and your fellow students would probably appreciate the information).
Credit
This assignment is based loosely on Arpaci-Dusseau’s initial-xv6 assignment.