From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- docs/RTOS/html/group__CMSIS__RTOS__Message.html | 489 ++++++++++++++++++++++++ 1 file changed, 489 insertions(+) create mode 100644 docs/RTOS/html/group__CMSIS__RTOS__Message.html (limited to 'docs/RTOS/html/group__CMSIS__RTOS__Message.html') diff --git a/docs/RTOS/html/group__CMSIS__RTOS__Message.html b/docs/RTOS/html/group__CMSIS__RTOS__Message.html new file mode 100644 index 0000000..083aeae --- /dev/null +++ b/docs/RTOS/html/group__CMSIS__RTOS__Message.html @@ -0,0 +1,489 @@ + + + + + +Message Queue +CMSIS-RTOS: Message Queue + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS +  Version 1.03 +
+
Real-Time Operating System: API and RTX Reference Implementation.
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Macros | +Functions
+
+
Message Queue
Inter-Thread Communication and Resource Sharing
+
+
+ +

Exchange messages between threads in a FIFO-like operation. +More...

+ + + + + + + + + + + +

+Macros

#define osFeature_MessageQ   1
 Message Queues: 1=available, 0=not available. More...
 
#define osMessageQDef(name, queue_sz, type)
 Create a Message Queue Definition. More...
 
#define osMessageQ(name)   &os_messageQ_def_##name
 Access a Message Queue Definition. More...
 
+ + + + + + + + + + +

+Functions

osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)
 Create and Initialize a Message Queue. More...
 
osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec)
 Put a Message to a Queue. More...
 
osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec)
 Get a Message or Wait for a Message from a Queue. More...
 
+

Description

+

Message passing is another basic communication model between threads. In the message passing model, one thread sends data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to information to be shared. In CMSIS-RTOS, this mechanism is called s message queue. The data is passed from one thread to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The data to be passed can be of integer or pointer type:

+
+MessageQueue.png +
+CMSIS-RTOS Message Queue
+

Compared to a Memory Pool, message queues are less efficient in general, but solve a broader range of problems. Sometimes, threads do not have a common address space or the use of shared memory raises problems, such as mutual exclusion.

+

Working with Message Queues

+

Follow these steps to create and use a message queue:

+
    +
  1. Setup the message queue:
    osMessageQDef(message_q, 5, uint32_t); // Declare a message queue
    +
    osMessageQId (message_q_id); // Declare an ID for the message queue
    +
    2. +
  2. Then, create the message queue in a thread:
    message_q_id = osMessageCreate(osMessageQ(message_q), NULL);
    +
    3. +
  3. Fill the message queue with data:
    uint32_t data = 512;
    +
    +
    osMailPut(message_q_id, data, osWaitForever);
    +
    4. +
  4. From the receiving thread access the data using:
    osEvent event = osMessageGet(message_q_id, osWaitForever);
    +
    5. +
+

Macro Definition Documentation

+ +
+
+ + + + +
#define osFeature_MessageQ   1
+
+

A CMSIS-RTOS implementation may support message queues.

+ +

CMSIS-RTOS RTX Setting: osFeature_MessageQ is 1

+ +
+
+ +
+
+ + + + + + + + +
#define osMessageQ( name)   &os_messageQ_def_##name
+
+

Access to the message queue definition for the function osMessageCreate.

+
Parameters
+ + +
namename of the queue
+
+
+
Note
CAN BE CHANGED: The parameter to osMessageQ shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
#define osMessageQDef( name,
 queue_sz,
 type 
)
+
+

Define the attributes of a message queue created by the function osMessageCreate using osMessageQ.

+
Parameters
+ + + + +
namename of the queue.
queue_szmaximum number of messages in the queue.
typedata type of a single message element (for debugger).
+
+
+
Note
CAN BE CHANGED: The parameter to osMessageQDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
+ +
+
+

Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + +
osMessageQId osMessageCreate (const osMessageQDef_t * queue_def,
osThreadId thread_id 
)
+
+
Parameters
+ + + +
[in]queue_defqueue definition referenced with osMessageQ.
[in]thread_idthread ID (obtained by osThreadCreate or osThreadGetId) or NULL.
+
+
+
Returns
message queue ID for reference by other functions or NULL in case of error.
+
Note
MUST REMAIN UNCHANGED: osMessageCreate shall be consistent in every CMSIS-RTOS.
+

Create and initialize a message queue. The parameter thread_id registers the receiving thread for a message and is needed for the general osWait function to deliver the message.

