X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fthreads.texi;h=d353f2212ed12ad5e64af51e830329ef572d8b9e;hb=bc4d80ea366522bd5aa51d9c371c47deca10c69f;hp=2e779eecb40a613b0203f999120d14ad141fe4db;hpb=3c7843a633a3599801c806e32242512db9e6cca2;p=pintos-anon

diff --git a/doc/threads.texi b/doc/threads.texi
index 2e779ee..d353f22 100644
--- a/doc/threads.texi
+++ b/doc/threads.texi
@@ -74,7 +74,7 @@ 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
+@code{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
@@ -133,12 +133,13 @@ above.
 
 @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.
+the kernel.
 
 @item interrupt.c
 @itemx interrupt.h
@@ -170,7 +171,108 @@ directories and page tables.  This will be more important to you in
 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.  @code{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, @code{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 @code{printf()} and a few other functions.
+@end table
 
 @node Debugging versus Testing
 @section Debugging versus Testing
@@ -321,6 +423,10 @@ 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
 
@@ -396,9 +502,6 @@ it on by inserting the line @code{#define MLFQS 1} in
 @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
@@ -429,14 +532,6 @@ 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{If a thread finishes, should its children be terminated immediately,
-or should they finish normally?}
-
-You should feel free to decide what semantics you think this
-should have. You need only provide justification for your
-decision.
-
 @item
 @b{Why can't I disable interrupts?}
 
@@ -475,9 +570,29 @@ 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
 
-@item Alarm Clock FAQs
+@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
@@ -520,7 +635,8 @@ 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
+@node Problem 1-2 Join FAQ
+@subsection Problem 1-2: Join FAQ
 
 @enumerate 1
 @item
@@ -532,7 +648,8 @@ A parent joining a child that has completed should be handled
 gracefully and should act as a no-op.
 @end enumerate
 
-@item Priority Scheduling FAQs
+@node Problem 1-3 Priority Scheduling FAQ
+@subsection Problem 1-3: Priority Scheduling FAQ
 
 @enumerate 1
 @item
@@ -658,7 +775,8 @@ its priority has been increased by a donation?}
 The higher (donated) priority.
 @end enumerate
 
-@item Advanced Scheduler FAQs
+@node Problem 1-4 Advanced Scheduler FAQ
+@subsection Problem 1-4: Advanced Scheduler FAQ
 
 @enumerate 1
 @item
@@ -706,4 +824,3 @@ However, you are free to do so.
 
 No.  Hard-coding the dispatch table values is fine.
 @end enumerate
-@end enumerate