begriffs open source - cmsis/blob - CMSIS/Documentation/Doxygen/RTOS2/src/ref_cmsis_os2_msg_queue.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
  23 @{
  24 */
  25 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  26 /**
  27 \def osMessageQueueId_t
  28 \details
  29 Returned by:
  30 - \ref osMessageQueueNew
  31 */
  32
  33 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  34 /**
  35 \struct osMessageQueueAttr_t
  36 \details
  37 Specifies the following attributes for the \ref osMessageQueueNew function.
  38 */
  39
  40 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  41 /**
  42 \fn osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
  43 \details
  44 The function \ref osMessageQueueNew creates and initializes a  message queue object.
  45 The function returns a message queue object identifier or \token{NULL} in case of an error.
  46
  47 The function can be called after kernel initialization with \ref osKernelInitialize. It is possible to
  48 create message queue objects before the RTOS kernel is started with \ref osKernelStart.
  49
  50 The total amount of memory required for the message queue data is at least <code>msg_count * msg_size</code>.
  51 The \em msg_size is rounded up to a double even number to ensure 32-bit alignment of the memory blocks.
  52
  53 The memory blocks allocated from the message queue have a fixed size defined with the parameter \c msg_size.
  54
  55 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  56
  57 <b>Code Example</b>
  58
  59 Refer to \ref osMessageQueuePut
  60 */
  61
  62 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  63 /**
  64 \fn const char *osMessageQueueGetName (osMessageQueueId_t mq_id)
  65 \details
  66 The function \b osMessageQueueGetName returns the pointer to the name string of the message queue identified by parameter \a
  67 mq_id or \token{NULL} in case of an error.
  68
  69 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  70 */
  71
  72 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  73 /**
  74 \fn osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)
  75 \details
  76 The blocking function \b osMessageQueuePut puts the message pointed to by \a msg_ptr into the the message queue specified
  77 by parameter \a mq_id. The parameter \a msg_prio is used to sort message according their priority (higher numbers indicate
  78 a higher priority) on insertion.
  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 \ref ThreadStates "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 (i.e. try semantics).
  84  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the message is delivered (i.e. wait semantics).
  85  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
  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 (wait-timed semantics).
  90  - \em osErrorResource: not enough space in the queue (try semantics).
  91  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid, non-zero timeout specified in an ISR.
  92  - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified message queue.
  93
  94 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
  95 \token{0}.
  96
  97 <b>Code Example:</b>
  98 \code
  99 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 100
 101 /*----------------------------------------------------------------------------
 102  *      Message Queue creation & usage
 103  *---------------------------------------------------------------------------*/
 104
 105 #define MSGQUEUE_OBJECTS 16                     // number of Message Queue Objects
 106
 107 typedef struct {                                // object data type
 108   uint8_t Buf[32];
 109   uint8_t Idx;
 110 } MSGQUEUE_OBJ_t;
 111
 112 osMessageQueueId_t mid_MsgQueue;                // message queue id
 113
 114 osThreadId_t tid_Thread_MsgQueue1;              // thread id 1
 115 osThreadId_t tid_Thread_MsgQueue2;              // thread id 2
 116
 117 void Thread_MsgQueue1 (void *argument);         // thread function 1
 118 void Thread_MsgQueue2 (void *argument);         // thread function 2
 119
 120 int Init_MsgQueue (void) {
 121
 122   mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);
 123   if (mid_MsgQueue == NULL) {
 124     ; // Message Queue object not created, handle failure
 125   }
 126
 127   tid_Thread_MsgQueue1 = osThreadNew(Thread_MsgQueue1, NULL, NULL);
 128   if (tid_Thread_MsgQueue1 == NULL) {
 129     return(-1);
 130   }
 131   tid_Thread_MsgQueue2 = osThreadNew(Thread_MsgQueue2, NULL, NULL);
 132   if (tid_Thread_MsgQueue2 == NULL) {
 133     return(-1);
 134   }
 135
 136   return(0);
 137 }
 138
 139 void Thread_MsgQueue1 (void *argument) {
 140   MSGQUEUE_OBJ_t msg;
 141
 142   while (1) {
 143     ; // Insert thread code here...
 144     msg.Buf[0] = 0x55U;                                         // do some work...
 145     msg.Idx    = 0U;
 146     osMessageQueuePut(mid_MsgQueue, &msg, 0U, 0U);
 147     osThreadYield();                                            // suspend thread
 148   }
 149 }
 150
 151 void Thread_MsgQueue2 (void *argument) {
 152   MSGQUEUE_OBJ_t msg;
 153   osStatus_t status;
 154
 155   while (1) {
 156     ; // Insert thread code here...
 157     status = osMessageQueueGet(mid_MsgQueue, &msg, NULL, 0U);   // wait for message
 158     if (status == osOK) {
 159       ; // process data
 160     }
 161   }
 162 }
 163 \endcode
 164 */
 165
 166 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 167 /**
 168 \fn osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
 169 \details
 170 The function \b osMessageQueueGet retrieves a message from the message queue specified by the parameter \a mq_id and saves it
 171 to the buffer pointed to by the parameter \a msg_ptr. The message priority is stored to parameter \a msg_prio if not token{NULL}.
 172
 173 The parameter \a timeout specifies how long the system waits to retrieve the message from the queue. While the system waits,
 174 the thread that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter
 175 \ref CMSIS_RTOS_TimeOutValue "timeout" can have the following values:
 176  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 177  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the message is retrieved (i.e. wait semantics).
 178  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 179
 180 Possible \ref osStatus_t return values:
 181  - \em osOK: the message has been retrieved from the queue.
 182  - \em osErrorTimeout: the message could not be retrieved from the queue in the given time (timed-wait semantics).
 183  - \em osErrorResource: nothing to get from the queue (try semantics).
 184  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid, non-zero timeout specified in an ISR.
 185  - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified message queue.
 186
 187 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 188 \token{0}.
 189
 190 <b>Code Example</b>
 191
 192 Refer to \ref osMessageQueuePut
 193 */
 194
 195 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 196 /**
 197 \fn uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
 198 \details
 199 The function \b osMessageQueueGetCapacity returns the maximum number of messages in the message queue object specified by
 200 parameter \a mq_id or \token{0} in case of an error.
 201
 202 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 203 */
 204
 205 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 206 /**
 207 \fn uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
 208 \details
 209 The function \b osMessageQueueGetMsgSize returns the maximum message size in bytes for the message queue object specified by
 210 parameter \a mq_id or \token{0} in case of an error.
 211
 212 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 213 */
 214
 215 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 216 /**
 217 \fn uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)
 218 \details
 219 The function \b osMessageQueueGetCount returns the number of queued messages in the message queue object specified by
 220 parameter \a mq_id or \token{0} in case of an error.
 221
 222 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 223 */
 224
 225 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 226 /**
 227 \fn uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)
 228 \details
 229 The function \b osMessageQueueGetSpace returns the number available slots for messages in the message queue object specified
 230 by parameter \a mq_id or \token{0} in case of an error.
 231
 232 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 233 */
 234
 235 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 236 /**
 237 \fn osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)
 238 \details
 239 The function \b osMessageQueueReset resets the message queue specified by the parameter \a mq_id.
 240
 241 Possible \ref osStatus_t return values:
 242  - \em osOK: the message queue has been rest.
 243  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid.
 244  - \em osErrorResource: the message queue is in an invalid state.
 245  - \em osErrorISR: \b osMessageQueueReset cannot be called from interrupt service routines.
 246  - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified message queue.
 247
 248 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 249 */
 250
 251 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 252 /**
 253 \fn osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)
 254 \details
 255 The function \b osMessageQueueDelete deletes a message queue object specified by parameter \a mq_id. It releases internal
 256 memory obtained for message queue handling. After this call, the \a mq_id is no longer valid and cannot be used. The
 257 message queue may be created again using the function \ref osMessageQueueNew.
 258
 259 Possible \ref osStatus_t return values:
 260  - \em osOK: the message queue object has been deleted.
 261  - \em osErrorParameter: parameter \em mq_id is \token{NULL} or invalid.
 262  - \em osErrorResource: the message queue is in an invalid state.
 263  - \em osErrorISR: \b osMessageQueueDelete cannot be called from interrupt service routines.
 264  - \em osErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified message queue.
 265
 266 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 267 */
 268 /// @}
 269
 270 // these struct members must stay outside the group to avoid double entries in documentation
 271 /**
 272 \var osMessageQueueAttr_t::attr_bits
 273 \details
 274 Reserved for future use (must be set to '0' for future compatibility).
 275
 276 \var osMessageQueueAttr_t::cb_mem
 277 \details
 278 Pointer to a memory for the message queue control block object. Refer to \ref CMSIS_RTOS_MemoryMgmt_Manual for more information.
 279
 280 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the message queue control block.
 281
 282 \var osMessageQueueAttr_t::cb_size
 283 \details
 284 The size (in bytes) of memory block passed with \ref cb_mem. Required value depends on the underlying kernel implementation.
 285
 286 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 287
 288 \var osMessageQueueAttr_t::name
 289 \details
 290 Pointer to a constant string with a human readable name (displayed during debugging) of the message queue object.
 291
 292 Default: \token{NULL} no name specified.
 293
 294 \var osMessageQueueAttr_t::mq_mem
 295 \details
 296 Pointer to a memory for the message queue data. Refer to \ref CMSIS_RTOS_MemoryMgmt_Manual for more information.
 297
 298 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the memory pool data.
 299
 300 \var osMessageQueueAttr_t::mq_size
 301 \details
 302 The size (in bytes) of memory block passed with \ref mq_mem. The minimum memory block size is <code>msg_count * msg_size</code> (parameters of the \ref osMessageQueueNew function). The \em msg_size is rounded up to a double even number to ensure 32-bit alignment of the memory blocks.
 303
 304 Default: 0 as the default is no memory provided with \ref mq_mem.
 305 */