From cab27d0f67e0fbeacc69b8a3a471057e134b5f78 Mon Sep 17 00:00:00 2001
From: Jeremy Soller <jackpot51@gmail.com>
Date: Thu, 3 Nov 2016 20:29:19 -0600
Subject: [PATCH] Add some documentation

---
 kernel/context/context.rs | 13 +++++++++++--
 kernel/lib.rs             |  8 ++++++++
 syscall                   |  2 +-
 3 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/kernel/context/context.rs b/kernel/context/context.rs
index a8678d7..4df574f 100644
--- a/kernel/context/context.rs
+++ b/kernel/context/context.rs
@@ -9,6 +9,8 @@ use context::memory::{Grant, Memory, SharedMemory, Tls};
 use syscall::data::Event;
 use sync::{WaitMap, WaitQueue};
 
+/// The status of a context - used for scheduling
+/// See syscall::process::waitpid and the sync module for examples of usage
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum Status {
     Runnable,
@@ -45,7 +47,7 @@ pub struct Context {
     pub wake: Option<(u64, u64)>,
     /// The architecture specific context
     pub arch: arch::context::Context,
-    /// Kernel FX
+    /// Kernel FX - used to store SIMD and FPU registers on context switch
     pub kfx: Option<Box<[u8]>>,
     /// Kernel stack
     pub kstack: Option<Box<[u8]>>,
@@ -55,7 +57,7 @@ pub struct Context {
     pub heap: Option<SharedMemory>,
     /// User stack
     pub stack: Option<Memory>,
-    /// User Tls
+    /// User Thread local storage
     pub tls: Option<Tls>,
     /// User grants
     pub grants: Arc<Mutex<Vec<Grant>>>,
@@ -103,6 +105,11 @@ impl Context {
         }
     }
 
+    /// Make a relative path absolute
+    /// Given a cwd of "scheme:/path"
+    /// This function will turn "foo" into "scheme:/path/foo"
+    /// "/foo" will turn into "scheme:/foo"
+    /// "bar:/foo" will be used directly, as it is already absolute
     pub fn canonicalize(&self, path: &[u8]) -> Vec<u8> {
         if path.iter().position(|&b| b == b':').is_none() {
             let cwd = self.cwd.lock();
@@ -144,6 +151,7 @@ impl Context {
         }
     }
 
+    /// Block the context, and return true if it was runnable before being blocked
     pub fn block(&mut self) -> bool {
         if self.status == Status::Runnable {
             self.status = Status::Blocked;
@@ -153,6 +161,7 @@ impl Context {
         }
     }
 
+    /// Unblock context, and return true if it was blocked before being marked runnable
     pub fn unblock(&mut self) -> bool {
         if self.status == Status::Blocked {
             self.status = Status::Runnable;
diff --git a/kernel/lib.rs b/kernel/lib.rs
index baefe32..ba38597 100644
--- a/kernel/lib.rs
+++ b/kernel/lib.rs
@@ -125,21 +125,27 @@ pub mod syscall;
 #[cfg(test)]
 pub mod tests;
 
+/// A unique number that identifies the current CPU - used for scheduling
 #[thread_local]
 static CPU_ID: AtomicUsize = ATOMIC_USIZE_INIT;
 
+/// Get the current CPU's scheduling ID
 #[inline(always)]
 pub fn cpu_id() -> usize {
     CPU_ID.load(Ordering::Relaxed)
 }
 
+/// The count of all CPUs that can have work scheduled
 static CPU_COUNT : AtomicUsize = ATOMIC_USIZE_INIT;
 
+/// Get the number of CPUs currently active
 #[inline(always)]
 pub fn cpu_count() -> usize {
     CPU_COUNT.load(Ordering::Relaxed)
 }
 
+/// Initialize userspace by running the initfs:bin/init process
+/// This function will also set the CWD to initfs:bin and open debug: as stdio
 pub extern fn userspace_init() {
     assert_eq!(syscall::chdir(b"initfs:bin"), Ok(0));
 
@@ -165,6 +171,7 @@ pub extern fn ksignal(signal: usize) {
     }
 }
 
+/// This is the kernel entry point for the primary CPU. The arch crate is responsible for calling this
 #[no_mangle]
 pub extern fn kmain(cpus: usize) {
     CPU_ID.store(0, Ordering::SeqCst);
@@ -198,6 +205,7 @@ pub extern fn kmain(cpus: usize) {
     }
 }
 
+/// This is the main kernel entry point for secondary CPUs
 #[no_mangle]
 pub extern fn kmain_ap(id: usize) {
     CPU_ID.store(id, Ordering::SeqCst);
diff --git a/syscall b/syscall
index 77c4386..2d238fa 160000
--- a/syscall
+++ b/syscall
@@ -1 +1 @@
-Subproject commit 77c43866dbd5275eaa5188b1fd5efadaee8530c3
+Subproject commit 2d238fada7e11972693f9e767dfda571e7afe66d