# 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.