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

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Message Queue Management ====
   3 /**
   4 @addtogroup CMSIS_RTOS_Message Message Queue
   5 @ingroup CMSIS_RTOS
   6 @brief Exchange messages between threads in a FIFO-like operation.
   7 @details
   8 \b Message \b passing is another basic communication model between threads. In the message passing model, one thread sends
   9 data explicitly, while another thread receives it. The operation is more like some kind of I/O rather than a direct access to
  10 information to be shared. In CMSIS-RTOS, this mechanism is called s \b message \b queue. The data is passed from one thread
  11 to another in a FIFO-like operation. Using message queue functions, you can control, send, receive, or wait for messages. The
  12 data to be passed can be of integer or pointer type:
  13
  14 \image html "MessageQueue.png" "CMSIS-RTOS Message Queue"
  15
  16 Compared to a \ref CMSIS_RTOS_PoolMgmt, message queues are less efficient in general, but solve a broader range of problems.
  17 Sometimes, threads do not have a common address space or the use of shared memory raises problems, such as mutual exclusion.
  18
  19 \note The functions \ref osMessageQueuePut, \ref osMessageQueueGet, \ref osMessageQueueGetCapacity,
  20 \ref osMessageQueueGetMsgSize, \ref osMessageQueueGetCount, \ref osMessageQueueGetSpace can be called from
  21 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  22 \note Refer to \ref msgQueueConfig for RTX5 configuration options.
  23 @{
  24 */
  25 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  26 /**
  27 \def osMessageQueueId_t
  28 \details
  29 */
  30
  31 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  32 /**
  33 \struct osMessageQueueAttr_t
  34 \details
  35 Attributes structure for message queue.
  36 */
  37
  38 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  39 /**
  40 \fn osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
  41 \details
  42 The function \b osMessageQueueNew creates and initializes a message queue object and returns the pointer to the message queue
  43 object identifier or \token{NULL} in case of an error. It can be safely called before the RTOS is
  44 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  45
  46 The parameter \a msg_count specifies the maximum number of messages om the queue.
  47
  48 The parameter \a msg_size sets message size in bytes.
  49
  50 The parameter \a attr specifies additional message queue attributes. Default attributes will be used if set to \token{NULL}.
  51
  52 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  53
  54 <b>Code Example</b>
  55
  56 Refer to \ref osMessageQueuePut
  57 */
  58
  59 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  60 /**
  61 \fn const char *osMessageQueueGetName (osMessageQueueId_t mq_id)
  62 \details
  63 The function \b osMessageQueueGetName returns the pointer to the name string of the message queue identified by parameter \a
  64 mq_id or \token{NULL} in case of an error.
  65
  66 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  67 */
  68
  69 */
  70 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  71 /**
  72 \fn osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
  73 \details
  74 The blocking function \b osMessageQueuePut puts a message into the the message queue specified by parameter \a mq_id.
  75
  76 The parameter \a msg_ptr points to the buffer with the message to be put into the queue.
  77
  78 The parameter \a msg_prio defines the message priority (higher numbers indicate a higher priority).
  79
  80 The parameter \a timeout specifies how long the system waits to put the message into the queue. While the system waits, the
  81 thread that is calling this function is put into the \b BLOCKED state. The parameter \ref CMSIS_RTOS_TimeOutValue "timeout"
  82 can have the following values:
  83  - when \a timeout is \token{0}, the function returns instantly.
  84  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the message is delivered.
  85  - all other values specify a time in kernel ticks for a timeout.
  86
  87 Possible \ref osStatus_t return values:
  88  - \em osOK: the message has been put into the queue.
  89  - \em osErrorTimeout: the message could not be put into the queue in the given time.
  90  - \em osErrorResource: not enough space in the queue.
  91  - \em osErrorParameter: the parameter \a mq_id is incorrect, non-zero timeout specified in an ISR.
  92
  93 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
  94 \token{0}.
  95
  96 <b>Code Example:</b>
  97 \code
  98 #include "cmsis_os2.h"                                             // CMSIS RTOS header file
  99
 100 /*----------------------------------------------------------------------------
 101  *      Message Queue creation & usage
 102  *---------------------------------------------------------------------------*/
 103
 104 void Thread_MsgQueue1 (void *argument);                            // thread function 1
 105 void Thread_MsgQueue2 (void *argument);                            // thread function 2
 106 osThreadId_t tid_Thread_MsgQueue1;                                 // thread id 1
 107 osThreadId_t tid_Thread_MsgQueue2;                                 // thread id 2
 108
 109 #define MSGQUEUE_OBJECTS      16                                   // number of Message Queue Objects
 110
 111 typedef struct {                                                   // object data type
 112   uint8_t Buf[32];
 113   uint8_t Idx;
 114 } MSGQUEUE_OBJ_t;
 115
 116 osMessageQueueId_t mid_MsgQueue;                                   // message queue id
 117
 118 int Init_MsgQueue (void) {
 119
 120   mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);
 121   if (!mid_MsgQueue) {
 122     ; // Message Queue object not created, handle failure
 123   }
 124
 125   tid_Thread_MsgQueue1 = osThreadNew (Thread_MsgQueue1, NULL, NULL);
 126   if (!tid_Thread_MsgQueue1) return(-1);
 127   tid_Thread_MsgQueue2 = osThreadNew (Thread_MsgQueue2, NULL, NULL);
 128   if (!tid_Thread_MsgQueue2) return(-1);
 129
 130   return(0);
 131 }
 132
 133 void Thread_MsgQueue1 (void *argument) {
 134   MSGQUEUE_OBJ_t msg;
 135
 136   while (1) {
 137     ; // Insert thread code here...
 138     msg.Buf[0] = 0x55;                                           // do some work...
 139     msg.Idx    = 0;
 140     osMessageQueuePut (mid_MsgQueue, &msg, 0, NULL);
 141     osThreadYield ();                                              // suspend thread
 142   }
 143 }
 144
 145 void Thread_MsgQueue2 (void *argument) {
 146
 147   MSGQUEUE_OBJ_t msg;
 148   osStatus_t status;
 149
 150   while (1) {
 151     ; // Insert thread code here...
 152     status = osMessageQueueGet (mid_MsgQueue, &msg, NULL, NULL);  // wait for message
 153     if (status == osOK) {
 154         ; // process data
 155     }
 156   }
 157 }
 158 \endcode
 159 */
 160
 161 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 162 /**
 163 \fn osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
 164 \details
 165 The function \b osMessageQueueGet retrieves a message from the message queue specified by the parameter \a mq_id and saves it
 166 to the buffer pointed to by the parameter \a msg_ptr.
 167
 168 The parameter \a msg_prio is a pointer to the buffer containing the message priority or token{NULL}.
 169
 170 The parameter \a timeout specifies how long the system waits to retrieve the message from the queue. While the system waits,
 171 the thread that is calling this function is put into the \b BLOCKED state. The parameter
 172 \ref CMSIS_RTOS_TimeOutValue "timeout" can have the following values:
 173  - when \a timeout is \token{0}, the function returns instantly.
 174  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the message is retrieved.
 175  - all other values specify a time in kernel ticks for a timeout.
 176
 177 Possible \ref osStatus_t return values:
 178  - \em osOK: the message has been retrieved from the queue.
 179  - \em osErrorTimeout: the message could not be retrieved from the queue in the given time.
 180  - \em osErrorResource: nothing to get from  the queue.
 181  - \em osErrorParameter: the parameter \a mq_id is incorrect, non-zero timeout specified in an ISR.
 182
 183 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 184 \token{0}.
 185
 186 <b>Code Example</b>
 187
 188 Refer to \ref osMessageQueuePut
 189 */
 190
 191 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 192 /**
 193 \fn uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
 194 \details
 195 The function \b osMessageQueueGetCapacity returns the maximum number of messages in the message queue object specified by
 196 parameter \a mq_id or \token{0} in case of an error.
 197
 198 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 199 */
 200
 201 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 202 /**
 203 \fn uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
 204 \details
 205 The function \b osMessageQueueGetMsgSize returns the maximum message size in bytes for the message queue object specified by
 206 parameter \a mq_id or \token{0} in case of an error.
 207
 208 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 209 */
 210
 211 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 212 /**
 213 \fn uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)
 214 \details
 215 The function \b osMessageQueueGetCount returns the number of queued messages in the message queue object specified by
 216 parameter \a mq_id or \token{0} in case of an error.
 217
 218 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 219 */
 220
 221 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 222 /**
 223 \fn uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)
 224 \details
 225 The function \b osMessageQueueGetSpace returns the number available slots for messages in the message queue object specified
 226 by parameter \a mq_id or \token{0} in case of an error.
 227
 228 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 229 */
 230
 231 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 232 /**
 233 \fn osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)
 234 \details
 235 The function \b osMessageQueueReset resets the message queue specified by the parameter \a mq_id.
 236
 237 Possible \ref osStatus_t return values:
 238  - \em osOK: the message queue has been rest.
 239  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid.
 240  - \em osErrorResource: the message queue specified by parameter \a mq_id is in an invalid message queue state.
 241  - \em osErrorISR: \b osMessageQueueReset cannot be called from interrupt service routines.
 242
 243 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 244 */
 245
 246 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 247 /**
 248 \fn osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)
 249 \details
 250 The function \b osMessageQueueDelete deletes a message queue object specified by parameter \a mq_id. It releases internal
 251 memory obtained for message queue handling. After this call, the \a mq_id is no longer valid and cannot be used. The
 252 message queue may be created again using the function \ref osMessageQueueNew.
 253
 254 Possible \ref osStatus_t return values:
 255  - \em osOK: the message queue object has been deleted.
 256  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid.
 257  - \em osErrorResource: the message queue specified by parameter \a mq_id is in an invalid message queue state.
 258  - \em osErrorISR: \b osMessageQueueDelete cannot be called from interrupt service routines.
 259
 260 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 261 */
 262 /// @}