@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.
-
-@item paging.c
-@itemx paging.h
-Initializes the kernel page table. FIXME
+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
doesn't give you any greater confidence in your code's correctness
than does running it only once.
-FIXME
So, to make your code easier to test, we've added a feature to Bochs
that makes timer interrupts come at random intervals, but in a
-perfectly predictable way. In particular, if you put a line
-@samp{ips-jitter: @var{seed}}, where @var{seed} is an integer, into
-your Bochs configuration file, then timer interrupts will come at
-irregularly spaced intervals. Within a single @var{seed} value,
-execution will still be reproducible, but timer behavior will change
-as @var{seed} is varied. Thus, for the highest degree of confidence
-you should test your code with many seed values.
+perfectly predictable way. In particular, if you invoke
+@command{pintos} with the option @option{-j @var{seed}}, timer
+interrupts will come at irregularly spaced intervals. Within a single
+@var{seed} value, execution will still be reproducible, but timer
+behavior will change as @var{seed} is varied. Thus, for the highest
+degree of confidence you should test your code with many seed values.
@node Tips
@section Tips
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
@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
projects / pintos-anon / blobdiff