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>

1 files changed, 105 insertions, 1 deletions

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; }