Add examples of how to iterate and remove elements from a list.

[pintos-anon] / doc / threads.texi

diff --git a/doc/threads.texi b/doc/threads.texi
index 314ee61ca865aef58c4cb51cc4260eea8a965001..b84a8f6e7ebffc397d55681e6169f4d800e7ef7f 100644 (file)
--- a/doc/threads.texi
+++ b/doc/threads.texi
@@ -531,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.
 
 @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 ++++++++++++++++++
 @verbatim
  devices/timer.c       |   42 +++++-
  threads/fixed-point.h |  120 ++++++++++++++++++


@@ -591,6 +597,34 @@ to cause many of the tests to fail.
 @item How do I run the tests?
 
 @xref{Testing}.
 @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
 @end table
 
 @menu


@@ -647,8 +681,8 @@ If multiple threads have the same highest priority,
 
 Priority donation only changes the priority of the donee
 thread.  The donor thread's priority is unchanged.  
 
 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?
 
 
 @item Can a thread's priority change while it is on the ready queue?
 


@@ -689,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.
 
 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
 @end table