pintos-os.org Git - pintos-anon/blob - doc/standards.texi

   1 @node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
   2 @appendix Coding Standards
   3
   4 All of you should have taken a class like CS 107, so we expect you to
   5 be familiar with some set of coding standards such as
   6 @uref{http://www.stanford.edu/class/cs140/projects/misc/CodingStandards.pdf,
   7 , CS 107 Coding Standards}. Even if you've taken 107, we recommend
   8 reviewing that document.  We expect code at the "Peer-Review Quality"
   9 level as described there.
  10
  11 Our standards for coding are mostly important in grading.  More
  12 information on our grading methodology can be found on the Course Info
  13 page and the Grading page.  We also want to stress that aside from the
  14 fact that we are explicitly basing part of your grade on these things,
  15 good coding practices will improve the quality of your code.  This
  16 makes it easier for your partners to interact with it, and ultimately,
  17 will improve your chances of having a good working program.  That said
  18 once, the rest of this document will discuss only the ways in which
  19 our coding standards will affect our grading.
  20
  21 @menu
  22 * Coding Style::
  23 * Conditional Compilation::
  24 * C99::
  25 * Unsafe String Functions::
  26 @end menu
  27
  28 @node Coding Style
  29 @section Style
  30
  31 Style, for the purposes of our grading, refers to how readable your
  32 code is.  At minimum, this means that your code is well formatted, your
  33 variable names are descriptive and your functions are decomposed and
  34 well commented.  Any other factors which make it hard (or easy) for us
  35 to read or use your code will be reflected in your style grade.
  36
  37 The existing Pintos code is written in the GNU style and largely
  38 follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU
  39 Coding Standards}.  We encourage you to follow the applicable parts of
  40 them too, especially chapter 5, ``Making the Best Use of C.''  Using a
  41 different style won't cause actual problems, but it's ugly to see
  42 gratuitous differences in style from one function to another.
  43
  44 Pintos comments sometimes refer to outside standards or
  45 specifications by writing a name inside square brackets, like this:
  46 @code{[IA32-v3]}.  These names refer to the reference names used in
  47 this documentation (@pxref{References}).
  48
  49 @node Conditional Compilation
  50 @section Conditional Compilation
  51
  52 Given the scope and complexity of your assignments this quarter, you
  53 may find it convenient while coding and debugging (and we will find it
  54 convenient while grading) to be able to independently turn different
  55 parts of the assignments on and off.  To do this, choose a macro name
  56 and use it in conditional
  57 compilation directives, e.g.:
  58
  59 @example
  60 #ifdef @var{NAME}
  61 @dots{}your code@dots{}
  62 #endif
  63 @end example
  64
  65 In general, the code that you turn in must not depend on conditional
  66 compilation directives.  Project code should be written so that all of
  67 the subproblems for the project function together, and it should
  68 compile properly without the need for any new macros to be defined.
  69 There are a few exceptions:
  70
  71 @itemize @bullet
  72 @item
  73 Problem 1-2, @code{thread_join()}.  Some other code expects
  74 @code{THREAD_JOIN_IMPLEMENTED} to be defined once you've implemented
  75 this function.
  76
  77 @item
  78 Problem 1-4, the advanced scheduler.  We must be able to turn this on
  79 and off with a compile-time directive.  You must use the macro name we
  80 specify for that part.  @xref{Problem 1-4 Advanced Scheduler}, for
  81 details.
  82
  83 @item
  84 Code written for extra credit may be included conditionally.  If the
  85 extra credit code changes the normally expected functionality of the
  86 code, then it @emph{must} be included conditionally, and it must not
  87 be enabled by default.
  88 @end itemize
  89
  90 You can use @file{constants.h} in @file{pintos/src} to define macros
  91 for conditional compilation.  We will replace the @file{constants.h}
  92 that you supply with one of our own when we test your code, so do not
  93 define anything important in it.
  94
  95 @node C99
  96 @section C99
  97
  98 The Pintos source code uses a few features of the ``C99'' standard
  99 library that were not in the original 1989 standard for C.  Because
 100 they are so new, most classes do not cover these features, so this
 101 section will describe them.  The new features used in Pintos are
 102 mostly in new headers:
 103
 104 @table @file
 105 @item <stdbool.h>
 106 Defines macros @code{bool}, a 1-bit type that takes on only the values
 107 0 and 1, @code{true}, which expands to 1, and @code{false}, which
 108 expands to 0.
 109
 110 @item <stdint.h>
 111 On systems that support them, this header defines types
 112 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
 113 64, and possibly others.  These are 2's complement signed and unsigned
 114 types, respectively, with the given number of bits.
 115
 116 On systems where it is possible, this header also defines types
 117 @code{intptr_t} and @code{uintptr_t}, which are integer types big
 118 enough to hold a pointer.
 119
 120 On all systems, this header defines types @code{intmax_t} and
 121 @code{uintmax_t}, which are the system's signed and unsigned integer
 122 types with the widest ranges.
 123
 124 For every signed integer type @code{@var{type}_t} it defines, as well
 125 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
 126 defines macros @code{@var{type}_MAX} and @code{@var{type}_MIN} that
 127 give the type's range.  Similarly, for every unsigned integer type
 128 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
 129 in @file{<stddef.h>}, this header defines a @code{@var{type}_MAX}
 130 macro giving its maximum value.
 131
 132 @item <inttypes.h>
 133 @file{<stdint.h>} is useful on its own, but it provides no way to pass
 134 the types it defines to @code{printf()} and related functions.  This
 135 header provides macros to help with that.  For every
 136 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
 137 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
 138 that type with @code{"%d"} and @code{"%i"}.  Similarly, for every
 139 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
 140 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
 141
 142 You use these something like this, taking advantage of the fact that
 143 the C compiler concatenates adjacent string literals:
 144 @example
 145 #include <inttypes.h>
 146 @dots{}
 147 int32_t value = @dots{};
 148 printf ("value=%08"PRId32"\n", value);
 149 @end example
 150 @noindent
 151 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
 152 above, you supply it yourself and follow it by any flags, field
 153 widths, etc.
 154
 155 @item <stdio.h>
 156 The @file{printf()} function has some new type modifiers for printing
 157 standard types:
 158
 159 @table @samp
 160 @item j
 161 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
 162 @samp{%ju}).
 163
 164 @item z
 165 For @code{size_t} (e.g.@: @samp{%zu}).
 166
 167 @item t
 168 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 169 @end table
 170 @end table
 171
 172 @node Unsafe String Functions
 173 @section Unsafe String Functions
 174
 175 A few of the string functions declared in the standard
 176 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
 177 The worst offenders are intentionally not included in the Pintos C
 178 library:
 179
 180 @table @code
 181 @item strcpy()
 182 When used carelessly this function can overflow the buffer reserved
 183 for its output string.  Use @code{strlcpy()} instead.  Refer to
 184 comments in its source code in @code{lib/string.c} for documentation.
 185
 186 @item strncpy()
 187 This function can leave its destination buffer without a null string
 188 terminator and it has performance problems besides.  Again, use
 189 @code{strlcpy()}.
 190
 191 @item strcat()
 192 Same issue as @code{strcpy()}, but substitute @code{strlcat()}.
 193 Again, refer to comments in its source code in @code{lib/string.c} for
 194 documentation.
 195
 196 @item strncat()
 197 The meaning of its buffer size argument often leads to problems.
 198 Again, use @code{strlcat()}.
 199
 200 @item strtok()
 201 Uses global data, so it is unsafe in threaded programs such as
 202 kernels.  Use @code{strtok_r()} instead, and see its source code in
 203 @code{lib/string.c} for documentation and an example.
 204
 205 @item sprintf()
 206 Same issue as @code{strcpy()}.  Use @code{snprintf()} instead.  Refer
 207 to comments in @code{lib/stdio.h} for documentation.
 208
 209 @item vsprintf()
 210 Same issue as @code{strcpy()}.  Use @code{vsnprintf()} instead.
 211 @end table
 212
 213 If you try to use any of these functions, you should get a hint from
 214 the error message, which will refer to an identifier like
 215 @code{dont_use_sprintf_use_snprintf}.