d/metal-cos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix up documentation

Browse Source
This commit is contained in:
Ali Mashtizadeh 2023-09-10 16:12:25 -04:00
parent a71bebe92e
commit 631603cab3
14 changed files with 210 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
sys/kern/bufcache.c
View File

@ -89,6 +89,7 @@ BufCache_Init()
* @param [in] disk Disk object
* @param [in] diskOffset Block offset within the disk
* @param [out] entry If successful, this contains the buffer cache entry.
*
* @retval 0 if successful
* @return ENOENT if not present.
*/
@ -124,6 +125,7 @@ BufCacheLookup(Disk *disk, uint64_t diskOffset, BufCacheEntry **entry)
* @param [in] disk Disk object
* @param [in] diskOffset Block offset within the disk
* @param [out] entry If successful, this contains the buffer cache entry.
*
* @retval 0 if successful.
* @return ENOMEM if there's no buffer cache entries free.
*/
@ -168,6 +170,7 @@ BufCacheAlloc(Disk *disk, uint64_t diskOffset, BufCacheEntry **entry)
* @param [in] disk Disk object
* @param [in] diskOffset Block offset within the disk
* @param [out] entry If successful, this contains the buffer cache entry.
*
* @retval 0 if successful
* @return Otherwise returns an error code.
*/

31
sys/kern/copy.c
View File

@ -17,16 +17,18 @@ extern int copystr_unsafe(void *to_addr, void *from_addr, uintptr_t len);
/**
* Copy_In --
*
* Safely copy memory from userspace. Prevents userspace pointers from
* reading kernel memory.
*
* Side effects:
* Kernel page fault may have occurred.
*
* @param [in] fromuser User address to copy from.
* @param [in] tokernel Kernel address to copy to.
* @param [in] len Length of the data to copy.
* @retval EFAULT if the address is invalid or causes a fault.
*
* Side effects:
* Kernel page fault may have occurred.
* @retval EFAULT if the address is invalid or causes a fault.
*/
int
Copy_In(uintptr_t fromuser, void *tokernel, uintptr_t len)
@ -51,16 +53,18 @@ Copy_In(uintptr_t fromuser, void *tokernel, uintptr_t len)
/**
* Copy_Out --
*
* Safely copy memory to userspace. Prevents userspace pointers from
* writing kernel memory.
*
* Side effects:
* Kernel page fault may have occurred.
*
* @param [in] fromkernel Kernel address to copy from.
* @param [in] touser User address to copy to.
* @param [in] len Length of the data to copy.
* @retval EFAULT if the address is invalid or causes a fault.
*
* Side effects:
* Kernel page fault may have occurred.
* @retval EFAULT if the address is invalid or causes a fault.
*/
int
Copy_Out(void *fromkernel, uintptr_t touser, uintptr_t len)
@ -89,13 +93,14 @@ Copy_Out(void *fromkernel, uintptr_t touser, uintptr_t len)
* Safely copy a string from userspace. Prevents userspace pointers from
* reading kernel memory.
*
* Side effects:
* Kernel page fault may have occurred.
*
* @param [in] fromuser User address to copy from.
* @param [in] tokernel Kernel address to copy to.
* @param [in] len Maximum string length.
* @retval EFAULT if the address is invalid or causes a fault.
*
* Side effects:
* Kernel page fault may have occurred.
* @retval EFAULT if the address is invalid or causes a fault.
*/
int
Copy_StrIn(uintptr_t fromuser, void *tokernel, uintptr_t len)
@ -120,16 +125,18 @@ Copy_StrIn(uintptr_t fromuser, void *tokernel, uintptr_t len)
/**
* Copy_StrOut --
*
* Safely copy a string to userspace. Prevents userspace pointers from
* writing kernel memory.
*
* Side effects:
* Kernel page fault may have occurred.
*
* @param [in] fromkernel Kernel address to copy from.
* @param [in] touser User address to copy to.
* @param [in] len Maximum string length.
* @retval EFAULT if the address is invalid or causes a fault.
*
* Side effects:
* Kernel page fault may have occurred.
* @retval EFAULT if the address is invalid or causes a fault.
*/
int
Copy_StrOut(void *fromkernel, uintptr_t touser, uintptr_t len)

4
sys/kern/disk.c
View File

@ -1,3 +1,7 @@
/*
* Copyright (c) 2013-2023 Ali Mashtizadeh
* All rights reserved.
*/
#include <stdbool.h>
#include <stdint.h>

28
sys/kern/loader.c
View File

