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