Merge remote-tracking branch 'origin/master' into relibc

src/context/mod.rs

-//! Context management
+//! # Context management
+//! 
+//! For resources on contexts, please consult [wikipedia](https://en.wikipedia.org/wiki/Context_switch) and  [osdev](https://wiki.osdev.org/Context_Switching)
 use alloc::boxed::Box;
 use core::alloc::{Alloc, GlobalAlloc, Layout};
 use core::sync::atomic::Ordering;
@@ -68,6 +70,8 @@ fn init_contexts() -> RwLock<ContextList> {
 
 /// Get the global schemes list, const
 pub fn contexts() -> RwLockReadGuard<'static, ContextList> {
+    //call once will init_contexts only once during the kernel's exececution, otherwise it will return the current context via a
+    //cache.
     CONTEXTS.call_once(init_contexts).read()
 }
 

src/lib.rs

@@ -153,6 +153,7 @@ pub fn kmain(cpus: usize, env: &[u8]) -> ! {
     CPU_ID.store(0, Ordering::SeqCst);
     CPU_COUNT.store(cpus, Ordering::SeqCst);
 
+    //Initialize the first context, stored in kernel/src/context/mod.rs
     context::init();
 
     let pid = syscall::getpid();

src/syscall/futex.rs

+//! # Futex
+//! Futex or Fast Userspace Mutex is "a method for waiting until a certain condition becomes true."
+//!
+//! For more information about futexes, please read [this](https://eli.thegreenplace.net/2018/basics-of-futexes/) blog post, and the [futex(2)](http://man7.org/linux/man-pages/man2/futex.2.html) man page
 use alloc::arc::Arc;
 use alloc::VecDeque;
 use core::intrinsics;

src/syscall/mod.rs

-///! Syscall handlers
+//!
+//! This module provides syscall definitions and the necessary resources to parse incoming
+//! syscalls
 
 extern crate syscall;
 
@@ -44,9 +46,12 @@ pub mod time;
 /// Validate input
 pub mod validate;
 
+/// This function is the syscall handler of the kernel, it is composed of an inner function that returns a `Result<usize>`. After the inner function runs, the syscall
+/// function calls [`Error::mux`] on it.
 pub fn syscall(a: usize, b: usize, c: usize, d: usize, e: usize, f: usize, bp: usize, stack: &mut SyscallStack) -> usize {
     #[inline(always)]
     fn inner(a: usize, b: usize, c: usize, d: usize, e: usize, f: usize, bp: usize, stack: &mut SyscallStack) -> Result<usize> {
+        //SYS_* is declared in kernel/syscall/src/number.rs
         match a & SYS_CLASS {
             SYS_CLASS_FILE => {
                 let fd = FileHandle::from(b);
@@ -165,6 +170,11 @@ pub fn syscall(a: usize, b: usize, c: usize, d: usize, e: usize, f: usize, bp: u
     }
     */
 
+    // The next lines set the current syscall in the context struct, then once the inner() function
+    // completes, we set the current syscall to none.
+    //
+    // When the code below falls out of scope it will release the lock
+    // see the spin crate for details
     {
         let contexts = ::context::contexts();
         if let Some(context_lock) = contexts.current() {
@@ -204,5 +214,6 @@ pub fn syscall(a: usize, b: usize, c: usize, d: usize, e: usize, f: usize, bp: u
     }
     */
 
+    // errormux turns Result<usize> into -errno
     Error::mux(result)
 }

src/syscall/time.rs

@@ -16,7 +16,9 @@ pub fn clock_gettime(clock: usize, time: &mut TimeSpec) -> Result<usize> {
     Ok(0)
 }
 
+/// Nanosleep will sleep by switching the current context
 pub fn nanosleep(req: &TimeSpec, rem_opt: Option<&mut TimeSpec>) -> Result<usize> {
+    //start is a tuple of (seconds, nanoseconds)
     let start = time::monotonic();
     let sum = start.1 + req.tv_nsec as u64;
     let end = (start.0 + req.tv_sec as u64 + sum / 1_000_000_000, sum % 1_000_000_000);