web/docs/group__lock__core.html

   1 <!-- HTML header for doxygen 1.8.20-->
   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">
   4 <head>
   5         <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   6         <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   7         <meta name="generator" content="Doxygen 1.9.4"/>
   8         <meta name="viewport" content="width=device-width, initial-scale=1"/>
   9         <title>Raspberry Pi Pico SDK: lock_core</title>
  10         <!-- <link href="tabs.css" rel="stylesheet" type="text/css"/> -->
  11         <script type="text/javascript" src="jquery.js"></script>
  12         <script type="text/javascript" src="dynsections.js"></script>
  13         <link href="navtree.css" rel="stylesheet" type="text/css"/>
  14 <script type="text/javascript" src="resize.js"></script>
  15 <script type="text/javascript" src="navtreedata.js"></script>
  16 <script type="text/javascript" src="navtree.js"></script>
  17         <link href="search/search.css" rel="stylesheet" type="text/css"/>
  18 <script type="text/javascript" src="search/searchdata.js"></script>
  19 <script type="text/javascript" src="search/search.js"></script>
  20     <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
  21         <link href="doxygen.css" rel="stylesheet" type="text/css" />
  22         <link href="normalise.css" rel="stylesheet" type="text/css"/>
  23 <link href="main.css" rel="stylesheet" type="text/css"/>
  24 <link href="styles.css" rel="stylesheet" type="text/css"/>
  25 </head>
  26 <body>
  27         <div class="navigation-mobile">
  28                 <div class="logo--mobile">
  29                         <a href="/"><img src="logo-mobile.svg" alt="Raspberry Pi"></a>
  30                 </div>
  31                 <div class="navigation-toggle">
  32                         <span class="line-1"></span>
  33                         <span class="line-2">
  34                                 <p>Menu Toggle</p>
  35                         </span>
  36                         <span class="line-3"></span>
  37                 </div>
  38         </div>
  39         <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  40                 <div class="logo">
  41                         <a href="index.html"> <img src="logo.svg" alt="Raspberry Pi"></a>
  42                         <span style="display: inline-block; margin-top: 10px;">
  43                                 v2.0.0
  44                         </span>
  45                 </div>
  46                 <div class="navigation-footer">
  47                         <img src="logo-mobile.svg" alt="Raspberry Pi">
  48                         <a href="https://www.raspberrypi.com/" target="_blank">By Raspberry Pi Ltd</a>
  49                 </div>
  50 <!--            <div class="search">
  51                         <form>
  52                                 <input type="search" name="search" id="search" placeholder="Search">
  53                                 <input type="submit" value="Search">
  54                         </form>
  55                 </div> -->
  56 <!-- Generated by Doxygen 1.9.4 -->
  57 <script type="text/javascript">
  58 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  59 var searchBox = new SearchBox("searchBox", "search",'Search','.html');
  60 /* @license-end */
  61 </script>
  62 <script type="text/javascript" src="menudata.js"></script>
  63 <script type="text/javascript" src="menu.js"></script>
  64 <script type="text/javascript">
  65 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  66 $(function() {
  67   initMenu('',true,false,'search.php','Search');
  68   $(document).ready(function() { init_search(); });
  69 });
  70 /* @license-end */
  71 </script>
  72 <div id="main-nav"></div>
  73 </div><!-- top -->
  74 <div id="side-nav" class="ui-resizable side-nav-resizable">
  75   <div id="nav-tree">
  76     <div id="nav-tree-contents">
  77       <div id="nav-sync" class="sync"></div>
  78     </div>
  79   </div>
  80   <div id="splitbar" style="-moz-user-select:none;"
  81        class="ui-resizable-handle">
  82   </div>
  83 </div>
  84 <script type="text/javascript">
  85 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  86 $(document).ready(function(){initNavTree('group__lock__core.html',''); initResizable(); });
  87 /* @license-end */
  88 </script>
  89 <div id="doc-content">
  90 <!-- window showing the filter options -->
  91 <div id="MSearchSelectWindow"
  92      onmouseover="return searchBox.OnSearchSelectShow()"
  93      onmouseout="return searchBox.OnSearchSelectHide()"
  94      onkeydown="return searchBox.OnSearchSelectKey(event)">
  95 </div>
  96
  97 <!-- iframe showing the search results (closed by default) -->
  98 <div id="MSearchResultsWindow">
  99 <iframe src="javascript:void(0)" frameborder="0"
 100         name="MSearchResults" id="MSearchResults">
 101 </iframe>
 102 </div>
 103
 104 <div class="header">
 105   <div class="summary">
 106 <a href="#files">Files</a> &#124;
 107 <a href="#define-members">Macros</a> &#124;
 108 <a href="#func-members">Functions</a>  </div>
 109   <div class="headertitle"><div class="title">lock_core<div class="ingroups"><a class="el" href="group__high__level.html">High Level APIs</a> &raquo; <a class="el" href="group__pico__sync.html">pico_sync</a></div></div></div>
 110 </div><!--header-->
 111 <div class="contents">
 112
 113 <p>base synchronization/lock primitive support.
 114 <a href="#details">More...</a></p>
 115 <table class="memberdecls">
 116 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="files" name="files"></a>
 117 Files</h2></td></tr>
 118 <tr class="memitem:lock__core_8h"><td class="memItemLeft" align="right" valign="top">file &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="lock__core_8h.html">lock_core.h</a></td></tr>
 119 <tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
 120 </table><table class="memberdecls">
 121 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
 122 Macros</h2></td></tr>
 123 <tr class="memitem:ga7e5b614312aabaada704b6a2350d39bc"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#ga7e5b614312aabaada704b6a2350d39bc">lock_owner_id_t</a>&#160;&#160;&#160;int8_t</td></tr>
 124 <tr class="memdesc:ga7e5b614312aabaada704b6a2350d39bc"><td class="mdescLeft">&#160;</td><td class="mdescRight">type to use to store the 'owner' of a lock.  <a href="group__lock__core.html#ga7e5b614312aabaada704b6a2350d39bc">More...</a><br /></td></tr>
 125 <tr class="separator:ga7e5b614312aabaada704b6a2350d39bc"><td class="memSeparator" colspan="2">&#160;</td></tr>
 126 <tr class="memitem:ga56aa223ceb22fdc4f0a3464fff119e14"><td class="memItemLeft" align="right" valign="top"><a id="ga56aa223ceb22fdc4f0a3464fff119e14" name="ga56aa223ceb22fdc4f0a3464fff119e14"></a>
 127 #define&#160;</td><td class="memItemRight" valign="bottom"><b>LOCK_INVALID_OWNER_ID</b>&#160;&#160;&#160;((<a class="el" href="group__lock__core.html#ga7e5b614312aabaada704b6a2350d39bc">lock_owner_id_t</a>)-1)</td></tr>
 128 <tr class="memdesc:ga56aa223ceb22fdc4f0a3464fff119e14"><td class="mdescLeft">&#160;</td><td class="mdescRight">marker value to use for a lock_owner_id_t which does not refer to any valid owner <br /></td></tr>
 129 <tr class="separator:ga56aa223ceb22fdc4f0a3464fff119e14"><td class="memSeparator" colspan="2">&#160;</td></tr>
 130 <tr class="memitem:gae28f1d974cf1f1b973127500a764245c"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#gae28f1d974cf1f1b973127500a764245c">lock_get_caller_owner_id</a>()&#160;&#160;&#160;((<a class="el" href="group__lock__core.html#ga7e5b614312aabaada704b6a2350d39bc">lock_owner_id_t</a>)<a class="el" href="group__pico__platform.html#ga58434ad816f519308ee02c639b7965bc">get_core_num</a>())</td></tr>
 131 <tr class="memdesc:gae28f1d974cf1f1b973127500a764245c"><td class="mdescLeft">&#160;</td><td class="mdescRight">return the owner id for the caller  <a href="group__lock__core.html#gae28f1d974cf1f1b973127500a764245c">More...</a><br /></td></tr>
 132 <tr class="separator:gae28f1d974cf1f1b973127500a764245c"><td class="memSeparator" colspan="2">&#160;</td></tr>
 133 <tr class="memitem:gaaea64ba43b0ff683739ba136fe5a2b29"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#gaaea64ba43b0ff683739ba136fe5a2b29">lock_internal_spin_unlock_with_wait</a>(lock,  save)&#160;&#160;&#160;<a class="el" href="group__hardware__sync.html#ga281ce69786da23cab7ba6c42537d4e87">spin_unlock</a>((lock)-&gt;spin_lock, save), <a class="el" href="group__hardware__sync.html#ga7799a0b9fc6444d463170266392f5fcd">__wfe</a>()</td></tr>
 134 <tr class="memdesc:gaaea64ba43b0ff683739ba136fe5a2b29"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically unlock the lock's spin lock, and wait for a notification.  <a href="group__lock__core.html#gaaea64ba43b0ff683739ba136fe5a2b29">More...</a><br /></td></tr>
 135 <tr class="separator:gaaea64ba43b0ff683739ba136fe5a2b29"><td class="memSeparator" colspan="2">&#160;</td></tr>
 136 <tr class="memitem:ga298f38f465c9115393f0f35f56c13279"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#ga298f38f465c9115393f0f35f56c13279">lock_internal_spin_unlock_with_notify</a>(lock,  save)&#160;&#160;&#160;<a class="el" href="group__hardware__sync.html#ga281ce69786da23cab7ba6c42537d4e87">spin_unlock</a>((lock)-&gt;spin_lock, save), <a class="el" href="group__hardware__sync.html#ga486eada32246494118f8273a80ae6856">__sev</a>()</td></tr>
 137 <tr class="memdesc:ga298f38f465c9115393f0f35f56c13279"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically unlock the lock's spin lock, and send a notification.  <a href="group__lock__core.html#ga298f38f465c9115393f0f35f56c13279">More...</a><br /></td></tr>
 138 <tr class="separator:ga298f38f465c9115393f0f35f56c13279"><td class="memSeparator" colspan="2">&#160;</td></tr>
 139 <tr class="memitem:ga627a09221ed61634d6dfea6f406e104e"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#ga627a09221ed61634d6dfea6f406e104e">lock_internal_spin_unlock_with_best_effort_wait_or_timeout</a>(lock,  save,  until)</td></tr>
 140 <tr class="memdesc:ga627a09221ed61634d6dfea6f406e104e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically unlock the lock's spin lock, and wait for a notification or a timeout.  <a href="group__lock__core.html#ga627a09221ed61634d6dfea6f406e104e">More...</a><br /></td></tr>
 141 <tr class="separator:ga627a09221ed61634d6dfea6f406e104e"><td class="memSeparator" colspan="2">&#160;</td></tr>
 142 <tr class="memitem:ga133eb482d67637b8b4e947dee5133513"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#ga133eb482d67637b8b4e947dee5133513">sync_internal_yield_until_before</a>(until)&#160;&#160;&#160;((void)0)</td></tr>
 143 <tr class="memdesc:ga133eb482d67637b8b4e947dee5133513"><td class="mdescLeft">&#160;</td><td class="mdescRight">yield to other processing until some time before the requested time  <a href="group__lock__core.html#ga133eb482d67637b8b4e947dee5133513">More...</a><br /></td></tr>
 144 <tr class="separator:ga133eb482d67637b8b4e947dee5133513"><td class="memSeparator" colspan="2">&#160;</td></tr>
 145 </table><table class="memberdecls">
 146 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
 147 Functions</h2></td></tr>
 148 <tr class="memitem:gabc062dfb52c8f7f17ec8427d1c4414d9"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__lock__core.html#gabc062dfb52c8f7f17ec8427d1c4414d9">lock_init</a> (<a class="el" href="structlock__core.html">lock_core_t</a> *core, uint lock_num)</td></tr>
 149 <tr class="memdesc:gabc062dfb52c8f7f17ec8427d1c4414d9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialise a lock structure.  <a href="group__lock__core.html#gabc062dfb52c8f7f17ec8427d1c4414d9">More...</a><br /></td></tr>
 150 <tr class="separator:gabc062dfb52c8f7f17ec8427d1c4414d9"><td class="memSeparator" colspan="2">&#160;</td></tr>
 151 </table>
 152 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 153 <p >base synchronization/lock primitive support. </p>
 154 <p >Most of the pico_sync locking primitives contain a lock_core_t structure member. This currently just holds a spin lock which is used only to protect the contents of the rest of the structure as part of implementing the synchronization primitive. As such, the spin_lock member of lock core is never still held on return from any function for the primitive.</p>
 155 <p ><a class="el" href="group__critical__section.html">critical_section</a> is an exceptional case in that it does not have a lock_core_t and simply wraps a spin lock, providing methods to lock and unlock said spin lock.</p>
 156 <p ><a class="el" href="structlock__core.html">lock_core</a> based structures work by locking the spin lock, checking state, and then deciding whether they additionally need to block or notify when the spin lock is released. In the blocking case, they will wake up again in the future, and try the process again.</p>
 157 <p >By default the SDK just uses the processors' events via SEV and WEV for notification and blocking as these are sufficient for cross core, and notification from interrupt handlers. However macros are defined in this file that abstract the wait and notify mechanisms to allow the SDK locking functions to effectively be used within an RTOS or other environment.</p>
 158 <p >When implementing an RTOS, it is desirable for the SDK synchronization primitives that wait, to block the calling task (and immediately yield), and those that notify, to wake a blocked task which isn't on processor. At least the wait macro implementation needs to be atomic with the protecting spin_lock unlock from the callers point of view; i.e. the task should unlock the spin lock when it starts its wait. Such implementation is up to the RTOS integration, however the macros are defined such that such operations are always combined into a single call (so they can be performed atomically) even though the default implementation does not need this, as a WFE which starts following the corresponding SEV is not missed. </p>
 159 <h2 class="groupheader">Macro Definition Documentation</h2>
 160 <a id="gae28f1d974cf1f1b973127500a764245c" name="gae28f1d974cf1f1b973127500a764245c"></a>
 161 <h2 class="memtitle"><span class="permalink"><a href="#gae28f1d974cf1f1b973127500a764245c">&#9670;&nbsp;</a></span>lock_get_caller_owner_id</h2>
 162
 163 <div class="memitem">
 164 <div class="memproto">
 165       <table class="memname">
 166         <tr>
 167           <td class="memname">#define lock_get_caller_owner_id</td>
 168           <td>(</td>
 169           <td class="paramname"></td><td>)</td>
 170           <td>&#160;&#160;&#160;((<a class="el" href="group__lock__core.html#ga7e5b614312aabaada704b6a2350d39bc">lock_owner_id_t</a>)<a class="el" href="group__pico__platform.html#ga58434ad816f519308ee02c639b7965bc">get_core_num</a>())</td>
 171         </tr>
 172       </table>
 173 </div><div class="memdoc">
 174
 175 <p>return the owner id for the caller </p>
 176 <p >By default this returns the calling core number, but may be overridden (e.g. to return an RTOS task id) </p>
 177
 178 </div>
 179 </div>
 180 <a id="ga627a09221ed61634d6dfea6f406e104e" name="ga627a09221ed61634d6dfea6f406e104e"></a>
 181 <h2 class="memtitle"><span class="permalink"><a href="#ga627a09221ed61634d6dfea6f406e104e">&#9670;&nbsp;</a></span>lock_internal_spin_unlock_with_best_effort_wait_or_timeout</h2>
 182
 183 <div class="memitem">
 184 <div class="memproto">
 185       <table class="memname">
 186         <tr>
 187           <td class="memname">#define lock_internal_spin_unlock_with_best_effort_wait_or_timeout</td>
 188           <td>(</td>
 189           <td class="paramtype">&#160;</td>
 190           <td class="paramname">lock, </td>
 191         </tr>
 192         <tr>
 193           <td class="paramkey"></td>
 194           <td></td>
 195           <td class="paramtype">&#160;</td>
 196           <td class="paramname">save, </td>
 197         </tr>
 198         <tr>
 199           <td class="paramkey"></td>
 200           <td></td>
 201           <td class="paramtype">&#160;</td>
 202           <td class="paramname">until&#160;</td>
 203         </tr>
 204         <tr>
 205           <td></td>
 206           <td>)</td>
 207           <td></td><td></td>
 208         </tr>
 209       </table>
 210 </div><div class="memdoc">
 211 <b>Value:</b><div class="fragment"><div class="line">    ({ \</div>
 212 <div class="line">    spin_unlock((lock)-&gt;spin_lock, save);                                                \</div>
 213 <div class="line">    best_effort_wfe_or_timeout(until);                                                   \</div>
 214 <div class="line">})</div>
 215 </div><!-- fragment -->
 216 <p>Atomically unlock the lock's spin lock, and wait for a notification or a timeout. </p>
 217 <p ><em>Atomic</em> here refers to the fact that it should not be possible for a concurrent lock_internal_spin_unlock_with_notify to insert itself between the spin unlock and this wait in a way that the wait does not see the notification (i.e. causing a missed notification). In other words this method should always wake up in response to a lock_internal_spin_unlock_with_notify for the same lock, which completes after this call starts.</p>
 218 <p >In an ideal implementation, this method would return exactly after the corresponding lock_internal_spin_unlock_with_notify has subsequently been called on the same lock instance or the timeout has been reached, however this method is free to return at <em>any</em> point before that; this macro is <em>always</em> used in a loop which locks the spin lock, checks the internal locking primitive state and then waits again if the calling thread should not proceed.</p>
 219 <p >By default this simply unlocks the spin lock, and then calls <a class="el" href="group__sleep.html#gaedc0ed51a5e908ddd660a5d279009abc">best_effort_wfe_or_timeout</a> but may be overridden (e.g. to actually block the RTOS task with a timeout).</p>
 220 <dl class="params"><dt>Parameters</dt><dd>
 221   <table class="params">
 222     <tr><td class="paramname">lock</td><td>the <a class="el" href="structlock__core.html">lock_core</a> for the primitive which needs to block </td></tr>
 223     <tr><td class="paramname">save</td><td>the uint32_t value that should be passed to spin_unlock when the spin lock is unlocked. (i.e. the PRIMASK state when the spin lock was acquire) </td></tr>
 224     <tr><td class="paramname">until</td><td>the <a class="el" href="group__timestamp.html#ga8b7f3d602cc053f05bacceeacc257ed8">absolute_time_t</a> value </td></tr>
 225   </table>
 226   </dd>
 227 </dl>
 228 <dl class="section return"><dt>Returns</dt><dd>true if the timeout has been reached </dd></dl>
 229
 230 </div>
 231 </div>
 232 <a id="ga298f38f465c9115393f0f35f56c13279" name="ga298f38f465c9115393f0f35f56c13279"></a>
 233 <h2 class="memtitle"><span class="permalink"><a href="#ga298f38f465c9115393f0f35f56c13279">&#9670;&nbsp;</a></span>lock_internal_spin_unlock_with_notify</h2>
 234
 235 <div class="memitem">
 236 <div class="memproto">
 237       <table class="memname">
 238         <tr>
 239           <td class="memname">#define lock_internal_spin_unlock_with_notify</td>
 240           <td>(</td>
 241           <td class="paramtype">&#160;</td>
 242           <td class="paramname">lock, </td>
 243         </tr>
 244         <tr>
 245           <td class="paramkey"></td>
 246           <td></td>
 247           <td class="paramtype">&#160;</td>
 248           <td class="paramname">save&#160;</td>
 249         </tr>
 250         <tr>
 251           <td></td>
 252           <td>)</td>
 253           <td></td><td>&#160;&#160;&#160;<a class="el" href="group__hardware__sync.html#ga281ce69786da23cab7ba6c42537d4e87">spin_unlock</a>((lock)-&gt;spin_lock, save), <a class="el" href="group__hardware__sync.html#ga486eada32246494118f8273a80ae6856">__sev</a>()</td>
 254         </tr>
 255       </table>
 256 </div><div class="memdoc">
 257
 258 <p>Atomically unlock the lock's spin lock, and send a notification. </p>
 259 <p ><em>Atomic</em> here refers to the fact that it should not be possible for this notification to happen during a lock_internal_spin_unlock_with_wait in a way that that wait does not see the notification (i.e. causing a missed notification). In other words this method should always wake up any lock_internal_spin_unlock_with_wait which started before this call completes.</p>
 260 <p >In an ideal implementation, this method would wake up only the corresponding lock_internal_spin_unlock_with_wait that has been called on the same lock instance, however it is free to wake up any of them, as they will check their condition and then re-wait if necessary/</p>
 261 <p >By default this macro simply unlocks the spin lock, and then performs a SEV, but may be overridden (e.g. to actually un-block RTOS task(s)).</p>
 262 <dl class="params"><dt>Parameters</dt><dd>
 263   <table class="params">
 264     <tr><td class="paramname">lock</td><td>the <a class="el" href="structlock__core.html">lock_core</a> for the primitive which needs to block </td></tr>
 265     <tr><td class="paramname">save</td><td>the uint32_t value that should be passed to spin_unlock when the spin lock is unlocked. (i.e. the PRIMASK state when the spin lock was acquire) </td></tr>
 266   </table>
 267   </dd>
 268 </dl>
 269
 270 </div>
 271 </div>
 272 <a id="gaaea64ba43b0ff683739ba136fe5a2b29" name="gaaea64ba43b0ff683739ba136fe5a2b29"></a>
 273 <h2 class="memtitle"><span class="permalink"><a href="#gaaea64ba43b0ff683739ba136fe5a2b29">&#9670;&nbsp;</a></span>lock_internal_spin_unlock_with_wait</h2>
 274
 275 <div class="memitem">
 276 <div class="memproto">
 277       <table class="memname">
 278         <tr>
 279           <td class="memname">#define lock_internal_spin_unlock_with_wait</td>
 280           <td>(</td>
 281           <td class="paramtype">&#160;</td>
 282           <td class="paramname">lock, </td>
 283         </tr>
 284         <tr>
 285           <td class="paramkey"></td>
 286           <td></td>
 287           <td class="paramtype">&#160;</td>
 288           <td class="paramname">save&#160;</td>
 289         </tr>
 290         <tr>
 291           <td></td>
 292           <td>)</td>
 293           <td></td><td>&#160;&#160;&#160;<a class="el" href="group__hardware__sync.html#ga281ce69786da23cab7ba6c42537d4e87">spin_unlock</a>((lock)-&gt;spin_lock, save), <a class="el" href="group__hardware__sync.html#ga7799a0b9fc6444d463170266392f5fcd">__wfe</a>()</td>
 294         </tr>
 295       </table>
 296 </div><div class="memdoc">
 297
 298 <p>Atomically unlock the lock's spin lock, and wait for a notification. </p>
 299 <p ><em>Atomic</em> here refers to the fact that it should not be possible for a concurrent lock_internal_spin_unlock_with_notify to insert itself between the spin unlock and this wait in a way that the wait does not see the notification (i.e. causing a missed notification). In other words this method should always wake up in response to a lock_internal_spin_unlock_with_notify for the same lock, which completes after this call starts.</p>
 300 <p >In an ideal implementation, this method would return exactly after the corresponding lock_internal_spin_unlock_with_notify has subsequently been called on the same lock instance, however this method is free to return at <em>any</em> point before that; this macro is <em>always</em> used in a loop which locks the spin lock, checks the internal locking primitive state and then waits again if the calling thread should not proceed.</p>
 301 <p >By default this macro simply unlocks the spin lock, and then performs a WFE, but may be overridden (e.g. to actually block the RTOS task).</p>
 302 <dl class="params"><dt>Parameters</dt><dd>
 303   <table class="params">
 304     <tr><td class="paramname">lock</td><td>the <a class="el" href="structlock__core.html">lock_core</a> for the primitive which needs to block </td></tr>
 305     <tr><td class="paramname">save</td><td>the uint32_t value that should be passed to spin_unlock when the spin lock is unlocked. (i.e. the <code>PRIMASK</code> state when the spin lock was acquire </td></tr>
 306   </table>
 307   </dd>
 308 </dl>
 309
 310 </div>
 311 </div>
 312 <a id="ga7e5b614312aabaada704b6a2350d39bc" name="ga7e5b614312aabaada704b6a2350d39bc"></a>
 313 <h2 class="memtitle"><span class="permalink"><a href="#ga7e5b614312aabaada704b6a2350d39bc">&#9670;&nbsp;</a></span>lock_owner_id_t</h2>
 314
 315 <div class="memitem">
 316 <div class="memproto">
 317       <table class="memname">
 318         <tr>
 319           <td class="memname">#define lock_owner_id_t&#160;&#160;&#160;int8_t</td>
 320         </tr>
 321       </table>
 322 </div><div class="memdoc">
 323
 324 <p>type to use to store the 'owner' of a lock. </p>
 325 <p >By default this is int8_t as it only needs to store the core number or -1, however it may be overridden if a larger type is required (e.g. for an RTOS task id) </p>
 326
 327 </div>
 328 </div>
 329 <a id="ga133eb482d67637b8b4e947dee5133513" name="ga133eb482d67637b8b4e947dee5133513"></a>
 330 <h2 class="memtitle"><span class="permalink"><a href="#ga133eb482d67637b8b4e947dee5133513">&#9670;&nbsp;</a></span>sync_internal_yield_until_before</h2>
 331
 332 <div class="memitem">
 333 <div class="memproto">
 334       <table class="memname">
 335         <tr>
 336           <td class="memname">#define sync_internal_yield_until_before</td>
 337           <td>(</td>
 338           <td class="paramtype">&#160;</td>
 339           <td class="paramname">until</td><td>)</td>
 340           <td>&#160;&#160;&#160;((void)0)</td>
 341         </tr>
 342       </table>
 343 </div><div class="memdoc">
 344
 345 <p>yield to other processing until some time before the requested time </p>
 346 <p >This method is provided for cases where the caller has no useful work to do until the specified time.</p>
 347 <p >By default this method does nothing, however it can be overridden (for example by an RTOS which is able to block the current task until the scheduler tick before the given time)</p>
 348 <dl class="params"><dt>Parameters</dt><dd>
 349   <table class="params">
 350     <tr><td class="paramname">until</td><td>the <a class="el" href="group__timestamp.html#ga8b7f3d602cc053f05bacceeacc257ed8">absolute_time_t</a> value </td></tr>
 351   </table>
 352   </dd>
 353 </dl>
 354
 355 </div>
 356 </div>
 357 <h2 class="groupheader">Function Documentation</h2>
 358 <a id="gabc062dfb52c8f7f17ec8427d1c4414d9" name="gabc062dfb52c8f7f17ec8427d1c4414d9"></a>
 359 <h2 class="memtitle"><span class="permalink"><a href="#gabc062dfb52c8f7f17ec8427d1c4414d9">&#9670;&nbsp;</a></span>lock_init()</h2>
 360
 361 <div class="memitem">
 362 <div class="memproto">
 363       <table class="memname">
 364         <tr>
 365           <td class="memname">void lock_init </td>
 366           <td>(</td>
 367           <td class="paramtype"><a class="el" href="structlock__core.html">lock_core_t</a> *&#160;</td>
 368           <td class="paramname"><em>core</em>, </td>
 369         </tr>
 370         <tr>
 371           <td class="paramkey"></td>
 372           <td></td>
 373           <td class="paramtype">uint&#160;</td>
 374           <td class="paramname"><em>lock_num</em>&#160;</td>
 375         </tr>
 376         <tr>
 377           <td></td>
 378           <td>)</td>
 379           <td></td><td></td>
 380         </tr>
 381       </table>
 382 </div><div class="memdoc">
 383
 384 <p>Initialise a lock structure. </p>
 385 <p >Inititalize a lock structure, providing the spin lock number to use for protecting internal state.</p>
 386 <dl class="params"><dt>Parameters</dt><dd>
 387   <table class="params">
 388     <tr><td class="paramname">core</td><td>Pointer to the <a class="el" href="structlock__core.html">lock_core</a> to initialize </td></tr>
 389     <tr><td class="paramname">lock_num</td><td>Spin lock number to use for the lock. As the spin lock is only used internally to the locking primitive method implementations, this does not need to be globally unique, however could suffer contention </td></tr>
 390   </table>
 391   </dd>
 392 </dl>
 393
 394 </div>
 395 </div>
 396 </div><!-- contents -->
 397 </div><!-- doc-content -->
 398
 399         <script src="main.js"></script>
 400 </body>
 401 </html>