Updated to use Bochs 2.6.11

[pintos-anon] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index 28bfc81f12979d93a542ead5b6662493e7874993..7d30a4b4cfbe1c218a6390f752c4fb16ff484364 100644 (file)
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -1,26 +1,21 @@
-@node Coding Standards, , Multilevel Feedback Scheduling, Top
+@node Coding Standards

 @appendix Coding Standards
 
 @appendix Coding Standards
 

-All of you should have taken a class like CS 107, so we expect you to
-be familiar with some set of coding standards such as
-@uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
-, CS 107 Coding Standards}. Even if you've taken 107, we recommend
-reviewing that document.  We expect code at the "Peer-Review Quality"
-level as described there.
-
-Our standards for coding are mostly important in grading.  More
-information on our grading methodology can be found on the Course Info
-page and the Grading page.  We also want to stress that aside from the
-fact that we are explicitly basing part of your grade on these things,
-good coding practices will improve the quality of your code.  This
-makes it easier for your partners to interact with it, and ultimately,
-will improve your chances of having a good working program.  That said
-once, the rest of this document will discuss only the ways in which
-our coding standards will affect our grading.
+@localcodingstandards{}
+
+Our standards for coding are most important for grading.  We want to
+stress that aside from the fact that we are explicitly basing part of
+your grade on these things, good coding practices will improve the
+quality of your code.  This makes it easier for your partners to
+interact with it, and ultimately, will improve your chances of having a
+good working program.  That said once, the rest of this document will
+discuss only the ways in which our coding standards will affect our
+grading.

 
 @menu
 * Coding Style::                
 
 @menu
 * Coding Style::                

-* Conditional Compilation::     
+* C99::                         
+* Unsafe String Functions::     

 @end menu
 
 @node Coding Style
 @end menu
 
 @node Coding Style


@@ -37,55 +32,44 @@ follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU
 Coding Standards}.  We encourage you to follow the applicable parts of
 them too, especially chapter 5, ``Making the Best Use of C.''  Using a
 different style won't cause actual problems, but it's ugly to see
 Coding Standards}.  We encourage you to follow the applicable parts of
 them too, especially chapter 5, ``Making the Best Use of C.''  Using a
 different style won't cause actual problems, but it's ugly to see

-gratuitous differences in style from one function to another.
+gratuitous differences in style from one function to another.  If your
+code is too ugly, it will cost you points.

 
 

-@node Conditional Compilation
-@section Conditional Compilation
+Please limit C source file lines to at most 79 characters long.

 
 

-Given the scope and complexity of your assignments this quarter, you
-may find it convenient while coding and debugging (and we will find it
-convenient while grading) to be able to independently turn different
-parts of the assignments on and off.  To do this, choose a macro name
-and use it in conditional
-compilation directives, e.g.:
+Pintos comments sometimes refer to external standards or
+specifications by writing a name inside square brackets, like this:
+@code{[IA32-v3a]}.  These names refer to the reference names used in
+this documentation (@pxref{Bibliography}).

 
 

-@example
-#ifdef @var{NAME}
-@dots{}your code@dots{}
-#endif
-@end example
+If you remove existing Pintos code, please delete it from your source
+file entirely.  Don't just put it into a comment or a conditional
+compilation directive, because that makes the resulting code hard to
+read.

 
 

-In general, the code that you turn in must not depend on conditional
-compilation directives.  Project code should be written so that all of
-the subproblems for the project function together, and it should
-compile properly without the need for any new macros to be defined.
-There are a few exceptions:
-
-@itemize @bullet
-@item
-Project 1 has a few parts that we must be able to turn on and off via
-conditional compilation.  You must use the macros we specify for those
-parts.
-
-@item
-Code written for extra credit may be included conditionally.  If the
-extra credit code changes the normally expected functionality of the
-code, then it @emph{must} be included conditionally, and it must not
-be enabled by default.
-@end itemize
-
-You can use @file{constants.h} in @file{pintos/src} to define macros
-for conditional compilation.  We will replace the @file{constants.h}
-that you supply with one of our own when we test your code, so do not
-define anything important in it.
+We're only going to do a compile in the directory for the project being
+submitted.  You don't need to make sure that the previous projects also
+compile.
+
+Project code should be written so that all of the subproblems for the
+project function together, that is, without the need to rebuild with
+different macros defined, etc.  If you do extra credit work that
+changes normal Pintos behavior so as to interfere with grading, then
+you must implement it so that it only acts that way when given a
+special command-line option of the form @option{-@var{name}}, where
+@var{name} is a name of your choice.  You can add such an option by
+modifying @func{parse_options} in @file{threads/init.c}.
+
+The introduction describes additional coding style requirements
+(@pxref{Design}).

 
 @node C99
 @section C99
 
 The Pintos source code uses a few features of the ``C99'' standard
 
 @node C99
 @section C99
 
 The Pintos source code uses a few features of the ``C99'' standard

-library that were not in the original 1989 standard for C.  Because
-they are so new, most classes do not cover these features, so this
-section will describe them.  The new features used in Pintos are
+library that were not in the original 1989 standard for C.  Many
+programmers are unaware of these feature, so we will describe them.  The
+new features used in Pintos are

 mostly in new headers:
 
 @table @file
 mostly in new headers:
 
 @table @file


@@ -97,7 +81,7 @@ expands to 0.
 @item <stdint.h>
 On systems that support them, this header defines types
 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
 @item <stdint.h>
 On systems that support them, this header defines types
 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,

