From: Godmar Back Date: Sat, 17 Nov 2007 09:42:26 +0000 (+0000) Subject: - add localsettings.texi which contains Stanford-local macros and variables X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fe56fdaa15035a489177ff1d6d6bfb5b3ba15f32;p=pintos-anon - add localsettings.texi which contains Stanford-local macros and variables - 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 --- diff --git a/doc/Makefile b/doc/Makefile index 8fc5415..ed8bb23 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,7 +1,7 @@ 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 diff --git a/doc/bibliography.texi b/doc/bibliography.texi index 76007f0..a23c4c7 100644 --- a/doc/bibliography.texi +++ b/doc/bibliography.texi @@ -105,6 +105,12 @@ Interface---DRAFT---24 April 2001}. A draft of a revised version of @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, diff --git a/doc/debug.texi b/doc/debug.texi index 958e51b..aa833ac 100644 --- a/doc/debug.texi +++ b/doc/debug.texi @@ -724,14 +724,15 @@ In a case like this, you might appreciate being able to make Bochs 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 diff --git a/doc/intro.texi b/doc/intro.texi index ede0a69..6c49f74 100644 --- a/doc/intro.texi +++ b/doc/intro.texi @@ -9,7 +9,7 @@ project team will strengthen its support in all three of these areas. 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 @@ -19,7 +19,7 @@ systems and software can run under it. In class we will use the 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 @@ -43,31 +43,17 @@ projects. @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:: @@ -82,10 +68,10 @@ you log in. 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 @@ -145,7 +131,7 @@ Example user programs for use starting with project 2. @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 @@ -158,14 +144,7 @@ directory. Then, issue the @samp{make} command. This will create a @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: @@ -515,12 +494,7 @@ Pintos comes with NO WARRANTY, not even for MERCHANTABILITY or FITNESS 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 @@ -534,7 +508,7 @@ work. 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 @@ -549,6 +523,8 @@ Example code for monitors (@pxref{Monitors}) is from classroom slides originally by Dawson Engler and updated by Mendel Rosenblum. +@localcredits{} + @node Trivia @section Trivia diff --git a/doc/localsettings.texi b/doc/localsettings.texi new file mode 100644 index 0000000..6a3dc3e --- /dev/null +++ b/doc/localsettings.texi @@ -0,0 +1,73 @@ +@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 + diff --git a/doc/pintos.texi b/doc/pintos.texi index ac16127..40e702f 100644 --- a/doc/pintos.texi +++ b/doc/pintos.texi @@ -1,4 +1,5 @@ \input texinfo @c -*- texinfo -*- + @c %**start of header @setfilename pintos.info @settitle Pintos Projects @@ -66,6 +67,9 @@ * License:: @end menu +@c institution-local settings +@include localsettings.texi + @include intro.texi @include threads.texi @include userprog.texi diff --git a/doc/standards.texi b/doc/standards.texi index b1296c7..8e4b370 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -1,12 +1,7 @@ @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 diff --git a/doc/threads.texi b/doc/threads.texi index c1519e8..6eec6bb 100644 --- a/doc/threads.texi +++ b/doc/threads.texi @@ -364,13 +364,7 @@ with each other, requiring lots of last-minute debugging. Some groups 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, @@ -480,9 +474,9 @@ priority. If necessary, you may impose a reasonable limit on depth of 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 @@ -696,7 +690,7 @@ kernel thread but the first. 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 diff --git a/doc/vm.texi b/doc/vm.texi index 25135f0..c2943ca 100644 --- a/doc/vm.texi +++ b/doc/vm.texi @@ -714,6 +714,12 @@ process. If you carefully designed your data structures, 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