syscall cleanup/scrub

- 2nd pass
- 3rd pass

Change-Id: I5eb314c0c635aa42bc4d841065d9a9a786f8be4b
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/198
Tested-by: Jenkins Server
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>
Reviewed-by: MIKE J. JONES <mjjones@us.ibm.com>

4 files changed, 163 insertions, 21 deletions

diff --git a/src/include/sys/mmio.h b/src/include/sys/mmio.h
index 3536071c8..35392f22e 100644
--- a/src/include/sys/mmio.h
+++ b/src/include/sys/mmio.h
@@ -9,22 +9,44 @@ extern "C"
 {
 #endif
 
+/** @fn mmio_map()
+ *  @brief Map a region into virtual address space.
+ *  
+ *  @param[in] ra - address of page
+ *  @param[in] pages - count of pages to map
+ *
+ *  @returns The virtual address where mapped.
+ */
 void* mmio_map(void* ra, size_t pages);
+
+
+/** @fn mmio_unmap()
+ *  @brief Unmap a region previously mapped into virtual address space.
+ *
+ *  Appears not to be implemented. See _mmioUnmap in src/kernel/vmmmgr.C
+ *  
+ *  @param[in] ea - virtual address as returned from mmio_map()
+ *  @param[in] pages - count of pages to unmap
+ *
+ *  @returns -1 from _mmioUnmap in src/kernel/vmmmgr.C 
+ */
 int mmio_unmap(void* ea, size_t pages);
 
+
 /** @fn mmio_hmer_read()
- *  @brief Reads the protected HMER register.
+ *  @brief Reads and returns protected HMER register.
+ *  @return HMER register value
  */
 uint64_t mmio_hmer_read();
 
+
 /** @fn mmio_hmer_write()
  *  @brief Writes the protected HMER register.
  *
  *  @param[in] value - The value to write into the HMER.
- *
- *  @returns 0.
  */
-int mmio_hmer_write(uint64_t value);
+void mmio_hmer_write(uint64_t value);
+
 
 /** @fn mmio_xscom_mutex()
  *  @brief Returns the per-CPU mutex for the XSCOM hardware logic.
@@ -36,7 +58,7 @@ int mmio_hmer_write(uint64_t value);
  *
  *  @note The task should only interact with the mutex while protected by an
  *        affinity pin.  If the pin is moved the mutex is no longer
- *        guarenteed for the CPU the task is executing on.
+ *        guaranteed for the CPU the task is executing on.
  */
 mutex_t * mmio_xscom_mutex();
 
diff --git a/src/include/sys/msg.h b/src/include/sys/msg.h
index eec71ea4e..b2cbc1d31 100644
--- a/src/include/sys/msg.h
+++ b/src/include/sys/msg.h
@@ -21,22 +21,126 @@ struct msg_t
 };
 
 // Message queue interfaces.
+
+
+/** @fn msg_q_create
+  * @brief Create a new message queue.
+  *
+  * @return msg_q_t handle
+  */
 msg_q_t msg_q_create();
-int msg_q_destroy();
+
+
+/** @fn msg_q_destroy
+  * @brief Deallocate a message queue previously allocated with msg_q_create()
+  *
+  * @param[in] q - handle to message queue to destroy
+  */
+void msg_q_destroy( msg_q_t q );
+
+
+/** @fn msg_q_register
+  * @brief Assign a name to a message queue.
+  *
+  * @param[in] q - handle of message queue to name
+  * @param[in] name - name
+  * 
+  * @return  Result of msg_sendrecv where zero indicates success
+  */
 int msg_q_register(msg_q_t q, const char* name);
+
+
+/** @fn msg_q_resolve
+  * @brief Given the name of a message queue, return the handle to it.
+  *
+  * @param[in] name - name of message queue
+  *
+  * @return message queue handle or null if name not found.
+  */
 msg_q_t msg_q_resolve(const char* name);
 
+
+
+
+
 // Message interfaces.
+/** @fn msg_allocate
+  * @brief Allocate space for message 
+  * @return Pointer to message
+  */
 ALWAYS_INLINE 
     inline msg_t* msg_allocate() { return (msg_t*)malloc(sizeof(msg_t)); }
+
+
+/** @fn msg_free
+  * @brief Free a msg_t
+  * @param[in] msg - message to free
+  */
+
 ALWAYS_INLINE
     inline void msg_free(msg_t* m) { free(m); }
 
+
+/** @fn msg_send 
+  * @brief Send a message asynchronously.
+  *
+  * This call adds the message queue then returns 
+  * to the caller. Any process waiting for a message 
+  * in the queue will awake with this message.
+  *
+  * @param[in] q - message queue
+  * @param[in] msg - message
+  * @return    Always returns zero.
+  */
 int msg_send(msg_q_t q, msg_t* msg);
