web/docs/group__pico__bootrom.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_bootrom</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__bootrom.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="#define-members">Macros</a> &#124;
 107 <a href="#func-members">Functions</a>  </div>
 108   <div class="headertitle"><div class="title">pico_bootrom<div class="ingroups"><a class="el" href="group__runtime.html">Runtime Infrastructure</a></div></div></div>
 109 </div><!--header-->
 110 <div class="contents">
 111
 112 <p>Access to functions and data in the bootrom.
 113 <a href="#details">More...</a></p>
 114 <table class="memberdecls">
 115 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
 116 Macros</h2></td></tr>
 117 <tr class="memitem:ga5b3c93cbab0054e9938f2aca7261a73e"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga5b3c93cbab0054e9938f2aca7261a73e">ROM_TABLE_CODE</a>(c1,  c2)&#160;&#160;&#160;((c1) | ((c2) &lt;&lt; 8))</td></tr>
 118 <tr class="memdesc:ga5b3c93cbab0054e9938f2aca7261a73e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return a bootrom lookup code based on two ASCII characters.  <a href="group__pico__bootrom.html#ga5b3c93cbab0054e9938f2aca7261a73e">More...</a><br /></td></tr>
 119 <tr class="separator:ga5b3c93cbab0054e9938f2aca7261a73e"><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="func-members" name="func-members"></a>
 122 Functions</h2></td></tr>
 123 <tr class="memitem:ga2b6dcf9d9c60d54a222f7c259c76b4b4"><td class="memItemLeft" align="right" valign="top">static uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga2b6dcf9d9c60d54a222f7c259c76b4b4">rom_table_code</a> (uint8_t c1, uint8_t c2)</td></tr>
 124 <tr class="memdesc:ga2b6dcf9d9c60d54a222f7c259c76b4b4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return a bootrom lookup code based on two ASCII characters.  <a href="group__pico__bootrom.html#ga2b6dcf9d9c60d54a222f7c259c76b4b4">More...</a><br /></td></tr>
 125 <tr class="separator:ga2b6dcf9d9c60d54a222f7c259c76b4b4"><td class="memSeparator" colspan="2">&#160;</td></tr>
 126 <tr class="memitem:gaaaf61234f389da6444b6479f29616d7d"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gaaaf61234f389da6444b6479f29616d7d">rom_func_lookup</a> (uint32_t code)</td></tr>
 127 <tr class="memdesc:gaaaf61234f389da6444b6479f29616d7d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Lookup a bootrom function by its code.  <a href="group__pico__bootrom.html#gaaaf61234f389da6444b6479f29616d7d">More...</a><br /></td></tr>
 128 <tr class="separator:gaaaf61234f389da6444b6479f29616d7d"><td class="memSeparator" colspan="2">&#160;</td></tr>
 129 <tr class="memitem:gad3e66e7bcbf0448a0a63cf37dfb4b53c"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gad3e66e7bcbf0448a0a63cf37dfb4b53c">rom_data_lookup</a> (uint32_t code)</td></tr>
 130 <tr class="memdesc:gad3e66e7bcbf0448a0a63cf37dfb4b53c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Lookup a bootrom data address by its code.  <a href="group__pico__bootrom.html#gad3e66e7bcbf0448a0a63cf37dfb4b53c">More...</a><br /></td></tr>
 131 <tr class="separator:gad3e66e7bcbf0448a0a63cf37dfb4b53c"><td class="memSeparator" colspan="2">&#160;</td></tr>
 132 <tr class="memitem:ga31965209f0ddaeaecaeb3c516abda04d"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga31965209f0ddaeaecaeb3c516abda04d">rom_funcs_lookup</a> (uint32_t *table, unsigned int count)</td></tr>
 133 <tr class="memdesc:ga31965209f0ddaeaecaeb3c516abda04d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Helper function to lookup the addresses of multiple bootrom functions.  <a href="group__pico__bootrom.html#ga31965209f0ddaeaecaeb3c516abda04d">More...</a><br /></td></tr>
 134 <tr class="separator:ga31965209f0ddaeaecaeb3c516abda04d"><td class="memSeparator" colspan="2">&#160;</td></tr>
 135 <tr class="memitem:ga8f4e326502015aa4f4624251df366268"><td class="memItemLeft" align="right" valign="top">static <a class="el" href="group__pico__platform.html#ga23eadd8d1642fb8fe4600708c36e116a">__force_inline</a> void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga8f4e326502015aa4f4624251df366268">rom_func_lookup_inline</a> (uint32_t code)</td></tr>
 136 <tr class="memdesc:ga8f4e326502015aa4f4624251df366268"><td class="mdescLeft">&#160;</td><td class="mdescRight">Lookup a bootrom function by code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.  <a href="group__pico__bootrom.html#ga8f4e326502015aa4f4624251df366268">More...</a><br /></td></tr>
 137 <tr class="separator:ga8f4e326502015aa4f4624251df366268"><td class="memSeparator" colspan="2">&#160;</td></tr>
 138 <tr class="memitem:ga1bbe1c1df02daaa7b68a0c95fb9dc545"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga1bbe1c1df02daaa7b68a0c95fb9dc545">rom_reset_usb_boot</a> (uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask)</td></tr>
 139 <tr class="memdesc:ga1bbe1c1df02daaa7b68a0c95fb9dc545"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reboot the device into BOOTSEL mode.  <a href="group__pico__bootrom.html#ga1bbe1c1df02daaa7b68a0c95fb9dc545">More...</a><br /></td></tr>
 140 <tr class="separator:ga1bbe1c1df02daaa7b68a0c95fb9dc545"><td class="memSeparator" colspan="2">&#160;</td></tr>
 141 <tr class="memitem:gaa089fab5e976fea3fd88fecb44863ffc"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gaa089fab5e976fea3fd88fecb44863ffc">rom_connect_internal_flash</a> ()</td></tr>
 142 <tr class="memdesc:gaa089fab5e976fea3fd88fecb44863ffc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Connect the SSI/QMI to the QSPI pads.  <a href="group__pico__bootrom.html#gaa089fab5e976fea3fd88fecb44863ffc">More...</a><br /></td></tr>
 143 <tr class="separator:gaa089fab5e976fea3fd88fecb44863ffc"><td class="memSeparator" colspan="2">&#160;</td></tr>
 144 <tr class="memitem:ga472decf755ee1f64afdf14a90e6c8807"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga472decf755ee1f64afdf14a90e6c8807">rom_flash_exit_xip</a> ()</td></tr>
 145 <tr class="memdesc:ga472decf755ee1f64afdf14a90e6c8807"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the QSPI device from its XIP state to a serial command state.  <a href="group__pico__bootrom.html#ga472decf755ee1f64afdf14a90e6c8807">More...</a><br /></td></tr>
 146 <tr class="separator:ga472decf755ee1f64afdf14a90e6c8807"><td class="memSeparator" colspan="2">&#160;</td></tr>
 147 <tr class="memitem:gad2a854a04f7007e9e5efa67fe8887cd7"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gad2a854a04f7007e9e5efa67fe8887cd7">rom_flash_range_erase</a> (uint32_t addr, size_t count, uint32_t block_size, uint8_t block_cmd)</td></tr>
 148 <tr class="memdesc:gad2a854a04f7007e9e5efa67fe8887cd7"><td class="mdescLeft">&#160;</td><td class="mdescRight">Erase bytes in flash.  <a href="group__pico__bootrom.html#gad2a854a04f7007e9e5efa67fe8887cd7">More...</a><br /></td></tr>
 149 <tr class="separator:gad2a854a04f7007e9e5efa67fe8887cd7"><td class="memSeparator" colspan="2">&#160;</td></tr>
 150 <tr class="memitem:ga7fd2af8eea3dbd7bc76ed3306186ccef"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#ga7fd2af8eea3dbd7bc76ed3306186ccef">rom_flash_range_program</a> (uint32_t addr, const uint8_t *data, size_t count)</td></tr>
 151 <tr class="memdesc:ga7fd2af8eea3dbd7bc76ed3306186ccef"><td class="mdescLeft">&#160;</td><td class="mdescRight">Program bytes in flash.  <a href="group__pico__bootrom.html#ga7fd2af8eea3dbd7bc76ed3306186ccef">More...</a><br /></td></tr>
 152 <tr class="separator:ga7fd2af8eea3dbd7bc76ed3306186ccef"><td class="memSeparator" colspan="2">&#160;</td></tr>
 153 <tr class="memitem:gacd6b37e87ff97264edba6c6349e52f72"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gacd6b37e87ff97264edba6c6349e52f72">rom_flash_flush_cache</a> ()</td></tr>
 154 <tr class="memdesc:gacd6b37e87ff97264edba6c6349e52f72"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flush the XIP cache.  <a href="group__pico__bootrom.html#gacd6b37e87ff97264edba6c6349e52f72">More...</a><br /></td></tr>
 155 <tr class="separator:gacd6b37e87ff97264edba6c6349e52f72"><td class="memSeparator" colspan="2">&#160;</td></tr>
 156 <tr class="memitem:gae2af7b462bd0a7e9d0fc0a5fc1ce909e"><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__pico__bootrom.html#gae2af7b462bd0a7e9d0fc0a5fc1ce909e">rom_flash_enter_cmd_xip</a> ()</td></tr>
 157 <tr class="memdesc:gae2af7b462bd0a7e9d0fc0a5fc1ce909e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Configure the SSI/QMI with a standard command.  <a href="group__pico__bootrom.html#gae2af7b462bd0a7e9d0fc0a5fc1ce909e">More...</a><br /></td></tr>
 158 <tr class="separator:gae2af7b462bd0a7e9d0fc0a5fc1ce909e"><td class="memSeparator" colspan="2">&#160;</td></tr>
 159 </table>
 160 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 161 <p >Access to functions and data in the bootrom. </p>
 162 <p >This header may be included by assembly code </p>
 163 <h2 class="groupheader">Macro Definition Documentation</h2>
 164 <a id="ga5b3c93cbab0054e9938f2aca7261a73e" name="ga5b3c93cbab0054e9938f2aca7261a73e"></a>
 165 <h2 class="memtitle"><span class="permalink"><a href="#ga5b3c93cbab0054e9938f2aca7261a73e">&#9670;&nbsp;</a></span>ROM_TABLE_CODE</h2>
 166
 167 <div class="memitem">
 168 <div class="memproto">
 169       <table class="memname">
 170         <tr>
 171           <td class="memname">#define ROM_TABLE_CODE</td>
 172           <td>(</td>
 173           <td class="paramtype">&#160;</td>
 174           <td class="paramname">c1, </td>
 175         </tr>
 176         <tr>
 177           <td class="paramkey"></td>
 178           <td></td>
 179           <td class="paramtype">&#160;</td>
 180           <td class="paramname">c2&#160;</td>
 181         </tr>
 182         <tr>
 183           <td></td>
 184           <td>)</td>
 185           <td></td><td>&#160;&#160;&#160;((c1) | ((c2) &lt;&lt; 8))</td>
 186         </tr>
 187       </table>
 188 </div><div class="memdoc">
 189
 190 <p>Return a bootrom lookup code based on two ASCII characters. </p>
 191 <p >These codes are uses to lookup data or function addresses in the bootrom</p>
 192 <dl class="params"><dt>Parameters</dt><dd>
 193   <table class="params">
 194     <tr><td class="paramname">c1</td><td>the first character </td></tr>
 195     <tr><td class="paramname">c2</td><td>the second character </td></tr>
 196   </table>
 197   </dd>
 198 </dl>
 199 <dl class="section return"><dt>Returns</dt><dd>the 'code' to use in <a class="el" href="group__pico__bootrom.html#gaaaf61234f389da6444b6479f29616d7d" title="Lookup a bootrom function by its code.">rom_func_lookup()</a> or <a class="el" href="group__pico__bootrom.html#gad3e66e7bcbf0448a0a63cf37dfb4b53c" title="Lookup a bootrom data address by its code.">rom_data_lookup()</a> </dd></dl>
 200
 201 </div>
 202 </div>
 203 <h2 class="groupheader">Function Documentation</h2>
 204 <a id="gaa089fab5e976fea3fd88fecb44863ffc" name="gaa089fab5e976fea3fd88fecb44863ffc"></a>
 205 <h2 class="memtitle"><span class="permalink"><a href="#gaa089fab5e976fea3fd88fecb44863ffc">&#9670;&nbsp;</a></span>rom_connect_internal_flash()</h2>
 206
 207 <div class="memitem">
 208 <div class="memproto">
 209 <table class="mlabels">
 210   <tr>
 211   <td class="mlabels-left">
 212       <table class="memname">
 213         <tr>
 214           <td class="memname">static void rom_connect_internal_flash </td>
 215           <td>(</td>
 216           <td class="paramname"></td><td>)</td>
 217           <td></td>
 218         </tr>
 219       </table>
 220   </td>
 221   <td class="mlabels-right">
 222 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 223   </tr>
 224 </table>
 225 </div><div class="memdoc">
 226
 227 <p>Connect the SSI/QMI to the QSPI pads. </p>
 228 <p >Restore all QSPI pad controls to their default state, and connect the SSI/QMI peripheral to the QSPI pads.</p>
 229 <p >On RP2350 if a secondary flash chip select GPIO has been configured via OTP OTP_DATA_FLASH_DEVINFO, or by writing to the runtime copy of FLASH_DEVINFO in bootram, then this bank 0 GPIO is also initialised and the QMI peripheral is connected. Otherwise, bank 0 IOs are untouched.  </p>
 230
 231 </div>
 232 </div>
 233 <a id="gad3e66e7bcbf0448a0a63cf37dfb4b53c" name="gad3e66e7bcbf0448a0a63cf37dfb4b53c"></a>
 234 <h2 class="memtitle"><span class="permalink"><a href="#gad3e66e7bcbf0448a0a63cf37dfb4b53c">&#9670;&nbsp;</a></span>rom_data_lookup()</h2>
 235
 236 <div class="memitem">
 237 <div class="memproto">
 238       <table class="memname">
 239         <tr>
 240           <td class="memname">void * rom_data_lookup </td>
 241           <td>(</td>
 242           <td class="paramtype">uint32_t&#160;</td>
 243           <td class="paramname"><em>code</em></td><td>)</td>
 244           <td></td>
 245         </tr>
 246       </table>
 247 </div><div class="memdoc">
 248
 249 <p>Lookup a bootrom data address by its code. </p>
 250 <dl class="params"><dt>Parameters</dt><dd>
 251   <table class="params">
 252     <tr><td class="paramname">code</td><td>the code </td></tr>
 253   </table>
 254   </dd>
 255 </dl>
 256 <dl class="section return"><dt>Returns</dt><dd>a pointer to the data, or NULL if the code does not match any bootrom function </dd></dl>
 257
 258 </div>
 259 </div>
 260 <a id="gae2af7b462bd0a7e9d0fc0a5fc1ce909e" name="gae2af7b462bd0a7e9d0fc0a5fc1ce909e"></a>
 261 <h2 class="memtitle"><span class="permalink"><a href="#gae2af7b462bd0a7e9d0fc0a5fc1ce909e">&#9670;&nbsp;</a></span>rom_flash_enter_cmd_xip()</h2>
 262
 263 <div class="memitem">
 264 <div class="memproto">
 265 <table class="mlabels">
 266   <tr>
 267   <td class="mlabels-left">
 268       <table class="memname">
 269         <tr>
 270           <td class="memname">static void rom_flash_enter_cmd_xip </td>
 271           <td>(</td>
 272           <td class="paramname"></td><td>)</td>
 273           <td></td>
 274         </tr>
 275       </table>
 276   </td>
 277   <td class="mlabels-right">
 278 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 279   </tr>
 280 </table>
 281 </div><div class="memdoc">
 282
 283 <p>Configure the SSI/QMI with a standard command. </p>
 284 <p >Configure the SSI/QMI to generate a standard 03h serial read command, with 24 address bits, upon each XIP access. This is a slow XIP configuration, but is widely supported. CLKDIV is set to 12 on RP2350. The debugger may call this function to ensure that flash is readable following a program/erase operation.</p>
 285 <p >Note that the same setup is performed by flash_exit_xip(), and the RP2350 flash program/erase functions do not leave XIP in an inaccessible state, so calls to this function are largely redundant on RP2350. It is provided on RP2350 for compatibility with RP2040. </p>
 286
 287 </div>
 288 </div>
 289 <a id="ga472decf755ee1f64afdf14a90e6c8807" name="ga472decf755ee1f64afdf14a90e6c8807"></a>
 290 <h2 class="memtitle"><span class="permalink"><a href="#ga472decf755ee1f64afdf14a90e6c8807">&#9670;&nbsp;</a></span>rom_flash_exit_xip()</h2>
 291
 292 <div class="memitem">
 293 <div class="memproto">
 294 <table class="mlabels">
 295   <tr>
 296   <td class="mlabels-left">
 297       <table class="memname">
 298         <tr>
 299           <td class="memname">static void rom_flash_exit_xip </td>
 300           <td>(</td>
 301           <td class="paramname"></td><td>)</td>
 302           <td></td>
 303         </tr>
 304       </table>
 305   </td>
 306   <td class="mlabels-right">
 307 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 308   </tr>
 309 </table>
 310 </div><div class="memdoc">
 311
 312 <p>Return the QSPI device from its XIP state to a serial command state. </p>
 313 <p >On RP2040, first set up the SSI for serial-mode operations, then issue the fixed XIP exit sequence described in Section 2.8.1.2 of the datasheet. Note that the bootrom code uses the IO forcing logic to drive the CS pin, which must be cleared before returning the SSI to XIP mode (e.g. by a call to _flash_flush_cache). This function configures the SSI with a fixed SCK clock divisor of /6. </p>
 314 <p >On RP2350, Initialise the QMI for serial operations (direct mode), and also initialise a basic XIP mode, where the QMI will perform 03h serial read commands at low speed (CLKDIV=12) in response to XIP reads.</p>
 315 <p >Then, issue a sequence to the QSPI device on chip select 0, designed to return it from continuous read mode ("XIP mode") and/or QPI mode to a state where it will accept serial commands. This is necessary after system reset to restore the QSPI device to a known state, because resetting RP2350 does not reset attached QSPI devices. It is also necessary when user code, having already performed some continuous-read-mode or QPI-mode accesses, wishes to return the QSPI device to a state where it will accept the serial erase and programming commands issued by the bootrom's flash access functions.</p>
 316 <p >If a GPIO for the secondary chip select is configured via FLASH_DEVINFO, then the XIP exit sequence is also issued to chip select 1.</p>
 317 <p >The QSPI device should be accessible for XIP reads after calling this function; the name flash_exit_xip refers to returning the QSPI device from its XIP state to a serial command state.  </p>
 318
 319 </div>
 320 </div>
 321 <a id="gacd6b37e87ff97264edba6c6349e52f72" name="gacd6b37e87ff97264edba6c6349e52f72"></a>
 322 <h2 class="memtitle"><span class="permalink"><a href="#gacd6b37e87ff97264edba6c6349e52f72">&#9670;&nbsp;</a></span>rom_flash_flush_cache()</h2>
 323
 324 <div class="memitem">
 325 <div class="memproto">
 326 <table class="mlabels">
 327   <tr>
 328   <td class="mlabels-left">
 329       <table class="memname">
 330         <tr>
 331           <td class="memname">static void rom_flash_flush_cache </td>
 332           <td>(</td>
 333           <td class="paramname"></td><td>)</td>
 334           <td></td>
 335         </tr>
 336       </table>
 337   </td>
 338   <td class="mlabels-right">
 339 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 340   </tr>
 341 </table>
 342 </div><div class="memdoc">
 343
 344 <p>Flush the XIP cache. </p>
 345 <p >Flush and enable the XIP cache. Also clears the IO forcing on QSPI CSn, so that the SSI can drive the flash chip select as normal. </p>
 346 <p >Flush the entire XIP cache, by issuing an invalidate by set/way maintenance operation to every cache line. This ensures that flash program/erase operations are visible to subsequent cached XIP reads.</p>
 347 <p >Note that this unpins pinned cache lines, which may interfere with cache-as-SRAM use of the XIP cache.</p>
 348 <p >No other operations are performed.  </p>
 349
 350 </div>
 351 </div>
 352 <a id="gad2a854a04f7007e9e5efa67fe8887cd7" name="gad2a854a04f7007e9e5efa67fe8887cd7"></a>
 353 <h2 class="memtitle"><span class="permalink"><a href="#gad2a854a04f7007e9e5efa67fe8887cd7">&#9670;&nbsp;</a></span>rom_flash_range_erase()</h2>
 354
 355 <div class="memitem">
 356 <div class="memproto">
 357 <table class="mlabels">
 358   <tr>
 359   <td class="mlabels-left">
 360       <table class="memname">
 361         <tr>
 362           <td class="memname">static void rom_flash_range_erase </td>
 363           <td>(</td>
 364           <td class="paramtype">uint32_t&#160;</td>
 365           <td class="paramname"><em>addr</em>, </td>
 366         </tr>
 367         <tr>
 368           <td class="paramkey"></td>
 369           <td></td>
 370           <td class="paramtype">size_t&#160;</td>
 371           <td class="paramname"><em>count</em>, </td>
 372         </tr>
 373         <tr>
 374           <td class="paramkey"></td>
 375           <td></td>
 376           <td class="paramtype">uint32_t&#160;</td>
 377           <td class="paramname"><em>block_size</em>, </td>
 378         </tr>
 379         <tr>
 380           <td class="paramkey"></td>
 381           <td></td>
 382           <td class="paramtype">uint8_t&#160;</td>
 383           <td class="paramname"><em>block_cmd</em>&#160;</td>
 384         </tr>
 385         <tr>
 386           <td></td>
 387           <td>)</td>
 388           <td></td><td></td>
 389         </tr>
 390       </table>
 391   </td>
 392   <td class="mlabels-right">
 393 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 394   </tr>
 395 </table>
 396 </div><div class="memdoc">
 397
 398 <p>Erase bytes in flash. </p>
 399 <p >Erase count bytes, starting at addr (offset from start of flash). Optionally, pass a block erase command e.g. D8h block erase, and the size of the block erased by this command - this function will use the larger block erase where possible, for much higher erase speed. addr must be aligned to a 4096-byte sector, and count must be a multiple of 4096 bytes.</p>
 400 <p >This is a low-level flash API, and no validation of the arguments is performed.</p>
 401 <p >See rom_flash_op on RP2350 for a higher-level API which checks alignment, flash bounds and partition permissions, and can transparently apply a runtime-to-storage address translation.</p>
 402 <p >The QSPI device must be in a serial command state before calling this API, which can be achieved by calling <a class="el" href="group__pico__bootrom.html#gaa089fab5e976fea3fd88fecb44863ffc" title="Connect the SSI/QMI to the QSPI pads.">rom_connect_internal_flash()</a> followed by <a class="el" href="group__pico__bootrom.html#ga472decf755ee1f64afdf14a90e6c8807" title="Return the QSPI device from its XIP state to a serial command state.">rom_flash_exit_xip()</a>. After the erase, the flash cache should be flushed via <a class="el" href="group__pico__bootrom.html#gacd6b37e87ff97264edba6c6349e52f72" title="Flush the XIP cache.">rom_flash_flush_cache()</a> to ensure the modified flash data is visible to cached XIP accesses.</p>
 403 <p >Finally, the original XIP mode should be restored by copying the saved XIP setup function from bootram into SRAM, and executing it: the bootrom provides a default function which restores the flash mode/clkdiv discovered during flash scanning, and user programs can override this with their own XIP setup function.</p>
 404 <p >For the duration of the erase operation, QMI is in direct mode and attempting to access XIP from DMA, the debugger or the other core will return a bus fault. XIP becomes accessible again once the function returns. </p>
 405 <dl class="params"><dt>Parameters</dt><dd>
 406   <table class="params">
 407     <tr><td class="paramname">addr</td><td>the offset from start of flash to be erased </td></tr>
 408     <tr><td class="paramname">count</td><td>number of bytes to erase </td></tr>
 409     <tr><td class="paramname">block_size</td><td>optional size of block erased by block_cmd </td></tr>
 410     <tr><td class="paramname">block_cmd</td><td>optional block erase command e.g. D8h block erase </td></tr>
 411   </table>
 412   </dd>
 413 </dl>
 414
 415 </div>
 416 </div>
 417 <a id="ga7fd2af8eea3dbd7bc76ed3306186ccef" name="ga7fd2af8eea3dbd7bc76ed3306186ccef"></a>
 418 <h2 class="memtitle"><span class="permalink"><a href="#ga7fd2af8eea3dbd7bc76ed3306186ccef">&#9670;&nbsp;</a></span>rom_flash_range_program()</h2>
 419
 420 <div class="memitem">
 421 <div class="memproto">
 422 <table class="mlabels">
 423   <tr>
 424   <td class="mlabels-left">
 425       <table class="memname">
 426         <tr>
 427           <td class="memname">static void rom_flash_range_program </td>
 428           <td>(</td>
 429           <td class="paramtype">uint32_t&#160;</td>
 430           <td class="paramname"><em>addr</em>, </td>
 431         </tr>
 432         <tr>
 433           <td class="paramkey"></td>
 434           <td></td>
 435           <td class="paramtype">const uint8_t *&#160;</td>
 436           <td class="paramname"><em>data</em>, </td>
 437         </tr>
 438         <tr>
 439           <td class="paramkey"></td>
 440           <td></td>
 441           <td class="paramtype">size_t&#160;</td>
 442           <td class="paramname"><em>count</em>&#160;</td>
 443         </tr>
 444         <tr>
 445           <td></td>
 446           <td>)</td>
 447           <td></td><td></td>
 448         </tr>
 449       </table>
 450   </td>
 451   <td class="mlabels-right">
 452 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 453   </tr>
 454 </table>
 455 </div><div class="memdoc">
 456
 457 <p>Program bytes in flash. </p>
 458 <p >Program data to a range of flash addresses starting at addr (offset from the start of flash) and count bytes in size. addr must be aligned to a 256-byte boundary, and count must be a multiple of 256.</p>
 459 <p >This is a low-level flash API, and no validation of the arguments is performed.</p>
 460 <p >See rom_flash_op on RP2350 for a higher-level API which checks alignment, flash bounds and partition permissions, and can transparently apply a runtime-to-storage address translation.</p>
 461 <p >The QSPI device must be in a serial command state before calling this API - see notes on rom_flash_range_erase </p>
 462 <dl class="params"><dt>Parameters</dt><dd>
 463   <table class="params">
 464     <tr><td class="paramname">addr</td><td>the offset from start of flash to be erased </td></tr>
 465     <tr><td class="paramname">data</td><td>buffer containing the data to be written </td></tr>
 466     <tr><td class="paramname">count</td><td>number of bytes to erase </td></tr>
 467   </table>
 468   </dd>
 469 </dl>
 470
 471 </div>
 472 </div>
 473 <a id="gaaaf61234f389da6444b6479f29616d7d" name="gaaaf61234f389da6444b6479f29616d7d"></a>
 474 <h2 class="memtitle"><span class="permalink"><a href="#gaaaf61234f389da6444b6479f29616d7d">&#9670;&nbsp;</a></span>rom_func_lookup()</h2>
 475
 476 <div class="memitem">
 477 <div class="memproto">
 478       <table class="memname">
 479         <tr>
 480           <td class="memname">void * rom_func_lookup </td>
 481           <td>(</td>
 482           <td class="paramtype">uint32_t&#160;</td>
 483           <td class="paramname"><em>code</em></td><td>)</td>
 484           <td></td>
 485         </tr>
 486       </table>
 487 </div><div class="memdoc">
 488
 489 <p>Lookup a bootrom function by its code. </p>
 490 <dl class="params"><dt>Parameters</dt><dd>
 491   <table class="params">
 492     <tr><td class="paramname">code</td><td>the code </td></tr>
 493   </table>
 494   </dd>
 495 </dl>
 496 <dl class="section return"><dt>Returns</dt><dd>a pointer to the function, or NULL if the code does not match any bootrom function </dd></dl>
 497
 498 </div>
 499 </div>
 500 <a id="ga8f4e326502015aa4f4624251df366268" name="ga8f4e326502015aa4f4624251df366268"></a>
 501 <h2 class="memtitle"><span class="permalink"><a href="#ga8f4e326502015aa4f4624251df366268">&#9670;&nbsp;</a></span>rom_func_lookup_inline()</h2>
 502
 503 <div class="memitem">
 504 <div class="memproto">
 505 <table class="mlabels">
 506   <tr>
 507   <td class="mlabels-left">
 508       <table class="memname">
 509         <tr>
 510           <td class="memname">static <a class="el" href="group__pico__platform.html#ga23eadd8d1642fb8fe4600708c36e116a">__force_inline</a> void * rom_func_lookup_inline </td>
 511           <td>(</td>
 512           <td class="paramtype">uint32_t&#160;</td>
 513           <td class="paramname"><em>code</em></td><td>)</td>
 514           <td></td>
 515         </tr>
 516       </table>
 517   </td>
 518   <td class="mlabels-right">
 519 <span class="mlabels"><span class="mlabel">static</span></span>  </td>
 520   </tr>
 521 </table>
 522 </div><div class="memdoc">
 523
 524 <p>Lookup a bootrom function by code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage. </p>
 525 <dl class="params"><dt>Parameters</dt><dd>
 526   <table class="params">
 527     <tr><td class="paramname">code</td><td>the code </td></tr>
 528   </table>
 529   </dd>
 530 </dl>
 531 <dl class="section return"><dt>Returns</dt><dd>a pointer to the function, or NULL if the code does not match any bootrom function </dd></dl>
 532
 533 </div>
 534 </div>
 535 <a id="ga31965209f0ddaeaecaeb3c516abda04d" name="ga31965209f0ddaeaecaeb3c516abda04d"></a>
 536 <h2 class="memtitle"><span class="permalink"><a href="#ga31965209f0ddaeaecaeb3c516abda04d">&#9670;&nbsp;</a></span>rom_funcs_lookup()</h2>
 537
 538 <div class="memitem">
 539 <div class="memproto">
 540       <table class="memname">
 541         <tr>
 542           <td class="memname">bool rom_funcs_lookup </td>
 543           <td>(</td>
 544           <td class="paramtype">uint32_t *&#160;</td>
 545           <td class="paramname"><em>table</em>, </td>
 546         </tr>
 547         <tr>
 548           <td class="paramkey"></td>
 549           <td></td>
 550           <td class="paramtype">unsigned int&#160;</td>
 551           <td class="paramname"><em>count</em>&#160;</td>
 552         </tr>
 553         <tr>
 554           <td></td>
 555           <td>)</td>
 556           <td></td><td></td>
 557         </tr>
 558       </table>
 559 </div><div class="memdoc">
 560
 561 <p>Helper function to lookup the addresses of multiple bootrom functions. </p>
 562 <p >This method looks up the 'codes' in the table, and convert each table entry to the looked up function pointer, if there is a function for that code in the bootrom.</p>
 563 <dl class="params"><dt>Parameters</dt><dd>
 564   <table class="params">
 565     <tr><td class="paramname">table</td><td>an IN/OUT array, elements are codes on input, function pointers on success. </td></tr>
 566     <tr><td class="paramname">count</td><td>the number of elements in the table </td></tr>
 567   </table>
 568   </dd>
 569 </dl>
 570 <dl class="section return"><dt>Returns</dt><dd>true if all the codes were found, and converted to function pointers, false otherwise </dd></dl>
 571
 572 </div>
 573 </div>
 574 <a id="ga1bbe1c1df02daaa7b68a0c95fb9dc545" name="ga1bbe1c1df02daaa7b68a0c95fb9dc545"></a>
 575 <h2 class="memtitle"><span class="permalink"><a href="#ga1bbe1c1df02daaa7b68a0c95fb9dc545">&#9670;&nbsp;</a></span>rom_reset_usb_boot()</h2>
 576
 577 <div class="memitem">
 578 <div class="memproto">
 579       <table class="memname">
 580         <tr>
 581           <td class="memname">void rom_reset_usb_boot </td>
 582           <td>(</td>
 583           <td class="paramtype">uint32_t&#160;</td>
 584           <td class="paramname"><em>usb_activity_gpio_pin_mask</em>, </td>
 585         </tr>
 586         <tr>
 587           <td class="paramkey"></td>
 588           <td></td>
 589           <td class="paramtype">uint32_t&#160;</td>
 590           <td class="paramname"><em>disable_interface_mask</em>&#160;</td>
 591         </tr>
 592         <tr>
 593           <td></td>
 594           <td>)</td>
 595           <td></td><td></td>
 596         </tr>
 597       </table>
 598 </div><div class="memdoc">
 599
 600 <p>Reboot the device into BOOTSEL mode. </p>
 601 <p >This function reboots the device into the BOOTSEL mode ('usb boot").
 602
 603 Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device, and to limit the USB interfaces exposed.</p>
 604 <dl class="params"><dt>Parameters</dt><dd>
 605   <table class="params">
 606     <tr><td class="paramname">usb_activity_gpio_pin_mask</td><td>0 No pins are used as per a cold boot. Otherwise a single bit set indicating which GPIO pin should be set to output and raised whenever there is mass storage activity from the host. </td></tr>
 607     <tr><td class="paramname">disable_interface_mask</td><td>value to control exposed interfaces<ul>
 608 <li>0 To enable both interfaces (as per a cold boot)</li>
 609 <li>1 To disable the USB Mass Storage Interface</li>
 610 <li>2 To disable the USB PICOBOOT Interface </li>
 611 </ul>
 612 </td></tr>
 613   </table>
 614   </dd>
 615 </dl>
 616
 617 </div>
 618 </div>
 619 <a id="ga2b6dcf9d9c60d54a222f7c259c76b4b4" name="ga2b6dcf9d9c60d54a222f7c259c76b4b4"></a>
 620 <h2 class="memtitle"><span class="permalink"><a href="#ga2b6dcf9d9c60d54a222f7c259c76b4b4">&#9670;&nbsp;</a></span>rom_table_code()</h2>
 621
 622 <div class="memitem">
 623 <div class="memproto">
 624 <table class="mlabels">
 625   <tr>
 626   <td class="mlabels-left">
 627       <table class="memname">
 628         <tr>
 629           <td class="memname">static uint32_t rom_table_code </td>
 630           <td>(</td>
 631           <td class="paramtype">uint8_t&#160;</td>
 632           <td class="paramname"><em>c1</em>, </td>
 633         </tr>
 634         <tr>
 635           <td class="paramkey"></td>
 636           <td></td>
 637           <td class="paramtype">uint8_t&#160;</td>
 638           <td class="paramname"><em>c2</em>&#160;</td>
 639         </tr>
 640         <tr>
 641           <td></td>
 642           <td>)</td>
 643           <td></td><td></td>
 644         </tr>
 645       </table>
 646   </td>
 647   <td class="mlabels-right">
 648 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 649   </tr>
 650 </table>
 651 </div><div class="memdoc">
 652
 653 <p>Return a bootrom lookup code based on two ASCII characters. </p>
 654 <p >These codes are uses to lookup data or function addresses in the bootrom</p>
 655 <dl class="params"><dt>Parameters</dt><dd>
 656   <table class="params">
 657     <tr><td class="paramname">c1</td><td>the first character </td></tr>
 658     <tr><td class="paramname">c2</td><td>the second character </td></tr>
 659   </table>
 660   </dd>
 661 </dl>
 662 <dl class="section return"><dt>Returns</dt><dd>the 'code' to use in <a class="el" href="group__pico__bootrom.html#gaaaf61234f389da6444b6479f29616d7d" title="Lookup a bootrom function by its code.">rom_func_lookup()</a> or <a class="el" href="group__pico__bootrom.html#gad3e66e7bcbf0448a0a63cf37dfb4b53c" title="Lookup a bootrom data address by its code.">rom_data_lookup()</a> </dd></dl>
 663
 664 </div>
 665 </div>
 666 </div><!-- contents -->
 667 </div><!-- doc-content -->
 668
 669         <script src="main.js"></script>
 670 </body>
 671 </html>