Add suggested implementations for filesys syscalls.

Clarify write syscall description.

diff --git a/doc/userprog.texi b/doc/userprog.texi
index 65932604d7099a7d0ae374a63f9b6e0249e9e723..bd2dfd9180e12acea78fb72c8a4ccf909ea38c70 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -568,11 +568,15 @@ waits for @var{B}, then @var{A} waits for @var{C}), and so on.
 @deftypefn {System Call} bool create (const char *@var{file}, unsigned @var{initial_size})
 Creates a new file called @var{file} initially @var{initial_size} bytes
 in size.  Returns true if successful, false otherwise.
 @deftypefn {System Call} bool create (const char *@var{file}, unsigned @var{initial_size})
 Creates a new file called @var{file} initially @var{initial_size} bytes
 in size.  Returns true if successful, false otherwise.

+
+Consider implementing this function in terms of @func{filesys_create}.

 @end deftypefn
 
 @deftypefn {System Call} bool remove (const char *@var{file})
 Deletes the file called @var{file}.  Returns true if successful, false
 otherwise.
 @end deftypefn
 
 @deftypefn {System Call} bool remove (const char *@var{file})
 Deletes the file called @var{file}.  Returns true if successful, false
 otherwise.

+
+Consider implementing this function in terms of @func{filesys_remove}.

 @end deftypefn
 
 @deftypefn {System Call} int open (const char *@var{file})
 @end deftypefn
 
 @deftypefn {System Call} int open (const char *@var{file})


@@ -585,10 +589,14 @@ File descriptors numbered 0 and 1 are reserved for the console: fd 0
 is standard input (@code{stdin}), fd 1 is standard output
 (@code{stdout}).  These special file descriptors are valid as system
 call arguments only as explicitly described below.
 is standard input (@code{stdin}), fd 1 is standard output
 (@code{stdout}).  These special file descriptors are valid as system
 call arguments only as explicitly described below.

+
+Consider implementing this function in terms of @func{filesys_open}.

 @end deftypefn
 
 @deftypefn {System Call} int filesize (int @var{fd})
 Returns the size, in bytes, of the file open as @var{fd}.
 @end deftypefn
 
 @deftypefn {System Call} int filesize (int @var{fd})
 Returns the size, in bytes, of the file open as @var{fd}.

+
+Consider implementing this function in terms of @func{file_length}.

 @end deftypefn
 
 @deftypefn {System Call} int read (int @var{fd}, void *@var{buffer}, unsigned @var{size})
 @end deftypefn
 
 @deftypefn {System Call} int read (int @var{fd}, void *@var{buffer}, unsigned @var{size})


@@ -597,6 +605,8 @@ Reads @var{size} bytes from the file open as @var{fd} into
 file), or -1 if the file could not be read (due to a condition other
 than end of file).  Fd 0 reads from the keyboard using
 @func{kbd_getc}.
 file), or -1 if the file could not be read (due to a condition other
 than end of file).  Fd 0 reads from the keyboard using
 @func{kbd_getc}.

+
+Consider implementing this function in terms of @func{file_read}.

 @end deftypefn
 
 @deftypefn {System Call} int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})
 @end deftypefn
 
 @deftypefn {System Call} int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})


@@ -604,11 +614,18 @@ Writes @var{size} bytes from @var{buffer} to the open file @var{fd}.
 Returns the number of bytes actually written, or -1 if the file could
 not be written.
 
 Returns the number of bytes actually written, or -1 if the file could
 not be written.
 

+Writing past end-of-file would normally extend the file, but file growth
+is not implemented by the basic file system.  The expected behavior is
+to write as many bytes as possible up to end-of-file and return the
+actual number written, or -1 if no bytes could be written at all.
+

 Fd 1 writes to the console.  Your code to write to the console should
 write all of @var{buffer} in one call to @func{putbuf}, at least as
 long as @var{size} is not bigger than a few hundred bytes.  Otherwise,
 lines of text output by different processes may end up interleaved on
 the console, confusing both human readers and our grading scripts.
 Fd 1 writes to the console.  Your code to write to the console should
 write all of @var{buffer} in one call to @func{putbuf}, at least as
 long as @var{size} is not bigger than a few hundred bytes.  Otherwise,
 lines of text output by different processes may end up interleaved on
 the console, confusing both human readers and our grading scripts.

+
+Consider implementing this function in terms of @func{file_write}.

 @end deftypefn
 
 @deftypefn {System Call} void seek (int @var{fd}, unsigned @var{position})
 @end deftypefn
 
 @deftypefn {System Call} void seek (int @var{fd}, unsigned @var{position})


@@ -623,15 +640,21 @@ have a fixed length until project 4 is complete, so writes past end of
 file will return an error.)  These semantics are implemented in the
 file system and do not require any special effort in system call
 implementation.
 file will return an error.)  These semantics are implemented in the
 file system and do not require any special effort in system call
 implementation.

+
+Consider implementing this function in terms of @func{file_seek}.

 @end deftypefn
 
 @deftypefn {System Call} unsigned tell (int @var{fd})
 Returns the position of the next byte to be read or written in open
 file @var{fd}, expressed in bytes from the beginning of the file.
 @end deftypefn
 
 @deftypefn {System Call} unsigned tell (int @var{fd})
 Returns the position of the next byte to be read or written in open
 file @var{fd}, expressed in bytes from the beginning of the file.

+
+Consider implementing this function in terms of @func{file_tell}.

 @end deftypefn
 
 @deftypefn {System Call} void close (int @var{fd})
 Closes file descriptor @var{fd}.
 @end deftypefn
 
 @deftypefn {System Call} void close (int @var{fd})
 Closes file descriptor @var{fd}.

+
+Consider implementing this function in terms of @func{file_close}.

 @end deftypefn
 
 The file defines other syscalls.  Ignore them for now.  You will
 @end deftypefn
 
 The file defines other syscalls.  Ignore them for now.  You will