+We've supplied a program for conveniently running Pintos in a simulator,
+called @command{pintos}. In the simplest case, you can invoke
+@command{pintos} as @code{pintos @var{argument}@dots{}}. Each
+@var{argument} is passed to the Pintos kernel for it to act on.
+
+Try it out. First @command{cd} into the newly created @file{build}
+directory. Then issue the command @code{pintos run alarm-multiple},
+which passes the arguments @code{run alarm-multiple} to the Pintos
+kernel. In these arguments, @command{run} instructs the kernel to run a
+test and @code{alarm-multiple} is the test to run.
+
+This command creates a @file{bochsrc.txt} file, which is needed for
+running Bochs, and then invoke Bochs. Bochs opens a new window that
+represents the simulated machine's display, and a BIOS message briefly
+flashes. Then Pintos boots and runs the @code{alarm-multiple} test
+program, which 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 to disable X output:
+@code{pintos -v -- run alarm-multiple}.)
+
+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 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{stdin} and @code{stdout}. You can log serial output to a file by
+redirecting at the
+command line, e.g.@: @code{pintos run alarm-multiple > logfile}.
+
+The @command{pintos} program offers several options for configuring the
+simulator or the virtual hardware. If you specify any options, they
+must precede the commands passed to the Pintos kernel and be separated
+from them by @option{--}, so that the whole command looks like
+@code{pintos @var{option}@dots{} -- @var{argument}@dots{}}. Invoke
+@code{pintos} without any arguments to see a list of available options.
+Options can select a simulator to use: the default is Bochs, but
+@option{--qemu} selects QEMU. You can run the simulator
+with a debugger (@pxref{GDB}). You can set the amount of memory to give
+the VM. Finally, you can select 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
+(Bochs only), or @option{-s} to suppress serial input from @code{stdin}
+and output to @code{stdout}.
+
+The Pintos kernel has commands and options other than @command{run}.
+These are not very interesting for now, but you can see a list of them
+using @option{-h}, e.g.@: @code{pintos -h}.
+
+@node Debugging versus Testing
+@subsection Debugging versus Testing
+
+When you're debugging code, it's useful to be able to run a
+program twice and have it do exactly the same thing. On second and
+later runs, you can make new observations without having to discard or
+verify your old observations. This property is called
+``reproducibility.'' One of the simulators that Pintos supports, Bochs,
+can be set up for
+reproducibility, and that's the way that @command{pintos} invokes it
+by default.
+
+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
+computer, as we do, this means that every part of the computer must be
+the same. For example, you must use the same command-line argument, the
+same disks, the same version
+of Bochs, and you must not hit any keys on the keyboard (because you
+could not be sure to hit them at exactly the same point each time)
+during the runs.
+
+While reproducibility is useful for debugging, it is a problem for
+testing thread synchronization, an important part of most of the projects. In
+particular, when Bochs is set up for reproducibility, timer interrupts
+will come at perfectly reproducible points, and therefore so will
+thread switches. That means that running the same test several times
+doesn't give you any greater confidence in your code's correctness
+than does running it only once.
+
+So, to make your code easier to test, we've added a feature, called
+``jitter,'' to Bochs, that makes timer interrupts come at random
+intervals, but in a 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.
+
+On the other hand, when Bochs runs in reproducible mode, timings are not
+realistic, meaning that a ``one-second'' delay may be much shorter or
+even much longer than one second. You can invoke @command{pintos} with
+a different option, @option{-r}, to set up Bochs for realistic
+timings, in which a one-second delay should take approximately one
+second of real time. Simulation in real-time mode is not reproducible,
+and options @option{-j} and @option{-r} are mutually exclusive.
+
+The QEMU simulator is available as an
+alternative to Bochs (use @option{--qemu} when invoking
+@command{pintos}). The QEMU simulator is much faster than Bochs, but it
+only supports real-time simulation and does not have a reproducible
+mode.
+
+@node Grading
+@section Grading
+
+We will grade your assignments based on test results and design quality,
+each of which comprises 50% of your grade.
+
+@menu
+* Testing::
+* Design::
+@end menu
+
+@node Testing
+@subsection Testing
+
+Your test result grade will be based on our tests. Each project has
+several tests, each of which has a name beginning with @file{tests}.
+To completely test your submission, invoke @code{make check} from the
+project @file{build} directory. This will build and run each test and
+print a ``pass'' or ``fail'' message for each one. When a test fails,
+@command{make check} also prints some details of the reason for failure.
+After running all the tests, @command{make check} also prints a summary
+of the test results.
+
+For project 1, the tests will probably run faster in Bochs. For the
+rest of the projects, they will run much faster in QEMU.
+@command{make check} will select the faster simulator by default, but
+you can override its choice by specifying @option{SIMULATOR=--bochs} or
+@option{SIMULATOR=--qemu} on the @command{make} command line.
+
+You can also run individual tests one at a time. A given test @var{t}
+writes its output to @file{@var{t}.output}, then a script scores the
+output as ``pass'' or ``fail'' and writes the verdict to
+@file{@var{t}.result}. To run and grade a single test, @command{make}
+the @file{.result} file explicitly from the @file{build} directory, e.g.@:
+@code{make tests/threads/alarm-multiple.result}. If @command{make} says
+that the test result is up-to-date, but you want to re-run it anyway,
+either run @code{make clean} or delete the @file{.output} file by hand.
+
+By default, each test provides feedback only at completion, not during
+its run. If you prefer, you can observe the progress of each test by
+specifying @option{VERBOSE=1} on the @command{make} command line, as in
+@code{make check VERBOSE=1}. You can also provide arbitrary options to the
+@command{pintos} run by the tests with @option{PINTOSOPTS='@dots{}'},
+e.g.@: @code{make check PINTOSOPTS='-j 1'} to select a jitter value of 1
+(@pxref{Debugging versus Testing}).
+
+All of the tests and related files are in @file{pintos/src/tests}.
+Before we test your submission, we will replace the contents of that
+directory by a pristine, unmodified copy, to ensure that the correct
+tests are used. Thus, you can modify some of the tests if that helps in
+debugging, but we will run the originals.
+
+All software has bugs, so some of our tests may be flawed. If you think
+a test failure is a bug in the test, not a bug in your code,
+please point it out. We will look at it and fix it if necessary.
+
+Please don't try to take advantage of our generosity in giving out our
+test suite. Your code has to work properly in the general case, not
+just for the test cases we supply. For example, it would be unacceptable
+to explicitly base the kernel's behavior on the name of the running
+test case. Such attempts to side-step the test cases will receive no
+credit. If you think your solution may be in a gray area here, please
+ask us about it.
+
+@node Design
+@subsection Design
+
+We will judge your design based on the design document and the source
+code that you submit. We will read your entire design document and much
+of your source code.
+
+Don't forget that design quality, including the design document, is 50%
+of your project grade. It
+is better to spend one or two hours writing a good design document than
+it is to spend that time getting the last 5% of the points for tests and
+then trying to rush through writing the design document in the last 15
+minutes.
+
+@menu
+* Design Document::
+* Source Code::
+@end menu
+
+@node Design Document
+@subsubsection Design Document
+
+We provide a design document template for each project. For each
+significant part of a project, the template asks questions in four
+areas:
+
+@table @strong
+@item Data Structures
+
+The instructions for this section are always the same:
+
+@quotation
+Copy here the declaration of each new or changed @code{struct} or
+@code{struct} member, global or static variable, @code{typedef}, or
+enumeration. Identify the purpose of each in 25 words or less.
+@end quotation
+
+The first part is mechanical. Just copy new or modified declarations
+into the design document, to highlight for us the actual changes to data
+structures. Each declaration should include the comment that should
+accompany it in the source code (see below).
+
+We also ask for a very brief description of the purpose of each new or
+changed data structure. The limit of 25 words or less is a guideline
+intended to save your time and avoid duplication with later areas.
+
+@item Algorithms
+
+This is where you tell us how your code works, through questions that
+probe your understanding of your code. We might not be able to easily
+figure it out from the code, because many creative solutions exist for
+most OS problems. Help us out a little.
+
+Your answers should be at a level below the high level description of
+requirements given in the assignment. We have read the assignment too,
+so it is unnecessary to repeat or rephrase what is stated there. On the
+other hand, your answers should be at a level above the low level of the
+code itself. Don't give a line-by-line run-down of what your code does.
+Instead, use your answers to explain how your code works to implement
+the requirements.
+
+@item Synchronization
+
+An operating system kernel is a complex, multithreaded program, in which
+synchronizing multiple threads can be difficult. This section asks
+about how you chose to synchronize this particular type of activity.
+
+@item Rationale
+
+Whereas the other sections primarily ask ``what'' and ``how,'' the
+rationale section concentrates on ``why.'' This is where we ask you to
+justify some design decisions, by explaining why the choices you made
+are better than alternatives. You may be able to state these in terms
+of time and space complexity, which can be made as rough or informal
+arguments (formal language or proofs are unnecessary).
+@end table
+
+An incomplete, evasive, or non-responsive design document or one that
+strays from the template without good reason may be penalized.
+Incorrect capitalization, punctuation, spelling, or grammar can also
+cost points. @xref{Project Documentation}, for a sample design document
+for a fictitious project.
+
+@node Source Code
+@subsubsection Source Code
+
+Your design will also be judged by looking at your source code. We will
+typically look at the differences between the original Pintos source
+tree and your submission, based on the output of a command like
+@code{diff -urpb pintos.orig pintos.submitted}. We will try to match up your
+description of the design with the code submitted. Important
+discrepancies between the description and the actual code will be
+penalized, as will be any bugs we find by spot checks.
+
+The most important aspects of source code design are those that specifically
+relate to the operating system issues at stake in the project. For
+example, the organization of an inode is an important part of file
+system design, so in the file system project a poorly designed inode
+would lose points. Other issues are much less important. For
+example, multiple Pintos design problems call for a ``priority
+queue,'' that is, a dynamic collection from which the minimum (or
+maximum) item can quickly be extracted. Fast priority queues can be
+implemented many ways, but we do not expect you to build a fancy data
+structure even if it might improve performance. Instead, you are
+welcome to use a linked list (and Pintos even provides one with
+convenient functions for sorting and finding minimums and maximums).
+
+Pintos is written in a consistent style. Make your additions and
+modifications in existing Pintos source files blend in, not stick out.
+In new source files, adopt the existing Pintos style by preference, but
+make your code self-consistent at the very least. There should not be a
+patchwork of different styles that makes it obvious that three different
+people wrote the code. Use horizontal and vertical white space to make
+code readable. Add a brief comment on every structure, structure
+member, global or static variable, typedef, enumeration, and function
+definition. Update
+existing comments as you modify code. Don't comment out or use the
+preprocessor to ignore blocks of code (instead, remove it entirely).
+Use assertions to document key invariants. Decompose code into
+functions for clarity. Code that is difficult to understand because it
+violates these or other ``common sense'' software engineering practices
+will be penalized.
+
+In the end, remember your audience. Code is written primarily to be
+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 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.
+
+@localhonorcodepolicy{}
+
+@node Acknowledgements
+@section Acknowledgements
+
+The Pintos core and this documentation were originally written by Ben
+Pfaff @email{blp@@cs.stanford.edu}.
+
+Additional features were contributed by Anthony Romano
+@email{chz@@vt.edu}.
+
+The GDB macros supplied with Pintos were written by Godmar Back
+@email{gback@@cs.vt.edu}, and their documentation is adapted from his
+work.
+
+The original structure and form of Pintos was inspired by the Nachos
+instructional operating system from the University of California,
+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
+course. These files bear the original MIT license notice.
+
+The Pintos projects and documentation originated with those designed for
+Nachos by current and former CS 140 teaching assistants at Stanford
+University, including at least Yu Ping, Greg Hutchins, Kelly Shaw, Paul
+Twohey, Sameer Qureshi, and John Rector.
+
+Example code for monitors (@pxref{Monitors}) is
+from classroom slides originally by Dawson Engler and updated by Mendel
+Rosenblum.
+
+@localcredits{}
+
+@node Trivia
+@section Trivia
+
+Pintos originated as a replacement for Nachos with a similar design.
+Since then Pintos has greatly diverged from the Nachos design. Pintos
+differs from Nachos in two important ways. First, Pintos runs on real
+or simulated 80@var{x}86 hardware, but Nachos runs as a process on a
+host operating system. Second, Pintos is written in C like most
+real-world operating systems, but Nachos is written in C++.
+
+Why the name ``Pintos''? First, like nachos, pinto beans are a common
+Mexican food. Second, Pintos is small and a ``pint'' is a small amount.
+Third, like drivers of the eponymous car, students are likely to have
+trouble with blow-ups.
projects / pintos-anon / blobdiff