From 24db4eee8c52c7aa7eaf5bdc08609b2610bb42bb Mon Sep 17 00:00:00 2001 From: Martin Lenders Date: Tue, 1 Apr 2014 15:45:06 +0200 Subject: [PATCH] Fix documentation for msg.h --- core/include/msg.h | 123 ++++++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 53 deletions(-) diff --git a/core/include/msg.h b/core/include/msg.h index da9fe81b77..96abd6fdf5 100644 --- a/core/include/msg.h +++ b/core/include/msg.h @@ -11,13 +11,14 @@ * @ingroup core * @brief Messaging API for inter process communication * - * There are two ways to use the IPC Messaging system of RIOT. The default is synchronous - * messaging. In this manner, messages are either dropped when the receiver is not waiting and the - * message was sent non-blocking, or will be delivered immediately when the receiver calls - * msg_receive(msg_t* m). To use asynchronous messaging any thread can create its own queue by - * calling msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non full message - * queue are never dropped and the sending never blocks. Threads with a full message queue behaves - * like in synchronous mode. + * There are two ways to use the IPC Messaging system of RIOT. The default is + * synchronous messaging. In this manner, messages are either dropped when the + * receiver is not waiting and the message was sent non-blocking, or will be + * delivered immediately when the receiver calls msg_receive(msg_t* m). To use + * asynchronous messaging any thread can create its own queue by calling + * msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non + * full message queue are never dropped * and the sending never blocks. Threads + * with a full message queue behaves like in synchronous mode. * * @{ * @@ -29,16 +30,12 @@ * @author Kévin Roussel */ -#ifndef __MSG_H -#define __MSG_H +#ifndef __MSG_H_ +#define __MSG_H_ #include #include -#define MESSAGE_SENT 1 -#define MESSAGE_PROCESS_NOT_WAITING 0 -#define MESSAGE_PROCESS_UNKNOWN 2 - /** * @brief Describes a message object which can be sent between threads. * @@ -48,31 +45,35 @@ * */ typedef struct msg { - uint16_t sender_pid; ///< PID of sending thread. Will be filled in by msg_send - uint16_t type; ///< Type field. + uint16_t sender_pid; /**< PID of sending thread. Will be filled in + by msg_send. */ + uint16_t type; /**< Type field. */ union { - char *ptr; ///< pointer content field - uint32_t value; ///< value content field - } content; + char *ptr; /**< Pointer content field. */ + uint32_t value; /**< Value content field. */ + } content; /**< Content of the message. */ } msg_t; /** * @brief Send a message. * - * This function sends a message to another thread. - * The msg structure has to be allocated (e.g. on the stack) - * before calling the function and can be freed afterwards. - * If called from an interrupt, this function will never block. + * This function sends a message to another thread. The ``msg_t`` structure has + * to be allocated (e.g. on the stack) before calling the function and can be + * freed afterwards. If called from an interrupt, this function will never + * block. * - * @param m Pointer to message structure - * @param target_pid PID of target thread - * @param block If true and receiver is not receive-blocked, function will block. If not, function - * returns. + * @param[in] m Pointer to preallocated ``msg_t`` structure, must + * not be NULL. + * @param[in] target_pid PID of target thread + * @param[in] block If not 0 and receiver is not receive-blocked, + * function will block. If not, function returns. * - * @return 1 if sending was successful (message delivered directly or to a queue) - * @return 0 if receiver is not waiting or has a full message queue and block == false - * @return -1 on error (invalid PID) + * @return 1, if sending was successful (message delivered directly or to a + * queue) + * @return 0, if receiver is not waiting or has a full message queue and + * ``block == 0`` + * @return -1, on error (invalid PID) */ int msg_send(msg_t *m, unsigned int target_pid, bool block); @@ -95,13 +96,15 @@ int msg_send_to_self(msg_t *m); /** * @brief Send message from interrupt. * - * Will be automatically chosen instead of msg_send if inISR() == true + * Will be automatically chosen instead of ``msg_sennd()`` if called from an + * interrupt/ISR. * - * @param m pointer to message structure - * @param target_pid PID of target thread + * @param[in] m Pointer to preallocated ``msg_t`` structure, must + * not be NULL. + * @param[in] target_pid PID of target thread. * - * @return 1 if sending was successful - * @return 0 if receiver is not waiting and block == false + * @return 1, if sending was successful + * @return 0, if receiver is not waiting and ``block == 0`` */ int msg_send_int(msg_t *m, unsigned int target_pid); @@ -110,9 +113,11 @@ int msg_send_int(msg_t *m, unsigned int target_pid); * @brief Receive a message. * * This function blocks until a message was received. - * @param m pointer to preallocated msg * - * @return 1 Function always succeeds or blocks forever. + * @param[out] m Pointer to preallocated ``msg_t`` structure, must not be + * NULL. + * + * @return 1, Function always succeeds or blocks forever. */ int msg_receive(msg_t *m); @@ -120,21 +125,30 @@ int msg_receive(msg_t *m); * @brief Try to receive a message. * * This function does not block if no message can be received. - * @param m pointer to preallocated msg * - * @return 1 if a message was received, -1 otherwise. + * @param[out] m Pointer to preallocated ``msg_t`` structure, must not be + * NULL. + * + * @return 1, if a message was received + * @return -1, otherwise. */ int msg_try_receive(msg_t *m); /** * @brief Send a message, block until reply received. * - * This function sends a message to target_pid and then blocks until target has sent a reply. - * @note CAUTION!Use this function only when receiver is already waiting. If not use simple msg_send() - * @param m pointer to preallocated msg - * @param reply pointer to preallocated msg. Reply will be written here. - * @param target pid the pid of the target process - * @return 1 if successful + * This function sends a message to *target_pid* and then blocks until target + * has sent a reply which is then stored in *reply*. + * + * @note CAUTION! Use this function only when receiver is already waiting. + * If not use simple msg_send() + * @param[in] m Pointer to preallocated ``msg_t`` structure with + * the message to send, must not be NULL. + * @param[out] reply Pointer to preallocated msg. Reply will be written + * here, must not be NULL. + * @param[in] target_pid The PID of the target process + * + * @return 1, if successful. */ int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid); @@ -143,24 +157,27 @@ int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid); * * Sender must have sent the message with msg_send_receive(). * - * @param m msg to reply to. - * @param reply message that target will get as reply + * @param[in] m message to reply to, must not be NULL. + * @param[out] reply message that target will get as reply, must not be + * NULL. * - * @return 1 if successful - * @return 0 on error + * @return 1, if successful + * @return 0, on error */ int msg_reply(msg_t *m, msg_t *reply); /** * @brief Initialize the current thread's message queue. * - * @param array Pointer to preallocated array of msg objects - * @param num Number of msg objects in array. MUST BE POWER OF TWO! + * @param[in] array Pointer to preallocated array of ``msg_t`` structures, must + * not be NULL. + * @param[in] num Number of ``msg_t`` structurs in array. + * **MUST BE POWER OF TWO!** * - * @return 0 if successful - * @return -1 on error + * @return 0, if successful + * @return -1, on error */ int msg_init_queue(msg_t *array, int num); +#endif /* __MSG_H_ */ /** @} */ -#endif /* __MSG_H */