begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Message.txt

   1
   2
   3 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   4 //  ==== Message Queue Management ====
   5 /**
   6 @addtogroup CMSIS_RTOS_Message Message Queue
   7 @ingroup CMSIS_RTOS
   8 @brief Exchange messages between threads in a FIFO-like operation.
   9 @details
  10 \b Message \b passing is another basic communication model between threads. In the message passing model, one thread sends
  11 data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to
  12 information to be shared. In CMSIS-RTOS, this mechanism is called s \b message \b queue. The data is passed from one thread
  13 to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The
  14 data to be passed can be of integer or pointer type:
  15
  16 \image html "MessageQueue.png" "CMSIS-RTOS Message Queue"
  17
  18 Compared to a \ref CMSIS_RTOS_PoolMgmt, message queues are less efficient in general, but solve a broader range of problems.
  19 Sometimes, threads do not have a common address space or the use of shared memory raises problems, such as mutual exclusion.
  20
  21 Working with Message Queues
  22 ---------------------------
  23 Follow these steps to create and use a message queue:
  24 -# Setup the message queue:
  25 \code{.c}
  26 osMessageQueueId_t MsgQ_Id;                                       // Define a message queue ID
  27 \endcode
  28 -# Then, create the message queue in a thread:
  29 \code{.c}
  30 MsgQId_Isr = osMessageQueueNew (16, sizeof(uint32_t), NULL);      // Instance a message queue for 16 elements of uint32_t
  31 \endcode
  32 -# Fill the message queue with data:
  33 \code{.c}
  34 uint32_t data = 512;
  35
  36 osMessageQueuePut(MsgQ_Id, data, 0, 0);
  37 \endcode
  38 -# From the receiving thread access the data using:
  39 \code{.c}
  40 uint32_t msg;
  41 osMessageQueueGet(MsgQ_Id, &msg, NULL, 0);
  42 \endcode
  43
  44 @{
  45 */
  46 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  47 /**
  48 \def osMessageQueueId_t
  49 \details
  50
  51 */
  52 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  53 /**
  54 \struct osMessageQueueAttr_t
  55 \details
  56 Attributes structure for message queue.
  57 */
  58
  59 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  60 /**
  61 \fn osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
  62 \details
  63
  64 */
  65 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  66 /**
  67 \fn osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
  68 \details
  69 <b>Code Example:</b>
  70 \code{.c}
  71
  72 #include "cmsis_os2.h"                                           // CMSIS RTOS header file
  73
  74 /*----------------------------------------------------------------------------
  75  *      Message Queue creation & usage
  76  *---------------------------------------------------------------------------*/
  77
  78 void Thread_MsgQueue1 (void *argument);                   // thread function 1
  79 void Thread_MsgQueue2 (void *argument);                   // thread function 2
  80 osThreadId_t tid_Thread_MsgQueue1;                                // thread id 1
  81 osThreadId_t tid_Thread_MsgQueue2;                                // thread id 2
  82
  83 #define MSGQUEUE_OBJECTS      16                                // number of Message Queue Objects
  84
  85 typedef struct {                                                // object data type
  86   uint8_t Buf[32];
  87   uint8_t Idx;
  88 } MSGQUEUE_OBJ_t;
  89
  90 osMemoryPoolId_t mpid_MemPool2;                                         // memory pool id
  91 osMessageQueueId_t mid_MsgQueue;                                      // message queue id
  92
  93 int Init_MsgQueue (void) {
  94
  95   mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);
  96   if (!mid_MsgQueue) {
  97     ; // Message Queue object not created, handle failure
  98   }
  99
 100   tid_Thread_MsgQueue1 = osThreadNew (Thread_MsgQueue1, NULL, NULL);
 101   if (!tid_Thread_MsgQueue1) return(-1);
 102   tid_Thread_MsgQueue2 = osThreadNew (Thread_MsgQueue2, NULL, NULL);
 103   if (!tid_Thread_MsgQueue2) return(-1);
 104
 105   return(0);
 106 }
 107
 108 void Thread_MsgQueue1 (void *argument) {
 109   MSGQUEUE_OBJ_t pMsg = 0;
 110
 111   while (1) {
 112     ; // Insert thread code here...
 113     pMsg->Buf[0] = 0x55;                                           // do some work...
 114     pMsg->Idx    = 0;
 115     osMessageQueuePut (mid_MsgQueue, &pMsg, NULL, NULL);
 116     osThreadYield ();                                             // suspend thread
 117   }
 118 }
 119
 120 void Thread_MsgQueue2 (void *argument) {
 121
 122   MSGQUEUE_OBJ_t pMsg = 0;
 123
 124   while (1) {
 125     ; // Insert thread code here...
 126     status = osMessageQueueGet (mid_MsgQueue, &pMsg, NULL, NULL);     // wait for message
 127     if (status == osOK) {
 128         ; // process data
 129     }
 130   }
 131 }
 132 \endcode
 133
 134 */
 135 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 136 /**
 137 \fn osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
 138 \details
 139
 140 */
 141 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 142 /**
 143 \fn uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
 144 \details
 145
 146 */
 147 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 148 /**
 149 \fn uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
 150 \details
 151
 152 */
 153 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 154 /**
 155 \fn uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)
 156 \details
 157
 158 */
 159 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 160 /**
 161 \fn uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)
 162 \details
 163
 164 */
 165 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 166 /**
 167 \fn osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)
 168 \details
 169
 170 */
 171 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 172 /**
 173 \fn osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)
 174 \details
 175
 176 */
 177 /// @}