msg.h

Messaging API for inter process communication.

KERNEL_PID_ISR

Value of msg.h::msg_t::sender_pid if the sender was an interrupt service routine. 

1
(KERNEL_PID_LAST + 1)
int msg_send(msg_t * m, kernel_types.h::kernel_pid_t target_pid)

Send a message (blocking).

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.

Parameters

m:Pointer to preallocated msg_t structure, must not be NULL.
target_pid:PID of target thread

Return values

  • 1, if sending was successful (message delivered directly or to a queue)
  • 0, if called from ISR and receiver cannot receive the message now (it is not waiting or it’s message queue is full)
  • -1, on error (invalid PID)
int msg_try_send(msg_t * m, kernel_types.h::kernel_pid_t target_pid)

Send a message (non-blocking).

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. This function will never block.

Parameters

m:Pointer to preallocated msg_t structure, must not be NULL.
target_pid:PID of target thread

Return values

  • 1, if sending was successful (message delivered directly or to a queue)
  • 0, if receiver is not waiting or has a full message queue
  • -1, on error (invalid PID)
int msg_send_to_self(msg_t * m)

Send a message to the current thread.

Will work only if the thread has a message queue.

Will be automatically chosen instead of msg_send if target_pid == thread_pid. This function never blocks.

Parameters

m:pointer to message structure

Return values

  • 1 if sending was successful
  • 0 if the thread’s message queue is full (or inexistent)
int msg_send_int(msg_t * m, kernel_types.h::kernel_pid_t target_pid)

Send message from interrupt.

Will be automatically chosen instead of msg.h::msg_send() if called from an interrupt/ISR.

The value of m->sender_pid is set to msg.h::KERNEL_PID_ISR.

See also

msg.h::msg_sent_by_int()

Parameters

m:Pointer to preallocated msg_t structure, must not be NULL.
target_pid:PID of target thread.

Return values

  • 1, if sending was successful
  • 0, if receiver is not waiting and block == 0
  • -1, on error (invalid PID)
int msg_sent_by_int(const msg_t * m)

Test if the message was sent inside an ISR.

See also

msg.h::msg_send_int()

Parameters

m:The message in question.

Return values

  • == 0 if not sent by an ISR
  • != 0 if sent by an ISR
int msg_receive(msg_t * m)

Receive a message.

This function blocks until a message was received.

Parameters

m:Pointer to preallocated msg_t structure, must not be NULL.

Return values

  • 1, Function always succeeds or blocks forever.
int msg_try_receive(msg_t * m)

Try to receive a message.

This function does not block if no message can be received.

Parameters

m:Pointer to preallocated msg_t structure, must not be NULL.

Return values

  • 1, if a message was received
  • -1, otherwise.
int msg_send_receive(msg_t * m, msg_t * reply, kernel_types.h::kernel_pid_t target_pid)

Send a message, block until reply received.

This function sends a message to target_pid and then blocks until target has sent a reply which is then stored in reply.

Parameters

m:Pointer to preallocated msg_t structure with the message to send, must not be NULL.
reply:Pointer to preallocated msg. Reply will be written here, must not be NULL. Can be identical to m.
target_pid:The PID of the target process

Return values

  • 1, if successful.
int msg_reply(msg_t * m, msg_t * reply)

Replies to a message.

Sender must have sent the message with msg.h::msg_send_receive().

Parameters

m:message to reply to, must not be NULL.
reply:message that target will get as reply, must not be NULL.

Return values

  • 1, if successful
  • -1, on error
int msg_reply_int(msg_t * m, msg_t * reply)

Replies to a message from interrupt.

An ISR can obviously not receive messages, however a thread might delegate replying to a message to an ISR.

Parameters

m:message to reply to, must not be NULL.
reply:message that target will get as reply, must not be NULL.

Return values

  • 1, if successful
  • -1, on error
int msg_avail(void)

Check how many messages are available in the message queue.

Return values

  • Number of messages available in our queue on success
  • -1, if no caller’s message queue is initialized
void msg_init_queue(msg_t * array, int num)

Initialize the current thread’s message queue.

Parameters

array:Pointer to preallocated array of msg_t structures, must not be NULL.
num:Number of msg_t structures in array. MUST BE POWER OF TWO!

void msg_queue_print(void)

Prints the message queue of the current thread.

struct msg_t

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.

kernel_types.h::kernel_pid_t sender_pid

PID of sending thread.

Will be filled in by msg_send.

uint16_t type

Type field.

void * ptr

Pointer content field.

uint32_t value

Value content field.

union msg_t::@2 content

Content of the message.