Lab: Alarm and uthread

This lab will familiarize you with the implementation of system calls and switching between threads of execution. In particular, you will implement new system calls (sigalarm and sigreturn) and switching between threads in a user-level thread package.

Start a new branch for this lab, forking from your last branch.

  $ git checkout -b alarm

Warmup: RISC-V assembly

For this lab it will be important to understand a bit of RISC-V assembly. There is a file user/call.c in your xv6 repo. make fs.img builds a user program call and a readable assembly a version of the program in the file user/call.asm.

Read through user/call.asm and understand it. The instruction manual for RISC-V is in the doc directory (doc/riscv-spec-v2.2.pdf). Here are some questions that you should answer (store the answers in a file answers-alarm.txt):

Which registers contain arguments to functions? Which register holds 13 in the call to printf? Which register holds the second argument? Which register holds the third one? Etc.
Where is the function call to f from main? Where is the call to g? (Hint: the compiler may inline functions.)
At what address is the function printf located?
What value is in the register ra just after the jalr to printf in main?

Warmup: system call tracing

In this exercise you will modify the xv6 kernel to print out a line for each system call invocation. It is enough to print the name of the system call and the return value; you don't need to print the system call arguments. You don't have to submit your solution, but it will be handy to keep your code around for debugging purposes in this and later labs.

When you're done, you should see output like this when booting xv6:

...
fork -> 2
exec -> 0
open -> 3
close -> 0
$write -> 1
 write -> 1

That's init forking and execing sh, sh making sure only two file descriptors are open, and sh writing the $ prompt. (Note: the output of the shell and the system call trace are intermixed, because the shell uses the write syscall to print its output.)

Hint: modify the syscall() function in kernel/syscall.c.

Run the command from the previous lab and inspect the system call trace. Are there many system calls? Which system calls correspond to code in the applications you wrote?

Optional: print the system call arguments.

Alarm

In this exercise you'll add a feature to xv6 that periodically alerts a process as it uses CPU time. This might be useful for compute-bound processes that want to limit how much CPU time they chew up, or for processes that want to compute but also want to take some periodic action. More generally, you'll be implementing a primitive form of user-level interrupt/fault handlers; you could use something similar to handle page faults in the application, for example. Your solution is correct if it passes alarmtest and usertests.

You should add a new sigalarm(interval, handler) system call. If an application calls sigalarm(n, fn), then after every n "ticks" of CPU time that the program consumes, the kernel should cause application function fn to be called. When fn returns, the application should resume where it left off. A tick is a fairly arbitrary unit of time in xv6, determined by how often a hardware timer generates interrupts.

You'll find a file user/alarmtest.c in your xv6 repository. Add it to the Makefile. It won't compile correctly until you've added sigalarm and sigreturn system calls (see below).

alarmtest calls sigalarm(2, periodic) in test0 to ask the kernel to force a call to periodic() every 2 ticks, and then spins for a while. You can see the assembly code for alarmtest in user/alarmtest.asm, which may be handy for debugging. Your solution is correct, when alarmtest produces output like this and usertests also runs correctly:

$ alarmtest
test0 start
......................................alarm!
test0 passed
test1 start
..alarm!
..alarm!
..alarm!
.alarm!
..alarm!
..alarm!
..alarm!
..alarm!
..alarm!
..alarm!
test1 passed
$ usertests
...
ALL TESTS PASSED
$

The main challenge will be to arrange that the handler is invoked when the process's alarm interval expires. You'll need to modify usertrap() in kernel/trap.c so that when a process's alarm interval expires, the process executes the handler. How can you do that? You will need to understand how system calls work (i.e., the code in kernel/trampoline.S and kernel/trap.c). Which register contains the address to which system calls return?

Your solution will be only a few lines of code, but it may be tricky to get it right. We'll test your code with the version of alarmtest.c in the original repository; if you modify alarmtest.c, make sure your kernel changes cause the original alarmtest to pass the tests.

test0: invoke handler

Get started by modifying the kernel to jump to the alarm handler in user space, which will cause test0 to print "alarm!". Don't worry yet what happens after the "alarm!" output; it's OK for now if your program crashes after printing "alarm!". Here are some hints:

test1(): resume interrupted code

Chances are that alarmtest crashes at some point after it prints "alarm!". Depending on how your solution works, that point may be in test0, or it may be in test1. Crashes are likely caused by the alarm handler (periodic in alarmtest.c) returning to the wrong point in the user program.

Your job now is to ensure that, when the alarm handler is done, control returns to the instruction at which the user program was originally interrupted by the timer interrupt. You must also ensure that the register contents are restored to values they held at the time of the interrupt, so that the user program can continue undisturbed after the alarm.

Your solution is likely to require you to save and restore registers---what registers do you need to save and restore to resume the interrupted code correctly? (Hint: it will be many). Several approaches are possible; for this lab you should make the sigreturn system call restore registers and return to the original interrupted user instruction. The user-space alarm handler calls sigreturn when it is done. Some hints:

