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
  17 \ref osSemaphoreAcquire, the semaphore count is decremented. When the semaphore count is 0, no semaphore token can be
  18 obtained. The thread/ISR that tries to obtain the semaphore token needs to wait until the next token is free. Semaphores are
  19 released with \ref osSemaphoreRelease incrementing the semaphore count.
  20
  21 \note The functions \ref osSemaphoreAcquire, \ref osSemaphoreGetCount, and \ref osSemaphoreRelease can be called from
  22 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  23
  24 \note Refer to \ref semaphoreConfig for RTX5 configuration options.
  25
  26 Semaphore Use Cases
  27 -------------------
  28 Due to their flexibility, semaphores cover a wide range of synchronizing applications. At the same time, they are perhaps the
  29 most challenging RTOS object to understand. The following explains a use case for semaphores, taken from the book
  30 <a href="http://www.greenteapress.com/semaphores/" target="_blank">The Little Book Of Semaphores</a> by Allen B. Downey which
  31 is available for free download.
  32
  33 <b>Non-binary Semaphore (Multiplex)</b>
  34
  35 A multiplex limits the number of threads that can access a critical section of code. For example, this could be a function
  36 accessing DMA resources which can only support a limited number of calls.
  37
  38 To allow multiple threads to run the function, initialize a semaphore to the maximum number of threads that can be allowed.
  39 The number of tokens in the semaphore represents the number of additional threads that may enter. If this number is zero,
  40 then the next thread trying to access the function will have to wait until one of the other threads exits and releases its
  41 token. When all threads have exited the token number is back to n. The following example shows the code for one of the
  42 threads that might access the resource:
  43
  44 \code
  45 osSemaphoreId_t multiplex_id;
  46
  47 void thread_n (void)
  48   {
  49     multiplex_id = osSemaphoreNew(3, 3, NULL);
  50     while(1)
  51       {
  52         osSemaphoreAcquire(multiplex_id, osWaitForever);
  53         // do something
  54         osSemaphoreRelease(multiplex_id);
  55       }
  56   }
  57 \endcode
  58 @{
  59 */
  60
  61 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  62 /**
  63 \typedef  osSemaphoreId_t
  64 \details
  65 */
  66
  67 /**
  68 \struct osSemaphoreAttr_t
  69 \details
  70 */
  71
  72 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  73 /**
  74 \fn osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
  75 \details
  76 The function \b osSemaphoreNew creates and initializes a semaphore object that is used to manage access to shared resources
  77 and returns the pointer to the semaphore object identifier or \token{NULL} in case of an error. It can be safely called
  78 before the RTOS is started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  79
  80 The parameter \em max_count specifies the maximum number of available tokens. A \em max_count value of 1 creates a binary
  81 semaphore.
  82
  83 The parameter \em initial_count sets the initial number of available tokens.
  84
  85 The parameter \em attr specifies additional semaphore attributes. Default attributes will be used if set to \token{NULL}.
  86
  87 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  88
  89 <b>Code Example</b>
  90 \code
  91 #include "cmsis_os2.h"                                     // CMSIS RTOS header file
  92
  93 void Thread_Semaphore (void *argument);                    // thread function
  94 osThreadId_t tid_Thread_Semaphore;                         // thread id
  95
  96 osSemaphoreId_t sid_Thread_Semaphore;                      // semaphore id
  97
  98 int Init_Semaphore (void)
  99 {
 100
 101   sid_Thread_Semaphore = osSemaphoreNew(2, 2, NULL);
 102   if (!sid_Thread_Semaphore) {
 103     ; // Semaphore object not created, handle failure
 104   }
 105
 106   tid_Thread_Semaphore = osThreadNew (Thread_Semaphore, NULL, NULL);
 107   if (!tid_Thread_Semaphore) {
 108     return(-1);
 109   }
 110
 111   return(0);
 112 }
 113
 114 void Thread_Semaphore (void *argument)
 115 {
 116   osStatus_t val;
 117
 118   while (1) {
 119     ; // Insert thread code here...
 120
 121     val = osSemaphoreAcquire (sid_Thread_Semaphore, 10);   // wait 10 mSec
 122     switch (val) {
 123     case osOK:
 124       ; // Use protected code here...
 125       osSemaphoreRelease (sid_Thread_Semaphore);           // Return a token back to a semaphore
 126       break;
 127     case osErrorResource:
 128       break;
 129     case osErrorParameter:
 130       break;
 131     default:
 132       break;
 133     }
 134
 135     osThreadYield ();                                      // suspend thread
 136   }
 137 }
 138 \endcode
 139 */
 140
 141 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 142 /**
 143 \fn const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id)
 144 \details
 145 The function \b osSemaphoreGetName returns the pointer to the name string of the semaphore identified by parameter \a
 146 semaphore_id or \token{NULL} in case of an error.
 147
 148 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 149 */
 150
 151 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 152 /**
 153 \fn osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout)
 154 \details
 155 The blocking function \b osSemaphoreAcquire waits until a token of the semaphore object specified by parameter
 156 \a semaphore_id becomes available. If a token is available, the function instantly returns and decrements the token count.
 157
 158 The parameter \a timeout specifies how long the system waits to acquire the token. While the system waits, the thread/ISR
 159 that is calling this function is put into the \b BLOCKED state. The parameter \ref CMSIS_RTOS_TimeOutValue "timeout" can have
 160 the following values:
 161  - when \a timeout is \token{0}, the function returns instantly.
 162  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the semaphore becomes
 163    available.
 164  - all other values specify a time in kernel ticks for a timeout.
 165
 166 Possible \ref osStatus_t return values:
 167  - \em osOK: the token has been obtained.
 168  - \em osErrorTimeout: the token could not be obtained in the given time.
 169  - \em osErrorResource: the token could not be obtained when no \a timeout was specified.
 170  - \em osErrorParameter: the parameter \a semaphore_id is incorrect.
 171
 172 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 173 \token{0}.
 174
 175 <b>Code Example</b>
 176
 177 Refer to \ref osSemaphoreNew.
 178 */
 179
 180 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 181 /**
 182 \fn osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id)
 183 \details
 184 The function \b osSemaphoreRelease releases a token of the semaphore object specified by parameter \a semaphore_id. Other
 185 threads/ISRs that currently wait for a token of this semaphore object will be put into the \b READY state.
 186
 187 Possible \ref osStatus_t return values:
 188  - \em osOK: the token has been correctly released and the count increased.
 189  - \em osErrorResource: the maximum token count has been reached.
 190  - \em osErrorParameter: the parameter \a semaphore_id is incorrect.
 191
 192 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 193
 194 <b>Code Example</b>
 195
 196 Refer to \ref osSemaphoreNew.
 197 */
 198
 199 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 200 /**
 201 \fn uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id)
 202 \details
 203 The function \b osSemaphoreGetCount returns the count of available semaphores of the semaphore object specified by parameter
 204 \a semaphore_id. In case of an error, it returns \token{0}.
 205
 206 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 207 */
 208
 209 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 210 /**
 211 \fn osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id)
 212 \details
 213 The function \b osSemaphoreDelete deletes a semaphore object specified by parameter \a semaphore_id. It releases internal
 214 memory obtained for semaphore handling. After this call, the \a semaphore_id is no longer valid and cannot be used. The
 215 semaphore may be created again using the function \ref osSemaphoreNew.
 216
 217 Possible \ref osStatus_t return values:
 218  - \em osOK: the semaphore object has been deleted.
 219  - \em osErrorParameter: the parameter \a semaphore_id is \token{NULL} or invalid.
 220  - \em osErrorResource: the semaphore specified by parameter \em semaphore_id is in an invalid semaphore state.
 221  - \em osErrorISR: \b osSemaphoreDelete cannot be called from interrupt service routines.
 222
 223 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 224 */
 225 /// @}