Discourage combining student contributions late.

[pintos-anon] / doc / threads.texi

@node Project 1--Threads, Project 2--User Programs, Pintos Tour, Top
@chapter Project 1: Threads

In this assignment, we give you a minimally functional thread system.
Your job is to extend the functionality of this system to gain a
better understanding of synchronization problems. Additionally, you
will use at least part of this increased functionality in future
assignments.

You will be working in primarily in the @file{threads} directory for
this assignment, with some work in the @file{devices} directory on the
side.  Compilation should be done in the @file{threads} directory.

Before you read the description of this project, you should read all
of the following sections: @ref{Introduction}, @ref{Coding Standards},
@ref{Project Documentation}, @ref{Debugging Tools}, and
@ref{Development Tools}.  You should at least skim the material in
@ref{Threads Tour}.  To complete this project you will also need to
read @ref{Multilevel Feedback Scheduling}.

@menu
* Understanding Threads::       
* Project 1 Code::              
* Debugging versus Testing::    
* Tips::                        
* Problem 1-1 Alarm Clock::     
* Problem 1-2 Join::            
* Problem 1-3 Priority Scheduling::  
* Problem 1-4 Advanced Scheduler::  
* Threads FAQ::                 
@end menu

@node Understanding Threads
@section Understanding Threads

The first step is to read and understand the initial thread system.
Pintos, by default, implements thread creation and thread completion,
a simple scheduler to switch between threads, and synchronization
primitives (semaphores, locks, and condition variables). 

However, there's a lot of magic going on in some of this code, so if
you haven't already compiled and run the base system, as described in
the introduction (@pxref{Introduction}), you should do so now.  You
can read through parts of the source code by hand to see what's going
on.  If you like, you can add calls to @func{printf} almost
anywhere, then recompile and run to see what happens and in what
order.  You can also run the kernel in a debugger and set breakpoints
at interesting spots, single-step through code and examine data, and
so on.  @xref{i386-elf-gdb}, for more information.

When a thread is created, you are creating a new context to be
scheduled. You provide a function to be run in this context as an
argument to @func{thread_create}. The first time the thread is
scheduled and runs, it will start from the beginning of that function
and execute it in the context. When that function returns, that thread
completes. Each thread, therefore, acts like a mini-program running
inside Pintos, with the function passed to @func{thread_create}
acting like @func{main}.

At any given time, Pintos is running exactly one thread, with the
others switched out.  The scheduler decides which thread to run next
when it needs to switch between them.  (If no thread is ready to run
at any given time, then the special ``idle'' thread runs.)  The
synchronization primitives are used to force context switches when one
thread needs to wait for another thread to do something.

