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