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

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Semaphore Management ====
   3 /**
   4 \addtogroup CMSIS_RTOS_SemaphoreMgmt Semaphores
   5 \ingroup CMSIS_RTOS
   6 \brief Access shared resources simultaneously from different threads.
   7 \details
   8 Semaphores are used to manage and protect access to shared resources. Semaphores are very similar to
   9 \ref CMSIS_RTOS_MutexMgmt "Mutexes". Whereas a Mutex permits just one thread to access a shared resource at a
  10 time, a semaphore can be used to permit a fixed number of threads/ISRs to access a pool of shared resources. Using
  11 semaphores, access to a group of identical peripherals can be managed (for example multiple DMA channels).
  12
  13 \image html "Semaphore.png" "CMSIS-RTOS Semaphore"
  14
  15 A semaphore object should be initialized to the maximum number of available tokens. This number of available resources is
  16 specified as parameter of the \ref osSemaphoreNew function. Each time a semaphore token is obtained with \ref osSemaphoreAcquire
  17 (in \em available state), the semaphore count is decremented. When the semaphore count is 0 (i.e. \em depleted state), no
  18 more semaphore tokens can be obtained. The thread/ISR that tries to obtain the semaphore token needs to wait until the next
  19 token is free. Semaphores are released with \ref osSemaphoreRelease incrementing the semaphore count.
  20
  21 \image html "semaphore_states.png" "CMSIS-RTOS Semaphore States"
  22
  23 \note The functions \ref osSemaphoreAcquire, \ref osSemaphoreGetCount, and \ref osSemaphoreRelease can be called from
  24 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  25
  26 \note Refer to \ref semaphoreConfig for RTX5 configuration options.
  27
  28 Semaphore Use Cases
  29 -------------------
  30 Due to their flexibility, semaphores cover a wide range of synchronizing applications. At the same time, they are perhaps the
  31 most challenging RTOS object to understand. The following explains a use case for semaphores, taken from the book
  32 <a href="http://www.greenteapress.com/semaphores/" target="_blank">The Little Book Of Semaphores</a> by Allen B. Downey which
  33 is available for free download.
  34
  35 <b>Non-binary Semaphore (Multiplex)</b>
  36
  37 A multiplex limits the number of threads that can access a critical section of code. For example, this could be a function
  38 accessing DMA resources which can only support a limited number of calls.
  39
  40 To allow multiple threads to run the function, initialize a semaphore to the maximum number of threads that can be allowed.
  41 The number of tokens in the semaphore represents the number of additional threads that may enter. If this number is zero,
  42 then the next thread trying to access the function will have to wait until one of the other threads exits and releases its
  43 token. When all threads have exited the token number is back to n. The following example shows the code for one of the
  44 threads that might access the resource:
  45
  46 \code
  47 osSemaphoreId_t multiplex_id;
  48
  49 void thread_n (void)
  50 {
  51   multiplex_id = osSemaphoreNew(3, 3, NULL);
  52   while(1)
  53     {
  54       osSemaphoreAcquire(multiplex_id, osWaitForever);
  55       // do something
  56       osSemaphoreRelease(multiplex_id);
  57     }
  58 }
  59 \endcode
  60
  61 <b>Producer/Consumer Semaphore</b>
  62
  63 The producer-consumer problem can be solved using two semaphores.
  64
  65 A first semaphore (\token{empty_id}) counts down the available (empty) buffers, i.e.
  66 the producer thread can wait for available buffer slots by acquiring from this one.
  67
  68 A second semaphore (\token{filled_id}) counts up the used (filled) buffers, i.e.
  69 the consumer thread can wait for available data by acquiring from this one.
  70
  71 It is crucial for the correct behaviour that the threads acquire and release on both
  72 semaphores in the given sequence. According to this example one can have multiple
  73 producer and/or consumer threads running concurrently.
  74
  75 \code
  76 #define BUFFER_SIZE 10
  77 osSemaphoreId_t empty_id = osSemaphoreNew(BUFFER_SIZE, BUFFER_SIZE, NULL);
  78 osSemaphoreId_t filled_id = osSemaphoreNew(BUFFER_SIZE, 0, NULL);
  79
  80 void producer_thread (void)
  81 {
  82   while(1)
  83   {
  84     osSemaphoreAcquire(empty_id, osWaitForever);
  85     // produce data
  86     osSemaphoreRelease(filled_id);
  87   }
  88 }
  89
  90 void consumer_thread (void)
  91 {
  92   while(1)
  93   {
  94     osSemaphoreAcquire(filled_id, osWaitForever);
  95     // consume data
  96     osSemaphoreRelease(empty_id);
  97   }
  98 }
  99 \endcode
 100
 101 @{
 102 */
 103
 104 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 105 /**
 106 \typedef  osSemaphoreId_t
 107 \details
 108 Returned by:
 109 - \ref osSemaphoreNew
 110 */
 111
 112 /**
 113 \struct osSemaphoreAttr_t
 114 \details
 115 Attributes to configure a semaphore.
 116
 117 Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
 118  - osSemaphoreAttr_t::cb_mem
 119  - osSemaphoreAttr_t::cb_size
 120 */
 121
 122 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 123 /**
 124 \fn osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
 125 \details
 126 The function \b osSemaphoreNew creates and initializes a semaphore object that is used to manage access to shared resources
 127 and returns the pointer to the semaphore object identifier or \token{NULL} in case of an error. It can be safely called
 128 before the RTOS is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 129
 130 The parameter \em max_count specifies the maximum number of available tokens. A \em max_count value of 1 creates a binary
 131 semaphore.
 132
 133 The parameter \em initial_count sets the initial number of available tokens.
 134
 135 The parameter \em attr specifies additional semaphore attributes. Default attributes will be used if set to \token{NULL}.
 136 /*
 137 New definition:
 138 */
 139 Possible \ref osSemaphoreId_t return values:
 140 - pointer to the created semaphore object
 141 - \em NULL, if (\em max_count == 0U)
 142 - \em NULL, if  (\em max_count > \em MAX_SEMAPHORE_CNT)
 143 - \em NULL, if  (\em initial_count > \em max_count)
 144 - \em NULL, if the control block memory (\em attr->cb_mem) is not \em NULL and the memory is not 4 byte aligned
 145 - \em NULL, if the control block memory (\em attr->cb_mem) is not \em NULL but the size (\em attr->cb_size) is not big enough to store a \em semaphore object
 146 - \em NULL, if the control block memory (\em attr->cb_mem) is \em NULL but the size (\em attr->cb_size) is not 0
 147 - \em NULL, if the maximum number of semaphores have been created already
 148 - \em NULL, if IRQ is masked
 149 - \em NULL, if in IRQ mode.
 150
 151
 152
 153 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 154
 155 <b>Code Example</b>
 156 \code
 157 #include "cmsis_os2.h"                                     // CMSIS RTOS header file
 158
 159 void Thread_Semaphore (void *argument);                    // thread function
 160 osThreadId_t tid_Thread_Semaphore;                         // thread id
 161
 162 osSemaphoreId_t sid_Thread_Semaphore;                      // semaphore id
 163
 164 int Init_Semaphore (void)
 165 {
 166
 167   sid_Thread_Semaphore = osSemaphoreNew(2, 2, NULL);
 168   if (!sid_Thread_Semaphore) {
 169     ; // Semaphore object not created, handle failure
 170   }
 171
 172   tid_Thread_Semaphore = osThreadNew (Thread_Semaphore, NULL, NULL);
 173   if (!tid_Thread_Semaphore) {
 174     return(-1);
 175   }
 176
 177   return(0);
 178 }
 179
 180 void Thread_Semaphore (void *argument)
 181 {
 182   osStatus_t val;
 183
 184   while (1) {
 185     ; // Insert thread code here...
 186
 187     val = osSemaphoreAcquire (sid_Thread_Semaphore, 10);   // wait for max. 10 ticks for semaphore token to get available
 188     switch (val) {
 189     case osOK:
 190       ; // Use protected code here...
 191       osSemaphoreRelease (sid_Thread_Semaphore);           // Return a token back to a semaphore
 192       break;
 193     case osErrorResource:
 194       break;
 195     case osErrorParameter:
 196       break;
 197     default:
 198       break;
 199     }
 200
 201     osThreadYield ();                                      // suspend thread
 202   }
 203 }
 204 \endcode
 205 */
 206
 207 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 208 /**
 209 \fn const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id)
 210 \details
 211 The function \b osSemaphoreGetName returns the pointer to the name string of the semaphore identified by parameter \a
 212 semaphore_id or \token{NULL} in case of an error.
 213 /*
 214 New definition:
 215 */
 216 Possible return values:
 217 - pointer to the name string of the semaphore identified by parameter \a semaphore_id
 218 - \em NULL, if the semaphore specified by \a semaphore_id  is \em NULL
 219 - \em NULL, if a semaphore specified by \a semaphore_id does not exist
 220 - \em NULL, if the semaphore is in state \em 'osRtxObjectInactive'
 221 - \em NULL, if IRQ is masked
 222 - \em NULL, if in IRQ mode.
 223
 224
 225 \note This function \b cannot 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 osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)
 231 \details
 232 The blocking function \b osSemaphoreAcquire waits until a token of the semaphore object specified by parameter
 233 \a semaphore_id becomes available. If a token is available, the function instantly returns and decrements the token count.
 234
 235 The parameter \a timeout specifies how long the system waits to acquire the token. While the system waits, the thread
 236 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
 237 "timeout" can have the following values:
 238  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 239  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the semaphore becomes
 240    available (i.e. wait semantics).
 241  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 242
 243 Possible \ref osStatus_t return values:
 244 - \em 'osOK', if the token has been obtained
 245 - \em 'osErrorResource', if the semaphore specified by \a semaphore_id is in state \em 'osRtxObjectInactive'
 246 - \em 'osErrorTimeout', if the token is not available and \em timeout > 0
 247 - \em 'osErrorResource', if the token is not available and \em timeout == 0
 248 - \em 'osErrorParameter',  if a semaphore specified by \a semaphore_id does not exist
 249 - \em 'osErrorParameter', if semaphore_id equals \em NULL.
 250
 251
 252
 253 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 254 \token{0}.
 255
 256 <b>Code Example</b>
 257
 258 Refer to \ref osSemaphoreNew.
 259 */
 260
 261 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 262 /**
 263 \fn osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id)
 264 \details
 265 The function \b osSemaphoreRelease releases a token of the semaphore object specified by parameter \a semaphore_id. Tokens
 266 can only be released up to the maximum count specified at creation time, see \ref osSemaphoreNew. Other threads that
 267 currently wait for a token of this semaphore object will be put into the \ref ThreadStates "READY" state.
 268
 269 Possible \ref osStatus_t return values:
 270 - \em 'osOK', if the token has been correctly released and the count increased
 271 - \em 'osErrorParameter', if a semaphore specified by \a semaphore_id does not exist
 272 - \em 'osErrorParameter', if the semaphore specified by \a semaphore_id is \em NULL
 273 - \em 'osErrorResource', if the semaphore specified by \a semaphore_id is in state \em 'osRtxObjectInactive'.
 274 - \em 'osErrorResource', if no semaphore specified by \a semaphore_id has been taken.
 275
 276 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 277
 278 <b>Code Example</b>
 279
 280 Refer to \ref osSemaphoreNew.
 281 */
 282
 283 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 284 /**
 285 \fn uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)
 286 \details
 287 The function \b osSemaphoreGetCount returns the number of available tokens of the semaphore object specified by parameter
 288 \a semaphore_id. In case of an error it returns \token{0}.
 289
 290 Possible \ref osStatus_t return values:
 291 - \em the number of available tokens, in case of success
 292 - \em 0, if a semaphore specified by \a semaphore_id does not exist
 293 - \em 0, if the semaphore is \em NULL
 294 - \em 0, the semaphore is in state \em 'osRtxObjectInactive'.
 295
 296 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 297 */
 298
 299 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 300 /**
 301 \fn osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id)
 302 \details
 303 The function \b osSemaphoreDelete deletes a semaphore object specified by parameter \a semaphore_id. It releases internal
 304 memory obtained for semaphore handling. After this call, the \a semaphore_id is no longer valid and cannot be used. The
 305 semaphore may be created again using the function \ref osSemaphoreNew.
 306
 307 Possible \ref osStatus_t return values:
 308  - \em 'osOK', if the semaphore specified by \a semaphore_id has been deleted
 309  - \em 'osErrorResource', if the state of semaphore specified by \a semaphore_id is \em 'osRtxObjectInactive'
 310  - \em 'osErrorParameter', if a semaphore specified by \a semaphore_id does not exist
 311  - \em 'osErrorParameter', if the semaphore is \em NULL
 312  - \em 'osErrorISR', if IRQ is masked
 313  - \em 'osErrorISR', if in IRQ mode.
 314
 315 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 316 */
 317 /// @}
 318
 319 // these struct members must stay outside the group to avoid double entries in documentation
 320 /**
 321 \var osSemaphoreAttr_t::attr_bits
 322 \details
 323 Reserved for future use (set to '0').\n
 324 Default: \token{0}.
 325
 326 \var osSemaphoreAttr_t::cb_mem
 327 \details
 328 Pointer to a memory location for the semaphore control block object. This can optionally be used for custom memory management systems.\n
 329 Default: \token{NULL} (uses kernel memory management).
 330
 331
 332 \var osSemaphoreAttr_t::cb_size
 333 \details
 334 The size of the memory block passed with \ref cb_mem. Must be the size of a semaphore control block object or larger.
 335
 336 \var osSemaphoreAttr_t::name
 337 \details
 338 Pointer to a string with a human readable name of the semaphore object.\n
 339 Default: \token{NULL}.
 340 */