unified: Relocate mailbox doxygen style function headers

Change-Id: I06e9ce40da650df67f05db8779a5f6199e6091d5
Signed-off-by: Peter Mitsis <peter.mitsis@windriver.com>

include/kernel.h

@@ -885,20 +885,129 @@ struct k_mbox {
 	_DEBUG_TRACING_KERNEL_OBJECTS_INIT \
 	}
 
+/**
+ * @brief Define a mailbox
+ *
+ * This declares and initializes a mailbox. The new mailbox can be passed to
+ * the kernel's mailbxo functions.
+ *
+ * @param name Name of the mailbox
+ */
 #define K_MBOX_DEFINE(name) \
 	struct k_mbox name = \
 		K_MBOX_INITIALIZER(name) \
 
+/**
+ * @brief Initialize a mailbox.
+ *
+ * @param mbox Pointer to the mailbox object
+ *
+ * @return N/A
+ */
 extern void k_mbox_init(struct k_mbox *mbox);
 
+/**
+ * @brief Send a mailbox message in a synchronous manner.
+ *
+ * Sends a message to a mailbox and waits for a receiver to process it.
+ * The message data may be in a buffer, in a memory pool block, or non-existent
+ * (i.e. empty message).
+ *
+ * @param mbox Pointer to the mailbox object.
+ * @param tx_msg Pointer to transmit message descriptor.
+ * @param timeout Maximum time (milliseconds) to wait for the message to be
+ *        received (although not necessarily completely processed).
+ *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long
+ *        as necessary.
+ *
+ * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
+ */
 extern int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 		      int32_t timeout);
+
+#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
+/**
+ * @brief Send a mailbox message in an asynchronous manner.
+ *
+ * Sends a message to a mailbox without waiting for a receiver to process it.
+ * The message data may be in a buffer, in a memory pool block, or non-existent
+ * (i.e. an empty message). Optionally, the specified semaphore will be given
+ * by the mailbox when the message has been both received and disposed of
+ * by the receiver.
+ *
+ * @param mbox Pointer to the mailbox object.
+ * @param tx_msg Pointer to transmit message descriptor.
+ * @param sem Semaphore identifier, or NULL if none specified.
+ *
+ * @return N/A
+ */
 extern void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 			     struct k_sem *sem);
+#endif
 
+/**
+ * @brief Receive a mailbox message.
+ *
+ * Receives a message from a mailbox, then optionally retrieves its data
+ * and disposes of the message.
+ *
+ * @param mbox Pointer to the mailbox object.
+ * @param rx_msg Pointer to receive message descriptor.
+ * @param buffer Pointer to buffer to receive data.
+ *        (Use NULL to defer data retrieval and message disposal until later.)
+ * @param timeout Maximum time (milliseconds) to wait for a message.
+ *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long as
+ *        necessary.
+ *
+ * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
+ */
 extern int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg,
 		      void *buffer, int32_t timeout);
+
+/**
+ * @brief Retrieve mailbox message data into a buffer.
+ *
+ * Completes the processing of a received message by retrieving its data
+ * into a buffer, then disposing of the message.
+ *
+ * Alternatively, this routine can be used to dispose of a received message
+ * without retrieving its data.
+ *
+ * @param rx_msg Pointer to receive message descriptor.
+ * @param buffer Pointer to buffer to receive data. (Use NULL to discard data.)
+ *
+ * @return N/A
+ */
 extern void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
+
+/**
+ * @brief Retrieve mailbox message data into a memory pool block.
+ *
+ * Completes the processing of a received message by retrieving its data
+ * into a memory pool block, then disposing of the message. The memory pool
+ * block that results from successful retrieval must be returned to the pool
+ * once the data has been processed, even in cases where zero bytes of data
+ * are retrieved.
+ *
+ * Alternatively, this routine can be used to dispose of a received message
+ * without retrieving its data. In this case there is no need to return a
+ * memory pool block to the pool.
+ *
+ * This routine allocates a new memory pool block for the data only if the
+ * data is not already in one. If a new block cannot be allocated, the routine
+ * returns a failure code and the received message is left unchanged. This
+ * permits the caller to reattempt data retrieval at a later time or to dispose
+ * of the received message without retrieving its data.
+ *
+ * @param rx_msg Pointer to receive message descriptor.
+ * @param pool Memory pool identifier. (Use NULL to discard data.)
+ * @param block Pointer to area to hold memory pool block info.
+ * @param timeout Maximum time (milliseconds) to wait for a memory pool block.
+ *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long as
+ *        necessary.
+ *
+ * @return 0 if successful, -ENOMEM if failed immediately, -EAGAIN if timed out
+ */
 extern int k_mbox_data_block_get(struct k_mbox_msg *rx_msg,
 				 struct k_mem_pool *pool,
 				 struct k_mem_block *block, int32_t timeout);