begriffs open source - cmsis/blob - dev/v6.0.0-dev53/RTOS2/html/group__CMSIS__RTOS__MutexMgmt.html

   1 <!-- HTML header for doxygen 1.9.6-->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   6 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
   7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
   8 <title>CMSIS-RTOS2: Mutex Management</title>
   9 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
  10 <link href="tabs.css" rel="stylesheet" type="text/css"/>
  11 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  12 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  13 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="jquery.js"></script>
  15 <script type="text/javascript" src="dynsections.js"></script>
  16 <script type="text/javascript" src="printComponentTabs.js"></script>
  17 <script type="text/javascript" src="footer.js"></script>
  18 <script type="text/javascript" src="navtree.js"></script>
  19 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  20 <script type="text/javascript" src="resize.js"></script>
  21 <script type="text/javascript" src="navtreedata.js"></script>
  22 <script type="text/javascript" src="navtree.js"></script>
  23 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  24 <script type="text/javascript" src="search/searchdata.js"></script>
  25 <script type="text/javascript" src="search/search.js"></script>
  26 <script type="text/javascript">
  27 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  28   $(document).ready(function() { init_search(); });
  29 /* @license-end */
  30 </script>
  31 <script type="text/javascript" src="darkmode_toggle.js"></script>
  32 <link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
  33 <link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
  34 <link href="extra_search.css" rel="stylesheet" type="text/css"/>
  35 <link href="version.css" rel="stylesheet" type="text/css" />
  36 <script type="text/javascript" src="../../../version.js"></script>
  37 </head>
  38 <body>
  39 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  40 <div id="titlearea">
  41 <table cellspacing="0" cellpadding="0">
  42  <tbody>
  43  <tr style="height: 55px;">
  44   <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  45   <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
  46    <div id="projectname">CMSIS-RTOS2
  47    &#160;<span id="projectnumber"><script type="text/javascript">
  48      <!--
  49      writeHeader.call(this);
  50      writeVersionDropdown.call(this);
  51      //-->
  52     </script>
  53    </span>
  54    </div>
  55    <div id="projectbrief">Real-Time Operating System API</div>
  56   </td>
  57    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
  58         <span class="left">
  59           <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
  60           <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
  61                onfocus="searchBox.OnSearchFieldFocus(true)"
  62                onblur="searchBox.OnSearchFieldFocus(false)"
  63                onkeyup="searchBox.OnSearchFieldChange(event)"/>
  64           </span><span class="right">
  65             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
  66           </span>
  67         </div>
  68 </td>
  69   <!--END !PROJECT_NAME-->
  70  </tr>
  71  </tbody>
  72 </table>
  73 </div>
  74 <!-- end header part -->
  75 <div id="CMSISnav" class="tabs1">
  76   <ul class="tablist">
  77     <script type="text/javascript">
  78       writeComponentTabs.call(this);
  79     </script>
  80   </ul>
  81 </div>
  82 <script type="text/javascript">
  83   writeSubComponentTabs.call(this);
  84 </script>
  85 <!-- Generated by Doxygen 1.9.6 -->
  86 <script type="text/javascript">
  87 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  88 var searchBox = new SearchBox("searchBox", "search/",'.html');
  89 /* @license-end */
  90 </script>
  91 </div><!-- top -->
  92 <div id="side-nav" class="ui-resizable side-nav-resizable">
  93   <div id="nav-tree">
  94     <div id="nav-tree-contents">
  95       <div id="nav-sync" class="sync"></div>
  96     </div>
  97   </div>
  98   <div id="splitbar" style="-moz-user-select:none;"
  99        class="ui-resizable-handle">
 100   </div>
 101 </div>
 102 <script type="text/javascript">
 103 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
 104 $(document).ready(function(){initNavTree('group__CMSIS__RTOS__MutexMgmt.html',''); initResizable(); });
 105 /* @license-end */
 106 </script>
 107 <div id="doc-content">
 108 <!-- window showing the filter options -->
 109 <div id="MSearchSelectWindow"
 110      onmouseover="return searchBox.OnSearchSelectShow()"
 111      onmouseout="return searchBox.OnSearchSelectHide()"
 112      onkeydown="return searchBox.OnSearchSelectKey(event)">
 113 </div>
 114
 115 <!-- iframe showing the search results (closed by default) -->
 116 <div id="MSearchResultsWindow">
 117 <div id="MSearchResults">
 118 <div class="SRPage">
 119 <div id="SRIndex">
 120 <div id="SRResults"></div>
 121 <div class="SRStatus" id="Loading">Loading...</div>
 122 <div class="SRStatus" id="Searching">Searching...</div>
 123 <div class="SRStatus" id="NoMatches">No Matches</div>
 124 </div>
 125 </div>
 126 </div>
 127 </div>
 128
 129 <div class="header">
 130   <div class="summary">
 131 <a href="#nested-classes">Data Structures</a> &#124;
 132 <a href="#define-members">Macros</a> &#124;
 133 <a href="#typedef-members">Typedefs</a> &#124;
 134 <a href="#func-members">Functions</a>  </div>
 135   <div class="headertitle"><div class="title">Mutex Management<div class="ingroups"><a class="el" href="group__CMSIS__RTOS.html">CMSIS-RTOS2 API</a></div></div></div>
 136 </div><!--header-->
 137 <div class="contents">
 138
 139 <p>Synchronize resource access using Mutual Exclusion (Mutex).
 140 <a href="#details">More...</a></p>
 141 <table class="memberdecls">
 142 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
 143 Data Structures</h2></td></tr>
 144 <tr class="memitem:structosMutexAttr__t"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a></td></tr>
 145 <tr class="memdesc:structosMutexAttr__t"><td class="mdescLeft">&#160;</td><td class="mdescRight">Attributes structure for mutex.  <a href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">More...</a><br /></td></tr>
 146 <tr class="separator:structosMutexAttr__t"><td class="memSeparator" colspan="2">&#160;</td></tr>
 147 </table><table class="memberdecls">
 148 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
 149 Macros</h2></td></tr>
 150 <tr class="memitem:ga65c2482cc64a35d03871f3180f305926"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a>&#160;&#160;&#160;0x00000001U</td></tr>
 151 <tr class="memdesc:ga65c2482cc64a35d03871f3180f305926"><td class="mdescLeft">&#160;</td><td class="mdescRight">Recursive mutex.  <br /></td></tr>
 152 <tr class="separator:ga65c2482cc64a35d03871f3180f305926"><td class="memSeparator" colspan="2">&#160;</td></tr>
 153 <tr class="memitem:ga40fba270cb31a977b3bd551d41eb9599"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a>&#160;&#160;&#160;0x00000002U</td></tr>
 154 <tr class="memdesc:ga40fba270cb31a977b3bd551d41eb9599"><td class="mdescLeft">&#160;</td><td class="mdescRight">Priority inherit protocol.  <br /></td></tr>
 155 <tr class="separator:ga40fba270cb31a977b3bd551d41eb9599"><td class="memSeparator" colspan="2">&#160;</td></tr>
 156 <tr class="memitem:gaf0e1dee376798b4d516d164981526780"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gaf0e1dee376798b4d516d164981526780">osMutexRobust</a>&#160;&#160;&#160;0x00000008U</td></tr>
 157 <tr class="memdesc:gaf0e1dee376798b4d516d164981526780"><td class="mdescLeft">&#160;</td><td class="mdescRight">Robust mutex.  <br /></td></tr>
 158 <tr class="separator:gaf0e1dee376798b4d516d164981526780"><td class="memSeparator" colspan="2">&#160;</td></tr>
 159 </table><table class="memberdecls">
 160 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="typedef-members" name="typedef-members"></a>
 161 Typedefs</h2></td></tr>
 162 <tr class="memitem:ga313801836c62deb23055efb55a420e42"><td class="memItemLeft" align="right" valign="top">typedef void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a></td></tr>
 163 <tr class="separator:ga313801836c62deb23055efb55a420e42"><td class="memSeparator" colspan="2">&#160;</td></tr>
 164 </table><table class="memberdecls">
 165 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
 166 Functions</h2></td></tr>
 167 <tr class="memitem:gab90920022ab944296821368ef6bb52f8"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a> (const <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> *attr)</td></tr>
 168 <tr class="memdesc:gab90920022ab944296821368ef6bb52f8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create and Initialize a Mutex object.  <br /></td></tr>
 169 <tr class="separator:gab90920022ab944296821368ef6bb52f8"><td class="memSeparator" colspan="2">&#160;</td></tr>
 170 <tr class="memitem:ga00b5e58cd247a412d1afd18732d8b752"><td class="memItemLeft" align="right" valign="top">const char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga00b5e58cd247a412d1afd18732d8b752">osMutexGetName</a> (<a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id)</td></tr>
 171 <tr class="memdesc:ga00b5e58cd247a412d1afd18732d8b752"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get name of a Mutex object.  <br /></td></tr>
 172 <tr class="separator:ga00b5e58cd247a412d1afd18732d8b752"><td class="memSeparator" colspan="2">&#160;</td></tr>
 173 <tr class="memitem:gabc54686ea0fc281823b1763422d2a924"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924">osMutexAcquire</a> (<a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id, uint32_t timeout)</td></tr>
 174 <tr class="memdesc:gabc54686ea0fc281823b1763422d2a924"><td class="mdescLeft">&#160;</td><td class="mdescRight">Acquire a Mutex or timeout if it is locked.  <br /></td></tr>
 175 <tr class="separator:gabc54686ea0fc281823b1763422d2a924"><td class="memSeparator" colspan="2">&#160;</td></tr>
 176 <tr class="memitem:gaea629705703580ff58776bf73c8db915"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gaea629705703580ff58776bf73c8db915">osMutexRelease</a> (<a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id)</td></tr>
 177 <tr class="memdesc:gaea629705703580ff58776bf73c8db915"><td class="mdescLeft">&#160;</td><td class="mdescRight">Release a Mutex that was acquired by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924">osMutexAcquire</a>.  <br /></td></tr>
 178 <tr class="separator:gaea629705703580ff58776bf73c8db915"><td class="memSeparator" colspan="2">&#160;</td></tr>
 179 <tr class="memitem:ga7f9a7666df0978738cd570cb700b83fb"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaa6c32fe2a3e0a2e01f212d55b02e51c7">osThreadId_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga7f9a7666df0978738cd570cb700b83fb">osMutexGetOwner</a> (<a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id)</td></tr>
 180 <tr class="memdesc:ga7f9a7666df0978738cd570cb700b83fb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get Thread which owns a Mutex object.  <br /></td></tr>
 181 <tr class="separator:ga7f9a7666df0978738cd570cb700b83fb"><td class="memSeparator" colspan="2">&#160;</td></tr>
 182 <tr class="memitem:gabee73ad227ba4587d3db12ef9bd582bc"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabee73ad227ba4587d3db12ef9bd582bc">osMutexDelete</a> (<a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id)</td></tr>
 183 <tr class="memdesc:gabee73ad227ba4587d3db12ef9bd582bc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Delete a Mutex object.  <br /></td></tr>
 184 <tr class="separator:gabee73ad227ba4587d3db12ef9bd582bc"><td class="memSeparator" colspan="2">&#160;</td></tr>
 185 </table>
 186 <a name="details" id="details"></a><h2 class="groupheader">Description</h2>
 187 <p>Synchronize resource access using Mutual Exclusion (Mutex). </p>
 188 <p><b>Mutual exclusion</b> (widely known as <b>Mutex</b>) is used in various operating systems for resource management. Many resources in a microcontroller device can be used repeatedly, but only by one thread at a time (for example communication channels, memory, and files). Mutexes are used to protect access to a shared resource. A mutex is created and then passed between the threads (they can acquire and release the mutex).</p>
 189 <div class="image">
 190 <img src="Mutex.png" alt=""/>
 191 <div class="caption">
 192 CMSIS-RTOS Mutex</div></div>
 193 <p>A mutex is a special version of a <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html">semaphore</a>. Like the semaphore, it is a container for tokens. But instead of being able to have multiple tokens, a mutex can only carry one (representing the resource). Thus, a mutex token is binary and bounded, i.e. it is either <em>available</em>, or <em>blocked</em> by a owning thread. The advantage of a mutex is that it introduces thread ownership. When a thread acquires a mutex and becomes its owner, subsequent mutex acquires from that thread will succeed immediately without any latency (if <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> is specified). Thus, mutex acquires/releases can be nested.</p>
 194 <div class="image">
 195 <img src="mutex_states.png" alt=""/>
 196 <div class="caption">
 197 CMSIS-RTOS Mutex States</div></div>
 198 <dl class="section note"><dt>Note</dt><dd>Mutex management functions cannot be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a> (ISR), unlike a binary semaphore that can be released from an ISR. </dd></dl>
 199 <hr/><h2 class="groupheader">Data Structure Documentation</h2>
 200 <a name="structosMutexAttr__t" id="structosMutexAttr__t"></a>
 201 <h2 class="memtitle"><span class="permalink"><a href="#structosMutexAttr__t">&#9670;&#160;</a></span>osMutexAttr_t</h2>
 202
 203 <div class="memitem">
 204 <div class="memproto">
 205       <table class="memname">
 206         <tr>
 207           <td class="memname">struct osMutexAttr_t</td>
 208         </tr>
 209       </table>
 210 </div><div class="memdoc">
 211 <div class="textblock"><p>Attributes structure for mutex. </p>
 212 <p>Specifies the following attributes for the <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a> function. </p>
 213 </div><table class="fieldtable">
 214 <tr><th colspan="3">Data Fields</th></tr>
 215 <tr><td class="fieldtype">
 216 <a id="ab74e6bf80237ddc4109968cedc58c151" name="ab74e6bf80237ddc4109968cedc58c151"></a>const char *</td>
 217 <td class="fieldname">
 218 name</td>
 219 <td class="fielddoc">
 220 name of the mutex <p>Pointer to a constant string with a human readable name (displayed during debugging) of the mutex object.</p>
 221 <p>Default: <span class="XML-Token">NULL</span> no name specified. </p>
 222 </td></tr>
 223 <tr><td class="fieldtype">
 224 <a id="a6e93b49cb79c12f768d72580c7731f30" name="a6e93b49cb79c12f768d72580c7731f30"></a>uint32_t</td>
 225 <td class="fieldname">
 226 attr_bits</td>
 227 <td class="fielddoc">
 228 attribute bits <p>The following bit masks can be used to set options:</p><ul>
 229 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926">osMutexRecursive</a> : a thread can consume the mutex multiple times without locking itself.</li>
 230 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a> : the owner thread inherits the priority of a (higher priority) waiting thread.</li>
 231 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gaf0e1dee376798b4d516d164981526780">osMutexRobust</a> : the mutex is automatically released when owner thread is terminated.</li>
 232 </ul>
 233 <p>Use logical <em>'OR'</em> operation to select multiple options, for example: </p><div class="fragment"><div class="line"><a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926" title="Recursive mutex.">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599" title="Priority inherit protocol.">osMutexPrioInherit</a>;</div>
 234 </div><!-- fragment --><p>Default: <span class="XML-Token">0</span> which specifies:</p><ul>
 235 <li><em>non recursive mutex</em>: a thread cannot consume the mutex multiple times.</li>
 236 <li><em>non priority raising</em>: the priority of an owning thread is not changed.</li>
 237 <li><em>mutex is not automatically release</em>: the mutex object must be always is automatically released when owner thread is terminated. </li>
 238 </ul>
 239 </td></tr>
 240 <tr><td class="fieldtype">
 241 <a id="a1e100dc33d403841ed3c344e3397868e" name="a1e100dc33d403841ed3c344e3397868e"></a>void *</td>
 242 <td class="fieldname">
 243 cb_mem</td>
 244 <td class="fielddoc">
 245 memory for control block <p>Pointer to a memory for the mutex control block object. Refer to <a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Manual">Manual User-defined Allocation</a> for more information.</p>
 246 <p>Default: <span class="XML-Token">NULL</span> to use <a class="el" href="usingOS2.html#CMSIS_RTOS_MemoryMgmt_Automatic">Automatic Dynamic Allocation</a> for the mutex control block. </p>
 247 </td></tr>
 248 <tr><td class="fieldtype">
 249 <a id="aa55a4335d12dc2785dc00fdc292d1159" name="aa55a4335d12dc2785dc00fdc292d1159"></a>uint32_t</td>
 250 <td class="fieldname">
 251 cb_size</td>
 252 <td class="fielddoc">
 253 size of provided memory for control block <p>The size (in bytes) of memory block passed with <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#a1e100dc33d403841ed3c344e3397868e">cb_mem</a>. Required value depends on the underlying kernel implementation.</p>
 254 <p>Default: <span class="XML-Token">0</span> as the default is no memory provided with <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#a1e100dc33d403841ed3c344e3397868e">cb_mem</a>. </p>
 255 </td></tr>
 256 </table>
 257
 258 </div>
 259 </div>
 260 <h2 class="groupheader">Macro Definition Documentation</h2>
 261 <a id="ga65c2482cc64a35d03871f3180f305926" name="ga65c2482cc64a35d03871f3180f305926"></a>
 262 <h2 class="memtitle"><span class="permalink"><a href="#ga65c2482cc64a35d03871f3180f305926">&#9670;&#160;</a></span>osMutexRecursive</h2>
 263
 264 <div class="memitem">
 265 <div class="memproto">
 266       <table class="memname">
 267         <tr>
 268           <td class="memname">#define osMutexRecursive&#160;&#160;&#160;0x00000001U</td>
 269         </tr>
 270       </table>
 271 </div><div class="memdoc">
 272
 273 <p>Recursive mutex. </p>
 274 <p>Recursive flag in <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a>.</p>
 275 <p>The same thread can consume a mutex multiple times without locking itself. Each time the owning thread acquires the mutex the lock count is incremented. The mutex must be released multiple times as well until the lock count reaches zero. At reaching zero the mutex is actually released and can be acquired by other threads.</p>
 276 <dl class="section note"><dt>Note</dt><dd>The maximum amount of recursive locks possible is implementation specific, i.e. the type size used for the lock count. If the maximum amount of recursive locks is depleted mutex acquire might fail.</dd></dl>
 277 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 278 <div class="line"> </div>
 279 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id; </div>
 280 <div class="line"> </div>
 281 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 282 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,     <span class="comment">// human readable mutex name</span></div>
 283 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926" title="Recursive mutex.">osMutexRecursive</a>,    <span class="comment">// attr_bits</span></div>
 284 <div class="line">  NULL,                <span class="comment">// memory for control block   </span></div>
 285 <div class="line">  0U                   <span class="comment">// size for control block</span></div>
 286 <div class="line">};</div>
 287 <div class="line"> </div>
 288 <div class="line"><span class="comment">// must be called from a thread context</span></div>
 289 <div class="line"><span class="keywordtype">void</span> UseMutexRecursively(<span class="keywordtype">int</span> count) {</div>
 290 <div class="line">  <a class="code hl_enumeration" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e" title="Status code values returned by CMSIS-RTOS functions.">osStatus_t</a> result = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924" title="Acquire a Mutex or timeout if it is locked.">osMutexAcquire</a>(mutex_id, <a class="code hl_define" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb" title="Wait forever timeout value.">osWaitForever</a>);  <span class="comment">// lock count is incremented, might fail when lock count is depleted</span></div>
 291 <div class="line">  <span class="keywordflow">if</span> (result == <a class="code hl_enumvalue" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813eab17c65ad8b5bae759882b41c5bf35cda" title="Operation completed successfully.">osOK</a>) {</div>
 292 <div class="line">    <span class="keywordflow">if</span> (count &lt; 10) {</div>
 293 <div class="line">      UseMutexRecursively(count + 1);</div>
 294 <div class="line">    }</div>
 295 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gaea629705703580ff58776bf73c8db915" title="Release a Mutex that was acquired by osMutexAcquire.">osMutexRelease</a>(mutex_id); <span class="comment">// lock count is decremented, actually releases the mutex on lock count zero</span></div>
 296 <div class="line">  }</div>
 297 <div class="line">}</div>
 298 </div><!-- fragment -->
 299 </div>
 300 </div>
 301 <a id="ga40fba270cb31a977b3bd551d41eb9599" name="ga40fba270cb31a977b3bd551d41eb9599"></a>
 302 <h2 class="memtitle"><span class="permalink"><a href="#ga40fba270cb31a977b3bd551d41eb9599">&#9670;&#160;</a></span>osMutexPrioInherit</h2>
 303
 304 <div class="memitem">
 305 <div class="memproto">
 306       <table class="memname">
 307         <tr>
 308           <td class="memname">#define osMutexPrioInherit&#160;&#160;&#160;0x00000002U</td>
 309         </tr>
 310       </table>
 311 </div><div class="memdoc">
 312
 313 <p>Priority inherit protocol. </p>
 314 <p>Priority inheritance flag in <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a>.</p>
 315 <p>A mutex using priority inheritance protocol transfers a waiting threads priority to the current mutex owner if the owners thread priority is lower. This assures that a low priority thread does not block a high priority thread.</p>
 316 <p>Otherwise a low priority thread might hold a mutex but is not granted execution time due to another mid priority thread. Without priority inheritance the high priority thread waiting for the mutex would be blocked by the mid priority thread, called priority inversion.</p>
 317 <p><b>Code Example</b></p>
 318 <p>This example reveals a blocked high priority thread if <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a> is removed.</p>
 319 <div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 320 <div class="line"> </div>
 321 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;  </div>
 322 <div class="line"> </div>
 323 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 324 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,     <span class="comment">// human readable mutex name</span></div>
 325 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599" title="Priority inherit protocol.">osMutexPrioInherit</a>,  <span class="comment">// attr_bits</span></div>
 326 <div class="line">  NULL,                <span class="comment">// memory for control block   </span></div>
 327 <div class="line">  0U                   <span class="comment">// size for control block</span></div>
 328 <div class="line">};</div>
 329 <div class="line"> </div>
 330 <div class="line"><span class="keywordtype">void</span> HighPrioThread(<span class="keywordtype">void</span> *argument) {</div>
 331 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e" title="Wait for Timeout (Time Delay).">osDelay</a>(1000U); <span class="comment">// wait 1s until start actual work</span></div>
 332 <div class="line">  <span class="keywordflow">while</span>(1) {</div>
 333 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924" title="Acquire a Mutex or timeout if it is locked.">osMutexAcquire</a>(mutex_id, <a class="code hl_define" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb" title="Wait forever timeout value.">osWaitForever</a>); <span class="comment">// try to acquire mutex</span></div>
 334 <div class="line">    <span class="comment">// do stuff</span></div>
 335 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gaea629705703580ff58776bf73c8db915" title="Release a Mutex that was acquired by osMutexAcquire.">osMutexRelease</a>(mutex_id);</div>
 336 <div class="line">  }</div>
 337 <div class="line">}</div>
 338 <div class="line"> </div>
 339 <div class="line"><span class="keywordtype">void</span> MidPrioThread(<span class="keywordtype">void</span> *argument) {</div>
 340 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e" title="Wait for Timeout (Time Delay).">osDelay</a>(1000U); <span class="comment">// wait 1s until start actual work</span></div>
 341 <div class="line">  <span class="keywordflow">while</span>(1) {</div>
 342 <div class="line">    <span class="comment">// do non blocking stuff</span></div>
 343 <div class="line">  }</div>
 344 <div class="line">}</div>
 345 <div class="line"> </div>
 346 <div class="line"><span class="keywordtype">void</span> LowPrioThread(<span class="keywordtype">void</span> *argument) {</div>
 347 <div class="line">  <span class="keywordflow">while</span>(1) {</div>
 348 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924" title="Acquire a Mutex or timeout if it is locked.">osMutexAcquire</a>(mutex_id, <a class="code hl_define" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb" title="Wait forever timeout value.">osWaitForever</a>);</div>
 349 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e" title="Wait for Timeout (Time Delay).">osDelay</a>(5000U); <span class="comment">// block mutex for 5s</span></div>
 350 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gaea629705703580ff58776bf73c8db915" title="Release a Mutex that was acquired by osMutexAcquire.">osMutexRelease</a>(mutex_id);</div>
 351 <div class="line">    <a class="code hl_function" href="group__CMSIS__RTOS__Wait.html#gaf6055a51390ef65b6b6edc28bf47322e" title="Wait for Timeout (Time Delay).">osDelay</a>(5000U); <span class="comment">// sleep for 5s</span></div>
 352 <div class="line">  }</div>
 353 <div class="line">}</div>
 354 </div><!-- fragment --><p>During the first second the high and mid priority threads are delayed. Thus the low priority thread can start its work, acquires the mutex and delays while holding it.</p>
 355 <p>After the first second the high and mid priority threads become ready. Thus the high priority thread gets precedence and tries to acquire the mutex. Because the mutex is already owned by the low priority thread the high priority thread gets blocked.</p>
 356 <p>Finally the mid priority thread gets executed and start doing a lot of non-blocking stuff, i.e. it does not call any blocking RTOS functionality.</p>
 357 <p>Without <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a> we would stuck here forever. Even if the low priority thread gets ready after 5s. Due to its low priority the mid priority thread always gets precedence. The effect called priority inversion leads to the mid priority thread blocking the high priority thread indirectly.</p>
 358 <p>Using <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599">osMutexPrioInherit</a> as shown in the example code we get rid of this situation. Due to the priority inheritance protocol the low priority thread inherits the high priority while holding the mutex. Thus the low priority thread gets precedence over the mid priority thread until it release the mutex. On osMutexRelease the high priority thread get ready and is scheduled immediately. </p>
 359
 360 </div>
 361 </div>
 362 <a id="gaf0e1dee376798b4d516d164981526780" name="gaf0e1dee376798b4d516d164981526780"></a>
 363 <h2 class="memtitle"><span class="permalink"><a href="#gaf0e1dee376798b4d516d164981526780">&#9670;&#160;</a></span>osMutexRobust</h2>
 364
 365 <div class="memitem">
 366 <div class="memproto">
 367       <table class="memname">
 368         <tr>
 369           <td class="memname">#define osMutexRobust&#160;&#160;&#160;0x00000008U</td>
 370         </tr>
 371       </table>
 372 </div><div class="memdoc">
 373
 374 <p>Robust mutex. </p>
 375 <p>Robust flag in <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a>.</p>
 376 <p>Robust mutexes are automatically released if the owning thread is terminated (either by <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaddaa452dd7610e4096647a566d3556fc">osThreadExit</a> or <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga2f8ba6dba6e9c065a6e236ffd410d74a">osThreadTerminate</a>). Non-robust mutexes are not released and the user must assure mutex release manually.</p>
 377 <p><b>Code Example</b></p>
 378 <p>This example reveals a blocked mutex if osMutexRobust is removed.</p>
 379 <div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 380 <div class="line"> </div>
 381 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 382 <div class="line"> </div>
 383 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 384 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,     <span class="comment">// human readable mutex name</span></div>
 385 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#gaf0e1dee376798b4d516d164981526780" title="Robust mutex.">osMutexRobust</a>,       <span class="comment">// attr_bits</span></div>
 386 <div class="line">  NULL,                <span class="comment">// memory for control block   </span></div>
 387 <div class="line">  0U                   <span class="comment">// size for control block</span></div>
 388 <div class="line">};</div>
 389 <div class="line"> </div>
 390 <div class="line"><span class="keywordtype">void</span> Thread(<span class="keywordtype">void</span> *argument) {</div>
 391 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924" title="Acquire a Mutex or timeout if it is locked.">osMutexAcquire</a>(mutex_id, <a class="code hl_define" href="group__CMSIS__RTOS__Definitions.html#ga9eb9a7a797a42e4b55eb171ecc609ddb" title="Wait forever timeout value.">osWaitForever</a>);</div>
 392 <div class="line">  <a class="code hl_function" href="group__CMSIS__RTOS__ThreadMgmt.html#gaddaa452dd7610e4096647a566d3556fc" title="Terminate execution of current running thread.">osThreadExit</a>();</div>
 393 <div class="line">}</div>
 394 </div><!-- fragment --><p>Due to <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gaf0e1dee376798b4d516d164981526780">osMutexRobust</a> the mutex gets released automatically. A non-robust mutex would stay locked and cannot be released anymore. </p>
 395
 396 </div>
 397 </div>
 398 <h2 class="groupheader">Typedef Documentation</h2>
 399 <a id="ga313801836c62deb23055efb55a420e42" name="ga313801836c62deb23055efb55a420e42"></a>
 400 <h2 class="memtitle"><span class="permalink"><a href="#ga313801836c62deb23055efb55a420e42">&#9670;&#160;</a></span>osMutexId_t</h2>
 401
 402 <div class="memitem">
 403 <div class="memproto">
 404       <table class="memname">
 405         <tr>
 406           <td class="memname"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a></td>
 407         </tr>
 408       </table>
 409 </div><div class="memdoc">
 410 <p>Mutex ID identifies the mutex.</p>
 411 <p>Returned by:</p><ul>
 412 <li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a> </li>
 413 </ul>
 414
 415 </div>
 416 </div>
 417 <h2 class="groupheader">Function Documentation</h2>
 418 <a id="gab90920022ab944296821368ef6bb52f8" name="gab90920022ab944296821368ef6bb52f8"></a>
 419 <h2 class="memtitle"><span class="permalink"><a href="#gab90920022ab944296821368ef6bb52f8">&#9670;&#160;</a></span>osMutexNew()</h2>
 420
 421 <div class="memitem">
 422 <div class="memproto">
 423       <table class="memname">
 424         <tr>
 425           <td class="memname"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> osMutexNew </td>
 426           <td>(</td>
 427           <td class="paramtype">const <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a> *&#160;</td>
 428           <td class="paramname"><em>attr</em></td><td>)</td>
 429           <td></td>
 430         </tr>
 431       </table>
 432 </div><div class="memdoc">
 433
 434 <p>Create and Initialize a Mutex object. </p>
 435 <dl class="params"><dt>Parameters</dt><dd>
 436   <table class="params">
 437     <tr><td class="paramdir">[in]</td><td class="paramname">attr</td><td>mutex attributes; NULL: default values. </td></tr>
 438   </table>
 439   </dd>
 440 </dl>
 441 <dl class="section return"><dt>Returns</dt><dd>mutex ID for reference by other functions or NULL in case of error.</dd></dl>
 442 <p>The function <b>osMutexNew</b> creates and initializes a new mutex object and returns the pointer to the mutex object identifier or <span class="XML-Token">NULL</span> in case of an error. It can be safely called before the RTOS is started (call to <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>), but not before it is initialized (call to <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>).</p>
 443 <p>The parameter <em>attr</em> sets the mutex object attributes (refer to <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a>). Default attributes will be used if set to <span class="XML-Token">NULL</span>.</p>
 444 <dl class="section note"><dt>Note</dt><dd>This function <b>cannot</b> be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
 445 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 446 <div class="line"> </div>
 447 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;  </div>
 448 <div class="line"> </div>
 449 <div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t" title="Attributes structure for mutex.">osMutexAttr_t</a> Thread_Mutex_attr = {</div>
 450 <div class="line">  <span class="stringliteral">&quot;myThreadMutex&quot;</span>,                          <span class="comment">// human readable mutex name</span></div>
 451 <div class="line">  <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga65c2482cc64a35d03871f3180f305926" title="Recursive mutex.">osMutexRecursive</a> | <a class="code hl_define" href="group__CMSIS__RTOS__MutexMgmt.html#ga40fba270cb31a977b3bd551d41eb9599" title="Priority inherit protocol.">osMutexPrioInherit</a>,    <span class="comment">// attr_bits</span></div>
 452 <div class="line">  NULL,                                     <span class="comment">// memory for control block   </span></div>
 453 <div class="line">  0U                                        <span class="comment">// size for control block</span></div>
 454 <div class="line">};</div>
 455 <div class="line"> </div>
 456 <div class="line"><span class="keywordtype">void</span> CreateMutex (<span class="keywordtype">void</span>)  {</div>
 457 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8" title="Create and Initialize a Mutex object.">osMutexNew</a>(&amp;Thread_Mutex_attr);</div>
 458 <div class="line">  <span class="keywordflow">if</span> (mutex_id != NULL)  {</div>
 459 <div class="line">    <span class="comment">// Mutex object created</span></div>
 460 <div class="line">  }</div>
 461 <div class="line">}</div>
 462 </div><!-- fragment -->
 463 </div>
 464 </div>
 465 <a id="ga00b5e58cd247a412d1afd18732d8b752" name="ga00b5e58cd247a412d1afd18732d8b752"></a>
 466 <h2 class="memtitle"><span class="permalink"><a href="#ga00b5e58cd247a412d1afd18732d8b752">&#9670;&#160;</a></span>osMutexGetName()</h2>
 467
 468 <div class="memitem">
 469 <div class="memproto">
 470       <table class="memname">
 471         <tr>
 472           <td class="memname">*const char * osMutexGetName </td>
 473           <td>(</td>
 474           <td class="paramtype"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td>
 475           <td class="paramname"><em>mutex_id</em></td><td>)</td>
 476           <td></td>
 477         </tr>
 478       </table>
 479 </div><div class="memdoc">
 480
 481 <p>Get name of a Mutex object. </p>
 482 <dl class="params"><dt>Parameters</dt><dd>
 483   <table class="params">
 484     <tr><td class="paramdir">[in]</td><td class="paramname">mutex_id</td><td>mutex ID obtained by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>. </td></tr>
 485   </table>
 486   </dd>
 487 </dl>
 488 <dl class="section return"><dt>Returns</dt><dd>name as null-terminated string.</dd></dl>
 489 <p>The function <b>osMutexGetName</b> returns the pointer to the name string of the mutex identified by parameter <em>mutex_id</em> or <span class="XML-Token">NULL</span> in case of an error.</p>
 490 <dl class="section note"><dt>Note</dt><dd>This function may be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>. </dd></dl>
 491
 492 </div>
 493 </div>
 494 <a id="gabc54686ea0fc281823b1763422d2a924" name="gabc54686ea0fc281823b1763422d2a924"></a>
 495 <h2 class="memtitle"><span class="permalink"><a href="#gabc54686ea0fc281823b1763422d2a924">&#9670;&#160;</a></span>osMutexAcquire()</h2>
 496
 497 <div class="memitem">
 498 <div class="memproto">
 499       <table class="memname">
 500         <tr>
 501           <td class="memname"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> osMutexAcquire </td>
 502           <td>(</td>
 503           <td class="paramtype"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td>
 504           <td class="paramname"><em>mutex_id</em>, </td>
 505         </tr>
 506         <tr>
 507           <td class="paramkey"></td>
 508           <td></td>
 509           <td class="paramtype">uint32_t&#160;</td>
 510           <td class="paramname"><em>timeout</em>&#160;</td>
 511         </tr>
 512         <tr>
 513           <td></td>
 514           <td>)</td>
 515           <td></td><td></td>
 516         </tr>
 517       </table>
 518 </div><div class="memdoc">
 519
 520 <p>Acquire a Mutex or timeout if it is locked. </p>
 521 <dl class="params"><dt>Parameters</dt><dd>
 522   <table class="params">
 523     <tr><td class="paramdir">[in]</td><td class="paramname">mutex_id</td><td>mutex ID obtained by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>. </td></tr>
 524     <tr><td class="paramdir">[in]</td><td class="paramname">timeout</td><td><a class="el" href="usingOS2.html#CMSIS_RTOS_TimeOutValue">Timeout Values</a> or 0 in case of no time-out. </td></tr>
 525   </table>
 526   </dd>
 527 </dl>
 528 <dl class="section return"><dt>Returns</dt><dd>status code that indicates the execution status of the function.</dd></dl>
 529 <p>The blocking function <b>osMutexAcquire</b> waits until a mutex object specified by parameter <em>mutex_id</em> becomes available. If no other thread has obtained the mutex, the function instantly returns and blocks the mutex object.</p>
 530 <p>The parameter <em>timeout</em> specifies how long the system waits to acquire the mutex. While the system waits, the thread that is calling this function is put into the <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ThreadStates">BLOCKED</a> state. The parameter <a class="el" href="usingOS2.html#CMSIS_RTOS_TimeOutValue">timeout</a> can have the following values:</p><ul>
 531 <li>when <em>timeout</em> is <span class="XML-Token">0</span>, the function returns instantly (i.e. try semantics).</li>
 532 <li>when <em>timeout</em> is set to <b>osWaitForever</b> the function will wait for an infinite time until the mutex becomes available (i.e. wait semantics).</li>
 533 <li>all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).</li>
 534 </ul>
 535 <p>Possible <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> return values:</p><ul>
 536 <li><em>osOK:</em> the mutex has been obtained.</li>
 537 <li><em>osErrorTimeout:</em> the mutex could not be obtained in the given time.</li>
 538 <li><em>osErrorResource:</em> the mutex could not be obtained when no <em>timeout</em> was specified.</li>
 539 <li><em>osErrorParameter:</em> parameter <em>mutex_id</em> is <span class="XML-Token">NULL</span> or invalid.</li>
 540 <li><em>osErrorISR:</em> cannot be called from interrupt service routines.</li>
 541 <li><em>osErrorSafetyClass:</em> the calling thread safety class is lower than the safety class of the specified mutex.</li>
 542 </ul>
 543 <dl class="section note"><dt>Note</dt><dd>This function <b>cannot</b> be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
 544 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 545 <div class="line"> </div>
 546 <div class="line"><span class="keywordtype">void</span> WaitMutex (<span class="keywordtype">void</span>) {</div>
 547 <div class="line">  <a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;</div>
 548 <div class="line">  <a class="code hl_enumeration" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e" title="Status code values returned by CMSIS-RTOS functions.">osStatus_t</a>  status;</div>
 549 <div class="line"> </div>
 550 <div class="line">  mutex_id = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8" title="Create and Initialize a Mutex object.">osMutexNew</a>(NULL);</div>
 551 <div class="line">  <span class="keywordflow">if</span> (mutex_id != NULL) {</div>
 552 <div class="line">    status = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924" title="Acquire a Mutex or timeout if it is locked.">osMutexAcquire</a>(mutex_id, 0U);</div>
 553 <div class="line">    <span class="keywordflow">if</span> (status != <a class="code hl_enumvalue" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813eab17c65ad8b5bae759882b41c5bf35cda" title="Operation completed successfully.">osOK</a>)  {</div>
 554 <div class="line">      <span class="comment">// handle failure code</span></div>
 555 <div class="line">    }</div>
 556 <div class="line">  }</div>
 557 <div class="line">}</div>
 558 </div><!-- fragment -->
 559 </div>
 560 </div>
 561 <a id="gaea629705703580ff58776bf73c8db915" name="gaea629705703580ff58776bf73c8db915"></a>
 562 <h2 class="memtitle"><span class="permalink"><a href="#gaea629705703580ff58776bf73c8db915">&#9670;&#160;</a></span>osMutexRelease()</h2>
 563
 564 <div class="memitem">
 565 <div class="memproto">
 566       <table class="memname">
 567         <tr>
 568           <td class="memname"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> osMutexRelease </td>
 569           <td>(</td>
 570           <td class="paramtype"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td>
 571           <td class="paramname"><em>mutex_id</em></td><td>)</td>
 572           <td></td>
 573         </tr>
 574       </table>
 575 </div><div class="memdoc">
 576
 577 <p>Release a Mutex that was acquired by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924">osMutexAcquire</a>. </p>
 578 <dl class="params"><dt>Parameters</dt><dd>
 579   <table class="params">
 580     <tr><td class="paramdir">[in]</td><td class="paramname">mutex_id</td><td>mutex ID obtained by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>. </td></tr>
 581   </table>
 582   </dd>
 583 </dl>
 584 <dl class="section return"><dt>Returns</dt><dd>status code that indicates the execution status of the function.</dd></dl>
 585 <p>The function <b>osMutexRelease</b> releases a mutex specified by parameter <em>mutex_id</em>. Other threads that currently wait for this mutex will be put into the <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ThreadStates">READY</a> state.</p>
 586 <p>Possible <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> return values:</p><ul>
 587 <li><em>osOK:</em> the mutex has been correctly released.</li>
 588 <li><em>osErrorResource:</em> the mutex could not be released (mutex was not acquired or running thread is not the owner).</li>
 589 <li><em>osErrorParameter:</em> parameter <em>mutex_id</em> is <span class="XML-Token">NULL</span> or invalid.</li>
 590 <li><em>osErrorISR:</em> <b>osMutexRelease</b> cannot be called from interrupt service routines.</li>
 591 </ul>
 592 <dl class="section note"><dt>Note</dt><dd>This function <b>cannot</b> be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
 593 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 594 <div class="line"> </div>
 595 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;                                        <span class="comment">// Mutex id populated by the function osMutexNew()</span></div>
 596 <div class="line"> </div>
 597 <div class="line"><span class="keywordtype">void</span> ReleaseMutex (<a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id) {</div>
 598 <div class="line">  <a class="code hl_enumeration" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e" title="Status code values returned by CMSIS-RTOS functions.">osStatus_t</a> status;</div>
 599 <div class="line"> </div>
 600 <div class="line">  <span class="keywordflow">if</span> (mutex_id != NULL)  {</div>
 601 <div class="line">    status = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gaea629705703580ff58776bf73c8db915" title="Release a Mutex that was acquired by osMutexAcquire.">osMutexRelease</a>(mutex_id);</div>
 602 <div class="line">    <span class="keywordflow">if</span> (status != <a class="code hl_enumvalue" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813eab17c65ad8b5bae759882b41c5bf35cda" title="Operation completed successfully.">osOK</a>)  {</div>
 603 <div class="line">      <span class="comment">// handle failure code</span></div>
 604 <div class="line">    }</div>
 605 <div class="line">  }</div>
 606 <div class="line">}</div>
 607 </div><!-- fragment -->
 608 </div>
 609 </div>
 610 <a id="ga7f9a7666df0978738cd570cb700b83fb" name="ga7f9a7666df0978738cd570cb700b83fb"></a>
 611 <h2 class="memtitle"><span class="permalink"><a href="#ga7f9a7666df0978738cd570cb700b83fb">&#9670;&#160;</a></span>osMutexGetOwner()</h2>
 612
 613 <div class="memitem">
 614 <div class="memproto">
 615       <table class="memname">
 616         <tr>
 617           <td class="memname"><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaa6c32fe2a3e0a2e01f212d55b02e51c7">osThreadId_t</a> osMutexGetOwner </td>
 618           <td>(</td>
 619           <td class="paramtype"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td>
 620           <td class="paramname"><em>mutex_id</em></td><td>)</td>
 621           <td></td>
 622         </tr>
 623       </table>
 624 </div><div class="memdoc">
 625
 626 <p>Get Thread which owns a Mutex object. </p>
 627 <dl class="params"><dt>Parameters</dt><dd>
 628   <table class="params">
 629     <tr><td class="paramdir">[in]</td><td class="paramname">mutex_id</td><td>mutex ID obtained by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>. </td></tr>
 630   </table>
 631   </dd>
 632 </dl>
 633 <dl class="section return"><dt>Returns</dt><dd>thread ID of owner thread or NULL when mutex was not acquired.</dd></dl>
 634 <p>The function <b>osMutexGetOwner</b> returns the thread ID of the thread that acquired a mutex specified by parameter <em>mutex_id</em>. In case of an error or if the mutex is not blocked by any thread, it returns <span class="XML-Token">NULL</span>.</p>
 635 <dl class="section note"><dt>Note</dt><dd>This function <b>cannot</b> be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>. </dd></dl>
 636
 637 </div>
 638 </div>
 639 <a id="gabee73ad227ba4587d3db12ef9bd582bc" name="gabee73ad227ba4587d3db12ef9bd582bc"></a>
 640 <h2 class="memtitle"><span class="permalink"><a href="#gabee73ad227ba4587d3db12ef9bd582bc">&#9670;&#160;</a></span>osMutexDelete()</h2>
 641
 642 <div class="memitem">
 643 <div class="memproto">
 644       <table class="memname">
 645         <tr>
 646           <td class="memname"><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> osMutexDelete </td>
 647           <td>(</td>
 648           <td class="paramtype"><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a>&#160;</td>
 649           <td class="paramname"><em>mutex_id</em></td><td>)</td>
 650           <td></td>
 651         </tr>
 652       </table>
 653 </div><div class="memdoc">
 654
 655 <p>Delete a Mutex object. </p>
 656 <dl class="params"><dt>Parameters</dt><dd>
 657   <table class="params">
 658     <tr><td class="paramdir">[in]</td><td class="paramname">mutex_id</td><td>mutex ID obtained by <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>. </td></tr>
 659   </table>
 660   </dd>
 661 </dl>
 662 <dl class="section return"><dt>Returns</dt><dd>status code that indicates the execution status of the function.</dd></dl>
 663 <p>The function <b>osMutexDelete</b> deletes a mutex object specified by parameter <em>mutex_id</em>. It releases internal memory obtained for mutex handling. After this call, the <em>mutex_id</em> is no longer valid and cannot be used. The mutex may be created again using the function <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a>.</p>
 664 <p>Possible <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e">osStatus_t</a> return values:</p><ul>
 665 <li><em>osOK:</em> the mutex object has been deleted.</li>
 666 <li><em>osErrorParameter:</em> parameter <em>mutex_id</em> is <span class="XML-Token">NULL</span> or invalid.</li>
 667 <li><em>osErrorResource:</em> the mutex is in an invalid state.</li>
 668 <li><em>osErrorISR:</em> <b>osMutexDelete</b> cannot be called from interrupt service routines.</li>
 669 <li><em>osErrorSafetyClass:</em> the calling thread safety class is lower than the safety class of the specified mutex.</li>
 670 </ul>
 671 <dl class="section note"><dt>Note</dt><dd>This function <b>cannot</b> be called from <a class="el" href="usingOS2.html#CMSIS_RTOS_ISR_Calls">Interrupt Service Routines</a>.</dd></dl>
 672 <p><b>Code Example</b> </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;cmsis_os2.h&quot;</span></div>
 673 <div class="line"> </div>
 674 <div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id;                           <span class="comment">// Mutex id populated by the function osMutexNew()</span></div>
 675 <div class="line"> </div>
 676 <div class="line"><span class="keywordtype">void</span> DeleteMutex (<a class="code hl_typedef" href="group__CMSIS__RTOS__MutexMgmt.html#ga313801836c62deb23055efb55a420e42">osMutexId_t</a> mutex_id)  {</div>
 677 <div class="line">  <a class="code hl_enumeration" href="group__CMSIS__RTOS__Definitions.html#ga6c0dbe6069e4e7f47bb4cd32ae2b813e" title="Status code values returned by CMSIS-RTOS functions.">osStatus_t</a> status;</div>
 678 <div class="line"> </div>
 679 <div class="line">  <span class="keywordflow">if</span> (mutex_id != NULL)  {</div>
 680 <div class="line">    status = <a class="code hl_function" href="group__CMSIS__RTOS__MutexMgmt.html#gabee73ad227ba4587d3db12ef9bd582bc" title="Delete a Mutex object.">osMutexDelete</a>(mutex_id);</div>
 681 <div class="line">    <span class="keywordflow">if</span> (status != <a class="code hl_enumvalue" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813eab17c65ad8b5bae759882b41c5bf35cda" title="Operation completed successfully.">osOK</a>)  {</div>
 682 <div class="line">      <span class="comment">// handle failure code</span></div>
 683 <div class="line">    }</div>
 684 <div class="line">  }</div>
 685 <div class="line">}</div>
 686 </div><!-- fragment -->
 687 </div>
 688 </div>
 689 </div><!-- contents -->
 690 </div><!-- doc-content -->
 691 <!-- start footer part -->
 692 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 693   <ul>
 694     <li class="footer">
 695       <script type="text/javascript">
 696         <!--
 697         writeFooter.call(this);
 698         //-->
 699       </script>
 700     </li>
 701   </ul>
 702 </div>
 703 </body>
 704 </html>