@ -1,3 +1,7 @@
/*
* Copyright (c) 2006-2023 Ali Mashtizadeh
* All rights reserved.
*/
#include <stdbool.h>
#include <stdint.h>
@ -21,7 +25,7 @@
extern Handle *Console_OpenHandle();
/*
/**
* Loader_CheckHeader --
*
* Check that the program has a valid ELF header.
@ -46,12 +50,12 @@ Loader_CheckHeader(const Elf64_Ehdr *ehdr)
return true;
}
/*
/**
* LoaderLoadSegment --
*
* Loads a single segment into the target address space. This function
* loads a single page at a time because it has to lookup the address
* mappings through the page tables.
* Loads a single segment into the target address space. This function loads a
* single page at a time because it has to lookup the address mappings through
* the page tables.
*/
static void
LoaderLoadSegment(AS *as, VNode *vn, uintptr_t vaddr,
@ -84,11 +88,11 @@ LoaderLoadSegment(AS *as, VNode *vn, uintptr_t vaddr,
}
}
/*
/**
* LoaderZeroSegment --
*
* Zeroes a segment of memory in the target address space. This is done
* one page a time while translating the virtual address to physical.
* Zeroes a segment of memory in the target address space. This is done one
* page a time while translating the virtual address to physical.
*/
static void
LoaderZeroSegment(AS *as, uintptr_t vaddr, uintptr_t len)
@ -118,7 +122,7 @@ LoaderZeroSegment(AS *as, uintptr_t vaddr, uintptr_t len)
}
}
/*
/**
* Loader_Load --
*
* Load the ELF binary into the process belonging to the thread.
@ -184,12 +188,12 @@ Loader_Load(Thread *thr, VNode *vn, void *buf, uint64_t len)
return true;
}
/*
/**
* Loader_LoadInit --
*
* The init process is created from the execution kernel thread that
* initializes the system. This function initializes the thread and
* process state then loads the init binary.
* initializes the system. This function initializes the thread and process
* state then loads the init binary.
*/
void
Loader_LoadInit()

4
sys/kern/mutex.c
View File

@ -74,8 +74,8 @@ Mutex_Lock(Mutex *mtx)
/**
* Mutex_TryLock --
*
* Attempts to acquire the user mutex. Returns EBUSY if the lock is
* already taken, otherwise 0 on success.
* Attempts to acquire the user mutex. Returns EBUSY if the lock is already
* taken, otherwise 0 on success.
*/
int
Mutex_TryLock(Mutex *mtx)

4
sys/kern/nic.c
View File

@ -1,3 +1,7 @@
/*
* Copyright (c) 2013-2023 Ali Mashtizadeh
* All rights reserved.
*/
#include <stdbool.h>
#include <stdint.h>

14
sys/kern/palloc.c
View File

@ -63,9 +63,9 @@ PAlloc_Init()
/**
* PAlloc_LateInit --
*
* The late init call is made after the page tables are initialized using
* a small boot memory region (2nd 16MBs). This is where initialize the
* XMem region that represents the PageInfo array, and map memory into it.
* The late init call is made after the page tables are initialized using a
* small boot memory region (2nd 16MBs). This is where initialize the XMem
* region that represents the PageInfo array, and map memory into it.
*/
void
PAlloc_LateInit()
@ -178,8 +178,8 @@ PAllocGetInfo(void *pg)
/**
* PAlloc_AllocPage --
*
* Allocate a physical page and return the page's address in the Kernel's
* ident mapped memory region.
* Allocate a physical page and return the page's address in the Kernel's ident
* mapped memory region.
*
* @retval NULL if no memory is available.
* @return Newly allocated physical page.
@ -258,8 +258,8 @@ PAlloc_Retain(void *pg)
/**
* PAlloc_Release --
*
* Deccrement the reference count for a physical page. If the reference
* count is zero the page will be freed.
* Deccrement the reference count for a physical page. If the reference count
* is zero the page will be freed.
*/
void
PAlloc_Release(void *pg)

8
sys/kern/process.c
View File

@ -43,6 +43,7 @@ Slab processSlab;
*
* @param [in] parent Parent process.
* @param [in] title Process title.
*
* @return The newly created process.
*/
Process *
@ -134,6 +135,7 @@ Process_Destroy(Process *proc)
* Process_Lookup --
*
* Lookup a process by PID and increment its reference count.
*
* @param [in] pid Process ID to search for.
*
* @retval NULL No such process.
@ -191,12 +193,12 @@ Process_Release(Process *proc)
/**
* Process_Wait --
*
* Wait for a process to exit and then cleanup it's references. If the
* pid == 0, we wait for any process, otherwise we wait for a specific
* process.
* Wait for a process to exit and then cleanup it's references. If the pid ==
* 0, we wait for any process, otherwise we wait for a specific process.
*
* @param [in] proc Parent process.
* @param [in] pid Optionally specify the pid of the process to wait on.
*
* @retval ENOENT Process ID doesn't exist.
* @return Exit status of the process that exited or crashed.
*/

