summaryrefslogtreecommitdiffstats
path: root/doc/pintos_6.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pintos_6.html')
-rw-r--r--doc/pintos_6.html314
1 files changed, 314 insertions, 0 deletions
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>
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-12 11:45:43 +0000