-64, and possibly others.  These are 2's complement signed and unsigned
+64, and possibly other values.  These are 2's complement signed and unsigned

 types, respectively, with the given number of bits.  
 
 On systems where it is possible, this header also defines types
 types, respectively, with the given number of bits.  
 
 On systems where it is possible, this header also defines types


@@ -108,17 +92,17 @@ On all systems, this header defines types @code{intmax_t} and
 @code{uintmax_t}, which are the system's signed and unsigned integer
 types with the widest ranges.
 
 @code{uintmax_t}, which are the system's signed and unsigned integer
 types with the widest ranges.
 

-For every signed integer type @code{@var{type}_t} it defines, as well
+For every signed integer type @code{@var{type}_t} defined here, as well

 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also

-defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
+defines macros @code{@var{TYPE}_MAX} and @code{@var{TYPE}_MIN} that

 give the type's range.  Similarly, for every unsigned integer type
 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
 give the type's range.  Similarly, for every unsigned integer type
 @code{@var{type}_t} defined here, as well as for @code{size_t} defined

-in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
+in @file{<stddef.h>}, this header defines a @code{@var{TYPE}_MAX}

 macro giving its maximum value.
 
 @item <inttypes.h>
 macro giving its maximum value.
 
 @item <inttypes.h>

-@file{<stdint.h>} is useful on its own, but it provides no way to pass
-the types it defines to @code{printf()} and related functions.  This
+@file{<stdint.h>} provides no straightforward way to format
+the types it defines with @func{printf} and related functions.  This

 header provides macros to help with that.  For every
 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
 header provides macros to help with that.  For every
 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of


@@ -132,15 +116,15 @@ the C compiler concatenates adjacent string literals:
 #include <inttypes.h>
 @dots{}
 int32_t value = @dots{};
 #include <inttypes.h>
 @dots{}
 int32_t value = @dots{};

-printf ("value=%08"PRId32"\n");
+printf ("value=%08"PRId32"\n", value);

 @end example
 @noindent
 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
 above, you supply it yourself and follow it by any flags, field
 @end example
 @noindent
 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
 above, you supply it yourself and follow it by any flags, field

-widths, etc.
+width, etc.

 
 @item <stdio.h>
 
 @item <stdio.h>

-The @file{printf()} function has some new type modifiers for printing
+The @func{printf} function has some new type modifiers for printing

 standard types:
 
 @table @samp
 standard types:
 
 @table @samp


@@ -154,6 +138,9 @@ For @code{size_t} (e.g.@: @samp{%zu}).
 @item t
 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 @end table
 @item t
 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 @end table

+
+Pintos @func{printf} also implements a nonstandard @samp{'} flag that
+groups large numbers with commas to make them easier to read.

 @end table
 
 @node Unsafe String Functions
 @end table
 
 @node Unsafe String Functions


@@ -165,38 +152,38 @@ The worst offenders are intentionally not included in the Pintos C
 library:
 
 @table @code
 library:
 
 @table @code

-@item strcpy()
+@item strcpy

 When used carelessly this function can overflow the buffer reserved
 When used carelessly this function can overflow the buffer reserved

-for its output string.  Use @code{strlcpy()} instead.  Refer to
+for its output string.  Use @func{strlcpy} instead.  Refer to

 comments in its source code in @code{lib/string.c} for documentation.
 
 comments in its source code in @code{lib/string.c} for documentation.
 

-@item strncpy()
+@item strncpy

 This function can leave its destination buffer without a null string
 This function can leave its destination buffer without a null string

-terminator and it has performance problems besides.  Again, use
-@code{strlcpy()}.
+terminator.  It also has performance problems.  Again, use
+@func{strlcpy}.

 
 

-@item strcat()
-Same issue as @code{strcpy()}, but substitute @code{strlcat()}.
+@item strcat
+Same issue as @func{strcpy}.  Use @func{strlcat} instead.

 Again, refer to comments in its source code in @code{lib/string.c} for
 documentation.
 
 Again, refer to comments in its source code in @code{lib/string.c} for
 documentation.
 

-@item strncat()
-The meaning of its buffer size argument often leads to problems.
-Again, use @code{strlcat()}.
+@item strncat
+The meaning of its buffer size argument is surprising.
+Again, use @func{strlcat}.

 
 

-@item strtok()
+@item strtok

 Uses global data, so it is unsafe in threaded programs such as
 Uses global data, so it is unsafe in threaded programs such as

-kernels.  Use @code{strtok_r()} instead, and see its source code in
+kernels.  Use @func{strtok_r} instead, and see its source code in

 @code{lib/string.c} for documentation and an example.
 
 @code{lib/string.c} for documentation and an example.
 

-@item sprintf()
-Same issue as @code{strcpy()}.  Use @code{snprintf()} instead.  Refer
+@item sprintf
+Same issue as @func{strcpy}.  Use @func{snprintf} instead.  Refer

 to comments in @code{lib/stdio.h} for documentation.
 
 to comments in @code{lib/stdio.h} for documentation.
 

-@item vsprintf()
-Same issue as @code{strcpy()}.  Use @code{vsnprintf()} instead.
+@item vsprintf
+Same issue as @func{strcpy}.  Use @func{vsnprintf} instead.

 @end table
 
 @end table
 

-If you try to use any of these functions, you should get a hint from
-the error message, which will refer to an identifier like
+If you try to use any of these functions, the error message will give
+you a hint by referring to an identifier like

 @code{dont_use_sprintf_use_snprintf}.
 @code{dont_use_sprintf_use_snprintf}.