The Application Message Service (AMS) provides a central interface to transmit and receive application messages via the Control Channel of the MOST network. The so called application messages can have a payload size of up to 65535 bytes. Since the payload size of a single MOST control message is limited to 45 bytes (MOST150), an application messages with larger payload is transmitted via segmented transfer. The Application Message Service provides a common interface for single and segmented transfer and automatically performs segmentation.
See also API Reference, section Application Message Service. |
Any message which is received or transmitted via the Application Message Service requires a certain amount of memory. The UNICENS Library reserves an amount of memory which can be adjusted by defining the number und payload of AMS Tx and Rx messages. The configuration file ucs_cfg.h can be modified to your specific needs. A possible configuration might be:
The corresponding configuration will look like this:
Prior to the call of Ucs_Init(), the application is able to configure the AMS-related part of the initialization structure. The following table provides a brief overview of all parameters.
Parameter | Default | Mandatory | Description |
---|---|---|---|
rx.message_received_fptr | NULL | No | Callback function that is invoked on message reception |
tx.message_freed_fptr | NULL | No | Callback function that is invoked if memory dedicated to a Tx message is freed after a prior allocation has failed |
tx.default_llrbc | 10 | No | Default low-level retry block count for Tx messages |
The code below shows a possible initialization sequence of the Application Message Service.
See also Getting Started, section Initialization. |
In order to transmit an application message you haves to process the following steps.
data_ptr
[] beyond the specified amount of payload.The following example explains how to retrieve a message object with a payload size of 3 bytes. Be aware of the function Ucs_AmsTx_AllocMsg() might return NULL
if it is not possible to allocate the required amount of memory for the message.
As soon as the transmission has been completed, the Application Message Service will invoke the callback function that was passed to Ucs_AmsTx_SendMsg(). The application's callback function must have the function signature of Ucs_AmsTx_CompleteCb_t. Within the callback function, the application is allowed to access the message object (read only). After the callback function has returned, the application is no longer allowed to access the message object.
An example implementation of such a callback function is shown below.
An application may also transmit an application message with "external" payload. This might be useful to avoid copy operations if the message payload is already available in a continuous memory chunk. Process the following steps in order to transmit an application message with external payload.
data_size
. So the Application Message Service will not allocate a separate memory chunk for the payload.data_ptr
to the external payload reference. Set data_size
to define the desired amount of payload to transmit.The following example explains how to retrieve a message object and assign a predefined string as external payload. It is important to pass a callback function to Ucs_AmsTx_SendMsg(). The Application Message Service calls this function after the transmission is finished.
After completed transmission, the Application Message Service will invoke the callback function that was passed to Ucs_AmsTx_SendMsg(). The application is responsible to free or reuse the external payload. The Application Message Service will no longer access it.
By calling ams.rx.message_received_fptr() the AMS notifies that a new Rx message was received and has been added to the Rx queue. It is recommended that the application processes the Rx queue asynchronously, i.e., not within the ams.rx.message_received_fptr(). Therefore, the AMS provides the functions Ucs_AmsRx_PeekMsg(), Ucs_AmsRx_ReleaseMsg() and Ucs_AmsRx_GetMsgCnt(). The example shows that the callback function is implemented to set the variable _process_rx
to true
. The following main loop will process Rx messages if the variable is set. Instead of implementing the callback function it is also possible to use Ucs_AmsRx_GetMsgCnt() to retrieve the number of available messages in the Rx queue.
The asynchronous processing of the AMS Rx queue provides a comfortable way to process messages at the best moment for the application. During high message load it is possible that the application is not able to respond to a message immediately. In that case the application shall not call Ucs_AmsRx_ReleaseMsg(). Later, when it is able to process the message it can retrieve the same Rx message object by calling Ucs_AmsRx_PeekMsg().
See also API Reference, section Application Message Service. |