From: Ben Pfaff Date: Wed, 15 Sep 2004 21:15:14 +0000 (+0000) Subject: Update docs. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=98c2fc1ab7d395bb92cf4a57233fe432539d26a9;p=pintos-anon Update docs. --- diff --git a/doc/Makefile b/doc/Makefile index f6a7b7d..8d86141 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,5 +1,5 @@ TEXIS = projects.texi intro.texi threads.texi mlfqs.texi userprog.texi \ -filesys.texi vm.texi +filesys.texi vm.texi standards.texi all: projects.html projects.info diff --git a/doc/filesys.texi b/doc/filesys.texi index 5ffcb75..7628eb4 100644 --- a/doc/filesys.texi +++ b/doc/filesys.texi @@ -1,4 +1,4 @@ -@node Project 4--File Systems, , Project 3--Virtual Memory, Top +@node Project 4--File Systems, Multilevel Feedback Scheduling, Project 3--Virtual Memory, Top @chapter Project 4: File Systems In the previous two assignments, you made extensive use of a diff --git a/doc/intro.texi b/doc/intro.texi index 9af1fb3..82e4504 100644 --- a/doc/intro.texi +++ b/doc/intro.texi @@ -199,24 +199,46 @@ issue the command @code{pintos run}. This command will create a @file{bochsrc.txt} file, which is needed for running Bochs, and then invoke Bochs. -Bochs opens a new window that represents the the simulated machine's +Bochs opens a new window that represents the simulated machine's display, and a BIOS message briefly flashes. Then Pintos boots and -runs a simple test program that scrolls by a few screenfuls of text. +runs a simple test program that outputs a few screenfuls of text. When it's done, you can close Bochs by clicking on the ``Power'' button in the window's top right corner, or rerun the whole process by clicking on the ``Reset'' button just to its left. The other buttons are not very useful for our purposes. +(If no window appeared at all, and you just got a terminal full of +corrupt-looking text, then you're probably logged in remotely and X +forwarding is not set up correctly. In this case, you can fix your X +setup, or you can use the @option{-nv} option.) + The text printed by Pintos inside Bochs probably went by too quickly to read. However, you've probably noticed by now that the same text -was displayed - +was displayed in the terminal you used to run @command{pintos}. This +is because Pintos sends all output both to the VGA display and to the +first serial port, and by default the serial port is connected to +Bochs's @code{stdout}. You can log this output to a file by +redirecting at the command line, e.g.@: @code{pintos run > logfile}. + +The @command{pintos} program offers multiple options for running +Pintos. Use @code{pintos help} to see a list of the options. You can +select a simulator other than Bochs, although the Leland systems only +have Bochs installed. You can start the simulator running a debugger +(@pxref{Debugging Pintos}). You can set the amount of memory to give +the VM. Finally, you can set up how you want VM output to be +displayed: use @option{-nv} to turn off the VGA display, @option{-t} +to use your terminal window as the VGA display instead of opening a +new window, or @option{-ns} to suppress the serial output to +@code{stdout}. + +The @command{pintos} program offers commands other than @samp{run} and +@samp{help}, but we won't have any need for them until project 2. @node Pintos Trivia @section Pintos Trivia The design of Pintos is inspired by Nachos, an instructional operating -system implemented at UC Berkeley, and even uses a few pieces of +system originally from UC Berkeley, and even uses a few pieces of Nachos code. Pintos is different from Nachos in two important ways. First, Nachos requires a host operating system such as Solaris, whereas Pintos runs on real or simulated 80@var{x}86 hardware. diff --git a/doc/mlfqs.texi b/doc/mlfqs.texi index 90c22f3..cb64dc4 100644 --- a/doc/mlfqs.texi +++ b/doc/mlfqs.texi @@ -1,5 +1,5 @@ -@node Multilevel Feedback Scheduling, , Threads FAQ, Project 1--Threads -@section Multilevel Feedback Scheduling +@node Multilevel Feedback Scheduling, Coding Standards, Project 4--File Systems, Top +@appendix Multilevel Feedback Scheduling This section gives a brief overview of the behavior of the Solaris 2.6 Time-Sharing (TS) scheduler, an example of a Multilevel Feedback Queue @@ -37,7 +37,7 @@ scheduled if a lower priority process is running on the CPU. @end menu @node Scheduling in Solaris -@subsection Scheduling in Solaris +@section Scheduling in Solaris The Solaris operating system is based on Unix System V Release 4 (SVR4). Scheduling in Solaris, as in all SVR4-based schedulers, is @@ -97,7 +97,7 @@ class. Note the priorities of each of the processes, as listed in the fifth column. @node Class Independent Functionality -@subsection Class Independent Functionality +@section Class Independent Functionality The class independent routines arbitrate across the scheduling classes. This involves three basic responsibilities. @@ -120,7 +120,7 @@ must be moved between blocked and ready queues. @end itemize @node Time-Sharing Scheduling Class -@subsection Time-Sharing Scheduling Class +@section Time-Sharing Scheduling Class The time-sharing scheduler in Solaris is an example of a multi-level feedback queue scheduler. A job begins at priority 29. Compute-bound @@ -134,7 +134,7 @@ time-slice. Its priority is raised if it has not consumed its time-slice before a starvation interval expires. @node Dispatch Table -@subsection Dispatch Table +@section Dispatch Table The durations of the time-slices, the changes in priorities, and the starvation interval are specified in a user-tunable dispatch table. @@ -256,7 +256,7 @@ levels after it consumes its time-slice. The priority of a process is increased to 50 or above when the starvation timer expires. @node Implementation -@subsection Implementation +@section Implementation For each job in the TS class, the following data structure is maintained (we've removed a few of the fields for simplicity): @@ -332,7 +332,7 @@ preempted thread is added to the front of its priority queue. @end table @node Fairness -@subsection Fairness +@section Fairness The Solaris time-sharing scheduler approximates fair allocations by decreasing the priority of a job the more that it is scheduled. @@ -367,7 +367,7 @@ amount of time in a dedicated environment. @image{mlfqs2} @node Project Requirements -@subsection Project Requirements +@section Project Requirements For your project, you need to implement code that is similar in functionality to the Solaris TS scheduler, but your code does not have diff --git a/doc/projects.texi b/doc/projects.texi index 4c1465f..08ee9e5 100644 --- a/doc/projects.texi +++ b/doc/projects.texi @@ -7,6 +7,8 @@ * Project 2--User Programs:: * Project 3--Virtual Memory:: * Project 4--File Systems:: +* Multilevel Feedback Scheduling:: +* Coding Standards:: @end menu @include intro.texi @@ -15,4 +17,5 @@ @include vm.texi @include filesys.texi @c @include devel.texi -@c @include standards.texi +@include mlfqs.texi +@include standards.texi diff --git a/doc/standards.texi b/doc/standards.texi new file mode 100644 index 0000000..28bfc81 --- /dev/null +++ b/doc/standards.texi @@ -0,0 +1,202 @@ +@node Coding Standards, , Multilevel Feedback Scheduling, Top +@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. + +@menu +* Coding Style:: +* Conditional Compilation:: +@end menu + +@node Coding Style +@section Style + +Style, for the purposes of our grading, refers to how readable your +code is. At minimum, this means that your code is well formatted, your +variable names are descriptive and your functions are decomposed and +well commented. Any other factors which make it hard (or easy) for us +to read or use your code will be reflected in your style grade. + +The existing Pintos code is written in the GNU style and largely +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. + +@node Conditional Compilation +@section Conditional Compilation + +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.: + +@example +#ifdef @var{NAME} +@dots{}your code@dots{} +#endif +@end example + +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. + +@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 +mostly in new headers: + +@table @file +@item +Defines macros @code{bool}, a 1-bit type that takes on only the values +0 and 1, @code{true}, which expands to 1, and @code{false}, which +expands to 0. + +@item +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 +types, respectively, with the given number of bits. + +On systems where it is possible, this header also defines types +@code{intptr_t} and @code{uintptr_t}, which are integer types big +enough to hold a pointer. + +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. + +For every signed integer type @code{@var{type}_t} it defines, as well +as for @code{ptrdiff_t} defined in @file{}, this header also +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 +in @file{}, this header defines a @code{@var{type}_MAX} +macro giving its maximum value. + +@item +@file{} is useful on its own, but it provides no way to pass +the types it defines to @code{printf()} and related functions. This +header provides macros to help with that. For every +@code{int@var{n}_t} defined by @file{}, it provides macros +@code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of +that type with @code{"%d"} and @code{"%i"}. Similarly, for every +@code{uint@var{n}_t}, it provides @code{PRIo@var{n}}, +@code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}. + +You use these something like this, taking advantage of the fact that +the C compiler concatenates adjacent string literals: +@example +#include +@dots{} +int32_t value = @dots{}; +printf ("value=%08"PRId32"\n"); +@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. + +@item +The @file{printf()} function has some new type modifiers for printing +standard types: + +@table @samp +@item j +For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@: +@samp{%ju}). + +@item z +For @code{size_t} (e.g.@: @samp{%zu}). + +@item t +For @code{ptrdiff_t} (e.g.@: @samp{%td}). +@end table +@end table + +@node Unsafe String Functions +@section Unsafe String Functions + +A few of the string functions declared in the standard +@file{} and @file{} headers are notoriously unsafe. +The worst offenders are intentionally not included in the Pintos C +library: + +@table @code +@item strcpy() +When used carelessly this function can overflow the buffer reserved +for its output string. Use @code{strlcpy()} instead. Refer to +comments in its source code in @code{lib/string.c} for documentation. + +@item strncpy() +This function can leave its destination buffer without a null string +terminator and it has performance problems besides. Again, use +@code{strlcpy()}. + +@item strcat() +Same issue as @code{strcpy()}, but substitute @code{strlcat()}. +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 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 +@code{lib/string.c} for documentation and an example. + +@item sprintf() +Same issue as @code{strcpy()}. Use @code{snprintf()} instead. Refer +to comments in @code{lib/stdio.h} for documentation. + +@item vsprintf() +Same issue as @code{strcpy()}. Use @code{vsnprintf()} instead. +@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 +@code{dont_use_sprintf_use_snprintf}. diff --git a/doc/threads.texi b/doc/threads.texi index 7a048e7..c1fcfff 100644 --- a/doc/threads.texi +++ b/doc/threads.texi @@ -582,5 +582,3 @@ However, you are free to do so. No. Hard-coding the dispatch table values is fine. @end enumerate @end enumerate - -@include mlfqs.texi diff --git a/doc/userprog.texi b/doc/userprog.texi index 5f270e1..64d429f 100644 --- a/doc/userprog.texi +++ b/doc/userprog.texi @@ -477,7 +477,7 @@ e.g.@: @samp{example 1 2 3 4: 0}. @end enumerate @node 80x86 Calling Convention -@appendixsec 80@var{x}86 Calling Convention +@section 80@var{x}86 Calling Convention What follows is a quick and dirty discussion of the 80@var{x}86 calling convention. Some of the basics should be familiar from CS @@ -627,7 +627,7 @@ address space, in the page just below virtual address @code{PHYS_BASE} (defined in @file{threads/mmu.h}). @node System Calls -@appendixsec System Calls +@section System Calls We have already been dealing with one way that the operating system can regain control from a user program: interrupts from timers and I/O