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

   1 //
   2 // close group struct osMutexAttr_t
   3 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   4 //  ==== Mutex Management ====
   5 /**
   6 \addtogroup CMSIS_RTOS_MutexMgmt Mutex Management
   7 \ingroup CMSIS_RTOS
   8 \brief Synchronize resource access using Mutual Exclusion (Mutex).
   9 \details
  10 <b>Mutual exclusion</b> (widely known as \b Mutex) is used in various operating systems for resource management. Many
  11 resources in a microcontroller device can be used repeatedly, but only by one thread at a time (for example communication
  12 channels, memory, and files). Mutexes are used to protect access to a shared resource. A mutex is created and then passed
  13 between the threads (they can acquire and release the mutex).
  14
  15 \image html "Mutex.png" "CMSIS-RTOS Mutex"
  16
  17 A mutex is a special version of a \ref CMSIS_RTOS_SemaphoreMgmt "semaphore". Like the semaphore, it is a container for
  18 tokens. But instead of being able to have multiple tokens, a mutex can only carry one (representing the resource). Thus, a
  19 mutex token is binary and bounded, i.e. it is either \em available, or \em blocked by a owning thread. The advantage of a
  20 mutex is that it introduces thread ownership. When a thread acquires a mutex and becomes its owner, subsequent mutex acquires
  21 from that thread will succeed immediately without any latency (if \ref osMutexRecursive is specified). Thus, mutex acquires/releases
  22 can be nested.
  23
  24 \image html "mutex_states.png" "CMSIS-RTOS Mutex States"
  25
  26 \note Mutex management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" (ISR), unlike a
  27 binary semaphore that can be released from an ISR.
  28 \note Refer to \ref mutexConfig for RTX5 configuration options.
  29
  30 @{
  31 */
  32 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  33 /**
  34 \def osMutexRecursive
  35 \details
  36  - \ref osMutexAttr_t
  37 */
  38
  39 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  40 /**
  41 \def osMutexPrioInherit
  42 \details
  43  - \ref osMutexAttr_t
  44 */
  45
  46 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  47 /**
  48 \def osMutexRobust
  49 \details
  50  - \ref osMutexAttr_t
  51 */
  52
  53 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  54 /**
  55 \typedef osMutexId_t
  56 \details
  57 Returned by:
  58 - \ref osMutexNew
  59 */
  60
  61 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  62 /**
  63 \struct osMutexAttr_t
  64 \details
  65 */
  66
  67 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  68 /**
  69 \fn osMutexId_t osMutexNew (const osMutexAttr_t *attr)
  70 \details
  71 The function \b osMutexNew creates and initializes a new mutex object and returns the pointer to the mutex object identifier
  72 or \token{NULL} in case of an error. It can be safely called before the RTOS is
  73 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  74
  75 The parameter \a attr sets the mutex object attributes (refer to \ref osMutexAttr_t). Default attributes will be used if set
  76 to \token{NULL}.
  77
  78 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  79
  80 <b>Code Example</b>
  81 \code
  82 #include "cmsis_os2.h"
  83
  84 osMutexId_t mutex_id;
  85
  86 const osMutexAttr_t Thread_Mutex_attr = {
  87   "myThreadMutex",                          // human readable mutex name
  88   osMutexRecursive | osMutexPrioInherit,    // attr_bits
  89   NULL,                                     // memory for control block
  90   NULL                                      // size for control block
  91   };
  92
  93 void CreateMutex (void)  {
  94   mutex_id = osMutexNew(&Thread_Mutex_attr);
  95   if (mutex_id != NULL)  {
  96     // Mutex object created
  97   }
  98 }
  99 \endcode
 100 */
 101
 102 */
 103 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 104 /**
 105 \fn const char *osMutexGetName (osMutexId_t mutex_id)
 106 \details
 107 The function \b osMutexGetName returns the pointer to the name string of the mutex identified by parameter \a mutex_id or
 108 \token{NULL} in case of an error.
 109
 110 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 111 */
 112
 113 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 114 /**
 115 \fn osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout)
 116 \details
 117 The blocking function \b osMutexAcquire waits until a mutex object specified by parameter \a mutex_id becomes available. If
 118 no other thread has obtained the mutex, the function instantly returns and blocks the mutex object.
 119
 120 The parameter \a timeout specifies how long the system waits to acquire the mutex. While the system waits, the thread that is
 121 calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue "timeout"
 122 can have the following values:
 123  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 124  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the mutex becomes available (i.e. wait semantics).
 125  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 126
 127 Possible \ref osStatus_t return values:
 128  - \em osOK: the mutex has been obtained.
 129  - \em osErrorTimeout: the mutex could not be obtained in the given time.
 130  - \em osErrorParameter: parameter \em mutex_id is \token{NULL} or invalid.
 131  - \em osErrorResource: the mutex specified by parameter \a mutex_id is in an invalid mutex state or the mutex could not be
 132    obtained when no \a timeout was specified.
 133  - \em osErrorISR: cannot be called from interrupt service routines.
 134
 135 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 136
 137 <b>Code Example</b>
 138 \code
 139 #include "cmsis_os2.h"
 140
 141 void WaitMutex (void)  {
 142 osMutexId_t mutex_id;
 143 osStatus_t  status;
 144
 145   mutex_id = osMutexNew(NULL);
 146   if (mutex_id != NULL)  {
 147     status  = osMutexAcquire(mutex_id, 0);
 148     if (status != osOK)  {
 149       // handle failure code
 150     }
 151   }
 152 }
 153 \endcode
 154 */
 155
 156 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 157 /**
 158 \fn osStatus_t osMutexRelease (osMutexId_t mutex_id)
 159 \details
 160 The function \b osMutexRelease releases a mutex specified by parameter \a mutex_id. Other threads that currently wait for
 161 this mutex will be put into the \ref ThreadStates "READY" state.
 162
 163 Possible \ref osStatus_t return values:
 164  - \em osOK: the mutex has been correctly released.
 165  - \em osErrorParameter: parameter \em mutex_id is \token{NULL} or invalid.
 166  - \em osErrorResource: the mutex specified by parameter \a mutex_id is in an invalid mutex state or the mutex was not
 167    obtained before/the current thread is not the owner of the mutex.
 168  - \em osErrorISR: \b osMutexRelease cannot be called from interrupt service routines.
 169
 170 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 171
 172 <b>Code Example</b>
 173 \code
 174 #include "cmsis_os2.h"
 175
 176 osMutexId_t mutex_id;                                        // Mutex id populated by the function osMutexNew()
 177
 178 void ReleaseMutex (osMutexId_t mutex_id)  {
 179   osStatus_t status;
 180
 181   if (mutex_id != NULL)  {
 182     status = osMutexRelease(mutex_id);
 183     if (status != osOK)  {
 184       // handle failure code
 185     }
 186   }
 187 }
 188 \endcode
 189 */
 190
 191 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 192 /**
 193 \fn osThreadId_t osMutexGetOwner (osMutexId_t mutex_id)
 194 \details
 195 The function \b osMutexGetOwner returns the thread ID of the thread that acquired a mutex specified by parameter \a
 196 mutex_id. In case of an error or if the mutex is not blocked by any thread, it returns \token{NULL}.
 197
 198 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 199 */
 200
 201 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 202 /**
 203 \fn osStatus_t osMutexDelete (osMutexId_t mutex_id)
 204 \details
 205 The function \b osMutexDelete deletes a mutex object specified by parameter \a mutex_id. It releases internal memory obtained
 206 for mutex handling. After this call, the \a mutex_id is no longer valid and cannot be used. The mutex may be created again
 207 using the function \ref osMutexNew.
 208
 209 Possible \ref osStatus_t return values:
 210  - \em osOK: the mutex object has been deleted.
 211  - \em osErrorParameter: parameter \em mutex_id is \token{NULL} or invalid.
 212  - \em osErrorResource: the mutex specified by parameter \a mutex_id is in an invalid mutex state.
 213  - \em osErrorISR: \b osMutexDelete cannot be called from interrupt service routines.
 214
 215 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 216
 217 <b>Code Example</b>
 218 \code
 219 #include "cmsis_os2.h"
 220
 221 osMutexId_t mutex_id;                            // Mutex id populated by the function osMutexNew()
 222
 223 void DeleteMutex (osMutexId_t mutex_id)  {
 224   osStatus_t status;
 225
 226   if (mutex_id != NULL)  {
 227     status = osMutexDelete(mutex_id);
 228     if (status != osOK)  {
 229       // handle failure code
 230     }
 231   }
 232 }
 233 \endcode
 234 */
 235 /// @}
 236
 237 // these struct members must stay outside the group to avoid double entries in documentation
 238 /**
 239 \var osMutexAttr_t::attr_bits
 240 \details
 241 The following predefined bit masks can be assigned to set options for a mutex object.
 242
 243 Bit Mask                    |  Description
 244 :---------------------------|:------------------
 245 \token{osMutexRecursive}    | Mutex is recursive. The same thread can consume a mutex multiple times without locking itself.
 246 \token{osMutexPrioInherit}  | Priority inheritance protocol. While a thread owns this mutex it cannot be preempted by a higher priority thread to avoid starvation.
 247 \token{osMutexRobust}       | Robust mutex. Notify threads that acquire a mutex if the previous owner was terminated.
 248 */
 249 /**
 250 \var osMutexAttr_t::cb_mem
 251 \details
 252 Pointer to a memory location for the mutex control block object. This can optionally be used for custom memory management systems.\n
 253 Default: \token{NULL} (uses kernel memory management).
 254 */
 255 /**
 256 \var osMutexAttr_t::cb_size
 257 \details
 258 The size of the memory block passed with \ref cb_mem. Must be the size of a mutex control block object or larger.
 259 */
 260 /**
 261 \var osMutexAttr_t::name
 262 \details
 263 Pointer to a string with a human readable name of the event object.\n
 264 Default: \token{NULL}.
 265 */