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