summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authormanuel <manuel@mausz.at>2012-03-26 12:54:45 +0200
committermanuel <manuel@mausz.at>2012-03-26 12:54:45 +0200
commitb5f0874cd96ee2a62aabc645b9626c2749cb6a01 (patch)
tree1262e4bbe0634de6650be130c36e0538240f4cbf /doc
downloadprogos-b5f0874cd96ee2a62aabc645b9626c2749cb6a01.tar.gz
progos-b5f0874cd96ee2a62aabc645b9626c2749cb6a01.tar.bz2
progos-b5f0874cd96ee2a62aabc645b9626c2749cb6a01.zip
initial pintos checkin
Diffstat (limited to 'doc')
-rw-r--r--doc/pintos.css76
-rw-r--r--doc/pintos.html342
-rw-r--r--doc/pintos.pdfbin0 -> 514054 bytes
-rw-r--r--doc/pintos_1.html788
-rw-r--r--doc/pintos_10.html286
-rw-r--r--doc/pintos_11.html137
-rw-r--r--doc/pintos_2.html1734
-rw-r--r--doc/pintos_3.html375
-rw-r--r--doc/pintos_4.html83
-rw-r--r--doc/pintos_5.html3343
-rw-r--r--doc/pintos_6.html314
-rw-r--r--doc/pintos_7.html238
-rw-r--r--doc/pintos_8.html1041
-rw-r--r--doc/pintos_9.html143
-rw-r--r--doc/pintos_abt.html205
-rw-r--r--doc/pintos_fot.html79
-rw-r--r--doc/pintos_ovr.html69
-rw-r--r--doc/pintos_tour.pdfbin0 -> 257402 bytes
-rw-r--r--doc/sample.tmpl104
-rw-r--r--doc/start.tmpl101
-rw-r--r--doc/threads.tmpl82
-rw-r--r--doc/vm.tmpl81
22 files changed, 9621 insertions, 0 deletions
diff --git a/doc/pintos.css b/doc/pintos.css
new file mode 100644
index 0000000..019a33d
--- /dev/null
+++ b/doc/pintos.css
@@ -0,0 +1,76 @@
1body {
2 background: white;
3 color: black;
4 padding: 0em 1em 0em 3em;
5 margin: 0;
6 margin-left: auto;
7 margin-right: auto;
8 max-width: 8in;
9 text-align: justify
10}
11body>p {
12 margin: 0pt 0pt 0pt 0em;
13 text-align: justify
14}
15body>p + p {
16 margin: .75em 0pt 0pt 0pt
17}
18H1 {
19 font-size: 150%;
20 margin-left: -1.33em
21}
22H2 {
23 font-size: 125%;
24 font-weight: bold;
25 margin-left: -.8em
26}
27H3 {
28 font-size: 100%;
29 font-weight: bold;
30 margin-left: -.5em }
31H4 {
32 font-size: 100%;
33 margin-left: 0em
34}
35H1, H2, H3, H4, H5, H6 {
36 font-family: sans-serif;
37 color: blue
38}
39H1, H2 {
40 text-decoration: underline
41}
42html {
43 margin: 0;
44 font-weight: lighter
45}
46tt, code {
47 font-family: sans-serif
48}
49b, strong {
50 font-weight: bold
51}
52
53a:link {
54 color: blue;
55 text-decoration: none;
56}
57a:visited {
58 color: gray;
59 text-decoration: none;
60}
61a:active {
62 color: black;
63 text-decoration: none;
64}
65a:hover {
66 text-decoration: underline
67}
68
69address {
70 font-size: 90%;
71 font-style: normal
72}
73
74HR {
75 display: none
76}
diff --git a/doc/pintos.html b/doc/pintos.html
new file mode 100644
index 0000000..8060c46
--- /dev/null
+++ b/doc/pintos.html
@@ -0,0 +1,342 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Table of Contents</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Table of Contents">
18<META NAME="keywords" CONTENT="Pintos Projects: Table of Contents">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC_Contents"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
33</TR></TABLE>
34<H1>Table of Contents</H1>
35<BLOCKQUOTE>
36<A NAME="TOC1" HREF="pintos_1.html#SEC1">1. Introduction</A>
37<BR>
38<BLOCKQUOTE>
39<A NAME="TOC2" HREF="pintos_1.html#SEC2">1.1 Getting Started</A>
40<BR>
41<BLOCKQUOTE>
42<A NAME="TOC3" HREF="pintos_1.html#SEC3">1.1.1 Source Tree Overview</A>
43<BR>
44<A NAME="TOC4" HREF="pintos_1.html#SEC4">1.1.2 Building Pintos</A>
45<BR>
46<A NAME="TOC5" HREF="pintos_1.html#SEC5">1.1.3 Running Pintos</A>
47<BR>
48<A NAME="TOC6" HREF="pintos_1.html#SEC6">1.1.4 Debugging versus Testing</A>
49<BR>
50</BLOCKQUOTE>
51<A NAME="TOC7" HREF="pintos_1.html#SEC7">1.2 Grading</A>
52<BR>
53<BLOCKQUOTE>
54<A NAME="TOC8" HREF="pintos_1.html#SEC8">1.2.1 Testing</A>
55<BR>
56<A NAME="TOC9" HREF="pintos_1.html#SEC9">1.2.2 Design</A>
57<BR>
58<BLOCKQUOTE>
59<A NAME="TOC10" HREF="pintos_1.html#SEC10">1.2.2.1 Design Document</A>
60<BR>
61<A NAME="TOC11" HREF="pintos_1.html#SEC11">1.2.2.2 Source Code</A>
62<BR>
63</BLOCKQUOTE>
64</BLOCKQUOTE>
65<A NAME="TOC12" HREF="pintos_1.html#SEC12">1.3 Legal and Ethical Issues</A>
66<BR>
67<A NAME="TOC13" HREF="pintos_1.html#SEC13">1.4 Acknowledgements</A>
68<BR>
69<A NAME="TOC14" HREF="pintos_1.html#SEC14">1.5 Trivia</A>
70<BR>
71</BLOCKQUOTE>
72<A NAME="TOC15" HREF="pintos_2.html#SEC15">2. Project 0: Introducing Pintos</A>
73<BR>
74<BLOCKQUOTE>
75<A NAME="TOC16" HREF="pintos_2.html#SEC16">2.1 Understanding Threads</A>
76<BR>
77<BLOCKQUOTE>
78<A NAME="TOC17" HREF="pintos_2.html#SEC17">2.1.1 Source Files</A>
79<BR>
80<BLOCKQUOTE>
81<A NAME="TOC18" HREF="pintos_2.html#SEC18">2.1.1.1 <Q><TT>devices</TT></Q> code</A>
82<BR>
83<A NAME="TOC19" HREF="pintos_2.html#SEC19">2.1.1.2 <Q><TT>lib</TT></Q> files</A>
84<BR>
85</BLOCKQUOTE>
86<A NAME="TOC20" HREF="pintos_2.html#SEC20">2.1.2 Synchronization</A>
87<BR>
88<A NAME="TOC21" HREF="pintos_2.html#SEC21">2.1.3 Development Suggestions</A>
89<BR>
90</BLOCKQUOTE>
91<A NAME="TOC22" HREF="pintos_2.html#SEC22">2.2 Understanding User Programs</A>
92<BR>
93<BLOCKQUOTE>
94<A NAME="TOC23" HREF="pintos_2.html#SEC23">2.2.1 Source Files</A>
95<BR>
96<A NAME="TOC24" HREF="pintos_2.html#SEC24">2.2.2 Using the File System</A>
97<BR>
98<A NAME="TOC25" HREF="pintos_2.html#SEC25">2.2.3 How User Programs Work</A>
99<BR>
100<A NAME="TOC26" HREF="pintos_2.html#SEC26">2.2.4 Virtual Memory Layout</A>
101<BR>
102<BLOCKQUOTE>
103<A NAME="TOC27" HREF="pintos_2.html#SEC27">2.2.4.1 Typical Memory Layout</A>
104<BR>
105</BLOCKQUOTE>
106<A NAME="TOC28" HREF="pintos_2.html#SEC28">2.2.5 Accessing User Memory</A>
107<BR>
108</BLOCKQUOTE>
109<A NAME="TOC29" HREF="pintos_2.html#SEC29">2.3 Requirements</A>
110<BR>
111<BLOCKQUOTE>
112<A NAME="TOC30" HREF="pintos_2.html#SEC30">2.3.1 Design Document</A>
113<BR>
114<A NAME="TOC31" HREF="pintos_2.html#SEC31">2.3.2 Alarm Clock</A>
115<BR>
116<A NAME="TOC32" HREF="pintos_2.html#SEC32">2.3.3 Argument Passing</A>
117<BR>
118</BLOCKQUOTE>
119<A NAME="TOC33" HREF="pintos_2.html#SEC33">2.4 FAQ</A>
120<BR>
121<BLOCKQUOTE>
122<A NAME="TOC34" HREF="pintos_2.html#SEC34">2.4.1 Threads FAQ</A>
123<BR>
124<A NAME="TOC35" HREF="pintos_2.html#SEC35">2.4.2 Alarm Clock FAQ</A>
125<BR>
126<A NAME="TOC36" HREF="pintos_2.html#SEC36">2.4.3 Userprog FAQ</A>
127<BR>
128<A NAME="TOC37" HREF="pintos_2.html#SEC37">2.4.4 Argument Passing FAQ</A>
129<BR>
130</BLOCKQUOTE>
131<A NAME="TOC38" HREF="pintos_2.html#SEC38">2.5 80<VAR>x</VAR>86 Calling Convention</A>
132<BR>
133<BLOCKQUOTE>
134<A NAME="TOC39" HREF="pintos_2.html#SEC39">2.5.1 Program Startup Details</A>
135<BR>
136<A NAME="TOC40" HREF="pintos_2.html#SEC40">2.5.2 System Call Details</A>
137<BR>
138</BLOCKQUOTE>
139</BLOCKQUOTE>
140<A NAME="TOC41" HREF="pintos_3.html#SEC41">3. Project 1: Threads</A>
141<BR>
142<BLOCKQUOTE>
143<A NAME="TOC42" HREF="pintos_3.html#SEC42">3.1 Background</A>
144<BR>
145<A NAME="TOC43" HREF="pintos_3.html#SEC43">3.2 Requirements</A>
146<BR>
147<BLOCKQUOTE>
148<A NAME="TOC44" HREF="pintos_3.html#SEC44">3.2.1 Design Document</A>
149<BR>
150<A NAME="TOC45" HREF="pintos_3.html#SEC45">3.2.2 Priority Scheduling</A>
151<BR>
152</BLOCKQUOTE>
153<A NAME="TOC46" HREF="pintos_3.html#SEC46">3.3 FAQ</A>
154<BR>
155</BLOCKQUOTE>
156<A NAME="TOC47" HREF="pintos_4.html#SEC47">4. Project 2: Virtual Memory</A>
157<BR>
158<A NAME="TOC48" HREF="pintos_5.html#SEC48">A. Reference Guide</A>
159<BR>
160<BLOCKQUOTE>
161<A NAME="TOC49" HREF="pintos_5.html#SEC49">A.1 Loading</A>
162<BR>
163<BLOCKQUOTE>
164<A NAME="TOC50" HREF="pintos_5.html#SEC50">A.1.1 The Loader</A>
165<BR>
166<A NAME="TOC51" HREF="pintos_5.html#SEC51">A.1.2 Low-Level Kernel Initialization</A>
167<BR>
168<A NAME="TOC52" HREF="pintos_5.html#SEC52">A.1.3 High-Level Kernel Initialization</A>
169<BR>
170<A NAME="TOC53" HREF="pintos_5.html#SEC53">A.1.4 Physical Memory Map</A>
171<BR>
172</BLOCKQUOTE>
173<A NAME="TOC54" HREF="pintos_5.html#SEC54">A.2 Threads</A>
174<BR>
175<BLOCKQUOTE>
176<A NAME="TOC55" HREF="pintos_5.html#SEC55">A.2.1 <CODE>struct thread</CODE></A>
177<BR>
178<A NAME="TOC56" HREF="pintos_5.html#SEC56">A.2.2 Thread Functions</A>
179<BR>
180<A NAME="TOC57" HREF="pintos_5.html#SEC57">A.2.3 Thread Switching</A>
181<BR>
182</BLOCKQUOTE>
183<A NAME="TOC58" HREF="pintos_5.html#SEC58">A.3 Synchronization</A>
184<BR>
185<BLOCKQUOTE>
186<A NAME="TOC59" HREF="pintos_5.html#SEC59">A.3.1 Disabling Interrupts</A>
187<BR>
188<A NAME="TOC60" HREF="pintos_5.html#SEC60">A.3.2 Semaphores</A>
189<BR>
190<A NAME="TOC61" HREF="pintos_5.html#SEC61">A.3.3 Locks</A>
191<BR>
192<A NAME="TOC62" HREF="pintos_5.html#SEC62">A.3.4 Monitors</A>
193<BR>
194<BLOCKQUOTE>
195<A NAME="TOC63" HREF="pintos_5.html#SEC63">A.3.4.1 Monitor Example</A>
196<BR>
197</BLOCKQUOTE>
198<A NAME="TOC64" HREF="pintos_5.html#SEC64">A.3.5 Optimization Barriers</A>
199<BR>
200</BLOCKQUOTE>
201<A NAME="TOC65" HREF="pintos_5.html#SEC65">A.4 Interrupt Handling</A>
202<BR>
203<BLOCKQUOTE>
204<A NAME="TOC66" HREF="pintos_5.html#SEC66">A.4.1 Interrupt Infrastructure</A>
205<BR>
206<A NAME="TOC67" HREF="pintos_5.html#SEC67">A.4.2 Internal Interrupt Handling</A>
207<BR>
208<A NAME="TOC68" HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>
209<BR>
210</BLOCKQUOTE>
211<A NAME="TOC69" HREF="pintos_5.html#SEC69">A.5 Memory Allocation</A>
212<BR>
213<BLOCKQUOTE>
214<A NAME="TOC70" HREF="pintos_5.html#SEC70">A.5.1 Page Allocator</A>
215<BR>
216<A NAME="TOC71" HREF="pintos_5.html#SEC71">A.5.2 Block Allocator</A>
217<BR>
218</BLOCKQUOTE>
219<A NAME="TOC72" HREF="pintos_5.html#SEC72">A.6 Virtual Addresses</A>
220<BR>
221<A NAME="TOC73" HREF="pintos_5.html#SEC73">A.7 Page Table</A>
222<BR>
223<BLOCKQUOTE>
224<A NAME="TOC74" HREF="pintos_5.html#SEC74">A.7.1 Creation, Destruction, and Activation</A>
225<BR>
226<A NAME="TOC75" HREF="pintos_5.html#SEC75">A.7.2 Inspection and Updates</A>
227<BR>
228<A NAME="TOC76" HREF="pintos_5.html#SEC76">A.7.3 Accessed and Dirty Bits</A>
229<BR>
230<A NAME="TOC77" HREF="pintos_5.html#SEC77">A.7.4 Page Table Details</A>
231<BR>
232<BLOCKQUOTE>
233<A NAME="TOC78" HREF="pintos_5.html#SEC78">A.7.4.1 Structure</A>
234<BR>
235<A NAME="TOC79" HREF="pintos_5.html#SEC79">A.7.4.2 Page Table Entry Format</A>
236<BR>
237<A NAME="TOC80" HREF="pintos_5.html#SEC80">A.7.4.3 Page Directory Entry Format</A>
238<BR>
239</BLOCKQUOTE>
240</BLOCKQUOTE>
241<A NAME="TOC81" HREF="pintos_5.html#SEC81">A.8 Hash Table</A>
242<BR>
243<BLOCKQUOTE>
244<A NAME="TOC82" HREF="pintos_5.html#SEC82">A.8.1 Data Types</A>
245<BR>
246<A NAME="TOC83" HREF="pintos_5.html#SEC83">A.8.2 Basic Functions</A>
247<BR>
248<A NAME="TOC84" HREF="pintos_5.html#SEC84">A.8.3 Search Functions</A>
249<BR>
250<A NAME="TOC85" HREF="pintos_5.html#SEC85">A.8.4 Iteration Functions</A>
251<BR>
252<A NAME="TOC86" HREF="pintos_5.html#SEC86">A.8.5 Hash Table Example</A>
253<BR>
254<A NAME="TOC87" HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>
255<BR>
256<A NAME="TOC88" HREF="pintos_5.html#SEC88">A.8.7 Synchronization</A>
257<BR>
258</BLOCKQUOTE>
259</BLOCKQUOTE>
260<A NAME="TOC89" HREF="pintos_6.html#SEC89">B. Coding Standards</A>
261<BR>
262<BLOCKQUOTE>
263<A NAME="TOC90" HREF="pintos_6.html#SEC90">B.1 Style</A>
264<BR>
265<A NAME="TOC91" HREF="pintos_6.html#SEC91">B.2 C99</A>
266<BR>
267<A NAME="TOC92" HREF="pintos_6.html#SEC92">B.3 Unsafe String Functions</A>
268<BR>
269</BLOCKQUOTE>
270<A NAME="TOC93" HREF="pintos_7.html#SEC93">C. Project Documentation</A>
271<BR>
272<BLOCKQUOTE>
273<A NAME="TOC94" HREF="pintos_7.html#SEC94">C.1 Sample Assignment</A>
274<BR>
275<A NAME="TOC95" HREF="pintos_7.html#SEC95">C.2 Sample Design Document</A>
276<BR>
277</BLOCKQUOTE>
278<A NAME="TOC96" HREF="pintos_8.html#SEC96">D. Debugging Tools</A>
279<BR>
280<BLOCKQUOTE>
281<A NAME="TOC97" HREF="pintos_8.html#SEC97">D.1 <CODE>printf()</CODE></A>
282<BR>
283<A NAME="TOC98" HREF="pintos_8.html#SEC98">D.2 <CODE>ASSERT</CODE></A>
284<BR>
285<A NAME="TOC99" HREF="pintos_8.html#SEC99">D.3 Function and Parameter Attributes</A>
286<BR>
287<A NAME="TOC100" HREF="pintos_8.html#SEC100">D.4 Backtraces</A>
288<BR>
289<BLOCKQUOTE>
290<A NAME="TOC101" HREF="pintos_8.html#SEC101">D.4.1 Example</A>
291<BR>
292</BLOCKQUOTE>
293<A NAME="TOC102" HREF="pintos_8.html#SEC102">D.5 GDB</A>
294<BR>
295<BLOCKQUOTE>
296<A NAME="TOC103" HREF="pintos_8.html#SEC103">D.5.1 Using GDB</A>
297<BR>
298<A NAME="TOC104" HREF="pintos_8.html#SEC104">D.5.2 Example GDB Session</A>
299<BR>
300<A NAME="TOC105" HREF="pintos_8.html#SEC105">D.5.3 FAQ</A>
301<BR>
302</BLOCKQUOTE>
303<A NAME="TOC106" HREF="pintos_8.html#SEC106">D.6 Triple Faults</A>
304<BR>
305<A NAME="TOC107" HREF="pintos_8.html#SEC107">D.7 Modifying Bochs</A>
306<BR>
307<A NAME="TOC108" HREF="pintos_8.html#SEC108">D.8 Tips</A>
308<BR>
309</BLOCKQUOTE>
310<A NAME="TOC109" HREF="pintos_9.html#SEC109">E. Development Tools</A>
311<BR>
312<BLOCKQUOTE>
313<A NAME="TOC110" HREF="pintos_9.html#SEC110">E.1 Tags</A>
314<BR>
315<A NAME="TOC111" HREF="pintos_9.html#SEC111">E.2 cscope</A>
316<BR>
317<A NAME="TOC112" HREF="pintos_9.html#SEC112">E.3 git</A>
318<BR>
319</BLOCKQUOTE>
320<A NAME="TOC113" HREF="pintos_10.html#SEC113">Bibliography</A>
321<BR>
322<BLOCKQUOTE>
323<A NAME="TOC114" HREF="pintos_10.html#SEC114">E.4 Hardware References</A>
324<BR>
325<A NAME="TOC115" HREF="pintos_10.html#SEC115">E.5 Software References</A>
326<BR>
327<A NAME="TOC116" HREF="pintos_10.html#SEC116">E.6 Operating System Design References</A>
328<BR>
329</BLOCKQUOTE>
330<A NAME="TOC117" HREF="pintos_11.html#SEC117">License</A>
331<BR>
332</BLOCKQUOTE>
333<HR SIZE=1>
334<BR>
335<FONT SIZE="-1">
336This document was generated
337by on <I>March, 6 2012</I>
338using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
339</FONT>
340
341</BODY>
342</HTML>
diff --git a/doc/pintos.pdf b/doc/pintos.pdf
new file mode 100644
index 0000000..3549982
--- /dev/null
+++ b/doc/pintos.pdf
Binary files differ
diff --git a/doc/pintos_1.html b/doc/pintos_1.html
new file mode 100644
index 0000000..e921154
--- /dev/null
+++ b/doc/pintos_1.html
@@ -0,0 +1,788 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Introduction</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Introduction">
18<META NAME="keywords" CONTENT="Pintos Projects: Introduction">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC1"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_2.html#SEC15"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<A NAME="Introduction"></A>
39<H1> 1. Introduction </H1>
40<!--docid::SEC1::-->
41Welcome to the Operating System Development course at Vienna. In this
42course, you will be working with an adapted version of the Pintos
43operating system, which was written by Ben Pfaff (See section <A HREF="pintos_1.html#SEC13">1.4 Acknowledgements</A>.)
44<P>
45
46So ... Welcome to Pintos. Pintos is a simple operating system framework for
47the 80<VAR>x</VAR>86 architecture. It supports kernel threads, loading and
48running user programs, and a file system, but it implements all of
49these in a very simple way. In the Pintos projects, you and your
50project team will strengthen its support in some of these areas.
51</P>
52<P>
53
54Pintos could, theoretically, run on a regular IBM-compatible PC.
55For simplicity, we will run Pintos projects in a system simulator, that is,
56a program that simulates an 80<VAR>x</VAR>86 CPU and its peripheral devices accurately
57enough that unmodified operating systems and software can run under it.
58In class we will use the
59<A HREF="http://bochs.sourceforge.net">Bochs</A> and
60<A HREF="http://fabrice.bellard.free.fr/qemu/">QEMU</A> simulators. Pintos has also been tested with
61<A HREF="http://www.vmware.com/">VMware Player</A>.
62</P>
63<P>
64
65The course at the University of Stanford, where pintos originated, has a
66reputation of taking a lot of time -- we suppose deservedly so.
67We will do what we can to reduce the workload, such as providing a lot
68of support material, but there is plenty of hard work that needs to be done.
69We welcome your feedback. If you have suggestions on how we can reduce the
70unnecessary overhead of assignments, cutting them down to the important
71underlying issues, please let us know.
72</P>
73<P>
74
75This chapter explains how to get started working with Pintos. You
76should read the entire chapter before you start work on any of the
77projects.
78</P>
79<P>
80
81<A NAME="Getting Started"></A>
82<HR SIZE="6">
83<A NAME="SEC2"></A>
84<H2> 1.1 Getting Started </H2>
85<!--docid::SEC2::-->
86<P>
87
88To get started, you'll have to log into a machine that Pintos can be
89built on. There are two possibilities: Either you work on one of the
90machines in the TILAB (<A HREF="ssh.tilab.tuwien.ac.at">ssh.tilab.tuwien.ac.at</A>), or you use
91a virtual machine such as KVM, VMWare Player or VirtualBox. You may
92also setup your own machine to build pintos, but in this case we
93cannot provide support for problems you might encounter.
94We will test your submission in the TILAB environment, and thus you should
95ensure that your code works there.
96</P>
97<P>
98
99Once you've logged into one of these machines, either locally or
100remotely, start out by extracting the pintos tarball, and adding
101our binaries directory to your <CODE>PATH</CODE> environment variable.
102</P>
103<P>
104
105Assuming that you extracted the pintos tarball to <Q><TT>$HOME/pintos</TT></Q>,
106you need to add pintos' <Q><TT>utils</TT></Q> directory to your <CODE>PATH</CODE>
107environment variable.
108<TABLE><tr><td>&nbsp;</td><td class=example><pre>PATH=$HOME/pintos/src/utils:$PATH
109</pre></td></tr></table>It is a good idea to add this line to your <Q><TT>$HOME/.bash_profile</TT></Q>
110startup script (or an equivalent script, if you do not happen to use bash).
111Otherwise, you'll have to type it every time you log in.
112<P>
113
114<A NAME="Source Tree Overview"></A>
115<HR SIZE="6">
116<A NAME="SEC3"></A>
117<H3> 1.1.1 Source Tree Overview </H3>
118<!--docid::SEC3::-->
119<P>
120
121Here's the directory structure that you should see in <Q><TT>pintos/src</TT></Q>:
122</P>
123<P>
124
125</P>
126<DL COMPACT>
127
128<DT><Q><TT>intro/</TT></Q>
129<DD>This directory is used to build the system and run tests for project 0.
130It only contains a Makefile, which describes how to build the system
131and run tests.
132<P>
133
134</P>
135<DT><Q><TT>threads/</TT></Q>
136<DD>Source code for the base kernel, which is the focus of project 1.
137<P>
138
139</P>
140<DT><Q><TT>userprog/</TT></Q>
141<DD>Source code for the user programs. You will complete the user program
142loader in project 0, and rely on the code in this directory in
143project 2.
144<P>
145
146</P>
147<DT><Q><TT>vm/</TT></Q>
148<DD>An almost empty directory. You will implement virtual memory here in
149project 2.
150<P>
151
152</P>
153<DT><Q><TT>filesys/</TT></Q>
154<DD>Source code for a basic file system. You will use this file system,
155but do not need to modify it in this course.
156<P>
157
158</P>
159<DT><Q><TT>devices/</TT></Q>
160<DD>Source code for I/O device interfacing: keyboard, timer, disk, etc.
161You will modify the timer implementation in project 0. Otherwise
162you should have no need to change this code.
163<P>
164
165</P>
166<DT><Q><TT>lib/</TT></Q>
167<DD>An implementation of a subset of the standard C library. The code in
168this directory is compiled into both the Pintos kernel and user
169programs that run under it. In both kernel code
170and user programs, headers in this directory can be included using the
171<CODE>#include &lt;<small>...</small>&gt;</CODE> notation. You should have little need to
172modify this code.
173<P>
174
175</P>
176<DT><Q><TT>lib/kernel/</TT></Q>
177<DD>Parts of the C library that are included only in the Pintos kernel.
178This also includes implementations of some data types that you are
179free to use in your kernel code: bitmaps, doubly linked lists, and
180hash tables. In the kernel, headers in this
181directory can be included using the <CODE>#include &lt;<small>...</small>&gt;</CODE>
182notation.
183<P>
184
185</P>
186<DT><Q><TT>lib/user/</TT></Q>
187<DD>Parts of the C library that are included only in Pintos user programs.
188In user programs, headers in this directory can be included using the
189<CODE>#include &lt;<small>...</small>&gt;</CODE> notation.
190<P>
191
192</P>
193<DT><Q><TT>tests/</TT></Q>
194<DD>Tests for each project. You can modify this code if it helps you test
195your submission, but we will replace it with the originals before we run
196the tests.
197<P>
198
199</P>
200<DT><Q><TT>examples/</TT></Q>
201<DD>Example user programs for use in project 0, and also project 2.
202<P>
203
204</P>
205<DT><Q><TT>misc/</TT></Q>
206<DD><DT><Q><TT>utils/</TT></Q>
207<DD>These files may come in handy if you decide to try working with Pintos
208on your own machine. Otherwise, you can ignore them.
209</DL>
210<P>
211
212<A NAME="Building Pintos"></A>
213<HR SIZE="6">
214<A NAME="SEC4"></A>
215<H3> 1.1.2 Building Pintos </H3>
216<!--docid::SEC4::-->
217<P>
218
219As the next step, build the source code supplied for
220the first project. First, <CODE>cd</CODE> into the <Q><TT>intro</TT></Q>
221directory. Then, issue the <Q><SAMP>make</SAMP></Q> command. This will create a
222<Q><TT>build</TT></Q> directory under <Q><TT>intro</TT></Q>, populate it with a
223<Q><TT>Makefile</TT></Q> and a few subdirectories, and then build the kernel
224inside. The entire build should take less than 30 seconds.
225</P>
226<P>
227
228Following the build, the following are the interesting files in the
229<Q><TT>build</TT></Q> directory:
230</P>
231<P>
232
233</P>
234<DL COMPACT>
235<DT><Q><TT>Makefile</TT></Q>
236<DD>A copy of <Q><TT>pintos/src/Makefile.build</TT></Q>. It describes how to build
237the kernel. See <A HREF="pintos_2.html#Adding Source Files">Adding Source Files</A>, for more information.
238<P>
239
240</P>
241<DT><Q><TT>kernel.o</TT></Q>
242<DD>Object file for the entire kernel. This is the result of linking
243object files compiled from each individual kernel source file into a
244single object file. It contains debug information, so you can run
245GDB (see section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>) or <CODE>backtrace</CODE> (see section <A HREF="pintos_8.html#SEC100">D.4 Backtraces</A>) on it.
246<P>
247
248</P>
249<DT><Q><TT>kernel.bin</TT></Q>
250<DD>Memory image of the kernel, that is, the exact bytes loaded into
251memory to run the Pintos kernel. This is just <Q><TT>kernel.o</TT></Q> with
252debug information stripped out, which saves a lot of space, which in
253turn keeps the kernel from bumping up against a 512 kB size limit
254imposed by the kernel loader's design.
255<P>
256
257</P>
258<DT><Q><TT>loader.bin</TT></Q>
259<DD>Memory image for the kernel loader, a small chunk of code written in
260assembly language that reads the kernel from disk into memory and
261starts it up. It is exactly 512 bytes long, a size fixed by the
262PC BIOS.
263</DL>
264<P>
265
266Subdirectories of <Q><TT>build</TT></Q> contain object files (<Q><TT>.o</TT></Q>) and
267dependency files (<Q><TT>.d</TT></Q>), both produced by the compiler. The
268dependency files tell <CODE>make</CODE> which source files need to be
269recompiled when other source or header files are changed.
270</P>
271<P>
272
273<A NAME="Running Pintos"></A>
274<HR SIZE="6">
275<A NAME="SEC5"></A>
276<H3> 1.1.3 Running Pintos </H3>
277<!--docid::SEC5::-->
278<P>
279
280We've supplied a program for conveniently running Pintos in a simulator,
281called <CODE>pintos</CODE>. In the simplest case, you can invoke
282<CODE>pintos</CODE> as <CODE>pintos <VAR>argument</VAR><small>...</small></CODE>. Each
283<VAR>argument</VAR> is passed to the Pintos kernel for it to act on.
284</P>
285<P>
286
287Try it out. First <CODE>cd</CODE> into the newly created <Q><TT>build</TT></Q>
288directory. Then issue the command
289<CODE>pintos -kernel-test run alarm-multiple</CODE>,
290which passes the arguments <CODE>run alarm-multiple</CODE> to the Pintos
291kernel. In these arguments, <CODE>run</CODE>, together with the kernel
292option <Q><SAMP>-kernel-test</SAMP></Q>, instructs the kernel to run a test and
293<CODE>alarm-multiple</CODE> is the test to run.
294</P>
295<P>
296
297This command creates a <Q><TT>bochsrc.txt</TT></Q> file, which is needed for
298running Bochs, and then invoke Bochs. Bochs opens a new window that
299represents the simulated machine's display, and a BIOS message briefly
300flashes. Then Pintos boots and runs the <CODE>alarm-multiple</CODE> test
301program, which outputs a few screenfuls of text. When it's done, you
302can close Bochs by clicking on the &quot;Power&quot; button in the window's top
303right corner, or rerun the whole process by clicking on the &quot;Reset&quot;
304button just to its left. The other buttons are not very useful for our
305purposes.
306</P>
307<P>
308
309(If no window appeared at all, then you're probably logged in remotely and X
310forwarding is not set up correctly. In this case, you can fix your X
311setup, or you can use the <Q><SAMP>-v</SAMP></Q> option to disable X output:
312<CODE>pintos -v -- -kernel-test run alarm-multiple</CODE>.)
313</P>
314<P>
315
316The text printed by Pintos inside Bochs probably went by too quickly to
317read. However, you've probably noticed by now that the same text was
318displayed in the terminal you used to run <CODE>pintos</CODE>. This is
319because Pintos sends all output both to the VGA display and to the first
320serial port, and by default the serial port is connected to Bochs's
321<CODE>stdin</CODE> and <CODE>stdout</CODE>. You can log serial output to a file by
322redirecting at the
323command line, e.g. <CODE>pintos run alarm-multiple &gt; logfile</CODE>.
324</P>
325<P>
326
327The <CODE>pintos</CODE> program offers several options for configuring the
328simulator or the virtual hardware. If you specify any options, they
329must precede the commands passed to the Pintos kernel and be separated
330from them by <Q><SAMP>--</SAMP></Q>, so that the whole command looks like
331<CODE>pintos <VAR>option</VAR><small>...</small> -- <VAR>argument</VAR><small>...</small></CODE>. Invoke
332<CODE>pintos</CODE> without any arguments to see a list of available options.
333Options can select a simulator to use: the default is Bochs, but
334<Q><SAMP>--qemu</SAMP></Q> selects QEMU. You can run the simulator
335with a debugger (see section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>). You can set the amount of memory to give
336the VM. Finally, you can select how you want VM output to be displayed:
337use <Q><SAMP>-v</SAMP></Q> to turn off the VGA display, <Q><SAMP>-t</SAMP></Q> to use your
338terminal window as the VGA display instead of opening a new window
339(Bochs only), or <Q><SAMP>-s</SAMP></Q> to suppress serial input from <CODE>stdin</CODE>
340and output to <CODE>stdout</CODE>.
341</P>
342<P>
343
344The Pintos kernel has commands and options other than <CODE>run</CODE>.
345These are not very interesting for now, but you can see a list of them
346using <Q><SAMP>-h</SAMP></Q>, e.g. <CODE>pintos -h</CODE>.
347</P>
348<P>
349
350<A NAME="Debugging versus Testing"></A>
351<HR SIZE="6">
352<A NAME="SEC6"></A>
353<H3> 1.1.4 Debugging versus Testing </H3>
354<!--docid::SEC6::-->
355<P>
356
357When you're debugging code, it's useful to be able to run a
358program twice and have it do exactly the same thing. On second and
359later runs, you can make new observations without having to discard or
360verify your old observations. This property is called
361&quot;reproducibility.&quot; One of the simulators that Pintos supports, Bochs,
362can be set up for
363reproducibility, and that's the way that <CODE>pintos</CODE> invokes it
364by default.
365</P>
366<P>
367
368Of course, a simulation can only be reproducible from one run to the
369next if its input is the same each time. For simulating an entire
370computer, as we do, this means that every part of the computer must be
371the same. For example, you must use the same command-line argument, the
372same disks, the same version
373of Bochs, and you must not hit any keys on the keyboard (because you
374could not be sure to hit them at exactly the same point each time)
375during the runs.
376</P>
377<P>
378
379While reproducibility is useful for debugging, it is a problem for
380testing thread synchronization, an important part of most of the projects. In
381particular, when Bochs is set up for reproducibility, timer interrupts
382will come at perfectly reproducible points, and therefore so will
383thread switches. That means that running the same test several times
384doesn't give you any greater confidence in your code's correctness
385than does running it only once.
386</P>
387<P>
388
389So, to make your code easier to test, we've added a feature, called
390&quot;jitter,&quot; to Bochs, that makes timer interrupts come at random
391intervals, but in a perfectly predictable way. In particular, if you
392invoke <CODE>pintos</CODE> with the option <Q><SAMP>-j <VAR>seed</VAR></SAMP></Q>, timer
393interrupts will come at irregularly spaced intervals. Within a single
394<VAR>seed</VAR> value, execution will still be reproducible, but timer
395behavior will change as <VAR>seed</VAR> is varied. Thus, for the highest
396degree of confidence you should test your code with many seed values.
397</P>
398<P>
399
400On the other hand, when Bochs runs in reproducible mode, timings are not
401realistic, meaning that a &quot;one-second&quot; delay may be much shorter or
402even much longer than one second. You can invoke <CODE>pintos</CODE> with
403a different option, <Q><SAMP>-r</SAMP></Q>, to set up Bochs for realistic
404timings, in which a one-second delay should take approximately one
405second of real time. Simulation in real-time mode is not reproducible,
406and options <Q><SAMP>-j</SAMP></Q> and <Q><SAMP>-r</SAMP></Q> are mutually exclusive.
407</P>
408<P>
409
410The QEMU simulator is available as an
411alternative to Bochs (use <Q><SAMP>--qemu</SAMP></Q> when invoking
412<CODE>pintos</CODE>). The QEMU simulator is much faster than Bochs, but it
413only supports real-time simulation and does not have a reproducible
414mode.
415</P>
416<P>
417
418<A NAME="Grading"></A>
419<HR SIZE="6">
420<A NAME="SEC7"></A>
421<H2> 1.2 Grading </H2>
422<!--docid::SEC7::-->
423<P>
424
425We will grade your assignments based on test results and design quality,
426inspecting both your implementation and your design documents.
427</P>
428<P>
429
430<A NAME="Testing"></A>
431<HR SIZE="6">
432<A NAME="SEC8"></A>
433<H3> 1.2.1 Testing </H3>
434<!--docid::SEC8::-->
435<P>
436
437Your test result grade will be based on our tests. Each project has
438several tests, each of which has a name beginning with <Q><TT>tests</TT></Q>.
439To completely test your submission, invoke <CODE>make check</CODE> from the
440project <Q><TT>build</TT></Q> directory. This will build and run each test and
441print a &quot;pass&quot; or &quot;fail&quot; message for each one. When a test fails,
442<CODE>make check</CODE> also prints some details of the reason for failure.
443After running all the tests, <CODE>make check</CODE> also prints a summary
444of the test results.
445</P>
446<P>
447
448For project 1, the tests will probably run faster in Bochs. For the
449other projects, they will run much faster in QEMU.
450<CODE>make check</CODE> will select the faster simulator by default, but
451you can override its choice by specifying <Q><SAMP>SIMULATOR=--bochs</SAMP></Q> or
452<Q><SAMP>SIMULATOR=--qemu</SAMP></Q> on the <CODE>make</CODE> command line.
453</P>
454<P>
455
456You can also run individual tests one at a time. A given test <VAR>t</VAR>
457writes its output to <Q><TT><VAR>t</VAR>.output</TT></Q>, then a script scores the
458output as &quot;pass&quot; or &quot;fail&quot; and writes the verdict to
459<Q><TT><VAR>t</VAR>.result</TT></Q>. To run and grade a single test, <CODE>make</CODE>
460the <Q><TT>.result</TT></Q> file explicitly from the <Q><TT>build</TT></Q> directory, e.g.
461<CODE>make tests/threads/alarm-multiple.result</CODE>. If <CODE>make</CODE> says
462that the test result is up-to-date, but you want to re-run it anyway,
463either run <CODE>make clean</CODE> or delete the <Q><TT>.output</TT></Q> file by hand.
464</P>
465<P>
466
467By default, each test provides feedback only at completion, not during
468its run. If you prefer, you can observe the progress of each test by
469specifying <Q><SAMP>VERBOSE=1</SAMP></Q> on the <CODE>make</CODE> command line, as in
470<CODE>make check VERBOSE=1</CODE>. You can also provide arbitrary options to the
471<CODE>pintos</CODE> run by the tests with <Q><SAMP>PINTOSOPTS='<small>...</small>'</SAMP></Q>,
472e.g. <CODE>make check PINTOSOPTS='-j 1'</CODE> to select a jitter value of 1
473(see section <A HREF="pintos_1.html#SEC6">1.1.4 Debugging versus Testing</A>).
474</P>
475<P>
476
477All of the tests and related files are in <Q><TT>pintos/src/tests</TT></Q>.
478Before we test your submission, we will replace the contents of that
479directory by a pristine, unmodified copy, to ensure that the correct
480tests are used. Thus, you can modify some of the tests if that helps in
481debugging, but we will run the originals.
482</P>
483<P>
484
485All software has bugs, so some of our tests may be flawed. If you think
486a test failure is a bug in the test, not a bug in your code,
487please point it out. We will look at it and fix it if necessary.
488</P>
489<P>
490
491Please don't try to take advantage of our generosity in giving out our
492test suite. Your code has to work properly in the general case, not
493just for the test cases we supply. For example, it would be unacceptable
494to explicitly base the kernel's behavior on the name of the running
495test case. Such attempts to side-step the test cases will receive no
496credit. If you think your solution may be in a gray area here, please
497ask us about it.
498</P>
499<P>
500
501<A NAME="Design"></A>
502<HR SIZE="6">
503<A NAME="SEC9"></A>
504<H3> 1.2.2 Design </H3>
505<!--docid::SEC9::-->
506<P>
507
508We will judge your design based on the design document and the source
509code that you submit. We will read your entire design document and much
510of your source code.
511</P>
512<P>
513
514Don't forget that design quality, including the design document, is 30%
515of your project grade. It
516is better to spend one or two hours writing a good design document than
517it is to spend that time getting the last 5% of the points for tests and
518then trying to rush through writing the design document in the last 15
519minutes.
520</P>
521<P>
522
523<A NAME="Design Document"></A>
524<HR SIZE="6">
525<A NAME="SEC10"></A>
526<H4> 1.2.2.1 Design Document </H4>
527<!--docid::SEC10::-->
528<P>
529
530We provide a design document template for each project. For each
531significant part of a project, the template asks questions in four
532areas:
533</P>
534<P>
535
536</P>
537<DL COMPACT>
538<DT><STRONG>Data Structures</STRONG>
539<DD><P>
540
541The instructions for this section are always the same:
542</P>
543<P>
544
545<BLOCKQUOTE>
546Copy here the declaration of each new or changed <CODE>struct</CODE> or
547<CODE>struct</CODE> member, global or static variable, <CODE>typedef</CODE>, or
548enumeration. Identify the purpose of each in 25 words or less.
549</BLOCKQUOTE>
550<P>
551
552The first part is mechanical. Just copy new or modified declarations
553into the design document, to highlight for us the actual changes to data
554structures. Each declaration should include the comment that should
555accompany it in the source code (see below).
556</P>
557<P>
558
559We also ask for a very brief description of the purpose of each new or
560changed data structure. The limit of 25 words or less is a guideline
561intended to save your time and avoid duplication with later areas.
562</P>
563<P>
564
565</P>
566<DT><STRONG>Algorithms</STRONG>
567<DD><P>
568
569This is where you tell us how your code works, through questions that
570probe your understanding of your code. We might not be able to easily
571figure it out from the code, because many creative solutions exist for
572most OS problems. Help us out a little.
573</P>
574<P>
575
576Your answers should be at a level below the high level description of
577requirements given in the assignment. We have read the assignment too,
578so it is unnecessary to repeat or rephrase what is stated there. On the
579other hand, your answers should be at a level above the low level of the
580code itself. Don't give a line-by-line run-down of what your code does.
581Instead, use your answers to explain how your code works to implement
582the requirements.
583</P>
584<P>
585
586</P>
587<DT><STRONG>Synchronization</STRONG>
588<DD><P>
589
590An operating system kernel is a complex, multithreaded program, in which
591synchronizing multiple threads can be difficult. This section asks
592about how you chose to synchronize this particular type of activity.
593</P>
594<P>
595
596</P>
597<DT><STRONG>Rationale</STRONG>
598<DD><P>
599
600Whereas the other sections primarily ask &quot;what&quot; and &quot;how,&quot; the
601rationale section concentrates on &quot;why.&quot; This is where we ask you to
602justify some design decisions, by explaining why the choices you made
603are better than alternatives. You may be able to state these in terms
604of time and space complexity, which can be made as rough or informal
605arguments (formal language or proofs are unnecessary).
606</DL>
607<P>
608
609An incomplete, evasive, or non-responsive design document or one that
610strays from the template without good reason may be penalized.
611Incorrect capitalization, punctuation, spelling, or grammar can also
612cost points. See section <A HREF="pintos_7.html#SEC93">C. Project Documentation</A>, for a sample design document
613for a fictitious project.
614</P>
615<P>
616
617<A NAME="Source Code"></A>
618<HR SIZE="6">
619<A NAME="SEC11"></A>
620<H4> 1.2.2.2 Source Code </H4>
621<!--docid::SEC11::-->
622<P>
623
624Your design will also be judged by looking at your source code. We will
625typically look at the differences between the original Pintos source
626tree and your submission, based on the output of a command like
627<CODE>diff -urpb pintos.orig pintos.submitted</CODE>. We will try to match up your
628description of the design with the code submitted. Important
629discrepancies between the description and the actual code will be
630penalized, as will be any bugs we find by spot checks.
631</P>
632<P>
633
634The most important aspects of source code design are those that specifically
635relate to the operating system issues at stake in the project. For
636example, the organization of the supplemental page table is an important
637part of virtual memory design, so in the virtual memory project a poorly designed
638pagetable would lose points. Other issues are much less important. For
639example, multiple Pintos design problems call for a &quot;priority
640queue,&quot; that is, a dynamic collection from which the minimum (or
641maximum) item can quickly be extracted. Fast priority queues can be
642implemented many ways, but we do not expect you to build a fancy data
643structure even if it might improve performance. Instead, you are
644welcome to use a linked list (and Pintos even provides one with
645convenient functions for sorting and finding minimums and maximums).
646</P>
647<P>
648
649Pintos is written in a consistent style. Make your additions and
650modifications in existing Pintos source files blend in, not stick out.
651In new source files, adopt the existing Pintos style by preference, but
652make your code self-consistent at the very least. There should not be a
653patchwork of different styles that makes it obvious that three different
654people wrote the code. Use horizontal and vertical white space to make
655code readable. Add a brief comment on every structure, structure
656member, global or static variable, typedef, enumeration, and function
657definition. Update
658existing comments as you modify code. Don't comment out or use the
659preprocessor to ignore blocks of code (instead, remove it entirely).
660Use assertions to document key invariants. Decompose code into
661functions for clarity. Code that is difficult to understand because it
662violates these or other &quot;common sense&quot; software engineering practices
663will be penalized.
664</P>
665<P>
666
667In the end, remember your audience. Code is written primarily to be
668read by humans. It has to be acceptable to the compiler too, but the
669compiler doesn't care about how it looks or how well it is written.
670</P>
671<P>
672
673<A NAME="Legal and Ethical Issues"></A>
674<HR SIZE="6">
675<A NAME="SEC12"></A>
676<H2> 1.3 Legal and Ethical Issues </H2>
677<!--docid::SEC12::-->
678<P>
679
680Pintos is distributed under a liberal license that allows free use,
681modification, and distribution. Students and others who work on Pintos
682own the code that they write and may use it for any purpose.
683Pintos comes with NO WARRANTY, not even for MERCHANTABILITY or FITNESS
684FOR A PARTICULAR PURPOSE.
685See section <A HREF="pintos_11.html#SEC117">License</A>, for details of the license and lack of warranty.
686</P>
687<P>
688
689In the context of the Operating System Development at Vienna University
690of Technology, please respect the spirit and the letter of the honor code
691by refraining from reading any homework solutions available online or
692elsewhere. Reading the source code for other operating system kernels,
693such as Linux or FreeBSD, is allowed, but do not copy code from them literally.
694Please cite the code that inspired your own in your design documentation.
695Additionally, please do not redistribute the modified Pintos environment
696used in this course. It contains partial solutions which might spoil the
697fun for people at other universities.
698</P>
699<P>
700
701<A NAME="Acknowledgements"></A>
702<HR SIZE="6">
703<A NAME="SEC13"></A>
704<H2> 1.4 Acknowledgements </H2>
705<!--docid::SEC13::-->
706The Pintos core and this documentation were originally written by Ben
707Pfaff <A HREF="mailto:blp@cs.stanford.edu">blp@cs.stanford.edu</A>.
708<P>
709
710Additional features were contributed by Anthony Romano
711<A HREF="mailto:chz@vt.edu">chz@vt.edu</A>.
712</P>
713<P>
714
715The GDB macros supplied with Pintos were written by Godmar Back
716<A HREF="mailto:gback@cs.vt.edu">gback@cs.vt.edu</A>, and their documentation is adapted from his
717work.
718</P>
719<P>
720
721The original structure and form of Pintos was inspired by the Nachos
722instructional operating system from the University of California,
723Berkeley ([ <A HREF="pintos_10.html#Christopher">Christopher</A>]).
724</P>
725<P>
726
727The Pintos projects and documentation originated with those designed for
728Nachos by current and former CS 140 teaching assistants at Stanford
729University, including at least Yu Ping, Greg Hutchins, Kelly Shaw, Paul
730Twohey, Sameer Qureshi, and John Rector.
731</P>
732<P>
733
734Example code for monitors (see section <A HREF="pintos_5.html#SEC62">A.3.4 Monitors</A>) is
735from classroom slides originally by Dawson Engler and updated by Mendel
736Rosenblum.
737</P>
738<P>
739
740For the undergraduate OS Development course at Vienna UT, Rene Freingruber
741<A HREF="mailto:renefreing@yahoo.de">renefreing@yahoo.de</A> evaluated Pintos, and provided information on
742expected work hours and typical pitfalls. Benedikt Huber
743<A HREF="mailto:benedikt@vmars.tuwien.ac.at">benedikt@vmars.tuwien.ac.at</A> adapted Pintos and its documentation to
744meet the requirements of the course; Roland Kammerer
745<A HREF="mailto:kammerer@vmars.tuwien.ac.at">kammerer@vmars.tuwien.ac.at</A> created the virtual machine environments
746to simplify working outside the lab.
747</P>
748<P>
749
750<A NAME="Trivia"></A>
751<HR SIZE="6">
752<A NAME="SEC14"></A>
753<H2> 1.5 Trivia </H2>
754<!--docid::SEC14::-->
755<P>
756
757Pintos originated as a replacement for Nachos with a similar design.
758Since then Pintos has greatly diverged from the Nachos design. Pintos
759differs from Nachos in two important ways. First, Pintos runs on real
760or simulated 80<VAR>x</VAR>86 hardware, but Nachos runs as a process on a
761host operating system. Second, Pintos is written in C like most
762real-world operating systems, but Nachos is written in C++.
763</P>
764<P>
765
766Why the name &quot;Pintos&quot;? First, like nachos, pinto beans are a common
767Mexican food. Second, Pintos is small and a &quot;pint&quot; is a small amount.
768Third, like drivers of the eponymous car, students are likely to have
769trouble with blow-ups.
770<A NAME="Project 0--Introducing Pintos"></A>
771<HR SIZE="6">
772<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
773<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_1.html#SEC1"> &lt;&lt; </A>]</TD>
774<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_2.html#SEC15"> &gt;&gt; </A>]</TD>
775<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
776<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
777<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
778<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
779</TR></TABLE>
780<BR>
781<FONT SIZE="-1">
782This document was generated
783by on <I>March, 6 2012</I>
784using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
785</FONT>
786
787</BODY>
788</HTML>
diff --git a/doc/pintos_10.html b/doc/pintos_10.html
new file mode 100644
index 0000000..8bd02bc
--- /dev/null
+++ b/doc/pintos_10.html
@@ -0,0 +1,286 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Bibliography</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Bibliography">
18<META NAME="keywords" CONTENT="Pintos Projects: Bibliography">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC113"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> Bibliography </H1>
39<!--docid::SEC113::-->
40<P>
41
42<A NAME="Hardware References"></A>
43<HR SIZE="6">
44<A NAME="SEC114"></A>
45<H2> E.4 Hardware References </H2>
46<!--docid::SEC114::-->
47<P>
48
49<A NAME="IA32-v1"></A>
50[IA32-v1].
51IA-32 Intel Architecture Software Developer's Manual Volume 1: Basic
52Architecture. Basic 80<VAR>x</VAR>86 architecture and programming
53environment. Available via <A HREF="developer.intel.com">developer.intel.com</A>. Section numbers
54in this document refer to revision 18.
55</P>
56<P>
57
58<A NAME="IA32-v2a"></A>
59[IA32-v2a].
60IA-32 Intel Architecture Software Developer's Manual
61Volume 2A: Instruction Set Reference A-M. 80<VAR>x</VAR>86 instructions
62whose names begin with A through M. Available via
63<A HREF="developer.intel.com">developer.intel.com</A>. Section numbers in this document refer to
64revision 18.
65</P>
66<P>
67
68<A NAME="IA32-v2b"></A>
69[IA32-v2b].
70IA-32 Intel Architecture Software Developer's Manual Volume 2B:
71Instruction Set Reference N-Z. 80<VAR>x</VAR>86 instructions whose names
72begin with N through Z. Available via <A HREF="developer.intel.com">developer.intel.com</A>.
73Section numbers in this document refer to revision 18.
74</P>
75<P>
76
77<A NAME="IA32-v3a"></A>
78[IA32-v3a].
79IA-32 Intel Architecture Software Developer's Manual Volume 3A: System
80Programming Guide. Operating system support, including segmentation,
81paging, tasks, interrupt and exception handling. Available via
82<A HREF="developer.intel.com">developer.intel.com</A>. Section numbers in this document refer to
83revision 18.
84</P>
85<P>
86
87<A NAME="FreeVGA"></A>
88[FreeVGA].
89<A HREF="specs/freevga/home.htm">FreeVGA Project</A>. Documents the VGA video
90hardware used in PCs.
91</P>
92<P>
93
94<A NAME="kbd"></A>
95[kbd].
96<A HREF="specs/kbd/scancodes.html">Keyboard scancodes</A>. Documents PC keyboard
97interface.
98</P>
99<P>
100
101<A NAME="ATA-3"></A>
102[ATA-3].
103<A HREF="specs/ata-3-std.pdf">AT Attachment-3 Interface (ATA-3) Working
104Draft</A>. Draft of an old version of the ATA aka IDE interface for the
105disks used in most desktop PCs.
106</P>
107<P>
108
109<A NAME="PC16550D"></A>
110[PC16550D].
111<A HREF="specs/pc16550d.pdf">National Semiconductor PC16550D Universal
112Asynchronous Receiver/Transmitter with FIFOs</A>. Datasheet for a chip
113used for PC serial ports.
114</P>
115<P>
116
117<A NAME="8254"></A>
118[8254].
119<A HREF="specs/8254.pdf">Intel 8254 Programmable Interval Timer</A>.
120Datasheet for PC timer chip.
121</P>
122<P>
123
124<A NAME="8259A"></A>
125[8259A].
126<A HREF="specs/8259A.pdf">Intel 8259A Programmable Interrupt Controller
127(8259A/8259A-2)</A>. Datasheet for PC interrupt controller chip.
128</P>
129<P>
130
131<A NAME="MC146818A"></A>
132[MC146818A].
133<A HREF="specs/mc146818a.pdf">Motorola MC146818A Real Time Clock Plus
134Ram (RTC)</A>. Datasheet for PC real-time clock chip.
135</P>
136<P>
137
138<A NAME="Software References"></A>
139<HR SIZE="6">
140<A NAME="SEC115"></A>
141<H2> E.5 Software References </H2>
142<!--docid::SEC115::-->
143<P>
144
145<A NAME="ELF1"></A>
146[ELF1].
147<A HREF="specs/elf.pdf">Tool Interface Standard (TIS) Executable and
148Linking Format (ELF) Specification Version 1.2 Book I: Executable and
149Linking Format</A>. The ubiquitous format for executables in modern Unix
150systems.
151</P>
152<P>
153
154<A NAME="ELF2"></A>
155[ELF2].
156<A HREF="specs/elf.pdf">Tool Interface Standard (TIS) Executable and
157Linking Format (ELF) Specification Version 1.2 Book II: Processor
158Specific (Intel Architecture)</A>. 80<VAR>x</VAR>86-specific parts of ELF.
159</P>
160<P>
161
162<A NAME="ELF3"></A>
163[ELF3].
164<A HREF="specs/elf.pdf">Tool Interface Standard (TIS) Executable and
165Linking Format (ELF) Specification Version 1.2 Book III: Operating
166System Specific (UNIX System V Release 4)</A>. Unix-specific parts of
167ELF.
168</P>
169<P>
170
171<A NAME="SysV-ABI"></A>
172[SysV-ABI].
173<A HREF="specs/sysv-abi-4.1.pdf">System V Application Binary Interface:
174Edition 4.1</A>. Specifies how applications interface with the OS under
175Unix.
176</P>
177<P>
178
179<A NAME="SysV-i386"></A>
180[SysV-i386].
181<A HREF="specs/sysv-abi-i386-4.pdf">System V Application Binary
182Interface: Intel386 Architecture Processor Supplement: Fourth
183Edition</A>. 80<VAR>x</VAR>86-specific parts of the Unix interface.
184</P>
185<P>
186
187<A NAME="SysV-ABI-update"></A>
188[SysV-ABI-update].
189<A HREF="specs/sysv-abi-update.html/contents.html">System V Application Binary
190Interface--DRAFT--24 April 2001</A>. A draft of a revised version of
191[ <A HREF="pintos_10.html#SysV-ABI">SysV-ABI</A>] which was never completed.
192</P>
193<P>
194
195<A NAME="SUSv3"></A>
196[SUSv3].
197The Open Group, <A HREF="http://www.unix.org/single_unix_specification/">Single UNIX Specification V3</A>, 2001.
198</P>
199<P>
200
201<A NAME="Partitions"></A>
202[Partitions].
203A. E. Brouwer, <A HREF="specs/partitions/partition_tables.html">Minimal partition table specification</A>, 1999.
204</P>
205<P>
206
207<A NAME="IntrList"></A>
208[IntrList].
209R. Brown, <A HREF="http://www.ctyme.com/rbrown.htm">Ralf Brown's
210Interrupt List</A>, 2000.
211</P>
212<P>
213
214<A NAME="Operating System Design References"></A>
215<HR SIZE="6">
216<A NAME="SEC116"></A>
217<H2> E.6 Operating System Design References </H2>
218<!--docid::SEC116::-->
219<P>
220
221<A NAME="Christopher"></A>
222[Christopher].
223W. A. Christopher, S. J. Procter, T. E. Anderson,
224<CITE>The Nachos instructional operating system</CITE>.
225Proceedings of the <ACRONYM>USENIX</ACRONYM> Winter 1993 Conference.
226<A HREF="http://portal.acm.org/citation.cfm?id=1267307">http://portal.acm.org/citation.cfm?id=1267307</A>.
227</P>
228<P>
229
230<A NAME="Dijkstra"></A>
231[Dijkstra].
232E. W. Dijkstra, <CITE>The structure of the &quot;THE&quot;
233multiprogramming system</CITE>. Communications of the ACM 11(5):341--346,
2341968. <A HREF="http://doi.acm.org/10.1145/363095.363143">http://doi.acm.org/10.1145/363095.363143</A>.
235</P>
236<P>
237
238<A NAME="Hoare"></A>
239[Hoare].
240C. A. R. Hoare, <CITE>Monitors: An Operating System
241Structuring Concept</CITE>. Communications of the ACM, 17(10):549--557,
2421974. <A HREF="http://www.acm.org/classics/feb96/">http://www.acm.org/classics/feb96/</A>.
243</P>
244<P>
245
246<A NAME="Lampson"></A>
247[Lampson].
248B. W. Lampson, D. D. Redell, <CITE>Experience with processes and
249monitors in Mesa</CITE>. Communications of the ACM, 23(2):105--117, 1980.
250<A HREF="http://doi.acm.org/10.1145/358818.358824">http://doi.acm.org/10.1145/358818.358824</A>.
251</P>
252<P>
253
254<A NAME="McKusick"></A>
255[McKusick].
256M. K. McKusick, K. Bostic, M. J. Karels, J. S. Quarterman,
257<CITE>The Design and Implementation of the 4.4<ACRONYM>BSD</ACRONYM> Operating
258System</CITE>. Addison-Wesley, 1996.
259</P>
260<P>
261
262<A NAME="Wilson"></A>
263[Wilson].
264P. R. Wilson, M. S. Johnstone, M. Neely, D. Boles,
265<CITE>Dynamic Storage Allocation: A Survey and Critical Review</CITE>.
266International Workshop on Memory Management, 1995.
267<A HREF="http://www.cs.utexas.edu/users/oops/papers.html#allocsrv">http://www.cs.utexas.edu/users/oops/papers.html#allocsrv</A>.
268<A NAME="License"></A>
269<HR SIZE="6">
270<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
271<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_9.html#SEC109"> &lt;&lt; </A>]</TD>
272<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_11.html#SEC117"> &gt;&gt; </A>]</TD>
273<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
274<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
275<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
276<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
277</TR></TABLE>
278<BR>
279<FONT SIZE="-1">
280This document was generated
281by on <I>March, 6 2012</I>
282using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
283</FONT>
284
285</BODY>
286</HTML>
diff --git a/doc/pintos_11.html b/doc/pintos_11.html
new file mode 100644
index 0000000..d34b895
--- /dev/null
+++ b/doc/pintos_11.html
@@ -0,0 +1,137 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: License</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: License">
18<META NAME="keywords" CONTENT="Pintos Projects: License">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC117"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> License </H1>
39<!--docid::SEC117::-->
40<P>
41
42Pintos, including its documentation, is subject to the following
43license:
44</P>
45<P>
46
47<BLOCKQUOTE>
48Copyright &copy; 2004, 2005, 2006 Board of Trustees, Leland
49Stanford Jr. University. All rights reserved.
50<P>
51
52Permission is hereby granted, free of charge, to any person obtaining
53a copy of this software and associated documentation files (the
54&quot;Software&quot;), to deal in the Software without restriction, including
55without limitation the rights to use, copy, modify, merge, publish,
56distribute, sublicense, and/or sell copies of the Software, and to
57permit persons to whom the Software is furnished to do so, subject to
58the following conditions:
59</P>
60<P>
61
62The above copyright notice and this permission notice shall be
63included in all copies or substantial portions of the Software.
64</P>
65<P>
66
67THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND,
68EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
69MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
70NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
71LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
72OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
73WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
74</BLOCKQUOTE>
75<P>
76
77A few individual files in Pintos were originally derived from other
78projects, but they have been extensively modified for use in Pintos.
79The original code falls under the original license, and modifications
80for Pintos are additionally covered by the Pintos license above.
81</P>
82<P>
83
84In particular, code derived from Nachos is subject to the following
85license:
86</P>
87<P>
88
89<BLOCKQUOTE>
90Copyright &copy; 1992-1996 The Regents of the University of California.
91All rights reserved.
92<P>
93
94Permission to use, copy, modify, and distribute this software
95and its documentation for any purpose, without fee, and
96without written agreement is hereby granted, provided that the
97above copyright notice and the following two paragraphs appear
98in all copies of this software.
99</P>
100<P>
101
102IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO
103ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
104CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE
105AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
106HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
107</P>
108<P>
109
110THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
111WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
112WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
113PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN &quot;AS IS&quot;
114BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
115PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
116MODIFICATIONS.
117</BLOCKQUOTE>
118<P>
119
120<HR SIZE="6">
121<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
122<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
123<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
124<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
125<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
126<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
127<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
128</TR></TABLE>
129<BR>
130<FONT SIZE="-1">
131This document was generated
132by on <I>March, 6 2012</I>
133using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
134</FONT>
135
136</BODY>
137</HTML>
diff --git a/doc/pintos_2.html b/doc/pintos_2.html
new file mode 100644
index 0000000..ae51974
--- /dev/null
+++ b/doc/pintos_2.html
@@ -0,0 +1,1734 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Project 0--Introducing Pintos</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Project 0--Introducing Pintos">
18<META NAME="keywords" CONTENT="Pintos Projects: Project 0--Introducing Pintos">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC15"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_1.html#SEC1"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_3.html#SEC41"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> 2. Project 0: Introducing Pintos </H1>
39<!--docid::SEC15::-->
40<P>
41
42In this assignment, you will learn about the existing functionality
43in Pintos, and add two small features to the system: a more efficient
44implementation of <Q><SAMP>sleep</SAMP></Q>, and the ability to pass command line
45arguments to user programs.
46</P>
47<P>
48
49You will be working in the <Q><TT>threads</TT></Q> directory for the first part
50of this assignment (with some work in the <Q><TT>devices</TT></Q> directory on
51the side), and modify the file <Q><TT>userprog/process.c</TT></Q> in the second part.
52</P>
53<P>
54
55The tests for Project 0 are executed by changing the working directory
56to <Q><TT>intro</TT></Q> and running <Q><SAMP>make</SAMP></Q> followed by <Q><SAMP>make check</SAMP></Q>.
57</P>
58<P>
59
60Before you read the description of this project, you should read all of
61the following sections: <A HREF="pintos_1.html#SEC1">1. Introduction</A>, <A HREF="pintos_6.html#SEC89">B. Coding Standards</A>,
62<A HREF="pintos_8.html#SEC96">D. Debugging Tools</A>, and <A HREF="pintos_9.html#SEC109">E. Development Tools</A>. You should at least
63skim the material from <A HREF="pintos_5.html#SEC49">A.1 Loading</A> through <A HREF="pintos_5.html#SEC69">A.5 Memory Allocation</A>, especially <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>.
64</P>
65<P>
66
67<A NAME="Understanding Threads"></A>
68<HR SIZE="6">
69<A NAME="SEC16"></A>
70<H2> 2.1 Understanding Threads </H2>
71<!--docid::SEC16::-->
72<P>
73
74The first step is to read and understand the code for the initial thread
75system.
76Pintos already implements thread creation and thread completion,
77a simple scheduler to switch between threads, and synchronization
78primitives (semaphores, locks, condition variables, and optimization
79barriers).
80</P>
81<P>
82
83Some of this code might seem slightly mysterious. If
84you haven't already compiled and run the base system, as described in
85the introduction (see section <A HREF="pintos_1.html#SEC1">1. Introduction</A>), you should do so now. You
86can read through parts of the source code to see what's going
87on. If you like, you can add calls to <CODE>printf()</CODE> almost
88anywhere, then recompile and run to see what happens and in what
89order. You can also run the kernel in a debugger and set breakpoints
90at interesting spots, single-step through code and examine data, and
91so on.
92</P>
93<P>
94
95When a thread is created, you are creating a new context to be
96scheduled. You provide a function to be run in this context as an
97argument to <CODE>thread_create()</CODE>. The first time the thread is
98scheduled and runs, it starts from the beginning of that function
99and executes in that context. When the function returns, the thread
100terminates. Each thread, therefore, acts like a mini-program running
101inside Pintos, with the function passed to <CODE>thread_create()</CODE>
102acting like <CODE>main()</CODE>.
103</P>
104<P>
105
106At any given time, exactly one thread runs and the rest, if any,
107become inactive. The scheduler decides which thread to
108run next. (If no thread is ready to run
109at any given time, then the special &quot;idle&quot; thread, implemented in
110<CODE>idle()</CODE>, runs.)
111Synchronization primitives can force context switches when one
112thread needs to wait for another thread to do something.
113</P>
114<P>
115
116The mechanics of a context switch are
117in <Q><TT>threads/switch.S</TT></Q>, which is 80<VAR>x</VAR>86
118assembly code. (You don't have to understand it.) It saves the
119state of the currently running thread and restores the state of the
120thread we're switching to.
121</P>
122<P>
123
124Using the GDB debugger, slowly trace through a context
125switch to see what happens (see section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>). You can set a
126breakpoint on <CODE>schedule()</CODE> to start out, and then
127single-step from there.<A NAME="DOCF1" HREF="pintos_fot.html#FOOT1">(1)</A> Be sure
128to keep track of each thread's address
129and state, and what procedures are on the call stack for each thread.
130You will notice that when one thread calls <CODE>switch_threads()</CODE>,
131another thread starts running, and the first thing the new thread does
132is to return from <CODE>switch_threads()</CODE>. You will understand the thread
133system once you understand why and how the <CODE>switch_threads()</CODE> that
134gets called is different from the <CODE>switch_threads()</CODE> that returns.
135See section <A HREF="pintos_5.html#SEC57">A.2.3 Thread Switching</A>, for more information.
136</P>
137<P>
138
139<STRONG>Warning</STRONG>: In Pintos, each thread is assigned a small,
140fixed-size execution stack just under 4 kB in size. The kernel
141tries to detect stack overflow, but it cannot do so perfectly. You
142may cause bizarre problems, such as mysterious kernel panics, if you
143declare large data structures as non-static local variables,
144e.g. <Q><SAMP>int buf[1000];</SAMP></Q>. Alternatives to stack allocation include
145the page allocator and the block allocator (see section <A HREF="pintos_5.html#SEC69">A.5 Memory Allocation</A>).
146</P>
147<P>
148
149<A NAME="Project 1 Source Files"></A>
150<HR SIZE="6">
151<A NAME="SEC17"></A>
152<H3> 2.1.1 Source Files </H3>
153<!--docid::SEC17::-->
154<P>
155
156Here is a brief overview of the files in the <Q><TT>threads</TT></Q>
157directory. You will not need to modify most of this code, but the
158hope is that presenting this overview will give you a start on what
159code to look at.
160</P>
161<P>
162
163</P>
164<DL COMPACT>
165<DT><Q><TT>loader.S</TT></Q>
166<DD><DT><Q><TT>loader.h</TT></Q>
167<DD>The kernel loader. Assembles to 512 bytes of code and data that the
168PC BIOS loads into memory and which in turn finds the kernel on disk,
169loads it into memory, and jumps to <CODE>start()</CODE> in <Q><TT>start.S</TT></Q>.
170See section <A HREF="pintos_5.html#SEC50">A.1.1 The Loader</A>, for details. You should not need to look at
171this code or modify it.
172<P>
173
174</P>
175<DT><Q><TT>start.S</TT></Q>
176<DD>Does basic setup needed for memory protection and 32-bit
177operation on 80<VAR>x</VAR>86 CPUs. Unlike the loader, this code is
178actually part of the kernel. See section <A HREF="pintos_5.html#SEC51">A.1.2 Low-Level Kernel Initialization</A>,
179for details.
180<P>
181
182</P>
183<DT><Q><TT>kernel.lds.S</TT></Q>
184<DD>The linker script used to link the kernel. Sets the load address of
185the kernel and arranges for <Q><TT>start.S</TT></Q> to be near the beginning
186of the kernel image. See section <A HREF="pintos_5.html#SEC50">A.1.1 The Loader</A>, for details. Again, you
187should not need to look at this code
188or modify it, but it's here in case you're curious.
189<P>
190
191</P>
192<DT><Q><TT>init.c</TT></Q>
193<DD><DT><Q><TT>init.h</TT></Q>
194<DD>Kernel initialization, including <CODE>main()</CODE>, the kernel's &quot;main
195program.&quot; You should look over <CODE>main()</CODE> at least to see what
196gets initialized. You might want to add your own initialization code
197here. See section <A HREF="pintos_5.html#SEC52">A.1.3 High-Level Kernel Initialization</A>, for details.
198<P>
199
200</P>
201<DT><Q><TT>thread.c</TT></Q>
202<DD><DT><Q><TT>thread.h</TT></Q>
203<DD>Basic thread support. Much of your work will take place in these files.
204<Q><TT>thread.h</TT></Q> defines <CODE>struct thread</CODE>, which you are likely to modify
205in all three projects. See <A HREF="pintos_5.html#SEC55">A.2.1 <CODE>struct thread</CODE></A> and <A HREF="pintos_5.html#SEC54">A.2 Threads</A> for
206more information.
207<P>
208
209</P>
210<DT><Q><TT>switch.S</TT></Q>
211<DD><DT><Q><TT>switch.h</TT></Q>
212<DD>Assembly language routine for switching threads. Already discussed
213above. See section <A HREF="pintos_5.html#SEC56">A.2.2 Thread Functions</A>, for more information.
214<P>
215
216</P>
217<DT><Q><TT>palloc.c</TT></Q>
218<DD><DT><Q><TT>palloc.h</TT></Q>
219<DD>Page allocator, which hands out system memory in multiples of 4 kB
220pages. See section <A HREF="pintos_5.html#SEC70">A.5.1 Page Allocator</A>, for more information.
221<P>
222
223</P>
224<DT><Q><TT>malloc.c</TT></Q>
225<DD><DT><Q><TT>malloc.h</TT></Q>
226<DD>A simple implementation of <CODE>malloc()</CODE> and <CODE>free()</CODE> for
227the kernel. See section <A HREF="pintos_5.html#SEC71">A.5.2 Block Allocator</A>, for more information.
228<P>
229
230</P>
231<DT><Q><TT>interrupt.c</TT></Q>
232<DD><DT><Q><TT>interrupt.h</TT></Q>
233<DD>Basic interrupt handling and functions for turning interrupts on and
234off. See section <A HREF="pintos_5.html#SEC65">A.4 Interrupt Handling</A>, for more information.
235<P>
236
237</P>
238<DT><Q><TT>intr-stubs.S</TT></Q>
239<DD><DT><Q><TT>intr-stubs.h</TT></Q>
240<DD>Assembly code for low-level interrupt handling. See section <A HREF="pintos_5.html#SEC66">A.4.1 Interrupt Infrastructure</A>, for more information.
241<P>
242
243</P>
244<DT><Q><TT>synch.c</TT></Q>
245<DD><DT><Q><TT>synch.h</TT></Q>
246<DD>Basic synchronization primitives: semaphores, locks, condition
247variables, and optimization barriers. You will need to use these for
248synchronization in all
249four projects. See section <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>, for more information.
250<P>
251
252</P>
253<DT><Q><TT>io.h</TT></Q>
254<DD>Functions for I/O port access. This is mostly used by source code in
255the <Q><TT>devices</TT></Q> directory that you won't have to touch.
256<P>
257
258</P>
259<DT><Q><TT>vaddr.h</TT></Q>
260<DD><DT><Q><TT>pte.h</TT></Q>
261<DD>Functions and macros for working with virtual addresses and page table
262entries. These will be more important to you in project 2. For now,
263you can ignore them.
264<P>
265
266</P>
267<DT><Q><TT>flags.h</TT></Q>
268<DD>Macros that define a few bits in the 80<VAR>x</VAR>86 &quot;flags&quot; register.
269Probably of no interest. See [ <A HREF="pintos_10.html#IA32-v1">IA32-v1</A>], section 3.4.3, &quot;EFLAGS
270Register,&quot; for more information.
271</DL>
272<P>
273
274<A NAME="devices code"></A>
275<HR SIZE="6">
276<A NAME="SEC18"></A>
277<H4> 2.1.1.1 <Q><TT>devices</TT></Q> code </H4>
278<!--docid::SEC18::-->
279<P>
280
281The basic threaded kernel also includes these files in the
282<Q><TT>devices</TT></Q> directory:
283</P>
284<P>
285
286</P>
287<DL COMPACT>
288<DT><Q><TT>timer.c</TT></Q>
289<DD><DT><Q><TT>timer.h</TT></Q>
290<DD>System timer that ticks, by default, 100 times per second. You will
291modify this code in this project.
292<P>
293
294</P>
295<DT><Q><TT>vga.c</TT></Q>
296<DD><DT><Q><TT>vga.h</TT></Q>
297<DD>VGA display driver. Responsible for writing text to the screen.
298You should have no need to look at this code. <CODE>printf()</CODE>
299calls into the VGA display driver for you, so there's little reason to
300call this code yourself.
301<P>
302
303</P>
304<DT><Q><TT>serial.c</TT></Q>
305<DD><DT><Q><TT>serial.h</TT></Q>
306<DD>Serial port driver. Again, <CODE>printf()</CODE> calls this code for you,
307so you don't need to do so yourself.
308It handles serial input by passing it to the input layer (see below).
309<P>
310
311</P>
312<DT><Q><TT>block.c</TT></Q>
313<DD><DT><Q><TT>block.h</TT></Q>
314<DD>An abstraction layer for <EM>block devices</EM>, that is, random-access,
315disk-like devices that are organized as arrays of fixed-size blocks.
316Out of the box, Pintos supports two types of block devices: IDE disks
317and partitions.
318<P>
319
320</P>
321<DT><Q><TT>ide.c</TT></Q>
322<DD><DT><Q><TT>ide.h</TT></Q>
323<DD>Supports reading and writing sectors on up to 4 IDE disks.
324<P>
325
326</P>
327<DT><Q><TT>partition.c</TT></Q>
328<DD><DT><Q><TT>partition.h</TT></Q>
329<DD>Understands the structure of partitions on disks, allowing a single
330disk to be carved up into multiple regions (partitions) for
331independent use.
332<P>
333
334</P>
335<DT><Q><TT>kbd.c</TT></Q>
336<DD><DT><Q><TT>kbd.h</TT></Q>
337<DD>Keyboard driver. Handles keystrokes passing them to the input layer
338(see below).
339<P>
340
341</P>
342<DT><Q><TT>input.c</TT></Q>
343<DD><DT><Q><TT>input.h</TT></Q>
344<DD>Input layer. Queues input characters passed along by the keyboard or
345serial drivers.
346<P>
347
348</P>
349<DT><Q><TT>intq.c</TT></Q>
350<DD><DT><Q><TT>intq.h</TT></Q>
351<DD>Interrupt queue, for managing a circular queue that both kernel
352threads and interrupt handlers want to access. Used by the keyboard
353and serial drivers.
354<P>
355
356</P>
357<DT><Q><TT>rtc.c</TT></Q>
358<DD><DT><Q><TT>rtc.h</TT></Q>
359<DD>Real-time clock driver, to enable the kernel to determine the current
360date and time. By default, this is only used by <Q><TT>thread/init.c</TT></Q>
361to choose an initial seed for the random number generator.
362<P>
363
364</P>
365<DT><Q><TT>speaker.c</TT></Q>
366<DD><DT><Q><TT>speaker.h</TT></Q>
367<DD>Driver that can produce tones on the PC speaker.
368<P>
369
370</P>
371<DT><Q><TT>pit.c</TT></Q>
372<DD><DT><Q><TT>pit.h</TT></Q>
373<DD>Code to configure the 8254 Programmable Interrupt Timer. This code is
374used by both <Q><TT>devices/timer.c</TT></Q> and <Q><TT>devices/speaker.c</TT></Q>
375because each device uses one of the PIT's output channel.
376</DL>
377<P>
378
379<A NAME="lib files"></A>
380<HR SIZE="6">
381<A NAME="SEC19"></A>
382<H4> 2.1.1.2 <Q><TT>lib</TT></Q> files </H4>
383<!--docid::SEC19::-->
384<P>
385
386Finally, <Q><TT>lib</TT></Q> and <Q><TT>lib/kernel</TT></Q> contain useful library
387routines. (<Q><TT>lib/user</TT></Q> will be used by user programs, starting in
388project 2, but it is not part of the kernel.) Here's a few more
389details:
390</P>
391<P>
392
393</P>
394<DL COMPACT>
395<DT><Q><TT>ctype.h</TT></Q>
396<DD><DT><Q><TT>inttypes.h</TT></Q>
397<DD><DT><Q><TT>limits.h</TT></Q>
398<DD><DT><Q><TT>stdarg.h</TT></Q>
399<DD><DT><Q><TT>stdbool.h</TT></Q>
400<DD><DT><Q><TT>stddef.h</TT></Q>
401<DD><DT><Q><TT>stdint.h</TT></Q>
402<DD><DT><Q><TT>stdio.c</TT></Q>
403<DD><DT><Q><TT>stdio.h</TT></Q>
404<DD><DT><Q><TT>stdlib.c</TT></Q>
405<DD><DT><Q><TT>stdlib.h</TT></Q>
406<DD><DT><Q><TT>string.c</TT></Q>
407<DD><DT><Q><TT>string.h</TT></Q>
408<DD>A subset of the standard C library. See section <A HREF="pintos_6.html#SEC91">B.2 C99</A>, for
409information
410on a few recently introduced pieces of the C library that you might
411not have encountered before. See section <A HREF="pintos_6.html#SEC92">B.3 Unsafe String Functions</A>, for
412information on what's been intentionally left out for safety.
413<P>
414
415</P>
416<DT><Q><TT>debug.c</TT></Q>
417<DD><DT><Q><TT>debug.h</TT></Q>
418<DD>Functions and macros to aid debugging. See section <A HREF="pintos_8.html#SEC96">D. Debugging Tools</A>, for
419more information.
420<P>
421
422</P>
423<DT><Q><TT>random.c</TT></Q>
424<DD><DT><Q><TT>random.h</TT></Q>
425<DD>Pseudo-random number generator. The actual sequence of random values
426will not vary from one Pintos run to another, unless you do one of
427three things: specify a new random seed value on the <Q><SAMP>-rs</SAMP></Q>
428kernel command-line option on each run, or use a simulator other than
429Bochs, or specify the <Q><SAMP>-r</SAMP></Q> option to <CODE>pintos</CODE>.
430<P>
431
432</P>
433<DT><Q><TT>round.h</TT></Q>
434<DD>Macros for rounding.
435<P>
436
437</P>
438<DT><Q><TT>syscall-nr.h</TT></Q>
439<DD>System call numbers. Not used until project 2.
440<P>
441
442</P>
443<DT><Q><TT>kernel/list.c</TT></Q>
444<DD><DT><Q><TT>kernel/list.h</TT></Q>
445<DD>Doubly linked list implementation. Used all over the Pintos code, and
446you'll probably want to use it a few places yourself.
447<P>
448
449</P>
450<DT><Q><TT>kernel/bitmap.c</TT></Q>
451<DD><DT><Q><TT>kernel/bitmap.h</TT></Q>
452<DD>Bitmap implementation. You can use this in your code if you like, but
453you probably won't have any need for it in project 0 and project 1.
454<P>
455
456</P>
457<DT><Q><TT>kernel/hash.c</TT></Q>
458<DD><DT><Q><TT>kernel/hash.h</TT></Q>
459<DD>Hash table implementation.
460<P>
461
462</P>
463<DT><Q><TT>kernel/console.c</TT></Q>
464<DD><DT><Q><TT>kernel/console.h</TT></Q>
465<DD><DT><Q><TT>kernel/stdio.h</TT></Q>
466<DD>Implements <CODE>printf()</CODE> and a few other functions.
467</DL>
468<P>
469
470<A NAME="Project 1 Synchronization"></A>
471<HR SIZE="6">
472<A NAME="SEC20"></A>
473<H3> 2.1.2 Synchronization </H3>
474<!--docid::SEC20::-->
475<P>
476
477Proper synchronization is an important part of the solutions to these
478problems. Any synchronization problem can be easily solved by turning
479interrupts off: while interrupts are off, there is no concurrency, so
480there's no possibility for race conditions. Therefore, it's tempting to
481solve all synchronization problems this way, but <STRONG>don't</STRONG>.
482Instead, use semaphores, locks, and condition variables to solve the
483bulk of your synchronization problems. Read the tour section on
484synchronization (see section <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>) or the comments in
485<Q><TT>threads/synch.c</TT></Q> if you're unsure what synchronization primitives
486may be used in what situations.
487</P>
488<P>
489
490In the Pintos projects, the only class of problem best solved by
491disabling interrupts is coordinating data shared between a kernel thread
492and an interrupt handler. Because interrupt handlers can't sleep, they
493can't acquire locks. This means that data shared between kernel threads
494and an interrupt handler must be protected within a kernel thread by
495turning off interrupts.
496</P>
497<P>
498
499This project only requires accessing a little bit of thread state from
500interrupt handlers. For the alarm clock, the timer interrupt needs to
501wake up sleeping threads. In the advanced scheduler, the timer
502interrupt needs to access a few global and per-thread variables. When
503you access these variables from kernel threads, you will need to disable
504interrupts to prevent the timer interrupt from interfering.
505</P>
506<P>
507
508When you do turn off interrupts, take care to do so for the least amount
509of code possible, or you can end up losing important things such as
510timer ticks or input events. Turning off interrupts also increases the
511interrupt handling latency, which can make a machine feel sluggish if
512taken too far.
513</P>
514<P>
515
516The synchronization primitives themselves in <Q><TT>synch.c</TT></Q> are
517implemented by disabling interrupts. You may need to increase the
518amount of code that runs with interrupts disabled here, but you should
519still try to keep it to a minimum.
520</P>
521<P>
522
523Disabling interrupts can be useful for debugging, if you want to make
524sure that a section of code is not interrupted. You should remove
525debugging code before turning in your project. (Don't just comment it
526out, because that can make the code difficult to read.)
527</P>
528<P>
529
530There should be no busy waiting in your submission. A tight loop that
531calls <CODE>thread_yield()</CODE> is one form of busy waiting.
532</P>
533<P>
534
535<A NAME="Development Suggestions"></A>
536<HR SIZE="6">
537<A NAME="SEC21"></A>
538<H3> 2.1.3 Development Suggestions </H3>
539<!--docid::SEC21::-->
540<P>
541
542In the past, many groups divided the assignment into pieces, then each
543group member worked on his or her piece until just before the
544deadline, at which time the group reconvened to combine their code and
545submit. <STRONG>This is a bad idea. We do not recommend this
546approach.</STRONG> Groups that do this often find that two changes conflict
547with each other, requiring lots of last-minute debugging. Some groups
548who have done this have turned in code that did not even compile or
549boot, much less pass any tests.
550</P>
551<P>
552
553Instead, we recommend integrating your team's changes early and often,
554using the source code control system git.
555This is less likely to produce surprises, because everyone can see
556everyone else's code as it is written, instead of just when it is
557finished. These systems also make it possible to review changes and,
558when a change introduces a bug, drop back to working versions of code.
559</P>
560<P>
561
562You should expect to run into bugs that you simply don't understand
563while working on this and subsequent projects. When you do,
564reread the appendix on debugging tools, which is filled with
565useful debugging tips that should help you to get back up to speed
566(see section <A HREF="pintos_8.html#SEC96">D. Debugging Tools</A>). Be sure to read the section on backtraces
567(see section <A HREF="pintos_8.html#SEC100">D.4 Backtraces</A>), which will help you to get the most out of every
568kernel panic or assertion failure.
569</P>
570<P>
571
572<A NAME="Understanding User Programs"></A>
573<HR SIZE="6">
574<A NAME="SEC22"></A>
575<H2> 2.2 Understanding User Programs </H2>
576<!--docid::SEC22::-->
577<P>
578
579The tests for both the alarm clock assignment in Project 0, and the
580priority scheduler in Project 1, run as part of the operating system
581kernel, with full access to privileged parts of the system.
582Once we start running user programs on top of the operating system, this
583is no longer true.
584</P>
585<P>
586
587We allow more than one process to run at a time. Each process has one
588thread (multithreaded processes are not supported). User programs are
589written under the illusion that they have the entire machine. This
590means that when you load and run multiple processes at a time, you must
591manage memory, scheduling, and other state correctly to maintain this
592illusion.
593</P>
594<P>
595
596In Project 2, we will test your operating system by running
597user programs. This gives you much greater freedom. You must make sure
598that the user program interface meets the specifications described here,
599but given that constraint you are free to restructure or rewrite kernel
600code however you wish.
601</P>
602<P>
603
604<A NAME="User Program Source Files"></A>
605<HR SIZE="6">
606<A NAME="SEC23"></A>
607<H3> 2.2.1 Source Files </H3>
608<!--docid::SEC23::-->
609<P>
610
611</P>
612<DL COMPACT>
613<DT><Q><TT>process.c</TT></Q>
614<DD><DT><Q><TT>process.h</TT></Q>
615<DD>Loads ELF binaries and starts processes.
616<P>
617
618</P>
619<DT><Q><TT>pagedir.c</TT></Q>
620<DD><DT><Q><TT>pagedir.h</TT></Q>
621<DD>A simple manager for 80<VAR>x</VAR>86 hardware page tables.
622Although you probably won't want to modify this code for this project,
623you may want to call some of its functions.
624See <A HREF="pintos_4.html#Page Tables">Page Tables</A>, for more information.
625<P>
626
627</P>
628<DT><Q><TT>syscall.c</TT></Q>
629<DD><DT><Q><TT>syscall.h</TT></Q>
630<DD>Whenever a user process wants to access some kernel functionality, it
631invokes a system call.
632<P>
633
634</P>
635<DT><Q><TT>exception.c</TT></Q>
636<DD><DT><Q><TT>exception.h</TT></Q>
637<DD>When a user process performs a privileged or prohibited operation, it
638traps into the kernel as an &quot;exception&quot; or &quot;fault.&quot;<A NAME="DOCF2" HREF="pintos_fot.html#FOOT2">(2)</A> These files handle
639exceptions. In project 2, you will need to modify the page fault
640handler to support lazy page loading and stack growth.
641<P>
642
643</P>
644<DT><Q><TT>gdt.c</TT></Q>
645<DD><DT><Q><TT>gdt.h</TT></Q>
646<DD>The 80<VAR>x</VAR>86 is a segmented architecture. The Global Descriptor
647Table (GDT) is a table that describes the segments in use. These
648files set up the GDT. You should not need to modify these
649files for any of the projects. You can read the code if
650you're interested in how the GDT works.
651<P>
652
653</P>
654<DT><Q><TT>tss.c</TT></Q>
655<DD><DT><Q><TT>tss.h</TT></Q>
656<DD>The Task-State Segment (TSS) is used for 80<VAR>x</VAR>86 architectural
657task switching. Pintos uses the TSS only for switching stacks when a
658user process enters an interrupt handler, as does Linux. You
659should not need to modify these files for any of the projects.
660You can read the code if you're interested in how the TSS
661works.
662</DL>
663<P>
664
665<A NAME="Using the File System"></A>
666<HR SIZE="6">
667<A NAME="SEC24"></A>
668<H3> 2.2.2 Using the File System </H3>
669<!--docid::SEC24::-->
670<P>
671
672You will need to interface to the file system code, because
673user programs are loaded from the file system and most of the
674system calls you must implement deal with the file system.
675You will want to look over the <Q><TT>filesys.h</TT></Q> and <Q><TT>file.h</TT></Q>
676interfaces to understand how to use the file system, and especially
677its many limitations.
678</P>
679<P>
680
681There is no need to modify the file system code in this course, and so
682we recommend that you do not. Working on the file system is likely to
683distract you from the project's foci.
684</P>
685<P>
686
687You will have to tolerate the following limitations, however:
688</P>
689<P>
690
691<UL>
692<LI>
693No internal synchronization. Concurrent accesses will interfere with one
694another. You should use synchronization to ensure that only one process at a
695time is executing file system code.
696<P>
697
698</P>
699<LI>
700File size is fixed at creation time. The root directory is
701represented as a file, so the number of files that may be created is also
702limited.
703<P>
704
705</P>
706<LI>
707File data is allocated as a single extent, that is, data in a single
708file must occupy a contiguous range of sectors on disk. External
709fragmentation can therefore become a serious problem as a file system is
710used over time.
711<P>
712
713</P>
714<LI>
715No subdirectories.
716<P>
717
718</P>
719<LI>
720File names are limited to 14 characters.
721<P>
722
723</P>
724<LI>
725A system crash mid-operation may corrupt the disk in a way
726that cannot be repaired automatically. There is no file system repair
727tool anyway.
728</UL>
729<P>
730
731One important feature is included:
732</P>
733<P>
734
735<UL>
736<LI>
737Unix-like semantics for <CODE>filesys_remove()</CODE> are implemented.
738That is, if a file is open when it is removed, its blocks
739are not deallocated and it may still be accessed by any
740threads that have it open, until the last one closes it. See <A HREF="pintos_2.html#Removing an Open File">Removing an Open File</A>, for more information.
741</UL>
742<P>
743
744You need to be able to create a simulated disk with a file system
745partition. The <CODE>pintos-mkdisk</CODE> program provides this
746functionality. From the <Q><TT>userprog/build</TT></Q> directory, execute
747<CODE>pintos-mkdisk filesys.dsk --filesys-size=2</CODE>. This command
748creates a simulated disk named <Q><TT>filesys.dsk</TT></Q> that contains a 2
749MB Pintos file system partition. Then format the file system
750partition by passing <Q><SAMP>-f -q</SAMP></Q> on the kernel's command line:
751<CODE>pintos -f -q</CODE>. The <Q><SAMP>-f</SAMP></Q> option causes the file system to
752be formatted, and <Q><SAMP>-q</SAMP></Q> causes Pintos to exit as soon as the
753format is done.
754</P>
755<P>
756
757You'll need a way to copy files in and out of the simulated file system.
758The <CODE>pintos</CODE> <Q><SAMP>-p</SAMP></Q> (&quot;put&quot;) and <Q><SAMP>-g</SAMP></Q> (&quot;get&quot;)
759options do this. To copy <Q><TT><VAR>file</VAR></TT></Q> into the
760Pintos file system, use the command <Q><TT>pintos -p <VAR>file</VAR> -- -q</TT></Q>.
761(The <Q><SAMP>--</SAMP></Q> is needed because <Q><SAMP>-p</SAMP></Q> is for the <CODE>pintos</CODE>
762script, not for the simulated kernel.) To copy it to the Pintos file
763system under the name <Q><TT><VAR>newname</VAR></TT></Q>, add <Q><SAMP>-a
764<VAR>newname</VAR></SAMP></Q>: <Q><TT>pintos -p <VAR>file</VAR> -a <VAR>newname</VAR> -- -q</TT></Q>. The
765commands for copying files out of a VM are similar, but substitute
766<Q><SAMP>-g</SAMP></Q> for <Q><SAMP>-p</SAMP></Q>.
767</P>
768<P>
769
770Incidentally, these commands work by passing special commands
771<CODE>extract</CODE> and <CODE>append</CODE> on the kernel's command line and copying
772to and from a special simulated &quot;scratch&quot; partition. If you're very
773curious, you can look at the <CODE>pintos</CODE> script as well as
774<Q><TT>filesys/fsutil.c</TT></Q> to learn the implementation details.
775</P>
776<P>
777
778Here's a summary of how to create a disk with a file system partition,
779format the file system, copy the <CODE>echo</CODE> program into the new
780disk, and then run <CODE>echo</CODE>, passing argument <CODE>x</CODE>.
781(Argument passing won't work until you implemented it.) It assumes
782that you've already built the examples in <Q><TT>examples</TT></Q> and that the
783current directory is <Q><TT>userprog/build</TT></Q>:
784</P>
785<P>
786
787<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos-mkdisk filesys.dsk --filesys-size=2
788pintos -f -q
789pintos -p ../../examples/echo -a echo -- -q
790pintos -q run 'echo x'
791</pre></td></tr></table><P>
792
793The three final steps can actually be combined into a single command:
794</P>
795<P>
796
797<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos-mkdisk filesys.dsk --filesys-size=2
798pintos -p ../../examples/echo -a echo -- -f -q run 'echo x'
799</pre></td></tr></table><P>
800
801If you don't want to keep the file system disk around for later use or
802inspection, you can even combine all four steps into a single command.
803The <CODE>--filesys-size=<VAR>n</VAR></CODE> option creates a temporary file
804system partition
805approximately <VAR>n</VAR> megabytes in size just for the duration of the
806<CODE>pintos</CODE> run. The Pintos automatic test suite makes extensive
807use of this syntax:
808</P>
809<P>
810
811<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos --filesys-size=2 -p ../../examples/echo -a echo -- -f -q run 'echo x'
812</pre></td></tr></table><P>
813
814You can delete a file from the Pintos file system using the <CODE>rm
815<VAR>file</VAR></CODE> kernel action, e.g. <CODE>pintos -q rm <VAR>file</VAR></CODE>. Also,
816<CODE>ls</CODE> lists the files in the file system and <CODE>cat
817<VAR>file</VAR></CODE> prints a file's contents to the display.
818</P>
819<P>
820
821<A NAME="How User Programs Work"></A>
822<HR SIZE="6">
823<A NAME="SEC25"></A>
824<H3> 2.2.3 How User Programs Work </H3>
825<!--docid::SEC25::-->
826<P>
827
828Pintos can run normal C programs, as long as they fit into memory and use
829only the system calls you implement. Notably, <CODE>malloc()</CODE> cannot be
830implemented because none of the system calls required for this project
831allow for memory allocation. Pintos also can't run programs that use
832floating point operations, since the kernel doesn't save and restore the
833processor's floating-point unit when switching threads.
834</P>
835<P>
836
837The <Q><TT>src/examples</TT></Q> directory contains a few sample user
838programs. The <Q><TT>Makefile</TT></Q> in this directory
839compiles the provided examples, and you can edit it
840compile your own programs as well. Some of the example programs will
841not work with the current implementation of Pintos.
842</P>
843<P>
844
845Pintos can load <EM>ELF</EM> executables with the loader provided for you
846in <Q><TT>userprog/process.c</TT></Q>. ELF is a file format used by Linux,
847Solaris, and many other operating systems for object files,
848shared libraries, and executables. You can actually use any compiler
849and linker that output 80<VAR>x</VAR>86 ELF executables to produce programs
850for Pintos. (We've provided compilers and linkers that should do just
851fine.)
852</P>
853<P>
854
855You should realize immediately that, until you copy a
856test program to the simulated file system, Pintos will be unable to do
857useful work. You won't be able to do
858interesting things until you copy a variety of programs to the file system.
859You might want to create a clean reference file system disk and copy that
860over whenever you trash your <Q><TT>filesys.dsk</TT></Q> beyond a useful state,
861which may happen occasionally while debugging.
862</P>
863<P>
864
865<A NAME="Virtual Memory Layout"></A>
866<HR SIZE="6">
867<A NAME="SEC26"></A>
868<H3> 2.2.4 Virtual Memory Layout </H3>
869<!--docid::SEC26::-->
870<P>
871
872Virtual memory in Pintos is divided into two regions: user virtual
873memory and kernel virtual memory. User virtual memory ranges from
874virtual address 0 up to <CODE>PHYS_BASE</CODE>, which is defined in
875<Q><TT>threads/vaddr.h</TT></Q> and defaults to <TT>0xc0000000</TT> (3 GB). Kernel
876virtual memory occupies the rest of the virtual address space, from
877<CODE>PHYS_BASE</CODE> up to 4 GB.
878</P>
879<P>
880
881User virtual memory is per-process.
882When the kernel switches from one process to another, it
883also switches user virtual address spaces by changing the processor's
884page directory base register (see <CODE>pagedir_activate()</CODE> in
885<Q><TT>userprog/pagedir.c</TT></Q>). <CODE>struct thread</CODE> contains a pointer to a
886process's page table.
887</P>
888<P>
889
890Kernel virtual memory is global. It is always mapped the same way,
891regardless of what user process or kernel thread is running. In
892Pintos, kernel virtual memory is mapped one-to-one to physical
893memory, starting at <CODE>PHYS_BASE</CODE>. That is, virtual address
894<CODE>PHYS_BASE</CODE> accesses physical
895address 0, virtual address <CODE>PHYS_BASE</CODE> + <TT>0x1234</TT> accesses
896physical address <TT>0x1234</TT>, and so on up to the size of the machine's
897physical memory.
898</P>
899<P>
900
901A user program can only access its own user virtual memory. An attempt to
902access kernel virtual memory causes a page fault, handled by
903<CODE>page_fault()</CODE> in <Q><TT>userprog/exception.c</TT></Q>, and the process
904will be terminated. Kernel threads can access both kernel virtual
905memory and, if a user process is running, the user virtual memory of
906the running process. However, even in the kernel, an attempt to
907access memory at an unmapped user virtual address
908will cause a page fault.
909</P>
910<P>
911
912<A NAME="Typical Memory Layout"></A>
913<HR SIZE="6">
914<A NAME="SEC27"></A>
915<H4> 2.2.4.1 Typical Memory Layout </H4>
916<!--docid::SEC27::-->
917<P>
918
919Conceptually, each process is
920free to lay out its own user virtual memory however it
921chooses. In practice, user virtual memory is laid out like this:
922</P>
923<P>
924
925<CENTER>
926<TABLE><tr><td>&nbsp;</td><td class=example><pre> PHYS_BASE +----------------------------------+
927 | user stack |
928 | | |
929 | | |
930 | V |
931 | grows downward |
932 | |
933 | |
934 | |
935 | |
936 | grows upward |
937 | ^ |
938 | | |
939 | | |
940 +----------------------------------+
941 | uninitialized data segment (BSS) |
942 +----------------------------------+
943 | initialized data segment |
944 +----------------------------------+
945 | code segment |
946 0x08048000 +----------------------------------+
947 | |
948 | |
949 | |
950 | |
951 | |
952 0 +----------------------------------+
953</pre></td></tr></table></CENTER>
954<P>
955
956In this project, the user stack is fixed in size, but in project 2 it
957will be allowed to grow. Traditionally, the size of the uninitialized
958data segment can be adjusted with a system call, but you will not have
959to implement this.
960</P>
961<P>
962
963The code segment in Pintos starts at user virtual address
964<TT>0x08084000</TT>, approximately 128 MB from the bottom of the address
965space. This value is specified in [ <A HREF="pintos_10.html#SysV-i386">SysV-i386</A>] and has no deep
966significance.
967</P>
968<P>
969
970The linker sets the layout of a user program in memory, as directed by a
971&quot;linker script&quot; that tells it the names and locations of the various
972program segments. You can learn more about linker scripts by reading
973the &quot;Scripts&quot; chapter in the linker manual, accessible via <Q><SAMP>info
974ld</SAMP></Q>.
975</P>
976<P>
977
978To view the layout of a particular executable, run <CODE>objdump</CODE>
979(80<VAR>x</VAR>86) or <CODE>i386-elf-objdump</CODE> (SPARC) with the <Q><SAMP>-p</SAMP></Q>
980option.
981</P>
982<P>
983
984<A NAME="Accessing User Memory"></A>
985<HR SIZE="6">
986<A NAME="SEC28"></A>
987<H3> 2.2.5 Accessing User Memory </H3>
988<!--docid::SEC28::-->
989<P>
990
991As part of a system
992call, the kernel must often access memory through pointers provided by a user
993program. The kernel must be very careful about doing so, because
994the user can pass a null pointer, a pointer to
995unmapped virtual memory, or a pointer to kernel virtual address space
996(above <CODE>PHYS_BASE</CODE>). All of these types of invalid pointers must
997be rejected without harm to the kernel or other running processes, by
998terminating the offending process and freeing its resources.
999</P>
1000<P>
1001
1002There are at least two reasonable ways to do this correctly. The
1003first method is to verify
1004the validity of a user-provided pointer, then dereference it.
1005The second method is to check only that a user
1006pointer points below <CODE>PHYS_BASE</CODE>, then dereference it.
1007An invalid user pointer will cause a &quot;page fault&quot; that you can
1008handle by modifying the code for <CODE>page_fault()</CODE> in
1009<Q><TT>userprog/exception.c</TT></Q>. This technique is normally faster
1010because it takes advantage of the processor's MMU, so it tends to be
1011used in real kernels (including Linux). It is also the way
1012access to user pointers is implemented in the Pintos version provided.
1013</P>
1014<P>
1015
1016In either case, one needs to make sure not to &quot;leak&quot; resources. For
1017example, suppose that your system call has acquired a lock or
1018allocated memory with <CODE>malloc()</CODE>. If you encounter an invalid user pointer
1019afterward, you must still be sure to release the lock or free the page
1020of memory. If you choose to verify user pointers before dereferencing
1021them, this should be straightforward. It's more difficult to handle
1022if an invalid pointer causes a page fault,
1023because there's no way to return an error code from a memory access.
1024</P>
1025<P>
1026
1027<A NAME="Project 0 Requirements"></A>
1028<HR SIZE="6">
1029<A NAME="SEC29"></A>
1030<H2> 2.3 Requirements </H2>
1031<!--docid::SEC29::-->
1032<P>
1033
1034<A NAME="Project 0 Design Document"></A>
1035<HR SIZE="6">
1036<A NAME="SEC30"></A>
1037<H3> 2.3.1 Design Document </H3>
1038<!--docid::SEC30::-->
1039<P>
1040
1041Before you turn in your project, you must copy <A HREF="start.tmpl">the
1042project 0 design document template</A> into your source tree under the name
1043<Q><TT>pintos/src/intro/DESIGNDOC</TT></Q> and fill it in. We recommend that
1044you read the design document template before you start working on the
1045project. See section <A HREF="pintos_7.html#SEC93">C. Project Documentation</A>, for a sample design document
1046that goes along with a fictitious project.
1047</P>
1048<P>
1049
1050<A NAME="Alarm Clock"></A>
1051<HR SIZE="6">
1052<A NAME="SEC31"></A>
1053<H3> 2.3.2 Alarm Clock </H3>
1054<!--docid::SEC31::-->
1055<P>
1056
1057Reimplement <CODE>timer_sleep()</CODE>, defined in <Q><TT>devices/timer.c</TT></Q>.
1058Although a working implementation is provided, it &quot;busy waits,&quot; that
1059is, it spins in a loop checking the current time and calling
1060<CODE>thread_yield()</CODE> until enough time has gone by. Reimplement it to
1061avoid busy waiting.
1062</P>
1063<P>
1064
1065<A NAME="IDX1"></A>
1066</P>
1067<DL>
1068<DT><U>Function:</U> void <B>timer_sleep</B> (int64_t <VAR>ticks</VAR>)
1069<DD>Suspends execution of the calling thread until time has advanced by at
1070least <VAR>x</VAR> timer ticks. Unless the system is otherwise idle, the
1071thread need not wake up after exactly <VAR>x</VAR> ticks. Just put it on
1072the ready queue after they have waited for the right amount of time.
1073<P>
1074
1075<CODE>timer_sleep()</CODE> is useful for threads that operate in real-time,
1076e.g. for blinking the cursor once per second.
1077</P>
1078<P>
1079
1080The argument to <CODE>timer_sleep()</CODE> is expressed in timer ticks, not in
1081milliseconds or any another unit. There are <CODE>TIMER_FREQ</CODE> timer
1082ticks per second, where <CODE>TIMER_FREQ</CODE> is a macro defined in
1083<CODE>devices/timer.h</CODE>. The default value is 100. We don't recommend
1084changing this value, because any change is likely to cause many of
1085the tests to fail.
1086</P>
1087</DL>
1088<P>
1089
1090Separate functions <CODE>timer_msleep()</CODE>, <CODE>timer_usleep()</CODE>, and
1091<CODE>timer_nsleep()</CODE> do exist for sleeping a specific number of
1092milliseconds, microseconds, or nanoseconds, respectively, but these will
1093call <CODE>timer_sleep()</CODE> automatically when necessary. You do not need
1094to modify them.
1095</P>
1096<P>
1097
1098If your delays seem too short or too long, reread the explanation of the
1099<Q><SAMP>-r</SAMP></Q> option to <CODE>pintos</CODE> (see section <A HREF="pintos_1.html#SEC6">1.1.4 Debugging versus Testing</A>).
1100</P>
1101<P>
1102
1103The tests for the <A HREF="pintos_2.html#SEC31">2.3.2 Alarm Clock</A> assignment are executed by changing the
1104working directory <Q><TT>intro</TT></Q>. The run <Q><SAMP>make</SAMP></Q> to build the
1105Pintos kernel. Finally run <Q><SAMP>make check</SAMP></Q> to run the tests,
1106followed by <Q><SAMP>make grade</SAMP></Q> to obtain your score.
1107</P>
1108<P>
1109
1110The alarm clock implementation is not needed for later projects.
1111</P>
1112<P>
1113
1114<A NAME="Argument Passing"></A>
1115<HR SIZE="6">
1116<A NAME="SEC32"></A>
1117<H3> 2.3.3 Argument Passing </H3>
1118<!--docid::SEC32::-->
1119<P>
1120
1121Currently, <CODE>process_execute()</CODE> does not support passing arguments to
1122new processes. Implement this functionality, by extending
1123<CODE>process_execute()</CODE> so that instead of simply taking a program file
1124name as its argument, it divides it into words at spaces. The first
1125word is the program name, the second word is the first argument, and so
1126on. That is, <CODE>process_execute(&quot;grep foo bar&quot;)</CODE> should run
1127<CODE>grep</CODE> passing two arguments <CODE>foo</CODE> and <CODE>bar</CODE>.
1128</P>
1129<P>
1130
1131Within a command line, multiple spaces are equivalent to a single
1132space, so that <CODE>process_execute(&quot;grep foo bar&quot;)</CODE>
1133is equivalent to our original example. You can impose a reasonable
1134limit on the length of the command line arguments. For example, you
1135could limit the arguments to those that will fit in a single page (4
1136kB). (There is an unrelated limit of 128 bytes on command-line
1137arguments that the <CODE>pintos</CODE> utility can pass to the kernel.)
1138</P>
1139<P>
1140
1141You can parse argument strings any way you like. If you're lost,
1142look at <CODE>strtok_r()</CODE>, prototyped in <Q><TT>lib/string.h</TT></Q> and
1143implemented with thorough comments in <Q><TT>lib/string.c</TT></Q>. You can
1144find more about it by looking at the man page (run <CODE>man strtok_r</CODE>
1145at the prompt).
1146</P>
1147<P>
1148
1149See section <A HREF="pintos_2.html#SEC39">2.5.1 Program Startup Details</A>, for information on exactly how you
1150need to set up the stack.
1151</P>
1152<P>
1153
1154<A NAME="Project 0 FAQ"></A>
1155<HR SIZE="6">
1156<A NAME="SEC33"></A>
1157<H2> 2.4 FAQ </H2>
1158<!--docid::SEC33::-->
1159<P>
1160
1161</P>
1162<DL COMPACT>
1163<DT><B>How much code will I need to write?</B>
1164<DD><P>
1165
1166Here's a summary of our reference solution, produced by the
1167<CODE>diffstat</CODE> program. The final row gives total lines inserted
1168and deleted; a changed line counts as both an insertion and a deletion.
1169</P>
1170<P>
1171
1172The reference solution represents just one possible solution. Many
1173other solutions are also possible and many of those differ greatly from
1174the reference solution. Some excellent solutions may not modify all the
1175files modified by the reference solution, and some may modify files not
1176modified by the reference solution.
1177</P>
1178<P>
1179
1180<TABLE><tr><td>&nbsp;</td><td class=example><pre> devices/timer.c | 40 +++++++++++-
1181 threads/thread.h | 3 +
1182 userprog/process.c | 148 ++++++++++++++++++++++++++++++-----------
1183 3 files changed, 150 insertions(+), 41 deletions(-)
1184</pre></td></tr></table></DL>
1185<P>
1186
1187<A NAME="Threads FAQ"></A>
1188<HR SIZE="6">
1189<A NAME="SEC34"></A>
1190<H3> 2.4.1 Threads FAQ </H3>
1191<!--docid::SEC34::-->
1192<P>
1193
1194</P>
1195<DL COMPACT>
1196<DT><B>How do I update the <Q><TT>Makefile</TT></Q>s when I add a new source file?</B>
1197<DD><P>
1198
1199<A NAME="Adding Source Files"></A>
1200To add a <Q><TT>.c</TT></Q> file, edit the top-level <Q><TT>Makefile.build</TT></Q>.
1201Add the new file to variable <Q><SAMP><VAR>dir</VAR>_SRC</SAMP></Q>, where
1202<VAR>dir</VAR> is the directory where you added the file. For this
1203project, that means you should add it to <CODE>threads_SRC</CODE> or
1204<CODE>devices_SRC</CODE>. Then run <CODE>make</CODE>. If your new file
1205doesn't get
1206compiled, run <CODE>make clean</CODE> and then try again.
1207</P>
1208<P>
1209
1210When you modify the top-level <Q><TT>Makefile.build</TT></Q> and re-run
1211<CODE>make</CODE>, the modified
1212version should be automatically copied to
1213<Q><TT>threads/build/Makefile</TT></Q>. The converse is
1214not true, so any changes will be lost the next time you run <CODE>make
1215clean</CODE> from the <Q><TT>threads</TT></Q> directory. Unless your changes are
1216truly temporary, you should prefer to edit <Q><TT>Makefile.build</TT></Q>.
1217</P>
1218<P>
1219
1220A new <Q><TT>.h</TT></Q> file does not require editing the <Q><TT>Makefile</TT></Q>s.
1221</P>
1222<P>
1223
1224</P>
1225<DT><B>What does <CODE>warning: no previous prototype for `<VAR>func</VAR>'</CODE> mean?</B>
1226<DD><P>
1227
1228It means that you defined a non-<CODE>static</CODE> function without
1229preceding it by a prototype. Because non-<CODE>static</CODE> functions are
1230intended for use by other <Q><TT>.c</TT></Q> files, for safety they should be
1231prototyped in a header file included before their definition. To fix
1232the problem, add a prototype in a header file that you include, or, if
1233the function isn't actually used by other <Q><TT>.c</TT></Q> files, make it
1234<CODE>static</CODE>.
1235</P>
1236<P>
1237
1238</P>
1239<DT><B>What is the interval between timer interrupts?</B>
1240<DD><P>
1241
1242Timer interrupts occur <CODE>TIMER_FREQ</CODE> times per second. You can
1243adjust this value by editing <Q><TT>devices/timer.h</TT></Q>. The default is
1244100 Hz.
1245</P>
1246<P>
1247
1248We don't recommend changing this value, because any changes are likely
1249to cause many of the tests to fail.
1250</P>
1251<P>
1252
1253</P>
1254<DT><B>How long is a time slice?</B>
1255<DD><P>
1256
1257There are <CODE>TIME_SLICE</CODE> ticks per time slice. This macro is
1258declared in <Q><TT>threads/thread.c</TT></Q>. The default is 4 ticks.
1259</P>
1260<P>
1261
1262We don't recommend changing this value, because any changes are likely
1263to cause many of the tests to fail.
1264</P>
1265<P>
1266
1267</P>
1268<DT><B>How do I run the tests?</B>
1269<DD><P>
1270
1271See section <A HREF="pintos_1.html#SEC8">1.2.1 Testing</A>.
1272</P>
1273<P>
1274
1275See section <A HREF="pintos_8.html#SEC100">D.4 Backtraces</A>, for more information.
1276</DL>
1277<P>
1278
1279<A NAME="Alarm Clock FAQ"></A>
1280<HR SIZE="6">
1281<A NAME="SEC35"></A>
1282<H3> 2.4.2 Alarm Clock FAQ </H3>
1283<!--docid::SEC35::-->
1284<P>
1285
1286</P>
1287<DL COMPACT>
1288<DT><B>Do I need to account for timer values overflowing?</B>
1289<DD><P>
1290
1291Don't worry about the possibility of timer values overflowing. Timer
1292values are expressed as signed 64-bit numbers, which at 100 ticks per
1293second should be good for almost 2,924,712,087 years. By then, we
1294expect Pintos to have been phased out of the curriculum.
1295</DL>
1296<P>
1297
1298<A NAME="Userprog FAQ"></A>
1299<HR SIZE="6">
1300<A NAME="SEC36"></A>
1301<H3> 2.4.3 Userprog FAQ </H3>
1302<!--docid::SEC36::-->
1303<P>
1304
1305</P>
1306<DL COMPACT>
1307<DT><B>The kernel always panics when I run <CODE>pintos -p <VAR>file</VAR> -- -q</CODE>.</B>
1308<DD><P>
1309
1310Did you format the file system (with <Q><SAMP>pintos -f</SAMP></Q>)?
1311</P>
1312<P>
1313
1314Is your file name too long? The file system limits file names to 14
1315characters. A command like <Q><SAMP>pintos -p ../../examples/echo -- -q</SAMP></Q>
1316will exceed the limit. Use <Q><SAMP>pintos -p ../../examples/echo -a echo
1317-- -q</SAMP></Q> to put the file under the name <Q><TT>echo</TT></Q> instead.
1318</P>
1319<P>
1320
1321Is the file system full?
1322</P>
1323<P>
1324
1325Does the file system already contain 16 files? The base Pintos file
1326system has a 16-file limit.
1327</P>
1328<P>
1329
1330The file system may be so fragmented that there's not enough contiguous
1331space for your file.
1332</P>
1333<P>
1334
1335</P>
1336<DT><B>When I run <CODE>pintos -p ../file --</CODE>, <Q><TT>file</TT></Q> isn't copied.</B>
1337<DD><P>
1338
1339Files are written under the name you refer to them, by default, so in
1340this case the file copied in would be named <Q><TT>../file</TT></Q>. You
1341probably want to run <CODE>pintos -p ../file -a file --</CODE> instead.
1342</P>
1343<P>
1344
1345You can list the files in your file system with <CODE>pintos -q ls</CODE>.
1346</P>
1347<P>
1348
1349</P>
1350<DT><B>All my user programs die with page faults.</B>
1351<DD><P>
1352
1353This will happen if you haven't implemented argument passing
1354(or haven't done so correctly). The basic C library for user programs tries
1355to read <VAR>argc</VAR> and <VAR>argv</VAR> off the stack. If the stack
1356isn't properly set up, this causes a page fault.
1357</P>
1358<P>
1359
1360</P>
1361<DT><B>How can I disassemble user programs?</B>
1362<DD><P>
1363
1364The <CODE>objdump</CODE> (80<VAR>x</VAR>86) or <CODE>i386-elf-objdump</CODE>
1365(SPARC) utility can disassemble entire user
1366programs or object files. Invoke it as <CODE>objdump -d
1367<VAR>file</VAR></CODE>. You can use GDB's
1368<CODE>disassemble</CODE> command to disassemble individual functions
1369(see section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>).
1370</P>
1371<P>
1372
1373</P>
1374<DT><B>Why do many C include files not work in Pintos programs?</B>
1375<DD><DT><B>Can I use lib<VAR>foo</VAR> in my Pintos programs?</B>
1376<DD><P>
1377
1378The C library we provide is very limited. It does not include many of
1379the features that are expected of a real operating system's C library.
1380The C library must be built specifically for the operating system (and
1381architecture), since it must make system calls for I/O and memory
1382allocation. (Not all functions do, of course, but usually the library
1383is compiled as a unit.)
1384</P>
1385<P>
1386
1387The chances are good that the library you want uses parts of the C library
1388that Pintos doesn't implement. It will probably take at least some
1389porting effort to make it work under Pintos. Notably, the Pintos
1390user program C library does not have a <CODE>malloc()</CODE> implementation.
1391</P>
1392<P>
1393
1394</P>
1395<DT><B>How do I compile new user programs?</B>
1396<DD><P>
1397
1398Modify <Q><TT>src/examples/Makefile</TT></Q>, then run <CODE>make</CODE>.
1399</P>
1400<P>
1401
1402</P>
1403<DT><B>Can I run user programs under a debugger?</B>
1404<DD><P>
1405
1406Yes, with some limitations. See section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>.
1407</P>
1408<P>
1409
1410</P>
1411<DT><B>How can I run user programs that need more than 4 kB stack space?</B>
1412<DD><P>
1413
1414You may modify the stack setup code to allocate more than one page of
1415stack space for each process. In project 2, you will implement a better
1416solution.
1417</P>
1418<P>
1419
1420</P>
1421<DT><B>What happens when an open file is removed?</B>
1422<DD><A NAME="Removing an Open File"></A>
1423<P>
1424
1425You should implement the standard Unix semantics for files. That is, when
1426a file is removed any process which has a file descriptor for that file
1427may continue to use that descriptor. This means that
1428they can read and write from the file. The file will not have a name,
1429and no other processes will be able to open it, but it will continue
1430to exist until all file descriptors referring to the file are closed
1431or the machine shuts down.
1432</P>
1433<P>
1434
1435</DL>
1436<P>
1437
1438<A NAME="Argument Passing FAQ"></A>
1439<HR SIZE="6">
1440<A NAME="SEC37"></A>
1441<H3> 2.4.4 Argument Passing FAQ </H3>
1442<!--docid::SEC37::-->
1443<P>
1444
1445</P>
1446<DL COMPACT>
1447<DT><B>Isn't the top of stack in kernel virtual memory?</B>
1448<DD><P>
1449
1450The top of stack is at <CODE>PHYS_BASE</CODE>, typically <TT>0xc0000000</TT>, which
1451is also where kernel virtual memory starts.
1452But before the processor pushes data on the stack, it decrements the stack
1453pointer. Thus, the first (4-byte) value pushed on the stack
1454will be at address <TT>0xbffffffc</TT>.
1455</P>
1456<P>
1457
1458</P>
1459<DT><B>Is <CODE>PHYS_BASE</CODE> fixed?</B>
1460<DD><P>
1461
1462No. You should be able to support <CODE>PHYS_BASE</CODE> values that are
1463any multiple of <TT>0x10000000</TT> from <TT>0x80000000</TT> to <TT>0xf0000000</TT>,
1464simply via recompilation.
1465</DL>
1466<P>
1467
1468<A NAME="80x86 Calling Convention"></A>
1469<HR SIZE="6">
1470<A NAME="SEC38"></A>
1471<H2> 2.5 80<VAR>x</VAR>86 Calling Convention </H2>
1472<!--docid::SEC38::-->
1473<P>
1474
1475This section summarizes important points of the convention used for
1476normal function calls on 32-bit 80<VAR>x</VAR>86 implementations of Unix.
1477Some details are omitted for brevity. If you do want all the details,
1478refer to [ <A HREF="pintos_10.html#SysV-i386">SysV-i386</A>].
1479</P>
1480<P>
1481
1482The calling convention works like this:
1483</P>
1484<P>
1485
1486<OL>
1487<LI>
1488The caller pushes each of the function's arguments on the stack one by
1489one, normally using the <CODE>PUSH</CODE> assembly language instruction.
1490Arguments are pushed in right-to-left order.
1491<P>
1492
1493The stack grows downward: each push decrements the stack pointer, then
1494stores into the location it now points to, like the C expression
1495<Q><SAMP>*--sp = <VAR>value</VAR></SAMP></Q>.
1496</P>
1497<P>
1498
1499</P>
1500<LI>
1501The caller pushes the address of its next instruction (the <EM>return
1502address</EM>) on the stack and jumps to the first instruction of the callee.
1503A single 80<VAR>x</VAR>86 instruction, <CODE>CALL</CODE>, does both.
1504<P>
1505
1506</P>
1507<LI>
1508The callee executes. When it takes control, the stack pointer points to
1509the return address, the first argument is just above it, the second
1510argument is just above the first argument, and so on.
1511<P>
1512
1513</P>
1514<LI>
1515If the callee has a return value, it stores it into register <CODE>EAX</CODE>.
1516<P>
1517
1518</P>
1519<LI>
1520The callee returns by popping the return address from the stack and
1521jumping to the location it specifies, using the 80<VAR>x</VAR>86 <CODE>RET</CODE>
1522instruction.
1523<P>
1524
1525</P>
1526<LI>
1527The caller pops the arguments off the stack.
1528</OL>
1529<P>
1530
1531Consider a function <CODE>f()</CODE> that takes three <CODE>int</CODE> arguments.
1532This diagram shows a sample stack frame as seen by the callee at the
1533beginning of step 3 above, supposing that <CODE>f()</CODE> is invoked as
1534<CODE>f(1, 2, 3)</CODE>. The initial stack address is arbitrary:
1535</P>
1536<P>
1537
1538<CENTER>
1539<TABLE><tr><td>&nbsp;</td><td class=example><pre> +----------------+
1540 0xbffffe7c | 3 |
1541 0xbffffe78 | 2 |
1542 0xbffffe74 | 1 |
1543stack pointer --&gt; 0xbffffe70 | return address |
1544 +----------------+
1545</pre></td></tr></table></CENTER>
1546<P>
1547
1548<A NAME="Program Startup Details"></A>
1549<HR SIZE="6">
1550<A NAME="SEC39"></A>
1551<H3> 2.5.1 Program Startup Details </H3>
1552<!--docid::SEC39::-->
1553<P>
1554
1555The Pintos C library for user programs designates <CODE>_start()</CODE>, in
1556<Q><TT>lib/user/entry.c</TT></Q>, as the entry point for user programs. This
1557function is a wrapper around <CODE>main()</CODE> that calls <CODE>exit()</CODE> if
1558<CODE>main()</CODE> returns:
1559</P>
1560<P>
1561
1562<TABLE><tr><td>&nbsp;</td><td class=example><pre>void
1563_start (int argc, char *argv[])
1564{
1565 exit (main (argc, argv));
1566}
1567</pre></td></tr></table><P>
1568
1569The kernel must put the arguments for the initial function on the stack
1570before it allows the user program to begin executing. The arguments are
1571passed in the same way as the normal calling convention (see section <A HREF="pintos_2.html#SEC38">2.5 80<VAR>x</VAR>86 Calling Convention</A>).
1572</P>
1573<P>
1574
1575Consider how to handle arguments for the following example command:
1576<Q><SAMP>/bin/ls -l foo bar</SAMP></Q>.
1577First, break the command into words: <Q><SAMP>/bin/ls</SAMP></Q>,
1578<Q><SAMP>-l</SAMP></Q>, <Q><SAMP>foo</SAMP></Q>, <Q><SAMP>bar</SAMP></Q>. Place the words at the top of the
1579stack. Order doesn't matter, because they will be referenced through
1580pointers.
1581</P>
1582<P>
1583
1584Then, push the address of each string plus a null pointer sentinel, on
1585the stack, in right-to-left order. These are the elements of
1586<CODE>argv</CODE>. The null pointer sentinel ensures that <CODE>argv[argc]</CODE>
1587is a null pointer, as required by the C standard. The order ensures
1588that <CODE>argv[0]</CODE> is at the lowest virtual address. Word-aligned
1589accesses are faster than unaligned accesses, so for best performance
1590round the stack pointer down to a multiple of 4 before the first push.
1591</P>
1592<P>
1593
1594Then, push <CODE>argv</CODE> (the address of <CODE>argv[0]</CODE>) and <CODE>argc</CODE>,
1595in that order. Finally, push a fake &quot;return address&quot;: although the
1596entry function will never return, its stack frame must have the same
1597structure as any other.
1598</P>
1599<P>
1600
1601The table below shows the state of the stack and the relevant registers
1602right before the beginning of the user program, assuming
1603<CODE>PHYS_BASE</CODE> is <TT>0xc0000000</TT>:
1604</P>
1605<P>
1606
1607<CENTER>
1608</P>
1609<TABLE>
1610<TR><TD>Address </TD><TD> Name </TD><TD> Data </TD><TD> Type</TD>
1611</TR>
1612<TR><TD><TT>0xbffffffc</TT> </TD><TD> <CODE>argv[3][<small>...</small>]</CODE> </TD><TD> <Q><SAMP>bar\0</SAMP></Q> </TD><TD> <CODE>char[4]</CODE></TD>
1613</TR>
1614<TR><TD><TT>0xbffffff8</TT> </TD><TD> <CODE>argv[2][<small>...</small>]</CODE> </TD><TD> <Q><SAMP>foo\0</SAMP></Q> </TD><TD> <CODE>char[4]</CODE></TD>
1615</TR>
1616<TR><TD><TT>0xbffffff5</TT> </TD><TD> <CODE>argv[1][<small>...</small>]</CODE> </TD><TD> <Q><SAMP>-l\0</SAMP></Q> </TD><TD> <CODE>char[3]</CODE></TD>
1617</TR>
1618<TR><TD><TT>0xbfffffed</TT> </TD><TD> <CODE>argv[0][<small>...</small>]</CODE> </TD><TD> <Q><SAMP>/bin/ls\0</SAMP></Q> </TD><TD> <CODE>char[8]</CODE></TD>
1619</TR>
1620<TR><TD><TT>0xbfffffec</TT> </TD><TD> word-align </TD><TD> 0 </TD><TD> <CODE>uint8_t</CODE></TD>
1621</TR>
1622<TR><TD><TT>0xbfffffe8</TT> </TD><TD> <CODE>argv[4]</CODE> </TD><TD> <TT>0</TT> </TD><TD> <CODE>char *</CODE></TD>
1623</TR>
1624<TR><TD><TT>0xbfffffe4</TT> </TD><TD> <CODE>argv[3]</CODE> </TD><TD> <TT>0xbffffffc</TT> </TD><TD> <CODE>char *</CODE></TD>
1625</TR>
1626<TR><TD><TT>0xbfffffe0</TT> </TD><TD> <CODE>argv[2]</CODE> </TD><TD> <TT>0xbffffff8</TT> </TD><TD> <CODE>char *</CODE></TD>
1627</TR>
1628<TR><TD><TT>0xbfffffdc</TT> </TD><TD> <CODE>argv[1]</CODE> </TD><TD> <TT>0xbffffff5</TT> </TD><TD> <CODE>char *</CODE></TD>
1629</TR>
1630<TR><TD><TT>0xbfffffd8</TT> </TD><TD> <CODE>argv[0]</CODE> </TD><TD> <TT>0xbfffffed</TT> </TD><TD> <CODE>char *</CODE></TD>
1631</TR>
1632<TR><TD><TT>0xbfffffd4</TT> </TD><TD> <CODE>argv</CODE> </TD><TD> <TT>0xbfffffd8</TT> </TD><TD> <CODE>char **</CODE></TD>
1633</TR>
1634<TR><TD><TT>0xbfffffd0</TT> </TD><TD> <CODE>argc</CODE> </TD><TD> 4 </TD><TD> <CODE>int</CODE></TD>
1635</TR>
1636<TR><TD><TT>0xbfffffcc</TT> </TD><TD> return address </TD><TD> 0 </TD><TD> <CODE>void (*) ()</CODE></TD>
1637</TR></TABLE>
1638</CENTER>
1639<P>
1640
1641In this example, the stack pointer would be initialized to
1642<TT>0xbfffffcc</TT>.
1643</P>
1644<P>
1645
1646As shown above, your code should start the stack at the very top of
1647the user virtual address space, in the page just below virtual address
1648<CODE>PHYS_BASE</CODE> (defined in <Q><TT>threads/vaddr.h</TT></Q>).
1649</P>
1650<P>
1651
1652You may find the non-standard <CODE>hex_dump()</CODE> function, declared in
1653<Q><TT>&lt;stdio.h&gt;</TT></Q>, useful for debugging your argument passing code.
1654Here's what it would show in the above example:
1655</P>
1656<P>
1657
1658<TABLE><tr><td>&nbsp;</td><td class=example><pre>bfffffc0 00 00 00 00 | ....|
1659bfffffd0 04 00 00 00 d8 ff ff bf-ed ff ff bf f5 ff ff bf |................|
1660bfffffe0 f8 ff ff bf fc ff ff bf-00 00 00 00 00 2f 62 69 |............./bi|
1661bffffff0 6e 2f 6c 73 00 2d 6c 00-66 6f 6f 00 62 61 72 00 |n/ls.-l.foo.bar.|
1662</pre></td></tr></table><P>
1663
1664<A NAME="System Call Details"></A>
1665<HR SIZE="6">
1666<A NAME="SEC40"></A>
1667<H3> 2.5.2 System Call Details </H3>
1668<!--docid::SEC40::-->
1669<P>
1670
1671We already know one way that the operating system
1672can regain control from a user program: interrupts from timers and I/O
1673devices. These are &quot;external&quot; interrupts, because they are caused
1674by entities outside the CPU (see section <A HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>).
1675</P>
1676<P>
1677
1678The operating system also deals with software exceptions, which are
1679events that occur in program code (see section <A HREF="pintos_5.html#SEC67">A.4.2 Internal Interrupt Handling</A>). These can be errors such as a page fault or division by
1680zero. Exceptions are also the means by which a user program
1681can request services (&quot;system calls&quot;) from the operating system.
1682</P>
1683<P>
1684
1685In the 80<VAR>x</VAR>86 architecture, the <Q><SAMP>int</SAMP></Q> instruction is the
1686most commonly used means for invoking system calls. This instruction
1687is handled in the same way as other software exceptions. In Pintos,
1688user programs invoke <Q><SAMP>int $0x30</SAMP></Q> to make a system call. The
1689system call number and any additional arguments are expected to be
1690pushed on the stack in the normal fashion before invoking the
1691interrupt (see section <A HREF="pintos_2.html#SEC38">2.5 80<VAR>x</VAR>86 Calling Convention</A>).
1692</P>
1693<P>
1694
1695Thus, when the system call handler <CODE>syscall_handler()</CODE> gets control,
1696the system call number is in the 32-bit word at the caller's stack
1697pointer, the first argument is in the 32-bit word at the next higher
1698address, and so on. The caller's stack pointer is accessible to
1699<CODE>syscall_handler()</CODE> as the <Q><SAMP>esp</SAMP></Q> member of the
1700<CODE>struct intr_frame</CODE> passed to it. (<CODE>struct intr_frame</CODE> is on the kernel
1701stack.)
1702</P>
1703<P>
1704
1705The 80<VAR>x</VAR>86 convention for function return values is to place them
1706in the <CODE>EAX</CODE> register. System calls that return a value can do
1707so by modifying the <Q><SAMP>eax</SAMP></Q> member of <CODE>struct intr_frame</CODE>.
1708</P>
1709<P>
1710
1711You should try to avoid writing large amounts of repetitive code for
1712implementing system calls. Each system call argument, whether an
1713integer or a pointer, takes up 4 bytes on the stack. You should be able
1714to take advantage of this to avoid writing much near-identical code for
1715retrieving each system call's arguments from the stack.
1716<A NAME="Project 1--Threads"></A>
1717<HR SIZE="6">
1718<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1719<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_2.html#SEC15"> &lt;&lt; </A>]</TD>
1720<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_3.html#SEC41"> &gt;&gt; </A>]</TD>
1721<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
1722<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
1723<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1724<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
1725</TR></TABLE>
1726<BR>
1727<FONT SIZE="-1">
1728This document was generated
1729by on <I>March, 6 2012</I>
1730using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
1731</FONT>
1732
1733</BODY>
1734</HTML>
diff --git a/doc/pintos_3.html b/doc/pintos_3.html
new file mode 100644
index 0000000..c90148d
--- /dev/null
+++ b/doc/pintos_3.html
@@ -0,0 +1,375 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Project 1--Threads</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Project 1--Threads">
18<META NAME="keywords" CONTENT="Pintos Projects: Project 1--Threads">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC41"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_2.html#SEC15"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_4.html#SEC47"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> 3. Project 1: Threads </H1>
39<!--docid::SEC41::-->
40<P>
41
42In this assignment, we give you a minimally functional thread system.
43Your job is to extend the functionality of this system to gain a
44better understanding of synchronization problems.
45</P>
46<P>
47
48You will be working primarily in the <Q><TT>threads</TT></Q> directory for
49this assignment, with some work in the <Q><TT>devices</TT></Q> directory on the
50side. Compilation should be done in the <Q><TT>threads</TT></Q> directory.
51</P>
52<P>
53
54Before you read the description of this project, you should read all of
55the following sections: <A HREF="pintos_1.html#SEC1">1. Introduction</A>, <A HREF="pintos_6.html#SEC89">B. Coding Standards</A>,
56<A HREF="pintos_8.html#SEC96">D. Debugging Tools</A>, and <A HREF="pintos_9.html#SEC109">E. Development Tools</A>. You should at least
57skim the material from <A HREF="pintos_5.html#SEC49">A.1 Loading</A> through <A HREF="pintos_5.html#SEC69">A.5 Memory Allocation</A>, especially <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>.
58</P>
59<P>
60
61<A NAME="Project 1 Background"></A>
62<HR SIZE="6">
63<A NAME="SEC42"></A>
64<H2> 3.1 Background </H2>
65<!--docid::SEC42::-->
66<P>
67
68Before you start with project 1, be sure to refresh your knowledge
69on the thread subsystem introduced in the last project
70(<A HREF="pintos_2.html#SEC16">2.1 Understanding Threads</A>).
71</P>
72<P>
73
74<A NAME="Project 1 Requirements"></A>
75<HR SIZE="6">
76<A NAME="SEC43"></A>
77<H2> 3.2 Requirements </H2>
78<!--docid::SEC43::-->
79<P>
80
81<A NAME="Project 1 Design Document"></A>
82<HR SIZE="6">
83<A NAME="SEC44"></A>
84<H3> 3.2.1 Design Document </H3>
85<!--docid::SEC44::-->
86<P>
87
88Before you turn in your project, you must copy <A HREF="threads.tmpl">the
89project 1 design document template</A> into your source tree under the name
90<Q><TT>pintos/src/threads/DESIGNDOC</TT></Q> and fill it in. We recommend that
91you read the design document template before you start working on the
92project.
93</P>
94<P>
95
96<A NAME="Priority Scheduling"></A>
97<HR SIZE="6">
98<A NAME="SEC45"></A>
99<H3> 3.2.2 Priority Scheduling </H3>
100<!--docid::SEC45::-->
101<P>
102
103Implement priority scheduling in Pintos.
104When a thread is added to the ready list that has a higher priority
105than the currently running thread, the current thread should
106immediately yield the processor to the new thread. Similarly, when
107threads are waiting for a lock, semaphore, or condition variable, the
108highest priority waiting thread should be awakened first. A thread
109may raise or lower its own priority at any time, but lowering its
110priority such that it no longer has the highest priority must cause it
111to immediately yield the CPU.
112</P>
113<P>
114
115Thread priorities range from <CODE>PRI_MIN</CODE> (0) to <CODE>PRI_MAX</CODE> (63).
116Lower numbers correspond to lower priorities, so that priority 0
117is the lowest priority and priority 63 is the highest.
118The initial thread priority is passed as an argument to
119<CODE>thread_create()</CODE>. If there's no reason to choose another
120priority, use <CODE>PRI_DEFAULT</CODE> (31). The <CODE>PRI_</CODE> macros are
121defined in <Q><TT>threads/thread.h</TT></Q>, and you should not change their
122values.
123</P>
124<P>
125
126One issue with priority scheduling is &quot;priority inversion&quot;. Consider
127high, medium, and low priority threads <VAR>H</VAR>, <VAR>M</VAR>, and <VAR>L</VAR>,
128respectively. If <VAR>H</VAR> needs to wait for <VAR>L</VAR> (for instance, for a
129lock held by <VAR>L</VAR>), and <VAR>M</VAR> is on the ready list, then <VAR>H</VAR>
130will never get the CPU because the low priority thread will not get any
131CPU time. A partial fix for this problem is for <VAR>H</VAR> to &quot;donate&quot;
132its priority to <VAR>L</VAR> while <VAR>L</VAR> is holding the lock, then recall
133the donation once <VAR>L</VAR> releases (and thus <VAR>H</VAR> acquires) the lock.
134</P>
135<P>
136
137Implement priority donation. You will need to account for all different
138situations in which priority donation is required. Be sure to handle
139multiple donations, in which multiple priorities are donated to a single
140thread. You must also handle nested donation: if <VAR>H</VAR> is waiting on
141a lock that <VAR>M</VAR> holds and <VAR>M</VAR> is waiting on a lock that <VAR>L</VAR>
142holds, then both <VAR>M</VAR> and <VAR>L</VAR> should be boosted to <VAR>H</VAR>'s
143priority. If necessary, you may impose a reasonable limit on depth of
144nested priority donation, such as 8 levels.
145</P>
146<P>
147
148You must implement priority donation for locks. You need not
149implement priority donation for the other Pintos synchronization
150constructs. You do need to implement priority scheduling in all
151cases.
152</P>
153<P>
154
155Finally, implement the following functions that allow a thread to
156examine and modify its own priority. Skeletons for these functions are
157provided in <Q><TT>threads/thread.c</TT></Q>.
158</P>
159<P>
160
161<A NAME="IDX2"></A>
162</P>
163<DL>
164<DT><U>Function:</U> void <B>thread_set_priority</B> (int <VAR>new_priority</VAR>)
165<DD>Sets the current thread's priority to <VAR>new_priority</VAR>. If the
166current thread no longer has the highest priority, yields.
167</DL>
168<P>
169
170<A NAME="IDX3"></A>
171</P>
172<DL>
173<DT><U>Function:</U> int <B>thread_get_priority</B> (void)
174<DD>Returns the current thread's priority. In the presence of priority
175donation, returns the higher (donated) priority.
176</DL>
177<P>
178
179You need not provide any interface to allow a thread to directly modify
180other threads' priorities.
181</P>
182<P>
183
184The priority scheduler is not a necessary for project 2.
185</P>
186<P>
187
188<A NAME="Project 1 FAQ"></A>
189<HR SIZE="6">
190<A NAME="SEC46"></A>
191<H2> 3.3 FAQ </H2>
192<!--docid::SEC46::-->
193<P>
194
195</P>
196<DL COMPACT>
197<DT><B>How much code will I need to write?</B>
198<DD><P>
199
200Here's a summary of our reference solution, produced by the
201<CODE>diffstat</CODE> program. The final row gives total lines inserted
202and deleted; a changed line counts as both an insertion and a deletion.
203</P>
204<P>
205
206The reference solution represents just one possible solution. Many
207other solutions are also possible and many of those differ greatly from
208the reference solution. Some excellent solutions may not modify all the
209files modified by the reference solution, and some may modify files not
210modified by the reference solution.
211</P>
212<P>
213
214<TABLE><tr><td>&nbsp;</td><td class=example><pre> threads/interrupt.c | 3 +-
215 threads/synch.c | 55 ++++++++++++++++++--
216 threads/synch.h | 2 +
217 threads/thread.c | 111 +++++++++++++++++++++++++++++++++++-----
218 threads/thread.h | 10 +++-
219 5 files changed, 160 insertions(+), 21 deletions(-)
220</pre></td></tr></table><P>
221
222</P>
223<DT><B>Doesn't priority scheduling lead to starvation?</B>
224<DD><P>
225
226Yes, strict priority scheduling can lead to starvation
227because a thread will not run if any higher-priority thread is runnable.
228The advanced scheduler introduces a mechanism for dynamically
229changing thread priorities.
230</P>
231<P>
232
233Strict priority scheduling is valuable in real-time systems because it
234offers the programmer more control over which jobs get processing
235time. High priorities are generally reserved for time-critical
236tasks. It's not &quot;fair,&quot; but it addresses other concerns not
237applicable to a general-purpose operating system.
238</P>
239<P>
240
241</P>
242<DT><B>What thread should run after a lock has been released?</B>
243<DD><P>
244
245When a lock is released, the highest priority thread waiting for that
246lock should be unblocked and put on the list of ready threads. The
247scheduler should then run the highest priority thread on the ready
248list.
249</P>
250<P>
251
252</P>
253<DT><B>If the highest-priority thread yields, does it continue running?</B>
254<DD><P>
255
256Yes. If there is a single highest-priority thread, it continues
257running until it blocks or finishes, even if it calls
258<CODE>thread_yield()</CODE>.
259If multiple threads have the same highest priority,
260<CODE>thread_yield()</CODE> should switch among them in &quot;round robin&quot; order.
261</P>
262<P>
263
264</P>
265<DT><B>What happens to the priority of a donating thread?</B>
266<DD><P>
267
268Priority donation only changes the priority of the donee
269thread. The donor thread's priority is unchanged.
270Priority donation is not additive: if thread <VAR>A</VAR> (with priority 5) donates
271to thread <VAR>B</VAR> (with priority 3), then <VAR>B</VAR>'s new priority is 5, not 8.
272</P>
273<P>
274
275</P>
276<DT><B>Can a thread's priority change while it is on the ready queue?</B>
277<DD><P>
278
279Yes. Consider a ready, low-priority thread <VAR>L</VAR> that holds a lock.
280High-priority thread <VAR>H</VAR> attempts to acquire the lock and blocks,
281thereby donating its priority to ready thread <VAR>L</VAR>.
282</P>
283<P>
284
285</P>
286<DT><B>Can a thread's priority change while it is blocked?</B>
287<DD><P>
288
289Yes. While a thread that has acquired lock <VAR>L</VAR> is blocked for any
290reason, its priority can increase by priority donation if a
291higher-priority thread attempts to acquire <VAR>L</VAR>. This case is
292checked by the <CODE>priority-donate-sema</CODE> test.
293</P>
294<P>
295
296</P>
297<DT><B>Can a thread added to the ready list preempt the processor?</B>
298<DD><P>
299
300Yes. If a thread added to the ready list has higher priority than the
301running thread, the correct behavior is to immediately yield the
302processor. It is not acceptable to wait for the next timer interrupt.
303The highest priority thread should run as soon as it is runnable,
304preempting whatever thread is currently running.
305</P>
306<P>
307
308</P>
309<DT><B>How does <CODE>thread_set_priority()</CODE> affect a thread receiving donations?</B>
310<DD><P>
311
312It sets the thread's base priority. The thread's effective priority
313becomes the higher of the newly set priority or the highest donated
314priority. When the donations are released, the thread's priority
315becomes the one set through the function call. This behavior is checked
316by the <CODE>priority-donate-lower</CODE> test.
317</P>
318<P>
319
320</P>
321<DT><B>Doubled test names in output make them fail.</B>
322<DD><P>
323
324Suppose you are seeing output in which some test names are doubled,
325like this:
326</P>
327<P>
328
329<TABLE><tr><td>&nbsp;</td><td class=example><pre>(alarm-priority) begin
330(alarm-priority) (alarm-priority) Thread priority 30 woke up.
331Thread priority 29 woke up.
332(alarm-priority) Thread priority 28 woke up.
333</pre></td></tr></table><P>
334
335What is happening is that output from two threads is being
336interleaved. That is, one thread is printing <CODE>&quot;(alarm-priority)
337Thread priority 29 woke up.\n&quot;</CODE> and another thread is printing
338<CODE>&quot;(alarm-priority) Thread priority 30 woke up.\n&quot;</CODE>, but the first
339thread is being preempted by the second in the middle of its output.
340</P>
341<P>
342
343This problem indicates a bug in your priority scheduler. After all, a
344thread with priority 29 should not be able to run while a thread with
345priority 30 has work to do.
346</P>
347<P>
348
349Normally, the implementation of the <CODE>printf()</CODE> function in the
350Pintos kernel attempts to prevent such interleaved output by acquiring
351a console lock during the duration of the <CODE>printf</CODE> call and
352releasing it afterwards. However, the output of the test name,
353e.g., <CODE>(alarm-priority)</CODE>, and the message following it is output
354using two calls to <CODE>printf</CODE>, resulting in the console lock being
355acquired and released twice.
356</DL>
357<A NAME="Project 2--Virtual Memory"></A>
358<HR SIZE="6">
359<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
360<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_3.html#SEC41"> &lt;&lt; </A>]</TD>
361<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_4.html#SEC47"> &gt;&gt; </A>]</TD>
362<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
363<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
364<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
365<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
366</TR></TABLE>
367<BR>
368<FONT SIZE="-1">
369This document was generated
370by on <I>March, 6 2012</I>
371using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
372</FONT>
373
374</BODY>
375</HTML>
diff --git a/doc/pintos_4.html b/doc/pintos_4.html
new file mode 100644
index 0000000..70be2de
--- /dev/null
+++ b/doc/pintos_4.html
@@ -0,0 +1,83 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Project 2--Virtual Memory</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Project 2--Virtual Memory">
18<META NAME="keywords" CONTENT="Pintos Projects: Project 2--Virtual Memory">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC47"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_3.html#SEC41"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_5.html#SEC48"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> 4. Project 2: Virtual Memory </H1>
39<!--docid::SEC47::-->
40<P>
41
42By now you should have some familiarity with the inner workings of
43Pintos. Pintos can properly handle multiple threads of execution with proper
44synchronization, and can load multiple user programs at once. In this assignment,
45you will improve the memory management of Pintos.
46</P>
47<P>
48
49This assignment requires user programs (and in particular argument passing,
50which you implemented in project 0) to work. You will continue to handle
51Pintos disks and file systems the same way you did before
52(see section <A HREF="pintos_2.html#SEC24">2.2.2 Using the File System</A>).
53</P>
54<P>
55
56The documentation for this assignment will be released when Project 2
57is about to start.
58</P>
59<P>
60
61<A NAME="Managing the Supplemental Page Table"></A>
62<A NAME="Accessed and Dirty Bits"></A>
63<A NAME="Page Tables"></A>
64<A NAME="Why PAL_USER?"></A>
65<A NAME="Reference Guide"></A>
66<HR SIZE="6">
67<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
68<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_3.html#SEC41"> &lt;&lt; </A>]</TD>
69<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_5.html#SEC48"> &gt;&gt; </A>]</TD>
70<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
71<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
72<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
73<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
74</TR></TABLE>
75<BR>
76<FONT SIZE="-1">
77This document was generated
78by on <I>March, 6 2012</I>
79using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
80</FONT>
81
82</BODY>
83</HTML>
diff --git a/doc/pintos_5.html b/doc/pintos_5.html
new file mode 100644
index 0000000..670f351
--- /dev/null
+++ b/doc/pintos_5.html
@@ -0,0 +1,3343 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Reference Guide</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Reference Guide">
18<META NAME="keywords" CONTENT="Pintos Projects: Reference Guide">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC48"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_4.html#SEC47"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_6.html#SEC89"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> A. Reference Guide </H1>
39<!--docid::SEC48::-->
40<P>
41
42This chapter is a reference for the Pintos code. The reference guide
43does not cover all of the code in Pintos, but it does cover those
44pieces that students most often find troublesome. You may find that
45you want to read each part of the reference guide as you work on the
46project where it becomes important.
47</P>
48<P>
49
50We recommend using &quot;tags&quot; to follow along with references to function
51and variable names (see section <A HREF="pintos_9.html#SEC110">E.1 Tags</A>).
52</P>
53<P>
54
55<A NAME="Pintos Loading"></A>
56<HR SIZE="6">
57<A NAME="SEC49"></A>
58<H2> A.1 Loading </H2>
59<!--docid::SEC49::-->
60<P>
61
62This section covers the Pintos loader and basic kernel
63initialization.
64</P>
65<P>
66
67<A NAME="Pintos Loader"></A>
68<HR SIZE="6">
69<A NAME="SEC50"></A>
70<H3> A.1.1 The Loader </H3>
71<!--docid::SEC50::-->
72<P>
73
74The first part of Pintos that runs is the loader, in
75<Q><TT>threads/loader.S</TT></Q>. The PC BIOS loads the loader into memory.
76The loader, in turn, is responsible for finding the kernel on disk,
77loading it into memory, and then jumping to its start. It's
78not important to understand exactly how the loader works, but if
79you're interested, read on. You should probably read along with the
80loader's source. You should also understand the basics of the
8180<VAR>x</VAR>86 architecture as described by chapter 3, &quot;Basic Execution
82Environment,&quot; of [ <A HREF="pintos_10.html#IA32-v1">IA32-v1</A>].
83</P>
84<P>
85
86The PC BIOS loads the loader from the first sector of the first hard
87disk, called the <EM>master boot record</EM> (MBR). PC conventions
88reserve 64 bytes of the MBR for the partition table, and Pintos uses
89about 128 additional bytes for kernel command-line arguments. This
90leaves a little over 300 bytes for the loader's own code. This is a
91severe restriction that means, practically speaking, the loader must
92be written in assembly language.
93</P>
94<P>
95
96The Pintos loader and kernel don't have to be on the same disk, nor
97does is the kernel required to be in any particular location on a
98given disk. The loader's first job, then, is to find the kernel by
99reading the partition table on each hard disk, looking for a bootable
100partition of the type used for a Pintos kernel.
101</P>
102<P>
103
104When the loader finds a bootable kernel partition, it reads the
105partition's contents into memory at physical address 128 kB. The
106kernel is at the beginning of the partition, which might be larger
107than necessary due to partition boundary alignment conventions, so the
108loader reads no more than 512 kB (and the Pintos build process
109will refuse to produce kernels larger than that). Reading more data
110than this would cross into the region from 640 kB to 1 MB that
111the PC architecture reserves for hardware and the BIOS, and a standard
112PC BIOS does not provide any means to load the kernel above 1 MB.
113</P>
114<P>
115
116The loader's final job is to extract the entry point from the loaded
117kernel image and transfer control to it. The entry point is not at a
118predictable location, but the kernel's ELF header contains a pointer
119to it. The loader extracts the pointer and jumps to the location it
120points to.
121</P>
122<P>
123
124The Pintos kernel command line
125is stored in the boot loader. The <CODE>pintos</CODE> program actually
126modifies a copy of the boot loader on disk each time it runs the kernel,
127inserting whatever command-line arguments the user supplies to the kernel,
128and then the kernel at boot time reads those arguments out of the boot
129loader in memory. This is not an elegant solution, but it is simple
130and effective.
131</P>
132<P>
133
134<A NAME="Low-Level Kernel Initialization"></A>
135<HR SIZE="6">
136<A NAME="SEC51"></A>
137<H3> A.1.2 Low-Level Kernel Initialization </H3>
138<!--docid::SEC51::-->
139<P>
140
141The loader's last action is to transfer control to the kernel's entry
142point, which is <CODE>start()</CODE> in <Q><TT>threads/start.S</TT></Q>. The job of
143this code is to switch the CPU from legacy 16-bit &quot;real mode&quot; into
144the 32-bit &quot;protected mode&quot; used by all modern 80<VAR>x</VAR>86 operating
145systems.
146</P>
147<P>
148
149The startup code's first task is actually to obtain the machine's
150memory size, by asking the BIOS for the PC's memory size. The
151simplest BIOS function to do this can only detect up to 64 MB of RAM,
152so that's the practical limit that Pintos can support. The function
153stores the memory size, in pages, in global variable
154<CODE>init_ram_pages</CODE>.
155</P>
156<P>
157
158The first part of CPU initialization is to enable the A20 line, that
159is, the CPU's address line numbered 20. For historical reasons, PCs
160boot with this address line fixed at 0, which means that attempts to
161access memory beyond the first 1 MB (2 raised to the 20th power) will
162fail. Pintos wants to access more memory than this, so we have to
163enable it.
164</P>
165<P>
166
167Next, the loader creates a basic page table. This page table maps
168the 64 MB at the base of virtual memory (starting at virtual address
1690) directly to the identical physical addresses. It also maps the
170same physical memory starting at virtual address
171<CODE>LOADER_PHYS_BASE</CODE>, which defaults to <TT>0xc0000000</TT> (3 GB). The
172Pintos kernel only wants the latter mapping, but there's a
173chicken-and-egg problem if we don't include the former: our current
174virtual address is roughly <TT>0x20000</TT>, the location where the loader
175put us, and we can't jump to <TT>0xc0020000</TT> until we turn on the
176page table, but if we turn on the page table without jumping there,
177then we've just pulled the rug out from under ourselves.
178</P>
179<P>
180
181After the page table is initialized, we load the CPU's control
182registers to turn on protected mode and paging, and set up the segment
183registers. We aren't yet equipped to handle interrupts in protected
184mode, so we disable interrupts. The final step is to call <CODE>main()</CODE>.
185</P>
186<P>
187
188<A NAME="High-Level Kernel Initialization"></A>
189<HR SIZE="6">
190<A NAME="SEC52"></A>
191<H3> A.1.3 High-Level Kernel Initialization </H3>
192<!--docid::SEC52::-->
193<P>
194
195The kernel proper starts with the <CODE>main()</CODE> function. The
196<CODE>main()</CODE> function is written in C, as will be most of the code we
197encounter in Pintos from here on out.
198</P>
199<P>
200
201When <CODE>main()</CODE> starts, the system is in a pretty raw state. We're
202in 32-bit protected mode with paging enabled, but hardly anything else is
203ready. Thus, the <CODE>main()</CODE> function consists primarily of calls
204into other Pintos modules' initialization functions.
205These are usually named <CODE><VAR>module</VAR>_init()</CODE>, where
206<VAR>module</VAR> is the module's name, <Q><TT><VAR>module</VAR>.c</TT></Q> is the
207module's source code, and <Q><TT><VAR>module</VAR>.h</TT></Q> is the module's
208header.
209</P>
210<P>
211
212The first step in <CODE>main()</CODE> is to call <CODE>bss_init()</CODE>, which clears
213out the kernel's &quot;BSS&quot;, which is the traditional name for a
214segment that should be initialized to all zeros. In most C
215implementations, whenever you
216declare a variable outside a function without providing an
217initializer, that variable goes into the BSS. Because it's all zeros, the
218BSS isn't stored in the image that the loader brought into memory. We
219just use <CODE>memset()</CODE> to zero it out.
220</P>
221<P>
222
223Next, <CODE>main()</CODE> calls <CODE>read_command_line()</CODE> to break the kernel command
224line into arguments, then <CODE>parse_options()</CODE> to read any options at
225the beginning of the command line. (Actions specified on the
226command line execute later.)
227</P>
228<P>
229
230<CODE>thread_init()</CODE> initializes the thread system. We will defer full
231discussion to our discussion of Pintos threads below. It is called so
232early in initialization because a valid thread structure is a
233prerequisite for acquiring a lock, and lock acquisition in turn is
234important to other Pintos subsystems. Then we initialize the console
235and print a startup message to the console.
236</P>
237<P>
238
239The next block of functions we call initializes the kernel's memory
240system. <CODE>palloc_init()</CODE> sets up the kernel page allocator, which
241doles out memory one or more pages at a time (see section <A HREF="pintos_5.html#SEC70">A.5.1 Page Allocator</A>).
242<CODE>malloc_init()</CODE> sets
243up the allocator that handles allocations of arbitrary-size blocks of
244memory (see section <A HREF="pintos_5.html#SEC71">A.5.2 Block Allocator</A>).
245<CODE>paging_init()</CODE> sets up a page table for the kernel (see section <A HREF="pintos_5.html#SEC73">A.7 Page Table</A>).
246</P>
247<P>
248
249In projects 2 and later, <CODE>main()</CODE> also calls <CODE>tss_init()</CODE> and
250<CODE>gdt_init()</CODE>.
251</P>
252<P>
253
254The next set of calls initializes the interrupt system.
255<CODE>intr_init()</CODE> sets up the CPU's <EM>interrupt descriptor table</EM>
256(IDT) to ready it for interrupt handling (see section <A HREF="pintos_5.html#SEC66">A.4.1 Interrupt Infrastructure</A>), then <CODE>timer_init()</CODE> and <CODE>kbd_init()</CODE> prepare for
257handling timer interrupts and keyboard interrupts, respectively.
258<CODE>input_init()</CODE> sets up to merge serial and keyboard input into one
259stream. In
260projects 2 and later, we also prepare to handle interrupts caused by
261user programs using <CODE>exception_init()</CODE> and <CODE>syscall_init()</CODE>.
262</P>
263<P>
264
265Now that interrupts are set up, we can start the scheduler
266with <CODE>thread_start()</CODE>, which creates the idle thread and enables
267interrupts.
268With interrupts enabled, interrupt-driven serial port I/O becomes
269possible, so we use
270<CODE>serial_init_queue()</CODE> to switch to that mode. Finally,
271<CODE>timer_calibrate()</CODE> calibrates the timer for accurate short delays.
272</P>
273<P>
274
275If the file system is compiled in, as it will starting in project 2, we
276initialize the IDE disks with <CODE>ide_init()</CODE>, then the
277file system with <CODE>filesys_init()</CODE>.
278</P>
279<P>
280
281Boot is complete, so we print a message.
282</P>
283<P>
284
285Function <CODE>run_actions()</CODE> now parses and executes actions specified on
286the kernel command line, such as <CODE>run</CODE> to run a test (in project
2871) or a user program (in later projects).
288</P>
289<P>
290
291Finally, if <Q><SAMP>-q</SAMP></Q> was specified on the kernel command line, we
292call <CODE>shutdown_power_off()</CODE> to terminate the machine simulator. Otherwise,
293<CODE>main()</CODE> calls <CODE>thread_exit()</CODE>, which allows any other running
294threads to continue running.
295</P>
296<P>
297
298<A NAME="Physical Memory Map"></A>
299<HR SIZE="6">
300<A NAME="SEC53"></A>
301<H3> A.1.4 Physical Memory Map </H3>
302<!--docid::SEC53::-->
303<P>
304
305</P>
306<TABLE>
307@headitem Memory Range
308</TD><TD> Owner
309</TD><TD> Contents
310
311<TR><TD><TT>00000000</TT>--<TT>000003ff</TT> </TD><TD> CPU </TD><TD> Real mode interrupt table.</TD>
312</TR>
313<TR><TD><TT>00000400</TT>--<TT>000005ff</TT> </TD><TD> BIOS </TD><TD> Miscellaneous data area.</TD>
314</TR>
315<TR><TD><TT>00000600</TT>--<TT>00007bff</TT> </TD><TD> -- </TD><TD> ---</TD>
316</TR>
317<TR><TD><TT>00007c00</TT>--<TT>00007dff</TT> </TD><TD> Pintos </TD><TD> Loader.</TD>
318</TR>
319<TR><TD><TT>0000e000</TT>--<TT>0000efff</TT> </TD><TD> Pintos</TD>
320</TD><TD> Stack for loader; kernel stack and <CODE>struct thread</CODE> for initial
321kernel thread.
322</TR>
323<TR><TD><TT>0000f000</TT>--<TT>0000ffff</TT> </TD><TD> Pintos</TD>
324</TD><TD> Page directory for startup code.
325</TR>
326<TR><TD><TT>00010000</TT>--<TT>00020000</TT> </TD><TD> Pintos</TD>
327</TD><TD> Page tables for startup code.
328</TR>
329<TR><TD><TT>00020000</TT>--<TT>0009ffff</TT> </TD><TD> Pintos</TD>
330</TD><TD> Kernel code, data, and uninitialized data segments.
331</TR>
332<TR><TD><TT>000a0000</TT>--<TT>000bffff</TT> </TD><TD> Video </TD><TD> VGA display memory.</TD>
333</TR>
334<TR><TD><TT>000c0000</TT>--<TT>000effff</TT> </TD><TD> Hardware</TD>
335</TD><TD> Reserved for expansion card RAM and ROM.
336</TR>
337<TR><TD><TT>000f0000</TT>--<TT>000fffff</TT> </TD><TD> BIOS </TD><TD> ROM BIOS.</TD>
338</TR>
339<TR><TD><TT>00100000</TT>--<TT>03ffffff</TT> </TD><TD> Pintos </TD><TD> Dynamic memory allocation.</TD>
340</TR></TABLE>
341<P>
342
343<A NAME="Threads"></A>
344<HR SIZE="6">
345<A NAME="SEC54"></A>
346<H2> A.2 Threads </H2>
347<!--docid::SEC54::-->
348<P>
349
350<A NAME="struct thread"></A>
351<HR SIZE="6">
352<A NAME="SEC55"></A>
353<H3> A.2.1 <CODE>struct thread</CODE> </H3>
354<!--docid::SEC55::-->
355<P>
356
357The main Pintos data structure for threads is <CODE>struct thread</CODE>,
358declared in <Q><TT>threads/thread.h</TT></Q>.
359</P>
360<P>
361
362<A NAME="IDX4"></A>
363</P>
364<DL>
365<DT><U>Structure:</U> <B>struct thread</B>
366<DD>Represents a thread or a user process. In the projects, you will have
367to add your own members to <CODE>struct thread</CODE>. You may also change or
368delete the definitions of existing members.
369<P>
370
371Every <CODE>struct thread</CODE> occupies the beginning of its own page of
372memory. The rest of the page is used for the thread's stack, which
373grows downward from the end of the page. It looks like this:
374</P>
375<P>
376
377<TABLE><tr><td>&nbsp;</td><td class=example><pre> 4 kB +---------------------------------+
378 | kernel stack |
379 | | |
380 | | |
381 | V |
382 | grows downward |
383 | |
384 | |
385 | |
386 | |
387 | |
388 | |
389 | |
390 | |
391sizeof (struct thread) +---------------------------------+
392 | magic |
393 | : |
394 | : |
395 | status |
396 | tid |
397 0 kB +---------------------------------+
398</pre></td></tr></table><P>
399
400This has two consequences. First, <CODE>struct thread</CODE> must not be allowed
401to grow too big. If it does, then there will not be enough room for the
402kernel stack. The base <CODE>struct thread</CODE> is only a few bytes in size. It
403probably should stay well under 1 kB.
404</P>
405<P>
406
407Second, kernel stacks must not be allowed to grow too large. If a stack
408overflows, it will corrupt the thread state. Thus, kernel functions
409should not allocate large structures or arrays as non-static local
410variables. Use dynamic allocation with <CODE>malloc()</CODE> or
411<CODE>palloc_get_page()</CODE> instead (see section <A HREF="pintos_5.html#SEC69">A.5 Memory Allocation</A>).
412</P>
413</DL>
414<P>
415
416<A NAME="IDX5"></A>
417</P>
418<DL>
419<DT><U>Member of <CODE>struct thread</CODE>:</U> tid_t <B>tid</B>
420<DD>The thread's thread identifier or <EM>tid</EM>. Every thread must have a
421tid that is unique over the entire lifetime of the kernel. By
422default, <CODE>tid_t</CODE> is a <CODE>typedef</CODE> for <CODE>int</CODE> and each new
423thread receives the numerically next higher tid, starting from 1 for
424the initial process. You can change the type and the numbering scheme
425if you like.
426</DL>
427<P>
428
429<A NAME="IDX6"></A>
430</P>
431<DL>
432<DT><U>Member of <CODE>struct thread</CODE>:</U> enum thread_status <B>status</B>
433<DD><A NAME="Thread States"></A>
434The thread's state, one of the following:
435<P>
436
437<A NAME="IDX7"></A>
438</P>
439<DL>
440<DT><U>Thread State:</U> <B><CODE>THREAD_RUNNING</CODE></B>
441<DD>The thread is running. Exactly one thread is running at a given time.
442<CODE>thread_current()</CODE> returns the running thread.
443</DL>
444<P>
445
446<A NAME="IDX8"></A>
447</P>
448<DL>
449<DT><U>Thread State:</U> <B><CODE>THREAD_READY</CODE></B>
450<DD>The thread is ready to run, but it's not running right now. The
451thread could be selected to run the next time the scheduler is
452invoked. Ready threads are kept in a doubly linked list called
453<CODE>ready_list</CODE>.
454</DL>
455<P>
456
457<A NAME="IDX9"></A>
458</P>
459<DL>
460<DT><U>Thread State:</U> <B><CODE>THREAD_BLOCKED</CODE></B>
461<DD>The thread is waiting for something, e.g. a lock to become
462available, an interrupt to be invoked. The thread won't be scheduled
463again until it transitions to the <CODE>THREAD_READY</CODE> state with a
464call to <CODE>thread_unblock()</CODE>. This is most conveniently done
465indirectly, using one of the Pintos synchronization primitives that
466block and unblock threads automatically (see section <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>).
467<P>
468
469There is no <I>a priori</I> way to tell what a blocked thread is waiting
470for, but a backtrace can help (see section <A HREF="pintos_8.html#SEC100">D.4 Backtraces</A>).
471</P>
472</DL>
473<P>
474
475<A NAME="IDX10"></A>
476</P>
477<DL>
478<DT><U>Thread State:</U> <B><CODE>THREAD_DYING</CODE></B>
479<DD>The thread will be destroyed by the scheduler after switching to the
480next thread.
481</DL>
482</DL>
483<P>
484
485<A NAME="IDX11"></A>
486</P>
487<DL>
488<DT><U>Member of <CODE>struct thread</CODE>:</U> char <B>name[16]</B>
489<DD>The thread's name as a string, or at least the first few characters of
490it.
491</DL>
492<P>
493
494<A NAME="IDX12"></A>
495</P>
496<DL>
497<DT><U>Member of <CODE>struct thread</CODE>:</U> uint8_t *<B>stack</B>
498<DD>Every thread has its own stack to keep track of its state. When the
499thread is running, the CPU's stack pointer register tracks the top of
500the stack and this member is unused. But when the CPU switches to
501another thread, this member saves the thread's stack pointer. No
502other members are needed to save the thread's registers, because the
503other registers that must be saved are saved on the stack.
504<P>
505
506When an interrupt occurs, whether in the kernel or a user program, an
507<CODE>struct intr_frame</CODE> is pushed onto the stack. When the interrupt occurs
508in a user program, the <CODE>struct intr_frame</CODE> is always at the very top of
509the page. See section <A HREF="pintos_5.html#SEC65">A.4 Interrupt Handling</A>, for more information.
510</P>
511</DL>
512<P>
513
514<A NAME="IDX13"></A>
515</P>
516<DL>
517<DT><U>Member of <CODE>struct thread</CODE>:</U> int <B>priority</B>
518<DD>A thread priority, ranging from <CODE>PRI_MIN</CODE> (0) to <CODE>PRI_MAX</CODE>
519(63). Lower numbers correspond to lower priorities, so that
520priority 0 is the lowest priority and priority 63 is the highest.
521Pintos as provided ignores thread priorities, but you will implement
522priority scheduling in project 1 (see section <A HREF="pintos_3.html#SEC45">3.2.2 Priority Scheduling</A>).
523</DL>
524<P>
525
526<A NAME="IDX14"></A>
527</P>
528<DL>
529<DT><U>Member of <CODE>struct thread</CODE>:</U> <CODE>struct list_elem</CODE> <B>allelem</B>
530<DD>This &quot;list element&quot; is used to link the thread into the list of all
531threads. Each thread is inserted into this list when it is created
532and removed when it exits. The <CODE>thread_foreach()</CODE> function should
533be used to iterate over all threads.
534</DL>
535<P>
536
537<A NAME="IDX15"></A>
538</P>
539<DL>
540<DT><U>Member of <CODE>struct thread</CODE>:</U> <CODE>struct list_elem</CODE> <B>elem</B>
541<DD>A &quot;list element&quot; used to put the thread into doubly linked lists,
542either <CODE>ready_list</CODE> (the list of threads ready to run) or a list of
543threads waiting on a semaphore in <CODE>sema_down()</CODE>. It can do double
544duty because a thread waiting on a semaphore is not ready, and vice
545versa.
546</DL>
547<P>
548
549<A NAME="IDX16"></A>
550</P>
551<DL>
552<DT><U>Member of <CODE>struct thread</CODE>:</U> uint32_t *<B>pagedir</B>
553<DD>Only present in project 2 and later. See <A HREF="pintos_4.html#Page Tables">Page Tables</A>.
554</DL>
555<P>
556
557<A NAME="IDX17"></A>
558</P>
559<DL>
560<DT><U>Member of <CODE>struct thread</CODE>:</U> unsigned <B>magic</B>
561<DD>Always set to <CODE>THREAD_MAGIC</CODE>, which is just an arbitrary number defined
562in <Q><TT>threads/thread.c</TT></Q>, and used to detect stack overflow.
563<CODE>thread_current()</CODE> checks that the <CODE>magic</CODE> member of the running
564thread's <CODE>struct thread</CODE> is set to <CODE>THREAD_MAGIC</CODE>. Stack overflow
565tends to change this value, triggering the assertion. For greatest
566benefit, as you add members to <CODE>struct thread</CODE>, leave <CODE>magic</CODE> at
567the end.
568</DL>
569<P>
570
571<A NAME="Thread Functions"></A>
572<HR SIZE="6">
573<A NAME="SEC56"></A>
574<H3> A.2.2 Thread Functions </H3>
575<!--docid::SEC56::-->
576<P>
577
578<Q><TT>threads/thread.c</TT></Q> implements several public functions for thread
579support. Let's take a look at the most useful:
580</P>
581<P>
582
583<A NAME="IDX18"></A>
584</P>
585<DL>
586<DT><U>Function:</U> void <B>thread_init</B> (void)
587<DD>Called by <CODE>main()</CODE> to initialize the thread system. Its main
588purpose is to create a <CODE>struct thread</CODE> for Pintos's initial thread.
589This is possible because the Pintos loader puts the initial
590thread's stack at the top of a page, in the same position as any other
591Pintos thread.
592<P>
593
594Before <CODE>thread_init()</CODE> runs,
595<CODE>thread_current()</CODE> will fail because the running thread's
596<CODE>magic</CODE> value is incorrect. Lots of functions call
597<CODE>thread_current()</CODE> directly or indirectly, including
598<CODE>lock_acquire()</CODE> for locking a lock, so <CODE>thread_init()</CODE> is
599called early in Pintos initialization.
600</P>
601</DL>
602<P>
603
604<A NAME="IDX19"></A>
605</P>
606<DL>
607<DT><U>Function:</U> void <B>thread_start</B> (void)
608<DD>Called by <CODE>main()</CODE> to start the scheduler. Creates the idle
609thread, that is, the thread that is scheduled when no other thread is
610ready. Then enables interrupts, which as a side effect enables the
611scheduler because the scheduler runs on return from the timer interrupt, using
612<CODE>intr_yield_on_return()</CODE> (see section <A HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>).
613</DL>
614<P>
615
616<A NAME="IDX20"></A>
617</P>
618<DL>
619<DT><U>Function:</U> void <B>thread_tick</B> (void)
620<DD>Called by the timer interrupt at each timer tick. It keeps track of
621thread statistics and triggers the scheduler when a time slice expires.
622</DL>
623<P>
624
625<A NAME="IDX21"></A>
626</P>
627<DL>
628<DT><U>Function:</U> void <B>thread_print_stats</B> (void)
629<DD>Called during Pintos shutdown to print thread statistics.
630</DL>
631<P>
632
633<A NAME="IDX22"></A>
634</P>
635<DL>
636<DT><U>Function:</U> tid_t <B>thread_create</B> (const char *<VAR>name</VAR>, int <VAR>priority</VAR>, thread_func *<VAR>func</VAR>, void *<VAR>aux</VAR>)
637<DD>Creates and starts a new thread named <VAR>name</VAR> with the given
638<VAR>priority</VAR>, returning the new thread's tid. The thread executes
639<VAR>func</VAR>, passing <VAR>aux</VAR> as the function's single argument.
640<P>
641
642<CODE>thread_create()</CODE> allocates a page for the thread's
643<CODE>struct thread</CODE> and stack and initializes its members, then it sets
644up a set of fake stack frames for it (see section <A HREF="pintos_5.html#SEC57">A.2.3 Thread Switching</A>). The
645thread is initialized in the blocked state, then unblocked just before
646returning, which allows the new thread to
647be scheduled (see <A HREF="pintos_5.html#Thread States">Thread States</A>).
648</P>
649<P>
650
651<A NAME="IDX23"></A>
652</P>
653<DL>
654<DT><U>Type:</U> <B>void thread_func (void *<VAR>aux</VAR>)</B>
655<DD>This is the type of the function passed to <CODE>thread_create()</CODE>, whose
656<VAR>aux</VAR> argument is passed along as the function's argument.
657</DL>
658</DL>
659<P>
660
661<A NAME="IDX24"></A>
662</P>
663<DL>
664<DT><U>Function:</U> void <B>thread_block</B> (void)
665<DD>Transitions the running thread from the running state to the blocked
666state (see <A HREF="pintos_5.html#Thread States">Thread States</A>). The thread will not run again until
667<CODE>thread_unblock()</CODE> is
668called on it, so you'd better have some way arranged for that to happen.
669Because <CODE>thread_block()</CODE> is so low-level, you should prefer to use
670one of the synchronization primitives instead (see section <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>).
671</DL>
672<P>
673
674<A NAME="IDX25"></A>
675</P>
676<DL>
677<DT><U>Function:</U> void <B>thread_unblock</B> (struct thread *<VAR>thread</VAR>)
678<DD>Transitions <VAR>thread</VAR>, which must be in the blocked state, to the
679ready state, allowing it to resume running (see <A HREF="pintos_5.html#Thread States">Thread States</A>).
680This is called when the event that the thread is waiting for occurs,
681e.g. when the lock that
682the thread is waiting on becomes available.
683</DL>
684<P>
685
686<A NAME="IDX26"></A>
687</P>
688<DL>
689<DT><U>Function:</U> struct thread *<B>thread_current</B> (void)
690<DD>Returns the running thread.
691</DL>
692<P>
693
694<A NAME="IDX27"></A>
695</P>
696<DL>
697<DT><U>Function:</U> tid_t <B>thread_tid</B> (void)
698<DD>Returns the running thread's thread id. Equivalent to
699<CODE>thread_current ()-&gt;tid</CODE>.
700</DL>
701<P>
702
703<A NAME="IDX28"></A>
704</P>
705<DL>
706<DT><U>Function:</U> const char *<B>thread_name</B> (void)
707<DD>Returns the running thread's name. Equivalent to <CODE>thread_current
708()-&gt;name</CODE>.
709</DL>
710<P>
711
712<A NAME="IDX29"></A>
713</P>
714<DL>
715<DT><U>Function:</U> void <B>thread_exit</B> (void) <CODE>NO_RETURN</CODE>
716<DD>Causes the current thread to exit. Never returns, hence
717<CODE>NO_RETURN</CODE> (see section <A HREF="pintos_8.html#SEC99">D.3 Function and Parameter Attributes</A>).
718</DL>
719<P>
720
721<A NAME="IDX30"></A>
722</P>
723<DL>
724<DT><U>Function:</U> void <B>thread_yield</B> (void)
725<DD>Yields the CPU to the scheduler, which picks a new thread to run. The
726new thread might be the current thread, so you can't depend on this
727function to keep this thread from running for any particular length of
728time.
729</DL>
730<P>
731
732<A NAME="IDX31"></A>
733</P>
734<DL>
735<DT><U>Function:</U> void <B>thread_foreach</B> (thread_action_func *<VAR>action</VAR>, void *<VAR>aux</VAR>)
736<DD>Iterates over all threads <VAR>t</VAR> and invokes <CODE>action(t, aux)</CODE> on each.
737<VAR>action</VAR> must refer to a function that matches the signature
738given by <CODE>thread_action_func()</CODE>:
739<P>
740
741<A NAME="IDX32"></A>
742</P>
743<DL>
744<DT><U>Type:</U> <B>void thread_action_func (struct thread *<VAR>thread</VAR>, void *<VAR>aux</VAR>)</B>
745<DD>Performs some action on a thread, given <VAR>aux</VAR>.
746</DL>
747</DL>
748<P>
749
750<A NAME="IDX33"></A>
751</P>
752<DL>
753<DT><U>Function:</U> int <B>thread_get_priority</B> (void)
754<DD><A NAME="IDX34"></A>
755<DT><U>Function:</U> void <B>thread_set_priority</B> (int <VAR>new_priority</VAR>)
756<DD>Stub to set and get thread priority. See section <A HREF="pintos_3.html#SEC45">3.2.2 Priority Scheduling</A>.
757</DL>
758<P>
759
760<A NAME="IDX35"></A>
761</P>
762<DL>
763<DT><U>Function:</U> int <B>thread_get_nice</B> (void)
764<DD><A NAME="IDX36"></A>
765<DT><U>Function:</U> void <B>thread_set_nice</B> (int <VAR>new_nice</VAR>)
766<DD><A NAME="IDX37"></A>
767<DT><U>Function:</U> int <B>thread_get_recent_cpu</B> (void)
768<DD><A NAME="IDX38"></A>
769<DT><U>Function:</U> int <B>thread_get_load_avg</B> (void)
770<DD>Stubs for the advanced scheduler (not used in this course).
771</DL>
772<P>
773
774<A NAME="Thread Switching"></A>
775<HR SIZE="6">
776<A NAME="SEC57"></A>
777<H3> A.2.3 Thread Switching </H3>
778<!--docid::SEC57::-->
779<P>
780
781<CODE>schedule()</CODE> is responsible for switching threads. It
782is internal to <Q><TT>threads/thread.c</TT></Q> and called only by the three
783public thread functions that need to switch threads:
784<CODE>thread_block()</CODE>, <CODE>thread_exit()</CODE>, and <CODE>thread_yield()</CODE>.
785Before any of these functions call <CODE>schedule()</CODE>, they disable
786interrupts (or ensure that they are already disabled) and then change
787the running thread's state to something other than running.
788</P>
789<P>
790
791<CODE>schedule()</CODE> is short but tricky. It records the
792current thread in local variable <VAR>cur</VAR>, determines the next thread
793to run as local variable <VAR>next</VAR> (by calling
794<CODE>next_thread_to_run()</CODE>), and then calls <CODE>switch_threads()</CODE> to do
795the actual thread switch. The thread we switched to was also running
796inside <CODE>switch_threads()</CODE>, as are all the threads not currently
797running, so the new thread now returns out of
798<CODE>switch_threads()</CODE>, returning the previously running thread.
799</P>
800<P>
801
802<CODE>switch_threads()</CODE> is an assembly language routine in
803<Q><TT>threads/switch.S</TT></Q>. It saves registers on the stack, saves the
804CPU's current stack pointer in the current <CODE>struct thread</CODE>'s <CODE>stack</CODE>
805member, restores the new thread's <CODE>stack</CODE> into the CPU's stack
806pointer, restores registers from the stack, and returns.
807</P>
808<P>
809
810The rest of the scheduler is implemented in <CODE>thread_schedule_tail()</CODE>. It
811marks the new thread as running. If the thread we just switched from
812is in the dying state, then it also frees the page that contained the
813dying thread's <CODE>struct thread</CODE> and stack. These couldn't be freed
814prior to the thread switch because the switch needed to use it.
815</P>
816<P>
817
818Running a thread for the first time is a special case. When
819<CODE>thread_create()</CODE> creates a new thread, it goes through a fair
820amount of trouble to get it started properly. In particular, the new
821thread hasn't started running yet, so there's no way for it to be
822running inside <CODE>switch_threads()</CODE> as the scheduler expects. To
823solve the problem, <CODE>thread_create()</CODE> creates some fake stack frames
824in the new thread's stack:
825</P>
826<P>
827
828<UL>
829<LI>
830The topmost fake stack frame is for <CODE>switch_threads()</CODE>, represented
831by <CODE>struct switch_threads_frame</CODE>. The important part of this frame is
832its <CODE>eip</CODE> member, the return address. We point <CODE>eip</CODE> to
833<CODE>switch_entry()</CODE>, indicating it to be the function that called
834<CODE>switch_entry()</CODE>.
835<P>
836
837</P>
838<LI>
839The next fake stack frame is for <CODE>switch_entry()</CODE>, an assembly
840language routine in <Q><TT>threads/switch.S</TT></Q> that adjusts the stack
841pointer,<A NAME="DOCF3" HREF="pintos_fot.html#FOOT3">(3)</A>
842calls <CODE>thread_schedule_tail()</CODE> (this special case is why
843<CODE>thread_schedule_tail()</CODE> is separate from <CODE>schedule()</CODE>), and returns.
844We fill in its stack frame so that it returns into
845<CODE>kernel_thread()</CODE>, a function in <Q><TT>threads/thread.c</TT></Q>.
846<P>
847
848</P>
849<LI>
850The final stack frame is for <CODE>kernel_thread()</CODE>, which enables
851interrupts and calls the thread's function (the function passed to
852<CODE>thread_create()</CODE>). If the thread's function returns, it calls
853<CODE>thread_exit()</CODE> to terminate the thread.
854</UL>
855<P>
856
857<A NAME="Synchronization"></A>
858<HR SIZE="6">
859<A NAME="SEC58"></A>
860<H2> A.3 Synchronization </H2>
861<!--docid::SEC58::-->
862<P>
863
864If sharing of resources between threads is not handled in a careful,
865controlled fashion, the result is usually a big mess.
866This is especially the case in operating system kernels, where
867faulty sharing can crash the entire machine. Pintos provides several
868synchronization primitives to help out.
869</P>
870<P>
871
872<A NAME="Disabling Interrupts"></A>
873<HR SIZE="6">
874<A NAME="SEC59"></A>
875<H3> A.3.1 Disabling Interrupts </H3>
876<!--docid::SEC59::-->
877<P>
878
879The crudest way to do synchronization is to disable interrupts, that
880is, to temporarily prevent the CPU from responding to interrupts. If
881interrupts are off, no other thread will preempt the running thread,
882because thread preemption is driven by the timer interrupt. If
883interrupts are on, as they normally are, then the running thread may
884be preempted by another at any time, whether between two C statements
885or even within the execution of one.
886</P>
887<P>
888
889Incidentally, this means that Pintos is a &quot;preemptible kernel,&quot; that
890is, kernel threads can be preempted at any time. Traditional Unix
891systems are &quot;nonpreemptible,&quot; that is, kernel threads can only be
892preempted at points where they explicitly call into the scheduler.
893(User programs can be preempted at any time in both models.) As you
894might imagine, preemptible kernels require more explicit
895synchronization.
896</P>
897<P>
898
899You should have little need to set the interrupt state directly. Most
900of the time you should use the other synchronization primitives
901described in the following sections. The main reason to disable
902interrupts is to synchronize kernel threads with external interrupt
903handlers, which cannot sleep and thus cannot use most other forms of
904synchronization (see section <A HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>).
905</P>
906<P>
907
908Some external interrupts cannot be postponed, even by disabling
909interrupts. These interrupts, called <EM>non-maskable interrupts</EM>
910(NMIs), are supposed to be used only in emergencies, e.g. when the
911computer is on fire. Pintos does not handle non-maskable interrupts.
912</P>
913<P>
914
915Types and functions for disabling and enabling interrupts are in
916<Q><TT>threads/interrupt.h</TT></Q>.
917</P>
918<P>
919
920<A NAME="IDX39"></A>
921</P>
922<DL>
923<DT><U>Type:</U> <B>enum intr_level</B>
924<DD>One of <CODE>INTR_OFF</CODE> or <CODE>INTR_ON</CODE>, denoting that interrupts are
925disabled or enabled, respectively.
926</DL>
927<P>
928
929<A NAME="IDX40"></A>
930</P>
931<DL>
932<DT><U>Function:</U> enum intr_level <B>intr_get_level</B> (void)
933<DD>Returns the current interrupt state.
934</DL>
935<P>
936
937<A NAME="IDX41"></A>
938</P>
939<DL>
940<DT><U>Function:</U> enum intr_level <B>intr_set_level</B> (enum intr_level <VAR>level</VAR>)
941<DD>Turns interrupts on or off according to <VAR>level</VAR>. Returns the
942previous interrupt state.
943</DL>
944<P>
945
946<A NAME="IDX42"></A>
947</P>
948<DL>
949<DT><U>Function:</U> enum intr_level <B>intr_enable</B> (void)
950<DD>Turns interrupts on. Returns the previous interrupt state.
951</DL>
952<P>
953
954<A NAME="IDX43"></A>
955</P>
956<DL>
957<DT><U>Function:</U> enum intr_level <B>intr_disable</B> (void)
958<DD>Turns interrupts off. Returns the previous interrupt state.
959</DL>
960<P>
961
962<A NAME="Semaphores"></A>
963<HR SIZE="6">
964<A NAME="SEC60"></A>
965<H3> A.3.2 Semaphores </H3>
966<!--docid::SEC60::-->
967<P>
968
969A <EM>semaphore</EM> is a nonnegative integer together with two operators
970that manipulate it atomically, which are:
971</P>
972<P>
973
974<UL>
975<LI>
976&quot;Down&quot; or &quot;P&quot;: wait for the value to become positive, then
977decrement it.
978<P>
979
980</P>
981<LI>
982&quot;Up&quot; or &quot;V&quot;: increment the value (and wake up one waiting thread,
983if any).
984</UL>
985<P>
986
987A semaphore initialized to 0 may be used to wait for an event
988that will happen exactly once. For example, suppose thread <VAR>A</VAR>
989starts another thread <VAR>B</VAR> and wants to wait for <VAR>B</VAR> to signal
990that some activity is complete. <VAR>A</VAR> can create a semaphore
991initialized to 0, pass it to <VAR>B</VAR> as it starts it, and then
992&quot;down&quot; the semaphore. When <VAR>B</VAR> finishes its activity, it
993&quot;ups&quot; the semaphore. This works regardless of whether <VAR>A</VAR>
994&quot;downs&quot; the semaphore or <VAR>B</VAR> &quot;ups&quot; it first.
995</P>
996<P>
997
998A semaphore initialized to 1 is typically used for controlling access
999to a resource. Before a block of code starts using the resource, it
1000&quot;downs&quot; the semaphore, then after it is done with the resource it
1001&quot;ups&quot; the resource. In such a case a lock, described below, may be
1002more appropriate.
1003</P>
1004<P>
1005
1006Semaphores can also be initialized to values larger than 1. These are
1007rarely used.
1008</P>
1009<P>
1010
1011Semaphores were invented by Edsger Dijkstra and first used in the THE
1012operating system ([ <A HREF="pintos_10.html#Dijkstra">Dijkstra</A>]).
1013</P>
1014<P>
1015
1016Pintos' semaphore type and operations are declared in
1017<Q><TT>threads/synch.h</TT></Q>.
1018</P>
1019<P>
1020
1021<A NAME="IDX44"></A>
1022</P>
1023<DL>
1024<DT><U>Type:</U> <B>struct semaphore</B>
1025<DD>Represents a semaphore.
1026</DL>
1027<P>
1028
1029<A NAME="IDX45"></A>
1030</P>
1031<DL>
1032<DT><U>Function:</U> void <B>sema_init</B> (struct semaphore *<VAR>sema</VAR>, unsigned <VAR>value</VAR>)
1033<DD>Initializes <VAR>sema</VAR> as a new semaphore with the given initial
1034<VAR>value</VAR>.
1035</DL>
1036<P>
1037
1038<A NAME="IDX46"></A>
1039</P>
1040<DL>
1041<DT><U>Function:</U> void <B>sema_down</B> (struct semaphore *<VAR>sema</VAR>)
1042<DD>Executes the &quot;down&quot; or &quot;P&quot; operation on <VAR>sema</VAR>, waiting for
1043its value to become positive and then decrementing it by one.
1044</DL>
1045<P>
1046
1047<A NAME="IDX47"></A>
1048</P>
1049<DL>
1050<DT><U>Function:</U> bool <B>sema_try_down</B> (struct semaphore *<VAR>sema</VAR>)
1051<DD>Tries to execute the &quot;down&quot; or &quot;P&quot; operation on <VAR>sema</VAR>,
1052without waiting. Returns true if <VAR>sema</VAR>
1053was successfully decremented, or false if it was already
1054zero and thus could not be decremented without waiting. Calling this
1055function in a
1056tight loop wastes CPU time, so use <CODE>sema_down()</CODE> or find a
1057different approach instead.
1058</DL>
1059<P>
1060
1061<A NAME="IDX48"></A>
1062</P>
1063<DL>
1064<DT><U>Function:</U> void <B>sema_up</B> (struct semaphore *<VAR>sema</VAR>)
1065<DD>Executes the &quot;up&quot; or &quot;V&quot; operation on <VAR>sema</VAR>,
1066incrementing its value. If any threads are waiting on
1067<VAR>sema</VAR>, wakes one of them up.
1068<P>
1069
1070Unlike most synchronization primitives, <CODE>sema_up()</CODE> may be called
1071inside an external interrupt handler (see section <A HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>).
1072</P>
1073</DL>
1074<P>
1075
1076Semaphores are internally built out of disabling interrupt
1077(see section <A HREF="pintos_5.html#SEC59">A.3.1 Disabling Interrupts</A>) and thread blocking and unblocking
1078(<CODE>thread_block()</CODE> and <CODE>thread_unblock()</CODE>). Each semaphore maintains
1079a list of waiting threads, using the linked list
1080implementation in <Q><TT>lib/kernel/list.c</TT></Q>.
1081</P>
1082<P>
1083
1084<A NAME="Locks"></A>
1085<HR SIZE="6">
1086<A NAME="SEC61"></A>
1087<H3> A.3.3 Locks </H3>
1088<!--docid::SEC61::-->
1089<P>
1090
1091A <EM>lock</EM> is like a semaphore with an initial value of 1
1092(see section <A HREF="pintos_5.html#SEC60">A.3.2 Semaphores</A>). A lock's equivalent of &quot;up&quot; is called
1093&quot;release&quot;, and the &quot;down&quot; operation is called &quot;acquire&quot;.
1094</P>
1095<P>
1096
1097Compared to a semaphore, a lock has one added restriction: only the
1098thread that acquires a lock, called the lock's &quot;owner&quot;, is allowed to
1099release it. If this restriction is a problem, it's a good sign that a
1100semaphore should be used, instead of a lock.
1101</P>
1102<P>
1103
1104Locks in Pintos are not &quot;recursive,&quot; that is, it is an error for the
1105thread currently holding a lock to try to acquire that lock.
1106</P>
1107<P>
1108
1109Lock types and functions are declared in <Q><TT>threads/synch.h</TT></Q>.
1110</P>
1111<P>
1112
1113<A NAME="IDX49"></A>
1114</P>
1115<DL>
1116<DT><U>Type:</U> <B>struct lock</B>
1117<DD>Represents a lock.
1118</DL>
1119<P>
1120
1121<A NAME="IDX50"></A>
1122</P>
1123<DL>
1124<DT><U>Function:</U> void <B>lock_init</B> (struct lock *<VAR>lock</VAR>)
1125<DD>Initializes <VAR>lock</VAR> as a new lock.
1126The lock is not initially owned by any thread.
1127</DL>
1128<P>
1129
1130<A NAME="IDX51"></A>
1131</P>
1132<DL>
1133<DT><U>Function:</U> void <B>lock_acquire</B> (struct lock *<VAR>lock</VAR>)
1134<DD>Acquires <VAR>lock</VAR> for the current thread, first waiting for
1135any current owner to release it if necessary.
1136</DL>
1137<P>
1138
1139<A NAME="IDX52"></A>
1140</P>
1141<DL>
1142<DT><U>Function:</U> bool <B>lock_try_acquire</B> (struct lock *<VAR>lock</VAR>)
1143<DD>Tries to acquire <VAR>lock</VAR> for use by the current thread, without
1144waiting. Returns true if successful, false if the lock is already
1145owned. Calling this function in a tight loop is a bad idea because it
1146wastes CPU time, so use <CODE>lock_acquire()</CODE> instead.
1147</DL>
1148<P>
1149
1150<A NAME="IDX53"></A>
1151</P>
1152<DL>
1153<DT><U>Function:</U> void <B>lock_release</B> (struct lock *<VAR>lock</VAR>)
1154<DD>Releases <VAR>lock</VAR>, which the current thread must own.
1155</DL>
1156<P>
1157
1158<A NAME="IDX54"></A>
1159</P>
1160<DL>
1161<DT><U>Function:</U> bool <B>lock_held_by_current_thread</B> (const struct lock *<VAR>lock</VAR>)
1162<DD>Returns true if the running thread owns <VAR>lock</VAR>,
1163false otherwise.
1164There is no function to test whether an arbitrary thread owns a lock,
1165because the answer could change before the caller could act on it.
1166</DL>
1167<P>
1168
1169<A NAME="Monitors"></A>
1170<HR SIZE="6">
1171<A NAME="SEC62"></A>
1172<H3> A.3.4 Monitors </H3>
1173<!--docid::SEC62::-->
1174<P>
1175
1176A <EM>monitor</EM> is a higher-level form of synchronization than a
1177semaphore or a lock. A monitor consists of data being synchronized,
1178plus a lock, called the <EM>monitor lock</EM>, and one or more
1179<EM>condition variables</EM>. Before it accesses the protected data, a
1180thread first acquires the monitor lock. It is then said to be &quot;in the
1181monitor&quot;. While in the monitor, the thread has control over all the
1182protected data, which it may freely examine or modify. When access to
1183the protected data is complete, it releases the monitor lock.
1184</P>
1185<P>
1186
1187Condition variables allow code in the monitor to wait for a condition to
1188become true. Each condition variable is associated with an abstract
1189condition, e.g. &quot;some data has arrived for processing&quot; or &quot;over 10
1190seconds has passed since the user's last keystroke&quot;. When code in the
1191monitor needs to wait for a condition to become true, it &quot;waits&quot; on
1192the associated condition variable, which releases the lock and waits for
1193the condition to be signaled. If, on the other hand, it has caused one
1194of these conditions to become true, it &quot;signals&quot; the condition to wake
1195up one waiter, or &quot;broadcasts&quot; the condition to wake all of them.
1196</P>
1197<P>
1198
1199The theoretical framework for monitors was laid out by C. A. R.
1200Hoare ([ <A HREF="pintos_10.html#Hoare">Hoare</A>]). Their practical usage was later elaborated in a
1201paper on the Mesa operating system ([ <A HREF="pintos_10.html#Lampson">Lampson</A>]).
1202</P>
1203<P>
1204
1205Condition variable types and functions are declared in
1206<Q><TT>threads/synch.h</TT></Q>.
1207</P>
1208<P>
1209
1210<A NAME="IDX55"></A>
1211</P>
1212<DL>
1213<DT><U>Type:</U> <B>struct condition</B>
1214<DD>Represents a condition variable.
1215</DL>
1216<P>
1217
1218<A NAME="IDX56"></A>
1219</P>
1220<DL>
1221<DT><U>Function:</U> void <B>cond_init</B> (struct condition *<VAR>cond</VAR>)
1222<DD>Initializes <VAR>cond</VAR> as a new condition variable.
1223</DL>
1224<P>
1225
1226<A NAME="IDX57"></A>
1227</P>
1228<DL>
1229<DT><U>Function:</U> void <B>cond_wait</B> (struct condition *<VAR>cond</VAR>, struct lock *<VAR>lock</VAR>)
1230<DD>Atomically releases <VAR>lock</VAR> (the monitor lock) and waits for
1231<VAR>cond</VAR> to be signaled by some other piece of code. After
1232<VAR>cond</VAR> is signaled, reacquires <VAR>lock</VAR> before returning.
1233<VAR>lock</VAR> must be held before calling this function.
1234<P>
1235
1236Sending a signal and waking up from a wait are not an atomic operation.
1237Thus, typically <CODE>cond_wait()</CODE>'s caller must recheck the condition
1238after the wait completes and, if necessary, wait again. See the next
1239section for an example.
1240</P>
1241</DL>
1242<P>
1243
1244<A NAME="IDX58"></A>
1245</P>
1246<DL>
1247<DT><U>Function:</U> void <B>cond_signal</B> (struct condition *<VAR>cond</VAR>, struct lock *<VAR>lock</VAR>)
1248<DD>If any threads are waiting on <VAR>cond</VAR> (protected by monitor lock
1249<VAR>lock</VAR>), then this function wakes up one of them. If no threads are
1250waiting, returns without performing any action.
1251<VAR>lock</VAR> must be held before calling this function.
1252</DL>
1253<P>
1254
1255<A NAME="IDX59"></A>
1256</P>
1257<DL>
1258<DT><U>Function:</U> void <B>cond_broadcast</B> (struct condition *<VAR>cond</VAR>, struct lock *<VAR>lock</VAR>)
1259<DD>Wakes up all threads, if any, waiting on <VAR>cond</VAR> (protected by
1260monitor lock <VAR>lock</VAR>). <VAR>lock</VAR> must be held before calling this
1261function.
1262</DL>
1263<P>
1264
1265<HR SIZE="6">
1266<A NAME="SEC63"></A>
1267<H4> A.3.4.1 Monitor Example </H4>
1268<!--docid::SEC63::-->
1269<P>
1270
1271The classical example of a monitor is handling a buffer into which one
1272or more
1273&quot;producer&quot; threads write characters and out of which one or more
1274&quot;consumer&quot; threads read characters. To implement this we need,
1275besides the monitor lock, two condition variables which we will call
1276<VAR>not_full</VAR> and <VAR>not_empty</VAR>:
1277</P>
1278<P>
1279
1280<TABLE><tr><td>&nbsp;</td><td class=example><pre>char buf[BUF_SIZE]; /* Buffer. */
1281size_t n = 0; /* 0 &lt;= n &lt;= <VAR>BUF_SIZE</VAR>: # of characters in buffer. */
1282size_t head = 0; /* <VAR>buf</VAR> index of next char to write (mod <VAR>BUF_SIZE</VAR>). */
1283size_t tail = 0; /* <VAR>buf</VAR> index of next char to read (mod <VAR>BUF_SIZE</VAR>). */
1284struct lock lock; /* Monitor lock. */
1285struct condition not_empty; /* Signaled when the buffer is not empty. */
1286struct condition not_full; /* Signaled when the buffer is not full. */
1287
1288<small>...</small>initialize the locks and condition variables<small>...</small>
1289
1290void put (char ch) {
1291 lock_acquire (&amp;lock);
1292 while (n == BUF_SIZE) /* Can't add to <VAR>buf</VAR> as long as it's full. */
1293 cond_wait (&amp;not_full, &amp;lock);
1294 buf[head++ % BUF_SIZE] = ch; /* Add <VAR>ch</VAR> to <VAR>buf</VAR>. */
1295 n++;
1296 cond_signal (&amp;not_empty, &amp;lock); /* <VAR>buf</VAR> can't be empty anymore. */
1297 lock_release (&amp;lock);
1298}
1299
1300char get (void) {
1301 char ch;
1302 lock_acquire (&amp;lock);
1303 while (n == 0) /* Can't read <VAR>buf</VAR> as long as it's empty. */
1304 cond_wait (&amp;not_empty, &amp;lock);
1305 ch = buf[tail++ % BUF_SIZE]; /* Get <VAR>ch</VAR> from <VAR>buf</VAR>. */
1306 n--;
1307 cond_signal (&amp;not_full, &amp;lock); /* <VAR>buf</VAR> can't be full anymore. */
1308 lock_release (&amp;lock);
1309}
1310</pre></td></tr></table><P>
1311
1312Note that <CODE>BUF_SIZE</CODE> must divide evenly into <CODE>SIZE_MAX + 1</CODE>
1313for the above code to be completely correct. Otherwise, it will fail
1314the first time <CODE>head</CODE> wraps around to 0. In practice,
1315<CODE>BUF_SIZE</CODE> would ordinarily be a power of 2.
1316</P>
1317<P>
1318
1319<A NAME="Optimization Barriers"></A>
1320<HR SIZE="6">
1321<A NAME="SEC64"></A>
1322<H3> A.3.5 Optimization Barriers </H3>
1323<!--docid::SEC64::-->
1324<P>
1325
1326An <EM>optimization barrier</EM> is a special statement that prevents the
1327compiler from making assumptions about the state of memory across the
1328barrier. The compiler will not reorder reads or writes of variables
1329across the barrier or assume that a variable's value is unmodified
1330across the barrier, except for local variables whose address is never
1331taken. In Pintos, <Q><TT>threads/synch.h</TT></Q> defines the <CODE>barrier()</CODE>
1332macro as an optimization barrier.
1333</P>
1334<P>
1335
1336One reason to use an optimization barrier is when data can change
1337asynchronously, without the compiler's knowledge, e.g. by another
1338thread or an interrupt handler. The <CODE>too_many_loops()</CODE> function in
1339<Q><TT>devices/timer.c</TT></Q> is an example. This function starts out by
1340busy-waiting in a loop until a timer tick occurs:
1341</P>
1342<P>
1343
1344<TABLE><tr><td>&nbsp;</td><td class=example><pre>/* Wait for a timer tick. */
1345int64_t start = ticks;
1346while (ticks == start)
1347 barrier ();
1348</pre></td></tr></table><P>
1349
1350Without an optimization barrier in the loop, the compiler could
1351conclude that the loop would never terminate, because <CODE>start</CODE> and
1352<CODE>ticks</CODE> start out equal and the loop itself never changes them.
1353It could then &quot;optimize&quot; the function into an infinite loop, which
1354would definitely be undesirable.
1355</P>
1356<P>
1357
1358Optimization barriers can be used to avoid other compiler
1359optimizations. The <CODE>busy_wait()</CODE> function, also in
1360<Q><TT>devices/timer.c</TT></Q>, is an example. It contains this loop:
1361</P>
1362<P>
1363
1364<TABLE><tr><td>&nbsp;</td><td class=example><pre>while (loops-- &gt; 0)
1365 barrier ();
1366</pre></td></tr></table><P>
1367
1368The goal of this loop is to busy-wait by counting <CODE>loops</CODE> down
1369from its original value to 0. Without the barrier, the compiler could
1370delete the loop entirely, because it produces no useful output and has
1371no side effects. The barrier forces the compiler to pretend that the
1372loop body has an important effect.
1373</P>
1374<P>
1375
1376Finally, optimization barriers can be used to force the ordering of
1377memory reads or writes. For example, suppose we add a &quot;feature&quot;
1378that, whenever a timer interrupt occurs, the character in global
1379variable <CODE>timer_put_char</CODE> is printed on the console, but only if
1380global Boolean variable <CODE>timer_do_put</CODE> is true. The best way to
1381set up <Q><SAMP>x</SAMP></Q> to be printed is then to use an optimization barrier,
1382like this:
1383</P>
1384<P>
1385
1386<TABLE><tr><td>&nbsp;</td><td class=example><pre>timer_put_char = 'x';
1387barrier ();
1388timer_do_put = true;
1389</pre></td></tr></table><P>
1390
1391Without the barrier, the code is buggy because the compiler is free to
1392reorder operations when it doesn't see a reason to keep them in the
1393same order. In this case, the compiler doesn't know that the order of
1394assignments is important, so its optimizer is permitted to exchange
1395their order. There's no telling whether it will actually do this, and
1396it is possible that passing the compiler different optimization flags
1397or using a different version of the compiler will produce different
1398behavior.
1399</P>
1400<P>
1401
1402Another solution is to disable interrupts around the assignments.
1403This does not prevent reordering, but it prevents the interrupt
1404handler from intervening between the assignments. It also has the
1405extra runtime cost of disabling and re-enabling interrupts:
1406</P>
1407<P>
1408
1409<TABLE><tr><td>&nbsp;</td><td class=example><pre>enum intr_level old_level = intr_disable ();
1410timer_put_char = 'x';
1411timer_do_put = true;
1412intr_set_level (old_level);
1413</pre></td></tr></table><P>
1414
1415A second solution is to mark the declarations of
1416<CODE>timer_put_char</CODE> and <CODE>timer_do_put</CODE> as <Q><SAMP>volatile</SAMP></Q>. This
1417keyword tells the compiler that the variables are externally observable
1418and restricts its latitude for optimization. However, the semantics of
1419<Q><SAMP>volatile</SAMP></Q> are not well-defined, so it is not a good general
1420solution. The base Pintos code does not use <Q><SAMP>volatile</SAMP></Q> at all.
1421</P>
1422<P>
1423
1424The following is <EM>not</EM> a solution, because locks neither prevent
1425interrupts nor prevent the compiler from reordering the code within the
1426region where the lock is held:
1427</P>
1428<P>
1429
1430<TABLE><tr><td>&nbsp;</td><td class=example><pre>lock_acquire (&amp;timer_lock); /* INCORRECT CODE */
1431timer_put_char = 'x';
1432timer_do_put = true;
1433lock_release (&amp;timer_lock);
1434</pre></td></tr></table><P>
1435
1436The compiler treats invocation of any function defined externally,
1437that is, in another source file, as a limited form of optimization
1438barrier. Specifically, the compiler assumes that any externally
1439defined function may access any statically or dynamically allocated
1440data and any local variable whose address is taken. This often means
1441that explicit barriers can be omitted. It is one reason that Pintos
1442contains few explicit barriers.
1443</P>
1444<P>
1445
1446A function defined in the same source file, or in a header included by
1447the source file, cannot be relied upon as a optimization barrier.
1448This applies even to invocation of a function before its
1449definition, because the compiler may read and parse the entire source
1450file before performing optimization.
1451</P>
1452<P>
1453
1454<A NAME="Interrupt Handling"></A>
1455<HR SIZE="6">
1456<A NAME="SEC65"></A>
1457<H2> A.4 Interrupt Handling </H2>
1458<!--docid::SEC65::-->
1459<P>
1460
1461An <EM>interrupt</EM> notifies the CPU of some event. Much of the work
1462of an operating system relates to interrupts in one way or another.
1463For our purposes, we classify interrupts into two broad categories:
1464</P>
1465<P>
1466
1467<UL>
1468<LI>
1469<EM>Internal interrupts</EM>, that is, interrupts caused directly by CPU
1470instructions. System calls, attempts at invalid memory access
1471(<EM>page faults</EM>), and attempts to divide by zero are some activities
1472that cause internal interrupts. Because they are caused by CPU
1473instructions, internal interrupts are <EM>synchronous</EM> or synchronized
1474with CPU instructions. <CODE>intr_disable()</CODE> does not disable internal
1475interrupts.
1476<P>
1477
1478</P>
1479<LI>
1480<EM>External interrupts</EM>, that is, interrupts originating outside the
1481CPU. These interrupts come from hardware devices such as the system
1482timer, keyboard, serial ports, and disks. External interrupts are
1483<EM>asynchronous</EM>, meaning that their delivery is not
1484synchronized with instruction execution. Handling of external interrupts
1485can be postponed with <CODE>intr_disable()</CODE> and related functions
1486(see section <A HREF="pintos_5.html#SEC59">A.3.1 Disabling Interrupts</A>).
1487</UL>
1488<P>
1489
1490The CPU treats both classes of interrupts largely the same way,
1491so Pintos has common infrastructure to handle both classes.
1492The following section describes this
1493common infrastructure. The sections after that give the specifics of
1494external and internal interrupts.
1495</P>
1496<P>
1497
1498If you haven't already read chapter 3, &quot;Basic Execution Environment,&quot;
1499in [ <A HREF="pintos_10.html#IA32-v1">IA32-v1</A>], it is recommended that you do so now. You might
1500also want to skim chapter 5, &quot;Interrupt and Exception Handling,&quot; in
1501[ <A HREF="pintos_10.html#IA32-v3a">IA32-v3a</A>].
1502</P>
1503<P>
1504
1505<A NAME="Interrupt Infrastructure"></A>
1506<HR SIZE="6">
1507<A NAME="SEC66"></A>
1508<H3> A.4.1 Interrupt Infrastructure </H3>
1509<!--docid::SEC66::-->
1510<P>
1511
1512When an interrupt occurs, the CPU saves
1513its most essential state on a stack and jumps to an interrupt
1514handler routine. The 80<VAR>x</VAR>86 architecture supports 256
1515interrupts, numbered 0 through 255, each with an independent
1516handler defined in an array called the <EM>interrupt
1517descriptor table</EM> or IDT.
1518</P>
1519<P>
1520
1521In Pintos, <CODE>intr_init()</CODE> in <Q><TT>threads/interrupt.c</TT></Q> sets up the
1522IDT so that each entry points to a unique entry point in
1523<Q><TT>threads/intr-stubs.S</TT></Q> named <CODE>intr<VAR>NN</VAR>_stub()</CODE>, where
1524<VAR>NN</VAR> is the interrupt number in
1525hexadecimal. Because the CPU doesn't give
1526us any other way to find out the interrupt number, this entry point
1527pushes the interrupt number on the stack. Then it jumps to
1528<CODE>intr_entry()</CODE>, which pushes all the registers that the processor
1529didn't already push for us, and then calls <CODE>intr_handler()</CODE>, which
1530brings us back into C in <Q><TT>threads/interrupt.c</TT></Q>.
1531</P>
1532<P>
1533
1534The main job of <CODE>intr_handler()</CODE> is to call the function
1535registered for handling the particular interrupt. (If no
1536function is registered, it dumps some information to the console and
1537panics.) It also does some extra processing for external
1538interrupts (see section <A HREF="pintos_5.html#SEC68">A.4.3 External Interrupt Handling</A>).
1539</P>
1540<P>
1541
1542When <CODE>intr_handler()</CODE> returns, the assembly code in
1543<Q><TT>threads/intr-stubs.S</TT></Q> restores all the CPU registers saved
1544earlier and directs the CPU to return from the interrupt.
1545</P>
1546<P>
1547
1548The following types and functions are common to all
1549interrupts.
1550</P>
1551<P>
1552
1553<A NAME="IDX60"></A>
1554</P>
1555<DL>
1556<DT><U>Type:</U> <B>void intr_handler_func (struct intr_frame *<VAR>frame</VAR>)</B>
1557<DD>This is how an interrupt handler function must be declared. Its <VAR>frame</VAR>
1558argument (see below) allows it to determine the cause of the interrupt
1559and the state of the thread that was interrupted.
1560</DL>
1561<P>
1562
1563<A NAME="IDX61"></A>
1564</P>
1565<DL>
1566<DT><U>Type:</U> <B>struct intr_frame</B>
1567<DD>The stack frame of an interrupt handler, as saved by the CPU, the interrupt
1568stubs, and <CODE>intr_entry()</CODE>. Its most interesting members are described
1569below.
1570</DL>
1571<P>
1572
1573<A NAME="IDX62"></A>
1574</P>
1575<DL>
1576<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>edi</B>
1577<DD><A NAME="IDX63"></A>
1578<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>esi</B>
1579<DD><A NAME="IDX64"></A>
1580<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>ebp</B>
1581<DD><A NAME="IDX65"></A>
1582<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>esp_dummy</B>
1583<DD><A NAME="IDX66"></A>
1584<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>ebx</B>
1585<DD><A NAME="IDX67"></A>
1586<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>edx</B>
1587<DD><A NAME="IDX68"></A>
1588<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>ecx</B>
1589<DD><A NAME="IDX69"></A>
1590<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>eax</B>
1591<DD><A NAME="IDX70"></A>
1592<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint16_t <B>es</B>
1593<DD><A NAME="IDX71"></A>
1594<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint16_t <B>ds</B>
1595<DD>Register values in the interrupted thread, pushed by <CODE>intr_entry()</CODE>.
1596The <CODE>esp_dummy</CODE> value isn't actually used (refer to the
1597description of <CODE>PUSHA</CODE> in [ <A HREF="pintos_10.html#IA32-v2b">IA32-v2b</A>] for details).
1598</DL>
1599<P>
1600
1601<A NAME="IDX72"></A>
1602</P>
1603<DL>
1604<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>vec_no</B>
1605<DD>The interrupt vector number, ranging from 0 to 255.
1606</DL>
1607<P>
1608
1609<A NAME="IDX73"></A>
1610</P>
1611<DL>
1612<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> uint32_t <B>error_code</B>
1613<DD>The &quot;error code&quot; pushed on the stack by the CPU for some internal
1614interrupts.
1615</DL>
1616<P>
1617
1618<A NAME="IDX74"></A>
1619</P>
1620<DL>
1621<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> void <B>(*eip)</B> (void)
1622<DD>The address of the next instruction to be executed by the interrupted
1623thread.
1624</DL>
1625<P>
1626
1627<A NAME="IDX75"></A>
1628</P>
1629<DL>
1630<DT><U>Member of <CODE>struct intr_frame</CODE>:</U> void *<B>esp</B>
1631<DD>The interrupted thread's stack pointer.
1632</DL>
1633<P>
1634
1635<A NAME="IDX76"></A>
1636</P>
1637<DL>
1638<DT><U>Function:</U> const char *<B>intr_name</B> (uint8_t <VAR>vec</VAR>)
1639<DD>Returns the name of the interrupt numbered <VAR>vec</VAR>, or
1640<CODE>&quot;unknown&quot;</CODE> if the interrupt has no registered name.
1641</DL>
1642<P>
1643
1644<A NAME="Internal Interrupt Handling"></A>
1645<HR SIZE="6">
1646<A NAME="SEC67"></A>
1647<H3> A.4.2 Internal Interrupt Handling </H3>
1648<!--docid::SEC67::-->
1649<P>
1650
1651Internal interrupts are caused directly by CPU instructions executed by
1652the running kernel thread or user process (from project 2 onward). An
1653internal interrupt is therefore said to arise in a &quot;process context.&quot;
1654</P>
1655<P>
1656
1657In an internal interrupt's handler, it can make sense to examine the
1658<CODE>struct intr_frame</CODE> passed to the interrupt handler, or even to modify
1659it. When the interrupt returns, modifications in <CODE>struct intr_frame</CODE>
1660become changes to the calling thread or process's state. For example,
1661the Pintos system call handler returns a value to the user program by
1662modifying the saved EAX register (see section <A HREF="pintos_2.html#SEC40">2.5.2 System Call Details</A>).
1663</P>
1664<P>
1665
1666There are no special restrictions on what an internal interrupt
1667handler can or can't do. Generally they should run with interrupts
1668enabled, just like other code, and so they can be preempted by other
1669kernel threads. Thus, they do need to synchronize with other threads
1670on shared data and other resources (see section <A HREF="pintos_5.html#SEC58">A.3 Synchronization</A>).
1671</P>
1672<P>
1673
1674Internal interrupt handlers can be invoked recursively. For example,
1675the system call handler might cause a page fault while attempting to
1676read user memory. Deep recursion would risk overflowing the limited
1677kernel stack (see section <A HREF="pintos_5.html#SEC55">A.2.1 <CODE>struct thread</CODE></A>), but should be unnecessary.
1678</P>
1679<P>
1680
1681<A NAME="IDX77"></A>
1682</P>
1683<DL>
1684<DT><U>Function:</U> void <B>intr_register_int</B> (uint8_t <VAR>vec</VAR>, int <VAR>dpl</VAR>, enum intr_level <VAR>level</VAR>, intr_handler_func *<VAR>handler</VAR>, const char *<VAR>name</VAR>)
1685<DD>Registers <VAR>handler</VAR> to be called when internal interrupt numbered
1686<VAR>vec</VAR> is triggered. Names the interrupt <VAR>name</VAR> for debugging
1687purposes.
1688<P>
1689
1690If <VAR>level</VAR> is <CODE>INTR_ON</CODE>, external interrupts will be processed
1691normally during the interrupt handler's execution, which is normally
1692desirable. Specifying <CODE>INTR_OFF</CODE> will cause the CPU to disable
1693external interrupts when it invokes the interrupt handler. The effect
1694is slightly different from calling <CODE>intr_disable()</CODE> inside the
1695handler, because that leaves a window of one or more CPU instructions in
1696which external interrupts are still enabled. This is important for the
1697page fault handler; refer to the comments in <Q><TT>userprog/exception.c</TT></Q>
1698for details.
1699</P>
1700<P>
1701
1702<VAR>dpl</VAR> determines how the interrupt can be invoked. If <VAR>dpl</VAR> is
17030, then the interrupt can be invoked only by kernel threads. Otherwise
1704<VAR>dpl</VAR> should be 3, which allows user processes to invoke the
1705interrupt with an explicit INT instruction. The value of <VAR>dpl</VAR>
1706doesn't affect user processes' ability to invoke the interrupt
1707indirectly, e.g. an invalid memory reference will cause a page fault
1708regardless of <VAR>dpl</VAR>.
1709</P>
1710</DL>
1711<P>
1712
1713<A NAME="External Interrupt Handling"></A>
1714<HR SIZE="6">
1715<A NAME="SEC68"></A>
1716<H3> A.4.3 External Interrupt Handling </H3>
1717<!--docid::SEC68::-->
1718<P>
1719
1720External interrupts are caused by events outside the CPU.
1721They are asynchronous, so they can be invoked at any time that
1722interrupts have not been disabled. We say that an external interrupt
1723runs in an &quot;interrupt context.&quot;
1724</P>
1725<P>
1726
1727In an external interrupt, the <CODE>struct intr_frame</CODE> passed to the
1728handler is not very meaningful. It describes the state of the thread
1729or process that was interrupted, but there is no way to predict which
1730one that is. It is possible, although rarely useful, to examine it, but
1731modifying it is a recipe for disaster.
1732</P>
1733<P>
1734
1735Only one external interrupt may be processed at a time. Neither
1736internal nor external interrupt may nest within an external interrupt
1737handler. Thus, an external interrupt's handler must run with interrupts
1738disabled (see section <A HREF="pintos_5.html#SEC59">A.3.1 Disabling Interrupts</A>).
1739</P>
1740<P>
1741
1742An external interrupt handler must not sleep or yield, which rules out
1743calling <CODE>lock_acquire()</CODE>, <CODE>thread_yield()</CODE>, and many other
1744functions. Sleeping in interrupt context would effectively put the
1745interrupted thread to sleep, too, until the interrupt handler was again
1746scheduled and returned. This would be unfair to the unlucky thread, and
1747it would deadlock if the handler were waiting for the sleeping thread
1748to, e.g., release a lock.
1749</P>
1750<P>
1751
1752An external interrupt handler
1753effectively monopolizes the machine and delays all other activities.
1754Therefore, external interrupt handlers should complete as quickly as
1755they can. Anything that require much CPU time should instead run in a
1756kernel thread, possibly one that the interrupt triggers using a
1757synchronization primitive.
1758</P>
1759<P>
1760
1761External interrupts are controlled by a
1762pair of devices outside the CPU called <EM>programmable interrupt
1763controllers</EM>, <EM>PICs</EM> for short. When <CODE>intr_init()</CODE> sets up the
1764CPU's IDT, it also initializes the PICs for interrupt handling. The
1765PICs also must be &quot;acknowledged&quot; at the end of processing for each
1766external interrupt. <CODE>intr_handler()</CODE> takes care of that by calling
1767<CODE>pic_end_of_interrupt()</CODE>, which properly signals the PICs.
1768</P>
1769<P>
1770
1771The following functions relate to external
1772interrupts.
1773</P>
1774<P>
1775
1776<A NAME="IDX78"></A>
1777</P>
1778<DL>
1779<DT><U>Function:</U> void <B>intr_register_ext</B> (uint8_t <VAR>vec</VAR>, intr_handler_func *<VAR>handler</VAR>, const char *<VAR>name</VAR>)
1780<DD>Registers <VAR>handler</VAR> to be called when external interrupt numbered
1781<VAR>vec</VAR> is triggered. Names the interrupt <VAR>name</VAR> for debugging
1782purposes. The handler will run with interrupts disabled.
1783</DL>
1784<P>
1785
1786<A NAME="IDX79"></A>
1787</P>
1788<DL>
1789<DT><U>Function:</U> bool <B>intr_context</B> (void)
1790<DD>Returns true if we are running in an interrupt context, otherwise
1791false. Mainly used in functions that might sleep
1792or that otherwise should not be called from interrupt context, in this
1793form:
1794<TABLE><tr><td>&nbsp;</td><td class=example><pre>ASSERT (!intr_context ());
1795</pre></td></tr></table></DL>
1796<P>
1797
1798<A NAME="IDX80"></A>
1799</P>
1800<DL>
1801<DT><U>Function:</U> void <B>intr_yield_on_return</B> (void)
1802<DD>When called in an interrupt context, causes <CODE>thread_yield()</CODE> to be
1803called just before the interrupt returns. Used
1804in the timer interrupt handler when a thread's time slice expires, to
1805cause a new thread to be scheduled.
1806</DL>
1807<P>
1808
1809<A NAME="Memory Allocation"></A>
1810<HR SIZE="6">
1811<A NAME="SEC69"></A>
1812<H2> A.5 Memory Allocation </H2>
1813<!--docid::SEC69::-->
1814<P>
1815
1816Pintos contains two memory allocators, one that allocates memory in
1817units of a page, and one that can allocate blocks of any size.
1818</P>
1819<P>
1820
1821<A NAME="Page Allocator"></A>
1822<HR SIZE="6">
1823<A NAME="SEC70"></A>
1824<H3> A.5.1 Page Allocator </H3>
1825<!--docid::SEC70::-->
1826<P>
1827
1828The page allocator declared in <Q><TT>threads/palloc.h</TT></Q> allocates
1829memory in units of a page. It is most often used to allocate memory
1830one page at a time, but it can also allocate multiple contiguous pages
1831at once.
1832</P>
1833<P>
1834
1835The page allocator divides the memory it allocates into two pools,
1836called the kernel and user pools. By default, each pool gets half of
1837system memory above 1 MB, but the division can be changed with the
1838<Q><SAMP>-ul</SAMP></Q> kernel
1839command line
1840option (see <A HREF="pintos_4.html#Why PAL_USER?">Why PAL_USER?</A>). An allocation request draws from one
1841pool or the other. If one pool becomes empty, the other may still
1842have free pages. The user pool should be used for allocating memory
1843for user processes and the kernel pool for all other allocations.
1844This will only become important starting with project 3. Until then,
1845all allocations should be made from the kernel pool.
1846</P>
1847<P>
1848
1849Each pool's usage is tracked with a bitmap, one bit per page in
1850the pool. A request to allocate <VAR>n</VAR> pages scans the bitmap
1851for <VAR>n</VAR> consecutive bits set to
1852false, indicating that those pages are free, and then sets those bits
1853to true to mark them as used. This is a &quot;first fit&quot; allocation
1854strategy (see <A HREF="pintos_10.html#Wilson">Wilson</A>).
1855</P>
1856<P>
1857
1858The page allocator is subject to fragmentation. That is, it may not
1859be possible to allocate <VAR>n</VAR> contiguous pages even though <VAR>n</VAR>
1860or more pages are free, because the free pages are separated by used
1861pages. In fact, in pathological cases it may be impossible to
1862allocate 2 contiguous pages even though half of the pool's pages are free.
1863Single-page requests can't fail due to fragmentation, so
1864requests for multiple contiguous pages should be limited as much as
1865possible.
1866</P>
1867<P>
1868
1869Pages may not be allocated from interrupt context, but they may be
1870freed.
1871</P>
1872<P>
1873
1874When a page is freed, all of its bytes are cleared to <TT>0xcc</TT>, as
1875a debugging aid (see section <A HREF="pintos_8.html#SEC108">D.8 Tips</A>).
1876</P>
1877<P>
1878
1879Page allocator types and functions are described below.
1880</P>
1881<P>
1882
1883<A NAME="IDX81"></A>
1884</P>
1885<DL>
1886<DT><U>Function:</U> void *<B>palloc_get_page</B> (enum palloc_flags <VAR>flags</VAR>)
1887<DD><A NAME="IDX82"></A>
1888<DT><U>Function:</U> void *<B>palloc_get_multiple</B> (enum palloc_flags <VAR>flags</VAR>, size_t <VAR>page_cnt</VAR>)
1889<DD>Obtains and returns one page, or <VAR>page_cnt</VAR> contiguous pages,
1890respectively. Returns a null pointer if the pages cannot be allocated.
1891<P>
1892
1893The <VAR>flags</VAR> argument may be any combination of the following flags:
1894</P>
1895<P>
1896
1897<A NAME="IDX83"></A>
1898</P>
1899<DL>
1900<DT><U>Page Allocator Flag:</U> <B><CODE>PAL_ASSERT</CODE></B>
1901<DD>If the pages cannot be allocated, panic the kernel. This is only
1902appropriate during kernel initialization. User processes
1903should never be permitted to panic the kernel.
1904</DL>
1905<P>
1906
1907<A NAME="IDX84"></A>
1908</P>
1909<DL>
1910<DT><U>Page Allocator Flag:</U> <B><CODE>PAL_ZERO</CODE></B>
1911<DD>Zero all the bytes in the allocated pages before returning them. If not
1912set, the contents of newly allocated pages are unpredictable.
1913</DL>
1914<P>
1915
1916<A NAME="IDX85"></A>
1917</P>
1918<DL>
1919<DT><U>Page Allocator Flag:</U> <B><CODE>PAL_USER</CODE></B>
1920<DD>Obtain the pages from the user pool. If not set, pages are allocated
1921from the kernel pool.
1922</DL>
1923</DL>
1924<P>
1925
1926<A NAME="IDX86"></A>
1927</P>
1928<DL>
1929<DT><U>Function:</U> void <B>palloc_free_page</B> (void *<VAR>page</VAR>)
1930<DD><A NAME="IDX87"></A>
1931<DT><U>Function:</U> void <B>palloc_free_multiple</B> (void *<VAR>pages</VAR>, size_t <VAR>page_cnt</VAR>)
1932<DD>Frees one page, or <VAR>page_cnt</VAR> contiguous pages, respectively,
1933starting at <VAR>pages</VAR>. All of the pages must have been obtained using
1934<CODE>palloc_get_page()</CODE> or <CODE>palloc_get_multiple()</CODE>.
1935</DL>
1936<P>
1937
1938<A NAME="Block Allocator"></A>
1939<HR SIZE="6">
1940<A NAME="SEC71"></A>
1941<H3> A.5.2 Block Allocator </H3>
1942<!--docid::SEC71::-->
1943<P>
1944
1945The block allocator, declared in <Q><TT>threads/malloc.h</TT></Q>, can allocate
1946blocks of any size. It is layered on top of the page allocator
1947described in the previous section. Blocks returned by the block
1948allocator are obtained from the kernel pool.
1949</P>
1950<P>
1951
1952The block allocator uses two different strategies for allocating memory.
1953The first strategy applies to blocks that are 1 kB or smaller
1954(one-fourth of the page size). These allocations are rounded up to the
1955nearest power of 2, or 16 bytes, whichever is larger. Then they are
1956grouped into a page used only for allocations of that size.
1957</P>
1958<P>
1959
1960The second strategy applies to blocks larger than 1 kB.
1961These allocations (plus a small amount of overhead) are rounded up to
1962the nearest page in size, and then the block allocator requests that
1963number of contiguous pages from the page allocator.
1964</P>
1965<P>
1966
1967In either case, the difference between the allocation requested size
1968and the actual block size is wasted. A real operating system would
1969carefully tune its allocator to minimize this waste, but this is
1970unimportant in an instructional system like Pintos.
1971</P>
1972<P>
1973
1974As long as a page can be obtained from the page allocator, small
1975allocations always succeed. Most small allocations do not require a
1976new page from the page allocator at all, because they are satisfied
1977using part of a page already allocated. However, large allocations
1978always require calling into the page allocator, and any allocation
1979that needs more than one contiguous page can fail due to fragmentation,
1980as already discussed in the previous section. Thus, you should
1981minimize the number of large allocations in your code, especially
1982those over approximately 4 kB each.
1983</P>
1984<P>
1985
1986When a block is freed, all of its bytes are cleared to <TT>0xcc</TT>, as
1987a debugging aid (see section <A HREF="pintos_8.html#SEC108">D.8 Tips</A>).
1988</P>
1989<P>
1990
1991The block allocator may not be called from interrupt context.
1992</P>
1993<P>
1994
1995The block allocator functions are described below. Their interfaces are
1996the same as the standard C library functions of the same names.
1997</P>
1998<P>
1999
2000<A NAME="IDX88"></A>
2001</P>
2002<DL>
2003<DT><U>Function:</U> void *<B>malloc</B> (size_t <VAR>size</VAR>)
2004<DD>Obtains and returns a new block, from the kernel pool, at least
2005<VAR>size</VAR> bytes long. Returns a null pointer if <VAR>size</VAR> is zero or
2006if memory is not available.
2007</DL>
2008<P>
2009
2010<A NAME="IDX89"></A>
2011</P>
2012<DL>
2013<DT><U>Function:</U> void *<B>calloc</B> (size_t <VAR>a</VAR>, size_t <VAR>b</VAR>)
2014<DD>Obtains a returns a new block, from the kernel pool, at least
2015<CODE><VAR>a</VAR> * <VAR>b</VAR></CODE> bytes long. The block's contents will be
2016cleared to zeros. Returns a null pointer if <VAR>a</VAR> or <VAR>b</VAR> is zero
2017or if insufficient memory is available.
2018</DL>
2019<P>
2020
2021<A NAME="IDX90"></A>
2022</P>
2023<DL>
2024<DT><U>Function:</U> void *<B>realloc</B> (void *<VAR>block</VAR>, size_t <VAR>new_size</VAR>)
2025<DD>Attempts to resize <VAR>block</VAR> to <VAR>new_size</VAR> bytes, possibly moving
2026it in the process. If successful, returns the new block, in which case
2027the old block must no longer be accessed. On failure, returns a null
2028pointer, and the old block remains valid.
2029<P>
2030
2031A call with <VAR>block</VAR> null is equivalent to <CODE>malloc()</CODE>. A call
2032with <VAR>new_size</VAR> zero is equivalent to <CODE>free()</CODE>.
2033</P>
2034</DL>
2035<P>
2036
2037<A NAME="IDX91"></A>
2038</P>
2039<DL>
2040<DT><U>Function:</U> void <B>free</B> (void *<VAR>block</VAR>)
2041<DD>Frees <VAR>block</VAR>, which must have been previously returned by
2042<CODE>malloc()</CODE>, <CODE>calloc()</CODE>, or <CODE>realloc()</CODE> (and not yet freed).
2043</DL>
2044<P>
2045
2046<A NAME="Virtual Addresses"></A>
2047<HR SIZE="6">
2048<A NAME="SEC72"></A>
2049<H2> A.6 Virtual Addresses </H2>
2050<!--docid::SEC72::-->
2051<P>
2052
2053A 32-bit virtual address can be divided into a 20-bit <EM>page number</EM>
2054and a 12-bit <EM>page offset</EM> (or just <EM>offset</EM>), like this:
2055</P>
2056<P>
2057
2058<TABLE><tr><td>&nbsp;</td><td class=example><pre> 31 12 11 0
2059 +-------------------+-----------+
2060 | Page Number | Offset |
2061 +-------------------+-----------+
2062 Virtual Address
2063</pre></td></tr></table><P>
2064
2065Header <Q><TT>threads/vaddr.h</TT></Q> defines these functions and macros for
2066working with virtual addresses:
2067</P>
2068<P>
2069
2070<A NAME="IDX92"></A>
2071</P>
2072<DL>
2073<DT><U>Macro:</U> <B>PGSHIFT</B>
2074<DD><A NAME="IDX93"></A>
2075<DT><U>Macro:</U> <B>PGBITS</B>
2076<DD>The bit index (0) and number of bits (12) of the offset part of a
2077virtual address, respectively.
2078</DL>
2079<P>
2080
2081<A NAME="IDX94"></A>
2082</P>
2083<DL>
2084<DT><U>Macro:</U> <B>PGMASK</B>
2085<DD>A bit mask with the bits in the page offset set to 1, the rest set to 0
2086(<TT>0xfff</TT>).
2087</DL>
2088<P>
2089
2090<A NAME="IDX95"></A>
2091</P>
2092<DL>
2093<DT><U>Macro:</U> <B>PGSIZE</B>
2094<DD>The page size in bytes (4,096).
2095</DL>
2096<P>
2097
2098<A NAME="IDX96"></A>
2099</P>
2100<DL>
2101<DT><U>Function:</U> unsigned <B>pg_ofs</B> (const void *<VAR>va</VAR>)
2102<DD>Extracts and returns the page offset in virtual address <VAR>va</VAR>.
2103</DL>
2104<P>
2105
2106<A NAME="IDX97"></A>
2107</P>
2108<DL>
2109<DT><U>Function:</U> uintptr_t <B>pg_no</B> (const void *<VAR>va</VAR>)
2110<DD>Extracts and returns the page number in virtual address <VAR>va</VAR>.
2111</DL>
2112<P>
2113
2114<A NAME="IDX98"></A>
2115</P>
2116<DL>
2117<DT><U>Function:</U> void *<B>pg_round_down</B> (const void *<VAR>va</VAR>)
2118<DD>Returns the start of the virtual page that <VAR>va</VAR> points within, that
2119is, <VAR>va</VAR> with the page offset set to 0.
2120</DL>
2121<P>
2122
2123<A NAME="IDX99"></A>
2124</P>
2125<DL>
2126<DT><U>Function:</U> void *<B>pg_round_up</B> (const void *<VAR>va</VAR>)
2127<DD>Returns <VAR>va</VAR> rounded up to the nearest page boundary.
2128</DL>
2129<P>
2130
2131Virtual memory in Pintos is divided into two regions: user virtual
2132memory and kernel virtual memory (see section <A HREF="pintos_2.html#SEC26">2.2.4 Virtual Memory Layout</A>). The
2133boundary between them is <CODE>PHYS_BASE</CODE>:
2134</P>
2135<P>
2136
2137<A NAME="IDX100"></A>
2138</P>
2139<DL>
2140<DT><U>Macro:</U> <B>PHYS_BASE</B>
2141<DD>Base address of kernel virtual memory. It defaults to <TT>0xc0000000</TT> (3
2142GB), but it may be changed to any multiple of <TT>0x10000000</TT> from
2143<TT>0x80000000</TT> to <TT>0xf0000000</TT>.
2144<P>
2145
2146User virtual memory ranges from virtual address 0 up to
2147<CODE>PHYS_BASE</CODE>. Kernel virtual memory occupies the rest of the
2148virtual address space, from <CODE>PHYS_BASE</CODE> up to 4 GB.
2149</P>
2150</DL>
2151<P>
2152
2153<A NAME="IDX101"></A>
2154</P>
2155<DL>
2156<DT><U>Function:</U> bool <B>is_user_vaddr</B> (const void *<VAR>va</VAR>)
2157<DD><A NAME="IDX102"></A>
2158<DT><U>Function:</U> bool <B>is_kernel_vaddr</B> (const void *<VAR>va</VAR>)
2159<DD>Returns true if <VAR>va</VAR> is a user or kernel virtual address,
2160respectively, false otherwise.
2161</DL>
2162<P>
2163
2164The 80<VAR>x</VAR>86 doesn't provide any way to directly access memory given
2165a physical address. This ability is often necessary in an operating
2166system kernel, so Pintos works around it by mapping kernel virtual
2167memory one-to-one to physical memory. That is, virtual address
2168<CODE>PHYS_BASE</CODE> accesses physical address 0, virtual address
2169<CODE>PHYS_BASE</CODE> + <TT>0x1234</TT> accesses physical address <TT>0x1234</TT>, and
2170so on up to the size of the machine's physical memory. Thus, adding
2171<CODE>PHYS_BASE</CODE> to a physical address obtains a kernel virtual address
2172that accesses that address; conversely, subtracting <CODE>PHYS_BASE</CODE>
2173from a kernel virtual address obtains the corresponding physical
2174address. Header <Q><TT>threads/vaddr.h</TT></Q> provides a pair of functions to
2175do these translations:
2176</P>
2177<P>
2178
2179<A NAME="IDX103"></A>
2180</P>
2181<DL>
2182<DT><U>Function:</U> void *<B>ptov</B> (uintptr_t <VAR>pa</VAR>)
2183<DD>Returns the kernel virtual address corresponding to physical address
2184<VAR>pa</VAR>, which should be between 0 and the number of bytes of physical
2185memory.
2186</DL>
2187<P>
2188
2189<A NAME="IDX104"></A>
2190</P>
2191<DL>
2192<DT><U>Function:</U> uintptr_t <B>vtop</B> (void *<VAR>va</VAR>)
2193<DD>Returns the physical address corresponding to <VAR>va</VAR>, which must be a
2194kernel virtual address.
2195</DL>
2196<P>
2197
2198<A NAME="Page Table"></A>
2199<HR SIZE="6">
2200<A NAME="SEC73"></A>
2201<H2> A.7 Page Table </H2>
2202<!--docid::SEC73::-->
2203<P>
2204
2205The code in <Q><TT>pagedir.c</TT></Q> is an abstract interface to the 80<VAR>x</VAR>86
2206hardware page table, also called a &quot;page directory&quot; by Intel processor
2207documentation. The page table interface uses a <CODE>uint32_t *</CODE> to
2208represent a page table because this is convenient for accessing their
2209internal structure.
2210</P>
2211<P>
2212
2213The sections below describe the page table interface and internals.
2214</P>
2215<P>
2216
2217<A NAME="Page Table Creation Destruction Activation"></A>
2218<HR SIZE="6">
2219<A NAME="SEC74"></A>
2220<H3> A.7.1 Creation, Destruction, and Activation </H3>
2221<!--docid::SEC74::-->
2222<P>
2223
2224These functions create, destroy, and activate page tables. The base
2225Pintos code already calls these functions where necessary, so it should
2226not be necessary to call them yourself.
2227</P>
2228<P>
2229
2230<A NAME="IDX105"></A>
2231</P>
2232<DL>
2233<DT><U>Function:</U> uint32_t *<B>pagedir_create</B> (void)
2234<DD>Creates and returns a new page table. The new page table contains
2235Pintos's normal kernel virtual page mappings, but no user virtual
2236mappings.
2237<P>
2238
2239Returns a null pointer if memory cannot be obtained.
2240</P>
2241</DL>
2242<P>
2243
2244<A NAME="IDX106"></A>
2245</P>
2246<DL>
2247<DT><U>Function:</U> void <B>pagedir_destroy</B> (uint32_t *<VAR>pd</VAR>)
2248<DD>Frees all of the resources held by <VAR>pd</VAR>, including the page table
2249itself and the frames that it maps.
2250</DL>
2251<P>
2252
2253<A NAME="IDX107"></A>
2254</P>
2255<DL>
2256<DT><U>Function:</U> void <B>pagedir_activate</B> (uint32_t *<VAR>pd</VAR>)
2257<DD>Activates <VAR>pd</VAR>. The active page table is the one used by the CPU to
2258translate memory references.
2259</DL>
2260<P>
2261
2262<A NAME="Page Tables Inspection and Updates"></A>
2263<HR SIZE="6">
2264<A NAME="SEC75"></A>
2265<H3> A.7.2 Inspection and Updates </H3>
2266<!--docid::SEC75::-->
2267<P>
2268
2269These functions examine or update the mappings from pages to frames
2270encapsulated by a page table. They work on both active and inactive
2271page tables (that is, those for running and suspended processes),
2272flushing the TLB as necessary.
2273</P>
2274<P>
2275
2276<A NAME="IDX108"></A>
2277</P>
2278<DL>
2279<DT><U>Function:</U> bool <B>pagedir_set_page</B> (uint32_t *<VAR>pd</VAR>, void *<VAR>upage</VAR>, void *<VAR>kpage</VAR>, bool <VAR>writable</VAR>)
2280<DD>Adds to <VAR>pd</VAR> a mapping from user page <VAR>upage</VAR> to the frame identified
2281by kernel virtual address <VAR>kpage</VAR>. If <VAR>writable</VAR> is true, the
2282page is mapped read/write; otherwise, it is mapped read-only.
2283<P>
2284
2285User page <VAR>upage</VAR> must not already be mapped in <VAR>pd</VAR>.
2286</P>
2287<P>
2288
2289Kernel page <VAR>kpage</VAR> should be a kernel virtual address obtained from
2290the user pool with <CODE>palloc_get_page(PAL_USER)</CODE> (see <A HREF="pintos_4.html#Why PAL_USER?">Why PAL_USER?</A>).
2291</P>
2292<P>
2293
2294Returns true if successful, false on failure. Failure will occur if
2295additional memory required for the page table cannot be obtained.
2296</P>
2297</DL>
2298<P>
2299
2300<A NAME="IDX109"></A>
2301</P>
2302<DL>
2303<DT><U>Function:</U> void *<B>pagedir_get_page</B> (uint32_t *<VAR>pd</VAR>, const void *<VAR>uaddr</VAR>)
2304<DD>Looks up the frame mapped to <VAR>uaddr</VAR> in <VAR>pd</VAR>. Returns the
2305kernel virtual address for that frame, if <VAR>uaddr</VAR> is mapped, or a
2306null pointer if it is not.
2307</DL>
2308<P>
2309
2310<A NAME="IDX110"></A>
2311</P>
2312<DL>
2313<DT><U>Function:</U> void <B>pagedir_clear_page</B> (uint32_t *<VAR>pd</VAR>, void *<VAR>page</VAR>)
2314<DD>Marks <VAR>page</VAR> &quot;not present&quot; in <VAR>pd</VAR>. Later accesses to
2315the page will fault.
2316<P>
2317
2318Other bits in the page table for <VAR>page</VAR> are preserved, permitting
2319the accessed and dirty bits (see the next section) to be checked.
2320</P>
2321<P>
2322
2323This function has no effect if <VAR>page</VAR> is not mapped.
2324</P>
2325</DL>
2326<P>
2327
2328<A NAME="Page Table Accessed and Dirty Bits"></A>
2329<HR SIZE="6">
2330<A NAME="SEC76"></A>
2331<H3> A.7.3 Accessed and Dirty Bits </H3>
2332<!--docid::SEC76::-->
2333<P>
2334
233580<VAR>x</VAR>86 hardware provides some assistance for implementing page
2336replacement algorithms, through a pair of bits in the page table entry
2337(PTE) for each page. On any read or write to a page, the CPU sets the
2338<EM>accessed bit</EM> to 1 in the page's PTE, and on any write, the CPU
2339sets the <EM>dirty bit</EM> to 1. The CPU never resets these bits to 0,
2340but the OS may do so.
2341</P>
2342<P>
2343
2344Proper interpretation of these bits requires understanding of
2345<EM>aliases</EM>, that is, two (or more) pages that refer to the same
2346frame. When an aliased frame is accessed, the accessed and dirty bits
2347are updated in only one page table entry (the one for the page used for
2348access). The accessed and dirty bits for the other aliases are not
2349updated.
2350</P>
2351<P>
2352
2353See <A HREF="pintos_4.html#Accessed and Dirty Bits">Accessed and Dirty Bits</A>, on applying these bits in implementing
2354page replacement algorithms.
2355</P>
2356<P>
2357
2358<A NAME="IDX111"></A>
2359</P>
2360<DL>
2361<DT><U>Function:</U> bool <B>pagedir_is_dirty</B> (uint32_t *<VAR>pd</VAR>, const void *<VAR>page</VAR>)
2362<DD><A NAME="IDX112"></A>
2363<DT><U>Function:</U> bool <B>pagedir_is_accessed</B> (uint32_t *<VAR>pd</VAR>, const void *<VAR>page</VAR>)
2364<DD>Returns true if page directory <VAR>pd</VAR> contains a page table entry for
2365<VAR>page</VAR> that is marked dirty (or accessed). Otherwise,
2366returns false.
2367</DL>
2368<P>
2369
2370<A NAME="IDX113"></A>
2371</P>
2372<DL>
2373<DT><U>Function:</U> void <B>pagedir_set_dirty</B> (uint32_t *<VAR>pd</VAR>, const void *<VAR>page</VAR>, bool <VAR>value</VAR>)
2374<DD><A NAME="IDX114"></A>
2375<DT><U>Function:</U> void <B>pagedir_set_accessed</B> (uint32_t *<VAR>pd</VAR>, const void *<VAR>page</VAR>, bool <VAR>value</VAR>)
2376<DD>If page directory <VAR>pd</VAR> has a page table entry for <VAR>page</VAR>, then
2377its dirty (or accessed) bit is set to <VAR>value</VAR>.
2378</DL>
2379<P>
2380
2381<A NAME="Page Table Details"></A>
2382<HR SIZE="6">
2383<A NAME="SEC77"></A>
2384<H3> A.7.4 Page Table Details </H3>
2385<!--docid::SEC77::-->
2386<P>
2387
2388The functions provided with Pintos are sufficient to implement the
2389projects. However, you may still find it worthwhile to understand the
2390hardware page table format, so we'll go into a little detail in this
2391section.
2392</P>
2393<P>
2394
2395<A NAME="Page Table Structure"></A>
2396<HR SIZE="6">
2397<A NAME="SEC78"></A>
2398<H4> A.7.4.1 Structure </H4>
2399<!--docid::SEC78::-->
2400<P>
2401
2402The top-level paging data structure is a page called the &quot;page
2403directory&quot; (PD) arranged as an array of 1,024 32-bit page directory
2404entries (PDEs), each of which represents 4 MB of virtual memory. Each
2405PDE may point to the physical address of another page called a
2406&quot;page table&quot; (PT) arranged, similarly, as an array of 1,024
240732-bit page table entries (PTEs), each of which translates a single 4
2408kB virtual page to a physical page.
2409</P>
2410<P>
2411
2412Translation of a virtual address into a physical address follows
2413the three-step process illustrated in the diagram
2414below:<A NAME="DOCF4" HREF="pintos_fot.html#FOOT4">(4)</A>
2415</P>
2416<P>
2417
2418<OL>
2419<LI>
2420The most-significant 10 bits of the virtual address (bits 22<small>...</small>31)
2421index the page directory. If the PDE is marked &quot;present,&quot; the
2422physical address of a page table is read from the PDE thus obtained.
2423If the PDE is marked &quot;not present&quot; then a page fault occurs.
2424<P>
2425
2426</P>
2427<LI>
2428The next 10 bits of the virtual address (bits 12<small>...</small>21) index
2429the page table. If the PTE is marked &quot;present,&quot; the physical
2430address of a data page is read from the PTE thus obtained. If the PTE
2431is marked &quot;not present&quot; then a page fault occurs.
2432<P>
2433
2434</P>
2435<LI>
2436The least-significant 12 bits of the virtual address (bits 0<small>...</small>11)
2437are added to the data page's physical base address, yielding the final
2438physical address.
2439</OL>
2440<P>
2441
2442<TABLE><tr><td>&nbsp;</td><td class=example><pre> 31 22 21 12 11 0
2443+----------------------+----------------------+----------------------+
2444| Page Directory Index | Page Table Index | Page Offset |
2445+----------------------+----------------------+----------------------+
2446 | | |
2447 _______/ _______/ _____/
2448 / / /
2449 / Page Directory / Page Table / Data Page
2450 / .____________. / .____________. / .____________.
2451 |1,023|____________| |1,023|____________| | |____________|
2452 |1,022|____________| |1,022|____________| | |____________|
2453 |1,021|____________| |1,021|____________| \__\|____________|
2454 |1,020|____________| |1,020|____________| /|____________|
2455 | | | | | | | |
2456 | | | \____\| |_ | |
2457 | | . | /| . | \ | . |
2458 \____\| . |_ | . | | | . |
2459 /| . | \ | . | | | . |
2460 | . | | | . | | | . |
2461 | | | | | | | |
2462 |____________| | |____________| | |____________|
2463 4|____________| | 4|____________| | |____________|
2464 3|____________| | 3|____________| | |____________|
2465 2|____________| | 2|____________| | |____________|
2466 1|____________| | 1|____________| | |____________|
2467 0|____________| \__\0|____________| \____\|____________|
2468 / /
2469</pre></td></tr></table><P>
2470
2471Pintos provides some macros and functions that are useful for working
2472with raw page tables:
2473</P>
2474<P>
2475
2476<A NAME="IDX115"></A>
2477</P>
2478<DL>
2479<DT><U>Macro:</U> <B>PTSHIFT</B>
2480<DD><A NAME="IDX116"></A>
2481<DT><U>Macro:</U> <B>PTBITS</B>
2482<DD>The starting bit index (12) and number of bits (10), respectively, in a
2483page table index.
2484</DL>
2485<P>
2486
2487<A NAME="IDX117"></A>
2488</P>
2489<DL>
2490<DT><U>Macro:</U> <B>PTMASK</B>
2491<DD>A bit mask with the bits in the page table index set to 1 and the rest
2492set to 0 (<TT>0x3ff000</TT>).
2493</DL>
2494<P>
2495
2496<A NAME="IDX118"></A>
2497</P>
2498<DL>
2499<DT><U>Macro:</U> <B>PTSPAN</B>
2500<DD>The number of bytes of virtual address space that a single page table
2501page covers (4,194,304 bytes, or 4 MB).
2502</DL>
2503<P>
2504
2505<A NAME="IDX119"></A>
2506</P>
2507<DL>
2508<DT><U>Macro:</U> <B>PDSHIFT</B>
2509<DD><A NAME="IDX120"></A>
2510<DT><U>Macro:</U> <B>PDBITS</B>
2511<DD>The starting bit index (22) and number of bits (10), respectively, in a
2512page directory index.
2513</DL>
2514<P>
2515
2516<A NAME="IDX121"></A>
2517</P>
2518<DL>
2519<DT><U>Macro:</U> <B>PDMASK</B>
2520<DD>A bit mask with the bits in the page directory index set to 1 and other
2521bits set to 0 (<TT>0xffc00000</TT>).
2522</DL>
2523<P>
2524
2525<A NAME="IDX122"></A>
2526</P>
2527<DL>
2528<DT><U>Function:</U> uintptr_t <B>pd_no</B> (const void *<VAR>va</VAR>)
2529<DD><A NAME="IDX123"></A>
2530<DT><U>Function:</U> uintptr_t <B>pt_no</B> (const void *<VAR>va</VAR>)
2531<DD>Returns the page directory index or page table index, respectively, for
2532virtual address <VAR>va</VAR>. These functions are defined in
2533<Q><TT>threads/pte.h</TT></Q>.
2534</DL>
2535<P>
2536
2537<A NAME="IDX124"></A>
2538</P>
2539<DL>
2540<DT><U>Function:</U> unsigned <B>pg_ofs</B> (const void *<VAR>va</VAR>)
2541<DD>Returns the page offset for virtual address <VAR>va</VAR>. This function is
2542defined in <Q><TT>threads/vaddr.h</TT></Q>.
2543</DL>
2544<P>
2545
2546<A NAME="Page Table Entry Format"></A>
2547<HR SIZE="6">
2548<A NAME="SEC79"></A>
2549<H4> A.7.4.2 Page Table Entry Format </H4>
2550<!--docid::SEC79::-->
2551<P>
2552
2553You do not need to understand the PTE format to do the Pintos
2554projects, unless you wish to incorporate the page table into your
2555supplemental page table (see <A HREF="pintos_4.html#Managing the Supplemental Page Table">Managing the Supplemental Page Table</A>).
2556</P>
2557<P>
2558
2559The actual format of a page table entry is summarized below. For
2560complete information, refer to section 3.7, &quot;Page Translation Using
256132-Bit Physical Addressing,&quot; in [ <A HREF="pintos_10.html#IA32-v3a">IA32-v3a</A>].
2562</P>
2563<P>
2564
2565<TABLE><tr><td>&nbsp;</td><td class=example><pre> 31 12 11 9 6 5 2 1 0
2566+---------------------------------------+----+----+-+-+---+-+-+-+
2567| Physical Address | AVL| |D|A| |U|W|P|
2568+---------------------------------------+----+----+-+-+---+-+-+-+
2569</pre></td></tr></table><P>
2570
2571Some more information on each bit is given below. The names are
2572<Q><TT>threads/pte.h</TT></Q> macros that represent the bits' values:
2573</P>
2574<P>
2575
2576<A NAME="IDX125"></A>
2577</P>
2578<DL>
2579<DT><U>Macro:</U> <B>PTE_P</B>
2580<DD>Bit 0, the &quot;present&quot; bit. When this bit is 1, the
2581other bits are interpreted as described below. When this bit is 0, any
2582attempt to access the page will page fault. The remaining bits are then
2583not used by the CPU and may be used by the OS for any purpose.
2584</DL>
2585<P>
2586
2587<A NAME="IDX126"></A>
2588</P>
2589<DL>
2590<DT><U>Macro:</U> <B>PTE_W</B>
2591<DD>Bit 1, the &quot;read/write&quot; bit. When it is 1, the page
2592is writable. When it is 0, write attempts will page fault.
2593</DL>
2594<P>
2595
2596<A NAME="IDX127"></A>
2597</P>
2598<DL>
2599<DT><U>Macro:</U> <B>PTE_U</B>
2600<DD>Bit 2, the &quot;user/supervisor&quot; bit. When it is 1, user
2601processes may access the page. When it is 0, only the kernel may access
2602the page (user accesses will page fault).
2603<P>
2604
2605Pintos clears this bit in PTEs for kernel virtual memory, to prevent
2606user processes from accessing them.
2607</P>
2608</DL>
2609<P>
2610
2611<A NAME="IDX128"></A>
2612</P>
2613<DL>
2614<DT><U>Macro:</U> <B>PTE_A</B>
2615<DD>Bit 5, the &quot;accessed&quot; bit. See section <A HREF="pintos_5.html#SEC76">A.7.3 Accessed and Dirty Bits</A>.
2616</DL>
2617<P>
2618
2619<A NAME="IDX129"></A>
2620</P>
2621<DL>
2622<DT><U>Macro:</U> <B>PTE_D</B>
2623<DD>Bit 6, the &quot;dirty&quot; bit. See section <A HREF="pintos_5.html#SEC76">A.7.3 Accessed and Dirty Bits</A>.
2624</DL>
2625<P>
2626
2627<A NAME="IDX130"></A>
2628</P>
2629<DL>
2630<DT><U>Macro:</U> <B>PTE_AVL</B>
2631<DD>Bits 9<small>...</small>11, available for operating system use.
2632Pintos, as provided, does not use them and sets them to 0.
2633</DL>
2634<P>
2635
2636<A NAME="IDX131"></A>
2637</P>
2638<DL>
2639<DT><U>Macro:</U> <B>PTE_ADDR</B>
2640<DD>Bits 12<small>...</small>31, the top 20 bits of the physical address of a frame.
2641The low 12 bits of the frame's address are always 0.
2642</DL>
2643<P>
2644
2645Other bits are either reserved or uninteresting in a Pintos context and
2646should be set to@tie{}0.
2647</P>
2648<P>
2649
2650Header <Q><TT>threads/pte.h</TT></Q> defines three functions for working with
2651page table entries:
2652</P>
2653<P>
2654
2655<A NAME="IDX132"></A>
2656</P>
2657<DL>
2658<DT><U>Function:</U> uint32_t <B>pte_create_kernel</B> (uint32_t *<VAR>page</VAR>, bool <VAR>writable</VAR>)
2659<DD>Returns a page table entry that points to <VAR>page</VAR>, which should be a
2660kernel virtual address. The PTE's present bit will be set. It will be
2661marked for kernel-only access. If <VAR>writable</VAR> is true, the PTE will
2662also be marked read/write; otherwise, it will be read-only.
2663</DL>
2664<P>
2665
2666<A NAME="IDX133"></A>
2667</P>
2668<DL>
2669<DT><U>Function:</U> uint32_t <B>pte_create_user</B> (uint32_t *<VAR>page</VAR>, bool <VAR>writable</VAR>)
2670<DD>Returns a page table entry that points to <VAR>page</VAR>, which should be
2671the kernel virtual address of a frame in the user pool (see <A HREF="pintos_4.html#Why PAL_USER?">Why PAL_USER?</A>). The PTE's present bit will be set and it will be marked to
2672allow user-mode access. If <VAR>writable</VAR> is true, the PTE will also be
2673marked read/write; otherwise, it will be read-only.
2674</DL>
2675<P>
2676
2677<A NAME="IDX134"></A>
2678</P>
2679<DL>
2680<DT><U>Function:</U> void *<B>pte_get_page</B> (uint32_t <VAR>pte</VAR>)
2681<DD>Returns the kernel virtual address for the frame that <VAR>pte</VAR> points
2682to. The <VAR>pte</VAR> may be present or not-present; if it is not-present
2683then the pointer returned is only meaningful if the address bits in the PTE
2684actually represent a physical address.
2685</DL>
2686<P>
2687
2688<A NAME="Page Directory Entry Format"></A>
2689<HR SIZE="6">
2690<A NAME="SEC80"></A>
2691<H4> A.7.4.3 Page Directory Entry Format </H4>
2692<!--docid::SEC80::-->
2693<P>
2694
2695Page directory entries have the same format as PTEs, except that the
2696physical address points to a page table page instead of a frame. Header
2697<Q><TT>threads/pte.h</TT></Q> defines two functions for working with page
2698directory entries:
2699</P>
2700<P>
2701
2702<A NAME="IDX135"></A>
2703</P>
2704<DL>
2705<DT><U>Function:</U> uint32_t <B>pde_create</B> (uint32_t *<VAR>pt</VAR>)
2706<DD>Returns a page directory that points to <VAR>page</VAR>, which should be the
2707kernel virtual address of a page table page. The PDE's present bit will
2708be set, it will be marked to allow user-mode access, and it will be
2709marked read/write.
2710</DL>
2711<P>
2712
2713<A NAME="IDX136"></A>
2714</P>
2715<DL>
2716<DT><U>Function:</U> uint32_t *<B>pde_get_pt</B> (uint32_t <VAR>pde</VAR>)
2717<DD>Returns the kernel virtual address for the page table page that
2718<VAR>pde</VAR>, which must be marked present, points to.
2719</DL>
2720<P>
2721
2722<A NAME="Hash Table"></A>
2723<HR SIZE="6">
2724<A NAME="SEC81"></A>
2725<H2> A.8 Hash Table </H2>
2726<!--docid::SEC81::-->
2727<P>
2728
2729Pintos provides a hash table data structure in <Q><TT>lib/kernel/hash.c</TT></Q>.
2730To use it you will need to include its header file,
2731<Q><TT>lib/kernel/hash.h</TT></Q>, with <CODE>#include &lt;hash.h&gt;</CODE>.
2732No code provided with Pintos uses the hash table, which means that you
2733are free to use it as is, modify its implementation for your own
2734purposes, or ignore it, as you wish.
2735</P>
2736<P>
2737
2738Most implementations of the virtual memory project use a hash table to
2739translate pages to frames. You may find other uses for hash tables as
2740well.
2741</P>
2742<P>
2743
2744<A NAME="Hash Data Types"></A>
2745<HR SIZE="6">
2746<A NAME="SEC82"></A>
2747<H3> A.8.1 Data Types </H3>
2748<!--docid::SEC82::-->
2749<P>
2750
2751A hash table is represented by <CODE>struct hash</CODE>.
2752</P>
2753<P>
2754
2755<A NAME="IDX137"></A>
2756</P>
2757<DL>
2758<DT><U>Type:</U> <B>struct hash</B>
2759<DD>Represents an entire hash table. The actual members of <CODE>struct hash</CODE>
2760are &quot;opaque.&quot; That is, code that uses a hash table should not access
2761<CODE>struct hash</CODE> members directly, nor should it need to. Instead, use
2762hash table functions and macros.
2763</DL>
2764<P>
2765
2766The hash table operates on elements of type <CODE>struct hash_elem</CODE>.
2767</P>
2768<P>
2769
2770<A NAME="IDX138"></A>
2771</P>
2772<DL>
2773<DT><U>Type:</U> <B>struct hash_elem</B>
2774<DD>Embed a <CODE>struct hash_elem</CODE> member in the structure you want to include
2775in a hash table. Like <CODE>struct hash</CODE>, <CODE>struct hash_elem</CODE> is opaque.
2776All functions for operating on hash table elements actually take and
2777return pointers to <CODE>struct hash_elem</CODE>, not pointers to your hash table's
2778real element type.
2779</DL>
2780<P>
2781
2782You will often need to obtain a <CODE>struct hash_elem</CODE> given a real element
2783of the hash table, and vice versa. Given a real element of the hash
2784table, you may use the <Q><SAMP>&amp;</SAMP></Q> operator to obtain a pointer to its
2785<CODE>struct hash_elem</CODE>. Use the <CODE>hash_entry()</CODE> macro to go the other
2786direction.
2787</P>
2788<P>
2789
2790<A NAME="IDX139"></A>
2791</P>
2792<DL>
2793<DT><U>Macro:</U> <VAR>type</VAR> *<B>hash_entry</B> (struct hash_elem *<VAR>elem</VAR>, <VAR>type</VAR>, <VAR>member</VAR>)
2794<DD>Returns a pointer to the structure that <VAR>elem</VAR>, a pointer to a
2795<CODE>struct hash_elem</CODE>, is embedded within. You must provide <VAR>type</VAR>,
2796the name of the structure that <VAR>elem</VAR> is inside, and <VAR>member</VAR>,
2797the name of the member in <VAR>type</VAR> that <VAR>elem</VAR> points to.
2798<P>
2799
2800For example, suppose <CODE>h</CODE> is a <CODE>struct hash_elem *</CODE> variable
2801that points to a <CODE>struct thread</CODE> member (of type <CODE>struct hash_elem</CODE>)
2802named <CODE>h_elem</CODE>. Then, <CODE>hash_entry@tie{</CODE>(h, struct thread, h_elem)}
2803yields the address of the <CODE>struct thread</CODE> that <CODE>h</CODE> points within.
2804</P>
2805</DL>
2806<P>
2807
2808See section <A HREF="pintos_5.html#SEC86">A.8.5 Hash Table Example</A>, for an example.
2809</P>
2810<P>
2811
2812Each hash table element must contain a key, that is, data that
2813identifies and distinguishes elements, which must be unique
2814among elements in the hash table. (Elements may
2815also contain non-key data that need not be unique.) While an element is
2816in a hash table, its key data must not be changed. Instead, if need be,
2817remove the element from the hash table, modify its key, then reinsert
2818the element.
2819</P>
2820<P>
2821
2822For each hash table, you must write two functions that act on keys: a
2823hash function and a comparison function. These functions must match the
2824following prototypes:
2825</P>
2826<P>
2827
2828<A NAME="IDX140"></A>
2829</P>
2830<DL>
2831<DT><U>Type:</U> <B>unsigned hash_hash_func (const struct hash_elem *<VAR>element</VAR>, void *<VAR>aux</VAR>)</B>
2832<DD>Returns a hash of <VAR>element</VAR>'s data, as a value anywhere in the range
2833of <CODE>unsigned int</CODE>. The hash of an element should be a
2834pseudo-random function of the element's key. It must not depend on
2835non-key data in the element or on any non-constant data other than the
2836key. Pintos provides the following functions as a suitable basis for
2837hash functions.
2838<P>
2839
2840<A NAME="IDX141"></A>
2841</P>
2842<DL>
2843<DT><U>Function:</U> unsigned <B>hash_bytes</B> (const void *<VAR>buf</VAR>, size_t *<VAR>size</VAR>)
2844<DD>Returns a hash of the <VAR>size</VAR> bytes starting at <VAR>buf</VAR>. The
2845implementation is the general-purpose
2846<A HREF="http://en.wikipedia.org/wiki/Fowler_Noll_Vo_hash">Fowler-Noll-Vo
2847hash</A> for 32-bit words.
2848</DL>
2849<P>
2850
2851<A NAME="IDX142"></A>
2852</P>
2853<DL>
2854<DT><U>Function:</U> unsigned <B>hash_string</B> (const char *<VAR>s</VAR>)
2855<DD>Returns a hash of null-terminated string <VAR>s</VAR>.
2856</DL>
2857<P>
2858
2859<A NAME="IDX143"></A>
2860</P>
2861<DL>
2862<DT><U>Function:</U> unsigned <B>hash_int</B> (int <VAR>i</VAR>)
2863<DD>Returns a hash of integer <VAR>i</VAR>.
2864</DL>
2865<P>
2866
2867If your key is a single piece of data of an appropriate type, it is
2868sensible for your hash function to directly return the output of one of
2869these functions. For multiple pieces of data, you may wish to combine
2870the output of more than one call to them using, e.g., the <Q><SAMP>^</SAMP></Q>
2871(exclusive or)
2872operator. Finally, you may entirely ignore these functions and write
2873your own hash function from scratch, but remember that your goal is to
2874build an operating system kernel, not to design a hash function.
2875</P>
2876<P>
2877
2878See section <A HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>, for an explanation of <VAR>aux</VAR>.
2879</P>
2880</DL>
2881<P>
2882
2883<A NAME="IDX144"></A>
2884</P>
2885<DL>
2886<DT><U>Type:</U> <B>bool hash_less_func (const struct hash_elem *<VAR>a</VAR>, const struct hash_elem *<VAR>b</VAR>, void *<VAR>aux</VAR>)</B>
2887<DD>Compares the keys stored in elements <VAR>a</VAR> and <VAR>b</VAR>. Returns
2888true if <VAR>a</VAR> is less than <VAR>b</VAR>, false if <VAR>a</VAR> is greater than
2889or equal to <VAR>b</VAR>.
2890<P>
2891
2892If two elements compare equal, then they must hash to equal values.
2893</P>
2894<P>
2895
2896See section <A HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>, for an explanation of <VAR>aux</VAR>.
2897</P>
2898</DL>
2899<P>
2900
2901See section <A HREF="pintos_5.html#SEC86">A.8.5 Hash Table Example</A>, for hash and comparison function examples.
2902</P>
2903<P>
2904
2905A few functions accept a pointer to a third kind of
2906function as an argument:
2907</P>
2908<P>
2909
2910<A NAME="IDX145"></A>
2911</P>
2912<DL>
2913<DT><U>Type:</U> <B>void hash_action_func (struct hash_elem *<VAR>element</VAR>, void *<VAR>aux</VAR>)</B>
2914<DD>Performs some kind of action, chosen by the caller, on <VAR>element</VAR>.
2915<P>
2916
2917See section <A HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>, for an explanation of <VAR>aux</VAR>.
2918</P>
2919</DL>
2920<P>
2921
2922<A NAME="Basic Hash Functions"></A>
2923<HR SIZE="6">
2924<A NAME="SEC83"></A>
2925<H3> A.8.2 Basic Functions </H3>
2926<!--docid::SEC83::-->
2927<P>
2928
2929These functions create, destroy, and inspect hash tables.
2930</P>
2931<P>
2932
2933<A NAME="IDX146"></A>
2934</P>
2935<DL>
2936<DT><U>Function:</U> bool <B>hash_init</B> (struct hash *<VAR>hash</VAR>, hash_hash_func *<VAR>hash_func</VAR>, hash_less_func *<VAR>less_func</VAR>, void *<VAR>aux</VAR>)
2937<DD>Initializes <VAR>hash</VAR> as a hash table with <VAR>hash_func</VAR> as hash
2938function, <VAR>less_func</VAR> as comparison function, and <VAR>aux</VAR> as
2939auxiliary data.
2940Returns true if successful, false on failure. <CODE>hash_init()</CODE> calls
2941<CODE>malloc()</CODE> and fails if memory cannot be allocated.
2942<P>
2943
2944See section <A HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>, for an explanation of <VAR>aux</VAR>, which is
2945most often a null pointer.
2946</P>
2947</DL>
2948<P>
2949
2950<A NAME="IDX147"></A>
2951</P>
2952<DL>
2953<DT><U>Function:</U> void <B>hash_clear</B> (struct hash *<VAR>hash</VAR>, hash_action_func *<VAR>action</VAR>)
2954<DD>Removes all the elements from <VAR>hash</VAR>, which must have been
2955previously initialized with <CODE>hash_init()</CODE>.
2956<P>
2957
2958If <VAR>action</VAR> is non-null, then it is called once for each element in
2959the hash table, which gives the caller an opportunity to deallocate any
2960memory or other resources used by the element. For example, if the hash
2961table elements are dynamically allocated using <CODE>malloc()</CODE>, then
2962<VAR>action</VAR> could <CODE>free()</CODE> the element. This is safe because
2963<CODE>hash_clear()</CODE> will not access the memory in a given hash element
2964after calling <VAR>action</VAR> on it. However, <VAR>action</VAR> must not call
2965any function that may modify the hash table, such as <CODE>hash_insert()</CODE>
2966or <CODE>hash_delete()</CODE>.
2967</P>
2968</DL>
2969<P>
2970
2971<A NAME="IDX148"></A>
2972</P>
2973<DL>
2974<DT><U>Function:</U> void <B>hash_destroy</B> (struct hash *<VAR>hash</VAR>, hash_action_func *<VAR>action</VAR>)
2975<DD>If <VAR>action</VAR> is non-null, calls it for each element in the hash, with
2976the same semantics as a call to <CODE>hash_clear()</CODE>. Then, frees the
2977memory held by <VAR>hash</VAR>. Afterward, <VAR>hash</VAR> must not be passed to
2978any hash table function, absent an intervening call to <CODE>hash_init()</CODE>.
2979</DL>
2980<P>
2981
2982<A NAME="IDX149"></A>
2983</P>
2984<DL>
2985<DT><U>Function:</U> size_t <B>hash_size</B> (struct hash *<VAR>hash</VAR>)
2986<DD>Returns the number of elements currently stored in <VAR>hash</VAR>.
2987</DL>
2988<P>
2989
2990<A NAME="IDX150"></A>
2991</P>
2992<DL>
2993<DT><U>Function:</U> bool <B>hash_empty</B> (struct hash *<VAR>hash</VAR>)
2994<DD>Returns true if <VAR>hash</VAR> currently contains no elements,
2995false if <VAR>hash</VAR> contains at least one element.
2996</DL>
2997<P>
2998
2999<A NAME="Hash Search Functions"></A>
3000<HR SIZE="6">
3001<A NAME="SEC84"></A>
3002<H3> A.8.3 Search Functions </H3>
3003<!--docid::SEC84::-->
3004<P>
3005
3006Each of these functions searches a hash table for an element that
3007compares equal to one provided. Based on the success of the search,
3008they perform some action, such as inserting a new element into the hash
3009table, or simply return the result of the search.
3010</P>
3011<P>
3012
3013<A NAME="IDX151"></A>
3014</P>
3015<DL>
3016<DT><U>Function:</U> struct hash_elem *<B>hash_insert</B> (struct hash *<VAR>hash</VAR>, struct hash_elem *<VAR>element</VAR>)
3017<DD>Searches <VAR>hash</VAR> for an element equal to <VAR>element</VAR>. If none is
3018found, inserts <VAR>element</VAR> into <VAR>hash</VAR> and returns a null pointer.
3019If the table already contains an element equal to <VAR>element</VAR>, it is
3020returned without modifying <VAR>hash</VAR>.
3021</DL>
3022<P>
3023
3024<A NAME="IDX152"></A>
3025</P>
3026<DL>
3027<DT><U>Function:</U> struct hash_elem *<B>hash_replace</B> (struct hash *<VAR>hash</VAR>, struct hash_elem *<VAR>element</VAR>)
3028<DD>Inserts <VAR>element</VAR> into <VAR>hash</VAR>. Any element equal to
3029<VAR>element</VAR> already in <VAR>hash</VAR> is removed. Returns the element
3030removed, or a null pointer if <VAR>hash</VAR> did not contain an element
3031equal to <VAR>element</VAR>.
3032<P>
3033
3034The caller is responsible for deallocating any resources associated with
3035the returned element, as appropriate. For example, if the hash table
3036elements are dynamically allocated using <CODE>malloc()</CODE>, then the caller
3037must <CODE>free()</CODE> the element after it is no longer needed.
3038</P>
3039</DL>
3040<P>
3041
3042The element passed to the following functions is only used for hashing
3043and comparison purposes. It is never actually inserted into the hash
3044table. Thus, only key data in the element needs to be initialized, and
3045other data in the element will not be used. It often makes sense to
3046declare an instance of the element type as a local variable, initialize
3047the key data, and then pass the address of its <CODE>struct hash_elem</CODE> to
3048<CODE>hash_find()</CODE> or <CODE>hash_delete()</CODE>. See section <A HREF="pintos_5.html#SEC86">A.8.5 Hash Table Example</A>, for
3049an example. (Large structures should not be
3050allocated as local variables. See section <A HREF="pintos_5.html#SEC55">A.2.1 <CODE>struct thread</CODE></A>, for more
3051information.)
3052</P>
3053<P>
3054
3055<A NAME="IDX153"></A>
3056</P>
3057<DL>
3058<DT><U>Function:</U> struct hash_elem *<B>hash_find</B> (struct hash *<VAR>hash</VAR>, struct hash_elem *<VAR>element</VAR>)
3059<DD>Searches <VAR>hash</VAR> for an element equal to <VAR>element</VAR>. Returns the
3060element found, if any, or a null pointer otherwise.
3061</DL>
3062<P>
3063
3064<A NAME="IDX154"></A>
3065</P>
3066<DL>
3067<DT><U>Function:</U> struct hash_elem *<B>hash_delete</B> (struct hash *<VAR>hash</VAR>, struct hash_elem *<VAR>element</VAR>)
3068<DD>Searches <VAR>hash</VAR> for an element equal to <VAR>element</VAR>. If one is
3069found, it is removed from <VAR>hash</VAR> and returned. Otherwise, a null
3070pointer is returned and <VAR>hash</VAR> is unchanged.
3071<P>
3072
3073The caller is responsible for deallocating any resources associated with
3074the returned element, as appropriate. For example, if the hash table
3075elements are dynamically allocated using <CODE>malloc()</CODE>, then the caller
3076must <CODE>free()</CODE> the element after it is no longer needed.
3077</P>
3078</DL>
3079<P>
3080
3081<A NAME="Hash Iteration Functions"></A>
3082<HR SIZE="6">
3083<A NAME="SEC85"></A>
3084<H3> A.8.4 Iteration Functions </H3>
3085<!--docid::SEC85::-->
3086<P>
3087
3088These functions allow iterating through the elements in a hash table.
3089Two interfaces are supplied. The first requires writing and supplying a
3090<VAR>hash_action_func</VAR> to act on each element (see section <A HREF="pintos_5.html#SEC82">A.8.1 Data Types</A>).
3091</P>
3092<P>
3093
3094<A NAME="IDX155"></A>
3095</P>
3096<DL>
3097<DT><U>Function:</U> void <B>hash_apply</B> (struct hash *<VAR>hash</VAR>, hash_action_func *<VAR>action</VAR>)
3098<DD>Calls <VAR>action</VAR> once for each element in <VAR>hash</VAR>, in arbitrary
3099order. <VAR>action</VAR> must not call any function that may modify the hash
3100table, such as <CODE>hash_insert()</CODE> or <CODE>hash_delete()</CODE>. <VAR>action</VAR>
3101must not modify key data in elements, although it may modify any other
3102data.
3103</DL>
3104<P>
3105
3106The second interface is based on an &quot;iterator&quot; data type.
3107Idiomatically, iterators are used as follows:
3108</P>
3109<P>
3110
3111<TABLE><tr><td>&nbsp;</td><td class=example><pre>struct hash_iterator i;
3112
3113hash_first (&amp;i, h);
3114while (hash_next (&amp;i))
3115 {
3116 struct foo *f = hash_entry (hash_cur (&amp;i), struct foo, elem);
3117 <small>...</small>do something with <I>f</I><small>...</small>
3118 }
3119</pre></td></tr></table><P>
3120
3121<A NAME="IDX156"></A>
3122</P>
3123<DL>
3124<DT><U>Type:</U> <B>struct hash_iterator</B>
3125<DD>Represents a position within a hash table. Calling any function that
3126may modify a hash table, such as <CODE>hash_insert()</CODE> or
3127<CODE>hash_delete()</CODE>, invalidates all iterators within that hash table.
3128<P>
3129
3130Like <CODE>struct hash</CODE> and <CODE>struct hash_elem</CODE>, <CODE>struct hash_elem</CODE> is opaque.
3131</P>
3132</DL>
3133<P>
3134
3135<A NAME="IDX157"></A>
3136</P>
3137<DL>
3138<DT><U>Function:</U> void <B>hash_first</B> (struct hash_iterator *<VAR>iterator</VAR>, struct hash *<VAR>hash</VAR>)
3139<DD>Initializes <VAR>iterator</VAR> to just before the first element in
3140<VAR>hash</VAR>.
3141</DL>
3142<P>
3143
3144<A NAME="IDX158"></A>
3145</P>
3146<DL>
3147<DT><U>Function:</U> struct hash_elem *<B>hash_next</B> (struct hash_iterator *<VAR>iterator</VAR>)
3148<DD>Advances <VAR>iterator</VAR> to the next element in <VAR>hash</VAR>, and returns
3149that element. Returns a null pointer if no elements remain. After
3150<CODE>hash_next()</CODE> returns null for <VAR>iterator</VAR>, calling it again
3151yields undefined behavior.
3152</DL>
3153<P>
3154
3155<A NAME="IDX159"></A>
3156</P>
3157<DL>
3158<DT><U>Function:</U> struct hash_elem *<B>hash_cur</B> (struct hash_iterator *<VAR>iterator</VAR>)
3159<DD>Returns the value most recently returned by <CODE>hash_next()</CODE> for
3160<VAR>iterator</VAR>. Yields undefined behavior after <CODE>hash_first()</CODE> has
3161been called on <VAR>iterator</VAR> but before <CODE>hash_next()</CODE> has been
3162called for the first time.
3163</DL>
3164<P>
3165
3166<A NAME="Hash Table Example"></A>
3167<HR SIZE="6">
3168<A NAME="SEC86"></A>
3169<H3> A.8.5 Hash Table Example </H3>
3170<!--docid::SEC86::-->
3171<P>
3172
3173Suppose you have a structure, called <CODE>struct page</CODE>, that you
3174want to put into a hash table. First, define <CODE>struct page</CODE> to include a
3175<CODE>struct hash_elem</CODE> member:
3176</P>
3177<P>
3178
3179<TABLE><tr><td>&nbsp;</td><td class=example><pre>struct page
3180 {
3181 struct hash_elem hash_elem; /* Hash table element. */
3182 void *addr; /* Virtual address. */
3183 /* <small>...</small>other members<small>...</small> */
3184 };
3185</pre></td></tr></table><P>
3186
3187We write a hash function and a comparison function using <VAR>addr</VAR> as
3188the key. A pointer can be hashed based on its bytes, and the <Q><SAMP>&lt;</SAMP></Q>
3189operator works fine for comparing pointers:
3190</P>
3191<P>
3192
3193<TABLE><tr><td>&nbsp;</td><td class=example><pre>/* Returns a hash value for page <VAR>p</VAR>. */
3194unsigned
3195page_hash (const struct hash_elem *p_, void *aux UNUSED)
3196{
3197 const struct page *p = hash_entry (p_, struct page, hash_elem);
3198 return hash_bytes (&amp;p-&gt;addr, sizeof p-&gt;addr);
3199}
3200
3201/* Returns true if page <VAR>a</VAR> precedes page <VAR>b</VAR>. */
3202bool
3203page_less (const struct hash_elem *a_, const struct hash_elem *b_,
3204 void *aux UNUSED)
3205{
3206 const struct page *a = hash_entry (a_, struct page, hash_elem);
3207 const struct page *b = hash_entry (b_, struct page, hash_elem);
3208
3209 return a-&gt;addr &lt; b-&gt;addr;
3210}
3211</pre></td></tr></table><P>
3212
3213(The use of <CODE>UNUSED</CODE> in these functions' prototypes suppresses a
3214warning that <VAR>aux</VAR> is unused. See section <A HREF="pintos_8.html#SEC99">D.3 Function and Parameter Attributes</A>, for information about <CODE>UNUSED</CODE>. See section <A HREF="pintos_5.html#SEC87">A.8.6 Auxiliary Data</A>, for an explanation of <VAR>aux</VAR>.)
3215</P>
3216<P>
3217
3218Then, we can create a hash table like this:
3219</P>
3220<P>
3221
3222<TABLE><tr><td>&nbsp;</td><td class=example><pre>struct hash pages;
3223
3224hash_init (&amp;pages, page_hash, page_less, NULL);
3225</pre></td></tr></table><P>
3226
3227Now we can manipulate the hash table we've created. If <CODE><VAR>p</VAR></CODE>
3228is a pointer to a <CODE>struct page</CODE>, we can insert it into the hash table
3229with:
3230</P>
3231<P>
3232
3233<TABLE><tr><td>&nbsp;</td><td class=example><pre>hash_insert (&amp;pages, &amp;p-&gt;hash_elem);
3234</pre></td></tr></table><P>
3235
3236If there's a chance that <VAR>pages</VAR> might already contain a
3237page with the same <VAR>addr</VAR>, then we should check <CODE>hash_insert()</CODE>'s
3238return value.
3239</P>
3240<P>
3241
3242To search for an element in the hash table, use <CODE>hash_find()</CODE>. This
3243takes a little setup, because <CODE>hash_find()</CODE> takes an element to
3244compare against. Here's a function that will find and return a page
3245based on a virtual address, assuming that <VAR>pages</VAR> is defined at file
3246scope:
3247</P>
3248<P>
3249
3250<TABLE><tr><td>&nbsp;</td><td class=example><pre>/* Returns the page containing the given virtual <VAR>address</VAR>,
3251 or a null pointer if no such page exists. */
3252struct page *
3253page_lookup (const void *address)
3254{
3255 struct page p;
3256 struct hash_elem *e;
3257
3258 p.addr = address;
3259 e = hash_find (&amp;pages, &amp;p.hash_elem);
3260 return e != NULL ? hash_entry (e, struct page, hash_elem) : NULL;
3261}
3262</pre></td></tr></table><P>
3263
3264<CODE>struct page</CODE> is allocated as a local variable here on the assumption
3265that it is fairly small. Large structures should not be allocated as
3266local variables. See section <A HREF="pintos_5.html#SEC55">A.2.1 <CODE>struct thread</CODE></A>, for more information.
3267</P>
3268<P>
3269
3270A similar function could delete a page by address using
3271<CODE>hash_delete()</CODE>.
3272</P>
3273<P>
3274
3275<A NAME="Hash Auxiliary Data"></A>
3276<HR SIZE="6">
3277<A NAME="SEC87"></A>
3278<H3> A.8.6 Auxiliary Data </H3>
3279<!--docid::SEC87::-->
3280<P>
3281
3282In simple cases like the example above, there's no need for the
3283<VAR>aux</VAR> parameters. In these cases, just pass a null pointer to
3284<CODE>hash_init()</CODE> for <VAR>aux</VAR> and ignore the values passed to the hash
3285function and comparison functions. (You'll get a compiler warning if
3286you don't use the <VAR>aux</VAR> parameter, but you can turn that off with
3287the <CODE>UNUSED</CODE> macro, as shown in the example, or you can just ignore
3288it.)
3289</P>
3290<P>
3291
3292<VAR>aux</VAR> is useful when you have some property of the data in the
3293hash table is both constant and needed for hashing or comparison,
3294but not stored in the data items themselves. For example, if
3295the items in a hash table are fixed-length strings, but the items
3296themselves don't indicate what that fixed length is, you could pass
3297the length as an <VAR>aux</VAR> parameter.
3298</P>
3299<P>
3300
3301<A NAME="Hash Synchronization"></A>
3302<HR SIZE="6">
3303<A NAME="SEC88"></A>
3304<H3> A.8.7 Synchronization </H3>
3305<!--docid::SEC88::-->
3306<P>
3307
3308The hash table does not do any internal synchronization. It is the
3309caller's responsibility to synchronize calls to hash table functions.
3310In general, any number of functions that examine but do not modify the
3311hash table, such as <CODE>hash_find()</CODE> or <CODE>hash_next()</CODE>, may execute
3312simultaneously. However, these function cannot safely execute at the
3313same time as any function that may modify a given hash table, such as
3314<CODE>hash_insert()</CODE> or <CODE>hash_delete()</CODE>, nor may more than one function
3315that can modify a given hash table execute safely at once.
3316</P>
3317<P>
3318
3319It is also the caller's responsibility to synchronize access to data in
3320hash table elements. How to synchronize access to this data depends on
3321how it is designed and organized, as with any other data structure.
3322</P>
3323<P>
3324
3325<A NAME="Coding Standards"></A>
3326<HR SIZE="6">
3327<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
3328<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_5.html#SEC48"> &lt;&lt; </A>]</TD>
3329<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_6.html#SEC89"> &gt;&gt; </A>]</TD>
3330<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
3331<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
3332<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
3333<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
3334</TR></TABLE>
3335<BR>
3336<FONT SIZE="-1">
3337This document was generated
3338by on <I>March, 6 2012</I>
3339using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
3340</FONT>
3341
3342</BODY>
3343</HTML>
diff --git a/doc/pintos_6.html b/doc/pintos_6.html
new file mode 100644
index 0000000..afe7d8a
--- /dev/null
+++ b/doc/pintos_6.html
@@ -0,0 +1,314 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Coding Standards</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Coding Standards">
18<META NAME="keywords" CONTENT="Pintos Projects: Coding Standards">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC89"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_5.html#SEC48"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_7.html#SEC93"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> B. Coding Standards </H1>
39<!--docid::SEC89::-->
40<P>
41
42TODO: TUW coding standards
43We expect you to be
44familiar with some set of coding standards such as
45<A HREF="http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf">CS 107 Coding Standards</A>. Even if you've taken 107, we recommend
46reviewing that document. We expect code at the &quot;Peer-Review Quality&quot;
47level described there.
48</P>
49<P>
50
51Our standards for coding are most important for grading. We want to
52stress that aside from the fact that we are explicitly basing part of
53your grade on these things, good coding practices will improve the
54quality of your code. This makes it easier for your partners to
55interact with it, and ultimately, will improve your chances of having a
56good working program. That said once, the rest of this document will
57discuss only the ways in which our coding standards will affect our
58grading.
59</P>
60<P>
61
62<A NAME="Coding Style"></A>
63<HR SIZE="6">
64<A NAME="SEC90"></A>
65<H2> B.1 Style </H2>
66<!--docid::SEC90::-->
67<P>
68
69Style, for the purposes of our grading, refers to how readable your
70code is. At minimum, this means that your code is well formatted, your
71variable names are descriptive and your functions are decomposed and
72well commented. Any other factors which make it hard (or easy) for us
73to read or use your code will be reflected in your style grade.
74</P>
75<P>
76
77The existing Pintos code is written in the GNU style and largely
78follows the <A HREF="http://www.gnu.org/prep/standards_toc.html">GNU
79Coding Standards</A>. We encourage you to follow the applicable parts of
80them too, especially chapter 5, &quot;Making the Best Use of C.&quot; Using a
81different style won't cause actual problems, but it's ugly to see
82gratuitous differences in style from one function to another. If your
83code is too ugly, it will cost you points.
84</P>
85<P>
86
87Please limit C source file lines to at most 79 characters long.
88</P>
89<P>
90
91Pintos comments sometimes refer to external standards or
92specifications by writing a name inside square brackets, like this:
93<CODE>[IA32-v3a]</CODE>. These names refer to the reference names used in
94this documentation (see section <A HREF="pintos_10.html#SEC113">Bibliography</A>).
95</P>
96<P>
97
98If you remove existing Pintos code, please delete it from your source
99file entirely. Don't just put it into a comment or a conditional
100compilation directive, because that makes the resulting code hard to
101read.
102</P>
103<P>
104
105We're only going to do a compile in the directory for the project being
106submitted. You don't need to make sure that the previous projects also
107compile.
108</P>
109<P>
110
111Project code should be written so that all of the subproblems for the
112project function together, that is, without the need to rebuild with
113different macros defined, etc. If you do extra credit work that
114changes normal Pintos behavior so as to interfere with grading, then
115you must implement it so that it only acts that way when given a
116special command-line option of the form <Q><SAMP>-<VAR>name</VAR></SAMP></Q>, where
117<VAR>name</VAR> is a name of your choice. You can add such an option by
118modifying <CODE>parse_options()</CODE> in <Q><TT>threads/init.c</TT></Q>.
119</P>
120<P>
121
122The introduction describes additional coding style requirements
123(see section <A HREF="pintos_1.html#SEC9">1.2.2 Design</A>).
124</P>
125<P>
126
127<A NAME="C99"></A>
128<HR SIZE="6">
129<A NAME="SEC91"></A>
130<H2> B.2 C99 </H2>
131<!--docid::SEC91::-->
132<P>
133
134The Pintos source code uses a few features of the &quot;C99&quot; standard
135library that were not in the original 1989 standard for C. Many
136programmers are unaware of these feature, so we will describe them. The
137new features used in Pintos are
138mostly in new headers:
139</P>
140<P>
141
142</P>
143<DL COMPACT>
144<DT><Q><TT>&lt;stdbool.h&gt;</TT></Q>
145<DD>Defines macros <CODE>bool</CODE>, a 1-bit type that takes on only the values
1460 and 1, <CODE>true</CODE>, which expands to 1, and <CODE>false</CODE>, which
147expands to 0.
148<P>
149
150</P>
151<DT><Q><TT>&lt;stdint.h&gt;</TT></Q>
152<DD>On systems that support them, this header defines types
153<CODE>int<VAR>n</VAR>_t</CODE> and <CODE>uint<VAR>n</VAR>_t</CODE> for <VAR>n</VAR> = 8, 16, 32,
15464, and possibly other values. These are 2's complement signed and unsigned
155types, respectively, with the given number of bits.
156<P>
157
158On systems where it is possible, this header also defines types
159<CODE>intptr_t</CODE> and <CODE>uintptr_t</CODE>, which are integer types big
160enough to hold a pointer.
161</P>
162<P>
163
164On all systems, this header defines types <CODE>intmax_t</CODE> and
165<CODE>uintmax_t</CODE>, which are the system's signed and unsigned integer
166types with the widest ranges.
167</P>
168<P>
169
170For every signed integer type <CODE><VAR>type</VAR>_t</CODE> defined here, as well
171as for <CODE>ptrdiff_t</CODE> defined in <Q><TT>&lt;stddef.h&gt;</TT></Q>, this header also
172defines macros <CODE><VAR>TYPE</VAR>_MAX</CODE> and <CODE><VAR>TYPE</VAR>_MIN</CODE> that
173give the type's range. Similarly, for every unsigned integer type
174<CODE><VAR>type</VAR>_t</CODE> defined here, as well as for <CODE>size_t</CODE> defined
175in <Q><TT>&lt;stddef.h&gt;</TT></Q>, this header defines a <CODE><VAR>TYPE</VAR>_MAX</CODE>
176macro giving its maximum value.
177</P>
178<P>
179
180</P>
181<DT><Q><TT>&lt;inttypes.h&gt;</TT></Q>
182<DD><Q><TT>&lt;stdint.h&gt;</TT></Q> provides no straightforward way to format
183the types it defines with <CODE>printf()</CODE> and related functions. This
184header provides macros to help with that. For every
185<CODE>int<VAR>n</VAR>_t</CODE> defined by <Q><TT>&lt;stdint.h&gt;</TT></Q>, it provides macros
186<CODE>PRId<VAR>n</VAR></CODE> and <CODE>PRIi<VAR>n</VAR></CODE> for formatting values of
187that type with <CODE>&quot;%d&quot;</CODE> and <CODE>&quot;%i&quot;</CODE>. Similarly, for every
188<CODE>uint<VAR>n</VAR>_t</CODE>, it provides <CODE>PRIo<VAR>n</VAR></CODE>,
189<CODE>PRIu<VAR>n</VAR></CODE>, <CODE>PRIu<VAR>x</VAR></CODE>, and <CODE>PRIu<VAR>X</VAR></CODE>.
190<P>
191
192You use these something like this, taking advantage of the fact that
193the C compiler concatenates adjacent string literals:
194<TABLE><tr><td>&nbsp;</td><td class=example><pre>#include &lt;inttypes.h&gt;
195<small>...</small>
196int32_t value = <small>...</small>;
197printf (&quot;value=%08&quot;PRId32&quot;\n&quot;, value);
198</pre></td></tr></table>The <Q><SAMP>%</SAMP></Q> is not supplied by the <CODE>PRI</CODE> macros. As shown
199above, you supply it yourself and follow it by any flags, field
200width, etc.
201<P>
202
203</P>
204<DT><Q><TT>&lt;stdio.h&gt;</TT></Q>
205<DD>The <CODE>printf()</CODE> function has some new type modifiers for printing
206standard types:
207<P>
208
209</P>
210<DL COMPACT>
211<DT><Q><SAMP>j</SAMP></Q>
212<DD>For <CODE>intmax_t</CODE> (e.g. <Q><SAMP>%jd</SAMP></Q>) or <CODE>uintmax_t</CODE> (e.g.
213<Q><SAMP>%ju</SAMP></Q>).
214<P>
215
216</P>
217<DT><Q><SAMP>z</SAMP></Q>
218<DD>For <CODE>size_t</CODE> (e.g. <Q><SAMP>%zu</SAMP></Q>).
219<P>
220
221</P>
222<DT><Q><SAMP>t</SAMP></Q>
223<DD>For <CODE>ptrdiff_t</CODE> (e.g. <Q><SAMP>%td</SAMP></Q>).
224</DL>
225<P>
226
227Pintos <CODE>printf()</CODE> also implements a nonstandard <Q><SAMP>'</SAMP></Q> flag that
228groups large numbers with commas to make them easier to read.
229</DL>
230<P>
231
232<A NAME="Unsafe String Functions"></A>
233<HR SIZE="6">
234<A NAME="SEC92"></A>
235<H2> B.3 Unsafe String Functions </H2>
236<!--docid::SEC92::-->
237<P>
238
239A few of the string functions declared in the standard
240<Q><TT>&lt;string.h&gt;</TT></Q> and <Q><TT>&lt;stdio.h&gt;</TT></Q> headers are notoriously unsafe.
241The worst offenders are intentionally not included in the Pintos C
242library:
243</P>
244<P>
245
246</P>
247<DL COMPACT>
248<DT><CODE>strcpy</CODE>
249<DD>When used carelessly this function can overflow the buffer reserved
250for its output string. Use <CODE>strlcpy()</CODE> instead. Refer to
251comments in its source code in <CODE>lib/string.c</CODE> for documentation.
252<P>
253
254</P>
255<DT><CODE>strncpy</CODE>
256<DD>This function can leave its destination buffer without a null string
257terminator. It also has performance problems. Again, use
258<CODE>strlcpy()</CODE>.
259<P>
260
261</P>
262<DT><CODE>strcat</CODE>
263<DD>Same issue as <CODE>strcpy()</CODE>. Use <CODE>strlcat()</CODE> instead.
264Again, refer to comments in its source code in <CODE>lib/string.c</CODE> for
265documentation.
266<P>
267
268</P>
269<DT><CODE>strncat</CODE>
270<DD>The meaning of its buffer size argument is surprising.
271Again, use <CODE>strlcat()</CODE>.
272<P>
273
274</P>
275<DT><CODE>strtok</CODE>
276<DD>Uses global data, so it is unsafe in threaded programs such as
277kernels. Use <CODE>strtok_r()</CODE> instead, and see its source code in
278<CODE>lib/string.c</CODE> for documentation and an example.
279<P>
280
281</P>
282<DT><CODE>sprintf</CODE>
283<DD>Same issue as <CODE>strcpy()</CODE>. Use <CODE>snprintf()</CODE> instead. Refer
284to comments in <CODE>lib/stdio.h</CODE> for documentation.
285<P>
286
287</P>
288<DT><CODE>vsprintf</CODE>
289<DD>Same issue as <CODE>strcpy()</CODE>. Use <CODE>vsnprintf()</CODE> instead.
290</DL>
291<P>
292
293If you try to use any of these functions, the error message will give
294you a hint by referring to an identifier like
295<CODE>dont_use_sprintf_use_snprintf</CODE>.
296<A NAME="Project Documentation"></A>
297<HR SIZE="6">
298<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
299<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_6.html#SEC89"> &lt;&lt; </A>]</TD>
300<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_7.html#SEC93"> &gt;&gt; </A>]</TD>
301<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
302<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
303<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
304<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
305</TR></TABLE>
306<BR>
307<FONT SIZE="-1">
308This document was generated
309by on <I>March, 6 2012</I>
310using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
311</FONT>
312
313</BODY>
314</HTML>
diff --git a/doc/pintos_7.html b/doc/pintos_7.html
new file mode 100644
index 0000000..e7ac7b5
--- /dev/null
+++ b/doc/pintos_7.html
@@ -0,0 +1,238 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Project Documentation</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Project Documentation">
18<META NAME="keywords" CONTENT="Pintos Projects: Project Documentation">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC93"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_6.html#SEC89"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_8.html#SEC96"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> C. Project Documentation </H1>
39<!--docid::SEC93::-->
40<P>
41
42This chapter presents a sample assignment and a filled-in design
43document for one possible implementation. Its purpose is to give you an
44idea of what we expect to see in your own design documents.
45</P>
46<P>
47
48<A NAME="Sample Assignment"></A>
49<HR SIZE="6">
50<A NAME="SEC94"></A>
51<H2> C.1 Sample Assignment </H2>
52<!--docid::SEC94::-->
53<P>
54
55Implement <CODE>thread_join()</CODE>.
56</P>
57<P>
58
59<A NAME="IDX160"></A>
60</P>
61<DL>
62<DT><U>Function:</U> void <B>thread_join</B> (tid_t <VAR>tid</VAR>)
63<DD>Blocks the current thread until thread <VAR>tid</VAR> exits. If <VAR>A</VAR> is
64the running thread and <VAR>B</VAR> is the argument, then we say that
65&quot;<VAR>A</VAR> joins <VAR>B</VAR>.&quot;
66<P>
67
68Incidentally, the argument is a thread id, instead of a thread pointer,
69because a thread pointer is not unique over time. That is, when a
70thread dies, its memory may be, whether immediately or much later,
71reused for another thread. If thread <VAR>A</VAR> over time had two children
72<VAR>B</VAR> and <VAR>C</VAR> that were stored at the same address, then
73<CODE>thread_join(<VAR>B</VAR>)</CODE> and <CODE>thread_join(<VAR>C</VAR>)</CODE> would be
74ambiguous.
75</P>
76<P>
77
78A thread may only join its immediate children. Calling
79<CODE>thread_join()</CODE> on a thread that is not the caller's child should
80cause the caller to return immediately. Children are not &quot;inherited,&quot;
81that is, if <VAR>A</VAR> has child <VAR>B</VAR> and <VAR>B</VAR> has child <VAR>C</VAR>,
82then <VAR>A</VAR> always returns immediately should it try to join <VAR>C</VAR>,
83even if <VAR>B</VAR> is dead.
84</P>
85<P>
86
87A thread need not ever be joined. Your solution should properly free
88all of a thread's resources, including its <CODE>struct thread</CODE>,
89whether it is ever joined or not, and regardless of whether the child
90exits before or after its parent. That is, a thread should be freed
91exactly once in all cases.
92</P>
93<P>
94
95Joining a given thread is idempotent. That is, joining a thread
96multiple times is equivalent to joining it once, because it has already
97exited at the time of the later joins. Thus, joins on a given thread
98after the first should return immediately.
99</P>
100<P>
101
102You must handle all the ways a join can occur: nested joins (<VAR>A</VAR>
103joins <VAR>B</VAR>, then <VAR>B</VAR> joins <VAR>C</VAR>), multiple joins (<VAR>A</VAR>
104joins <VAR>B</VAR>, then <VAR>A</VAR> joins <VAR>C</VAR>), and so on.
105</P>
106</DL>
107<P>
108
109<A NAME="Sample Design Document"></A>
110<HR SIZE="6">
111<A NAME="SEC95"></A>
112<H2> C.2 Sample Design Document </H2>
113<!--docid::SEC95::-->
114<P>
115
116<TABLE><tr><td>&nbsp;</td><td class=example><pre>
117 +-----------------+
118 | CS 140 |
119 | SAMPLE PROJECT |
120 | DESIGN DOCUMENT |
121 +-----------------+
122
123---- GROUP ----
124
125Ben Pfaff &lt;blp@stanford.edu&gt;
126
127---- PRELIMINARIES ----
128
129&gt;&gt; If you have any preliminary comments on your submission, notes for
130&gt;&gt; the TAs, or extra credit, please give them here.
131
132(This is a sample design document.)
133
134&gt;&gt; Please cite any offline or online sources you consulted while
135&gt;&gt; preparing your submission, other than the Pintos documentation,
136&gt;&gt; course text, and lecture notes.
137
138None.
139
140 JOIN
141 ====
142
143---- DATA STRUCTURES ----
144
145&gt;&gt; Copy here the declaration of each new or changed `struct' or `struct'
146&gt;&gt; member, global or static variable, `typedef', or enumeration.
147&gt;&gt; Identify the purpose of each in 25 words or less.
148
149A &quot;latch&quot; is a new synchronization primitive. Acquires block
150until the first release. Afterward, all ongoing and future
151acquires pass immediately.
152
153 /* Latch. */
154 struct latch
155 {
156 bool released; /* Released yet? */
157 struct lock monitor_lock; /* Monitor lock. */
158 struct condition rel_cond; /* Signaled when released. */
159 };
160
161Added to struct thread:
162
163 /* Members for implementing thread_join(). */
164 struct latch ready_to_die; /* Release when thread about to die. */
165 struct semaphore can_die; /* Up when thread allowed to die. */
166 struct list children; /* List of child threads. */
167 list_elem children_elem; /* Element of `children' list. */
168
169---- ALGORITHMS ----
170
171&gt;&gt; Briefly describe your implementation of thread_join() and how it
172&gt;&gt; interacts with thread termination.
173
174thread_join() finds the joined child on the thread's list of
175children and waits for the child to exit by acquiring the child's
176ready_to_die latch. When thread_exit() is called, the thread
177releases its ready_to_die latch, allowing the parent to continue.
178
179---- SYNCHRONIZATION ----
180
181&gt;&gt; Consider parent thread P with child thread C. How do you ensure
182&gt;&gt; proper synchronization and avoid race conditions when P calls wait(C)
183&gt;&gt; before C exits? After C exits? How do you ensure that all resources
184&gt;&gt; are freed in each case? How about when P terminates without waiting,
185&gt;&gt; before C exits? After C exits? Are there any special cases?
186
187C waits in thread_exit() for P to die before it finishes its own
188exit, using the can_die semaphore &quot;down&quot;ed by C and &quot;up&quot;ed by P as
189it exits. Regardless of whether whether C has terminated, there
190is no race on wait(C), because C waits for P's permission before
191it frees itself.
192
193Regardless of whether P waits for C, P still &quot;up&quot;s C's can_die
194semaphore when P dies, so C will always be freed. (However,
195freeing C's resources is delayed until P's death.)
196
197The initial thread is a special case because it has no parent to
198wait for it or to &quot;up&quot; its can_die semaphore. Therefore, its
199can_die semaphore is initialized to 1.
200
201---- RATIONALE ----
202
203&gt;&gt; Critique your design, pointing out advantages and disadvantages in
204&gt;&gt; your design choices.
205
206This design has the advantage of simplicity. Encapsulating most
207of the synchronization logic into a new &quot;latch&quot; structure
208abstracts what little complexity there is into a separate layer,
209making the design easier to reason about. Also, all the new data
210members are in `struct thread', with no need for any extra dynamic
211allocation, etc., that would require extra management code.
212
213On the other hand, this design is wasteful in that a child thread
214cannot free itself before its parent has terminated. A parent
215thread that creates a large number of short-lived child threads
216could unnecessarily exhaust kernel memory. This is probably
217acceptable for implementing kernel threads, but it may be a bad
218idea for use with user processes because of the larger number of
219resources that user processes tend to own.
220</pre></td></tr></table><A NAME="Debugging Tools"></A>
221<HR SIZE="6">
222<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
223<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_7.html#SEC93"> &lt;&lt; </A>]</TD>
224<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_8.html#SEC96"> &gt;&gt; </A>]</TD>
225<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
226<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
227<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
228<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
229</TR></TABLE>
230<BR>
231<FONT SIZE="-1">
232This document was generated
233by on <I>March, 6 2012</I>
234using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
235</FONT>
236
237</BODY>
238</HTML>
diff --git a/doc/pintos_8.html b/doc/pintos_8.html
new file mode 100644
index 0000000..e354458
--- /dev/null
+++ b/doc/pintos_8.html
@@ -0,0 +1,1041 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Debugging Tools</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Debugging Tools">
18<META NAME="keywords" CONTENT="Pintos Projects: Debugging Tools">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC96"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_7.html#SEC93"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_9.html#SEC109"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> D. Debugging Tools </H1>
39<!--docid::SEC96::-->
40<P>
41
42Many tools lie at your disposal for debugging Pintos. This appendix
43introduces you to a few of them.
44</P>
45<P>
46
47<A NAME="printf"></A>
48<HR SIZE="6">
49<A NAME="SEC97"></A>
50<H2> D.1 <CODE>printf()</CODE> </H2>
51<!--docid::SEC97::-->
52<P>
53
54Don't underestimate the value of <CODE>printf()</CODE>. The way
55<CODE>printf()</CODE> is implemented in Pintos, you can call it from
56practically anywhere in the kernel, whether it's in a kernel thread or
57an interrupt handler, almost regardless of what locks are held.
58</P>
59<P>
60
61<CODE>printf()</CODE> is useful for more than just examining data.
62It can also help figure out when and where something goes wrong, even
63when the kernel crashes or panics without a useful error message. The
64strategy is to sprinkle calls to <CODE>printf()</CODE> with different strings
65(e.g. <CODE>&quot;&lt;1&gt;&quot;</CODE>, <CODE>&quot;&lt;2&gt;&quot;</CODE>, <small>...</small>) throughout the pieces of
66code you suspect are failing. If you don't even see <CODE>&lt;1&gt;</CODE> printed,
67then something bad happened before that point, if you see <CODE>&lt;1&gt;</CODE>
68but not <CODE>&lt;2&gt;</CODE>, then something bad happened between those two
69points, and so on. Based on what you learn, you can then insert more
70<CODE>printf()</CODE> calls in the new, smaller region of code you suspect.
71Eventually you can narrow the problem down to a single statement.
72See section <A HREF="pintos_8.html#SEC106">D.6 Triple Faults</A>, for a related technique.
73</P>
74<P>
75
76<A NAME="ASSERT"></A>
77<HR SIZE="6">
78<A NAME="SEC98"></A>
79<H2> D.2 <CODE>ASSERT</CODE> </H2>
80<!--docid::SEC98::-->
81<P>
82
83Assertions are useful because they can catch problems early, before
84they'd otherwise be noticed. Ideally, each function should begin with a
85set of assertions that check its arguments for validity. (Initializers
86for functions' local variables are evaluated before assertions are
87checked, so be careful not to assume that an argument is valid in an
88initializer.) You can also sprinkle assertions throughout the body of
89functions in places where you suspect things are likely to go wrong.
90They are especially useful for checking loop invariants.
91</P>
92<P>
93
94Pintos provides the <CODE>ASSERT</CODE> macro, defined in <Q><TT>&lt;debug.h&gt;</TT></Q>,
95for checking assertions.
96</P>
97<P>
98
99<A NAME="IDX161"></A>
100</P>
101<DL>
102<DT><U>Macro:</U> <B>ASSERT</B> <I>(expression)</I>
103<DD>Tests the value of <VAR>expression</VAR>. If it evaluates to zero (false),
104the kernel panics. The panic message includes the expression that
105failed, its file and line number, and a backtrace, which should help you
106to find the problem. See section <A HREF="pintos_8.html#SEC100">D.4 Backtraces</A>, for more information.
107</DL>
108<P>
109
110<A NAME="Function and Parameter Attributes"></A>
111<HR SIZE="6">
112<A NAME="SEC99"></A>
113<H2> D.3 Function and Parameter Attributes </H2>
114<!--docid::SEC99::-->
115<P>
116
117These macros defined in <Q><TT>&lt;debug.h&gt;</TT></Q> tell the compiler special
118attributes of a function or function parameter. Their expansions are
119GCC-specific.
120</P>
121<P>
122
123<A NAME="IDX162"></A>
124</P>
125<DL>
126<DT><U>Macro:</U> <B>UNUSED</B>
127<DD>Appended to a function parameter to tell the compiler that the
128parameter might not be used within the function. It suppresses the
129warning that would otherwise appear.
130</DL>
131<P>
132
133<A NAME="IDX163"></A>
134</P>
135<DL>
136<DT><U>Macro:</U> <B>NO_RETURN</B>
137<DD>Appended to a function prototype to tell the compiler that the
138function never returns. It allows the compiler to fine-tune its
139warnings and its code generation.
140</DL>
141<P>
142
143<A NAME="IDX164"></A>
144</P>
145<DL>
146<DT><U>Macro:</U> <B>NO_INLINE</B>
147<DD>Appended to a function prototype to tell the compiler to never emit
148the function in-line. Occasionally useful to improve the quality of
149backtraces (see below).
150</DL>
151<P>
152
153<A NAME="IDX165"></A>
154</P>
155<DL>
156<DT><U>Macro:</U> <B>PRINTF_FORMAT</B> <I>(<VAR>format</VAR>, <VAR>first</VAR>)</I>
157<DD>Appended to a function prototype to tell the compiler that the function
158takes a <CODE>printf()</CODE>-like format string as the argument numbered
159<VAR>format</VAR> (starting from 1) and that the corresponding value
160arguments start at the argument numbered <VAR>first</VAR>. This lets the
161compiler tell you if you pass the wrong argument types.
162</DL>
163<P>
164
165<A NAME="Backtraces"></A>
166<HR SIZE="6">
167<A NAME="SEC100"></A>
168<H2> D.4 Backtraces </H2>
169<!--docid::SEC100::-->
170<P>
171
172When the kernel panics, it prints a &quot;backtrace,&quot; that is, a summary
173of how your program got where it is, as a list of addresses inside the
174functions that were running at the time of the panic. You can also
175insert a call to <CODE>debug_backtrace()</CODE>, prototyped in
176<Q><TT>&lt;debug.h&gt;</TT></Q>, to print a backtrace at any point in your code.
177<CODE>debug_backtrace_all()</CODE>, also declared in <Q><TT>&lt;debug.h&gt;</TT></Q>,
178prints backtraces of all threads.
179</P>
180<P>
181
182The addresses in a backtrace are listed as raw hexadecimal numbers,
183which are difficult to interpret. We provide a tool called
184<CODE>backtrace</CODE> to translate these into function names and source
185file line numbers.
186Give it the name of your <Q><TT>kernel.o</TT></Q> as the first argument and the
187hexadecimal numbers composing the backtrace (including the <Q><SAMP>0x</SAMP></Q>
188prefixes) as the remaining arguments. It outputs the function name
189and source file line numbers that correspond to each address.
190</P>
191<P>
192
193If the translated form of a backtrace is garbled, or doesn't make
194sense (e.g. function A is listed above function B, but B doesn't
195call A), then it's a good sign that you're corrupting a kernel
196thread's stack, because the backtrace is extracted from the stack.
197Alternatively, it could be that the <Q><TT>kernel.o</TT></Q> you passed to
198<CODE>backtrace</CODE> is not the same kernel that produced
199the backtrace.
200</P>
201<P>
202
203Sometimes backtraces can be confusing without any corruption.
204Compiler optimizations can cause surprising behavior. When a function
205has called another function as its final action (a <EM>tail call</EM>), the
206calling function may not appear in a backtrace at all. Similarly, when
207function A calls another function B that never returns, the compiler may
208optimize such that an unrelated function C appears in the backtrace
209instead of A. Function C is simply the function that happens to be in
210memory just after A. In the threads project, this is commonly seen in
211backtraces for test failures.
212</P>
213<P>
214
215<A NAME="Backtrace Example"></A>
216<HR SIZE="6">
217<A NAME="SEC101"></A>
218<H3> D.4.1 Example </H3>
219<!--docid::SEC101::-->
220<P>
221
222Here's an example. Suppose that Pintos printed out this following call
223stack, which is taken from an actual Pintos submission for the file
224system project:
225</P>
226<P>
227
228<TABLE><tr><td>&nbsp;</td><td class=example><pre>Call stack: 0xc0106eff 0xc01102fb 0xc010dc22 0xc010cf67 0xc0102319
2290xc010325a 0x804812c 0x8048a96 0x8048ac8.
230</pre></td></tr></table><P>
231
232You would then invoke the <CODE>backtrace</CODE> utility like shown below,
233cutting and pasting the backtrace information into the command line.
234This assumes that <Q><TT>kernel.o</TT></Q> is in the current directory. You
235would of course enter all of the following on a single shell command
236line, even though that would overflow our margins here:
237</P>
238<P>
239
240<TABLE><tr><td>&nbsp;</td><td class=example><pre>backtrace kernel.o 0xc0106eff 0xc01102fb 0xc010dc22 0xc010cf67
2410xc0102319 0xc010325a 0x804812c 0x8048a96 0x8048ac8
242</pre></td></tr></table><P>
243
244The backtrace output would then look something like this:
245</P>
246<P>
247
248<TABLE><tr><td>&nbsp;</td><td class=example><pre>0xc0106eff: debug_panic (lib/debug.c:86)
2490xc01102fb: file_seek (filesys/file.c:405)
2500xc010dc22: seek (userprog/syscall.c:744)
2510xc010cf67: syscall_handler (userprog/syscall.c:444)
2520xc0102319: intr_handler (threads/interrupt.c:334)
2530xc010325a: intr_entry (threads/intr-stubs.S:38)
2540x0804812c: (unknown)
2550x08048a96: (unknown)
2560x08048ac8: (unknown)
257</pre></td></tr></table><P>
258
259(You will probably not see exactly the same addresses if you run the
260command above on your own kernel binary, because the source code you
261compiled and the compiler you used are probably different.)
262</P>
263<P>
264
265The first line in the backtrace refers to <CODE>debug_panic()</CODE>, the
266function that implements kernel panics. Because backtraces commonly
267result from kernel panics, <CODE>debug_panic()</CODE> will often be the first
268function shown in a backtrace.
269</P>
270<P>
271
272The second line shows <CODE>file_seek()</CODE> as the function that panicked,
273in this case as the result of an assertion failure. In the source code
274tree used for this example, line 405 of <Q><TT>filesys/file.c</TT></Q> is the
275assertion
276</P>
277<P>
278
279<TABLE><tr><td>&nbsp;</td><td class=example><pre>ASSERT (file_ofs &gt;= 0);
280</pre></td></tr></table><P>
281
282(This line was also cited in the assertion failure message.)
283Thus, <CODE>file_seek()</CODE> panicked because it passed a negative file offset
284argument.
285</P>
286<P>
287
288The third line indicates that <CODE>seek()</CODE> called <CODE>file_seek()</CODE>,
289presumably without validating the offset argument. In this submission,
290<CODE>seek()</CODE> implements the <CODE>seek</CODE> system call.
291</P>
292<P>
293
294The fourth line shows that <CODE>syscall_handler()</CODE>, the system call
295handler, invoked <CODE>seek()</CODE>.
296</P>
297<P>
298
299The fifth and sixth lines are the interrupt handler entry path.
300</P>
301<P>
302
303The remaining lines are for addresses below <CODE>PHYS_BASE</CODE>. This
304means that they refer to addresses in the user program, not in the
305kernel. If you know what user program was running when the kernel
306panicked, you can re-run <CODE>backtrace</CODE> on the user program, like
307so: (typing the command on a single line, of course):
308</P>
309<P>
310
311<TABLE><tr><td>&nbsp;</td><td class=example><pre>backtrace tests/filesys/extended/grow-too-big 0xc0106eff 0xc01102fb
3120xc010dc22 0xc010cf67 0xc0102319 0xc010325a 0x804812c 0x8048a96
3130x8048ac8
314</pre></td></tr></table><P>
315
316The results look like this:
317</P>
318<P>
319
320<TABLE><tr><td>&nbsp;</td><td class=example><pre>0xc0106eff: (unknown)
3210xc01102fb: (unknown)
3220xc010dc22: (unknown)
3230xc010cf67: (unknown)
3240xc0102319: (unknown)
3250xc010325a: (unknown)
3260x0804812c: test_main (...xtended/grow-too-big.c:20)
3270x08048a96: main (tests/main.c:10)
3280x08048ac8: _start (lib/user/entry.c:9)
329</pre></td></tr></table><P>
330
331You can even specify both the kernel and the user program names on
332the command line, like so:
333</P>
334<P>
335
336<TABLE><tr><td>&nbsp;</td><td class=example><pre>backtrace kernel.o tests/filesys/extended/grow-too-big 0xc0106eff
3370xc01102fb 0xc010dc22 0xc010cf67 0xc0102319 0xc010325a 0x804812c
3380x8048a96 0x8048ac8
339</pre></td></tr></table><P>
340
341The result is a combined backtrace:
342</P>
343<P>
344
345<TABLE><tr><td>&nbsp;</td><td class=example><pre>In kernel.o:
3460xc0106eff: debug_panic (lib/debug.c:86)
3470xc01102fb: file_seek (filesys/file.c:405)
3480xc010dc22: seek (userprog/syscall.c:744)
3490xc010cf67: syscall_handler (userprog/syscall.c:444)
3500xc0102319: intr_handler (threads/interrupt.c:334)
3510xc010325a: intr_entry (threads/intr-stubs.S:38)
352In tests/filesys/extended/grow-too-big:
3530x0804812c: test_main (...xtended/grow-too-big.c:20)
3540x08048a96: main (tests/main.c:10)
3550x08048ac8: _start (lib/user/entry.c:9)
356</pre></td></tr></table><P>
357
358Here's an extra tip for anyone who read this far: <CODE>backtrace</CODE>
359is smart enough to strip the <CODE>Call stack:</CODE> header and <Q><SAMP>.</SAMP></Q>
360trailer from the command line if you include them. This can save you
361a little bit of trouble in cutting and pasting. Thus, the following
362command prints the same output as the first one we used:
363</P>
364<P>
365
366<TABLE><tr><td>&nbsp;</td><td class=example><pre>backtrace kernel.o Call stack: 0xc0106eff 0xc01102fb 0xc010dc22
3670xc010cf67 0xc0102319 0xc010325a 0x804812c 0x8048a96 0x8048ac8.
368</pre></td></tr></table><P>
369
370<A NAME="GDB"></A>
371<HR SIZE="6">
372<A NAME="SEC102"></A>
373<H2> D.5 GDB </H2>
374<!--docid::SEC102::-->
375<P>
376
377You can run Pintos under the supervision of the GDB debugger.
378First, start Pintos with the <Q><SAMP>--gdb</SAMP></Q> option, e.g.
379<CODE>pintos --gdb -- run mytest</CODE>. Second, open a second terminal on
380the same machine and
381use <CODE>pintos-gdb</CODE> to invoke GDB on
382<Q><TT>kernel.o</TT></Q>:<A NAME="DOCF5" HREF="pintos_fot.html#FOOT5">(5)</A>
383<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos-gdb kernel.o
384</pre></td></tr></table>and issue the following GDB command:
385<TABLE><tr><td>&nbsp;</td><td class=example><pre>target remote localhost:1234
386</pre></td></tr></table><P>
387
388Now GDB is connected to the simulator over a local
389network connection. You can now issue any normal GDB
390commands. If you issue the <Q><SAMP>c</SAMP></Q> command, the simulated BIOS will take
391control, load Pintos, and then Pintos will run in the usual way. You
392can pause the process at any point with <KBD>Ctrl+C</KBD>.
393</P>
394<P>
395
396<A NAME="Using GDB"></A>
397<HR SIZE="6">
398<A NAME="SEC103"></A>
399<H3> D.5.1 Using GDB </H3>
400<!--docid::SEC103::-->
401<P>
402
403You can read the GDB manual by typing <CODE>info gdb</CODE> at a
404terminal command prompt. Here's a few commonly useful GDB commands:
405</P>
406<P>
407
408<A NAME="IDX166"></A>
409</P>
410<DL>
411<DT><U>GDB Command:</U> <B>c</B>
412<DD>Continues execution until <KBD>Ctrl+C</KBD> or the next breakpoint.
413</DL>
414<P>
415
416<A NAME="IDX167"></A>
417</P>
418<DL>
419<DT><U>GDB Command:</U> <B>break</B> <I>function</I>
420<DD><A NAME="IDX168"></A>
421<DT><U>GDB Command:</U> <B>break</B> <I>file:line</I>
422<DD><A NAME="IDX169"></A>
423<DT><U>GDB Command:</U> <B>break</B> <I>*address</I>
424<DD>Sets a breakpoint at <VAR>function</VAR>, at <VAR>line</VAR> within <VAR>file</VAR>, or
425<VAR>address</VAR>.
426(Use a <Q><SAMP>0x</SAMP></Q> prefix to specify an address in hex.)
427<P>
428
429Use <CODE>break main</CODE> to make GDB stop when Pintos starts running.
430</P>
431</DL>
432<P>
433
434<A NAME="IDX170"></A>
435</P>
436<DL>
437<DT><U>GDB Command:</U> <B>p</B> <I>expression</I>
438<DD>Evaluates the given <VAR>expression</VAR> and prints its value.
439If the expression contains a function call, that function will actually
440be executed.
441</DL>
442<P>
443
444<A NAME="IDX171"></A>
445</P>
446<DL>
447<DT><U>GDB Command:</U> <B>l</B> <I>*address</I>
448<DD>Lists a few lines of code around <VAR>address</VAR>.
449(Use a <Q><SAMP>0x</SAMP></Q> prefix to specify an address in hex.)
450</DL>
451<P>
452
453<A NAME="IDX172"></A>
454</P>
455<DL>
456<DT><U>GDB Command:</U> <B>bt</B>
457<DD>Prints a stack backtrace similar to that output by the
458<CODE>backtrace</CODE> program described above.
459</DL>
460<P>
461
462<A NAME="IDX173"></A>
463</P>
464<DL>
465<DT><U>GDB Command:</U> <B>p/a</B> <I>address</I>
466<DD>Prints the name of the function or variable that occupies <VAR>address</VAR>.
467(Use a <Q><SAMP>0x</SAMP></Q> prefix to specify an address in hex.)
468</DL>
469<P>
470
471<A NAME="IDX174"></A>
472</P>
473<DL>
474<DT><U>GDB Command:</U> <B>diassemble</B> <I>function</I>
475<DD>Disassembles <VAR>function</VAR>.
476</DL>
477<P>
478
479We also provide a set of macros specialized for debugging Pintos,
480written by Godmar Back <A HREF="mailto:gback@cs.vt.edu">gback@cs.vt.edu</A>. You can type
481<CODE>help user-defined</CODE> for basic help with the macros. Here is an
482overview of their functionality, based on Godmar's documentation:
483</P>
484<P>
485
486<A NAME="IDX175"></A>
487</P>
488<DL>
489<DT><U>GDB Macro:</U> <B>debugpintos</B>
490<DD>Attach debugger to a waiting pintos process on the same machine.
491Shorthand for <CODE>target remote localhost:1234</CODE>.
492</DL>
493<P>
494
495<A NAME="IDX176"></A>
496</P>
497<DL>
498<DT><U>GDB Macro:</U> <B>dumplist</B> <I>list type element</I>
499<DD>Prints the elements of <VAR>list</VAR>, which should be a <CODE>struct</CODE> list
500that contains elements of the given <VAR>type</VAR> (without the word
501<CODE>struct</CODE>) in which <VAR>element</VAR> is the <CODE>struct list_elem</CODE> member
502that links the elements.
503<P>
504
505Example: <CODE>dumplist all_list thread allelem</CODE> prints all elements of
506<CODE>struct thread</CODE> that are linked in <CODE>struct list all_list</CODE> using the
507<CODE>struct list_elem allelem</CODE> which is part of <CODE>struct thread</CODE>.
508</P>
509</DL>
510<P>
511
512<A NAME="IDX177"></A>
513</P>
514<DL>
515<DT><U>GDB Macro:</U> <B>btthread</B> <I>thread</I>
516<DD>Shows the backtrace of <VAR>thread</VAR>, which is a pointer to the
517<CODE>struct thread</CODE> of the thread whose backtrace it should show. For the
518current thread, this is identical to the <CODE>bt</CODE> (backtrace) command.
519It also works for any thread suspended in <CODE>schedule()</CODE>,
520provided you know where its kernel stack page is located.
521</DL>
522<P>
523
524<A NAME="IDX178"></A>
525</P>
526<DL>
527<DT><U>GDB Macro:</U> <B>btthreadlist</B> <I>list element</I>
528<DD>Shows the backtraces of all threads in <VAR>list</VAR>, the <CODE>struct list</CODE> in
529which the threads are kept. Specify <VAR>element</VAR> as the
530<CODE>struct list_elem</CODE> field used inside <CODE>struct thread</CODE> to link the threads
531together.
532<P>
533
534Example: <CODE>btthreadlist all_list allelem</CODE> shows the backtraces of
535all threads contained in <CODE>struct list all_list</CODE>, linked together by
536<CODE>allelem</CODE>. This command is useful to determine where your threads
537are stuck when a deadlock occurs. Please see the example scenario below.
538</P>
539</DL>
540<P>
541
542<A NAME="IDX179"></A>
543</P>
544<DL>
545<DT><U>GDB Macro:</U> <B>btthreadall</B>
546<DD>Short-hand for <CODE>btthreadlist all_list allelem</CODE>.
547</DL>
548<P>
549
550<A NAME="IDX180"></A>
551</P>
552<DL>
553<DT><U>GDB Macro:</U> <B>btpagefault</B>
554<DD>Print a backtrace of the current thread after a page fault exception.
555Normally, when a page fault exception occurs, GDB will stop
556with a message that might say:<A NAME="DOCF6" HREF="pintos_fot.html#FOOT6">(6)</A>
557<P>
558
559<TABLE><tr><td>&nbsp;</td><td class=example><pre>Program received signal 0, Signal 0.
5600xc0102320 in intr0e_stub ()
561</pre></td></tr></table><P>
562
563In that case, the <CODE>bt</CODE> command might not give a useful
564backtrace. Use <CODE>btpagefault</CODE> instead.
565</P>
566<P>
567
568You may also use <CODE>btpagefault</CODE> for page faults that occur in a user
569process. In this case, you may wish to also load the user program's
570symbol table using the <CODE>loadusersymbols</CODE> macro, as described above.
571</P>
572</DL>
573<P>
574
575<A NAME="IDX181"></A>
576</P>
577<DL>
578<DT><U>GDB Macro:</U> <B>hook-stop</B>
579<DD>GDB invokes this macro every time the simulation stops, which Bochs will
580do for every processor exception, among other reasons. If the
581simulation stops due to a page fault, <CODE>hook-stop</CODE> will print a
582message that says and explains further whether the page fault occurred
583in the kernel or in user code.
584<P>
585
586If the exception occurred from user code, <CODE>hook-stop</CODE> will say:
587<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos-debug: a page fault exception occurred in user mode
588pintos-debug: hit 'c' to continue, or 's' to step to intr_handler
589</pre></td></tr></table><P>
590
591In Project 2, a page fault in a user process leads to the termination of
592the process. You should expect those page faults to occur in the
593robustness tests where we test that your kernel properly terminates
594processes that try to access invalid addresses. To debug those, set a
595break point in <CODE>page_fault()</CODE> in <Q><TT>exception.c</TT></Q>, which you will
596need to modify accordingly.
597</P>
598<P>
599
600In Project 3, a page fault in a user process no longer automatically
601leads to the termination of a process. Instead, it may require reading in
602data for the page the process was trying to access, either
603because it was swapped out or because this is the first time it's
604accessed. In either case, you will reach <CODE>page_fault()</CODE> and need to
605take the appropriate action there.
606</P>
607<P>
608
609If the page fault did not occur in user mode while executing a user
610process, then it occurred in kernel mode while executing kernel code.
611In this case, <CODE>hook-stop</CODE> will print this message:
612<TABLE><tr><td>&nbsp;</td><td class=example><pre>pintos-debug: a page fault occurred in kernel mode
613</pre></td></tr></table>followed by the output of the <CODE>btpagefault</CODE> command.
614<P>
615
616Before Project 3, a page fault exception in kernel code is always a bug
617in your kernel, because your kernel should never crash. Starting with
618Project 3, the situation will change if you use the <CODE>get_user()</CODE> and
619<CODE>put_user()</CODE> strategy to verify user memory accesses
620(see section <A HREF="pintos_2.html#SEC28">2.2.5 Accessing User Memory</A>).
621</P>
622<P>
623
624</P>
625</DL>
626<P>
627
628<A NAME="Example GDB Session"></A>
629<HR SIZE="6">
630<A NAME="SEC104"></A>
631<H3> D.5.2 Example GDB Session </H3>
632<!--docid::SEC104::-->
633<P>
634
635This section narrates a sample GDB session, provided by Godmar Back.
636This example illustrates how one might debug a Project 1 solution in
637which occasionally a thread that calls <CODE>timer_sleep()</CODE> is not woken
638up. With this bug, tests such as <CODE>mlfqs_load_1</CODE> get stuck.
639</P>
640<P>
641
642This session was captured with a slightly older version of Bochs and the
643GDB macros for Pintos, so it looks slightly different than it would now.
644Program output is shown in normal type, user input in <STRONG>strong</STRONG>
645type.
646</P>
647<P>
648
649First, I start Pintos:
650</P>
651<P>
652
653<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>$ <STRONG>pintos -v --gdb -- -q -mlfqs run mlfqs-load-1</STRONG>
654Writing command line to /tmp/gDAlqTB5Uf.dsk...
655bochs -q
656========================================================================
657 Bochs x86 Emulator 2.2.5
658 Build from CVS snapshot on December 30, 2005
659========================================================================
66000000000000i[ ] reading configuration from bochsrc.txt
66100000000000i[ ] Enabled gdbstub
66200000000000i[ ] installing nogui module as the Bochs GUI
66300000000000i[ ] using log file bochsout.txt
664Waiting for gdb connection on localhost:1234
665</FONT></pre></td></tr></table><P>
666
667Then, I open a second window on the same machine and start GDB:
668</P>
669<P>
670
671<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>$ <STRONG>pintos-gdb kernel.o</STRONG>
672GNU gdb Red Hat Linux (6.3.0.0-1.84rh)
673Copyright 2004 Free Software Foundation, Inc.
674GDB is free software, covered by the GNU General Public License, and you are
675welcome to change it and/or distribute copies of it under certain conditions.
676Type &quot;show copying&quot; to see the conditions.
677There is absolutely no warranty for GDB. Type &quot;show warranty&quot; for details.
678This GDB was configured as &quot;i386-redhat-linux-gnu&quot;...
679Using host libthread_db library &quot;/lib/libthread_db.so.1&quot;.
680</FONT></pre></td></tr></table><P>
681
682Then, I tell GDB to attach to the waiting Pintos emulator:
683</P>
684<P>
685
686<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>(gdb) <STRONG>debugpintos</STRONG>
687Remote debugging using localhost:1234
6880x0000fff0 in ?? ()
689Reply contains invalid hex digit 78
690</FONT></pre></td></tr></table><P>
691
692Now I tell Pintos to run by executing <CODE>c</CODE> (short for
693<CODE>continue</CODE>) twice:
694</P>
695<P>
696
697<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>(gdb) <STRONG>c</STRONG>
698Continuing.
699Reply contains invalid hex digit 78
700(gdb) <STRONG>c</STRONG>
701Continuing.
702</FONT></pre></td></tr></table><P>
703
704Now Pintos will continue and output:
705</P>
706<P>
707
708<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>Pintos booting with 4,096 kB RAM...
709Kernel command line: -q -mlfqs run mlfqs-load-1
710374 pages available in kernel pool.
711373 pages available in user pool.
712Calibrating timer... 102,400 loops/s.
713Boot complete.
714Executing 'mlfqs-load-1':
715(mlfqs-load-1) begin
716(mlfqs-load-1) spinning for up to 45 seconds, please wait...
717(mlfqs-load-1) load average rose to 0.5 after 42 seconds
718(mlfqs-load-1) sleeping for another 10 seconds, please wait...
719</FONT></pre></td></tr></table><P>
720
721<small>...</small>until it gets stuck because of the bug I had introduced. I hit
722<KBD>Ctrl+C</KBD> in the debugger window:
723</P>
724<P>
725
726<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>Program received signal 0, Signal 0.
7270xc010168c in next_thread_to_run () at ../../threads/thread.c:649
728649 while (i &lt;= PRI_MAX &amp;&amp; list_empty (&amp;ready_list[i]))
729(gdb)
730</FONT></pre></td></tr></table><P>
731
732The thread that was running when I interrupted Pintos was the idle
733thread. If I run <CODE>backtrace</CODE>, it shows this backtrace:
734</P>
735<P>
736
737<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>(gdb) <STRONG>bt</STRONG>
738#0 0xc010168c in next_thread_to_run () at ../../threads/thread.c:649
739#1 0xc0101778 in schedule () at ../../threads/thread.c:714
740#2 0xc0100f8f in thread_block () at ../../threads/thread.c:324
741#3 0xc0101419 in idle (aux=0x0) at ../../threads/thread.c:551
742#4 0xc010145a in kernel_thread (function=0xc01013ff , aux=0x0)
743 at ../../threads/thread.c:575
744#5 0x00000000 in ?? ()
745</FONT></pre></td></tr></table><P>
746
747Not terribly useful. What I really like to know is what's up with the
748other thread (or threads). Since I keep all threads in a linked list
749called <CODE>all_list</CODE>, linked together by a <CODE>struct list_elem</CODE> member
750named <CODE>allelem</CODE>, I can use the <CODE>btthreadlist</CODE> macro from the
751macro library I wrote. <CODE>btthreadlist</CODE> iterates through the list of
752threads and prints the backtrace for each thread:
753</P>
754<P>
755
756<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>(gdb) <STRONG>btthreadlist all_list allelem</STRONG>
757pintos-debug: dumping backtrace of thread 'main' @0xc002f000
758#0 0xc0101820 in schedule () at ../../threads/thread.c:722
759#1 0xc0100f8f in thread_block () at ../../threads/thread.c:324
760#2 0xc0104755 in timer_sleep (ticks=1000) at ../../devices/timer.c:141
761#3 0xc010bf7c in test_mlfqs_load_1 () at ../../tests/threads/mlfqs-load-1.c:49
762#4 0xc010aabb in run_test (name=0xc0007d8c &quot;mlfqs-load-1&quot;)
763 at ../../tests/threads/tests.c:50
764#5 0xc0100647 in run_task (argv=0xc0110d28) at ../../threads/init.c:281
765#6 0xc0100721 in run_actions (argv=0xc0110d28) at ../../threads/init.c:331
766#7 0xc01000c7 in main () at ../../threads/init.c:140
767
768pintos-debug: dumping backtrace of thread 'idle' @0xc0116000
769#0 0xc010168c in next_thread_to_run () at ../../threads/thread.c:649
770#1 0xc0101778 in schedule () at ../../threads/thread.c:714
771#2 0xc0100f8f in thread_block () at ../../threads/thread.c:324
772#3 0xc0101419 in idle (aux=0x0) at ../../threads/thread.c:551
773#4 0xc010145a in kernel_thread (function=0xc01013ff , aux=0x0)
774 at ../../threads/thread.c:575
775#5 0x00000000 in ?? ()
776</FONT></pre></td></tr></table><P>
777
778In this case, there are only two threads, the idle thread and the main
779thread. The kernel stack pages (to which the <CODE>struct thread</CODE> points)
780are at <TT>0xc0116000</TT> and <TT>0xc002f000</TT>, respectively. The main thread
781is stuck in <CODE>timer_sleep()</CODE>, called from <CODE>test_mlfqs_load_1</CODE>.
782</P>
783<P>
784
785Knowing where threads are stuck can be tremendously useful, for instance
786when diagnosing deadlocks or unexplained hangs.
787</P>
788<P>
789
790<A NAME="IDX182"></A>
791</P>
792<DL>
793<DT><U>GDB Macro:</U> <B>loadusersymbols</B>
794<DD><P>
795
796You can also use GDB to debug a user program running under Pintos.
797To do that, use the <CODE>loadusersymbols</CODE> macro to load the program's
798symbol table:
799<TABLE><tr><td>&nbsp;</td><td class=example><pre>loadusersymbols <VAR>program</VAR>
800</pre></td></tr></table>where <VAR>program</VAR> is the name of the program's executable (in the host
801file system, not in the Pintos file system). For example, you may issue:
802<TABLE><tr><td>&nbsp;</td><td class=smallexample><pre><FONT SIZE=-1>(gdb) <STRONG>loadusersymbols tests/userprog/exec-multiple</STRONG>
803add symbol table from file &quot;tests/userprog/exec-multiple&quot; at
804 .text_addr = 0x80480a0
805(gdb)
806</FONT></pre></td></tr></table><P>
807
808After this, you should be
809able to debug the user program the same way you would the kernel, by
810placing breakpoints, inspecting data, etc. Your actions apply to every
811user program running in Pintos, not just to the one you want to debug,
812so be careful in interpreting the results: GDB does not know
813which process is currently active (because that is an abstraction
814the Pintos kernel creates). Also, a name that appears in
815both the kernel and the user program will actually refer to the kernel
816name. (The latter problem can be avoided by giving the user executable
817name on the GDB command line, instead of <Q><TT>kernel.o</TT></Q>, and then using
818<CODE>loadusersymbols</CODE> to load <Q><TT>kernel.o</TT></Q>.)
819<CODE>loadusersymbols</CODE> is implemented via GDB's <CODE>add-symbol-file</CODE>
820command.
821</P>
822<P>
823
824</P>
825</DL>
826<P>
827
828<A NAME="GDB FAQ"></A>
829<HR SIZE="6">
830<A NAME="SEC105"></A>
831<H3> D.5.3 FAQ </H3>
832<!--docid::SEC105::-->
833<P>
834
835</P>
836<DL COMPACT>
837<DT>GDB can't connect to Bochs.
838<DD><P>
839
840If the <CODE>target remote</CODE> command fails, then make sure that both
841GDB and <CODE>pintos</CODE> are running on the same machine by
842running <CODE>hostname</CODE> in each terminal. If the names printed
843differ, then you need to open a new terminal for GDB on the
844machine running <CODE>pintos</CODE>.
845</P>
846<P>
847
848</P>
849<DT>GDB doesn't recognize any of the macros.
850<DD><P>
851
852If you start GDB with <CODE>pintos-gdb</CODE>, it should load the Pintos
853macros automatically. If you start GDB some other way, then you must
854issue the command <CODE>source <VAR>pintosdir</VAR>/src/misc/gdb-macros</CODE>,
855where <VAR>pintosdir</VAR> is the root of your Pintos directory, before you
856can use them.
857</P>
858<P>
859
860</P>
861<DT>Can I debug Pintos with DDD?
862<DD><P>
863
864Yes, you can. DDD invokes GDB as a subprocess, so you'll need to tell
865it to invokes <CODE>pintos-gdb</CODE> instead:
866<TABLE><tr><td>&nbsp;</td><td class=example><pre>ddd --gdb --debugger pintos-gdb
867</pre></td></tr></table><P>
868
869</P>
870<DT>Can I use GDB inside Emacs?
871<DD><P>
872
873Yes, you can. Emacs has special support for running GDB as a
874subprocess. Type <KBD>M-x gdb</KBD> and enter your <CODE>pintos-gdb</CODE>
875command at the prompt. The Emacs manual has information on how to use
876its debugging features in a section titled &quot;Debuggers.&quot;
877</P>
878<P>
879
880</P>
881<DT>GDB is doing something weird.
882<DD><P>
883
884If you notice strange behavior while using GDB, there
885are three possibilities: a bug in your
886modified Pintos, a bug in Bochs's
887interface to GDB or in GDB itself, or
888a bug in the original Pintos code. The first and second
889are quite likely, and you should seriously consider both. We hope
890that the third is less likely, but it is also possible.
891</DL>
892<P>
893
894<A NAME="Triple Faults"></A>
895<HR SIZE="6">
896<A NAME="SEC106"></A>
897<H2> D.6 Triple Faults </H2>
898<!--docid::SEC106::-->
899<P>
900
901When a CPU exception handler, such as a page fault handler, cannot be
902invoked because it is missing or defective, the CPU will try to invoke
903the &quot;double fault&quot; handler. If the double fault handler is itself
904missing or defective, that's called a &quot;triple fault.&quot; A triple fault
905causes an immediate CPU reset.
906</P>
907<P>
908
909Thus, if you get yourself into a situation where the machine reboots in
910a loop, that's probably a &quot;triple fault.&quot; In a triple fault
911situation, you might not be able to use <CODE>printf()</CODE> for debugging,
912because the reboots might be happening even before everything needed for
913<CODE>printf()</CODE> is initialized.
914</P>
915<P>
916
917There are at least two ways to debug triple faults. First, you can run
918Pintos in Bochs under GDB (see section <A HREF="pintos_8.html#SEC102">D.5 GDB</A>). If Bochs has been built
919properly for Pintos, a triple fault under GDB will cause it to print the
920message &quot;Triple fault: stopping for gdb&quot; on the console and break into
921the debugger. (If Bochs is not running under GDB, a triple fault will
922still cause it to reboot.) You can then inspect where Pintos stopped,
923which is where the triple fault occurred.
924</P>
925<P>
926
927Another option is what I call &quot;debugging by infinite loop.&quot;
928Pick a place in the Pintos code, insert the infinite loop
929<CODE>for (;;);</CODE> there, and recompile and run. There are two likely
930possibilities:
931</P>
932<P>
933
934<UL>
935<LI>
936The machine hangs without rebooting. If this happens, you know that
937the infinite loop is running. That means that whatever caused the
938reboot must be <EM>after</EM> the place you inserted the infinite loop.
939Now move the infinite loop later in the code sequence.
940<P>
941
942</P>
943<LI>
944The machine reboots in a loop. If this happens, you know that the
945machine didn't make it to the infinite loop. Thus, whatever caused the
946reboot must be <EM>before</EM> the place you inserted the infinite loop.
947Now move the infinite loop earlier in the code sequence.
948</UL>
949<P>
950
951If you move around the infinite loop in a &quot;binary search&quot; fashion, you
952can use this technique to pin down the exact spot that everything goes
953wrong. It should only take a few minutes at most.
954</P>
955<P>
956
957<A NAME="Modifying Bochs"></A>
958<HR SIZE="6">
959<A NAME="SEC107"></A>
960<H2> D.7 Modifying Bochs </H2>
961<!--docid::SEC107::-->
962<P>
963
964An advanced debugging technique is to modify and recompile the
965simulator. This proves useful when the simulated hardware has more
966information than it makes available to the OS. For example, page
967faults have a long list of potential causes, but the hardware does not
968report to the OS exactly which one is the particular cause.
969Furthermore, a bug in the kernel's handling of page faults can easily
970lead to recursive faults, but a &quot;triple fault&quot; will cause the CPU to
971reset itself, which is hardly conducive to debugging.
972</P>
973<P>
974
975In a case like this, you might appreciate being able to make Bochs
976print out more debug information, such as the exact type of fault that
977occurred. It's not very hard. You start by retrieving the source
978code for Bochs 2.2.6 from <A HREF="http://bochs.sourceforge.net">http://bochs.sourceforge.net</A> and
979saving the file <Q><TT>bochs-2.2.6.tar.gz</TT></Q> into a directory.
980The script <Q><TT>pintos/src/misc/bochs-2.2.6-build.sh</TT></Q>
981applies a number of patches contained in <Q><TT>pintos/src/misc</TT></Q>
982to the Bochs tree, then builds Bochs and installs it in a directory
983of your choice.
984Run this script without arguments to learn usage instructions.
985To use your <Q><TT>bochs</TT></Q> binary with <CODE>pintos</CODE>, make sure
986it is the one printed by <Q><SAMP>which `bochs`</SAMP></Q>; otherwise, modify
987your <CODE>PATH</CODE> accordingly.
988</P>
989<P>
990
991Of course, to get any good out of this you'll have to actually modify
992Bochs. Instructions for doing this are firmly out of the scope of
993this document. However, if you want to debug page faults as suggested
994above, a good place to start adding <CODE>printf()</CODE>s is
995<CODE>BX_CPU_C::dtranslate_linear()</CODE> in <Q><TT>cpu/paging.cc</TT></Q>.
996</P>
997<P>
998
999<A NAME="Debugging Tips"></A>
1000<HR SIZE="6">
1001<A NAME="SEC108"></A>
1002<H2> D.8 Tips </H2>
1003<!--docid::SEC108::-->
1004<P>
1005
1006The page allocator in <Q><TT>threads/palloc.c</TT></Q> and the block allocator in
1007<Q><TT>threads/malloc.c</TT></Q> clear all the bytes in memory to
1008<TT>0xcc</TT> at time of free. Thus, if you see an attempt to
1009dereference a pointer like <TT>0xcccccccc</TT>, or some other reference to
1010<TT>0xcc</TT>, there's a good chance you're trying to reuse a page that's
1011already been freed. Also, byte <TT>0xcc</TT> is the CPU opcode for &quot;invoke
1012interrupt 3,&quot; so if you see an error like <CODE>Interrupt 0x03 (#BP
1013Breakpoint Exception)</CODE>, then Pintos tried to execute code in a freed page or
1014block.
1015</P>
1016<P>
1017
1018An assertion failure on the expression <CODE>sec_no &lt; d-&gt;capacity</CODE>
1019indicates that Pintos tried to access a file through an inode that has
1020been closed and freed. Freeing an inode clears its starting sector
1021number to <TT>0xcccccccc</TT>, which is not a valid sector number for disks
1022smaller than about 1.6 TB.
1023<A NAME="Development Tools"></A>
1024<HR SIZE="6">
1025<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1026<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_8.html#SEC96"> &lt;&lt; </A>]</TD>
1027<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_9.html#SEC109"> &gt;&gt; </A>]</TD>
1028<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
1029<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
1030<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1031<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
1032</TR></TABLE>
1033<BR>
1034<FONT SIZE="-1">
1035This document was generated
1036by on <I>March, 6 2012</I>
1037using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
1038</FONT>
1039
1040</BODY>
1041</HTML>
diff --git a/doc/pintos_9.html b/doc/pintos_9.html
new file mode 100644
index 0000000..b63a0ba
--- /dev/null
+++ b/doc/pintos_9.html
@@ -0,0 +1,143 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Development Tools</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Development Tools">
18<META NAME="keywords" CONTENT="Pintos Projects: Development Tools">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC109"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_8.html#SEC96"> &lt;&lt; </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_9.html#SEC110"> &gt;&gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36
37<HR SIZE=2>
38<H1> E. Development Tools </H1>
39<!--docid::SEC109::-->
40<P>
41
42Here are some tools that you might find useful while developing code.
43</P>
44<P>
45
46<A NAME="Tags"></A>
47<HR SIZE="6">
48<A NAME="SEC110"></A>
49<H2> E.1 Tags </H2>
50<!--docid::SEC110::-->
51<P>
52
53Tags are an index to the functions and global variables declared in a
54program. Many editors, including Emacs and <CODE>vi</CODE>, can use
55them. The <Q><TT>Makefile</TT></Q> in <Q><TT>pintos/src</TT></Q> produces Emacs-style
56tags with the command <CODE>make TAGS</CODE> or <CODE>vi</CODE>-style tags with
57<CODE>make tags</CODE>.
58</P>
59<P>
60
61In Emacs, use <KBD>M-.</KBD> to follow a tag in the current window,
62<KBD>C-x 4 .</KBD> in a new window, or <KBD>C-x 5 .</KBD> in a new frame. If
63your cursor is on a symbol name for any of those commands, it becomes
64the default target. If a tag name has multiple definitions, <KBD>M-0
65M-.</KBD> jumps to the next one. To jump back to where you were before
66you followed the last tag, use <KBD>M-*</KBD>.
67</P>
68<P>
69
70<A NAME="cscope"></A>
71<HR SIZE="6">
72<A NAME="SEC111"></A>
73<H2> E.2 cscope </H2>
74<!--docid::SEC111::-->
75<P>
76
77The <CODE>cscope</CODE> program also provides an index to functions and
78variables declared in a program. It has some features that tag
79facilities lack. Most notably, it can find all the points in a
80program at which a given function is called.
81</P>
82<P>
83
84The <Q><TT>Makefile</TT></Q> in <Q><TT>pintos/src</TT></Q> produces <CODE>cscope</CODE>
85indexes when it is invoked as <CODE>make cscope</CODE>. Once the index has
86been generated, run <CODE>cscope</CODE> from a shell command line; no
87command-line arguments are normally necessary. Then use the arrow
88keys to choose one of the search criteria listed near the bottom of
89the terminal, type in an identifier, and hit <KBD>Enter</KBD>.
90<CODE>cscope</CODE> will then display the matches in the upper part of
91the terminal. You may use the arrow keys to choose a particular
92match; if you then hit <KBD>Enter</KBD>, <CODE>cscope</CODE> will invoke the
93default system editor<A NAME="DOCF7" HREF="pintos_fot.html#FOOT7">(7)</A> and position the
94cursor on that match. To start a new search, type <KBD>Tab</KBD>. To exit
95<CODE>cscope</CODE>, type <KBD>Ctrl-d</KBD>.
96</P>
97<P>
98
99Emacs and some versions of <CODE>vi</CODE> have their own interfaces to
100<CODE>cscope</CODE>. For information on how to use these interface,
101visit <A HREF="http://cscope.sourceforge.net, the &lt;CODE&gt;cscope&lt;/CODE&gt; home
102page">http://cscope.sourceforge.net, the <CODE>cscope</CODE> home
103page</A>.
104</P>
105<P>
106
107<A NAME="git"></A>
108<HR SIZE="6">
109<A NAME="SEC112"></A>
110<H2> E.3 git </H2>
111<!--docid::SEC112::-->
112<P>
113
114git is a version-control system. That is, you can use it to keep
115track of multiple versions of files. The idea is that you do some
116work on your code and test it, then check it into the version-control
117system. If you decide that the work you've done since your last
118check-in is no good, you can easily revert to the last checked-in
119version. Furthermore, you can retrieve any old version of your code
120as of some given day and time. The version control logs tell you who
121made changes and when.
122</P>
123<P>
124
125<A NAME="Bibliography"></A>
126<HR SIZE="6">
127<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
128<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_9.html#SEC109"> &lt;&lt; </A>]</TD>
129<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_10.html#SEC113"> &gt;&gt; </A>]</TD>
130<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
131<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
132<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
133<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
134</TR></TABLE>
135<BR>
136<FONT SIZE="-1">
137This document was generated
138by on <I>March, 6 2012</I>
139using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
140</FONT>
141
142</BODY>
143</HTML>
diff --git a/doc/pintos_abt.html b/doc/pintos_abt.html
new file mode 100644
index 0000000..6683381
--- /dev/null
+++ b/doc/pintos_abt.html
@@ -0,0 +1,205 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: About this document</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: About this document">
18<META NAME="keywords" CONTENT="Pintos Projects: About this document">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC_About"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
33</TR></TABLE>
34<H1>About this document</H1>
35This document was generated
36by
37using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
38<P></P>
39The buttons in the navigation panels have the following meaning:
40<P></P>
41<table border = "1">
42<TR>
43<TH> Button </TH>
44<TH> Name </TH>
45<TH> Go to </TH>
46<TH> From 1.2.3 go to</TH>
47</TR>
48<TR>
49<TD ALIGN="CENTER">
50 [ &lt; ] </TD>
51<TD ALIGN="CENTER">
52Back
53</TD>
54<TD>
55previous section in reading order
56</TD>
57<TD>
581.2.2
59</TD>
60</TR>
61<TR>
62<TD ALIGN="CENTER">
63 [ &gt; ] </TD>
64<TD ALIGN="CENTER">
65Forward
66</TD>
67<TD>
68next section in reading order
69</TD>
70<TD>
711.2.4
72</TD>
73</TR>
74<TR>
75<TD ALIGN="CENTER">
76 [ &lt;&lt; ] </TD>
77<TD ALIGN="CENTER">
78FastBack
79</TD>
80<TD>
81beginning of this chapter or previous chapter
82</TD>
83<TD>
841
85</TD>
86</TR>
87<TR>
88<TD ALIGN="CENTER">
89 [ Up ] </TD>
90<TD ALIGN="CENTER">
91Up
92</TD>
93<TD>
94up section
95</TD>
96<TD>
971.2
98</TD>
99</TR>
100<TR>
101<TD ALIGN="CENTER">
102 [ &gt;&gt; ] </TD>
103<TD ALIGN="CENTER">
104FastForward
105</TD>
106<TD>
107next chapter
108</TD>
109<TD>
1102
111</TD>
112</TR>
113<TR>
114<TD ALIGN="CENTER">
115 [Top] </TD>
116<TD ALIGN="CENTER">
117Top
118</TD>
119<TD>
120cover (top) of document
121</TD>
122<TD>
123 &nbsp;
124</TD>
125</TR>
126<TR>
127<TD ALIGN="CENTER">
128 [Contents] </TD>
129<TD ALIGN="CENTER">
130Contents
131</TD>
132<TD>
133table of contents
134</TD>
135<TD>
136 &nbsp;
137</TD>
138</TR>
139<TR>
140<TD ALIGN="CENTER">
141 [Index] </TD>
142<TD ALIGN="CENTER">
143Index
144</TD>
145<TD>
146concept index
147</TD>
148<TD>
149 &nbsp;
150</TD>
151</TR>
152<TR>
153<TD ALIGN="CENTER">
154 [ ? ] </TD>
155<TD ALIGN="CENTER">
156About
157</TD>
158<TD>
159this page
160</TD>
161<TD>
162 &nbsp;
163</TD>
164</TR>
165</TABLE>
166 <P>
167 where the <STRONG> Example </STRONG> assumes that the current position
168 is at <STRONG> Subsubsection One-Two-Three </STRONG> of a document of
169 the following structure:</P>
170 <UL>
171 <LI> 1. Section One
172 <UL>
173 <LI>1.1 Subsection One-One
174 <UL>
175 <LI>...</LI>
176 </UL>
177 <LI>1.2 Subsection One-Two
178 <UL>
179 <LI>1.2.1 Subsubsection One-Two-One</LI>
180 <LI>1.2.2 Subsubsection One-Two-Two</LI>
181 <LI>1.2.3 Subsubsection One-Two-Three &nbsp; &nbsp;
182 <STRONG>&lt;== Current Position </STRONG></LI>
183 <LI>1.2.4 Subsubsection One-Two-Four</LI>
184 </UL>
185 </LI>
186 <LI>1.3 Subsection One-Three
187 <UL>
188 <LI>...</LI>
189 </UL>
190 </LI>
191 <LI>1.4 Subsection One-Four</LI>
192 </UL>
193 </LI>
194 </UL>
195
196<HR SIZE=1>
197<BR>
198<FONT SIZE="-1">
199This document was generated
200by on <I>March, 6 2012</I>
201using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
202</FONT>
203
204</BODY>
205</HTML>
diff --git a/doc/pintos_fot.html b/doc/pintos_fot.html
new file mode 100644
index 0000000..820500e
--- /dev/null
+++ b/doc/pintos_fot.html
@@ -0,0 +1,79 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Footnotes</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Footnotes">
18<META NAME="keywords" CONTENT="Pintos Projects: Footnotes">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="pintos_fot.html"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
33</TR></TABLE>
34<H1>Footnotes</H1>
35<H3><A NAME="FOOT1" HREF="pintos_2.html#DOCF1">(1)</A></H3>
36<P>GDB might tell you that
37<CODE>schedule()</CODE> doesn't exist, which is arguably a GDB bug.
38You can work around this by setting the breakpoint by filename and
39line number, e.g. <CODE>break thread.c:<VAR>ln</VAR></CODE> where <VAR>ln</VAR> is
40the line number of the first declaration in <CODE>schedule()</CODE>.
41<H3><A NAME="FOOT2" HREF="pintos_2.html#DOCF2">(2)</A></H3>
42<P>We
43will treat these terms as synonyms. There is no standard
44distinction between them, although Intel processor manuals make
45a minor distinction between them on 80<VAR>x</VAR>86.
46<H3><A NAME="FOOT3" HREF="pintos_5.html#DOCF3">(3)</A></H3>
47<P>This is because <CODE>switch_threads()</CODE> takes
48arguments on the stack and the 80<VAR>x</VAR>86 SVR4 calling convention
49requires the caller, not the called function, to remove them when the
50call is complete. See [ <A HREF="pintos_10.html#SysV-i386">SysV-i386</A>] chapter 3 for details.
51<H3><A NAME="FOOT4" HREF="pintos_5.html#DOCF4">(4)</A></H3>
52<P>Actually, virtual to physical translation on the
5380<VAR>x</VAR>86 architecture occurs via an intermediate &quot;linear
54address,&quot; but Pintos (and most modern 80<VAR>x</VAR>86 OSes) set up the CPU
55so that linear and virtual addresses are one and the same. Thus, you
56can effectively ignore this CPU feature.
57<H3><A NAME="FOOT5" HREF="pintos_8.html#DOCF5">(5)</A></H3>
58<P><CODE>pintos-gdb</CODE> is a wrapper around
59<CODE>gdb</CODE> (80<VAR>x</VAR>86) or <CODE>i386-elf-gdb</CODE> (SPARC) that loads
60the Pintos macros at startup.
61<H3><A NAME="FOOT6" HREF="pintos_8.html#DOCF6">(6)</A></H3>
62<P>To be precise, GDB will stop
63only when running under Bochs. When running under QEMU, you must
64set a breakpoint in the <CODE>page_fault</CODE> function to stop execution
65when a page fault occurs. In that case, the <CODE>btpagefault</CODE> macro is
66unnecessary.
67<H3><A NAME="FOOT7" HREF="pintos_9.html#DOCF7">(7)</A></H3>
68<P>This is typically <CODE>vi</CODE>. To
69exit <CODE>vi</CODE>, type <KBD>: q <KBD>Enter</KBD></KBD>.
70<HR SIZE=1>
71<BR>
72<FONT SIZE="-1">
73This document was generated
74by on <I>March, 6 2012</I>
75using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
76</FONT>
77
78</BODY>
79</HTML>
diff --git a/doc/pintos_ovr.html b/doc/pintos_ovr.html
new file mode 100644
index 0000000..610d243
--- /dev/null
+++ b/doc/pintos_ovr.html
@@ -0,0 +1,69 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html40/loose.dtd">
3<HTML>
4<!-- Created on March, 6 2012 by texi2html 1.66 -->
5<!--
6Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
7 Karl Berry <karl@freefriends.org>
8 Olaf Bachmann <obachman@mathematik.uni-kl.de>
9 and many others.
10Maintained by: Many creative people <dev@texi2html.cvshome.org>
11Send bugs and suggestions to <users@texi2html.cvshome.org>
12
13-->
14<HEAD>
15<TITLE>Pintos Projects: Short Table of Contents</TITLE>
16
17<META NAME="description" CONTENT="Pintos Projects: Short Table of Contents">
18<META NAME="keywords" CONTENT="Pintos Projects: Short Table of Contents">
19<META NAME="resource-type" CONTENT="document">
20<META NAME="distribution" CONTENT="global">
21<META NAME="Generator" CONTENT="texi2html 1.66">
22<LINK REL="stylesheet" HREF="pintos.css">
23</HEAD>
24
25<BODY >
26
27<A NAME="SEC_OVERVIEW"></A>
28<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
29<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Top">Top</A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos.html#SEC_Contents">Contents</A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="pintos_abt.html#SEC_About"> ? </A>]</TD>
33</TR></TABLE>
34<H1>Short Table of Contents</H1>
35<BLOCKQUOTE>
36<A NAME="TOC1" HREF="pintos_1.html#SEC1">1. Introduction</A>
37<BR>
38<A NAME="TOC15" HREF="pintos_2.html#SEC15">2. Project 0: Introducing Pintos</A>
39<BR>
40<A NAME="TOC41" HREF="pintos_3.html#SEC41">3. Project 1: Threads</A>
41<BR>
42<A NAME="TOC47" HREF="pintos_4.html#SEC47">4. Project 2: Virtual Memory</A>
43<BR>
44<A NAME="TOC48" HREF="pintos_5.html#SEC48">A. Reference Guide</A>
45<BR>
46<A NAME="TOC89" HREF="pintos_6.html#SEC89">B. Coding Standards</A>
47<BR>
48<A NAME="TOC93" HREF="pintos_7.html#SEC93">C. Project Documentation</A>
49<BR>
50<A NAME="TOC96" HREF="pintos_8.html#SEC96">D. Debugging Tools</A>
51<BR>
52<A NAME="TOC109" HREF="pintos_9.html#SEC109">E. Development Tools</A>
53<BR>
54<A NAME="TOC113" HREF="pintos_10.html#SEC113">Bibliography</A>
55<BR>
56<A NAME="TOC117" HREF="pintos_11.html#SEC117">License</A>
57<BR>
58
59</BLOCKQUOTE>
60<HR SIZE=1>
61<BR>
62<FONT SIZE="-1">
63This document was generated
64by on <I>March, 6 2012</I>
65using <A HREF="http://texi2html.cvshome.org"><I>texi2html</I></A>
66</FONT>
67
68</BODY>
69</HTML>
diff --git a/doc/pintos_tour.pdf b/doc/pintos_tour.pdf
new file mode 100644
index 0000000..98ec371
--- /dev/null
+++ b/doc/pintos_tour.pdf
Binary files differ
diff --git a/doc/sample.tmpl b/doc/sample.tmpl
new file mode 100644
index 0000000..2d07635
--- /dev/null
+++ b/doc/sample.tmpl
@@ -0,0 +1,104 @@
1
2 +-----------------+
3 | CS 140 |
4 | SAMPLE PROJECT |
5 | DESIGN DOCUMENT |
6 +-----------------+
7
8---- GROUP ----
9
10Ben Pfaff <blp@stanford.edu>
11
12---- PRELIMINARIES ----
13
14>> If you have any preliminary comments on your submission, notes for
15>> the TAs, or extra credit, please give them here.
16
17(This is a sample design document.)
18
19>> Please cite any offline or online sources you consulted while
20>> preparing your submission, other than the Pintos documentation,
21>> course text, and lecture notes.
22
23None.
24
25 JOIN
26 ====
27
28---- DATA STRUCTURES ----
29
30>> Copy here the declaration of each new or changed `struct' or `struct'
31>> member, global or static variable, `typedef', or enumeration.
32>> Identify the purpose of each in 25 words or less.
33
34A "latch" is a new synchronization primitive. Acquires block
35until the first release. Afterward, all ongoing and future
36acquires pass immediately.
37
38 /* Latch. */
39 struct latch
40 {
41 bool released; /* Released yet? */
42 struct lock monitor_lock; /* Monitor lock. */
43 struct condition rel_cond; /* Signaled when released. */
44 };
45
46Added to struct thread:
47
48 /* Members for implementing thread_join(). */
49 struct latch ready_to_die; /* Release when thread about to die. */
50 struct semaphore can_die; /* Up when thread allowed to die. */
51 struct list children; /* List of child threads. */
52 list_elem children_elem; /* Element of `children' list. */
53
54---- ALGORITHMS ----
55
56>> Briefly describe your implementation of thread_join() and how it
57>> interacts with thread termination.
58
59thread_join() finds the joined child on the thread's list of
60children and waits for the child to exit by acquiring the child's
61ready_to_die latch. When thread_exit() is called, the thread
62releases its ready_to_die latch, allowing the parent to continue.
63
64---- SYNCHRONIZATION ----
65
66>> Consider parent thread P with child thread C. How do you ensure
67>> proper synchronization and avoid race conditions when P calls wait(C)
68>> before C exits? After C exits? How do you ensure that all resources
69>> are freed in each case? How about when P terminates without waiting,
70>> before C exits? After C exits? Are there any special cases?
71
72C waits in thread_exit() for P to die before it finishes its own
73exit, using the can_die semaphore "down"ed by C and "up"ed by P as
74it exits. Regardless of whether whether C has terminated, there
75is no race on wait(C), because C waits for P's permission before
76it frees itself.
77
78Regardless of whether P waits for C, P still "up"s C's can_die
79semaphore when P dies, so C will always be freed. (However,
80freeing C's resources is delayed until P's death.)
81
82The initial thread is a special case because it has no parent to
83wait for it or to "up" its can_die semaphore. Therefore, its
84can_die semaphore is initialized to 1.
85
86---- RATIONALE ----
87
88>> Critique your design, pointing out advantages and disadvantages in
89>> your design choices.
90
91This design has the advantage of simplicity. Encapsulating most
92of the synchronization logic into a new "latch" structure
93abstracts what little complexity there is into a separate layer,
94making the design easier to reason about. Also, all the new data
95members are in `struct thread', with no need for any extra dynamic
96allocation, etc., that would require extra management code.
97
98On the other hand, this design is wasteful in that a child thread
99cannot free itself before its parent has terminated. A parent
100thread that creates a large number of short-lived child threads
101could unnecessarily exhaust kernel memory. This is probably
102acceptable for implementing kernel threads, but it may be a bad
103idea for use with user processes because of the larger number of
104resources that user processes tend to own.
diff --git a/doc/start.tmpl b/doc/start.tmpl
new file mode 100644
index 0000000..83b17ad
--- /dev/null
+++ b/doc/start.tmpl
@@ -0,0 +1,101 @@
1 +--------------------+
2 | OS Development |
3 | PROJECT 0: INTRO |
4 | DESIGN DOCUMENT |
5 +--------------------+
6
7---- GROUP ----
8
9>> Fill in the names and email addresses of your group members.
10
11FirstName LastName <email@domain.example>
12FirstName LastName <email@domain.example>
13FirstName LastName <email@domain.example>
14
15---- PRELIMINARIES ----
16
17>> If you have any preliminary comments on your submission, notes for the
18>> TAs, or extra credit, please give them here.
19
20>> Please cite any offline or online sources you consulted while
21>> preparing your submission, other than the Pintos documentation, course
22>> text, lecture notes, and course staff.
23
24 ALARM CLOCK
25 ===========
26
27---- DATA STRUCTURES ----
28
29>> A1: Copy here the declaration of each new or changed `struct' or
30>> `struct' member, global or static variable, `typedef', or
31>> enumeration. Identify the purpose of each in 25 words or less.
32
33---- ALGORITHMS ----
34
35>> A2: Briefly describe what happens in a call to timer_sleep(),
36>> including the effects of the timer interrupt handler.
37
38>> A3: What steps are taken to minimize the amount of time spent in
39>> the timer interrupt handler?
40
41---- SYNCHRONIZATION ----
42
43>> A4: How are race conditions avoided when multiple threads call
44>> timer_sleep() simultaneously?
45
46>> A5: How are race conditions avoided when a timer interrupt occurs
47>> during a call to timer_sleep()?
48
49---- RATIONALE ----
50
51>> A6: Why did you choose this design? In what ways is it superior to
52>> another design you considered?
53
54 ARGUMENT PASSING
55 ================
56
57---- DATA STRUCTURES ----
58
59>> A1: Copy here the declaration of each new or changed `struct' or
60>> `struct' member, global or static variable, `typedef', or
61>> enumeration. Identify the purpose of each in 25 words or less.
62
63---- ALGORITHMS ----
64
65>> A2: Briefly describe how you implemented argument parsing. How do
66>> you arrange for the elements of argv[] to be in the right order?
67>> How do you avoid overflowing the stack page?
68
69---- RATIONALE ----
70
71>> A3: Why does Pintos implement strtok_r() but not strtok()?
72
73>> A4: In Pintos, the kernel separates commands into a executable name
74>> and arguments. In Unix-like systems, the shell does this
75>> separation. Identify at least two advantages of the Unix approach.
76
77
78
79 SURVEY QUESTIONS
80 ================
81
82Answering these questions is optional, but it will help us improve the
83course in future quarters. Feel free to tell us anything you
84want--these questions are just to spur your thoughts. You may also
85choose to respond anonymously in the course evaluations at the end of
86the quarter.
87
88>> In your opinion, was this assignment, or any one of the three problems
89>> in it, too easy or too hard? Did it take too long or too little time?
90
91>> Did you find that working on a particular part of the assignment gave
92>> you greater insight into some aspect of OS design?
93
94>> Is there some particular fact or hint we should give students in
95>> future quarters to help them solve the problems? Conversely, did you
96>> find any of our guidance to be misleading?
97
98>> Do you have any suggestions for the TAs to more effectively assist
99>> students, either for future quarters or the remaining projects?
100
101>> Any other comments?
diff --git a/doc/threads.tmpl b/doc/threads.tmpl
new file mode 100644
index 0000000..c3df5fe
--- /dev/null
+++ b/doc/threads.tmpl
@@ -0,0 +1,82 @@
1 +--------------------+
2 | CS 140 |
3 | PROJECT 1: THREADS |
4 | DESIGN DOCUMENT |
5 +--------------------+
6
7---- GROUP ----
8
9>> Fill in the names and email addresses of your group members.
10
11FirstName LastName <email@domain.example>
12FirstName LastName <email@domain.example>
13FirstName LastName <email@domain.example>
14
15---- PRELIMINARIES ----
16
17>> If you have any preliminary comments on your submission, notes for the
18>> TAs, or extra credit, please give them here.
19
20>> Please cite any offline or online sources you consulted while
21>> preparing your submission, other than the Pintos documentation, course
22>> text, lecture notes, and course staff.
23
24
25 PRIORITY SCHEDULING
26 ===================
27
28---- DATA STRUCTURES ----
29
30>> B1: Copy here the declaration of each new or changed `struct' or
31>> `struct' member, global or static variable, `typedef', or
32>> enumeration. Identify the purpose of each in 25 words or less.
33
34>> B2: Explain the data structure used to track priority donation.
35>> Use ASCII art to diagram a nested donation. (Alternately, submit a
36>> .png file.)
37
38---- ALGORITHMS ----
39
40>> B3: How do you ensure that the highest priority thread waiting for
41>> a lock, semaphore, or condition variable wakes up first?
42
43>> B4: Describe the sequence of events when a call to lock_acquire()
44>> causes a priority donation. How is nested donation handled?
45
46>> B5: Describe the sequence of events when lock_release() is called
47>> on a lock that a higher-priority thread is waiting for.
48
49---- SYNCHRONIZATION ----
50
51>> B6: Describe a potential race in thread_set_priority() and explain
52>> how your implementation avoids it. Can you use a lock to avoid
53>> this race?
54
55---- RATIONALE ----
56
57>> B7: Why did you choose this design? In what ways is it superior to
58>> another design you considered?
59
60 SURVEY QUESTIONS
61 ================
62
63Answering these questions is optional, but it will help us improve the
64course in future quarters. Feel free to tell us anything you
65want--these questions are just to spur your thoughts. You may also
66choose to respond anonymously in the course evaluations at the end of
67the quarter.
68
69>> In your opinion, was this assignment, or any one of the three problems
70>> in it, too easy or too hard? Did it take too long or too little time?
71
72>> Did you find that working on a particular part of the assignment gave
73>> you greater insight into some aspect of OS design?
74
75>> Is there some particular fact or hint we should give students in
76>> future quarters to help them solve the problems? Conversely, did you
77>> find any of our guidance to be misleading?
78
79>> Do you have any suggestions for the TAs to more effectively assist
80>> students, either for future quarters or the remaining projects?
81
82>> Any other comments?
diff --git a/doc/vm.tmpl b/doc/vm.tmpl
new file mode 100644
index 0000000..82b0806
--- /dev/null
+++ b/doc/vm.tmpl
@@ -0,0 +1,81 @@
1 +---------------------------+
2 | CS 140 |
3 | PROJECT 3: VIRTUAL MEMORY |
4 | DESIGN DOCUMENT |
5 +---------------------------+
6
7---- GROUP ----
8
9>> Fill in the names and email addresses of your group members.
10
11FirstName LastName <email@domain.example>
12FirstName LastName <email@domain.example>
13FirstName LastName <email@domain.example>
14
15---- PRELIMINARIES ----
16
17>> If you have any preliminary comments on your submission, notes for the
18>> TAs, or extra credit, please give them here.
19
20>> Please cite any offline or online sources you consulted while
21>> preparing your submission, other than the Pintos documentation, course
22>> text, lecture notes, and course staff.
23
24 PAGE TABLE MANAGEMENT
25 =====================
26
27TODO
28
29 STACK GROWTH
30 ============
31TODO
32
33 MEMORY MAPPED FILES
34 ===================
35
36---- DATA STRUCTURES ----
37
38>> C1: Copy here the declaration of each new or changed `struct' or
39>> `struct' member, global or static variable, `typedef', or
40>> enumeration. Identify the purpose of each in 25 words or less.
41
42---- ALGORITHMS ----
43
44>> C2: Describe how memory mapped files integrate into your virtual
45>> memory subsystem.
46
47>> C3: Explain how you determine whether a new file mapping overlaps
48>> any existing segment.
49
50---- RATIONALE ----
51
52>> C4: Mappings created with "mmap" have similar semantics to those of
53>> data demand-paged from executables, except that "mmap" mappings are
54>> written back to their original files, not to swap. This implies
55>> that much of their implementation can be shared. Explain why your
56>> implementation either does or does not share much of the code for
57>> the two situations.
58
59 SURVEY QUESTIONS
60 ================
61
62Answering these questions is optional, but it will help us improve the
63course in future quarters. Feel free to tell us anything you
64want--these questions are just to spur your thoughts. You may also
65choose to respond anonymously in the course evaluations at the end of
66the quarter.
67
68>> In your opinion, was this assignment, or any one of the three problems
69>> in it, too easy or too hard? Did it take too long or too little time?
70
71>> Did you find that working on a particular part of the assignment gave
72>> you greater insight into some aspect of OS design?
73
74>> Is there some particular fact or hint we should give students in
75>> future quarters to help them solve the problems? Conversely, did you
76>> find any of our guidance to be misleading?
77
78>> Do you have any suggestions for the TAs to more effectively assist
79>> students, either for future quarters or the remaining projects?
80
81>> Any other comments?
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-12 10:31:44 +0000