src/utils, src/misc.
Update copyright years in license. Add license to manual.
-Most of Pintos is subject to the following license:
+Pintos, including its documentation, is subject to the following
+license:
- Copyright 2004 Board of Trustees, Leland Stanford Jr. University
- All rights reserved.
+ Copyright (C) 2004, 2005, 2006 Board of Trustees, Leland Stanford
+ Jr. University. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
TEXIS = pintos.texi intro.texi threads.texi userprog.texi vm.texi \
-filesys.texi bibliography.texi reference.texi standards.texi doc.texi \
-sample.tmpl.texi devel.texi debug.texi 44bsd.texi
+filesys.texi license.texi reference.texi 44bsd.texi standards.texi \
+doc.texi sample.tmpl.texi devel.texi debug.texi installation.texi \
+bibliography.texi
all: pintos.html pintos.info pintos.dvi pintos.ps pintos.pdf
--- /dev/null
+@node Installing Pintos
+@appendix Installing Pintos
+
+This chapter explains how to install a Pintos development environment on
+your own machine. If you are using a Pintos development environment
+that has been set up by someone else, you do not need to read this
+chapter or follow these instructions.
+
+The Pintos development environment is targeted at Unix-like systems. It
+has been most extensively tested on GNU/Linux, in particular the Debian
+and Ubuntu distributions, and Solaris. It is not designed to install
+under any form of Windows.
+
+Prerequisites for installing a Pintos development environment include
+the following, on top of standard Unix utilities:
+
+@itemize @bullet
+@item
+Required: @uref{http://gcc.gnu.org/, GCC}. Version 4.0 or later is
+preferred. Version 3.3 or later should work. If the host machine has
+an 80@var{x}86 processor, then GCC should be available as @command{gcc};
+otherwise, an 80@var{x}86 cross-compiler should be available as
+@command{i386-elf-gcc}. A sample set of commands for installing GCC
+3.3.6 as a cross-compiler are included in
+@file{src/@/misc/@/gcc-3.3.6-cross-howto}.
+
+@item
+Required: @uref{http://www.gnu.org/software/binutils/, GNU binutils}.
+Pintos uses @command{addr2line}, @command{ar}, @command{ld},
+@command{objcopy}, and @command{ranlib}. If the host machine is not an
+80@var{x}86, versions targeting 80@var{x}86 should be available with an
+@samp{i386-elf-} prefix.
+
+@item
+Required: @uref{http://www.perl.org, Perl}. Version 5.8.0 or later is
+preferred. Version 5.6.1 or later should work.
+
+@item
+Required: @uref{http://www.gnu.org/software/make/, GNU make}, version
+3.80 or later.
+
+@item
+Recommended: @uref{http://fabrice.bellard.free.fr/qemu/, qemu}, version
+0.8.0 or later. If qemu is not available, Bochs can be used, but its
+slowness is frustrating.
+
+@item
+Recommended: @uref{http://www.gnu.org/software/gdb/, GDB}. GDB is
+helpful in debugging (@pxref{GDB}). If the host machine is not an
+80@var{x}86, a version of GDB targeting 80@var{x}86 should be available
+as @samp{i386-elf-gdb}.
+
+@item
+Recommended: @uref{http://www.x.org/, X}. Being able to use an X server
+makes the virtual machine feel more like a physical machine, but it is
+not strictly necessary.
+
+@item
+Optional: @uref{http://www.gnu.org/software/texinfo/, Texinfo}, version
+4.5 or later. Texinfo is required to build the PDF version of the
+documentation.
+
+@item
+Optional: @uref{http://www.tug.org/, @TeX{}}. Also required to build
+the PDF version of the documentation.
+
+@item
+Optional: @uref{http://www.vmware.com/, VMware GSX Server}. This is a
+third platform that can also be used to test Pintos.
+@end itemize
+
+Once these prerequisites are available, follow these instructions to
+install Pintos:
+
+@enumerate 1
+@item
+Install @uref{http://bochs.sourceforge.net/, Bochs}, version 2.2.6, as
+described below (@pxref{Building Bochs for Pintos}).
+
+@item
+Install scripts from @file{src/utils}. Copy @file{backtrace},
+@command{pintos}, @command{pintos-gdb}, @command{pintos-mkdisk} into the
+default @env{PATH}.
+
+@item
+Install @file{src/misc/gdb-macros} in a public location. Then use a
+text editor to edit the installed copy of @command{pintos-gdb}, changing
+the definition of @env{GDBMACROS} to point to where you installed
+@file{gdb-macros}. Test the installation by running
+@command{pintos-gdb} without any arguments. If it does not complain
+about missing @file{gdb-macros}, it is installed correctly.
+
+@item
+Compile the remaining Pintos utilities by typing @command{make} in
+@file{src/utils}. Install @file{squish-pty} somewhere in @env{PATH}.
+If your Perl is older than version 5.8.0, also install
+@file{setitimer-helper}; otherwise, it is unneeded.
+
+@item
+Pintos should now be ready for use. If you have the Pintos reference
+solutions, which are provided only to faculty and their teaching
+assistants, then you may test your installation by running @command{make
+check} in the top-level @file{tests} directory. The tests take between
+20 minutes and 1 hour to run, depending on the speed of your hardware.
+
+@item
+Optional: Build the documentation, by running @command{make dist} in the
+top-level @file{doc} directory. This creates a @file{WWW} subdirectory
+within @file{doc} that contains HTML and PDF versions of the
+documentation, plus the design document templates and various hardware
+specifications referenced by the documentation. Building the PDF
+version of the manual requires Texinfo and @TeX{} (see above). You may
+install @file{WWW} wherever you find most useful.
+@end enumerate
+
+@menu
+* Building Bochs for Pintos::
+@end menu
+
+@node Building Bochs for Pintos
+@section Building Bochs for Pintos
+
+Upstream Bochs has bugs and warts that should be fixed when used with
+Pintos. Thus, Bochs should be installed manually for use with Pintos,
+instead of using the packaged version of Bochs included with an
+operating system distribution.
+
+Two different Bochs binaries should be installed. One, named simply
+@command{bochs}, should have the GDB stub enabled, by passing
+@option{--enable-gdb-stub} to the Bochs @command{configure} script. The
+other, named @command{bochs-dbg}, should have the internal debugger
+enabled, by passing @option{--enable-debugger} to @command{configure}.
+(The @command{pintos} script selects a binary based on the options
+passed to it.) In each case, the X, terminal, and ``no GUI'' interfaces
+should be configured, by passing @option{--with-x --with-x11 --with-term
+--with-nogui} to @command{configure}.
+
+This version of Pintos is designed for use with Bochs 2.2.6. A number
+of patches for this version of Bochs are included in @file{src/misc}:
+
+@table @file
+@item bochs-2.2.6-big-endian.patch
+
+Makes the GDB stubs work on big-endian systems such as Solaris/Sparc, by
+doing proper byteswapping. It should be harmless elsewhere.
+
+@item bochs-2.2.6-jitter.patch
+
+Adds the ``jitter'' feature, in which timer interrupts are delivered at
+random intervals (@pxref{Debugging versus Testing}).
+
+@item bochs-2.2.6-triple-fault.patch
+
+Causes Bochs to break to GDB when a triple fault occurs and
+the GDB stub is active (@pxref{Triple Faults}).
+
+@item bochs-2.2.6-ms-extensions.patch
+
+Needed for Bochs to compile with GCC on some hosts. Probably
+harmless elsewhere.
+
+@item bochs-2.2.6-solaris-tty.patch
+
+Needed for Bochs to compile in terminal support on Solaris
+hosts. Probably harmless elsewhere.
+
+@item bochs-2.2.6-solaris-link.patch
+
+Needed on Solaris hosts. Do not apply it elsewhere.
+@end table
+
+To apply all the patches, @command{cd} into the Bochs directory, then
+type:
+@example
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch
+patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch
+@end example
+@noindent
+You will have to supply the proper @env{$PINTOSDIR}, of course. You can
+use @command{patch}'s @option{--dry-run} option if you want to test
+whether the patches would apply cleanly before trying to apply them.
+
+Sample commands to build and install Bochs for Pintos are supplied in
+@file{src/misc/bochs-2.2.6-build.sh}.
@menu
* Getting Started::
* Grading::
-* License::
+* Legal and Ethical Issues::
* Acknowledgements::
* Trivia::
@end menu
read by humans. It has to be acceptable to the compiler too, but the
compiler doesn't care about how it looks or how well it is written.
-@node License
-@section License
+@node Legal and Ethical Issues
+@section Legal and Ethical Issues
Pintos is distributed under a liberal license that allows free use,
modification, and distribution. Students and others who work on Pintos
own the code that they write and may use it for any purpose.
+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
but do not copy code from them literally. Please cite the code that
inspired your own in your design documentation.
-Pintos comes with NO WARRANTY, not even for MERCHANTABILITY or FITNESS
-FOR A PARTICULAR PURPOSE.
-
-The @file{LICENSE} file at the top level of the Pintos source
-distribution has full details of the license and lack of warranty.
-
@node Acknowledgements
@section Acknowledgements
--- /dev/null
+@node License
+@unnumbered License
+
+Pintos, including its documentation, is subject to the following
+license:
+
+@quotation
+Copyright @copyright{} 2004, 2005, 2006 Board of Trustees, Leland
+Stanford Jr.@: University. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+``Software''), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+@end quotation
+
+A few individual files in Pintos were originally derived from other
+projects, but they have been extensively modified for use in Pintos.
+The original code falls under the original license, and modifications
+for Pintos are additionally covered by the Pintos license above.
+
+In particular, code derived from Nachos is subject to the following
+license:
+
+@quotation
+Copyright @copyright{} 1992-1996 The Regents of the University of California.
+All rights reserved.
+
+Permission to use, copy, modify, and distribute this software
+and its documentation for any purpose, without fee, and
+without written agreement is hereby granted, provided that the
+above copyright notice and the following two paragraphs appear
+in all copies of this software.
+
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO
+ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE
+AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
+HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN ``AS IS''
+BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
+MODIFICATIONS.
+@end quotation
+
+Code derived from MIT's 6.828 course code is subject to the
+following license:
+
+@quotation
+Copyright @copyright{} 1997 Massachusetts Institute of Technology
+
+This software is being provided by the copyright holders under the
+following license. By obtaining, using and/or copying this software,
+you agree that you have read, understood, and will comply with the
+following terms and conditions:
+
+Permission to use, copy, modify, distribute, and sell this software
+and its documentation for any purpose and without fee or royalty is
+hereby granted, provided that the full text of this NOTICE appears on
+ALL copies of the software and documentation or portions thereof,
+including modifications, that you make.
+
+THIS SOFTWARE IS PROVIDED ``AS IS,'' AND COPYRIGHT HOLDERS MAKE NO
+REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE,
+BUT NOT LIMITATION, COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR
+WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR
+THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY
+THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT
+HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE OR
+DOCUMENTATION.
+
+The name and trademarks of copyright holders may NOT be used in
+advertising or publicity pertaining to the software without specific,
+written prior permission. Title to copyright in this software and any
+associated documentation will at all times remain with copyright
+holders. See the file AUTHORS which should have accompanied this software
+for a list of all copyright holders.
+
+This file may be derived from previously copyrighted software. This
+copyright applies only to those changes made by the copyright
+holders listed in the AUTHORS file. The rest of this file is covered by
+the copyright notices, if any, listed below.
+@end quotation
* Project Documentation::
* Debugging Tools::
* Development Tools::
+* Installing Pintos::
* Bibliography::
+* License::
@end menu
@include intro.texi
@include doc.texi
@include debug.texi
@include devel.texi
+@include installation.texi
@include bibliography.texi
+@include license.texi
@bye
-Most of Pintos is subject to the following license:
+Pintos, including its documentation, is subject to the following
+license:
- Copyright 2004 Board of Trustees, Leland Stanford Jr. University
- All rights reserved.
+ Copyright (C) 2004, 2005, 2006 Board of Trustees, Leland Stanford
+ Jr. University. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
+++ /dev/null
-This version of Pintos is designed for use with Bochs 2.2.6. A few
-patches for this version of Bochs are included:
-
- bochs-2.2.6-big-endian.patch
-
- Makes the gdb stubs work on big-endian systems such as
- Solaris/Sparc, by doing proper byteswapping. It should be
- harmless elsewhere.
-
- bochs-2.2.6-jitter.patch
-
- Adds the `jitter' feature described in the project documentation,
- in which timer interrupts are delivered at random intervals.
-
- bochs-2.2.6-triple-fault.patch
-
- Causes Bochs to break to GDB when a triple fault occurs and
- the GDB stub is active.
-
- bochs-2.2.6-ms-extensions.patch
-
- Needed for Bochs to compile with GCC on some hosts. Probably
- harmless elsewhere.
-
- bochs-2.2.6-solaris-tty.patch
-
- Needed for Bochs to compile in terminal support on Solaris
- hosts. Probably harmless elsewhere.
-
- bochs-2.2.6-solaris-link.patch
-
- Needed on Solaris hosts. Do not apply it elsewhere.
-
-To apply all the patches, cd into the Bochs directory, then type
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-big-endian.patch
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-jitter.patch
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-triple-fault.patch
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-ms-extensions.patch
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-tty.patch
- patch -p1 < $PINTOSDIR/src/misc/bochs-2.2.6-solaris-link.patch
-You will have to supply the proper $PINTOSDIR, of course. You can use
-patch's --dry-run option if you want to test whether the patches would
-apply cleanly before trying to apply them.
-
-Sample commands to build and install Bochs for Pintos are supplied in
-bochs-2.2.6-build.sh.
+++ /dev/null
-If you want to be able to give input to Pintos running in Bochs
-through a terminal (as opposed to a VGA console window), you will need
-to compile squish-pty (with `make') and install it in PATH.
-Otherwise, squish-pty is unneeded.
-
-If your version of Perl predates 5.8.0 and you want the "pintos"
-script's timeout support (with -T) to properly limit the child's CPU
-time, then you will need to compile setitimer-helper (with `make') and
-install it in PATH. Otherwise, setitimer-helper is unneeded.
-
-- Ben
projects / pintos-anon / commitdiff