-@node Project 1--Threads, Project 2--User Programs, Top, Top
+@node Project 1--Threads, Project 2--User Programs, Introduction, Top
@chapter Project 1: Threads
In this assignment, we give you a minimally functional thread system.
@menu
* Understanding Threads::
+* Project 1 Code::
* Debugging versus Testing::
* Tips::
* Problem 1-1 Alarm Clock::
* Problem 1-2 Join::
* Problem 1-3 Priority Scheduling::
* Problem 1-4 Advanced Scheduler::
-* Threads FAQ::
-* Multilevel Feedback Scheduling::
+* Threads FAQ::
@end menu
-@node Understanding Threads, Debugging versus Testing, Project 1--Threads, Project 1--Threads
+@node Understanding Threads
@section Understanding Threads
The first step is to read and understand the initial thread system.
Pintos, by default, implements thread creation and thread completion,
a simple scheduler to switch between threads, and synchronization
primitives (semaphores, locks, and condition variables).
-@c FIXME: base system doesn't do anything. Debugger sucks.
-However, there's a lot of magic going on in some of this code, so you
-should compile and run the base system to see a simple test of the
-code. You should read through the source code by hand to see what's
-going on. If you like, you can add calls to @code{printf()} almost
+
+However, there's a lot of magic going on in some of this code, so if
+you haven't already compiled and run the base system, as described in
+the introduction (@pxref{Introduction}), you should do so now. You
+can read through parts of the source code by hand to see what's going
+on. If you like, you can add calls to @code{printf()} almost
anywhere, then recompile and run to see what happens and in what
-order.
+order. You can also run the kernel in a debugger and set breakpoints
+at interesting spots, single-step through code and examine data, and
+so on. @xref{i386-elf-gdb}, for more information.
When a thread is created, you are creating a new context to be
scheduled. You provide a function to be run in this context as an
assembly; don't worry about understanding it). It involves saving the
state of the currently running thread and restoring the state of the
thread we're switching to.
-@c FIXME
-Slowly trace through a context switch to see what happens. Be sure to
-keep track of each thread's address and state, and what procedures are
-on the call stack for each thread. You will notice that when one
-thread calls @code{switch_threads()}, another thread starts running,
-and the first thing the new thread does is to return from
-@code{switch_threads()}. We realize this comment will seem cryptic to
+
+Using the @command{gdb} debugger, slowly trace through a context
+switch to see what happens (@pxref{i386-elf-gdb}). You can set a
+breakpoint on the @code{schedule()} function to start out, and then
+single-step from there. Be sure to keep track of each thread's
+address and state, and what procedures are on the call stack for each
+thread. You will notice that when one thread calls
+@code{switch_threads()}, another thread starts running, and the first
+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.
@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
limit. If you need larger chunks, consider using a linked structure
instead.
-@node Debugging versus Testing, Tips, Understanding Threads, Project 1--Threads
+@node Project 1 Code
+@section Code
+
+Here is a brief overview of the files in the @file{threads}
+directory. You will not need to modify most of this code, but the
+hope is that presenting this overview will give you a start on what
+code to look at.
+
+@table @file
+@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. You should not need to look at this code or
+modify it.
+
+@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
+of the kernel image. 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 @code{main()}.
+
+@item init.c
+@itemx init.h
+Kernel initialization, including @code{main()}, the kernel's ``main
+program.'' You should look over @code{main()} at least to see what
+gets initialized.
+
+@item thread.c
+@itemx thread.h
+Basic thread support. Much of your work will take place in these
+files. @file{thread.h} defines @code{struct thread}, which you will
+modify in the first three projects.
+
+@item switch.S
+@itemx switch.h
+Assembly language routine for switching threads. Already discussed
+above.
+
+@item palloc.c
+@itemx palloc.h
+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.
+
+@item interrupt.c
+@itemx interrupt.h
+Basic interrupt handling and functions for turning interrupts on and
+off.
+
+@item intr-stubs.pl
+@itemx intr-stubs.h
+A Perl program that outputs assembly for low-level interrupt handling.
+
+@item synch.c
+@itemx synch.h
+Basic synchronization primitives: semaphores, locks, and condition
+variables. You will need to use these for synchronization through all
+four projects.
+
+@item test.c
+@itemx test.h
+Test code. For project 1, you will replace this file with your test
+cases.
+
+@item io.h
+Functions for I/O port access. This is mostly used by source code in
+the @file{devices} directory that you won't have to touch.
+
+@item mmu.h
+Functions and macros related to memory management, including page
+directories and page tables. This will be more important to you in
+project 3. For now, you can ignore it.
+@end table
+
+@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
When you're debugging code, it's useful to be able to be able to run a
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
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.
-
-@node Tips, Problem 1-1 Alarm Clock, Debugging versus Testing, Project 1--Threads
+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
There should be no busy-waiting in any of your solutions to this
justified, ask!
While all parts of this assignment are required if you intend to earn
-full credit on this project, keep in mind that Problem 2 (Join) will
+full credit on this project, keep in mind that Problem 1-2 (Join) will
be needed for future assignments, so you'll want to get this one
right. We don't give out solutions, so you're stuck with your Join
-code for the whole quarter. Problem 1 (Alarm Clock) could be very
+code for the whole quarter. Problem 1-1 (Alarm Clock) could be very
handy, but not strictly required in the future. The upshot of all
this is that you should focus heavily on making sure that your
-implementation of Join works correctly, since if it's broken, you will
-need to fix it for future assignments. The other parts can be turned
-off in the future if you find you can't make them work quite right.
+implementation of @code{thread_join()} works correctly, since if it's
+broken, you will need to fix it for future assignments. The other
+parts can be turned off in the future if you find you can't make them
+work quite right.
-Also keep in mind that Problem 4 (the MLFQS) builds on the features you
-implement in Problem 3, so to avoid unnecessary code duplication, it
+Also keep in mind that Problem 1-4 (the MLFQS) builds on the features you
+implement in Problem 1-3, so to avoid unnecessary code duplication, it
would be a good idea to divide up the work among your team members
-such that you have Problem 3 fully working before you begin to tackle
-Problem 4.
+such that you have Problem 1-3 fully working before you begin to tackle
+Problem 1-4.
-@node Problem 1-1 Alarm Clock, Problem 1-2 Join, Tips, Project 1--Threads
-@section Problem 1-2: Alarm Clock
+@node Problem 1-1 Alarm Clock
+@section Problem 1-1: Alarm Clock
Improve the implementation of the timer device defined in
@file{devices/timer.c} by reimplementing @code{timer_sleep()}.
The argument to @code{timer_sleep()} is expressed in timer ticks, not
in milliseconds or some other unit.
-@node Problem 1-2 Join, Problem 1-3 Priority Scheduling, Problem 1-1 Alarm Clock, Project 1--Threads
+@node Problem 1-2 Join
@section Problem 1-2: Join
-Implement @code{thread_join(struct thread *)} in
-@file{threads/thread.c}. There is already a prototype for it in
-@file{threads/thread.h}, which you should not change. This function
-causes the currently running thread to block until thread passed as an
-argument exits. If A is the running thread and B is the argument,
-then we say that ``A joins B'' in this case.
+Implement @code{thread_join(tid_t)} in @file{threads/thread.c}. There
+is already a prototype for it in @file{threads/thread.h}, which you
+should not change. This function causes the currently running thread
+to block until the thread whose thread id is passed as an argument
+exits. If A is the running thread and B is the argument, then we say
+that ``A joins B'' in this case.
+
+Incidentally, we don't use @code{struct thread *} as
+@file{thread_join()}'s parameter type because a thread pointer is not
+unique over time. That is, when a thread dies, its memory may be,
+whether immediately or much later, reused for another thread. If
+thread A over time had two children B and C that were stored at the
+same address, then @code{thread_join(@r{B})} and
+@code{thread_join(@r{C})} would be ambiguous. Introducing a thread id
+or @dfn{tid}, represented by type @code{tid_t}, that is intentionally
+unique over time solves the problem. The provided code uses an
+@code{int} for @code{tid_t}, but you may decide you prefer to use some
+other type.
The model for @code{thread_join()} is the @command{wait} system call
in Unix-like systems. (Try reading the manpages.) That system call
can only be used by a parent process to wait for a child's death. You
should implement @code{thread_join()} to have the same restriction.
-That is, a thread may only join on its immediate children.
+That is, a thread may only join its immediate children.
A thread need not ever be joined. Your solution should properly free
all of a thread's resources, including its @code{struct thread},
exited at the time of the later joins. Thus, joins on T after the
first should return immediately.
-The behavior of calling @code{thread_join()} on an thread that is not
-the caller's child is undefined. You need not handle this case
-gracefully.
+Calling @code{thread_join()} on an thread that is not the caller's
+child should cause the caller to return immediately.
Consider all the ways a join can occur: nested joins (A joins B when B
is joined on C), multiple joins (A joins B, then A joins C), and so
Be careful to program this function correctly. You will need its
functionality for project 2.
-@node Problem 1-3 Priority Scheduling, Problem 1-4 Advanced Scheduler, Problem 1-2 Join, Project 1--Threads
-@section Problem 1-3 Priority Scheduling
+Once you've implemented @code{thread_join()}, define
+@code{THREAD_JOIN_IMPLEMENTED} in @file{constants.h}.
+@xref{Conditional Compilation}, for more information.
-Implement priority scheduling in Pintos. Priority
-scheduling is a key building block for real-time systems. Implement functions
-@code{thread_set_priority()} to set the priority of a thread and
-@code{thread_get_priority()} to get the priority of a thread. There
-are already prototypes for these functions in @file{threads/thread.h},
+@node Problem 1-3 Priority Scheduling
+@section Problem 1-3: Priority Scheduling
+
+Implement priority scheduling in Pintos. Priority scheduling is a key
+building block for real-time systems. Implement functions
+@code{thread_set_priority()} to set the priority of the running thread
+and @code{thread_get_priority()} to get the running thread's priority.
+(A thread can examine and modify only its own priority.) There are
+already prototypes for these functions in @file{threads/thread.h},
which you should not change.
+Thread priority ranges from @code{PRI_MIN} (0) to @code{PRI_MAX} (59).
+The initial thread priority is passed as an argument to
+@code{thread_create()}. If there's no reason to choose another
+priority, use @code{PRI_DEFAULT} (29). The @code{PRI_} macros are
+defined in @file{threads/thread.h}, and you should not change their
+values.
+
When a thread is added to the ready list that has a higher priority
than the currently running thread, the current thread should
immediately yield the processor to the new thread. Similarly, when
donation and inversion can occur. Be sure to handle multiple
donations, in which multiple priorities are donated to a thread. You
must also handle nested donation: given high, medium, and low priority
-threads H, M, and L, respectively, and supposing H is waiting on a
-lock that M holds and M is waiting on a lock that L holds, both M and
-L should be boosted to H's priority.
+threads H, M, and L, respectively, if H is waiting on a lock that M
+holds and M is waiting on a lock that L holds, then both M and L
+should be boosted to H's priority.
You only need to implement priority donation when a thread is waiting
-for a lock held by a lower-priority thread. You do not need to
+for a lock held by a lower-priority thread. You do not need to
implement this fix for semaphores, condition variables or joins.
However, you do need to implement priority scheduling in all cases.
-@node Problem 1-4 Advanced Scheduler, Threads FAQ, Problem 1-3 Priority Scheduling, Project 1--Threads
-@section Problem 1-4 Advanced Scheduler
+@node Problem 1-4 Advanced Scheduler
+@section Problem 1-4: Advanced Scheduler
Implement Solaris's multilevel feedback queue scheduler (MLFQS) to
reduce the average response time for running jobs on your system.
Demonstrate that your scheduling algorithm reduces response time
relative to the original Pintos scheduling algorithm (round robin) for
-at least one workload of your own design (i.e. in addition to the
+at least one workload of your own design (i.e.@: in addition to the
provided test).
You may assume a static priority for this problem. It is not necessary
to ``re-donate'' a thread's priority if it changes (although you are
free to do so).
-@node Threads FAQ, , Problem 1-4 Advanced Scheduler, Project 1--Threads
-@section FAQ
+You must write your code so that we can turn the MLFQS on and off at
+compile time. By default, it must be off, but we must be able to turn
+it on by inserting the line @code{#define MLFQS 1} in
+@file{constants.h}. @xref{Conditional Compilation}, for details.
-@enumerate 1
-@item General FAQs
+@node Threads FAQ
+@section FAQ
@enumerate 1
@item
@b{I am adding a new @file{.h} or @file{.c} file. How do I fix the
-@file{Makefile}s?}
+@file{Makefile}s?}@anchor{Adding c or h Files}
To add a @file{.c} file, edit the top-level @file{Makefile.build}.
You'll want to add your file to variable @samp{@var{dir}_SRC}, where
directory. Then run @code{make}. If your new file doesn't get
compiled, run @code{make clean} and then try again.
+When you modify the top-level @file{Makefile.build}, the modified
+version should be automatically copied to
+@file{threads/build/Makefile} when you re-run make. The opposite is
+not true, so any changes will be lost the next time you run @code{make
+clean} from the @file{threads} directory. Therefore, you should
+prefer to edit @file{Makefile.build} (unless your changes are meant to
+be truly temporary).
+
There is no need to edit the @file{Makefile}s to add a @file{.h} file.
@item
-@b{If a thread finishes, should its children be terminated immediately,
-or should they finish normally?}
+@b{How do I write my test cases?}
-You should feel free to decide what semantics you think this
-should have. You need only provide justification for your
-decision.
+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{Why can't I disable interrupts?}
want to emphasize that there are only limited cases where this is
appropriate.
+You might find @file{devices/intq.h} and its users to be an
+inspiration or source of rationale.
+
@item
-@b{Where might interrupt-level manipuation be appropriate?}
+@b{Where might interrupt-level manipulation be appropriate?}
You might find it necessary in some solutions to the Alarm problem.
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
@b{Doesn't the priority scheduling lead to starvation? Or do I have to
implement some sort of aging?}
-
It is true that strict priority scheduling can lead to starvation
because thread may not run if a higher-priority thread is runnable.
In this problem, don't worry about starvation or any sort of aging
solution must act this way.
@item
-@b{What range of priorities should be supported and what should the
-default priority of a thread be?}
+@b{What should @code{thread_get_priority()} return in a thread while
+its priority has been increased by a donation?}
-Your implementation should support priorities from 0 through 59 and
-the default priority of a thread should be 29.
+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
adjust this value by editing @file{devices/timer.h}. The default is
100 Hz.
+You can also adjust the number of timer ticks per time slice by
+modifying @code{TIME_SLICE} in @file{devices/timer.c}.
+
@item
@b{Do I have to modify the dispatch table?}
No. Hard-coding the dispatch table values is fine.
@end enumerate
-@end enumerate
-
-@include mlfqs.texi
projects / pintos-anon / blobdiff