Use macros for 8259A PIC registers, instead of writing them literally.
[pintos-anon] / doc / threads.texi
index cbcda160631b2c918c23d9d81e9ce4277a10be23..6eec6bb1ea5a44d1620b04faf8108b879d7ad5f1 100644 (file)
@@ -40,7 +40,7 @@ The first step is to read and understand the code for the initial thread
 system.
 Pintos already implements thread creation and thread completion,
 a simple scheduler to switch between threads, and synchronization
-primitives (semaphores, locks, condition variables, and memory
+primitives (semaphores, locks, condition variables, and optimization
 barriers).
 
 Some of this code might seem slightly mysterious.  If
@@ -170,7 +170,7 @@ Infrastructure}, for more information.
 @item synch.c
 @itemx synch.h
 Basic synchronization primitives: semaphores, locks, condition
-variables, and memory barriers.  You will need to use these for
+variables, and optimization barriers.  You will need to use these for
 synchronization in all
 four projects.  @xref{Synchronization}, for more information.
 
@@ -364,13 +364,7 @@ with each other, requiring lots of last-minute debugging.  Some groups
 who have done this have turned in code that did not even compile or
 boot, much less pass any tests.
 
-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.
+@localcvspolicy{}
 
 You should expect to run into bugs that you simply don't understand
 while working on this and subsequent projects.  When you do,
@@ -480,9 +474,9 @@ priority.  If necessary, you may impose a reasonable limit on depth of
 nested priority donation, such as 8 levels.
 
 You must implement priority donation for locks.  You need not
-implement priority donation for semaphores or condition variables
-(but you are welcome to do so).  You do need to implement
-priority scheduling in all cases.
+implement priority donation for the other Pintos synchronization
+constructs.  You do need to implement priority scheduling in all
+cases.
 
 Finally, implement the following functions that allow a thread to
 examine and modify its own priority.  Skeletons for these functions are
@@ -524,7 +518,7 @@ scheduler
 with the @option{-mlfqs} kernel option.  Passing this
 option sets @code{thread_mlfqs}, declared in @file{threads/thread.h}, to
 true when the options are parsed by @func{parse_options}, which happens
-midway through @func{main}.
+early in @func{main}.
 
 When the 4.4@acronym{BSD} scheduler is enabled, threads no longer
 directly control their own priorities.  The @var{priority} argument to
@@ -633,7 +627,7 @@ does not actually mean that @func{pass} called @func{debug_panic}.  In
 fact, @func{fail} called @func{debug_panic} (via the @func{PANIC}
 macro).  GCC knows that @func{debug_panic} does not return, because it
 is declared @code{NO_RETURN} (@pxref{Function and Parameter
-Attributes}), so it doesn't include any code in @func{pass} to take
+Attributes}), so it doesn't include any code in @func{fail} to take
 control when @func{debug_panic} returns.  This means that the return
 address on the stack looks like it is at the beginning of the function
 that happens to follow @func{fail} in memory, which in this case happens
@@ -696,7 +690,7 @@ kernel thread but the first.
 Don't worry about the possibility of timer values overflowing.  Timer
 values are expressed as signed 64-bit numbers, which at 100 ticks per
 second should be good for almost 2,924,712,087 years.  By then, we
-expect Pintos to have been phased out of the CS 140 curriculum.
+expect Pintos to have been phased out of the @value{coursenumber} curriculum.
 @end table
 
 @node Priority Scheduling FAQ
@@ -740,11 +734,9 @@ to thread @var{B} (with priority 3), then @var{B}'s new priority is 5, not 8.
 
 @item Can a thread's priority change while it is on the ready queue?
 
-Yes.  Consider this case: low-priority thread @var{L} holds a
-lock that high-priority thread @var{H} wants, so @var{H} donates its
-priority to @var{L}.  @var{L} releases the lock and
-thus loses the CPU and is moved to the ready queue.  Now @var{L}'s
-old priority is restored while it is in the ready queue.
+Yes.  Consider a ready, low-priority thread @var{L} that holds a lock.
+High-priority thread @var{H} attempts to acquire the lock and blocks,
+thereby donating its priority to ready thread @var{L}.
 
 @item Can a thread's priority change while it is blocked?
 
@@ -768,14 +760,6 @@ becomes the higher of the newly set priority or the highest donated
 priority.  When the donations are released, the thread's priority
 becomes the one set through the function call.  This behavior is checked
 by the @code{priority-donate-lower} test.
-
-@item Calling @func{printf} in @func{sema_up} or @func{sema_down} reboots!
-
-@anchor{printf Reboots}
-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 table
 
 @node Advanced Scheduler FAQ
@@ -791,4 +775,32 @@ scheduler at the same time.
 
 Yes.  In general, your implementation may differ from the description,
 as long as its behavior is the same.
+
+@item Some scheduler tests fail and I don't understand why.  Help!
+
+If your implementation mysteriously fails some of the advanced
+scheduler tests, try the following:
+
+@itemize
+@item
+Read the source files for the tests that you're failing, to make sure
+that you understand what's going on.  Each one has a comment at the
+top that explains its purpose and expected results.
+
+@item
+Double-check your fixed-point arithmetic routines and your use of them
+in the scheduler routines.
+
+@item
+Consider how much work your implementation does in the timer
+interrupt.  If the timer interrupt handler takes too long, then it
+will take away most of a timer tick from the thread that the timer
+interrupt preempted.  When it returns control to that thread, it
+therefore won't get to do much work before the next timer interrupt
+arrives.  That thread will therefore get blamed for a lot more CPU
+time than it actually got a chance to use.  This raises the
+interrupted thread's recent CPU count, thereby lowering its priority.
+It can cause scheduling decisions to change.  It also raises the load
+average.
+@end itemize
 @end table