The exact mechanics of a context switch are pretty gruesome and have
been provided for you in @file{threads/switch.S} (this is 80@var{x}86
assembly; don't worry about understanding it).  It involves saving the
state of the currently running thread and restoring the state of the
thread we're switching to.

Using the @command{gdb} debugger, slowly trace through a context
switch to see what happens (@pxref{i386-elf-gdb}).  You can set a
breakpoint on the @func{schedule} function to start out, and then
single-step from there.@footnote{@command{gdb} might tell you that
@func{schedule} doesn't exist, which is arguably a @command{gdb} bug.
You can work around this by setting the breakpoint by filename and
line number, e.g.@: @code{break thread.c:@var{ln}} where @var{ln} is
the line number of the first declaration in @func{schedule}.}  Be sure
to keep track of each thread's address
and state, and what procedures are on the call stack for each thread.
You will notice that when one thread calls @func{switch_threads},
another thread starts running, and the first thing the new thread does
is to return from @func{switch_threads}.  We realize this comment will
seem cryptic to you at this point, but you will understand threads
once you understand why the @func{switch_threads} that gets called is
different from the @func{switch_threads} that returns.

@strong{Warning}: In Pintos, each thread is assigned a small,
fixed-size execution stack just under @w{4 kB} in size.  The kernel
does try to detect stack overflow, but it cannot always succeed.  You
may cause bizarre problems, such as mysterious kernel panics, if you
declare large data structures as non-static local variables,
e.g. @samp{int buf[1000];}.  Alternatives to stack allocation include
the page allocator in @file{threads/palloc.c} and the block allocator
in @file{threads/malloc.c}.  Note that the page allocator doles out
@w{4 kB} chunks and that @func{malloc} has a @w{2 kB} block size
limit.  If you need larger chunks, consider using a linked structure
instead.

@node Project 1 Code
@section Code

Here is a brief overview of the files in the @file{threads}
directory.  You will not need to modify most of this code, but the
hope is that presenting this overview will give you a start on what
code to look at.

@table @file
@item loader.S
@itemx loader.h
The kernel loader.  Assembles to 512 bytes of code and data that the
PC BIOS loads into memory and which in turn loads the kernel into
memory, does basic processor initialization, and jumps to the
beginning of the kernel.  You should not need to look at this code or
modify it.

@item kernel.lds.S
The linker script used to link the kernel.  Sets the load address of
the kernel and arranges for @file{start.S} to be at the very beginning
of the kernel image.  Again, you should not need to look at this code
or modify it, but it's here in case you're curious.

@item start.S
Jumps to @func{main}.

@item init.c
@itemx init.h
Kernel initialization, including @func{main}, the kernel's ``main
program.''  You should look over @func{main} at least to see what
gets initialized.

@item thread.c
@itemx thread.h
Basic thread support.  Much of your work will take place in these
files.  @file{thread.h} defines @struct{thread}, which you will
modify in the first three projects.

@item switch.S
@itemx switch.h
Assembly language routine for switching threads.  Already discussed
above.

@item palloc.c
@itemx palloc.h
Page allocator, which hands out system memory in multiples of 4 kB
pages.

@item malloc.c
@itemx malloc.h
A very simple implementation of @func{malloc} and @func{free} for
the kernel.

@item interrupt.c
@itemx interrupt.h
Basic interrupt handling and functions for turning interrupts on and
off.

@item intr-stubs.pl
@itemx intr-stubs.h
A Perl program that outputs assembly for low-level interrupt handling.

@item synch.c
@itemx synch.h
Basic synchronization primitives: semaphores, locks, and condition
variables.  You will need to use these for synchronization through all
four projects.

@item test.c
@itemx test.h
Test code.  For project 1, you will replace this file with your test
cases.

@item io.h
Functions for I/O port access.  This is mostly used by source code in
the @file{devices} directory that you won't have to touch.

@item mmu.h
Functions and macros related to memory management, including page
directories and page tables.  This will be more important to you in
project 3.  For now, you can ignore it.
@end table

@menu
* devices code::                
* lib files::                   
@end menu

@node devices code
@subsection @file{devices} code

The basic threaded kernel also includes these files in the
@file{devices} directory:

@table @file
@item timer.c
@itemx timer.h
System timer that ticks, by default, 100 times per second.  You will
modify this code in Problem 1-1.

@item vga.c
@itemx vga.h
VGA display driver.  Responsible for writing text to the screen.
You should have no need to look at this code.  @func{printf} will
call into the VGA display driver for you, so there's little reason to
call this code yourself.

@item serial.c
@itemx serial.h
Serial port driver.  Again, @func{printf} calls this code for you,
so you don't need to do so yourself.  Feel free to look through it if
you're curious.

@item disk.c
@itemx disk.h
Supports reading and writing sectors on up to 4 IDE disks.  This won't
actually be used until project 2.

@item intq.c
@itemx intq.h
Interrupt queue, for managing a circular queue that both kernel
threads and interrupt handlers want to access.  Used by the keyboard
and serial drivers.
@end table

@node lib files
@subsection @file{lib} files

Finally, @file{lib} and @file{lib/kernel} contain useful library
routines.  (@file{lib/user} will be used by user programs, starting in
project 2, but it is not part of the kernel.)  Here's a few more
details:

@table @file
@item ctype.h
@itemx inttypes.h
@itemx limits.h
@itemx stdarg.h
@itemx stdbool.h
@itemx stddef.h
@itemx stdint.h
@itemx stdio.c
@itemx stdio.h
@itemx stdlib.c
@itemx stdlib.h
@itemx string.c
@itemx string.h
Implementation of the standard C library.  @xref{C99}, for information
on a few recently introduced pieces of the C library that you might
not have encountered before.  @xref{Unsafe String Functions}, for
information on what's been intentionally left out for safety.

@item debug.c
@itemx debug.h
Functions and macros to aid debugging.  @xref{Debugging Tools}, for
more information.

@item random.c
@itemx random.h
Pseudo-random number generator.

@item round.h
Macros for rounding.

@item syscall-nr.h
System call numbers.  Not used until project 2.

@item kernel/list.c
@itemx kernel/list.h
Doubly linked list implementation.  Used all over the Pintos code, and
you'll probably want to use it a few places yourself in project 1.

@item kernel/bitmap.c
@itemx kernel/bitmap.h
Bitmap implementation.  You can use this in your code if you like, but
you probably won't have any need for project 1.

@item kernel/hash.c
@itemx kernel/hash.h
Hash table implementation.  Likely to come in handy for project 3.

@item kernel/console.c
@itemx kernel/console.h
Implements @func{printf} and a few other functions.
@end table

@node Debugging versus Testing
@section Debugging versus Testing

When you're debugging code, it's useful to be able to be able to run a
program twice and have it do exactly the same thing.  On second and
later runs, you can make new observations without having to discard or
verify your old observations.  This property is called
``reproducibility.''  The simulator we use, Bochs, can be set up for
reproducibility, and that's the way that @command{pintos} invokes it
by default.

Of course, a simulation can only be reproducible from one run to the
next if its input is the same each time.  For simulating an entire
computer, as we do, this means that every part of the computer must be
the same.  For example, you must use the same disks, the same version
of Bochs, and you must not hit any keys on the keyboard (because you
could not be sure to hit them at exactly the same point each time)
during the runs.

While reproducibility is useful for debugging, it is a problem for
testing thread synchronization, an important part of this project.  In
particular, when Bochs is set up for reproducibility, timer interrupts
will come at perfectly reproducible points, and therefore so will
thread switches.  That means that running the same test several times
doesn't give you any greater confidence in your code's correctness
than does running it only once.

So, to make your code easier to test, we've added a feature, called
``jitter,'' to Bochs, that makes timer interrupts come at random
intervals, but in a perfectly predictable way.  In particular, if you
invoke @command{pintos} with the option @option{-j @var{seed}}, timer
interrupts will come at irregularly spaced intervals.  Within a single
@var{seed} value, execution will still be reproducible, but timer
behavior will change as @var{seed} is varied.  Thus, for the highest
degree of confidence you should test your code with many seed values.

On the other hand, when Bochs runs in reproducible mode, timings are not
realistic, meaning that a ``one-second'' delay may be much shorter or
even much longer than one second.  You can invoke @command{pintos} with
a different option, @option{-r}, to make it set up Bochs for realistic
timings, in which a one-second delay should take approximately one
second of real time.  Simulation in real-time mode is not reproducible,
and options @option{-j} and @option{-r} are mutually exclusive.

@node Tips
@section Tips

@itemize @bullet
@item
There should be no busy waiting in any of your solutions to this
assignment.  We consider a tight loop that calls @func{thread_yield}
to be one form of busy waiting.

@item
Proper synchronization is an important part of the solutions to these
problems.  It is tempting to synchronize all your code by turning off
interrupts with @func{intr_disable} or @func{intr_set_level}, because
this eliminates concurrency and thus the possibility for race
conditions, but @strong{don't}.  Instead, use semaphores, locks, and
condition variables to solve the bulk of your synchronization
problems.  Read the tour section on synchronization
(@pxref{Synchronization}) or the comments in @file{threads/synch.c} if
you're unsure what synchronization primitives may be used in what
situations.

You might run into a few situations where interrupt disabling is the
best way to handle synchronization.  If so, you need to explain your
rationale in your design documents.  If you're unsure whether a given
situation justifies disabling interrupts, talk to the TAs, who can
help you decide on the right thing to do.

Disabling interrupts can be useful for debugging, if you want to make
sure that a section of code is not interrupted.  You should remove
debugging code before turning in your project.

@item
All parts of this assignment are required if you intend to earn full
credit on this project.  However, some will be more important in
future projects:

@itemize @minus
@item
Problem 1-1 (Alarm Clock) could be handy for later projects, but it is
not strictly required.

@item
Problem 1-2 (Join) will be needed for future projects.  We don't give
out solutions, so to avoid extra work later you should make sure that
your implementation of @func{thread_join} works correctly.

@item
Problems 1-3 and 1-4 won't be needed for later projects.
@end itemize

@item
Problem 1-4 (MLFQS) builds on the features you implement in Problem
1-3.  You should have Problem 1-3 fully working before you begin to
tackle Problem 1-4.

@item
In the past, many groups divided the assignment into pieces, then each
group member worked on his or her piece until just before the
deadline, at which time the group reconvened to combine their code and
submit.  @strong{This is a bad idea.  We do not recommend this
approach.}  Groups that do this often find that two changes conflict
with each other, requiring lots of last-minute debugging.  Some groups
who have done this have turned in code that did not even successfully
boot.

Instead, we recommend integrating your team's changes early and often,
using a source code control system such as CVS (@pxref{CVS}) or a
group collaboration site such as SourceForge (@pxref{SourceForge}).
This is less likely to produce surprises, because everyone can see
everyone else's code as it is written, instead of just when it is
finished.  These systems also make it possible to review changes and,
when a change introduces a bug, drop back to working versions of code.
@end itemize

@node Problem 1-1 Alarm Clock
@section Problem 1-1: Alarm Clock

Improve the implementation of the timer device defined in
@file{devices/timer.c} by reimplementing @func{timer_sleep}.
Threads call @code{timer_sleep(@var{x})} to suspend execution until
time has advanced by at least @w{@var{x} timer ticks}.  This is
useful for threads that operate in real-time, for example, for
blinking the cursor once per second.  There is no requirement that
threads start running immediately after waking up; just put them on
the ready queue after they have waited for approximately the right
amount of time.

A working implementation of this function is provided.  However, the
version provided is poor, because it ``busy waits,'' that is, it spins
in a tight loop checking the current time until the current time has
advanced far enough.  This is undesirable because it wastes time that
could potentially be used more profitably by another thread.  Your
solution should not busy wait.

The argument to @func{timer_sleep} is expressed in timer ticks, not in
milliseconds or any another unit.  There are @code{TIMER_FREQ} timer
ticks per second, where @code{TIMER_FREQ} is a macro defined in
@code{devices/timer.h}.

Separate functions @func{timer_msleep}, @func{timer_usleep}, and
@func{timer_nsleep} do exist for sleeping a specific number of
milliseconds, microseconds, or nanoseconds, respectively, but these will
call @func{timer_sleep} automatically when necessary.  You do not need
to modify them.

If your delays seem too short or too long, reread the explanation of the
@option{-r} option to @command{pintos} (@pxref{Debugging versus
Testing}).

@node Problem 1-2 Join
@section Problem 1-2: Join

Implement @code{thread_join(tid_t)} in @file{threads/thread.c}.  There
is already a prototype for it in @file{threads/thread.h}, which you
should not change.  This function causes the currently running thread
to block until the thread whose thread id is passed as an argument
exits.  If @var{A} is the running thread and @var{B} is the argument,
then we say that ``@var{A} joins @var{B}.''

Incidentally, we don't use @code{struct thread *} as
@func{thread_join}'s parameter type because a thread pointer is not
unique over time.  That is, when a thread dies, its memory may be,
whether immediately or much later, reused for another thread.  If
thread @var{A} over time had two children @var{B} and @var{C} that
were stored at the same address, then @code{thread_join(@var{B})} and
@code{thread_join(@var{C})} would be ambiguous.  Introducing a thread
id or @dfn{tid}, represented by type @code{tid_t}, that is
intentionally unique over time solves the problem.  The provided code
uses an @code{int} for @code{tid_t}, but you may decide you prefer to
use some other type.

The model for @func{thread_join} is the @command{wait} system call
in Unix-like systems.  (Try reading the manpages.)  That system call
can only be used by a parent process to wait for a child's death.  You
should implement @func{thread_join} to have the same restriction.
That is, a thread may only join its immediate children.

A thread need not ever be joined.  Your solution should properly free
all of a thread's resources, including its @struct{thread},
whether it is ever joined or not, and regardless of whether the child
exits before or after its parent.  That is, a thread should be freed
exactly once in all cases.

Joining a given thread is idempotent.  That is, joining a thread T
multiple times is equivalent to joining it once, because T has already
exited at the time of the later joins.  Thus, joins on T after the
first should return immediately.

Calling @func{thread_join} on an thread that is not the caller's
child should cause the caller to return immediately.

Consider all the ways a join can occur: nested joins (@var{A} joins
@var{B}, then @var{B} joins @var{C}), multiple joins (@var{A} joins
@var{B}, then @var{A} joins @var{C}), and so on.  Does your join work
if @func{thread_join} is called on a thread that has not yet been
scheduled for the first time?  You should handle all of these cases.
Write test code that demonstrates the cases your join works for.
Don't overdo the output volume, please!

Be careful to program this function correctly.  You will need its
functionality for project 2.

Once you've implemented @func{thread_join}, define
@code{THREAD_JOIN_IMPLEMENTED} in @file{constants.h}.
@xref{Conditional Compilation}, for more information.

@node Problem 1-3 Priority Scheduling
@section Problem 1-3: Priority Scheduling

Implement priority scheduling in Pintos.  Priority scheduling is a key
building block for real-time systems.  Implement functions
@func{thread_set_priority} to set the priority of the running thread
and @func{thread_get_priority} to get the running thread's priority.
(This API only allows a thread to examine and modify its own
priority.)  There are already prototypes for these functions in
@file{threads/thread.h}, which you should not change.

Thread priority ranges from @code{PRI_MIN} (0) to @code{PRI_MAX} (59).
The initial thread priority is passed as an argument to
@func{thread_create}.  If there's no reason to choose another
priority, use @code{PRI_DEFAULT} (29).  The @code{PRI_} macros are
defined in @file{threads/thread.h}, and you should not change their
values.

When a thread is added to the ready list that has a higher priority
than the currently running thread, the current thread should
immediately yield the processor to the new thread.  Similarly, when
threads are waiting for a lock, semaphore or condition variable, the
highest priority waiting thread should be woken up first.  A thread
may set its priority at any time.

One issue with priority scheduling is ``priority inversion'': if a
high priority thread needs to wait for a low priority thread (for
instance, for a lock held by a low priority thread, or in
@func{thread_join} for a thread to complete), and a middle priority
thread is on the ready list, then the high priority thread will never
get the CPU because the low priority thread will not get any CPU time.
A partial fix for this problem is to have the waiting thread
``donate'' its priority to the low priority thread while it is holding
the lock, then recall the donation once it has acquired the lock.
Implement this fix.

You will need to account for all different orders in which priority
donation and inversion can occur.  Be sure to handle multiple
donations, in which multiple priorities are donated to a thread.  You
must also handle nested donation: given high, medium, and low priority
threads @var{H}, @var{M}, and @var{L}, respectively, if @var{H} is
waiting on a lock that @var{M} holds and @var{M} is waiting on a lock
that @var{L} holds, then both @var{M} and @var{L} should be boosted to
@var{H}'s priority.

You only need to implement priority donation when a thread is waiting
for a lock held by a lower-priority thread.  You do not need to
implement this fix for semaphores, condition variables, or joins,
although you are welcome to do so.  However, you do need to implement
priority scheduling in all cases.

You may assume a static priority for priority donation, that is, it is
not necessary to ``re-donate'' a thread's priority if it changes
(although you are free to do so).

@node Problem 1-4 Advanced Scheduler
@section Problem 1-4: Advanced Scheduler

Implement Solaris's multilevel feedback queue scheduler (MLFQS) to
reduce the average response time for running jobs on your system.
@xref{Multilevel Feedback Scheduling}, for a detailed description of
the MLFQS requirements.

Demonstrate that your scheduling algorithm reduces response time
relative to the original Pintos scheduling algorithm (round robin) for
at least one workload of your own design (i.e.@: in addition to the
provided test).

You must write your code so that we can turn the MLFQS on and off at
compile time.  By default, it must be off, but we must be able to turn
it on by inserting the line @code{#define MLFQS 1} in
@file{constants.h}.  @xref{Conditional Compilation}, for details.

@node Threads FAQ
@section FAQ

@enumerate 1
@item
@b{I am adding a new @file{.h} or @file{.c} file.  How do I fix the
@file{Makefile}s?}@anchor{Adding c or h Files}

To add a @file{.c} file, edit the top-level @file{Makefile.build}.
You'll want to add your file to variable @samp{@var{dir}_SRC}, where
@var{dir} is the directory where you added the file.  For this
project, that means you should add it to @code{threads_SRC}, or
possibly @code{devices_SRC} if you put in the @file{devices}
directory.  Then run @code{make}.  If your new file doesn't get
compiled, run @code{make clean} and then try again.

When you modify the top-level @file{Makefile.build}, the modified
version should be automatically copied to
@file{threads/build/Makefile} when you re-run make.  The opposite is
not true, so any changes will be lost the next time you run @code{make
clean} from the @file{threads} directory.  Therefore, you should
prefer to edit @file{Makefile.build} (unless your changes are meant to
be truly temporary).

There is no need to edit the @file{Makefile}s to add a @file{.h} file.

@item
@b{How do I write my test cases?}

Test cases should be replacements for the existing @file{test.c}
file.  Put them in a @file{threads/testcases} directory.
@xref{TESTCASE}, for more information.

@item
@b{Why can't I disable interrupts?}

Turning off interrupts should only be done for short amounts of time,
or else you end up losing important things such as disk or input
events.  Turning off interrupts also increases the interrupt handling
latency, which can make a machine feel sluggish if taken too far.
Therefore, in general, setting the interrupt level should be used
sparingly.  Also, any synchronization problem can be easily solved by
turning interrupts off, since while interrupts are off, there is no
concurrency, so there's no possibility for race conditions.

To make sure you understand concurrency well, we are discouraging you
from taking this shortcut at all in your solution.  If you are unable
to solve a particular synchronization problem with semaphores, locks,
or conditions, or think that they are inadequate for a particular
reason, you may turn to disabling interrupts.  If you want to do this,
we require in your design document a complete justification and
scenario (i.e.@: exact sequence of events) to show why interrupt
manipulation is the best solution.  If you are unsure, the TAs can
help you determine if you are using interrupts too haphazardly.  We
want to emphasize that there are only limited cases where this is
appropriate.

You might find @file{devices/intq.h} and its users to be an
inspiration or source of rationale.

@item
@b{Where might interrupt-level manipulation be appropriate?}

You might find it necessary in some solutions to the Alarm problem.

You might want it at one small point for the priority scheduling
problem.  Note that it is not required to use interrupts for these
problems.  There are other, equally correct solutions that do not
require interrupt manipulation.  However, if you do manipulate
interrupts and @strong{correctly and fully document it} in your design
document, we will allow limited use of interrupt disabling.

@item
@b{What does ``warning: no previous prototype for `@var{function}''
mean?}

It means that you defined a non-@code{static} function without
preceding it by a prototype.  Because non-@code{static} functions are
intended for use by other @file{.c} files, for safety they should be
prototyped in a header file included before their definition.  To fix
the problem, add a prototype in a header file that you include, or, if
the function isn't actually used by other @file{.c} files, make it
@code{static}.
@end enumerate

@menu
* Problem 1-1 Alarm Clock FAQ::  
* Problem 1-2 Join FAQ::        
* Problem 1-3 Priority Scheduling FAQ::  
* Problem 1-4 Advanced Scheduler FAQ::  
@end menu

@node Problem 1-1 Alarm Clock FAQ
@subsection Problem 1-1: Alarm Clock FAQ

@enumerate 1
@item
@b{Why can't I use most synchronization primitives in an interrupt
handler?}

As you've discovered, you cannot sleep in an external interrupt
handler.  Since many lock, semaphore, and condition variable functions
attempt to sleep, you won't be able to call those in
@func{timer_interrupt}.  You may still use those that never sleep.

Having said that, you need to make sure that global data does not get
updated by multiple threads simultaneously executing
@func{timer_sleep}.  Here are some pieces of information to think
about:

@enumerate a
@item
Interrupts are turned off while @func{timer_interrupt} runs.  This
means that @func{timer_interrupt} will not be interrupted by a
thread running in @func{timer_sleep}.

@item
A thread in @func{timer_sleep}, however, can be interrupted by a
call to @func{timer_interrupt}, except when that thread has turned
off interrupts.

@item
Examples of synchronization mechanisms have been presented in lecture.
Going over these examples should help you understand when each type is
useful or needed.  @xref{Synchronization}, for specific information
about synchronization in Pintos.
@end enumerate

@item
@b{What about timer overflow due to the fact that times are defined as
integers? Do I need to check for that?}

Don't worry about the possibility of timer values overflowing.  Timer
values are expressed as signed 63-bit numbers, which at 100 ticks per
second should be good for almost 2,924,712,087 years.

@item
@b{The test program mostly works but reports a few out-of-order
wake ups.  I think it's a problem in the test program.  What gives?}
@anchor{Out of Order 1-1}

This test is inherently full of race conditions.  On a real system it
wouldn't work perfectly all the time either.  There are a few ways you
can help it work more reliably:

@itemize @bullet
@item
Make time slices longer by increasing @code{TIME_SLICE} in
@file{timer.c} to a large value, such as 100.

@item
Make the timer tick more slowly by decreasing @code{TIMER_FREQ} in
@file{timer.h} to its minimum value of 19.
@end itemize

The former two changes are only desirable for testing problem 1-1 and
possibly 1-3.  You should revert them before working on other parts
of the project or turn in the project.

@item
@b{Should @file{p1-1.c} be expected to work with the MLFQS turned on?}

No.  The MLFQS will adjust priorities, changing thread ordering.
@end enumerate

@node Problem 1-2 Join FAQ
@subsection Problem 1-2: Join FAQ

@enumerate 1
@item
@b{Am I correct to assume that once a thread is deleted, it is no
longer accessible by the parent (i.e.@: the parent can't call
@code{thread_join(child)})?}

A parent joining a child that has completed should be handled
gracefully and should act as a no-op.
@end enumerate

@node Problem 1-3 Priority Scheduling FAQ
@subsection Problem 1-3: Priority Scheduling FAQ

@enumerate 1
@item
@b{Doesn't the priority scheduling lead to starvation? Or do I have to
implement some sort of aging?}

It is true that strict priority scheduling can lead to starvation
because thread may not run if a higher-priority thread is runnable.
In this problem, don't worry about starvation or any sort of aging
technique.  Problem 4 will introduce a mechanism for dynamically
changing thread priorities.

This sort of scheduling is valuable in real-time systems because it
offers the programmer more control over which jobs get processing
time.  High priorities are generally reserved for time-critical
tasks. It's not ``fair,'' but it addresses other concerns not
applicable to a general-purpose operating system.

@item
@b{After a lock has been released, does the program need to switch to
the highest priority thread that needs the lock (assuming that its
priority is higher than that of the current thread)?}

When a lock is released, the highest priority thread waiting for that
lock should be unblocked and put on the ready to run list.  The
scheduler should then run the highest priority thread on the ready
list.

@item
@b{If a thread calls @func{thread_yield} and then it turns out that
it has higher priority than any other threads, does the high-priority
thread continue running?}

Yes.  If there is a single highest-priority thread, it continues
running until it blocks or finishes, even if it calls
@func{thread_yield}.

@item
@b{If the highest priority thread is added to the ready to run list it
should start execution immediately.  Is it immediate enough if I
wait until next timer interrupt occurs?}

The highest priority thread should run as soon as it is runnable,
preempting whatever thread is currently running.

@item
@b{What happens to the priority of the donating thread?  Do the priorities
get swapped?}

No.  Priority donation only changes the priority of the low-priority
thread.  The donating thread's priority stays unchanged.  Also note
that priorities aren't additive: if thread A (with priority 5) donates
to thread B (with priority 3), then B's new priority is 5, not 8.

@item 
@b{Can a thread's priority be changed while it is sitting on the ready
queue?}

Yes.  Consider this case: low-priority thread L currently has a lock
that high-priority thread H wants.  H donates its priority to L (the
lock holder).  L finishes with the lock, and then loses the CPU and is
moved to the ready queue.  Now L's old priority is restored while it
is in the ready queue.

@item
@b{Can a thread's priority change while it is sitting on the queue of a
semaphore?}

Yes.  Same scenario as above except L gets blocked waiting on a new
lock when H restores its priority.

@item
@b{Why is @file{p1-3.c}'s FIFO test skipping some threads?  I know my
scheduler is round-robin'ing them like it's supposed to.   Our output
starts out okay, but toward the end it starts getting out of order.}

The usual problem is that the serial output buffer fills up.  This is
causing serial_putc() to block in thread @var{A}, so that thread
@var{B} is scheduled.  Thread @var{B} immediately tries to do output
of its own and blocks on the serial lock (which is held by thread
@var{A}).  Now that we've wasted some time in scheduling and locking,
typically some characters have been drained out of the serial buffer
by the interrupt handler, so thread @var{A} can continue its output.
After it finishes, though, some other thread (not @var{B}) is
scheduled, because thread @var{B} was already scheduled while we
waited for the buffer to drain.

There's at least one other possibility.  Context switches are being
invoked by the test when it explicitly calls @func{thread_yield}.
However, the time slice timer is still alive and so, every tick (by
default), a thread gets switched out (caused by @func{timer_interrupt}
calling @func{intr_yield_on_return}) before it gets a chance to run
@func{printf}, effectively skipping it.  If we use a different jitter
value, the same behavior is seen where a thread gets started and
switched out completely.

Normally you can fix these problems using the same techniques
suggested on problem 1-1 (@pxref{Out of Order 1-1}).

@item
@b{What happens when a thread is added to the ready list which has
higher priority than the currently running thread?}

The correct behavior is to immediately yield the processor.  Your
solution must act this way.

@item
@b{What should @func{thread_get_priority} return in a thread while
its priority has been increased by a donation?}

The higher (donated) priority.

@item
@b{Should @file{p1-3.c} be expected to work with the MLFQS turned on?}

No.  The MLFQS will adjust priorities, changing thread ordering.

@item
@b{@func{printf} in @func{sema_up} or @func{sema_down} makes the
system reboot!}

Yes.  These functions are called before @func{printf} is ready to go.
You could add a global flag initialized to false and set it to true
just before the first @func{printf} in @func{main}.  Then modify
@func{printf} itself to return immediately if the flag isn't set.
@end enumerate

@node Problem 1-4 Advanced Scheduler FAQ
@subsection Problem 1-4: Advanced Scheduler FAQ

@enumerate 1
@item
@b{What is the interval between timer interrupts?}

Timer interrupts occur @code{TIMER_FREQ} times per second.  You can
adjust this value by editing @file{devices/timer.h}.  The default is
100 Hz.

You can also adjust the number of timer ticks per time slice by
modifying @code{TIME_SLICE} in @file{devices/timer.c}.

@item
@b{Do I have to modify the dispatch table?}

No, although you are allowed to. It is possible to complete
this problem (i.e.@: demonstrate response time improvement)
without doing so.

@item
@b{When the scheduler changes the priority of a thread, how does this
affect priority donation?}

Short (official) answer: Don't worry about it. Your priority donation
code may assume static priority assignment.

Longer (unofficial) opinion: If you wish to take this into account,
however, your design may end up being ``cleaner.''  You have
considerable freedom in what actually takes place. I believe what
makes the most sense is for scheduler changes to affect the
``original'' (non-donated) priority.  This change may actually be
masked by the donated priority.  Priority changes should only
propagate with donations, not ``backwards'' from donees to donors.

@item
@b{What is meant by ``static priority''?}

Once thread A has donated its priority to thread B, if thread A's
priority changes (due to the scheduler) while the donation still
exists, you do not have to change thread B's donated priority.
However, you are free to do so.

@item
@b{Do I have to make my dispatch table user-configurable?}

No.  Hard-coding the dispatch table values is fine.
@end enumerate