initial checkout from wrc

1 files changed, 315 insertions, 0 deletions

diff --git a/include/ulib.h b/include/ulib.h
new file mode 100644
index 0000000..d254d6a
--- /dev/null
+++ b/include/ulib.h
@@ -0,0 +1,315 @@
+/**
+** @file	ulib.h
+**
+** @author	CSCI-452 class of 20245
+**
+** @brief	Declarations for user-level library functions
+**
+** This module implements a simple collection of support functions
+** similar to the standard C library.
+*/
+
+#ifndef ULIB_H_
+#define ULIB_H_
+
+#include <common.h>
+
+/*
+** General (C and/or assembly) definitions
+*/
+
+#ifndef ASM_SRC
+
+/*
+** Start of C-only definitions
+*/
+
+/*
+** Types
+*/
+
+/*
+** Globals
+*/
+
+/*
+** Prototypes
+*/
+
+/*
+*************************************************
+** SYSTEM CALLS *********************************
+*************************************************
+*/
+
+/**
+** exit - terminate the calling process
+**
+** usage:   exit(status);
+**
+** @param status   Termination status of this process
+**
+** Does not return.
+*/
+void exit( int32_t status );
+
+/**
+** waitpid - wait for a child process to terminate
+**
+** usage:   pid = waitpid(pid,&status);
+**
+** @param pid    PID of the desired child, or 0 for any child
+** @param status Pointer to int32_t into which the child's status is placed,
+**               or NULL
+**
+** @return  The PID of the terminated child, or an error code
+**
+** If there are no children in the system, returns an error code (*status
+** is unchanged).
+**
+** If there are one or more children in the system and at least one has
+** terminated but hasn't yet been cleaned up, cleans up that process and
+** returns its information; otherwise, blocks until a child terminates.
+*/
+int waitpid( uint_t pid, int32_t *status );
+
+/**
+** fork - create a duplicate of the calling process
+**
+** usage:   pid = fork();
+**
+** @return   parent - the pid of the new child, or an error code
+**           child  - 0
+*/
+int fork( void );
+
+/**
+** exec - replace the memory image of the calling process
+**
+** usage:   exec( what, args )
+**
+** @param what    program table index of the program to exec
+** @param args    the command-line argument vector
+**
+** Does not return if it succeeds; if it returns, something has
+** gone wrong.
+*/
+void exec( uint_t what, char **args );
+
+/**
+** read - read into a buffer from a stream
+**
+** usage:   n = read(channel,buf,length)
+**
+** @param chan   I/O stream to read from
+** @param buf    Buffer to read into
+** @param length Maximum capacity of the buffer
+**
+** @return   The count of bytes transferred, or an error code
+*/
+int read( uint_t chan, void *buffer, uint_t length );
+
+/**
+** write - write from a buffer to a stream
+**
+** usage:   n = write(channel,buf,length)
+**
+** @param chan   I/O stream to write to
+** @param buf    Buffer to write from
+** @param length Maximum capacity of the buffer
+**
+** @return   The count of bytes transferred, or an error code
+*/
+int write( uint_t chan, const void *buffer, uint_t length );
+
+/**
+** getpid - get the PID of the calling process
+**
+** usage:   pid = getpid()
+**
+** @return   the PID of this process
+*/
+uint_t getpid( void );
+
+/**
+** getppid - get the PID of the calling process' parent
+**
+** usage:   pid = getppid()
+**
+** @return   the PID of this process' parent
+*/
+uint_t getppid( void );
+
+/**
+** gettime - get the current system time
+**
+** usage:   pid = gettime()
+**
+** @return   the system time
+*/
+uint32_t gettime( void );
+
+/**
+** getprio - get the scheduling priority of the calling process
+**
+** usage:   prio = getprio()
+**
+** @return   the process' priority
+*/
+int getprio( void );
+
+/**
+** setprio - set the scheduling priority of the calling process
+**
+** usage:   oldprio = setprio(newprio)
+**
+** @param new   the desired new priority
+**
+** @return   the old priority value
+*/
+int setprio( int new );
+
+/**
+** kill - terminate a process with extreme prejudice
+**
+** usage:   n = kill( pid )
+**
+** @param pid  the intended victim
+**
+** @return   0 on success, else an error code
+*/
+int32_t kill( uint_t pid );
+
+/**
+** sleep - put the current process to sleep for some length of time
+**
+** usage:   sleep(n);
+**
+** @param ms Desired sleep time (in ms), or 0 to yield the CPU
+**
+** @return the time the process spent sleeping (in ms)
+*/
+int sleep( uint32_t ms );
+
+/**
+** bogus - a nonexistent system call, to test our syscall ISR
+**
+** usage:   bogus()
+**
+** Does not return.
+*/
+void bogus( void );
+
+/*
+*************************************************
+** CONVENIENT "SHORTHAND" VERSIONS OF SYSCALLS **
+*************************************************
+**
+** These are library functions that perform specific common
+** variants of system calls. This helps reduce the total number
+** of system calls, keeping our baseline OS as lean and mean
+** as we can make it. :-)
+*/
+
+/**
+** wait - wait for any child to exit
+**
+** usage:   pid = wait(&status)
+**
+** Calls waitpid(0,status)
+**
+** @param status Pointer to int32_t into which the child's status is placed,
+**               or NULL
+**
+** @return  The PID of the terminated child, or an error code
+*/
+int wait( int32_t *status );
+
+/**
+** spawn - create a new process running a different program
+**
+** usage:       n = spawn(what,args)
+**
+** Creates a new process and then execs 'what'
+**
+** @param what  Program table index of the program to spawn
+** @param args  The command-line argument vector for the process
+**
+** @return      The PID of the child, or an error code
+*/
+int spawn( uint_t what, char **args );
+
+/**
+** cwritech(ch) - write a single character to the console
+**
+** @param ch The character to write
+**
+** @return  The return value from calling write()
+*/
+int cwritech( char ch );
+
+/**
+** cwrites(str) - write a NUL-terminated string to the console
+**
+** @param str The string to write
+**
+*/
+int cwrites( const char *str );
+
+/**
+** cwrite(buf,leng) - write a sized buffer to the console
+**
+** @param buf  The buffer to write
+** @param leng The number of bytes to write
+**
+** @return  The return value from calling write()
+*/
+int cwrite( const char *buf, uint32_t leng );
+
+/**
+** swritech(ch) - write a single character to the SIO
+**
+** @param ch The character to write
+**
+** @return  The return value from calling write()
+*/
+int swritech( char ch );
+
+/**
+** swrites(str) - write a NUL-terminated string to the SIO
+**
+** @param str The string to write
+**
+** @return  The return value from calling write()
+*/
+int swrites( const char *str );
+
+/**
+** swrite(buf,leng) - write a sized buffer to the SIO
+**
+** @param buf  The buffer to write
+** @param leng The number of bytes to write
+**
+** @return  The return value from calling write()
+*/
+int swrite( const char *buf, uint32_t leng );
+
+/*
+*************************************************
+** MISCELLANEOUS USEFUL SUPPORT FUNCTIONS *******
+*************************************************
+*/
+
+/**
+** fake_exit()
+**
+** dummy "startup" function
+**
+** calls exit(%eax) - serves as the "return to" code for
+** main() functions, in case they don't call exit() themselves
+*/
+void fake_exit( void );
+
+#endif /* !ASM_SRC */
+
+#endif