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 */
  62
  63 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  64 /**
  65 \typedef  osSemaphoreId_t
  66 \details
  67 */
  68
  69 /**
  70 \struct osSemaphoreAttr_t
  71 \details
  72 */
  73
  74 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  75 /**
  76 \fn osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
  77 \details
  78 The function \b osSemaphoreNew creates and initializes a semaphore object that is used to manage access to shared resources
  79 and returns the pointer to the semaphore object identifier or \token{NULL} in case of an error. It can be safely called
  80 before the RTOS is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  81
  82 The parameter \em max_count specifies the maximum number of available tokens. A \em max_count value of 1 creates a binary
  83 semaphore.
  84
  85 The parameter \em initial_count sets the initial number of available tokens.
  86
  87 The parameter \em attr specifies additional semaphore attributes. Default attributes will be used if set to \token{NULL}.
  88
  89 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  90
  91 <b>Code Example</b>
  92 \code
  93 #include "cmsis_os2.h"                                     // CMSIS RTOS header file
  94
  95 void Thread_Semaphore (void *argument);                    // thread function
  96 osThreadId_t tid_Thread_Semaphore;                         // thread id
  97
  98 osSemaphoreId_t sid_Thread_Semaphore;                      // semaphore id
  99
 100 int Init_Semaphore (void)
 101 {
 102
 103   sid_Thread_Semaphore = osSemaphoreNew(2, 2, NULL);
 104   if (!sid_Thread_Semaphore) {
 105     ; // Semaphore object not created, handle failure
 106   }
 107
 108   tid_Thread_Semaphore = osThreadNew (Thread_Semaphore, NULL, NULL);
 109   if (!tid_Thread_Semaphore) {
 110     return(-1);
 111   }
 112
 113   return(0);
 114 }
 115
 116 void Thread_Semaphore (void *argument)
 117 {
 118   osStatus_t val;
 119
 120   while (1) {
 121     ; // Insert thread code here...
 122
 123     val = osSemaphoreAcquire (sid_Thread_Semaphore, 10);   // wait for max. 10 ticks for semaphore token to get available
 124     switch (val) {
 125     case osOK:
 126       ; // Use protected code here...
 127       osSemaphoreRelease (sid_Thread_Semaphore);           // Return a token back to a semaphore
 128       break;
 129     case osErrorResource:
 130       break;
 131     case osErrorParameter:
 132       break;
 133     default:
 134       break;
 135     }
 136
 137     osThreadYield ();                                      // suspend thread
 138   }
 139 }
 140 \endcode
 141 */
 142
 143 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 144 /**
 145 \fn const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id)
 146 \details
 147 The function \b osSemaphoreGetName returns the pointer to the name string of the semaphore identified by parameter \a
 148 semaphore_id or \token{NULL} in case of an error.
 149
 150 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 151 */
 152
 153 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 154 /**
 155 \fn osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)
 156 \details
 157 The blocking function \b osSemaphoreAcquire waits until a token of the semaphore object specified by parameter
 158 \a semaphore_id becomes available. If a token is available, the function instantly returns and decrements the token count.
 159
 160 The parameter \a timeout specifies how long the system waits to acquire the token. While the system waits, the thread/ISR
 161 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
 162 "timeout" can have the following values:
 163  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 164  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the semaphore becomes
 165    available (i.e. wait semantics).
 166  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 167
 168 Possible \ref osStatus_t return values:
 169  - \em osOK: the token has been obtained.
 170  - \em osErrorTimeout: the token could not be obtained in the given time.
 171  - \em osErrorResource: the token could not be obtained when no \a timeout was specified.
 172  - \em osErrorParameter: the parameter \a semaphore_id is incorrect.
 173
 174 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 175 \token{0}.
 176
 177 <b>Code Example</b>
 178
 179 Refer to \ref osSemaphoreNew.
 180 */
 181
 182 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 183 /**
 184 \fn osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id)
 185 \details
 186 The function \b osSemaphoreRelease releases a token of the semaphore object specified by parameter \a semaphore_id. Other
 187 threads that currently wait for a token of this semaphore object will be put into the \ref ThreadStates "READY" state.
 188
 189 Possible \ref osStatus_t return values:
 190  - \em osOK: the token has been correctly released and the count increased.
 191  - \em osErrorResource: the maximum token count has been reached.
 192  - \em osErrorParameter: the parameter \a semaphore_id is incorrect.
 193
 194 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 195
 196 <b>Code Example</b>
 197
 198 Refer to \ref osSemaphoreNew.
 199 */
 200
 201 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 202 /**
 203 \fn uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)
 204 \details
 205 The function \b osSemaphoreGetCount returns the number of available tokens of the semaphore object specified by parameter
 206 \a semaphore_id. In case of an error it returns \token{0}.
 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 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id)
 214 \details
 215 The function \b osSemaphoreDelete deletes a semaphore object specified by parameter \a semaphore_id. It releases internal
 216 memory obtained for semaphore handling. After this call, the \a semaphore_id is no longer valid and cannot be used. The
 217 semaphore may be created again using the function \ref osSemaphoreNew.
 218
 219 Possible \ref osStatus_t return values:
 220  - \em osOK: the semaphore object has been deleted.
 221  - \em osErrorParameter: the parameter \a semaphore_id is \token{NULL} or invalid.
 222  - \em osErrorResource: the semaphore specified by parameter \em semaphore_id is in an invalid semaphore state.
 223  - \em osErrorISR: \b osSemaphoreDelete cannot be called from interrupt service routines.
 224
 225 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 226 */
 227 /// @}
 228
 229 // these struct members must stay outside the group to avoid double entries in documentation
 230 /**
 231 \var osSemaphoreAttr_t::attr_bits
 232 \details
 233 Reserved for future use (set to '0').\n
 234 Default: \token{0}.
 235
 236 \var osSemaphoreAttr_t::cb_mem
 237 \details
 238 Pointer to a memory location for the semaphore control block object. This can optionally be used for custom memory management systems.\n
 239 Default: \token{NULL} (uses kernel memory management).
 240
 241
 242 \var osSemaphoreAttr_t::cb_size
 243 \details
 244 The size of the memory block passed with \ref cb_mem. Must be the size of a semaphore control block object or larger.
 245
 246 \var osSemaphoreAttr_t::name
 247 \details
 248 Pointer to a string with a human readable name of the semaphore object.\n
 249 Default: \token{NULL}.
 250 */