Once you pass test0 and test1, run usertests to make sure you didn't break any other parts of the kernel.

Uthread: switching between threads

In this exercise you will write code to switch between threads of execution. Your xv6 has two files uthread.c and uthread_switch.S, and a rule in the Makefile to build uthread.

Run xv6, then run uthread from the xv6 shell. The xv6 kernel will print an error message about uthread encountering a page fault.

Your job is to complete uthread_switch.S, so that you see output similar to the output below (make sure to run with CPUS=1).

~/classes/6828/xv6$ make CPUS=1 qemu
...
$ uthread
my thread running
my thread 0x0000000000002A30
my thread running
my thread 0x0000000000004A40
my thread 0x0000000000002A30
my thread 0x0000000000004A40
my thread 0x0000000000002A30
my thread 0x0000000000004A40
my thread 0x0000000000002A30
my thread 0x0000000000004A40
my thread 0x0000000000002A30
...
my thread 0x0000000000002A88
my thread 0x0000000000004A98
my thread: exit
my thread: exit
thread_schedule: no runnable threads
$

uthread creates two threads and switches back and forth between them. Each thread prints "my thread ..." and then yields to give the other thread a chance to run.

To observe the above output, you need to complete uthread_switch.S, but before jumping into uthread_switch.S, first understand how uthread.c uses uthread_switch. uthread.c has two global variables current_thread and next_thread. Each is a pointer to a thread structure. The thread structure has a stack for a thread and a saved stack pointer (sp, which points into the thread's stack). The job of uthread_switch is to save the current thread state into the structure pointed to by current_thread, restore next_thread's state, and make current_thread point to where next_thread was pointing to, so that when uthread_switch returns next_thread is running and is the current_thread.

You should study thread_create, which sets up the initial stack for a new thread. It provides hints about what uthread_switch should do. Note that thread_create simulates saving all callee-save registers on a new thread's stack.

To write the assembly in thread_switch, you need to know how the C compiler lays out struct thread in memory, which is as follows:

    --------------------
    | 4 bytes for state|
    --------------------
    | stack size bytes |
    | for stack        |
    --------------------
    | 8 bytes for sp   |
    --------------------  <--- current_thread
         ......

         ......
    --------------------
    | 4 bytes for state|
    --------------------
    | stack size bytes |
    | for stack        |
    --------------------
    | 8 bytes for sp   |
    --------------------  <--- next_thread
The variables &next_thread and ¤t_thread each contain the address of a pointer to struct thread, and are passed to thread_switch. The following fragment of assembly will be useful:
   ld t0, 0(a0)
   sd sp, 0(t0)
This saves sp in current_thread->sp. This works because sp is at offset 0 in the struct. You can study the assembly the compiler generates for uthread.c by looking at uthread.asm.

To test your code it might be helpful to single step through your uthread_switch using riscv64-linux-gnu-gdb. You can get started in this way:

(gdb) file user/_uthread
Reading symbols from user/_uthread...
(gdb) b *0x230

0x230 is the address of uthread_switch (see uthread.asm). When you compile it may be at a different address, so check uthread_asm. You may also be able to type "b uthread_switch". XXX This doesn't work for me; why?

The breakpoint may (or may not) be triggered before you even run uthread. How could that happen?

Once your xv6 shell runs, type "uthread", and gdb will break at thread_switch. Now you can type commands like the following to inspect the state of uthread:

  (gdb) p/x *next_thread
  $1 = {sp = 0x4a28, stack = {0x0 (repeats 8088 times),
      0x68, 0x1, 0x0 }, state = 0x1}
What address is 0x168, which sits on the bottom of the stack of next_thread?
With "x", you can examine the content of a memory location
  (gdb) x/x next_thread->sp
  0x4a28 :      0x00000168
Why does that print 0x168?

This completes the lab. Make sure you pass all of the make grade tests and don't forget to write up your answers to the questions in answers-alarm.txt. Commit your changes (including adding answers-alarm.txt) and type make handin in the lab directory to hand in your lab.

Optional challenges

The user-level thread package interacts badly with the operating system in several ways. For example, if one user-level thread blocks in a system call, another user-level thread won't run, because the user-level threads scheduler doesn't know that one of its threads has been descheduled by the xv6 scheduler. As another example, two user-level threads will not run concurrently on different cores, because the xv6 scheduler isn't aware that there are multiple threads that could run in parallel. Note that if two user-level threads were to run truly in parallel, this implementation won't work because of several races (e.g., two threads on different processors could call thread_schedule concurrently, select the same runnable thread, and both run it on different processors.)

There are several ways of addressing these problems. One is using scheduler activations and another is to use one kernel thread per user-level thread (as Linux kernels do). Implement one of these ways in xv6. This is not easy to get right; for example, you will need to implement TLB shootdown when updating a page table for a multithreaded user process.

Add locks, condition variables, barriers, etc. to your thread package.