-@node Project 1--Threads, Project 2--User Programs, Introduction, Top
+@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.
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::
+* Problem 1-2 Priority Scheduling::
+* Problem 1-3 Advanced Scheduler::
* Threads FAQ::
@end menu
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 @code{printf()} almost
+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
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 @code{thread_create()}. The first time the thread is
+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 @code{thread_create()}
-acting like @code{main()}.
+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
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 @code{schedule()} function to start out, and then
-single-step from there. 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
-@code{switch_threads()}, another thread starts running, and the first
-thing the new thread does is to return from
-@code{switch_threads()}. We realize this comment will seem cryptic to
-you at this point, but you will understand threads once you understand
-why the @code{switch_threads()} that gets called is different from the
-@code{switch_threads()} that returns. @c FIXME
+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
-ma cause bizarre problems, such as mysterious kernel panics, if 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 @code{malloc()} has a @w{2 kB} block size
+@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.
or modify it, but it's here in case you're curious.
@item start.S
-Jumps to @code{main()}.
+Jumps to @func{main}.
@item init.c
@itemx init.h
-Kernel initialization, including @code{main()}, the kernel's ``main
-program.'' You should look over @code{main()} at least to see what
+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 @code{struct thread}, which you will
+files. @file{thread.h} defines @struct{thread}, which you will
modify in the first three projects.
@item switch.S
@item palloc.c
@itemx palloc.h
-Page allocator, which hands out system memory one 4 kB page at a time.
+Page allocator, which hands out system memory in multiples of 4 kB
+pages.
@item malloc.c
@itemx malloc.h
-A very simple implementation of @code{malloc()} and @code{free()} for
-the kernel. The largest block that can be allocated is 2 kB.
+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
+@item intr-stubs.S
@itemx intr-stubs.h
-A Perl program that outputs assembly for low-level interrupt handling.
+Assembly code for low-level interrupt handling.
@item synch.c
@itemx synch.h
project 3. For now, you can ignore it.
@end table
-FIXME devices and lib directories?
+@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
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. If you use the Bochs configuration files we provide,
-which specify @samp{ips: @var{n}} where @var{n} is a number of
-simulated instructions per second, your simulations can be
-reproducible.
+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
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 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
+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
-There should be no busy-waiting in any of your solutions to this
-assignment. Furthermore, resist the temptation to directly disable
-interrupts in your solution by calling @code{intr_disable()} or
-@code{intr_set_level()}, although you may find doing so to be useful
-while debugging. Instead, use semaphores, locks and condition
-variables to solve synchronization problems. Hint: read the comments
-in @file{threads/synch.h} if you're unsure what synchronization
-primitives may be used in what situations.
-
-Given some designs of some problems, there may be one or two instances
-in which it is appropriate to directly change the interrupt levels
-instead of relying on the given synchroniztion primitives. This must
-be justified in your @file{DESIGNDOC} file. If you're not sure you're
-justified, ask!
-
-While all parts of this assignment are required if you intend to earn
-full credit on this project, keep in mind that Problem 1-2 (Join) will
-be needed for future assignments, so you'll want to get this one
-right. We don't give out solutions, so you're stuck with your Join
-code for the whole quarter. Problem 1-1 (Alarm Clock) could be very
-handy, but not strictly required in the future. The upshot of all
-this is that you should focus heavily on making sure that your
-implementation of @code{thread_join()} works correctly, since if it's
-broken, you will need to fix it for future assignments. The other
-parts can be turned off in the future if you find you can't make them
-work quite right.
-
-Also keep in mind that Problem 1-4 (the MLFQS) builds on the features you
-implement in Problem 1-3, so to avoid unnecessary code duplication, it
-would be a good idea to divide up the work among your team members
-such that you have Problem 1-3 fully working before you begin to tackle
-Problem 1-4.
+@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. Problem 1-1 (Alarm Clock) could be handy for
+later projects, but it is not strictly required. Problems 1-2
+(Priority Scheduling) and 1-3 (Advanced Scheduler) won't be needed for
+later projects.
+
+@item
+Problem 1-3 (MLFQS) builds on the features you implement in Problem
+1-2. You should have Problem 1-2 fully working before you begin to
+tackle Problem 1-3.
+
+@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.
+
+@item
+You should expect to run into bugs that you simply don't understand
+while working on this and subsequent projects. When you do, go back
+and reread the appendix on debugging tools, which is filled with
+useful debugging tips that should help you to get back up to speed
+(@pxref{Debugging Tools}). Be sure to read the section on backtraces
+(@pxref{Backtraces}), which will help you to get the most out of every
+kernel panic or assertion failure.
+@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 @code{timer_sleep()}.
+@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
could potentially be used more profitably by another thread. Your
solution should not busy wait.
-The argument to @code{timer_sleep()} is expressed in timer ticks, not
-in milliseconds or some other unit.
-
-@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 A is the running thread and B is the argument, then we say
-that ``A joins B'' in this case.
-
-Incidentally, we don't use @code{struct thread *} as
-@file{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 A over time had two children B and C that were stored at the
-same address, then @code{thread_join(@r{B})} and
-@code{thread_join(@r{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 @code{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 @code{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 @code{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 @code{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 (A joins B when B
-is joined on C), multiple joins (A joins B, then A joins C), and so
-on. Does your join work if @code{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 @code{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
+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 Priority Scheduling
+@section Problem 1-2: Priority Scheduling
Implement priority scheduling in Pintos. Priority scheduling is a key
building block for real-time systems. Implement functions
-@code{thread_set_priority()} to set the priority of the running thread
-and @code{thread_get_priority()} to get the running thread's priority.
-(A thread can examine and modify only its own priority.) There are
-already prototypes for these functions in @file{threads/thread.h},
-which you should not change.
+@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
-@code{thread_create()}. If there's no reason to choose another
+@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.
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's
-priority may be set at any time, including while the thread is waiting
-on a lock, semaphore, or condition variable.
+highest priority waiting thread should be woken up first. A thread
+may raise or lower its own priority at any time, but lowering its
+priority such that it no longer has the highest priority must cause it
+to immediately yield the CPU.
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
-@code{thread_join()} for a thread to complete), and a middle priority
+instance, for a lock held by a low priority thread), 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
the lock, then recall the donation once it has acquired the lock.
Implement this fix.
-You will need to account for all different orders that priority
+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 H, M, and L, respectively, if H is waiting on a lock that M
-holds and M is waiting on a lock that L holds, then both M and L
-should be boosted to H's 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.
-However, you do need to implement priority scheduling in all cases.
+implement this fix for semaphores or condition variables
+although you are welcome to do so. However, you do need to implement
+priority scheduling in all cases.
-@node Problem 1-4 Advanced Scheduler
-@section Problem 1-4: Advanced Scheduler
+@node Problem 1-3 Advanced Scheduler
+@section Problem 1-3: Advanced Scheduler
Implement Solaris's multilevel feedback queue scheduler (MLFQS) to
reduce the average response time for running jobs on your system.
at least one workload of your own design (i.e.@: in addition to the
provided test).
-You may assume a static priority for this problem. It is not necessary
-to ``re-donate'' a thread's priority if it changes (although you are
-free to do so).
-
-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.
+You must write your code so that we can choose a scheduling algorithm
+policy at Pintos startup time. By default, the round-robin scheduler
+must be active, but we must be able to choose the MLFQS by invoking
+@command{pintos} with the @option{-o mlfqs} option. Passing this
+option sets @code{enable_mlfqs}, declared in @file{threads/init.h}, to
+true.
@node Threads FAQ
@section FAQ
-@enumerate 1
-@item General FAQs
-
@enumerate 1
@item
@b{I am adding a new @file{.h} or @file{.c} file. How do I fix the
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 condition.
+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
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
-@item Alarm Clock FAQs
+@menu
+* Problem 1-1 Alarm Clock FAQ::
+* Problem 1-2 Priority Scheduling FAQ::
+* Problem 1-3 Advanced Scheduler FAQ::
+@end menu
+
+@node Problem 1-1 Alarm Clock FAQ
+@subsection Problem 1-1: Alarm Clock FAQ
@enumerate 1
@item
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
-@code{timer_interrupt()}. You may still use those that never sleep.
+@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
-@code{timer_sleep()}. Here are some pieces of information to think
+@func{timer_sleep}. Here are some pieces of information to think
about:
@enumerate a
@item
-Interrupts are turned off while @code{timer_interrupt()} runs. This
-means that @code{timer_interrupt()} will not be interrupted by a
-thread running in @code{timer_sleep()}.
+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 @code{timer_sleep()}, however, can be interrupted by a
-call to @code{timer_interrupt()}, except when that thread has turned
+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.
+useful or needed. @xref{Synchronization}, for specific information
+about synchronization in Pintos.
@end enumerate
@item
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.
-@end enumerate
-@item Join FAQs
+@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.
-@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)})?}
+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-2. You should revert them before working on other parts
+of the project or turn in the project. We will test problem 1-1 with
+@code{TIME_SLICE} set to 100 and @code{TIMER_FREQ} set to 19, but we
+will leave them at their defaults for all the other problems.
-A parent joining a child that has completed should be handled
-gracefully and should act as a no-op.
+@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
-@item Priority Scheduling FAQs
+@node Problem 1-2 Priority Scheduling FAQ
+@subsection Problem 1-2: Priority Scheduling FAQ
@enumerate 1
@item
list.
@item
-@b{If a thread calls @code{thread_yield()} and then it turns out that
+@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
-@code{thread_yield()}.
+@func{thread_yield}.
@item
@b{If the highest priority thread is added to the ready to run list it
lock when H restores its priority.
@item
-@b{Why is pubtest3's FIFO test skipping some threads! I know my scheduler
-is round-robin'ing them like it's supposed to! Our output is like this:}
-
-@example
-Thread 0 goes.
-Thread 2 goes.
-Thread 3 goes.
-Thread 4 goes.
-Thread 0 goes.
-Thread 1 goes.
-Thread 2 goes.
-Thread 3 goes.
-Thread 4 goes.
-@end example
-
-@noindent @b{which repeats 5 times and then}
-
-@example
-Thread 1 goes.
-Thread 1 goes.
-Thread 1 goes.
-Thread 1 goes.
-Thread 1 goes.
-@end example
-
-This happens because context switches are being invoked by the test
-when it explicitly calls @code{thread_yield()}. However, the time
-slice timer is still alive and so, every tick (by default), thread 1
-gets switched out (caused by @code{timer_interrupt()} calling
-@code{intr_yield_on_return()}) before it gets a chance to run its
-mainline. It is by coincidence that Thread 1 is the one that gets
-skipped in our example. If we use a different jitter value, the same
-behavior is seen where a thread gets started and switched out
-completely.
-
-Solution: Increase the value of @code{TIME_SLICE} in
-@file{devices/timer.c} to a very high value, such as 10000, to see
-that the threads will round-robin if they aren't interrupted.
+@b{Why is @file{p1-2.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
solution must act this way.
@item
-@b{What should @code{thread_get_priority()} return in a thread while
+@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-2.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
-@item Advanced Scheduler FAQs
+@node Problem 1-3 Advanced Scheduler FAQ
+@subsection Problem 1-3: Advanced Scheduler FAQ
@enumerate 1
@item
No. Hard-coding the dispatch table values is fine.
@end enumerate
-@end enumerate
projects / pintos-anon / blobdiff