web/docs/group__multicore__lockout.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: lockout</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__multicore__lockout.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="#func-members">Functions</a>  </div>
 107   <div class="headertitle"><div class="title">lockout<div class="ingroups"><a class="el" href="group__high__level.html">High Level APIs</a> &raquo; <a class="el" href="group__pico__multicore.html">pico_multicore</a></div></div></div>
 108 </div><!--header-->
 109 <div class="contents">
 110
 111 <p>Functions to enable one core to force the other core to pause execution in a known state.
 112 <a href="#details">More...</a></p>
 113 <table class="memberdecls">
 114 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
 115 Functions</h2></td></tr>
 116 <tr class="memitem:ga4e969086bda6851bc8ce8199113fd595"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">multicore_lockout_victim_init</a> (void)</td></tr>
 117 <tr class="memdesc:ga4e969086bda6851bc8ce8199113fd595"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialize the current core such that it can be a "victim" of lockout (i.e. forced to pause in a known state by the other core)  <a href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">More...</a><br /></td></tr>
 118 <tr class="separator:ga4e969086bda6851bc8ce8199113fd595"><td class="memSeparator" colspan="2">&#160;</td></tr>
 119 <tr class="memitem:ga3669ce9202da1860fcbbb11094778dd5"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#ga3669ce9202da1860fcbbb11094778dd5">multicore_lockout_victim_is_initialized</a> (uint core_num)</td></tr>
 120 <tr class="memdesc:ga3669ce9202da1860fcbbb11094778dd5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Determine if multicore_victim_init() has been called on the specified core.  <a href="group__multicore__lockout.html#ga3669ce9202da1860fcbbb11094778dd5">More...</a><br /></td></tr>
 121 <tr class="separator:ga3669ce9202da1860fcbbb11094778dd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
 122 <tr class="memitem:ga9a3f4df6b0e4140b0f40899a02c238d8"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#ga9a3f4df6b0e4140b0f40899a02c238d8">multicore_lockout_start_blocking</a> (void)</td></tr>
 123 <tr class="memdesc:ga9a3f4df6b0e4140b0f40899a02c238d8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Request the other core to pause in a known state and wait for it to do so.  <a href="group__multicore__lockout.html#ga9a3f4df6b0e4140b0f40899a02c238d8">More...</a><br /></td></tr>
 124 <tr class="separator:ga9a3f4df6b0e4140b0f40899a02c238d8"><td class="memSeparator" colspan="2">&#160;</td></tr>
 125 <tr class="memitem:gaaf40bf0b8b3a704f3178e38977d292be"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#gaaf40bf0b8b3a704f3178e38977d292be">multicore_lockout_start_timeout_us</a> (uint64_t timeout_us)</td></tr>
 126 <tr class="memdesc:gaaf40bf0b8b3a704f3178e38977d292be"><td class="mdescLeft">&#160;</td><td class="mdescRight">Request the other core to pause in a known state and wait up to a time limit for it to do so.  <a href="group__multicore__lockout.html#gaaf40bf0b8b3a704f3178e38977d292be">More...</a><br /></td></tr>
 127 <tr class="separator:gaaf40bf0b8b3a704f3178e38977d292be"><td class="memSeparator" colspan="2">&#160;</td></tr>
 128 <tr class="memitem:gab1b7b6dc6f81ca9524467f5024681167"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">multicore_lockout_end_blocking</a> (void)</td></tr>
 129 <tr class="memdesc:gab1b7b6dc6f81ca9524467f5024681167"><td class="mdescLeft">&#160;</td><td class="mdescRight">Release the other core from a locked out state amd wait for it to acknowledge.  <a href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">More...</a><br /></td></tr>
 130 <tr class="separator:gab1b7b6dc6f81ca9524467f5024681167"><td class="memSeparator" colspan="2">&#160;</td></tr>
 131 <tr class="memitem:gad61a822f1b135db1be62c19754694fe2"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__multicore__lockout.html#gad61a822f1b135db1be62c19754694fe2">multicore_lockout_end_timeout_us</a> (uint64_t timeout_us)</td></tr>
 132 <tr class="memdesc:gad61a822f1b135db1be62c19754694fe2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Release the other core from a locked out state amd wait up to a time limit for it to acknowledge.  <a href="group__multicore__lockout.html#gad61a822f1b135db1be62c19754694fe2">More...</a><br /></td></tr>
 133 <tr class="separator:gad61a822f1b135db1be62c19754694fe2"><td class="memSeparator" colspan="2">&#160;</td></tr>
 134 </table>
 135 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 136 <p >Functions to enable one core to force the other core to pause execution in a known state. </p>
 137 <p >Sometimes it is useful to enter a critical section on both cores at once. On a single core system a critical section can trivially be entered by disabling interrupts, however on a multi-core system that is not sufficient, and unless the other core is polling in some way, then it will need to be interrupted in order to cooperatively enter a blocked state.</p>
 138 <p >These "lockout" functions use the inter core FIFOs to cause an interrupt on one core from the other, and manage waiting for the other core to enter the "locked out" state.</p>
 139 <p >The usage is that the "victim" core ... i.e the core that can be "locked out" by the other core calls <a class="el" href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">multicore_lockout_victim_init</a> to hook the FIFO interrupt. Note that either or both cores may do this.</p>
 140 <dl class="section note"><dt>Note</dt><dd>When "locked out" the victim core is paused (it is actually executing a tight loop with code in RAM) and has interrupts disabled. This makes the lockout functions suitable for use by code that wants to write to flash (at which point no code may be executing from flash)</dd></dl>
 141 <p>The core which wishes to lockout the other core calls <a class="el" href="group__multicore__lockout.html#ga9a3f4df6b0e4140b0f40899a02c238d8">multicore_lockout_start_blocking</a> or <a class="el" href="group__multicore__lockout.html#gaaf40bf0b8b3a704f3178e38977d292be">multicore_lockout_start_timeout_us</a> to interrupt the other "victim" core and wait for it to be in a "locked out" state. Once the lockout is no longer needed it calls <a class="el" href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">multicore_lockout_end_blocking</a> or <a class="el" href="group__multicore__lockout.html#gad61a822f1b135db1be62c19754694fe2">multicore_lockout_end_timeout_us</a> to release the lockout and wait for confirmation.</p>
 142 <dl class="section note"><dt>Note</dt><dd>Because multicore lockout uses the intercore FIFOs, the FIFOs <b>cannot</b> be used for any other purpose </dd></dl>
 143 <h2 class="groupheader">Function Documentation</h2>
 144 <a id="gab1b7b6dc6f81ca9524467f5024681167" name="gab1b7b6dc6f81ca9524467f5024681167"></a>
 145 <h2 class="memtitle"><span class="permalink"><a href="#gab1b7b6dc6f81ca9524467f5024681167">&#9670;&nbsp;</a></span>multicore_lockout_end_blocking()</h2>
 146
 147 <div class="memitem">
 148 <div class="memproto">
 149       <table class="memname">
 150         <tr>
 151           <td class="memname">void multicore_lockout_end_blocking </td>
 152           <td>(</td>
 153           <td class="paramtype">void&#160;</td>
 154           <td class="paramname"></td><td>)</td>
 155           <td></td>
 156         </tr>
 157       </table>
 158 </div><div class="memdoc">
 159
 160 <p>Release the other core from a locked out state amd wait for it to acknowledge. </p>
 161 <dl class="section note"><dt>Note</dt><dd>The other core must previously have been "locked out" by calling a <code>multicore_lockout_start_</code> function from this core </dd></dl>
 162
 163 </div>
 164 </div>
 165 <a id="gad61a822f1b135db1be62c19754694fe2" name="gad61a822f1b135db1be62c19754694fe2"></a>
 166 <h2 class="memtitle"><span class="permalink"><a href="#gad61a822f1b135db1be62c19754694fe2">&#9670;&nbsp;</a></span>multicore_lockout_end_timeout_us()</h2>
 167
 168 <div class="memitem">
 169 <div class="memproto">
 170       <table class="memname">
 171         <tr>
 172           <td class="memname">bool multicore_lockout_end_timeout_us </td>
 173           <td>(</td>
 174           <td class="paramtype">uint64_t&#160;</td>
 175           <td class="paramname"><em>timeout_us</em></td><td>)</td>
 176           <td></td>
 177         </tr>
 178       </table>
 179 </div><div class="memdoc">
 180
 181 <p>Release the other core from a locked out state amd wait up to a time limit for it to acknowledge. </p>
 182 <p >The other core must previously have been "locked out" by calling a <code>multicore_lockout_start_</code> function from this core</p>
 183 <dl class="section note"><dt>Note</dt><dd>be very careful using small timeout values, as a timeout here will leave the "lockout" functionality in a bad state. It is probably preferable to use <a class="el" href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">multicore_lockout_end_blocking</a> anyway as if you have already waited for the victim core to enter the lockout state, then the victim core will be ready to exit the lockout state very quickly.</dd></dl>
 184 <dl class="params"><dt>Parameters</dt><dd>
 185   <table class="params">
 186     <tr><td class="paramname">timeout_us</td><td>the timeout in microseconds </td></tr>
 187   </table>
 188   </dd>
 189 </dl>
 190 <dl class="section return"><dt>Returns</dt><dd>true if the other core successfully exited locked out state within the timeout, false otherwise </dd></dl>
 191
 192 </div>
 193 </div>
 194 <a id="ga9a3f4df6b0e4140b0f40899a02c238d8" name="ga9a3f4df6b0e4140b0f40899a02c238d8"></a>
 195 <h2 class="memtitle"><span class="permalink"><a href="#ga9a3f4df6b0e4140b0f40899a02c238d8">&#9670;&nbsp;</a></span>multicore_lockout_start_blocking()</h2>
 196
 197 <div class="memitem">
 198 <div class="memproto">
 199       <table class="memname">
 200         <tr>
 201           <td class="memname">void multicore_lockout_start_blocking </td>
 202           <td>(</td>
 203           <td class="paramtype">void&#160;</td>
 204           <td class="paramname"></td><td>)</td>
 205           <td></td>
 206         </tr>
 207       </table>
 208 </div><div class="memdoc">
 209
 210 <p>Request the other core to pause in a known state and wait for it to do so. </p>
 211 <p >The other (victim) core must have previously executed <a class="el" href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">multicore_lockout_victim_init()</a></p>
 212 <dl class="section note"><dt>Note</dt><dd>multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding <a class="el" href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">multicore_lockout_end_blocking</a> </dd></dl>
 213
 214 </div>
 215 </div>
 216 <a id="gaaf40bf0b8b3a704f3178e38977d292be" name="gaaf40bf0b8b3a704f3178e38977d292be"></a>
 217 <h2 class="memtitle"><span class="permalink"><a href="#gaaf40bf0b8b3a704f3178e38977d292be">&#9670;&nbsp;</a></span>multicore_lockout_start_timeout_us()</h2>
 218
 219 <div class="memitem">
 220 <div class="memproto">
 221       <table class="memname">
 222         <tr>
 223           <td class="memname">bool multicore_lockout_start_timeout_us </td>
 224           <td>(</td>
 225           <td class="paramtype">uint64_t&#160;</td>
 226           <td class="paramname"><em>timeout_us</em></td><td>)</td>
 227           <td></td>
 228         </tr>
 229       </table>
 230 </div><div class="memdoc">
 231
 232 <p>Request the other core to pause in a known state and wait up to a time limit for it to do so. </p>
 233 <p >The other core must have previously executed <a class="el" href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">multicore_lockout_victim_init()</a></p>
 234 <dl class="section note"><dt>Note</dt><dd>multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding <a class="el" href="group__multicore__lockout.html#gab1b7b6dc6f81ca9524467f5024681167">multicore_lockout_end_blocking</a></dd></dl>
 235 <dl class="params"><dt>Parameters</dt><dd>
 236   <table class="params">
 237     <tr><td class="paramname">timeout_us</td><td>the timeout in microseconds </td></tr>
 238   </table>
 239   </dd>
 240 </dl>
 241 <dl class="section return"><dt>Returns</dt><dd>true if the other core entered the locked out state within the timeout, false otherwise </dd></dl>
 242
 243 </div>
 244 </div>
 245 <a id="ga4e969086bda6851bc8ce8199113fd595" name="ga4e969086bda6851bc8ce8199113fd595"></a>
 246 <h2 class="memtitle"><span class="permalink"><a href="#ga4e969086bda6851bc8ce8199113fd595">&#9670;&nbsp;</a></span>multicore_lockout_victim_init()</h2>
 247
 248 <div class="memitem">
 249 <div class="memproto">
 250       <table class="memname">
 251         <tr>
 252           <td class="memname">void multicore_lockout_victim_init </td>
 253           <td>(</td>
 254           <td class="paramtype">void&#160;</td>
 255           <td class="paramname"></td><td>)</td>
 256           <td></td>
 257         </tr>
 258       </table>
 259 </div><div class="memdoc">
 260
 261 <p>Initialize the current core such that it can be a "victim" of lockout (i.e. forced to pause in a known state by the other core) </p>
 262 <p >This code hooks the intercore FIFO IRQ, and the FIFO may not be used for any other purpose after this. </p>
 263
 264 </div>
 265 </div>
 266 <a id="ga3669ce9202da1860fcbbb11094778dd5" name="ga3669ce9202da1860fcbbb11094778dd5"></a>
 267 <h2 class="memtitle"><span class="permalink"><a href="#ga3669ce9202da1860fcbbb11094778dd5">&#9670;&nbsp;</a></span>multicore_lockout_victim_is_initialized()</h2>
 268
 269 <div class="memitem">
 270 <div class="memproto">
 271       <table class="memname">
 272         <tr>
 273           <td class="memname">bool multicore_lockout_victim_is_initialized </td>
 274           <td>(</td>
 275           <td class="paramtype">uint&#160;</td>
 276           <td class="paramname"><em>core_num</em></td><td>)</td>
 277           <td></td>
 278         </tr>
 279       </table>
 280 </div><div class="memdoc">
 281
 282 <p>Determine if multicore_victim_init() has been called on the specified core. </p>
 283 <dl class="section note"><dt>Note</dt><dd>this state persists even if the core is subsequently reset; therefore you are advised to always call <a class="el" href="group__multicore__lockout.html#ga4e969086bda6851bc8ce8199113fd595">multicore_lockout_victim_init()</a> again after resetting a core, which had previously been initialized.</dd></dl>
 284 <dl class="params"><dt>Parameters</dt><dd>
 285   <table class="params">
 286     <tr><td class="paramname">core_num</td><td>the core number (0 or 1) </td></tr>
 287   </table>
 288   </dd>
 289 </dl>
 290 <dl class="section return"><dt>Returns</dt><dd>true if multicore_victim_init() has been called on the specified core, false otherwise. </dd></dl>
 291
 292 </div>
 293 </div>
 294 </div><!-- contents -->
 295 </div><!-- doc-content -->
 296
 297         <script src="main.js"></script>
 298 </body>
 299 </html>