+
+
+/** @fn msg_sendrecv
+  * @brief Send a message to a server and get a response synchronously.
+  *
+  * The calling [client] thread blocks until the recipient [server] receives 
+  * and replies to the message. 
+  *
+  * @param[in] q - message queue
+  * @param[in,out] msg - message
+  * @return Zero on success, else negative.
+  */
 int msg_sendrecv(msg_q_t q, msg_t* msg);
+
+
+/** @fn msg_respond
+  * @brief Respond to a synchronous message.
+  *
+  * This is how server-side code responds to synchronous
+  * messaging when clients call msg_sendrecv().  
+  * 
+  * @param[in] q - message queue
+  * @param[in] msg - response message
+  * @return Zero on success, else negative.
+  */
 int msg_respond(msg_q_t q, msg_t* msg);
+
+
+/** @fn msg_wait
+  * @brief  Read a message from the message queue.
+  * 
+  * If a message is already on the queue, this call will return immediately
+  * with the message. Otherwise the calling thread will block and wait for
+  * a message. 
+  *
+  * @param[in] q - message queue to read
+  * @return the message posted to the queue
+  */
 msg_t* msg_wait(msg_q_t q);
 
+
+/** @fn msg_is_async
+  * @brief  Indicates if message is asynchronous.
+  *
+  * Tests the message field "__reserved__async" which appears to be set to 0 to indicate asynchronous, and 1 to indicate synchronous message.
+  *
+  * @return true if asynchronous message
+  */
 ALWAYS_INLINE
     inline uint32_t msg_is_async(msg_t* msg) 
 	{ return 0 == msg->__reserved__async; }
diff --git a/src/include/sys/sync.h b/src/include/sys/sync.h
index b6274a0a6..7a4d1afde 100644
--- a/src/include/sys/sync.h
+++ b/src/include/sys/sync.h
@@ -29,29 +29,35 @@ typedef _barrier_imp_t barrier_t;
 #define MUTEX_INITIALIZER {0}
 
 /**
- * Initialize a barrier object
+ * @fn barrier_init
+ * @brief Initialize a barrier object
  * @param[out] o_barrier The barrier
  * @param[in] i_count The number of threads to wait on
- * @pre an unitiailized barrier object
+ * @pre an uninitialized barrier object
  * @post a valid barrier object
  */
 void barrier_init (barrier_t * o_barrier, uint64_t i_count);
 
+
 /**
- * Destroy a barrier
+ * @fn barrier_destroy 
+ * @brief Destroy a barrier
  * @param[in] i_barrier  The barrier
  */
 void barrier_destroy (barrier_t * i_barrier);
 
+
 /**
- * Wait on a barrier
+ * @fn barrier_wait
+ * @brief Wait on a barrier
+ * This thread will block until the barrier count is reached.
  * @param[in] i_barrier The barrier
- * @post this thread will be blocked until the barrier count is reached.
  */
 void barrier_wait (barrier_t * i_barrier);
 
 /**
- * Initialize a mutex object
+ * @fn mutex_init
+ * @brief Initialize a mutex object
  * @param[out] o_mutex the mutex
  * @pre an uninitialized mutex object
  * @post a valid mutex object
@@ -59,25 +65,27 @@ void barrier_wait (barrier_t * i_barrier);
 void mutex_init(mutex_t * o_mutex);
 
 /**
- * Destroy / Uninitialize a mutex object.
- * @param[in] i_mutex The mutex
+ * @fn mutex_destroy
+ * @brief Destroy / uninitialize a mutex object.
+ * @param[in] i_mutex - the mutex
  * @note This does not free the memory associated with the object if the mutex
  *       was allocated off the heap.
  */
 void mutex_destroy(mutex_t * i_mutex);
 
 /**
- * Obtain a lock on a mutex
- * @param[in] i_mutex The mutex
+ * @fn mutex_lock
+ * @brief Obtain a lock on a mutex
+ * @param[in] i_mutex - The mutex
  * @post returns when this thread has the lock
  */
 void mutex_lock(mutex_t * i_mutex);
 
 /**
- * Release a lock on a mutex
- * @param[in] i_mutex the mutex
- * @returns non zero on error
- * @post mutex lock release
+ * @fn mutex_unlock
+ * @brief Release a lock on a mutex
+ * @param[in] i_mutex - the mutex
+ * @post mutex lock released
  */
 void mutex_unlock(mutex_t * i_mutex);
 
diff --git a/src/include/sys/time.h b/src/include/sys/time.h
index 2ed63710a..eb67107dc 100644
--- a/src/include/sys/time.h
+++ b/src/include/sys/time.h
@@ -8,7 +8,15 @@ extern "C"
 {
 #endif
 
-int nanosleep(uint64_t sec, uint64_t nsec);
+
+/** @fn nanosleep()
+ *  @brief Sleep for time duration given: seconds plus nanoseconds.
+ *  @param[in] sec  - seconds
+ *  @param[in] nsec - nanoseconds (billionths of a second)
+ */
+void nanosleep(uint64_t sec, uint64_t nsec);
+
+
 
 #ifdef __cplusplus
 }