@item loader.S
@itemx loader.h
The kernel loader. Assembles to 512 bytes of code and data that the
-PC BIOS loads into memory and which in turn loads the kernel into
-memory, does basic processor initialization, and jumps to the
-beginning of the kernel. @xref{Pintos Loader}, for details. You should
-not need to look at this code or modify it.
+PC BIOS loads into memory and which in turn finds the kernel on disk,
+loads it into memory, and jumps to @func{start} in @file{start.S}.
+@xref{Pintos Loader}, for details. You should not need to look at
+this code or modify it.
+
+@item start.S
+Does basic setup needed for memory protection and 32-bit
+operation on 80@var{x}86 CPUs. Unlike the loader, this code is
+actually part of the kernel. @xref{Low-Level Kernel Initialization},
+for details.
@item kernel.lds.S
The linker script used to link the kernel. Sets the load address of
-the kernel and arranges for @file{start.S} to be at the very beginning
+the kernel and arranges for @file{start.S} to be near the beginning
of the kernel image. @xref{Pintos Loader}, for details. Again, you
should not need to look at this code
or modify it, but it's here in case you're curious.
-@item start.S
-Jumps to @func{main}.
-
@item init.c
@itemx init.h
Kernel initialization, including @func{main}, the kernel's ``main
program.'' You should look over @func{main} at least to see what
gets initialized. You might want to add your own initialization code
-here. @xref{Kernel Initialization}, for details.
+here. @xref{High-Level Kernel Initialization}, for details.
@item thread.c
@itemx thread.h
so you don't need to do so yourself.
It handles serial input by passing it to the input layer (see below).
-@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 block.c
+@itemx block.h
+An abstraction layer for @dfn{block devices}, that is, random-access,
+disk-like devices that are organized as arrays of fixed-size blocks.
+Out of the box, Pintos supports two types of block devices: IDE disks
+and partitions. Block devices, regardless of type, won't actually be
+used until project 2.
+
+@item ide.c
+@itemx ide.h
+Supports reading and writing sectors on up to 4 IDE disks.
+
+@item partition.c
+@itemx partition.h
+Understands the structure of partitions on disks, allowing a single
+disk to be carved up into multiple regions (partitions) for
+independent use.
@item kbd.c
@itemx kbd.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.
+
+@item rtc.c
+@itemx rtc.h
+Real-time clock driver, to enable the kernel to determine the current
+date and time. By default, this is only used by @file{thread/init.c}
+to choose an initial seed for the random number generator.
+
+@item speaker.c
+@itemx speaker.h
+Driver that can produce tones on the PC speaker.
+
+@item pit.c
+@itemx pit.h
+Code to configure the 8254 Programmable Interrupt Timer. This code is
+used by both @file{devices/timer.c} and @file{devices/speaker.c}
+because each device uses one of the PIT's output channel.
@end table
@node lib files
@item random.c
@itemx random.h
-Pseudo-random number generator.
+Pseudo-random number generator. The actual sequence of random values
+will not vary from one Pintos run to another, unless you do one of
+three things: specify a new random seed value on the @option{-rs}
+kernel command-line option on each run, or use a simulator other than
+Bochs, or specify the @option{-r} option to @command{pintos}.
@item round.h
Macros for rounding.
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 @value{coursenumber} curriculum.
+expect Pintos to have been phased out of the Computer Science curriculum.
@end table
@node Priority Scheduling FAQ
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 Doubled test names in output make them fail.
+
+Suppose you are seeing output in which some test names are doubled,
+like this:
+
+@example
+(alarm-priority) begin
+(alarm-priority) (alarm-priority) Thread priority 30 woke up.
+Thread priority 29 woke up.
+(alarm-priority) Thread priority 28 woke up.
+@end example
+
+What is happening is that output from two threads is being
+interleaved. That is, one thread is printing @code{"(alarm-priority)
+Thread priority 29 woke up.\n"} and another thread is printing
+@code{"(alarm-priority) Thread priority 30 woke up.\n"}, but the first
+thread is being preempted by the second in the middle of its output.
+
+This problem indicates a bug in your priority scheduler. After all, a
+thread with priority 29 should not be able to run while a thread with
+priority 30 has work to do.
+
+Normally, the implementation of the @code{printf()} function in the
+Pintos kernel attempts to prevent such interleaved output by acquiring
+a console lock during the duration of the @code{printf} call and
+releasing it afterwards. However, the output of the test name,
+e.g., @code{(alarm-priority)}, and the message following it is output
+using two calls to @code{printf}, resulting in the console lock being
+acquired and released twice.
@end table
@node Advanced Scheduler FAQ