X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fthreads.texi;h=8f07bb792ff461e512c770818efc7bfb11550a17;hb=8abbb333aea445641d967befd3ca477502ea770b;hp=f538d8382b2f1554f4457e0241325f3e95ecae62;hpb=90823ae32d93d84129ea163c48cb59a6bfaaa82c;p=pintos-anon

diff --git a/doc/threads.texi b/doc/threads.texi
index f538d83..8f07bb7 100644
--- a/doc/threads.texi
+++ b/doc/threads.texi
@@ -185,8 +185,8 @@ project 3.  For now, you can ignore it.
 
 @item flags.h
 Macros that define a few bits in the 80@var{x}86 ``flags'' register.
-Probably of no interest.  See @bibref{IA32-v1}, section 3.4.3, for more
-information.
+Probably of no interest.  See @bibref{IA32-v1}, section 3.4.3, ``EFLAGS
+Register,'' for more information.
 @end table
 
 @menu
@@ -328,9 +328,14 @@ timer ticks or input events.  Turning off interrupts also increases the
 interrupt handling latency, which can make a machine feel sluggish if
 taken too far.
 
+You may need to add or modify code where interrupts are already
+disabled, such as in @func{sema_up} or @func{sema_down}.  You should
+still try to keep this code as short as you can.
+
 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.
+debugging code before turning in your project.  (Don't just comment it
+out, because that can make the code difficult to read.)
 
 There should be no busy waiting in your submission.  A tight loop that
 calls @func{thread_yield} is one form of busy waiting.
@@ -459,11 +464,12 @@ multiple donations, in which multiple priorities are donated to a single
 thread.  You must also handle nested donation: 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.
+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
+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.
 
 Finally, implement the following functions that allow a thread to
@@ -480,6 +486,9 @@ Returns the current thread's priority.  In the presence of priority
 donation, returns the higher (donated) priority.
 @end deftypefun
 
+You need not provide any interface to allow a thread to directly modify
+other threads' priorities.
+
 The priority scheduler is not used in any later project.
 
 @node Advanced Scheduler
@@ -488,15 +497,16 @@ The priority scheduler is not used in any later project.
 Implement a multilevel feedback queue scheduler similar to the
 4.4@acronym{BSD} scheduler to
 reduce the average response time for running jobs on your system.
-@xref{4.4BSD Scheduler}, for a detailed description of
-the MLFQS requirements.
+@xref{4.4BSD Scheduler}, for detailed requirements.
 
-The advanced scheduler builds on the priority scheduler.  You should
-have the priority scheduler working, except possibly for priority
-donation, before you start work on the advanced scheduler.
+Like the priority scheduler, the advanced scheduler chooses the thread
+to run based on priorities.  However, the advanced scheduler does not do
+priority donation.  Thus, we recommend that you have the priority
+scheduler working, except possibly for priority donation, before you
+start work on the advanced scheduler.
 
-You must write your code so that we can choose a scheduling algorithm
-policy at Pintos startup time.  By default, the round-robin scheduler
+You must write your code to allow us to choose a scheduling algorithm
+policy at Pintos startup time.  By default, the priority scheduler
 must be active, but we must be able to choose the 4.4@acronym{BSD}
 scheduler
 with the @option{-mlfqs} kernel option.  Passing this
@@ -521,6 +531,12 @@ Here's a summary of our reference solution, produced by the
 @command{diffstat} program.  The final row gives total lines inserted
 and deleted; a changed line counts as both an insertion and a deletion.
 
+The reference solution represents just one possible solution.  Many
+other solutions are also possible and many of those differ greatly from
+the reference solution.  Some excellent solutions may not modify all the
+files modified by the reference solution, and some may modify files not
+modified by the reference solution.
+
 @verbatim
  devices/timer.c       |   42 +++++-
  threads/fixed-point.h |  120 ++++++++++++++++++
@@ -575,8 +591,40 @@ to cause many of the tests to fail.
 There are @code{TIME_SLICE} ticks per time slice.  This macro is
 declared in @file{threads/thread.c}.  The default is 4 ticks.
 
-We don't recommend changing this values, because any changes are likely
+We don't recommend changing this value, because any changes are likely
 to cause many of the tests to fail.
+
+@item How do I run the tests?
+
+@xref{Testing}.
+
+@item Why do I get a test failure in @func{pass}?
+
+@anchor{The pass function fails}
+You are probably looking at a backtrace that looks something like this:
+
+@example
+0xc0108810: debug_panic (../../lib/kernel/debug.c:32)
+0xc010a99f: pass (../../tests/threads/tests.c:93)
+0xc010bdd3: test_mlfqs_load_1 (../../tests/threads/mlfqs-load-1.c:33)
+0xc010a8cf: run_test (../../tests/threads/tests.c:51)
+0xc0100452: run_task (../../threads/init.c:283)
+0xc0100536: run_actions (../../threads/init.c:333)
+0xc01000bb: main (../../threads/init.c:137)
+@end example
+
+This is just confusing output from the @command{backtrace} program.  It
+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
+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
+to be @func{pass}.
+
+@xref{Backtraces}, for more information.
 @end table
 
 @menu
@@ -626,15 +674,15 @@ list.
 Yes.  As long as there is a single highest-priority thread, it continues
 running until it blocks or finishes, even if it calls
 @func{thread_yield}.
-If there are multiple threads have the same highest priority,
+If multiple threads have the same highest priority,
 @func{thread_yield} should switch among them in ``round robin'' order.
 
 @item What happens to the priority of a donating thread?
 
 Priority donation only changes the priority of the donee
 thread.  The donor thread's priority is unchanged.  
-Priority donation is not additive: if thread @var{A} (with priority 5) donates
-to thread @var{B} (with priority 3), then @var{B}'s new priority is 5, not 8.
+Priority donation is not additive: if thread @var{A} (with priority 3) donates
+to thread @var{B} (with priority 5), then @var{B}'s new priority is 3, not 8.
 
 @item Can a thread's priority change while it is on the ready queue?
 
@@ -652,6 +700,12 @@ processor.  It is not acceptable to wait for the next timer interrupt.
 The highest priority thread should run as soon as it is runnable,
 preempting whatever thread is currently running.
 
+@item How does @func{thread_set_priority} affect a thread receiving donations?
+
+It should do something sensible, but no particular behavior is
+required.  None of the test cases call @func{thread_set_priority} from a
+thread while it is receiving a priority donation.
+
 @item Calling @func{printf} in @func{sema_up} or @func{sema_down} reboots!
 
 @anchor{printf Reboots}
@@ -669,4 +723,12 @@ just before the first @func{printf} in @func{main}.  Then modify
 
 It doesn't have to.  We won't test priority donation and the advanced
 scheduler at the same time.
+
+@item Can I use one queue instead of 64 queues?
+
+Yes, that's fine.  It's easiest to describe the algorithm in terms of 64
+separate queues, but that doesn't mean you have to implement it that
+way.
+
+If you use a single queue, it should probably be sorted.
 @end table