updated comment regarding per-process open file table

1 files changed, 61 insertions, 29 deletions

diff --git a/src/userprog/flist.h b/src/userprog/flist.h
index 3fcd1d5..eb5626d 100644
--- a/src/userprog/flist.h
+++ b/src/userprog/flist.h
@@ -1,35 +1,67 @@
 #ifndef _MAP_H_
 #define _MAP_H_
 
-/* Place functions to handle a process open files here (file list).
-   
-   flist.h : Your function declarations and documentation.
-   flist.c : Your implementation.
-
-   The following is strongly recommended:
-
-   - A function that given a file (struct file*, see filesys/file.h)
-     and a process id INSERT this in a list of files. Return an
-     integer that can be used to find the opened file later.
-
-   - A function that given an integer (obtained from above function)
-     and a process id FIND the file in a list. Should return NULL if
-     the specified process did not insert the file or already removed
-     it.
-
-   - A function that given an integer (obtained from above function)
-     and a process id REMOVE the file from a list. Should return NULL
-     if the specified process did not insert the file or already
-     removed it.
-   
-   - A function that given a process id REMOVE ALL files the specified
-     process have in the list.
-
-   All files obtained from filesys/filesys.c:filesys_open() are
-   considered OPEN files and must be added to a list or else kept
-   track of, to guarantee ALL open files are eventyally CLOSED
-   (probably when removed from the list(s)).
+/* Place code to keep track of your per-process open file table here.
+ *
+ * (The system-wide open file table exist as part of filesys/inode.c )
+ *
+ * User-mode code use a file by first opening it to retrieve a file
+ * descriptor (integer) that uniquely identifies the open file for the
+ * operation system. This file descriptor is then passed to read or
+ * write to use the file, and finally to close to led the operating
+ * system release any resources associated with the file.
+ *
+ * The kernel use a file in the same way, but use pointer to a file
+ * structure to uniquely identify a file instead of an integer. If we
+ * do not care for security we could pass this pointer directly to
+ * user-mode code when a file is opened and expect the same pointer
+ * back when the file is used in read, write or close.
+ * 
+ * But we do care for security, we want to:
+ *
+ * - Hide kernel addresses and data from (untrusted) user-mode code
+ *
+ * - Perform validity checks that a file descriptor was indeed
+ *   obtained from a call to open by the same process
+ *
+ * - Verify that a file descriptor was not closed
+ *
+ * - Make sure the kernel can close all files associated to a process
+ *   as soon as it terminate
+ *
+ * This is best done by shielding kernel data from user code. Now the
+ * kernel must keep track of which file descriptors a certain process
+ * have open, and which kernel file pointer that are associated to
+ * each file descriptor. This mapping is for you to solve, and the
+ * data structure you need may be places int this file.
+ *
+ * 
+ * User-mode sequence                 Kernel sequence
+ * ------------------                 ---------------
+ *
+ * char buffer[5];                    struct file* fp;
+ *
+ * int   fd = open("example.txt");    fp = filesys_open(...)
+ *       |                            \_________
+ *       |                                      \
+ *       V                                       V
+ * read( fd, buffer, 5);              file_read( fp, ...)
+ *       |                                       |
+ *       V                                       V
+ * write(fd, buffer, 5);              file_write(fp, ...)
+ *       |                                       |
+ *       V                                       V
+ * close(fd);                         file_close(fp);
+ *
+ *
+ * A (very) simple implementation data structure equivalent to a C++
+ * std::map is recommended.
+ *
+ * This structure can be placed either globally or locally for each
+ * process. If you go for a global map, consider how to remember which
+ * process that opened each file. If you go for a local map, consider
+ * where to declare and initialize it correct. In both cases, consider
+ * what size limit that may be appropriate.
  */
 
-
 #endif