From 209f0b74c71b4eb5fed33ff4fa1271d3bc35b127 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sun, 26 Sep 2004 07:58:01 +0000 Subject: [PATCH] Update docs. --- doc/filesys.texi | 30 +++++-------- doc/pintos.css | 77 +++------------------------------ doc/threads.texi | 110 +++++++++++++++++++++++++++++++++++++++++++++-- doc/vm.texi | 5 ++- src/TODO | 5 +-- 5 files changed, 129 insertions(+), 98 deletions(-) diff --git a/doc/filesys.texi b/doc/filesys.texi index 7f739bf..b496de7 100644 --- a/doc/filesys.texi +++ b/doc/filesys.texi @@ -24,10 +24,6 @@ filesystem implementation. Your submission should define @code{THREAD_JOIN_IMPLEMENTED} in @file{constants.h} (@pxref{Conditional Compilation}). -FIXME FIXME FIXME -The first step is to understand the default filesystem provided by the -base code. - @menu * File System New Code:: * Problem 4-1 Large Files:: @@ -212,17 +208,16 @@ request for disk block 2 is handled asynchronously. In other words, the process will block to wait for disk block 1, but should not block waiting for disk block 2. -FIXME When you're implementing this, please make sure you have a scheme for making any read-ahead and write-behind threads halt when Pintos is ``done'' (when the user program has completed, etc), so that Pintos -will halt normally and print its various statistics. +will halt normally and the disk contents will be consistent. @node File System Design Document Requirements @section Design Document Requirements As always, submit a design document file summarizing your design. Be -sure to cover the following points : +sure to cover the following points: @itemize @bullet @item @@ -279,24 +274,21 @@ document. @b{What exec modes for running Pintos do I absolutely need to support?} -FIXME FIXME -The most standard mode is to run your Pintos with all the command -flags on one command line, like this: @samp{pintos -f -cp shell -shell -ex "shell"}. However, you also need to support these flags -individually---especially since that's how the grader tests your -program. Thus, you should be able to run the above instead as: +You also need to support the @option{-f}, @option{-ci}, and +@option{-ex} flags individually, and you need to handle them when +they're combined, like this: @samp{pintos -f -ci shell 12345 -ex +"shell"}. Thus, you should be able to treat the above as equivalent +to: -FIXME @example pintos -f -pintos -cp shell shell +pintos -ci shell 12345 pintos -ex "shell" @end example -Note that this also provides a way for you to validate that your disks -are really persistent. This is a common problem with a write behind -cache: if you don't shut down properly it will leave the disk in an -inconsistent state. +If you don't change the filesystem interface, then this should already +be implemented properly in @file{threads/init.c} and +@file{filesys/fsutil.c}. @item @b{Will you test our file system with a different @code{DISK_SECTOR_SIZE}?} diff --git a/doc/pintos.css b/doc/pintos.css index b00c2ce..3dee90c 100644 --- a/doc/pintos.css +++ b/doc/pintos.css @@ -1,11 +1,12 @@ body { background: white; color: black; - padding: 0em 12em 0em 3em; + padding: 0em 1em 0em 3em; margin: 0 } body>p { - margin: 0pt 0pt 0pt 0em + margin: 0pt 0pt 0pt 0em; + text-align: justify } body>p + p { margin: .75em 0pt 0pt 0pt @@ -54,75 +55,11 @@ a:hover { text-decoration: underline } -div.menu { - margin: 0; - font-size: 80%; - font-weight: bold; - line-height: 1.1; - text-align: center; - position: absolute; - top: 2em; - left: auto; - width: 8.5em; - right: 2em; -} -div.menu p, span.menuitem { - display: block; - margin: 0; - padding: 0.3em 0.4em; - font-family: Arial, sans-serif; - background: #ddd; - border: thin outset #000; - color: #000; - text-indent: 0em; -} -IMG.menuimg { - width: 50%; - height: auto; - border-width: 0 -} - -div.menu a, div.menu em { - display: block; - margin: 0 0.5em -} -div.menu a, div.menu em { - border-top: 2px groove #000 -} -div.menu a:first-child { - border-top: none -} -div.menu em { - color: #fff -} - -div.menu a:link { - text-decoration: none; - color: blue -} -div.menu a:visited { - text-decoration: none; - color: gray -} -div.menu a:hover { - background: blue; - color: white -} - -div.menu span.menugap + span.menuitem { - display: block; - margin-top: 1em -} - -span.hide { - display: none -} - -body>div.menu { - position: fixed -} - address { font-size: 90%; font-style: normal } + +HR { + display: none +} diff --git a/doc/threads.texi b/doc/threads.texi index 451eff8..6a36e08 100644 --- a/doc/threads.texi +++ b/doc/threads.texi @@ -74,7 +74,7 @@ thing the new thread does is to return from @code{switch_threads()}. We realize this comment will seem cryptic to you at this point, but you will understand threads once you understand why the @code{switch_threads()} that gets called is different from the -@code{switch_threads()} that returns. @c FIXME +@code{switch_threads()} that returns. @strong{Warning}: In Pintos, each thread is assigned a small, fixed-size execution stack just under @w{4 kB} in size. The kernel @@ -133,12 +133,13 @@ above. @item palloc.c @itemx palloc.h -Page allocator, which hands out system memory one 4 kB page at a time. +Page allocator, which hands out system memory in multiples of 4 kB +pages. @item malloc.c @itemx malloc.h A very simple implementation of @code{malloc()} and @code{free()} for -the kernel. The largest block that can be allocated is 2 kB. +the kernel. @item interrupt.c @itemx interrupt.h @@ -170,7 +171,108 @@ directories and page tables. This will be more important to you in project 3. For now, you can ignore it. @end table -FIXME devices and lib directories? +@menu +* devices code:: +* lib files:: +@end menu + +@node devices code +@subsection @file{devices} code + +The basic threaded kernel also includes these files in the +@file{devices} directory: + +@table @file +@item timer.c +@itemx timer.h +System timer that ticks, by default, 100 times per second. You will +modify this code in Problem 1-1. + +@item vga.c +@itemx vga.h +VGA display driver. Responsible for writing text to the screen. +You should have no need to look at this code. @code{printf()} will +call into the VGA display driver for you, so there's little reason to +call this code yourself. + +@item serial.c +@itemx serial.h +Serial port driver. Again, @code{printf()} calls this code for you, +so you don't need to do so yourself. Feel free to look through it if +you're curious. + +@item disk.c +@itemx disk.h +Supports reading and writing sectors on up to 4 IDE disks. This won't +actually be used until project 2. + +@item intq.c +@itemx intq.h +Interrupt queue, for managing a circular queue that both kernel +threads and interrupt handlers want to access. Used by the keyboard +and serial drivers. +@end table + +@node lib files +@subsection @file{lib} files + +Finally, @file{lib} and @file{lib/kernel} contain useful library +routines. (@file{lib/user} will be used by user programs, starting in +project 2, but it is not part of the kernel.) Here's a few more +details: + +@table @file +@item ctype.h +@itemx inttypes.h +@itemx limits.h +@itemx stdarg.h +@itemx stdbool.h +@itemx stddef.h +@itemx stdint.h +@itemx stdio.c +@itemx stdio.h +@itemx stdlib.c +@itemx stdlib.h +@itemx string.c +@itemx string.h +Implementation of the standard C library. @xref{C99}, for information +on a few recently introduced pieces of the C library that you might +not have encountered before. @xref{Unsafe String Functions}, for +information on what's been intentionally left out for safety. + +@item debug.c +@itemx debug.h +Functions and macros to aid debugging. @xref{Debugging Tools}, for +more information. + +@item random.c +@itemx random.h +Pseudo-random number generator. + +@item round.h +Macros for rounding. + +@item syscall-nr.h +System call numbers. Not used until project 2. + +@item kernel/list.c +@itemx kernel/list.h +Doubly linked list implementation. Used all over the Pintos code, and +you'll probably want to use it a few places yourself in project 1. + +@item kernel/bitmap.c +@itemx kernel/bitmap.h +Bitmap implementation. You can use this in your code if you like, but +you probably won't have any need for project 1. + +@item kernel/hash.c +@itemx kernel/hash.h +Hash table implementation. Likely to come in handy for project 3. + +@item kernel/console.c +@itemx kernel/console.h +Implements @code{printf()} and a few other functions. +@end table @node Debugging versus Testing @section Debugging versus Testing diff --git a/doc/vm.texi b/doc/vm.texi index 6f4428e..094d182 100644 --- a/doc/vm.texi +++ b/doc/vm.texi @@ -528,8 +528,9 @@ the linker manual, accessible via @samp{info ld}. @item @b{Do page tables need to created lazily?} -No. You can create the page tables at load time (or @code{mmap} time) -if you like. +No. You can create the page tables at load time (or @code{mmap} +time). Real OSes often manage their page tables lazily, but it's just +an unneeded complication for our purposes. @item @b{Our code handles the PageFault exceptions. However, the number of diff --git a/src/TODO b/src/TODO index 681fded..a234cfc 100644 --- a/src/TODO +++ b/src/TODO @@ -1,3 +1,5 @@ +* Add stats. + * Write, test VM. * Handling of read-only pages? @@ -5,9 +7,6 @@ * Test list, hash ADTs. - Finish comments for hash.[ch]. -* Compile and install gdb, dbg versions. - - Test gdb version. - * References/bibliography. - Userprog refers to [SysV-i386]. -- 2.30.2