From 1bfd73b2020b7beb4c91c67fb35c8c3a1847b57b Mon Sep 17 00:00:00 2001 From: EDiasAlberto Date: Sun, 10 Nov 2024 01:32:48 +0000 Subject: [PATCH] Comment syscall functions and handlers --- src/userprog/syscall.c | 54 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/userprog/syscall.c b/src/userprog/syscall.c index 96c099d..ccb02f3 100644 --- a/src/userprog/syscall.c +++ b/src/userprog/syscall.c @@ -79,6 +79,9 @@ static const syscall_arguments syscall_lookup[] = static const int LOOKUP_SIZE = sizeof (syscall_lookup) / sizeof (syscall_arguments); + +/* Initialises the syscall handling system, as well as a global lock to + synchronise all file access between processes. */ void syscall_init (void) { @@ -86,6 +89,9 @@ syscall_init (void) lock_init (&filesys_lock); } +/* Function that takes a interrupt frame containing a syscall and its args. + Validates the arguments and pointers before calling the relevant + high-level system call function, storing its output (if any) in f->eax */ static void syscall_handler (struct intr_frame *f) { @@ -111,6 +117,8 @@ syscall_handler (struct intr_frame *f) f->eax = syscall.function (args[0], args[1], args[2]); } +/* Called upon a "halt" syscall, resulting in a complete shutdown of the + process, via shutdown_power_off (); */ static void syscall_halt (void) { @@ -126,6 +134,10 @@ syscall_exit (int status) thread_exit (); } +/* Executes a given command with the relevant args, by calling process_execute. + Acquires the filesystem lock as process_execute accesses the file system. + Returns PID for the process that is running the CMD_LINE + */ static pid_t syscall_exec (const char *cmd_line) { @@ -138,12 +150,17 @@ syscall_exec (const char *cmd_line) return pid; } +/* Handles the syscall of wait. Effectively a wrapper for process_wait as the + necessary validation and such all happens in process_wait anyway. */ static int syscall_wait (pid_t pid) { return process_wait (pid); } +/* Handles the syscall for file creation. First validates the user file + pointer. Acquires the file system lock to prevent synchronisation issues, + and then uses FILESYS_CREATE to create the file, returning the same status */ static bool syscall_create (const char *file UNUSED, unsigned initial_size UNUSED) { @@ -156,6 +173,9 @@ syscall_create (const char *file UNUSED, unsigned initial_size UNUSED) return status; } +/* Handles the syscall for file removal. First validates the user file pointer. + Acquires the file system lock to prevent synchronisation issues, and then + uses FILESYS_REMOVE to remove the file, returning the same success status */ static bool syscall_remove (const char *file) { @@ -168,6 +188,10 @@ syscall_remove (const char *file) return status; } +/* Handles the syscall for opening a file connection. First, validates the file + pointer. Then it acquires a lock for the file system, in order to open the + connection without synchronisation issues. It then maps a new fd to this file + in the hash table before returning the fd. */ static int syscall_open (const char *file) { @@ -179,19 +203,27 @@ syscall_open (const char *file) if (ptr == NULL) return -1; + /* Allocate space for a struct representing a mapping from an FD to a struct + file. */ struct open_file *file_info = (struct open_file*) malloc (sizeof (struct open_file)); if (file_info == NULL) return -1; + /* Populate the above struct, with a unique FD and the current open file */ file_info->fd = fd_counter++; file_info->file = ptr; + /* Add the new FD->file mapping to the hashtable for the current thread */ hash_insert (&thread_current ()->open_files, &file_info->elem); + /* Return the new FD */ return file_info->fd; } +/* Handles the syscall for getting a file's size. Converts a provided FD into + the asssociated file struct. Acquire the lock for the filesystem and use + FILE_LENGTH to calculate the length for return. */ static int syscall_filesize (int fd) { @@ -206,6 +238,10 @@ syscall_filesize (int fd) return bytes; } +/* Handles the syscall for reading SIZE bytes from a file referenced by FD. + If the FD references the console, use input_getc (), otherwise convert the + FD to its associated file struct, acquire the filesystem lock, read up to + SIZE bytes and then return the number of bytes read.*/ static int syscall_read (int fd, void *buffer, unsigned size) { @@ -239,6 +275,10 @@ syscall_read (int fd, void *buffer, unsigned size) } } +/* Handles the syscall for writing SIZE bytes to a file referenced by FD. + If the FD references the console, use put_buf (), otherwise convert the + FD to its associated file struct, acquire the filesystem lock, write up to + SIZE bytes and then return the number of bytes written.*/ static int syscall_write (int fd, const void *buffer, unsigned size) { @@ -270,6 +310,10 @@ syscall_write (int fd, const void *buffer, unsigned size) } } +/* Handles the syscall for seeking to POSITION bytes in a file referenced by + FD. Converts the FD to its associated file struct, acquires the filesystem + lock and then uses file_seek to adjust the cursor to a specific position in + the file.*/ static void syscall_seek (int fd, unsigned position) { @@ -282,6 +326,9 @@ syscall_seek (int fd, unsigned position) } } +/* Handles the syscall for returning the next byte in a file referenced by + FD. Converts the FD to its associated file struct, acquires the filesystem + lock and then uses file_tell to read the next byte.*/ static unsigned syscall_tell (int fd) { @@ -296,6 +343,9 @@ syscall_tell (int fd) return pos; } +/* Handles the syscall for closing a connection to a file. Converts the FD to + its associated file struct. If it exists, it removes it from the hash table, + acquires the filesystem lock, and uses file_close to close the connection.*/ static void syscall_close (int fd) { @@ -311,12 +361,16 @@ syscall_close (int fd) } } +/* Hashing function needed for the open_file table. Returns a hash for an entry, + based on its FD. */ unsigned fd_hash (const struct hash_elem *element, void *aux UNUSED) { return hash_int (hash_entry (element, struct open_file, elem)->fd); } +/* Comparator function for the open_file table. Compares two entries based on + the FDs. */ bool fd_less (const struct hash_elem *a_, const struct hash_elem *b_, void *aux UNUSED)