started commenting

student-distrib/syscall.c

 #include "syscall.h"
 
-/*
- *The halt system call
+/* The halt system call
  *
- *DESCRIPTION: This function terminates a process, returning the specified value to its parent process.
- *INPUT: status --
- *RETURN:
+ * int32_t halt (uint8_t status)
  *
+ * DESCRIPTION: This function terminates a process, returning the specified value to its parent process.
+ * 
+ * INPUT:       status --
+ * 
+ * RETURN:
  */
-int32_t halt (uint8_t status){
+int32_t halt (uint8_t status)
+{
 
     int i;
     cli();
 
     pcb_t* pcb_cur =  terminal[running_terminal].pcb;
-    //pcb_t* pcb_cur = current_pcb();
 
     // printf("[halt] running_terminal = %d\n", running_terminal);
 
@@ -71,20 +73,24 @@ int32_t halt (uint8_t status){
     return 0;
 }
 
-/*
- *The execute system call
- *
- *DESCRIPTION: This function attempts to load and execute a new program,
- *             handing off the processor to the new program until it terminates.
- *INPUT: command -- a space-separated sequence of words. The first word is the file name
- *                  of the program to be executed, and the rest of the command—stripped
- *                  of leading spaces—should be provided to the new program on request
- *                  via the getargs system call.
- *RETURN: -1     if the command cannot be executed. (for example, program does not exist / the file not executable,)
- *       256     if the program dies by an exception.
- *        0-255  if the program executes a halt system call. (in which case the value returned is that given by the program’s call to halt)
+/* The execute system call
+ *
+ * int32_t execute(const uint8_t* command)
+ *
+ * DESCRIPTION: This function attempts to load and execute a new program,
+ *              handing off the processor to the new program until it terminates.
+ *
+ * INPUT:       command -- a space-separated sequence of words. The first word is the file name
+ *                        of the program to be executed, and the rest of the command—stripped
+ *                        of leading spaces—should be provided to the new program on request
+ *                        via the getargs system call.
+ *
+ * RETURN:      -1    -- if the command cannot be executed. (for example, program does not exist / the file not executable,)
+ *              256   -- if the program dies by an exception.
+ *              0-255 -- if the program executes a halt system call. (in which case the value returned is that given by the program’s call to halt)
  */
-int32_t  execute(const uint8_t* command){
+int32_t execute(const uint8_t* command)
+{
 
     cli();
 
@@ -231,41 +237,42 @@ int32_t  execute(const uint8_t* command){
         return 0;
 }
 
-/*
- *The read system call
+/* The read system call
  *
- *DISCRIPTION: This function reads data from the keyboard, a file, device (RTC), or directory.
- *             This function use a jump table referenced by the task’s file array to call
- *             from a generic handler for this call into a file-type-specific function.
- *             This jump table is inserted into the file array on the open system call.
+ * int32_t read(int32_t fd_n, void* buf, int32_t nbytes)
  *
- *        case 1 - keyboard   : return data from one line that has been terminated by pressing
- *                              Enter, or as much as fits in the buffer from one such line.
- *                              The line returned should include the line feed character.
+ * DESCRIPTION: This function reads data from the keyboard, a file, device (RTC), or directory.
+ *              This function use a jump table referenced by the task’s file array to call
+ *              from a generic handler for this call into a file-type-specific function.
+ *              This jump table is inserted into the file array on the open system call.
  *
- *        case 2 - file       : data should be read to the end of the file or the end of the
- *                              buffer provided, whichever occurs sooner.
+ *              case 1 - keyboard   : return data from one line that has been terminated by pressing
+ *                                    Enter, or as much as fits in the buffer from one such line.
+ *                                    The line returned should include the line feed character.
  *
- *        case 3 - device(RTC): this call should always return 0, but only after an interrupt
- *                              has occurred (set a flag and wait until the interrupt handler
- *                              clears it, then return 0).
+ *              case 2 - file       : data should be read to the end of the file or the end of the
+ *                                    buffer provided, whichever occurs sooner.
  *
- *        case 4 - directory  : only the filename should be provided (as much as fits, max 32 bytes),
- *                              and subsequent reads should read from successive directory entries
- *                              until the last is reached, at which point read should repeatedly
- *                              return 0.
+ *              case 3 - device(RTC): this call should always return 0, but only after an interrupt
+ *                                    has occurred (set a flag and wait until the interrupt handler
+ *                                    clears it, then return 0).
  *
- *INPUT: fd -- file discriptor
- *       buf -- buffer that store the file
- *       nbytes -- the number of bytes that need to read
+ *              case 4 - directory  : only the filename should be provided (as much as fits, max 32 bytes),
+ *                                    and subsequent reads should read from successive directory entries
+ *                                    until the last is reached, at which point read should repeatedly
+ *                                    return 0.
+ *
+ * INPUT:       fd     -- file discriptor
+ *              buf    -- buffer that store the file
+ *              nbytes -- the number of bytes that need to read
  *
- *RETURN: 1. the number of bytes read when success
- *        2. 0 when the initial file position is at or beyond the end of file,
- *           for normal files and the directory
- *        3. -1 when there fd are out of range or indicate to STDOUT_FD
+ * RETURN:      1. the number of bytes read when success
+ *              2. 0 when the initial file position is at or beyond the end of file,
+ *                 for normal files and the directory
+ *              3. -1 when there fd are out of range or indicate to STDOUT_FD
  */
-int32_t read (int32_t fd_n, void* buf, int32_t nbytes){
-
+int32_t read(int32_t fd_n, void* buf, int32_t nbytes)
+{
     int32_t ret;
 
     if (fd_check(fd_n) < 0 || fd_n == STDOUT_FD) return -1; // invalid fd
@@ -274,15 +281,9 @@ int32_t read (int32_t fd_n, void* buf, int32_t nbytes){
 
     if (nbytes < 0) return -1; // invalid nbytes
 
-    //terminal[running_terminal].pcb = current_pcb();
-
-    /* Enable for keyboard interrupts */
-    //sti();
-
     ret = terminal[running_terminal].pcb->fd[fd_n].fileop_ptr.read(fd_n, buf, nbytes);
 
     return ret;
-
 }
 
 /*
@@ -391,55 +392,55 @@ int32_t open (const uint8_t* filename){
     return fd;
 }
 
-/*
- *The close system call
- *
- *DISCRIPTION: This function closes the specified file descriptor and makes it available
- *             for return from later calls to open.
- *NOTE: the default descriptors (0 for input and 1 for output) can't be closed
- *INPUT: fd -- file discriptor for the file that we want to close
- *RETURN: 1. -1 when Trying to close an invalid descriptor
- *        2. 0  when successful closes the file.
+/* The close system call
+ *
+ * int32_t close (int32_t fd)
+ *
+ * DESCRIPTION: This function closes the specified file descriptor and makes it available
+ *              for return from later calls to open.
+ *
+ * NOTE:        the default descriptors (0 for input and 1 for output) can't be closed
+ *
+ * INPUT:       fd -- file discriptor for the file that we want to close
+ *
+ * RETURN:      -1 -- when Trying to close an invalid descriptor
+ *               0 -- when successful closes the file.
  */
-int32_t close (int32_t fd){
+int32_t close (int32_t fd)
+{
+    if(fd_check(fd) < 0 || fd < USER_FILE_START)
+        return -1; // invalid fd
 
-    if (fd_check(fd) < 0 || fd < USER_FILE_START) return -1; // invalid fd
+    terminal[running_terminal].pcb->fd[fd].fileop_ptr.close(fd);
 
-     //terminal[ running_terminal].pcb = current_pcb();
-
-    //sti();
-
-     terminal[ running_terminal].pcb->fd[fd].fileop_ptr.close(fd);
-        
     fd_clear(fd);
-    
+
     return 0;
-    
 }
 
 /*
  *The getargs system call
  *
- *DISCRIPTION: This function reads the program’s command line arguments into a user-level buffer.
- *             These arguments are stored as part of the task data when a new program is loaded.
- *             Here they are merely copied into user space.
+ * DESCRIPTION: This function reads the program’s command line arguments into a user-level buffer.
+ *              These arguments are stored as part of the task data when a new program is loaded.
+ *              Here they are merely copied into user space.
  *
- *INPUT: buf -- buffer that holds the file
- *       nbytes -- number of bytes that we want to operate
+ * INPUT:       buf    -- buffer that holds the file
+ *              nbytes -- number of bytes that we want to COPY
  *
- *RETURN: -1 If there are no arguments, or if the arguments and a terminal NULL (0-byte) do not fit in the buffer.
+ * RETURN:      -1 If there are no arguments, or if the arguments and a terminal NULL (0-byte) do not fit in the buffer.
  *
- *NOTE: The shell does not request arguments, but you should probably still
- *      initialize the shell task’s argument data to the empty string.
+ * NOTE:        The shell does not request arguments, but you should probably still
+ *              initialize the shell task’s argument data to the empty string.
  */
 int32_t getargs (uint8_t* buf, int32_t nbytes){
 
     uint8_t* argument;
 
      //terminal[ running_terminal].pcb = current_pcb();
-    argument = (uint8_t*) ( terminal[ running_terminal].pcb->argv);
+    argument = (uint8_t*) (terminal[running_terminal].pcb->argv);
 
-    if(  terminal[ running_terminal].pcb->arg_num == 0 || nbytes <= 0 )
+    if( terminal[running_terminal].pcb->arg_num == 0 || nbytes <= 0 )
     {
         //printf("[getargs] return -1\n");
         return -1; //If there are no arguments
@@ -458,25 +459,26 @@ int32_t getargs (uint8_t* buf, int32_t nbytes){
     return 0;
 }
 
-/*
- *The vidmap system call
+/* int32_t vidmap (uint8_t** screen_start)
  *
- *DESCRIPTION: This function maps the text-mode video memory into user space at a pre-set virtual address.
- *             Although the address returned is always the same, it should be written into the memory
- *             location provided by the caller (which must be checked for validity).
+ * The vidmap system call
  *
- *INPUT: screen_start --
+ * DESCRIPTION: This function maps the text-mode video memory into user space at a pre-set virtual address.
+ *              Although the address returned is always the same, it should be written into the memory
+ *              location provided by the caller (which must be checked for validity).
  *
- *RETURN: -1 If the location is invalid.
+ * INPUT:       screen_start --
  *
- *NOTE:1. To avoid adding kernel-side exception handling for this sort of check, you can simply
- *        check whether the address falls within the address range covered by the single user-level page.
- *     2. The video memory will require you to add another page mapping for the program, in this case
- *        a 4 kB page. It is not ok to simply change the permissions of the video page located < 4MB
- *        and pass that address
+ * RETURN:      -1 If the location is invalid.
+ *
+ * NOTE:        1. To avoid adding kernel-side exception handling for this sort of check, you can simply
+ *                 check whether the address falls within the address range covered by the single user-level page.
+ *              2. The video memory will require you to add another page mapping for the program, in this case
+ *                 a 4 kB page. It is not ok to simply change the permissions of the video page located < 4MB
+ *                 and pass that address
  */
-int32_t vidmap (uint8_t** screen_start){
-
+int32_t vidmap (uint8_t** screen_start)
+{
     /* Check for valid argument */
     if ( screen_start == NULL)
         return -1;
@@ -492,27 +494,28 @@ int32_t vidmap (uint8_t** screen_start){
 
     *screen_start = (uint8_t *)(0x8400000);
 
-    //screen_start =  terminal[ running_terminal].vid_mem;
-
-
     return 0x8400000;
 }
 
 /*
- *The set handler system calls
+ * The set handler system calls
+ *
+ * DESCRIPTION: This function are related to signal handling and are discussed in the section Signals below.
+ *
+ * INPUT:       signum --
+ *              handler_address --
  *
- *DISCRIPTION: This function are related to signal handling and are discussed in the section Signals below.
- *INPUT: signum --
- *       handler_address --
- *RETURN:
+ * RETURN:
  *
- *NOTE: Even if your operating system does not support signals, you must support these system calls;
- *      in such a case, however, you may immediately return failure from these calls.
+ * NOTE:        Even if your operating system does not support signals, you must support these system calls;
+ *              in such a case, however, you may immediately return failure from these calls.
  */
-int32_t set_handler (int32_t signum, void* handler_address){
+int32_t set_handler (int32_t signum, void* handler_address)
+{
     return -1;
 }
 
-int32_t sigreturn (void){
+int32_t sigreturn (void)
+{
     return -1;
 }