mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
138 lines
4.2 KiB
C
138 lines
4.2 KiB
C
/**
|
|
* 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.
|
|
*
|
|
* @defgroup kernel_msg Messaging / IPC
|
|
* @ingroup kernel
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* @author Freie Universität Berlin, Computer Systems & Telematics
|
|
* @author Kaspar Schleiser <kaspar@schleiser.de>
|
|
*/
|
|
|
|
#ifndef __MSG_H
|
|
#define __MSG_H
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
|
|
#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.
|
|
*
|
|
* User can set type and one of content.ptr and content.value. (content is a union)
|
|
* The meaning of type and the content fields is totally up to the user,
|
|
* the corresponding fields are never read by the kernel.
|
|
*
|
|
*/
|
|
typedef struct msg {
|
|
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;
|
|
} 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.
|
|
*
|
|
* @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.
|
|
*
|
|
* @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)
|
|
*/
|
|
int msg_send(msg_t *m, unsigned int target_pid, bool block);
|
|
|
|
|
|
/**
|
|
* @brief Send message from interrupt.
|
|
*
|
|
* Will be automatically chosen instead of msg_send if inISR() == true
|
|
*
|
|
* @param m pointer to message structure
|
|
* @param target_pid PID of target thread
|
|
*
|
|
* @return 1 if sending was successful
|
|
* @return 0 if receiver is not waiting and block == false
|
|
*/
|
|
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.
|
|
*/
|
|
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.
|
|
*/
|
|
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
|
|
*/
|
|
int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid);
|
|
|
|
/**
|
|
* @brief Replies to a message.
|
|
*
|
|
* 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
|
|
*
|
|
* @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!
|
|
*/
|
|
int msg_init_queue(msg_t *array, int num);
|
|
|
|
/** @} */
|
|
#endif /* __MSG_H */
|