git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/RISC-V_RV32_SiFive_HiFive1_GCC/freedom-metal/doc/html/devguide/pmps.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
   8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   9     <title>Physical Memory Protection &#8212; Freedom Metal v201905 documentation</title>
  10     <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  12     <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
  13     <script type="text/javascript" src="../_static/jquery.js"></script>
  14     <script type="text/javascript" src="../_static/underscore.js"></script>
  15     <script type="text/javascript" src="../_static/doctools.js"></script>
  16     <link rel="index" title="Index" href="../genindex.html" />
  17     <link rel="search" title="Search" href="../search.html" />
  18     <link rel="next" title="Standard I/O" href="tty.html" />
  19     <link rel="prev" title="Instruction Tightly Integrated Memory" href="itim.html" />
  20
  21   <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  22
  23
  24   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  25
  26   </head><body>
  27
  28
  29     <div class="document">
  30       <div class="documentwrapper">
  31         <div class="bodywrapper">
  32
  33
  34           <div class="body" role="main">
  35
  36   <div class="section" id="physical-memory-protection">
  37 <h1>Physical Memory Protection<a class="headerlink" href="#physical-memory-protection" title="Permalink to this headline">¶</a></h1>
  38 <p>Physical Memory Protection (PMP) is a part of the RISC-V Privileged Architecture
  39 Specification which discribes the interface for a standard RISC-V memory
  40 protection unit.</p>
  41 <p>The PMP defines a finite number of PMP regions which can be individually configured
  42 to enforce access permissions to a range of addresses in memory. Each PMP region
  43 is configurable with the following options:</p>
  44 <dl class="class">
  45 <dt>
  46 <em class="property">struct </em><code class="descname">metal_pmp_config</code><br /></dt>
  47 <dd><p>Configuration for a PMP region. </p>
  48 <div class="breathe-sectiondef docutils container">
  49 <p class="breathe-sectiondef-title rubric">Public Types</p>
  50 <dl class="type">
  51 <dt>
  52 <em class="property">enum </em><code class="descname">metal_pmp_locked</code><br /></dt>
  53 <dd><p>Sets whether the PMP region is locked. </p>
  54 <p><em>Values:</em></p>
  55 <dl class="enumerator">
  56 <dt>
  57 <code class="descname">METAL_PMP_UNLOCKED</code> = 0<br /></dt>
  58 <dd></dd></dl>
  59
  60 <dl class="enumerator">
  61 <dt>
  62 <code class="descname">METAL_PMP_LOCKED</code> = 1<br /></dt>
  63 <dd></dd></dl>
  64
  65 </dd></dl>
  66
  67 </div>
  68 <div class="breathe-sectiondef docutils container">
  69 <p class="breathe-sectiondef-title rubric">Public Members</p>
  70 <dl class="member">
  71 <dt>
  72 int <code class="descname">R</code><br /></dt>
  73 <dd><p>Sets whether reads to the PMP region succeed. </p>
  74 </dd></dl>
  75
  76 <dl class="member">
  77 <dt>
  78 int <code class="descname">W</code><br /></dt>
  79 <dd><p>Sets whether writes to the PMP region succeed. </p>
  80 </dd></dl>
  81
  82 <dl class="member">
  83 <dt>
  84 int <code class="descname">X</code><br /></dt>
  85 <dd><p>Sets whether the PMP region is executable. </p>
  86 </dd></dl>
  87
  88 <dl class="member">
  89 <dt>
  90 <a class="reference internal" href="../apiref/pmp.html#_CPPv322metal_pmp_address_mode" title="metal_pmp_address_mode">metal_pmp_address_mode</a> <code class="descname">A</code><br /></dt>
  91 <dd><p>Sets the addressing mode of the PMP region. </p>
  92 </dd></dl>
  93
  94 </div>
  95 </dd></dl>
  96
  97 <div class="section" id="initializing-the-pmp">
  98 <h2>Initializing the PMP<a class="headerlink" href="#initializing-the-pmp" title="Permalink to this headline">¶</a></h2>
  99 <p>All PMP-related functions first depend on having a handle to the PMP device:</p>
 100 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">metal_pmp</span> <span class="o">*</span><span class="n">pmp</span> <span class="o">=</span> <span class="n">metal_pmp_get_device</span><span class="p">();</span>
 101 <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">pmp</span><span class="p">)</span> <span class="p">{</span>
 102    <span class="cm">/* Failed to get PMP device handle */</span>
 103 <span class="p">}</span>
 104 </pre></div>
 105 </div>
 106 <p>PMP initialization is optional and has the effect of disabling all PMP regions,
 107 if possible:</p>
 108 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">metal_pmp_init</span><span class="p">(</span><span class="n">pmp</span><span class="p">);</span>
 109 </pre></div>
 110 </div>
 111 <p>The number of PMP regions available can be retrieved from the PMP device handle:</p>
 112 <dl class="class">
 113 <dt>
 114 <em class="property">struct </em><code class="descname">metal_pmp</code><br /></dt>
 115 <dd><p>A handle for the PMP device. </p>
 116 </dd></dl>
 117
 118 </div>
 119 <div class="section" id="configuring-a-pmp-region">
 120 <h2>Configuring a PMP Region<a class="headerlink" href="#configuring-a-pmp-region" title="Permalink to this headline">¶</a></h2>
 121 <p>Freedom Metal has a set of APIs for configuring a PMP region. The most generic of these
 122 is</p>
 123 <dl class="function">
 124 <dt id="_CPPv320metal_pmp_set_regionP9metal_pmpj16metal_pmp_config6size_t">
 125 <span id="_CPPv220metal_pmp_set_regionP9metal_pmpj16metal_pmp_config6size_t"></span><span id="metal_pmp_set_region__metal_pmpP.unsigned-i.metal_pmp_config.s"></span><span class="target" id="pmp_8h_1acdbdbc7cc2727d4ae10205617aee3013"></span>int <code class="descname">metal_pmp_set_region</code><span class="sig-paren">(</span><em class="property">struct</em> <a class="reference internal" href="../apiref/pmp.html#_CPPv39metal_pmp" title="metal_pmp">metal_pmp</a> *<em>pmp</em>, unsigned int <em>region</em>, <em class="property">struct</em> <a class="reference internal" href="../apiref/pmp.html#_CPPv316metal_pmp_config" title="metal_pmp_config">metal_pmp_config</a> <em>config</em>, size_t <em>address</em><span class="sig-paren">)</span><br /></dt>
 126 <dd><p>Configure a PMP region. </p>
 127 <p><dl class="docutils">
 128 <dt><strong>Return</strong></dt>
 129 <dd>0 upon success </dd>
 130 <dt><strong>Parameters</strong></dt>
 131 <dd><ul class="breatheparameterlist first last simple">
 132 <li><code class="docutils literal notranslate"><span class="pre">pmp</span></code>: The PMP device handle </li>
 133 <li><code class="docutils literal notranslate"><span class="pre">region</span></code>: The PMP region to configure </li>
 134 <li><code class="docutils literal notranslate"><span class="pre">config</span></code>: The desired configuration of the PMP region </li>
 135 <li><code class="docutils literal notranslate"><span class="pre">address</span></code>: The desired address of the PMP region </li>
 136 </ul>
 137 </dd>
 138 </dl>
 139 </p>
 140 </dd></dl>
 141
 142 <p>This function allows for the configuration of all PMP region settings.</p>
 143 <p>Additional APIs are provided for granularly changing individual PMP region settings.
 144 For example:</p>
 145 <dl class="function">
 146 <dt>
 147 int <code class="descname">metal_pmp_set_address</code><span class="sig-paren">(</span><em class="property">struct</em> <a class="reference internal" href="../apiref/pmp.html#_CPPv39metal_pmp" title="metal_pmp">metal_pmp</a> *<em>pmp</em>, unsigned int <em>region</em>, size_t <em>address</em><span class="sig-paren">)</span><br /></dt>
 148 <dd><p>Set the address for a PMP region. </p>
 149 <p><dl class="docutils">
 150 <dt><strong>Return</strong></dt>
 151 <dd>0 if the address is successfully set </dd>
 152 <dt><strong>Parameters</strong></dt>
 153 <dd><ul class="breatheparameterlist first last simple">
 154 <li><code class="docutils literal notranslate"><span class="pre">pmp</span></code>: The PMP device handle </li>
 155 <li><code class="docutils literal notranslate"><span class="pre">region</span></code>: The PMP region to set </li>
 156 <li><code class="docutils literal notranslate"><span class="pre">address</span></code>: The desired address of the PMP region </li>
 157 </ul>
 158 </dd>
 159 </dl>
 160 </p>
 161 </dd></dl>
 162
 163 <dl class="function">
 164 <dt>
 165 int <code class="descname">metal_pmp_lock</code><span class="sig-paren">(</span><em class="property">struct</em> <a class="reference internal" href="../apiref/pmp.html#_CPPv39metal_pmp" title="metal_pmp">metal_pmp</a> *<em>pmp</em>, unsigned int <em>region</em><span class="sig-paren">)</span><br /></dt>
 166 <dd><p>Lock a PMP region. </p>
 167 <p><dl class="docutils">
 168 <dt><strong>Return</strong></dt>
 169 <dd>0 if the region is successfully locked </dd>
 170 <dt><strong>Parameters</strong></dt>
 171 <dd><ul class="breatheparameterlist first last simple">
 172 <li><code class="docutils literal notranslate"><span class="pre">pmp</span></code>: The PMP device handle </li>
 173 <li><code class="docutils literal notranslate"><span class="pre">region</span></code>: The PMP region to lock </li>
 174 </ul>
 175 </dd>
 176 </dl>
 177 </p>
 178 </dd></dl>
 179
 180 <dl class="function">
 181 <dt>
 182 int <code class="descname">metal_pmp_set_writeable</code><span class="sig-paren">(</span><em class="property">struct</em> <a class="reference internal" href="../apiref/pmp.html#_CPPv39metal_pmp" title="metal_pmp">metal_pmp</a> *<em>pmp</em>, unsigned int <em>region</em>, int <em>W</em><span class="sig-paren">)</span><br /></dt>
 183 <dd><p>Set the writable bit for a PMP region. </p>
 184 <p><dl class="docutils">
 185 <dt><strong>Return</strong></dt>
 186 <dd>0 if the writable bit is successfully set </dd>
 187 <dt><strong>Parameters</strong></dt>
 188 <dd><ul class="breatheparameterlist first last simple">
 189 <li><code class="docutils literal notranslate"><span class="pre">pmp</span></code>: The PMP device handle </li>
 190 <li><code class="docutils literal notranslate"><span class="pre">region</span></code>: The PMP region to set </li>
 191 <li><code class="docutils literal notranslate"><span class="pre">W</span></code>: The desired value of the writable bit </li>
 192 </ul>
 193 </dd>
 194 </dl>
 195 </p>
 196 </dd></dl>
 197
 198 <p>Additional documentation for this API is provided in <a class="reference internal" href="../apiref/pmp.html"><span class="doc">the PMP API reference</span></a>.</p>
 199 <p>The RISC-V specification allows implementation of PMP to hard-wire the configuration
 200 values of PMP regions. In these cases, attempts to configure these PMP regions will
 201 fail.</p>
 202 </div>
 203 <div class="section" id="handling-pmp-access-faults">
 204 <h2>Handling PMP Access Faults<a class="headerlink" href="#handling-pmp-access-faults" title="Permalink to this headline">¶</a></h2>
 205 <p>Attempted memory accesses which the PMP is configured to prevent trigger a
 206 CPU exception. These exceptions can be handled by installing a CPU exception
 207 handler for exception codes related to memory access faults.</p>
 208 <p>Additional documentation about creating and registering exception handlers can
 209 be found in <a class="reference internal" href="exceptions.html"><span class="doc">the Exception Handlers Developer Guide</span></a>.</p>
 210 </div>
 211 <div class="section" id="additional-documentation">
 212 <h2>Additional Documentation<a class="headerlink" href="#additional-documentation" title="Permalink to this headline">¶</a></h2>
 213 <p>Additional documentation about the Physical Memory Protection system and fault
 214 handling on RISC-V systems can be found in
 215 <a class="reference external" href="https://riscv.org/specifications/privileged-isa/">The RISC-V Privileged ISA Specification v1.10</a>.</p>
 216 </div>
 217 </div>
 218
 219
 220           </div>
 221
 222         </div>
 223       </div>
 224       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 225         <div class="sphinxsidebarwrapper">
 226 <h1 class="logo"><a href="../index.html">Freedom Metal</a></h1>
 227
 228
 229
 230
 231
 232
 233
 234
 235 <h3>Navigation</h3>
 236 <ul class="current">
 237 <li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction to Freedom Metal</a></li>
 238 <li class="toctree-l1 current"><a class="reference internal" href="../devguide.html">Developer Guide</a><ul class="current">
 239 <li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exception Handlers</a></li>
 240 <li class="toctree-l2"><a class="reference internal" href="fe310-g000-pll.html">FE310-G00 PLL</a></li>
 241 <li class="toctree-l2"><a class="reference internal" href="interrupts.html">Interrupt Handlers</a></li>
 242 <li class="toctree-l2"><a class="reference internal" href="itim.html">Instruction Tightly Integrated Memory</a></li>
 243 <li class="toctree-l2 current"><a class="current reference internal" href="#">Physical Memory Protection</a></li>
 244 <li class="toctree-l2"><a class="reference internal" href="tty.html">Standard I/O</a></li>
 245 </ul>
 246 </li>
 247 <li class="toctree-l1"><a class="reference internal" href="../api.html">API Reference</a></li>
 248 </ul>
 249
 250 <div class="relations">
 251 <h3>Related Topics</h3>
 252 <ul>
 253   <li><a href="../index.html">Documentation overview</a><ul>
 254   <li><a href="../devguide.html">Developer Guide</a><ul>
 255       <li>Previous: <a href="itim.html" title="previous chapter">Instruction Tightly Integrated Memory</a></li>
 256       <li>Next: <a href="tty.html" title="next chapter">Standard I/O</a></li>
 257   </ul></li>
 258   </ul></li>
 259 </ul>
 260 </div>
 261 <div id="searchbox" style="display: none" role="search">
 262   <h3>Quick search</h3>
 263     <div class="searchformwrapper">
 264     <form class="search" action="../search.html" method="get">
 265       <input type="text" name="q" />
 266       <input type="submit" value="Go" />
 267       <input type="hidden" name="check_keywords" value="yes" />
 268       <input type="hidden" name="area" value="default" />
 269     </form>
 270     </div>
 271 </div>
 272 <script type="text/javascript">$('#searchbox').show(0);</script>
 273         </div>
 274       </div>
 275       <div class="clearer"></div>
 276     </div>
 277     <div class="footer">
 278       &copy;2019, SiFive Inc..
 279
 280       |
 281       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.5</a>
 282       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.11</a>
 283
 284       |
 285       <a href="../_sources/devguide/pmps.rst.txt"
 286           rel="nofollow">Page source</a>
 287     </div>
 288
 289
 290
 291
 292   </body>
 293 </html>