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(3U, 3U, NULL);
  52   while(1) {
  53     osSemaphoreAcquire(multiplex_id, osWaitForever);
  54     // do something
  55     osSemaphoreRelease(multiplex_id);
  56   }
  57 }
  58 \endcode
  59
  60 <b>Producer/Consumer Semaphore</b>
  61
  62 The producer-consumer problem can be solved using two semaphores.
  63
  64 A first semaphore (\token{empty_id}) counts down the available (empty) buffers, i.e.
  65 the producer thread can wait for available buffer slots by acquiring from this one.
  66
  67 A second semaphore (\token{filled_id}) counts up the used (filled) buffers, i.e.
  68 the consumer thread can wait for available data by acquiring from this one.
  69
  70 It is crucial for the correct behaviour that the threads acquire and release on both
  71 semaphores in the given sequence. According to this example one can have multiple
  72 producer and/or consumer threads running concurrently.
  73
  74 \code
  75 #define BUFFER_SIZE 10U
  76
  77 osSemaphoreId_t empty_id = osSemaphoreNew(BUFFER_SIZE, BUFFER_SIZE, NULL);
  78 osSemaphoreId_t filled_id = osSemaphoreNew(BUFFER_SIZE, 0U, NULL);
  79
  80 void producer_thread (void) {
  81   while(1) {
  82     osSemaphoreAcquire(empty_id, osWaitForever);
  83     // produce data
  84     osSemaphoreRelease(filled_id);
  85   }
  86 }
  87
  88 void consumer_thread (void) {
  89
  90   while(1){
  91     osSemaphoreAcquire(filled_id, osWaitForever);
  92     // consume data
  93     osSemaphoreRelease(empty_id);
  94   }
  95 }
  96 \endcode
  97
  98 @{
  99 */
 100
 101 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 102 /**
 103 \typedef  osSemaphoreId_t
 104 \details
 105 Returned by:
 106 - \ref osSemaphoreNew
 107 */
 108
 109 /**
 110 \struct osSemaphoreAttr_t
 111 \details
 112 Specifies the following attributes for the \ref osSemaphoreNew function.
 113 */
 114
 115 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 116 /**
 117 \fn osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
 118 \details
 119 The function \b osSemaphoreNew creates and initializes a semaphore object that is used to manage access to shared resources
 120 and returns the pointer to the semaphore object identifier or \token{NULL} in case of an error. It can be safely called
 121 before the RTOS is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 122
 123 The parameter \em max_count specifies the maximum number of available tokens. A \em max_count value of 1 creates a binary
 124 semaphore.
 125
 126 The parameter \em initial_count sets the initial number of available tokens.
 127
 128 The parameter \em attr specifies additional semaphore attributes. Default attributes will be used if set to \token{NULL}.
 129
 130 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 131
 132 <b>Code Example</b>
 133 \code
 134 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 135
 136 osSemaphoreId_t sid_Semaphore;                  // semaphore id
 137
 138 osThreadId_t tid_Thread_Semaphore;              // thread id
 139
 140 void Thread_Semaphore (void *argument);         // thread function
 141
 142 int Init_Semaphore (void) {
 143
 144   sid_Semaphore = osSemaphoreNew(2U, 2U, NULL);
 145   if (sid_Semaphore == NULL) {
 146     ; // Semaphore object not created, handle failure
 147   }
 148
 149   tid_Thread_Semaphore = osThreadNew(Thread_Semaphore, NULL, NULL);
 150   if (tid_Thread_Semaphore == NULL) {
 151     return(-1);
 152   }
 153
 154   return(0);
 155 }
 156
 157 void Thread_Semaphore (void *argument) {
 158   osStatus_t val;
 159
 160   while (1) {
 161     ; // Insert thread code here...
 162
 163     val = osSemaphoreAcquire(sid_Semaphore, 10U);       // wait for max. 10 ticks for semaphore token to get available
 164     switch (val) {
 165       case osOK:
 166         ; // Use protected code here...
 167         osSemaphoreRelease(sid_Semaphore);              // return a token back to a semaphore
 168         break;
 169       case osErrorResource:
 170         break;
 171       case osErrorParameter:
 172         break;
 173       default:
 174         break;
 175     }
 176
 177     osThreadYield();                                    // suspend thread
 178   }
 179 }
 180 \endcode
 181 */
 182
 183 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 184 /**
 185 \fn const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id)
 186 \details
 187 The function \b osSemaphoreGetName returns the pointer to the name string of the semaphore identified by parameter \a
 188 semaphore_id or \token{NULL} in case of an error.
 189
 190 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 191 */
 192
 193 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 194 /**
 195 \fn osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)
 196 \details
 197 The blocking function \b osSemaphoreAcquire waits until a token of the semaphore object specified by parameter
 198 \a semaphore_id becomes available. If a token is available, the function instantly returns and decrements the token count.
 199
 200 The parameter \a timeout specifies how long the system waits to acquire the token. While the system waits, the thread
 201 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
 202 "timeout" can have the following values:
 203  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 204  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the semaphore becomes
 205    available (i.e. wait semantics).
 206  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 207
 208 Possible \ref osStatus_t return values:
 209  - \em osOK: the token has been obtained and the token count decremented.
 210  - \em osErrorTimeout: the token could not be obtained in the given time.
 211  - \em osErrorResource: the token could not be obtained when no \a timeout was specified.
 212  - \em osErrorParameter: the parameter \a semaphore_id is \token{NULL} or invalid.
 213
 214 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 215 \token{0}.
 216
 217 <b>Code Example</b>
 218
 219 Refer to \ref osSemaphoreNew.
 220 */
 221
 222 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 223 /**
 224 \fn osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id)
 225 \details
 226 The function \b osSemaphoreRelease releases a token of the semaphore object specified by parameter \a semaphore_id. Tokens
 227 can only be released up to the maximum count specified at creation time, see \ref osSemaphoreNew. Other threads that
 228 currently wait for a token of this semaphore object will be put into the \ref ThreadStates "READY" state.
 229
 230 Possible \ref osStatus_t return values:
 231  - \em osOK: the token has been released and the count incremented.
 232  - \em osErrorResource: the token could not be released (maximum token count has been reached).
 233  - \em osErrorParameter: the parameter \a semaphore_id is \token{NULL} or invalid.
 234
 235 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 236
 237 <b>Code Example</b>
 238
 239 Refer to \ref osSemaphoreNew.
 240 */
 241
 242 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 243 /**
 244 \fn uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)
 245 \details
 246 The function \b osSemaphoreGetCount returns the number of available tokens of the semaphore object specified by parameter
 247 \a semaphore_id. In case of an error it returns \token{0}.
 248
 249 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 250 */
 251
 252 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 253 /**
 254 \fn osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id)
 255 \details
 256 The function \b osSemaphoreDelete deletes a semaphore object specified by parameter \a semaphore_id. It releases internal
 257 memory obtained for semaphore handling. After this call, the \a semaphore_id is no longer valid and cannot be used. The
 258 semaphore may be created again using the function \ref osSemaphoreNew.
 259
 260 Possible \ref osStatus_t return values:
 261  - \em osOK: the semaphore object has been deleted.
 262  - \em osErrorParameter: the parameter \a semaphore_id is \token{NULL} or invalid.
 263  - \em osErrorResource: the semaphore is in an invalid state.
 264  - \em osErrorISR: \b osSemaphoreDelete cannot be called from interrupt service routines.
 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 osSemaphoreAttr_t::attr_bits
 273 \details
 274 Reserved for future use (must be set to '0' for future compatibility).
 275
 276 \var osSemaphoreAttr_t::cb_mem
 277 \details
 278 Pointer to a memory for the semaphore control block object. Refer to \ref StaticObjectMemory for more information.
 279
 280 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the semaphore control block.
 281
 282 \var osSemaphoreAttr_t::cb_size
 283 \details
 284 The size (in bytes) of memory block passed with \ref cb_mem. For RTX, the minimum value is defined with \ref osRtxSemaphoreCbSize (higher values are permitted).
 285
 286 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 287
 288 \var osSemaphoreAttr_t::name
 289 \details
 290 Pointer to a constant string with a human readable name (displayed during debugging) of the semaphore object.
 291
 292 Default: \token{NULL} no name specified.
 293 */