Embedded software applications occasionally may need to pass data around the application. When data needs to be passed or when data being received is going to be used to synchronize thread execution, a developer may decide to use a message queue. In this post, we will explore message queues and how to use them.
A message queue is the primary method within an RTOS to transmit information from one thread to the next. A message queue contains at least one mailbox to contain the transmitted message. A single message must be at least one word in size (32 bits). Messages that are sixteen words or larger should be passed by pointer in order to minimize memory usage and improve performance. The mailbox contains a stand-alone message copy so if a pointer to the data is being used, the data must not be modified until after the receiving thread has dereferenced the pointer and accessed the data. A message queue can contain more than a single message box which allows messages to accumulate in the queue for processing by a receiving thread.
Creating a message queue in the Renesas Synergy™ development environment is similar to creating a semaphore, mutex or event flag. A developer opens the Synergy Configurator, navigates to the threads tab and then within the selected thread, adds a queue. An example queue that is added into the blinky thread can be seen below:
Once the queue has been created, a developer can select the queue and navigate to the Synergy properties window to create the initial settings. The configurable properties can be seen below:
Developers can provide the queue a string name and a symbol name that will be used in the code. A developer also needs to specify how many words the message size will be. In the example above, a developer specifies that the queue size is 20 bytes and that the message size is 4 bytes (1 word). The queue can hold 5 messages (20/4) before the queue is full.
There are several APIs that a developer can use to interact with the message queue. These are detailed in the ThreadX user manual which can be downloaded from the Synergy Gallery. The primary APIs that we will discuss are the following:
UINT tx_queue_receive(TX_QUEUE *queue_ptr, VOID *destination_ptr, ULONG wait_option)
UINT tx_queue_send(TX_QUEUE *queue_ptr, VOID *source_ptr, ULONG wait_option)
If a developer wanted to send a message using the queue shown earlier, they would need a UINT status variable along with a ULONG variable for storing their message. For example, a developer would create something similar to following:
UINT status;
ULONG my_message[4] = {0x00, 0x00, 0x00, 0x00};
A developer could then use the tx_queue_send API call to send my_message as follows:
status = tx_queue_send(&my_RxQue, my_message, TX_NO_WAIT);
Another thread would then use the tx_queue_receive API call to wait for data to be received. Developers have the option to have the receive call continue executing if no message are available, TX_NO_WAIT, block until a message is received, TX_WAIT_FOREVER or only block for a timeout period. The receive API implementation would be as follows:
status = tx_queue_receive(&my_RxQue, my_message, TX_WAIT_FOREVER);
Keep in mind that the ThreadX Message Queue mechanism provides basic RTOS messaging capabilities. If additional capabilities such as:
are needed, a develop may want to consider using the Synergy Messaging Framework which extends the message queue capabilities. To learn more about the Messaging Framework, consider reading Getting started with the Messaging Framework.
Until next time,
Live long and profit!
Professor_IoT
Hot Tip of the Week
One of the most important ways to learn about using the Synergy Platform in your application is to look at working application projects available on the Synergy Kit web page here.
In order to import these existing projects into your ISDE- either e2 studio or IAR EW for Synergy- you can follow along the step by step instructions provided in the application note available here. After you do this the first time, it will be easy to remember. Don’t delay. Start importing those projects today!