web/docs/group__hardware__claim.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: hardware_claim</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__hardware__claim.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">hardware_claim<div class="ingroups"><a class="el" href="group__hardware.html">Hardware APIs</a></div></div></div>
 108 </div><!--header-->
 109 <div class="contents">
 110
 111 <p>Lightweight hardware resource management API.
 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:ga6487272cf1fa8d5b2e67f78bb5bdab4d"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#ga6487272cf1fa8d5b2e67f78bb5bdab4d">hw_claim_or_assert</a> (uint8_t *bits, uint bit_index, const char *message)</td></tr>
 117 <tr class="memdesc:ga6487272cf1fa8d5b2e67f78bb5bdab4d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically claim a resource, panicking if it is already in use.  <a href="group__hardware__claim.html#ga6487272cf1fa8d5b2e67f78bb5bdab4d">More...</a><br /></td></tr>
 118 <tr class="separator:ga6487272cf1fa8d5b2e67f78bb5bdab4d"><td class="memSeparator" colspan="2">&#160;</td></tr>
 119 <tr class="memitem:gacc8b9324cd6f327e57c6dcb8cbef1745"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#gacc8b9324cd6f327e57c6dcb8cbef1745">hw_claim_unused_from_range</a> (uint8_t *bits, bool required, uint bit_lsb, uint bit_msb, const char *message)</td></tr>
 120 <tr class="memdesc:gacc8b9324cd6f327e57c6dcb8cbef1745"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically claim one resource out of a range of resources, optionally asserting if none are free.  <a href="group__hardware__claim.html#gacc8b9324cd6f327e57c6dcb8cbef1745">More...</a><br /></td></tr>
 121 <tr class="separator:gacc8b9324cd6f327e57c6dcb8cbef1745"><td class="memSeparator" colspan="2">&#160;</td></tr>
 122 <tr class="memitem:gab3aa24c90859fbc4da40b8fce8852f6e"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#gab3aa24c90859fbc4da40b8fce8852f6e">hw_is_claimed</a> (const uint8_t *bits, uint bit_index)</td></tr>
 123 <tr class="memdesc:gab3aa24c90859fbc4da40b8fce8852f6e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Determine if a resource is claimed at the time of the call.  <a href="group__hardware__claim.html#gab3aa24c90859fbc4da40b8fce8852f6e">More...</a><br /></td></tr>
 124 <tr class="separator:gab3aa24c90859fbc4da40b8fce8852f6e"><td class="memSeparator" colspan="2">&#160;</td></tr>
 125 <tr class="memitem:ga9291a012435d3efff22c592d47e82b4a"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#ga9291a012435d3efff22c592d47e82b4a">hw_claim_clear</a> (uint8_t *bits, uint bit_index)</td></tr>
 126 <tr class="memdesc:ga9291a012435d3efff22c592d47e82b4a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Atomically unclaim a resource.  <a href="group__hardware__claim.html#ga9291a012435d3efff22c592d47e82b4a">More...</a><br /></td></tr>
 127 <tr class="separator:ga9291a012435d3efff22c592d47e82b4a"><td class="memSeparator" colspan="2">&#160;</td></tr>
 128 <tr class="memitem:gac322717d266403fac74aed5cef23eb95"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#gac322717d266403fac74aed5cef23eb95">hw_claim_lock</a> (void)</td></tr>
 129 <tr class="memdesc:gac322717d266403fac74aed5cef23eb95"><td class="mdescLeft">&#160;</td><td class="mdescRight">Acquire the runtime mutual exclusion lock provided by the <code>hardware_claim</code> library.  <a href="group__hardware__claim.html#gac322717d266403fac74aed5cef23eb95">More...</a><br /></td></tr>
 130 <tr class="separator:gac322717d266403fac74aed5cef23eb95"><td class="memSeparator" colspan="2">&#160;</td></tr>
 131 <tr class="memitem:gae5ebb9e8ede55de49e6296953d731005"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__hardware__claim.html#gae5ebb9e8ede55de49e6296953d731005">hw_claim_unlock</a> (uint32_t token)</td></tr>
 132 <tr class="memdesc:gae5ebb9e8ede55de49e6296953d731005"><td class="mdescLeft">&#160;</td><td class="mdescRight">Release the runtime mutual exclusion lock provided by the <code>hardware_claim</code> library.  <a href="group__hardware__claim.html#gae5ebb9e8ede55de49e6296953d731005">More...</a><br /></td></tr>
 133 <tr class="separator:gae5ebb9e8ede55de49e6296953d731005"><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 >Lightweight hardware resource management API. </p>
 137 <p ><code>hardware_claim</code> provides a simple API for management of hardware resources at runtime.</p>
 138 <p >This API is usually called by other hardware specific <em>claiming</em> APIs and provides simple multi-core safe methods to manipulate compact bit-sets representing hardware resources.</p>
 139 <p >This API allows any other library to cooperatively participate in a scheme by which both compile time and runtime allocation of resources can co-exist, and conflicts can be avoided or detected (depending on the use case) without the libraries having any other knowledge of each other.</p>
 140 <p >Facilities are providing for:</p>
 141 <ol type="1">
 142 <li>Claiming resources (and asserting if they are already claimed)</li>
 143 <li>Freeing (unclaiming) resources</li>
 144 <li>Finding unused resources </li>
 145 </ol>
 146 <h2 class="groupheader">Function Documentation</h2>
 147 <a id="ga9291a012435d3efff22c592d47e82b4a" name="ga9291a012435d3efff22c592d47e82b4a"></a>
 148 <h2 class="memtitle"><span class="permalink"><a href="#ga9291a012435d3efff22c592d47e82b4a">&#9670;&nbsp;</a></span>hw_claim_clear()</h2>
 149
 150 <div class="memitem">
 151 <div class="memproto">
 152       <table class="memname">
 153         <tr>
 154           <td class="memname">void hw_claim_clear </td>
 155           <td>(</td>
 156           <td class="paramtype">uint8_t *&#160;</td>
 157           <td class="paramname"><em>bits</em>, </td>
 158         </tr>
 159         <tr>
 160           <td class="paramkey"></td>
 161           <td></td>
 162           <td class="paramtype">uint&#160;</td>
 163           <td class="paramname"><em>bit_index</em>&#160;</td>
 164         </tr>
 165         <tr>
 166           <td></td>
 167           <td>)</td>
 168           <td></td><td></td>
 169         </tr>
 170       </table>
 171 </div><div class="memdoc">
 172
 173 <p>Atomically unclaim a resource. </p>
 174 <p >The resource ownership is indicated by the bit_index bit in an array of bits.</p>
 175 <dl class="params"><dt>Parameters</dt><dd>
 176   <table class="params">
 177     <tr><td class="paramname">bits</td><td>pointer to an array of bits (8 bits per byte) </td></tr>
 178     <tr><td class="paramname">bit_index</td><td>resource to unclaim (bit index into array of bits) </td></tr>
 179   </table>
 180   </dd>
 181 </dl>
 182
 183 </div>
 184 </div>
 185 <a id="gac322717d266403fac74aed5cef23eb95" name="gac322717d266403fac74aed5cef23eb95"></a>
 186 <h2 class="memtitle"><span class="permalink"><a href="#gac322717d266403fac74aed5cef23eb95">&#9670;&nbsp;</a></span>hw_claim_lock()</h2>
 187
 188 <div class="memitem">
 189 <div class="memproto">
 190       <table class="memname">
 191         <tr>
 192           <td class="memname">uint32_t hw_claim_lock </td>
 193           <td>(</td>
 194           <td class="paramtype">void&#160;</td>
 195           <td class="paramname"></td><td>)</td>
 196           <td></td>
 197         </tr>
 198       </table>
 199 </div><div class="memdoc">
 200
 201 <p>Acquire the runtime mutual exclusion lock provided by the <code>hardware_claim</code> library. </p>
 202 <p >This method is called automatically by the other <code>hw_claim_</code> methods, however it is provided as a convenience to code that might want to protect other hardware initialization code from concurrent use.</p>
 203 <dl class="section note"><dt>Note</dt><dd><a class="el" href="group__hardware__claim.html#gac322717d266403fac74aed5cef23eb95" title="Acquire the runtime mutual exclusion lock provided by the hardware_claim library.">hw_claim_lock()</a> uses a spin lock internally, so disables interrupts on the calling core, and will deadlock if the calling core already owns the lock.</dd></dl>
 204 <dl class="section return"><dt>Returns</dt><dd>a token to pass to <a class="el" href="group__hardware__claim.html#gae5ebb9e8ede55de49e6296953d731005" title="Release the runtime mutual exclusion lock provided by the hardware_claim library.">hw_claim_unlock()</a> </dd></dl>
 205
 206 </div>
 207 </div>
 208 <a id="ga6487272cf1fa8d5b2e67f78bb5bdab4d" name="ga6487272cf1fa8d5b2e67f78bb5bdab4d"></a>
 209 <h2 class="memtitle"><span class="permalink"><a href="#ga6487272cf1fa8d5b2e67f78bb5bdab4d">&#9670;&nbsp;</a></span>hw_claim_or_assert()</h2>
 210
 211 <div class="memitem">
 212 <div class="memproto">
 213       <table class="memname">
 214         <tr>
 215           <td class="memname">void hw_claim_or_assert </td>
 216           <td>(</td>
 217           <td class="paramtype">uint8_t *&#160;</td>
 218           <td class="paramname"><em>bits</em>, </td>
 219         </tr>
 220         <tr>
 221           <td class="paramkey"></td>
 222           <td></td>
 223           <td class="paramtype">uint&#160;</td>
 224           <td class="paramname"><em>bit_index</em>, </td>
 225         </tr>
 226         <tr>
 227           <td class="paramkey"></td>
 228           <td></td>
 229           <td class="paramtype">const char *&#160;</td>
 230           <td class="paramname"><em>message</em>&#160;</td>
 231         </tr>
 232         <tr>
 233           <td></td>
 234           <td>)</td>
 235           <td></td><td></td>
 236         </tr>
 237       </table>
 238 </div><div class="memdoc">
 239
 240 <p>Atomically claim a resource, panicking if it is already in use. </p>
 241 <p >The resource ownership is indicated by the bit_index bit in an array of bits.</p>
 242 <dl class="params"><dt>Parameters</dt><dd>
 243   <table class="params">
 244     <tr><td class="paramname">bits</td><td>pointer to an array of bits (8 bits per byte) </td></tr>
 245     <tr><td class="paramname">bit_index</td><td>resource to claim (bit index into array of bits) </td></tr>
 246     <tr><td class="paramname">message</td><td>string to display if the bit cannot be claimed; note this may have a single printf format "%d" for the bit </td></tr>
 247   </table>
 248   </dd>
 249 </dl>
 250
 251 </div>
 252 </div>
 253 <a id="gae5ebb9e8ede55de49e6296953d731005" name="gae5ebb9e8ede55de49e6296953d731005"></a>
 254 <h2 class="memtitle"><span class="permalink"><a href="#gae5ebb9e8ede55de49e6296953d731005">&#9670;&nbsp;</a></span>hw_claim_unlock()</h2>
 255
 256 <div class="memitem">
 257 <div class="memproto">
 258       <table class="memname">
 259         <tr>
 260           <td class="memname">void hw_claim_unlock </td>
 261           <td>(</td>
 262           <td class="paramtype">uint32_t&#160;</td>
 263           <td class="paramname"><em>token</em></td><td>)</td>
 264           <td></td>
 265         </tr>
 266       </table>
 267 </div><div class="memdoc">
 268
 269 <p>Release the runtime mutual exclusion lock provided by the <code>hardware_claim</code> library. </p>
 270 <dl class="section note"><dt>Note</dt><dd>This method MUST be called from the same core that call <a class="el" href="group__hardware__claim.html#gac322717d266403fac74aed5cef23eb95" title="Acquire the runtime mutual exclusion lock provided by the hardware_claim library.">hw_claim_lock()</a></dd></dl>
 271 <dl class="params"><dt>Parameters</dt><dd>
 272   <table class="params">
 273     <tr><td class="paramname">token</td><td>the token returned by the corresponding call to <a class="el" href="group__hardware__claim.html#gac322717d266403fac74aed5cef23eb95" title="Acquire the runtime mutual exclusion lock provided by the hardware_claim library.">hw_claim_lock()</a> </td></tr>
 274   </table>
 275   </dd>
 276 </dl>
 277
 278 </div>
 279 </div>
 280 <a id="gacc8b9324cd6f327e57c6dcb8cbef1745" name="gacc8b9324cd6f327e57c6dcb8cbef1745"></a>
 281 <h2 class="memtitle"><span class="permalink"><a href="#gacc8b9324cd6f327e57c6dcb8cbef1745">&#9670;&nbsp;</a></span>hw_claim_unused_from_range()</h2>
 282
 283 <div class="memitem">
 284 <div class="memproto">
 285       <table class="memname">
 286         <tr>
 287           <td class="memname">int hw_claim_unused_from_range </td>
 288           <td>(</td>
 289           <td class="paramtype">uint8_t *&#160;</td>
 290           <td class="paramname"><em>bits</em>, </td>
 291         </tr>
 292         <tr>
 293           <td class="paramkey"></td>
 294           <td></td>
 295           <td class="paramtype">bool&#160;</td>
 296           <td class="paramname"><em>required</em>, </td>
 297         </tr>
 298         <tr>
 299           <td class="paramkey"></td>
 300           <td></td>
 301           <td class="paramtype">uint&#160;</td>
 302           <td class="paramname"><em>bit_lsb</em>, </td>
 303         </tr>
 304         <tr>
 305           <td class="paramkey"></td>
 306           <td></td>
 307           <td class="paramtype">uint&#160;</td>
 308           <td class="paramname"><em>bit_msb</em>, </td>
 309         </tr>
 310         <tr>
 311           <td class="paramkey"></td>
 312           <td></td>
 313           <td class="paramtype">const char *&#160;</td>
 314           <td class="paramname"><em>message</em>&#160;</td>
 315         </tr>
 316         <tr>
 317           <td></td>
 318           <td>)</td>
 319           <td></td><td></td>
 320         </tr>
 321       </table>
 322 </div><div class="memdoc">
 323
 324 <p>Atomically claim one resource out of a range of resources, optionally asserting if none are free. </p>
 325 <dl class="params"><dt>Parameters</dt><dd>
 326   <table class="params">
 327     <tr><td class="paramname">bits</td><td>pointer to an array of bits (8 bits per byte) </td></tr>
 328     <tr><td class="paramname">required</td><td>true if this method should panic if the resource is not free </td></tr>
 329     <tr><td class="paramname">bit_lsb</td><td>the lower bound (inclusive) of the resource range to claim from </td></tr>
 330     <tr><td class="paramname">bit_msb</td><td>the upper bound (inclusive) of the resource range to claim from </td></tr>
 331     <tr><td class="paramname">message</td><td>string to display if the bit cannot be claimed </td></tr>
 332   </table>
 333   </dd>
 334 </dl>
 335 <dl class="section return"><dt>Returns</dt><dd>the bit index representing the claimed or -1 if none are available in the range, and required = false </dd></dl>
 336
 337 </div>
 338 </div>
 339 <a id="gab3aa24c90859fbc4da40b8fce8852f6e" name="gab3aa24c90859fbc4da40b8fce8852f6e"></a>
 340 <h2 class="memtitle"><span class="permalink"><a href="#gab3aa24c90859fbc4da40b8fce8852f6e">&#9670;&nbsp;</a></span>hw_is_claimed()</h2>
 341
 342 <div class="memitem">
 343 <div class="memproto">
 344 <table class="mlabels">
 345   <tr>
 346   <td class="mlabels-left">
 347       <table class="memname">
 348         <tr>
 349           <td class="memname">bool hw_is_claimed </td>
 350           <td>(</td>
 351           <td class="paramtype">const uint8_t *&#160;</td>
 352           <td class="paramname"><em>bits</em>, </td>
 353         </tr>
 354         <tr>
 355           <td class="paramkey"></td>
 356           <td></td>
 357           <td class="paramtype">uint&#160;</td>
 358           <td class="paramname"><em>bit_index</em>&#160;</td>
 359         </tr>
 360         <tr>
 361           <td></td>
 362           <td>)</td>
 363           <td></td><td></td>
 364         </tr>
 365       </table>
 366   </td>
 367   <td class="mlabels-right">
 368 <span class="mlabels"><span class="mlabel">inline</span></span>  </td>
 369   </tr>
 370 </table>
 371 </div><div class="memdoc">
 372
 373 <p>Determine if a resource is claimed at the time of the call. </p>
 374 <p >The resource ownership is indicated by the bit_index bit in an array of bits.</p>
 375 <dl class="params"><dt>Parameters</dt><dd>
 376   <table class="params">
 377     <tr><td class="paramname">bits</td><td>pointer to an array of bits (8 bits per byte) </td></tr>
 378     <tr><td class="paramname">bit_index</td><td>resource to check (bit index into array of bits) </td></tr>
 379   </table>
 380   </dd>
 381 </dl>
 382 <dl class="section return"><dt>Returns</dt><dd>true if the resource is claimed </dd></dl>
 383
 384 </div>
 385 </div>
 386 </div><!-- contents -->
 387 </div><!-- doc-content -->
 388
 389         <script src="main.js"></script>
 390 </body>
 391 </html>