Add an identifier to each question in the design document templates,
[pintos-anon] / doc / userprog.tmpl
index a8b4269e9c5c1de6025b289a91afd490c3ea3cbd..1cf7ed7aca78c70366863f15dfc2737ea9b043ec 100644 (file)
@@ -26,87 +26,90 @@ FirstName LastName <email@domain.example>
 
 ---- DATA STRUCTURES ----
 
->> Copy here the declaration of each new or changed `struct' or `struct'
->> member, global or static variable, `typedef', or enumeration.
->> Identify the purpose of each in 25 words or less.
+>> A1: Copy here the declaration of each new or changed `struct' or
+>> `struct' member, global or static variable, `typedef', or
+>> enumeration.  Identify the purpose of each in 25 words or less.
 
 ---- ALGORITHMS ----
 
->> Briefly describe how you implemented argument parsing.  How do you
->> arrange for the elements of argv[] to be in the right order?  How do
->> you avoid overflowing the stack page?
+>> A2: Briefly describe how you implemented argument parsing.  How do
+>> you arrange for the elements of argv[] to be in the right order?
+>> How do you avoid overflowing the stack page?
 
 ---- RATIONALE ----
 
->> Why does Pintos implement strtok_r() but not strtok()?
+>> A3: Why does Pintos implement strtok_r() but not strtok()?
 
->> In Pintos, the kernel separates commands into a executable name and
->> arguments.  In Unix-like systems, the shell does this separation.
->> Identify at least two advantages of the Unix approach.
+>> A4: In Pintos, the kernel separates commands into a executable name
+>> and arguments.  In Unix-like systems, the shell does this
+>> separation.  Identify at least two advantages of the Unix approach.
 
                             SYSTEM CALLS
                             ============
 
 ---- DATA STRUCTURES ----
 
->> Copy here the declaration of each new or changed `struct' or `struct'
->> member, global or static variable, `typedef', or enumeration.
->> Identify the purpose of each in 25 words or less.
+>> B1: Copy here the declaration of each new or changed `struct' or
+>> `struct' member, global or static variable, `typedef', or
+>> enumeration.  Identify the purpose of each in 25 words or less.
 
->> Describe how file descriptors are associated with open files.  Are
->> file descriptors unique within the entire OS or just within a single
->> process?
+>> B2: Describe how file descriptors are associated with open files.
+>> Are file descriptors unique within the entire OS or just within a
+>> single process?
 
 ---- ALGORITHMS ----
 
->> Describe your code for reading and writing user data from the kernel.
-
->> Suppose a system call causes a full page (4,096 bytes) of data to be
->> copied from user space into the kernel.  What is the least and the
->> greatest possible number of inspections of the page table (e.g. calls
->> to pagedir_get_page()) that might result?  What about for a system
->> call that only copies 2 bytes of data?  Is there room for improvement
->> in these numbers, and how much?
-
->> Briefly describe your implementation of the "wait" system call and how
->> it interacts with process termination.
-
->> Any access to user program memory at a user-specified address can fail
->> due to a bad pointer value.  Such accesses must cause the process to
->> be terminated.  System calls are fraught with such accesses, e.g. a
->> "write" system call requires reading the system call number from the
->> user stack, then each of the call's three arguments, then an arbitrary
->> amount of user memory, and any of these can fail at any point.  This
->> poses a design and error-handling problem: how do you best avoid
->> obscuring the primary function of code in a morass of error-handling?
->> Furthermore, when an error is detected, how do you ensure that all
->> temporarily allocated resources (locks, buffers, etc.) are freed?  In
->> a few paragraphs, describe the strategy or strategies you adopted for
+>> B3: Describe your code for reading and writing user data from the
+>> kernel.
+
+>> B4: Suppose a system call causes a full page (4,096 bytes) of data
+>> to be copied from user space into the kernel.  What is the least
+>> and the greatest possible number of inspections of the page table
+>> (e.g. calls to pagedir_get_page()) that might result?  What about
+>> for a system call that only copies 2 bytes of data?  Is there room
+>> for improvement in these numbers, and how much?
+
+>> B5: Briefly describe your implementation of the "wait" system call
+>> and how it interacts with process termination.
+
+>> B6: Any access to user program memory at a user-specified address
+>> can fail due to a bad pointer value.  Such accesses must cause the
+>> process to be terminated.  System calls are fraught with such
+>> accesses, e.g. a "write" system call requires reading the system
+>> call number from the user stack, then each of the call's three
+>> arguments, then an arbitrary amount of user memory, and any of
+>> these can fail at any point.  This poses a design and
+>> error-handling problem: how do you best avoid obscuring the primary
+>> function of code in a morass of error-handling?  Furthermore, when
+>> an error is detected, how do you ensure that all temporarily
+>> allocated resources (locks, buffers, etc.) are freed?  In a few
+>> paragraphs, describe the strategy or strategies you adopted for
 >> managing these issues.  Give an example.
 
 ---- SYNCHRONIZATION ----
 
->> The "exec" system call returns -1 if loading the new executable fails,
->> so it cannot return before the new executable has completed loading.
->> How does your code ensure this?  How is the load success/failure
->> status passed back to the thread that calls "exec"?
+>> B7: The "exec" system call returns -1 if loading the new executable
+>> fails, so it cannot return before the new executable has completed
+>> loading.  How does your code ensure this?  How is the load
+>> success/failure status passed back to the thread that calls "exec"?
 
->> Consider parent process P with child process C.  How do you ensure
->> proper synchronization and avoid race conditions when P calls wait(C)
->> before C exits?  After C exits?  How do you ensure that all resources
->> are freed in each case?  How about when P terminates without waiting,
->> before C exits?  After C exits?  Are there any special cases?
+>> B8: Consider parent process P with child process C.  How do you
+>> ensure proper synchronization and avoid race conditions when P
+>> calls wait(C) before C exits?  After C exits?  How do you ensure
+>> that all resources are freed in each case?  How about when P
+>> terminates without waiting, before C exits?  After C exits?  Are
+>> there any special cases?
 
 ---- RATIONALE ----
 
->> Why did you choose to implement access to user memory from the
+>> B9: Why did you choose to implement access to user memory from the
 >> kernel in the way that you did?
 
->> What advantages or disadvantages can you see to your design for file
->> descriptors?
+>> B10: What advantages or disadvantages can you see to your design
+>> for file descriptors?
 
->> The default tid_t to pid_t mapping is the identity mapping.  If you
->> changed it, what advantages are there to your approach?
+>> B11: The default tid_t to pid_t mapping is the identity mapping.
+>> If you changed it, what advantages are there to your approach?
 
                           SURVEY QUESTIONS
                           ================