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:

Table: Message Allocation 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:

Table: Message Allocation Macro Parameters for Static Structures

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:

Table: Message Dynamic Allocation 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:

Table: Message Free 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:

Table: Message Free 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:

Table: Message Send 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:

Table: Message Send Basic 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:

Table: Message Forward 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.