+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
osThreadId tid_thread1; // ID for thread 1
+
osThreadId tid_thread2; // for thread 2
+
+
typedef struct { // Message object structure
+
float voltage; // AD result of measured voltage
+
float current; // AD result of measured current
+
int counter; // A counter value
+
} T_MEAS;
+
+
osPoolDef(mpool, 16, T_MEAS); // Define memory pool
+
osPoolId mpool;
+
osMessageQDef(MsgBox, 16, &T_MEAS); // Define message queue
+
osMessageQId MsgBox;
+
+
void send_thread (void const *argument); // forward reference
+
void recv_thread (void const *argument); // forward reference
+
// Thread definitions
+
osThreadDef(send_thread, osPriorityNormal, 1, 0);
+
osThreadDef(recv_thread, osPriorityNormal, 1, 2000);
+
+
//
+
// Thread 1: Send thread
+
//
+
void send_thread (void const *argument) {
+
T_MEAS *mptr;
+
+
mptr = osPoolAlloc(mpool); // Allocate memory for the message
+
mptr->voltage = 223.72; // Set the message content
+
mptr->current = 17.54;
+
mptr->counter = 120786;
+
osMessagePut(MsgBox, (uint32_t)mptr, osWaitForever); // Send Message
+
osDelay(100);
+
+
mptr = osPoolAlloc(mpool); // Allocate memory for the message
+
mptr->voltage = 227.23; // Prepare a 2nd message
+
mptr->current = 12.41;
+
mptr->counter = 170823;
+
osMessagePut(MsgBox, (uint32_t)mptr, osWaitForever); // Send Message
+
osThreadYield(); // Cooperative multitasking
+
// We are done here, exit this thread
+
}
+
+
//
+
// Thread 2: Receive thread
+
//
+
void recv_thread (void const *argument) {
+
T_MEAS *rptr;
+
osEvent evt;
+
+
for (;;) {
+
evt = osMessageGet(MsgBox, osWaitForever); // wait for message
+
if (evt.status == osEventMessage) {
+
rptr = evt.value.p;
+
printf ("\nVoltage: %.2f V\n", rptr->voltage);
+
printf ("Current: %.2f A\n", rptr->current);
+
printf ("Number of cycles: %d\n", rptr->counter);
+
osPoolFree(mpool, rptr); // free memory allocated for message
+
}
+
}
+
}
+
+
void StartApplication (void) {
+
mpool = osPoolCreate(osPool(mpool)); // create memory pool
+
MsgBox = osMessageCreate(osMessageQ(MsgBox), NULL); // create msg queue
+
+
tid_thread1 = osThreadCreate(osThread(send_thread), NULL);
+
tid_thread2 = osThreadCreate(osThread(recv_thread), NULL);
+
:
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + +
osEvent osMessageGet (osMessageQId queue_id,
uint32_t millisec 
)
+
+
Parameters
+ + + +
[in]queue_idmessage queue ID obtained with osMessageCreate.
[in]millisecTimout Value or 0 in case of no time-out.
+
+
+
Returns
event information that includes status code.
+
Note
MUST REMAIN UNCHANGED: osMessageGet shall be consistent in every CMSIS-RTOS.
+

Suspend the execution of the current RUNNING thread until a message arrives. When a message is already in the queue, the function returns instantly with the message information.

+

The argument millisec specifies how long the system waits for a message to become available. While the system waits the thread that is calling this function is put into the state WAITING. The millisec timeout value can have the following values:

+
    +
  • when millisec is 0, the function returns instantly.
    • +
  • when millisec is set to osWaitForever the function will wait for an infinite time until a message arrives.
    • +
  • all other values specify a time in millisecond for a timeout.
    • +
+
Note
The parameter millisec must be 0 for using this function in an ISR.
+
+Interrupt Service Routines can call this function.
+

Status and Error Codes
+

+
    +
  • osOK: no message is available in the queue and no timeout was specified.
    • +
  • osEventTimeout: no message has arrived during the given timeout period.
    • +
  • osEventMessage: message received, value.p contains the pointer to message.
    • +
  • osErrorParameter: a parameter is invalid or outside of a permitted range.
    • +
+ +
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
osStatus osMessagePut (osMessageQId queue_id,
uint32_t info,
uint32_t millisec 
)
+
+
Parameters
+ + + + +
[in]queue_idmessage queue ID obtained with osMessageCreate.
[in]infomessage information.
[in]millisecTimout Value or 0 in case of no time-out.
+
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osMessagePut shall be consistent in every CMSIS-RTOS.
+

Put the message info in a message queue specified by queue_id.

+

When the message queue is full, the system retries for a specified time with millisec. While the system retries the thread that is calling this function is put into the state WAITING. The millisec timeout can have the following values:

+
    +
  • when millisec is 0, the function returns instantly.
    • +
  • when millisec is set to osWaitForever the function will wait for an infinite time until a message queue slot becomes available.
    • +
  • all other values specify a time in millisecond for a timeout.
    • +
+
Note
The parameter millisec must be 0 for using this function in an ISR.
+
+Interrupt Service Routines can call this function.
+

Status and Error Codes
+

+
    +
  • osOK: the message is put into the queue.
    • +
  • osErrorResource: no memory in the queue was available.
    • +
  • osErrorTimeoutResource: no memory in the queue was available during the given time limit.
    • +
  • osErrorParameter: a parameter is invalid or outside of a permitted range.
    • +
+ +
+
+
+
+ + + + -- cgit