16
sys/kern/sched.c
View File

@ -47,8 +47,8 @@ Thread *curProc[MAX_CPUS];
/**
* Sched_Current() --
*
* Get the currently executing thread. This function retains a reference
* count and you must release the reference by calling Thread_Release.
* Get the currently executing thread. This function retains a reference count
* and you must release the reference by calling Thread_Release.
*
* @return Returns the current thread.
*/
@ -117,9 +117,8 @@ Sched_SetWaiting(Thread *thr)
/**
* Sched_SetZombie --
*
* Set the thread to the zombie state and move it to the parent
* processes's zombie process queue. The thread should be currently
* running.
* Set the thread to the zombie state and move it to the parent processes's
* zombie process queue. The thread should be currently running.
*
* @param [in] thr Thread to be set as zombie.
*/
@ -165,10 +164,9 @@ Sched_SetZombie(Thread *thr)
/**
* Sched_Switch --
*
* Switch between threads. During the creation of kernel threads (and by
* proxy user threads) we may not return through this code path and thus
* the kernel thread initialization function must release the scheduler
* lock.
* Switch between threads. During the creation of kernel threads (and by proxy
* user threads) we may not return through this code path and thus the kernel
* thread initialization function must release the scheduler lock.
*
* @param [in] oldthr Current thread we are switching from.
* @param [in] newthr Thread to switch to.

4
sys/kern/sga.c
View File

@ -1,3 +1,7 @@
/*
* Copyright (c) 2013-2023 Ali Mashtizadeh
* All rights reserved.
*/
#include <stdint.h>

4
sys/kern/spinlock.c
View File

@ -68,8 +68,8 @@ Spinlock_Destroy(Spinlock *lock)
/**
* Spinlock_Lock --
*
* Spin until we acquire the spinlock. This will also disable interrupts
* to prevent deadlocking with interrupt handlers.
* Spin until we acquire the spinlock. This will also disable interrupts to
* prevent deadlocking with interrupt handlers.
*/
void
Spinlock_Lock(Spinlock *lock) __NO_LOCK_ANALYSIS

1
sys/kern/thread.c
View File

@ -222,6 +222,7 @@ Thread_Destroy(Thread *thr)
*
* @param [in] proc Process within which to find a specific thread.
* @param [in] tid Thread ID of the thread to find.
*
* @retval NULL if the thread isn't found.
*/
Thread *

14
sys/kern/vfs.c
View File

@ -56,9 +56,8 @@ VFS_MountRoot(Disk *rootDisk)
/**
* VFS_Lookup --
*
* Lookup a VNode by a path. This function recursively searches the
* directory heirarchy until the given path is found otherwise returns
* NULL if not found.
* Lookup a VNode by a path. This function recursively searches the directory
* heirarchy until the given path is found otherwise returns NULL if not found.
*/
VNode *
VFS_Lookup(const char *path)
@ -118,8 +117,8 @@ VFS_Lookup(const char *path)
/**
* VFS_Stat --
*
* Return the struct stat that contains the file and directory information
* for a given VNode.
* Return the struct stat that contains the file and directory information for
* a given VNode.
*/
int
VFS_Stat(const char *path, struct stat *sb)
@ -141,6 +140,7 @@ VFS_Stat(const char *path, struct stat *sb)
* Open a vnode for reading and writing.
*
* @param [in] fn VNode to open.
*
* @return Return status
*/
int
@ -155,6 +155,7 @@ VFS_Open(VNode *fn)
* Close a vnode.
*
* @param [in] fn VNode to close.
*
* @return Return status
*/
int
@ -172,6 +173,7 @@ VFS_Close(VNode *fn)
* @param [in] buf Buffer to write the data to.
* @param [in] off File offset in bytes.
* @param [in] len Length to read in bytes.
*
* @return Return status
*/
int
@ -189,6 +191,7 @@ VFS_Read(VNode *fn, void *buf, uint64_t off, uint64_t len)
* @param [in] buf Buffer to read the data from.
* @param [in] off File offset in bytes.
* @param [in] len Length to read in bytes.
*
* @return Return status
*/
int
@ -206,6 +209,7 @@ VFS_Write(VNode *fn, void *buf, uint64_t off, uint64_t len)
* @param [in] buf Buffer to write the data to.
* @param [in] off Directory offset in bytes.
* @param [in] len Length to read in bytes.
*
* @return Return status
*/
int