@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
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
@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
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
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.
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
@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
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?}
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
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
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
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
No. Hard-coding the dispatch table values is fine.
@end enumerate
-@end enumerate