Warn that coding style costs points.
[pintos-anon] / doc / intro.texi
1 @node Introduction, Pintos Tour, Top, Top
2 @chapter Introduction
3
4 Welcome to Pintos.  Pintos is a simple operating system framework for
5 the 80@var{x}86 architecture.  It supports kernel threads, loading and
6 running user programs, and a file system, but it implements all of
7 these in a very simple way.  In the Pintos projects, you and your
8 project team will strengthen its support in all three of these areas.
9 You will also add a virtual memory implementation.
10
11 Pintos could, theoretically, run on a regular IBM-compatible PC.  As
12 much fun as it might be, it is impractical to supply every student in
13 CS 140 with his or her own PC.  Therefore, we will run Pintos projects
14 in a PC simulator, that is, a program that simulates an 80@var{x}86
15 CPU and its peripheral devices well enough that unmodified operating
16 systems and software can run under it.  In class we will use the
17 @uref{http://bochs.sourceforge.net, , Bochs} simulator.  Pintos has
18 also been tested within @uref{http://fabrice.bellard.free.fr/qemu/, ,
19 qemu} and
20 @uref{http://www.vmware.com/products/server/gsx_features.html, ,
21 VMware GSX Server}.
22
23 These projects are hard.  CS 140 has a reputation of taking a lot of
24 time, and deservedly so.  We will do what we can to ease the pain,
25 such as providing a lot of support material, but to some extent there
26 is simply some amount of hard work that needs to be done.  Because
27 Pintos is a new system, it is also possible that some parts of the
28 projects are not only difficult, but more difficult than they should
29 be.  We welcome your feedback.  If you have suggestions on how we can
30 reduce the unnecessary overhead of assignments, cutting them down to
31 the important underlying issues, please let us know.
32
33 This chapter explains how to get started working with Pintos.  You
34 should read the entire chapter before you proceed to any of the
35 projects.
36
37 @menu
38 * Getting Started::             
39 * Pintos Trivia::               
40 @end menu
41
42 @node Getting Started
43 @section Getting Started
44
45 To get started, you'll have to log into a machine that Pintos can be
46 built on.  For the purposes of CS 140, our ``officially supported''
47 Pintos development machines are the Sun Solaris machines managed by
48 Stanford ITSS, as described on the
49 @uref{http://www.stanford.edu/dept/itss/services/cluster/environs/sweet/,
50 , ITSS webpage}.  We will test your code on these machines, and the
51 instructions given here assume this environment.  However, Pintos and
52 its supporting tools are portable enough that it should build ``out of
53 the box'' in other environments, including the Linux machines managed
54 by ITSS.
55
56 Once you've logged into one of these machines, either locally or
57 remotely, start out by adding our binaries directory to your
58 @env{PATH} environment.  Under @command{csh}, the Stanford default
59 shell, you can do so with this command:
60 @example
61 set path = ( $path /usr/class/cs140/i386/bin )
62 @end example
63 @noindent
64 It might be a good idea to add this line into the @file{.cshrc} file
65 in your home directory.  Otherwise, you'll have to type it every time
66 you log in.
67
68 @menu
69 * Source Tree Overview::        
70 * Building Pintos::             
71 * Running Pintos::              
72 @end menu
73
74 @node Source Tree Overview
75 @subsection Source Tree Overview
76
77 Now you can extract the source for Pintos into a directory named
78 @file{pintos/src} by executing
79 @example
80 tar xzf /usr/class/cs140/pintos/pintos.tar.gz
81 @end example
82 Alternatively, retrieve
83 @uref{http://www.stanford.edu/class/cs140/pintos/pintos.tar.gz} and
84 extract it in a similar way.
85
86 Let's take a look at what's inside.  Here's the directory structure
87 that you should see in @file{pintos/src}:
88
89 @table @file
90 @item threads/
91 Source code for the base kernel, which you will modify starting with
92 project 1.
93
94 @item userprog/
95 Source code for the user program loader, which you will modify
96 starting with project 2.
97
98 @item vm/
99 An almost empty directory, where you will implement virtual memory in
100 project 3.
101
102 @item filesys/
103 Source code for a basic file system, which you will use starting with
104 project 2 but which you should not modify until project 4.
105
106 @item devices/
107 Source code for I/O device interfacing: keyboard, timer, disk, etc.
108 You will improve the timer implementation in project 1, but otherwise
109 you should have no need to change this code.
110
111 @item lib/
112 An implementation of a subset of the standard C library.  The code in
113 this directory is compiled into both the Pintos kernel and, starting
114 from project 2, user programs that run under it.  Headers in this
115 directory can be included using the @code{#include <@dots{}>}
116 notation.  You should have little need to modify this code.
117
118 @item lib/kernel/
119 Parts of the C library that are included only in the Pintos kernel.
120 This also includes implementations of some data types that you are
121 free to use in your kernel code: bitmaps, doubly linked lists, and
122 hash tables.
123
124 @item lib/user/
125 Parts of the C library that are included only in Pintos user programs.
126
127 @item tests/
128 Code for testing each project.
129
130 @item misc/
131 @itemx utils/
132 These files may come in handy if you decide to try working with Pintos
133 away from ITSS's Sun Solaris machines.  Otherwise, you can ignore
134 them.
135 @end table
136
137 @node Building Pintos
138 @subsection Building Pintos
139
140 The next thing to do is to try building the source code supplied for
141 the first project.  First, @command{cd} into the @file{threads}
142 directory.  Then, issue the @samp{make} command.  This will create a
143 @file{build} directory under @file{threads}, populate it with a
144 @file{Makefile} and a few subdirectories, and then build the kernel
145 inside.  The entire build should take less than 30 seconds.
146
147 Watch the commands executed during the build.  You should notice that
148 the build tools' names begin with @samp{i386-elf-}, e.g.@:
149 @code{i386-elf-gcc}, @code{i386-elf-ld}.  These are ``cross-compiler''
150 tools.  That is, the build is running on a Sparc machine (called the
151 @dfn{host}), but the result will run on an 80@var{x}86 machine (called
152 the @dfn{target}).  The @samp{i386-elf-@var{program}} tools, which
153 reside in @file{/usr/class/cs140/i386/bin}, are specially built for
154 this configuration.
155
156 Following the build, the following are the interesting files in the
157 @file{build} directory:
158
159 @table @file
160 @item Makefile
161 A copy of @file{pintos/src/Makefile.build}.  It describes how to build
162 the kernel.  @xref{Adding c or h Files}, for more information.
163
164 @item kernel.o
165 Object file for the entire kernel.  This is the result of linking
166 object files compiled from each individual kernel source file into a
167 single object file.  It contains debug information, so you can run
168 @command{gdb} or 
169
170 @item kernel.bin
171 Memory image of the kernel.  These are the exact bytes loaded into
172 memory to run the Pintos kernel.  To simplify loading, it is always
173 padded out with zero bytes so that it is an exact multiple of 4 kB in
174 size.
175
176 @item loader.bin
177 Memory image for the kernel loader, a small chunk of code written in
178 assembly language that reads the kernel from disk into memory and
179 starts it up.  It is exactly 512 bytes long.  Its size is fixed by the
180 PC BIOS.
181
182 @item os.dsk
183 Disk image for the kernel, simply @file{loader.bin} followed by
184 @file{kernel.bin}.  This file is used as a ``virtual disk'' by the
185 simulator.
186 @end table
187
188 Subdirectories of @file{build} contain object files (@file{.o}) and
189 dependency files (@file{.d}), both produced by the compiler.  The
190 dependency files tell @command{make} which source files need to be
191 recompiled when other source or header files are changed.
192
193 @node Running Pintos
194 @subsection Running Pintos
195
196 To start the kernel that you just built in the Bochs simulator, first
197 @command{cd} into the newly created @file{build} directory.  Then
198 issue the command @code{pintos run}.  This command will create a
199 @file{bochsrc.txt} file, which is needed for running Bochs, and then
200 invoke Bochs.
201
202 Bochs opens a new window that represents the simulated machine's
203 display, and a BIOS message briefly flashes.  Then Pintos boots and
204 runs a simple test program that outputs a few screenfuls of text.
205 When it's done, you can close Bochs by clicking on the ``Power''
206 button in the window's top right corner, or rerun the whole process by
207 clicking on the ``Reset'' button just to its left.  The other buttons
208 are not very useful for our purposes.
209
210 (If no window appeared at all, and you just got a terminal full of
211 corrupt-looking text, then you're probably logged in remotely and X
212 forwarding is not set up correctly.  In this case, you can fix your X
213 setup, or you can use the @option{-v} option.)
214
215 The text printed by Pintos inside Bochs probably went by too quickly
216 to read.  However, you've probably noticed by now that the same text
217 was displayed in the terminal you used to run @command{pintos}.  This
218 is because Pintos sends all output both to the VGA display and to the
219 first serial port, and by default the serial port is connected to
220 Bochs's @code{stdout}.  You can log this output to a file by
221 redirecting at the command line, e.g.@: @code{pintos run > logfile}.
222
223 The @command{pintos} program offers multiple options for running
224 Pintos.  Specify these options on the command line @emph{before} the
225 @option{run} command.  Use @code{pintos help} to see a list of the
226 options.  You can select a simulator other than Bochs, although the
227 Leland systems only have Bochs installed.  You can start the simulator
228 running a debugger (@pxref{i386-elf-gdb}).  You can set the amount of
229 memory to give the VM.  Finally, you can set up how you want VM output
230 to be displayed: use @option{-v} to turn off the VGA display,
231 @option{-t} to use your terminal window as the VGA display instead of
232 opening a new window, or @option{-s} to suppress the serial output to
233 @code{stdout}.
234
235 The @command{pintos} program offers commands other than @samp{run} and
236 @samp{help}, but we won't have any need for them until project 2.
237
238 The Pintos kernel has its own command line that you can use to pass
239 options.  These options must be specified @emph{after} the
240 @option{run} command.  These options are not very interesting for now,
241 but you can see a list of them using the @option{-u} option, e.g.@:
242 @code{pintos run -u}.
243
244 @node Pintos Trivia
245 @section Pintos Trivia
246
247 The design of Pintos is inspired by Nachos, an instructional operating
248 system originally from UC Berkeley, and even uses a few pieces of
249 Nachos code.  Pintos is different from Nachos in two important ways.
250 First, Nachos requires a host operating system such as Solaris,
251 whereas Pintos runs on real or simulated 80@var{x}86 hardware.
252 Second, Nachos is written in C++, whereas, like most real-world
253 operating systems, Pintos is written in C.
254
255 The name ``Pintos'' was chosen for multiple reasons.  First, it was
256 named for a Mexican food to reflect that it was inspired by Nachos.
257 Second, Pintos is small and a ``pint'' is a small quantity.  Third,
258 like drivers of the eponymous car, students are likely to have trouble
259 with blow-ups.