X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fstandards.texi;h=5b5d50293cb4397168d4027b37ce45e19f209f94;hb=c0667e92ce6156b69ee962683dcfb78f5c4ec0f8;hp=e7ed5686265f8bd94e89b496b7414f6192c631c3;hpb=a3f360bff01c33a4c9167c35f30b760b3a5de8d5;p=pintos-anon

diff --git a/doc/standards.texi b/doc/standards.texi
index e7ed568..5b5d502 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -39,7 +39,20 @@ 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
-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.
+
+Pintos comments sometimes refer to external standards or
+specifications by writing a name inside square brackets, like this:
+@code{[IA32-v3]}.  These names refer to the reference names used in
+this documentation (@pxref{References}).
+
+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.  We're only going to do a compile in the directory for the current
+project, so you don't need to make sure that the previous projects also
+compile.
 
 @node Conditional Compilation
 @section Conditional Compilation
@@ -65,7 +78,7 @@ There are a few exceptions:
 
 @itemize @bullet
 @item
-Problem 1-2, @code{thread_join()}.  Some other code expects
+Problem 1-2, @func{thread_join}.  Some other code expects
 @code{THREAD_JOIN_IMPLEMENTED} to be defined once you've implemented
 this function.
 
@@ -75,6 +88,13 @@ and off with a compile-time directive.  You must use the macro name we
 specify for that part.  @xref{Problem 1-4 Advanced Scheduler}, for
 details.
 
+@item
+Problem 3-2, paging to and from disk.  Your page replacement policy must
+default to LRU-like replacement, but we must be able to choose a random
+replacement policy with a compile-time directive.  You must use the
+macro name we specify for that part.  @xref{Problem 3-2 Paging To and
+From Disk}, for details.
+
 @item
 Code written for extra credit may be included conditionally.  If the
 extra credit code changes the normally expected functionality of the
@@ -126,7 +146,7 @@ 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
+the types it defines to @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
@@ -148,7 +168,7 @@ above, you supply it yourself and follow it by any flags, field
 widths, etc.
 
 @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
@@ -162,6 +182,9 @@ For @code{size_t} (e.g.@: @samp{%zu}).
 @item t
 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 @end table
+
+Pintos @func{printf} also implements a nonstandard @samp{'} flag that
+group large numbers with commas to make them easier to read.
 @end table
 
 @node Unsafe String Functions
@@ -172,37 +195,37 @@ A few of the string functions declared in the standard
 The worst offenders are intentionally not included in the Pintos C
 library:
 
-@table @code
-@item strcpy()
+@table @func
+@item strcpy
 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.
 
-@item strncpy()
+@item strncpy
 This function can leave its destination buffer without a null string
 terminator and it has performance problems besides.  Again, use
-@code{strlcpy()}.
+@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.
 
-@item strncat()
+@item strncat
 The meaning of its buffer size argument often leads to problems.
-Again, use @code{strlcat()}.
+Again, use @func{strlcat}.
 
-@item strtok()
+@item strtok
 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.
 
-@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.
 
-@item vsprintf()
-Same issue as @code{strcpy()}.  Use @code{vsnprintf()} instead.
+@item vsprintf
+Same issue as @func{strcpy}.  Use @func{vsnprintf} instead.
 @end table
 
 If you try to use any of these functions, you should get a hint from