-@node Introduction, Project 1--Threads, Top, Top
+@node Introduction, Pintos Tour, Top, Top
@chapter Introduction
Welcome to Pintos. Pintos is a simple operating system framework for
You will also add a virtual memory implementation.
Pintos could, theoretically, run on a regular IBM-compatible PC. As
-fun as it might be, it is impractical to supply every student in CS
-140 with his or her own PC. Therefore, we will run Pintos projects in
-a PC simulator, that is, a program that simulates an 80@var{x}86 CPU
-and its peripheral devices well enough that unmodified operating
+much fun as it might be, it is impractical to supply every student in
+CS 140 with his or her own PC. Therefore, we will run Pintos projects
+in a PC simulator, that is, a program that simulates an 80@var{x}86
+CPU and its peripheral devices well enough that unmodified operating
systems and software can run under it. In class we will use the
@uref{http://bochs.sourceforge.net, , Bochs} simulator. Pintos has
also been tested within @uref{http://fabrice.bellard.free.fr/qemu/, ,
@menu
* Getting Started::
+* Pintos License::
* Pintos Trivia::
@end menu
@example
tar xzf /usr/class/cs140/pintos/pintos.tar.gz
@end example
-Alternatively
+Alternatively, retrieve
@uref{http://www.stanford.edu/class/cs140/pintos/pintos.tar.gz} and
extract it in a similar way.
Object file for the entire kernel. This is the result of linking
object files compiled from each individual kernel source file into a
single object file. It contains debug information, so you can run
-@command{gdb} or
+@command{gdb} or @command{backtrace} (@pxref{Backtraces}) on it.
@item kernel.bin
Memory image of the kernel. These are the exact bytes loaded into
@file{bochsrc.txt} file, which is needed for running Bochs, and then
invoke Bochs.
-Bochs opens a new window that represents the the simulated machine's
+Bochs opens a new window that represents the simulated machine's
display, and a BIOS message briefly flashes. Then Pintos boots and
-runs a simple test program that scrolls by a few screenfuls of text.
+runs a simple test program that outputs a few screenfuls of text.
When it's done, you can close Bochs by clicking on the ``Power''
button in the window's top right corner, or rerun the whole process by
clicking on the ``Reset'' button just to its left. The other buttons
are not very useful for our purposes.
+(If no window appeared at all, and you just got a terminal full of
+corrupt-looking text, then you're probably logged in remotely and X
+forwarding is not set up correctly. In this case, you can fix your X
+setup, or you can use the @option{-v} option.)
+
The text printed by Pintos inside Bochs probably went by too quickly
to read. However, you've probably noticed by now that the same text
-was displayed
-
+was displayed in the terminal you used to run @command{pintos}. This
+is because Pintos sends all output both to the VGA display and to the
+first serial port, and by default the serial port is connected to
+Bochs's @code{stdout}. You can log this output to a file by
+redirecting at the command line, e.g.@: @code{pintos run > logfile}.
+
+The @command{pintos} program offers multiple options for running
+Pintos. Specify these options on the command line @emph{before} the
+@option{run} command. Use @code{pintos help} to see a list of the
+options. You can select a simulator other than Bochs, although the
+Leland systems only have Bochs installed. You can start the simulator
+running a debugger (@pxref{i386-elf-gdb}). You can set the amount of
+memory to give the VM. Finally, you can set up how you want VM output
+to be displayed: use @option{-v} to turn off the VGA display,
+@option{-t} to use your terminal window as the VGA display instead of
+opening a new window, or @option{-s} to suppress the serial output to
+@code{stdout}.
+
+The @command{pintos} program offers commands other than @samp{run} and
+@samp{help}, but we won't have any need for them until project 2.
+
+The Pintos kernel has its own command line that you can use to pass
+options. These options must be specified @emph{after} the
+@option{run} command. These options are not very interesting for now,
+but you can see a list of them using the @option{-u} option, e.g.@:
+@code{pintos run -u}.
+
+@node Pintos License
+@section Pintos License
+
+Pintos is distributed under a liberal license that allows it to be
+freely used, modified, and distributed. Students and others own their
+own code and may use it for any purpose. 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. (Source code for other operating system kernels,
+such as Linux or FreeBSD, is of course fair game.)
+
+There is NO WARRANTY for Pintos, not even for MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.
+
+Please refer to the @file{LICENSE} file at the top level of the Pintos
+source distribution for details of license and lack of warranty.
@node Pintos Trivia
@section Pintos Trivia
The design of Pintos is inspired by Nachos, an instructional operating
-system implemented at UC Berkeley, and even uses a few pieces of
+system originally from UC Berkeley, and even uses a few pieces of
Nachos code. Pintos is different from Nachos in two important ways.
First, Nachos requires a host operating system such as Solaris,
whereas Pintos runs on real or simulated 80@var{x}86 hardware.
projects / pintos-anon / blobdiff