Messages
Overview
Message queues provide a mechanism to transmit one or more messages to a task. (Queue names and purposes are defined in Kernel Environment.)
Transmission of messages is performed in three steps:
- Sender task allocates a message structure
- Message parameters are filled
- Message structure is pushed in the kernel
A message is identified by a unique ID composed of the task type and an increasing number. A message has a list of parameters that is defined in a structure (see Message Format).
Message Format
The structure of the message contains:
- id: Message identifier
- dest_id: Destination kernel identifier
- src_id: Source kernel identifier
- param_len: Parameter embedded structure length
- param: Parameter embedded structure. Must be word-aligned.
The source and destination tasks describe which task the message is coming from/to. As a task can implement multiple instances, these source and destination task identifiers are constructed with both the task index and the task type, as shown in the "Destination or source task identifier construction" figure.
Figure: Destination or source task identifier construction
Parameter Management
During message allocation, the size of the parameter is passed and memory is allocated in the kernel heap. To store this data, the pointer on the parameters is returned. The scheduler frees this memory after the transition completion.
Message Queue Primitives
Message Allocation
ke_msg_alloc
Prototype:
void *ke_msg_alloc(ke_msg_id_t const id, ke_task_id_t const dest_id, ke_task_id_t const src_id, uint16_t const param_str)
Parameters:
Type |
Parameters |
Description |
---|---|---|
ke_msg_id_t |
id |
Message Identifier |
ke_task_id_t |
dest_id |
Destination Task Identifier |
ke_task_id_t |
src_id |
Source Task Identifier |
uint16_t |
param_len |
Size of the message parameters to be allocated |
Return:
Pointer to the parameter member of the ke_msg. If the parameter structure is empty, the pointer points to the end of the message and must not be used (except to retrieve the message pointer or to send the message).
Description:
This primitive allocates memory for a message that has to be sent. The memory is allocated dynamically on the heap, and the length of the variable parameter structure must be provided in order to allocate the correct size.
Message Allocation Macro (Static Structure)
KE_MSG_ALLOC
Prototype:
KE_MSG_ALLOC(id, dest_id, src_id, param_str)
Parameters:
Type |
Parameters |
Description |
---|---|---|
ke_msg_id_t |
id |
Message Identifier |
ke_task_id_t |
dest_id |
Destination Task Identifier |
ke_task_id_t |
src_id |
Source Task Identifier |
void const * |
param_str |
Structure tag for the message data |
Return:
Pointer to the allocated structure cast to the correct type.
Description:
This macro calls ke_msg_alloc() and cast the returned pointer to the appropriate structure. Can only be used if a parameter structure exists for this message (otherwise, use ke_msg_send_basic()).
Message Allocation Macro (Variable Structure)
KE_MSG_ALLOC_DYN
Prototype:
KE_MSG_ALLOC_DYN(id, dest_id, src_id, param_str, length)
Parameters:
Type |
Parameters |
Description |
---|---|---|
ke_msg_id_t |
id |
Message Identifier |
ke_task_id_t |
dest_id |
Destination Task Identifier |
ke_task_id_t |
src_id |
Source Task Identifier |
void const * |
param_str |
Structure tag for the message data |
uint16_t |
length |
Length of the variable portion of the data structure |
Return:
Pointer to the allocated structure of variable length, cast to the correct type.
Description:
This macro calls ke_msg_alloc() and cast the returned pointer to the appropriate structure. Can only be used if a parameter structure exists for this message (otherwise, use ke_msg_send_basic()).
NOTE: This function can only be used if the variable data array is located at the end of the structure to be allocated.
Message Free
ke_msg_free
Prototype:
void ke_msg_free(struct ke_msg const *param)
Parameters:
Type |
Parameters |
Description |
---|---|---|
struct ke_msg const * |
param |
Pointer to the message to be freed |
Return:
None
Description:
Free allocated message.
Message Free Macro
KE_MSG_FREE
Prototype:
KE_MSG_FREE(param_ptr)
Parameters:
Type |
Parameters |
Description |
---|---|---|
void const * |
param_ptr |
Structure tag for the message data |
Return:
None
Description:
This macro calls ke_msg_free() to free a previously allocated message.
Message Send
ke_msg_send
Prototype:
void ke_msg_send(void const *param_ptr)
Parameters:
Type |
Parameters |
Description |
---|---|---|
void const * |
param_ptr |
Pointer to the parameter member of the message that is to be sent |
Return:
None
Description:
Send a message previously allocated with any ke_msg_alloc()-like functions. The kernel takes care of freeing the message memory. Once the function has been called, it is not possible to access the message's data any more as the kernel might have copied the message and freed the original memory.
Message Send Basic
ke_msg_send_basic
Prototype:
void ke_msg_send_basic(ke_msg_id_t const id, ke_task_id_t const dest_id, ke_task_id_t const src_id)
Parameters:
Type |
Parameters |
Description |
---|---|---|
ke_msg_id_t |
id |
Message Identifier |
ke_task_id_t |
dest_id |
Destination Task Identifier |
ke_task_id_t |
src_id |
Source Task Identifier |
Return:
None
Description:
Send a message that has a zero length parameter member. No allocation is required as this is performed internally.
Message Forward
ke_msg_forward
Prototype:
void ke_msg_forward(void const *param_ptr, ke_task_id_t const dest_id, ke_task_id_t const src_id)
Parameters:
Type |
Parameters |
Description |
---|---|---|
void const * |
param_ptr |
Pointer to the parameter member of the message that is to be sent |
ke_task_id_t |
dest_id |
Destination Task Identifier |
ke_task_id_t |
src_id |
Source Task Identifier |
Return:
None
Description:
Forward a message to another task by changing its destination and source task IDs.