web/docs/group__pico__rand.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: pico_rand</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__pico__rand.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">pico_rand<div class="ingroups"><a class="el" href="group__high__level.html">High Level APIs</a></div></div></div>
 108 </div><!--header-->
 109 <div class="contents">
 110
 111 <p>Random Number Generator 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:ga97a9544b527a3ba865ab70142bdd5d1b"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__rand.html#ga97a9544b527a3ba865ab70142bdd5d1b">get_rand_128</a> (<a class="el" href="structrng__128.html">rng_128_t</a> *rand128)</td></tr>
 117 <tr class="memdesc:ga97a9544b527a3ba865ab70142bdd5d1b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get 128-bit random number.  <a href="group__pico__rand.html#ga97a9544b527a3ba865ab70142bdd5d1b">More...</a><br /></td></tr>
 118 <tr class="separator:ga97a9544b527a3ba865ab70142bdd5d1b"><td class="memSeparator" colspan="2">&#160;</td></tr>
 119 <tr class="memitem:ga783185fba81c03eb0c1d687d322b0112"><td class="memItemLeft" align="right" valign="top">uint64_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__rand.html#ga783185fba81c03eb0c1d687d322b0112">get_rand_64</a> (void)</td></tr>
 120 <tr class="memdesc:ga783185fba81c03eb0c1d687d322b0112"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get 64-bit random number.  <a href="group__pico__rand.html#ga783185fba81c03eb0c1d687d322b0112">More...</a><br /></td></tr>
 121 <tr class="separator:ga783185fba81c03eb0c1d687d322b0112"><td class="memSeparator" colspan="2">&#160;</td></tr>
 122 <tr class="memitem:gac446d739bd6818ee25b5c8644ef7c8e8"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__rand.html#gac446d739bd6818ee25b5c8644ef7c8e8">get_rand_32</a> (void)</td></tr>
 123 <tr class="memdesc:gac446d739bd6818ee25b5c8644ef7c8e8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get 32-bit random number.  <a href="group__pico__rand.html#gac446d739bd6818ee25b5c8644ef7c8e8">More...</a><br /></td></tr>
 124 <tr class="separator:gac446d739bd6818ee25b5c8644ef7c8e8"><td class="memSeparator" colspan="2">&#160;</td></tr>
 125 </table>
 126 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 127 <p >Random Number Generator API. </p>
 128 <p >This module generates random numbers at runtime utilizing a number of possible entropy sources and uses those sources to modify the state of a 128-bit 'Pseudo Random Number Generator' implemented in software.</p>
 129 <p >The random numbers (32 to 128 bit) to be supplied are read from the PRNG which is used to help provide a large number space.</p>
 130 <p >The following (multiple) sources of entropy are available (of varying quality), each enabled by a #define:</p>
 131 <ul>
 132 <li>The Ring Oscillator (ROSC) (PICO_RAND_ENTROPY_SRC_ROSC == 1): PICO_RAND_ROSC_BIT_SAMPLE_COUNT bits are gathered from the ring oscillator "random bit" and mixed in each time. This should not be used if the ROSC is off, or the processor is running from the ROSC. <dl class="section note"><dt>Note</dt><dd>the maximum throughput of ROSC bit sampling is controlled by PICO_RAND_MIN_ROSC_BIT_SAMPLE_TIME_US which defaults to 10us, i.e. 100,000 bits per second.</dd></dl>
 133 </li>
 134 <li>Time (PICO_RAND_ENTROPY_SRC_TIME == 1): The 64-bit microsecond timer is mixed in each time.</li>
 135 <li>Bus Performance Counter (PICO_RAND_ENTROPY_SRC_BUS_PERF_COUNTER == 1): One of the bus fabric's performance counters is mixed in each time.</li>
 136 </ul>
 137 <dl class="section note"><dt>Note</dt><dd>All entropy sources are hashed before application to the PRNG state machine.</dd></dl>
 138 <p>The <em>first</em> time a random number is requested, the 128-bit PRNG state must be seeded. Multiple entropy sources are also available for the seeding operation:</p>
 139 <ul>
 140 <li>The Ring Oscillator (ROSC) (PICO_RAND_SEED_ENTROPY_SRC_ROSC == 1): 64 bits are gathered from the ring oscillator "random bit" and mixed into the seed.</li>
 141 <li>Time (PICO_RAND_SEED_ENTROPY_SRC_TIME == 1): The 64-bit microsecond timer is mixed into the seed.</li>
 142 <li>Board Identifier (PICO_RAND_SEED_ENTROPY_SRC_BOARD_ID == 1): The board id via <a class="el" href="group__pico__unique__id.html#gaf87ef8a55d8dc2520776e427a605b6fb">pico_get_unique_board_id</a> is mixed into the seed.</li>
 143 <li>RAM hash (PICO_RAND_SEED_ENTROPY_SRC_RAM_HASH (PICO_RAND_SEED_ENTROPY_SRC_RAM_HASH): The hashed contents of a subset of RAM are mixed in. Initial RAM contents are undefined on power up, so provide a reasonable source of entropy. By default the last 1K of RAM (which usually contains the core 0 stack) is hashed, which may also provide for differences after each warm reset.</li>
 144 </ul>
 145 <p >With default settings, the seed generation takes approximately 1 millisecond while subsequent random numbers generally take between 10 and 20 microseconds to generate.</p>
 146 <p >pico_rand methods may be safely called from either core or from an IRQ, but be careful in the latter case as the calls may block for a number of microseconds waiting on more entropy. </p>
 147 <h2 class="groupheader">Function Documentation</h2>
 148 <a id="ga97a9544b527a3ba865ab70142bdd5d1b" name="ga97a9544b527a3ba865ab70142bdd5d1b"></a>
 149 <h2 class="memtitle"><span class="permalink"><a href="#ga97a9544b527a3ba865ab70142bdd5d1b">&#9670;&nbsp;</a></span>get_rand_128()</h2>
 150
 151 <div class="memitem">
 152 <div class="memproto">
 153       <table class="memname">
 154         <tr>
 155           <td class="memname">void get_rand_128 </td>
 156           <td>(</td>
 157           <td class="paramtype"><a class="el" href="structrng__128.html">rng_128_t</a> *&#160;</td>
 158           <td class="paramname"><em>rand128</em></td><td>)</td>
 159           <td></td>
 160         </tr>
 161       </table>
 162 </div><div class="memdoc">
 163
 164 <p>Get 128-bit random number. </p>
 165 <p >This method may be safely called from either core or from an IRQ, but be careful in the latter case as the call may block for a number of microseconds waiting on more entropy.</p>
 166 <dl class="params"><dt>Parameters</dt><dd>
 167   <table class="params">
 168     <tr><td class="paramname">rand128</td><td>Pointer to storage to accept a 128-bit random number </td></tr>
 169   </table>
 170   </dd>
 171 </dl>
 172
 173 </div>
 174 </div>
 175 <a id="gac446d739bd6818ee25b5c8644ef7c8e8" name="gac446d739bd6818ee25b5c8644ef7c8e8"></a>
 176 <h2 class="memtitle"><span class="permalink"><a href="#gac446d739bd6818ee25b5c8644ef7c8e8">&#9670;&nbsp;</a></span>get_rand_32()</h2>
 177
 178 <div class="memitem">
 179 <div class="memproto">
 180       <table class="memname">
 181         <tr>
 182           <td class="memname">uint32_t get_rand_32 </td>
 183           <td>(</td>
 184           <td class="paramtype">void&#160;</td>
 185           <td class="paramname"></td><td>)</td>
 186           <td></td>
 187         </tr>
 188       </table>
 189 </div><div class="memdoc">
 190
 191 <p>Get 32-bit random number. </p>
 192 <p >This method may be safely called from either core or from an IRQ, but be careful in the latter case as the call may block for a number of microseconds waiting on more entropy.</p>
 193 <dl class="section return"><dt>Returns</dt><dd>32-bit random number </dd></dl>
 194
 195 </div>
 196 </div>
 197 <a id="ga783185fba81c03eb0c1d687d322b0112" name="ga783185fba81c03eb0c1d687d322b0112"></a>
 198 <h2 class="memtitle"><span class="permalink"><a href="#ga783185fba81c03eb0c1d687d322b0112">&#9670;&nbsp;</a></span>get_rand_64()</h2>
 199
 200 <div class="memitem">
 201 <div class="memproto">
 202       <table class="memname">
 203         <tr>
 204           <td class="memname">uint64_t get_rand_64 </td>
 205           <td>(</td>
 206           <td class="paramtype">void&#160;</td>
 207           <td class="paramname"></td><td>)</td>
 208           <td></td>
 209         </tr>
 210       </table>
 211 </div><div class="memdoc">
 212
 213 <p>Get 64-bit random number. </p>
 214 <p >This method may be safely called from either core or from an IRQ, but be careful in the latter case as the call may block for a number of microseconds waiting on more entropy.</p>
 215 <dl class="section return"><dt>Returns</dt><dd>64-bit random number </dd></dl>
 216
 217 </div>
 218 </div>
 219 </div><!-- contents -->
 220 </div><!-- doc-content -->
 221
 222         <script src="main.js"></script>
 223 </body>
 224 </html>