- threads.texi - removed comment about being welcome to implement priority donation for semaphores
- vm.texi - added FAQ about how to resume. It truely is a FAQ, at least here at Tech.
- debug.texi - updated Bochs build instructions
TEXIS = pintos.texi intro.texi threads.texi userprog.texi vm.texi \
filesys.texi license.texi reference.texi 44bsd.texi standards.texi \
doc.texi sample.tmpl.texi devel.texi debug.texi installation.texi \
-bibliography.texi
+bibliography.texi localsettings.texi
all: pintos.html pintos.info pintos.dvi pintos.ps pintos.pdf
@node Operating System Design References
@section Operating System Design References
+@bibdfn{Christopher}
+W.@: A.@: Christopher, S.@: J.@: Procter, T.@: E.@: Anderson,
+@cite{The Nachos instructional operating system}.
+Proceedings of the @acronym{USENIX} Winter 1993 Conference.
+@uref{http://portal.acm.org/citation.cfm?id=1267307}.
+
@bibdfn{Dijkstra}
E.@: W.@: Dijkstra, @cite{The structure of the ``THE''
multiprogramming system}. Communications of the ACM 11(5):341--346,
print out more debug information, such as the exact type of fault that
occurred. It's not very hard. You start by retrieving the source
code for Bochs 2.2.6 from @uref{http://bochs.sourceforge.net} and
-extracting it into a directory. Then read
-@file{pintos/src/misc/bochs-2.2.6.README} and apply the patches needed.
-Then run @file{./configure}, supplying the options you want (some
-suggestions are in the patch file). Finally, run @command{make}.
-This will compile Bochs and eventually produce a new binary
-@file{bochs}. To use your @file{bochs} binary with @command{pintos},
+saving the file @file{bochs-2.2.6.tar.gz} into a directory.
+The script @file{pintos/src/misc/bochs-2.2.6-build.sh}
+applies a number of patches contained in @file{pintos/src/misc}
+to the Bochs tree, then builds Bochs and installs it in a directory
+of your choice.
+Run this script without arguments to learn usage instructions.
+To use your @file{bochs} binary with @command{pintos},
put it in your @env{PATH}, and make sure that it is earlier than
-@file{/usr/class/cs140/`uname -m`/bochs}.
+@file{@value{localpintosbindir}/bochs}.
Of course, to get any good out of this you'll have to actually modify
Bochs. Instructions for doing this are firmly out of the scope of
You will also add a virtual memory implementation.
Pintos could, theoretically, run on a regular IBM-compatible PC.
-Unfortunately, it is impractical to supply every CS 140 student
+Unfortunately, it is impractical to supply every @value{coursenumber} student
a dedicated PC for use with Pintos. Therefore, we will run Pintos projects
in a system simulator, that is, a program that simulates an 80@var{x}86
CPU and its peripheral devices accurately enough that unmodified operating
QEMU} simulators. Pintos has also been tested with
@uref{http://www.vmware.com/, , VMware Player}.
-These projects are hard. CS 140 has a reputation of taking a lot of
+These projects are hard. @value{coursenumber} has a reputation of taking a lot of
time, and deservedly so. We will do what we can to reduce the workload, such
as providing a lot of support material, but there is plenty of
hard work that needs to be done. We welcome your
@section Getting Started
To get started, you'll have to log into a machine that Pintos can be
-built on. The CS140 ``officially supported''
-Pintos development machines are the machines in Sweet Hall managed by
-Stanford ITSS, as described on the
-@uref{http://www.stanford.edu/services/cluster/environs/sweet/, , ITSS
-webpage}. You may use the Solaris or Linux machines. We will test your
-code on these machines, and the instructions given here assume this
-environment. We cannot provide support for installing and working on
-Pintos on your own machine, but we provide instructions for doing so
-nonetheless (@pxref{Installing Pintos}).
+built on.
+@localmachines{}
+We will test your code on these machines, and the instructions given
+here assume this environment. We cannot provide support for installing
+and working on Pintos on your own machine, but we provide instructions
+for doing so nonetheless (@pxref{Installing Pintos}).
Once you've logged into one of these machines, either locally or
remotely, start out by adding our binaries directory to your @env{PATH}
-environment. Under @command{csh}, Stanford's login shell, you can do so
-with this command:@footnote{The term @samp{`uname -m`} expands to either
-@file{sun4u} or @file{i686} according to the type of computer you're
-logged into.}
-@example
-set path = ( /usr/class/cs140/`uname -m`/bin $path )
-@end example
-@noindent
-@strong{Notice that both @samp{`} are left single quotes or
-``backticks,'' not apostrophes (@samp{'}).}
-It is a good idea to add this line to the @file{.cshrc} file
-in your home directory. Otherwise, you'll have to type it every time
-you log in.
+environment.
+@localpathsetup{}
@menu
* Source Tree Overview::
Now you can extract the source for Pintos into a directory named
@file{pintos/src}, by executing
@example
-zcat /usr/class/cs140/pintos/pintos.tar.gz | tar x
+zcat @value{localpintostarpath} | tar x
@end example
Alternatively, fetch
-@uref{http://@/www.stanford.edu/@/class/@/cs140/@/pintos/@/pintos.@/tar.gz}
+@uref{@value{localpintoshttppath}}
and extract it in a similar way.
Let's take a look at what's inside. Here's the directory structure
@item misc/
@itemx utils/
These files may come in handy if you decide to try working with Pintos
-away from the ITSS machines. Otherwise, you can ignore them.
+on your own machine. Otherwise, you can ignore them.
@end table
@node Building Pintos
@file{Makefile} and a few subdirectories, and then build the kernel
inside. The entire build should take less than 30 seconds.
-Watch the commands executed during the build. On the Linux machines,
-the ordinary system tools are used. On a SPARC machine, special build
-tools are used, whose names begin with @samp{i386-elf-}, e.g.@:
-@code{i386-elf-gcc}, @code{i386-elf-ld}. These are ``cross-compiler''
-tools. That is, the build is running on a SPARC machine (called the
-@dfn{host}), but the result will run on a simulated 80@var{x}86 machine
-(called the @dfn{target}). The @samp{i386-elf-@var{program}} tools are
-specially built for this configuration.
+@localcrossbuild{}
Following the build, the following are the interesting files in the
@file{build} directory:
FOR A PARTICULAR PURPOSE.
@xref{License}, for details of the license and lack of warranty.
-In the context of Stanford's CS 140 course, please respect the spirit
-and the letter of the honor code by refraining from reading any homework
-solutions available online or elsewhere. Reading the source code for
-other operating system kernels, such as Linux or FreeBSD, is allowed,
-but do not copy code from them literally. Please cite the code that
-inspired your own in your design documentation.
+@localhonorcodepolicy{}
@node Acknowledgements
@section Acknowledgements
The original structure and form of Pintos was inspired by the Nachos
instructional operating system from the University of California,
-Berkeley.
+Berkeley (@bibref{Christopher}).
A few of the Pintos source files are derived from code used in the
Massachusetts Institute of Technology's 6.828 advanced operating systems
from classroom slides originally by Dawson Engler and updated by Mendel
Rosenblum.
+@localcredits{}
+
@node Trivia
@section Trivia
--- /dev/null
+@c Local settings
+
+@set coursenumber CS 140
+@set localpintostarpath /usr/class/cs140/pintos/pintos.tar.gz
+@set localpintoshttppath http://@/www.stanford.edu/@/class/@/cs140/@/pintos/@/pintos.@/tar.gz
+@set localpintosbindir /usr/class/cs140/`uname -m`/bin
+
+@macro localmachines{}
+The CS 140 ``officially supported'' Pintos development machines are
+the machines in Sweet Hall managed by Stanford ITSS, as described on
+the @uref{http://www.stanford.edu/services/cluster/environs/sweet/, ,
+ITSS webpage}. You may use the Solaris or Linux machines.
+@end macro
+
+@macro localpathsetup{}
+Under @command{csh}, Stanford's login shell, you can do so
+with this command:@footnote{The term @samp{`uname -m`} expands to either
+@file{sun4u} or @file{i686} according to the type of computer you're
+logged into.}
+@example
+set path = ( @value{localpintosbindir} $path )
+@end example
+@noindent
+@strong{Notice that both @samp{`} are left single quotes or
+``backticks,'' not apostrophes (@samp{'}).}
+It is a good idea to add this line to the @file{.cshrc} file
+in your home directory. Otherwise, you'll have to type it every time
+you log in.
+@end macro
+
+@macro localcrossbuild{}
+Watch the commands executed during the build. On the Linux machines,
+the ordinary system tools are used. On a SPARC machine, special build
+tools are used, whose names begin with @samp{i386-elf-}, e.g.@:
+@code{i386-elf-gcc}, @code{i386-elf-ld}. These are ``cross-compiler''
+tools. That is, the build is running on a SPARC machine (called the
+@dfn{host}), but the result will run on a simulated 80@var{x}86 machine
+(called the @dfn{target}). The @samp{i386-elf-@var{program}} tools are
+specially built for this configuration.
+@end macro
+
+@macro localhonorcodepolicy{}
+In the context of Stanford's CS 140 course, please respect the spirit
+and the letter of the honor code by refraining from reading any homework
+solutions available online or elsewhere. Reading the source code for
+other operating system kernels, such as Linux or FreeBSD, is allowed,
+but do not copy code from them literally. Please cite the code that
+inspired your own in your design documentation.
+@end macro
+
+@macro localcredits{}
+@c none needed
+@end macro
+
+@macro localcvspolicy{}
+Instead, we recommend integrating your team's changes early and often,
+using a source code control system such as CVS (@pxref{CVS}) or a
+group collaboration site such as SourceForge (@pxref{SourceForge}).
+This is less likely to produce surprises, because everyone can see
+everyone else's code as it is written, instead of just when it is
+finished. These systems also make it possible to review changes and,
+when a change introduces a bug, drop back to working versions of code.
+@end macro
+
+@macro localcodingstandards{}
+All of you should have taken a class like CS 107, so we expect you to be
+familiar with some set of coding standards such as
+@uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
+, CS 107 Coding Standards}. Even if you've taken 107, we recommend
+reviewing that document. We expect code at the ``Peer-Review Quality''
+level described there.
+@end macro
+
\input texinfo @c -*- texinfo -*-
+
@c %**start of header
@setfilename pintos.info
@settitle Pintos Projects
* License::
@end menu
+@c institution-local settings
+@include localsettings.texi
+
@include intro.texi
@include threads.texi
@include userprog.texi
@node Coding Standards
@appendix Coding Standards
-All of you should have taken a class like CS 107, so we expect you to be
-familiar with some set of coding standards such as
-@uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
-, CS 107 Coding Standards}. Even if you've taken 107, we recommend
-reviewing that document. We expect code at the ``Peer-Review Quality''
-level described there.
+@localcodingstandards{}
Our standards for coding are most important for grading. We want to
stress that aside from the fact that we are explicitly basing part of
who have done this have turned in code that did not even compile or
boot, much less pass any tests.
-Instead, we recommend integrating your team's changes early and often,
-using a source code control system such as CVS (@pxref{CVS}) or a
-group collaboration site such as SourceForge (@pxref{SourceForge}).
-This is less likely to produce surprises, because everyone can see
-everyone else's code as it is written, instead of just when it is
-finished. These systems also make it possible to review changes and,
-when a change introduces a bug, drop back to working versions of code.
+@localcvspolicy{}
You should expect to run into bugs that you simply don't understand
while working on this and subsequent projects. When you do,
nested priority donation, such as 8 levels.
You must implement priority donation for locks. You need not
-implement priority donation for semaphores or condition variables
-(but you are welcome to do so). You do need to implement
-priority scheduling in all cases.
+implement priority donation for the other Pintos synchronization
+constructs. You do need to implement priority scheduling in all
+cases.
Finally, implement the following functions that allow a thread to
examine and modify its own priority. Skeletons for these functions are
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 CS 140 curriculum.
+expect Pintos to have been phased out of the @value{coursenumber} curriculum.
@end table
@node Priority Scheduling FAQ
sharing of read-only pages should not make this part significantly
harder.
+@item How do we resume a process after we have handled a page fault?
+
+Returning from @func{page_fault} resumes the current user process
+(@pxref{Internal Interrupt Handling}).
+It will then retry the instruction to which the instruction pointer points.
+
@item Does the virtual memory system need to support data segment growth?
No. The size of the data segment is determined by the linker. We still
projects / pintos-anon / commitdiff