git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/RISC-V_RV32_SiFive_HiFive1_GCC/freedom-metal/doc/html/devguide/exceptions.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>Exception Handlers &#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="FE310-G00 PLL" href="fe310-g000-pll.html" />
  19     <link rel="prev" title="Developer Guide" href="../devguide.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="exception-handlers">
  37 <h1>Exception Handlers<a class="headerlink" href="#exception-handlers" title="Permalink to this headline">¶</a></h1>
  38 <p>CPU exceptions are the mechanism by which various execution and memory system
  39 errors are handled. When an exception occurs, Freedom Metal will call the
  40 corresponding exception handler function, if one has been registered by the
  41 application.</p>
  42 <div class="section" id="initializing-the-cpu">
  43 <h2>Initializing the CPU<a class="headerlink" href="#initializing-the-cpu" title="Permalink to this headline">¶</a></h2>
  44 <p>When the user application enters the <code class="docutils literal notranslate"><span class="pre">main()</span></code> function, the Freedom Metal
  45 framework has not yet performed the initialization necessary to register
  46 exception handlers. If this initialization is not performed before an exception
  47 occurs, any exception will cause the CPU to spin in a tight loop until reset.</p>
  48 <p>To initialize the Freedom Metal exception handlers, initialize CPU interrupts:</p>
  49 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">metal_cpu</span> <span class="o">*</span><span class="n">cpu0</span> <span class="o">=</span> <span class="n">metal_get_cpu</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
  50 <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">cpu</span><span class="p">)</span> <span class="p">{</span>
  51    <span class="cm">/* There was an error acquiring the CPU hart 0 handle */</span>
  52 <span class="p">}</span>
  53
  54 <span class="k">struct</span> <span class="n">metal_interrupt</span> <span class="o">*</span><span class="n">cpu_int</span> <span class="o">=</span> <span class="n">metal_cpu_interrupt_controller</span><span class="p">(</span><span class="n">cpu0</span><span class="p">);</span>
  55 <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">cpu_int</span><span class="p">)</span> <span class="p">{</span>
  56    <span class="cm">/* There was an error acquiring the CPU interrupt controller */</span>
  57 <span class="p">}</span>
  58
  59 <span class="n">metal_interrupt_init</span><span class="p">(</span><span class="n">cpu_int</span><span class="p">);</span>
  60 </pre></div>
  61 </div>
  62 <p>The Freedom Metal interrupt API is further documented in <a class="reference internal" href="interrupts.html"><span class="doc">Interrupt Handlers</span></a>
  63 and <a class="reference internal" href="../apiref/interrupt.html"><span class="doc">Interrupts</span></a>.</p>
  64 </div>
  65 <div class="section" id="defining-an-exception-handler">
  66 <h2>Defining an Exception Handler<a class="headerlink" href="#defining-an-exception-handler" title="Permalink to this headline">¶</a></h2>
  67 <p>Exception handlers must conform to the following function signature:</p>
  68 <dl class="type">
  69 <dt>
  70 <em class="property">typedef </em>void (*<code class="descname">metal_exception_handler_t</code>)<span class="sig-paren">(</span><em class="property">struct</em> <a class="reference internal" href="../apiref/cpu.html#_CPPv39metal_cpu" title="metal_cpu">metal_cpu</a> *cpu, int ecode<span class="sig-paren">)</span><br /></dt>
  71 <dd><p>Function signature for exception handlers. </p>
  72 </dd></dl>
  73
  74 <p>Therefore, an example exception handler might look like:</p>
  75 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">my_exception_handler</span><span class="p">(</span><span class="k">struct</span> <span class="n">metal_cpu</span> <span class="o">*</span><span class="n">cpu</span><span class="p">,</span> <span class="kt">int</span> <span class="n">ecode</span><span class="p">)</span> <span class="p">{</span>
  76    <span class="cm">/* Contents of handler */</span>
  77 <span class="p">}</span>
  78 </pre></div>
  79 </div>
  80 </div>
  81 <div class="section" id="registering-an-exception-handler">
  82 <h2>Registering an Exception Handler<a class="headerlink" href="#registering-an-exception-handler" title="Permalink to this headline">¶</a></h2>
  83 <p>Exception handlers are registered with a given CPU hart for an individual exception
  84 code.</p>
  85 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cm">/* CPU Hart 0&#39;s interrupt controller must be initialized</span>
  86 <span class="cm"> * if it is not already */</span>
  87 <span class="k">struct</span> <span class="n">metal_cpu</span> <span class="o">*</span><span class="n">cpu0</span> <span class="o">=</span> <span class="n">metal_get_cpu</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
  88
  89 <span class="kt">int</span> <span class="n">rc</span> <span class="o">=</span> <span class="n">metal_cpu_exception_register</span><span class="p">(</span><span class="n">cpu0</span><span class="p">,</span>
  90             <span class="o">&lt;</span><span class="n">my_ecode</span><span class="o">&gt;</span><span class="p">,</span> <span class="cm">/* Set to your desired value */</span>
  91             <span class="n">my_exception_handler</span><span class="p">);</span>
  92 <span class="k">if</span><span class="p">(</span><span class="n">rc</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
  93    <span class="cm">/* Failed to register exception handler */</span>
  94 <span class="p">}</span>
  95 </pre></div>
  96 </div>
  97 <p>A single exception handler may be used for multiple exception codes. For this reason,
  98 exception handlers receive the exception code as the <code class="docutils literal notranslate"><span class="pre">ecode</span></code> parameter and may use
  99 this to determine how to handle the exception.</p>
 100 </div>
 101 <div class="section" id="returing-execution-after-a-faulting-instruction">
 102 <h2>Returing Execution after a Faulting Instruction<a class="headerlink" href="#returing-execution-after-a-faulting-instruction" title="Permalink to this headline">¶</a></h2>
 103 <p>The default behavior of a RISC-V CPU is to return execution to the faulting instruction.
 104 If this is not the desired behavior, execution can be returned to the instruction after
 105 the faulting instruction using the following method:</p>
 106 <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">return_after_fault</span><span class="p">(</span><span class="k">struct</span> <span class="n">metal_cpu</span> <span class="o">*</span><span class="n">cpu</span><span class="p">,</span> <span class="kt">int</span> <span class="n">ecode</span><span class="p">)</span>
 107 <span class="p">{</span>
 108    <span class="cm">/* Get the faulting instruction address */</span>
 109    <span class="kt">uintptr_t</span> <span class="n">epc</span> <span class="o">=</span> <span class="n">metal_cpu_get_exception_pc</span><span class="p">(</span><span class="n">cpu</span><span class="p">);</span>
 110
 111    <span class="cm">/* Get the length of the faulting instruction */</span>
 112    <span class="kt">size_t</span> <span class="n">len</span> <span class="o">=</span> <span class="n">metal_cpu_get_instruction_length</span><span class="p">(</span><span class="n">cpu</span><span class="p">,</span> <span class="n">epc</span><span class="p">);</span>
 113
 114    <span class="cm">/* Advance stored exception program counter by the</span>
 115 <span class="cm">    * instruction length */</span>
 116    <span class="n">metal_cpu_set_exception_pc</span><span class="p">(</span><span class="n">cpu</span><span class="p">,</span> <span class="n">epc</span> <span class="o">+</span> <span class="n">len</span><span class="p">);</span>
 117 <span class="p">}</span>
 118 </pre></div>
 119 </div>
 120 </div>
 121 <div class="section" id="additional-documentation">
 122 <h2>Additional Documentation<a class="headerlink" href="#additional-documentation" title="Permalink to this headline">¶</a></h2>
 123 <p>Additional documentation for the exception handler API can be found in <a class="reference internal" href="../apiref/cpu.html"><span class="doc">The CPU API Reference</span></a>.</p>
 124 </div>
 125 </div>
 126
 127
 128           </div>
 129
 130         </div>
 131       </div>
 132       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 133         <div class="sphinxsidebarwrapper">
 134 <h1 class="logo"><a href="../index.html">Freedom Metal</a></h1>
 135
 136
 137
 138
 139
 140
 141
 142
 143 <h3>Navigation</h3>
 144 <ul class="current">
 145 <li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction to Freedom Metal</a></li>
 146 <li class="toctree-l1 current"><a class="reference internal" href="../devguide.html">Developer Guide</a><ul class="current">
 147 <li class="toctree-l2 current"><a class="current reference internal" href="#">Exception Handlers</a></li>
 148 <li class="toctree-l2"><a class="reference internal" href="fe310-g000-pll.html">FE310-G00 PLL</a></li>
 149 <li class="toctree-l2"><a class="reference internal" href="interrupts.html">Interrupt Handlers</a></li>
 150 <li class="toctree-l2"><a class="reference internal" href="itim.html">Instruction Tightly Integrated Memory</a></li>
 151 <li class="toctree-l2"><a class="reference internal" href="pmps.html">Physical Memory Protection</a></li>
 152 <li class="toctree-l2"><a class="reference internal" href="tty.html">Standard I/O</a></li>
 153 </ul>
 154 </li>
 155 <li class="toctree-l1"><a class="reference internal" href="../api.html">API Reference</a></li>
 156 </ul>
 157
 158 <div class="relations">
 159 <h3>Related Topics</h3>
 160 <ul>
 161   <li><a href="../index.html">Documentation overview</a><ul>
 162   <li><a href="../devguide.html">Developer Guide</a><ul>
 163       <li>Previous: <a href="../devguide.html" title="previous chapter">Developer Guide</a></li>
 164       <li>Next: <a href="fe310-g000-pll.html" title="next chapter">FE310-G00 PLL</a></li>
 165   </ul></li>
 166   </ul></li>
 167 </ul>
 168 </div>
 169 <div id="searchbox" style="display: none" role="search">
 170   <h3>Quick search</h3>
 171     <div class="searchformwrapper">
 172     <form class="search" action="../search.html" method="get">
 173       <input type="text" name="q" />
 174       <input type="submit" value="Go" />
 175       <input type="hidden" name="check_keywords" value="yes" />
 176       <input type="hidden" name="area" value="default" />
 177     </form>
 178     </div>
 179 </div>
 180 <script type="text/javascript">$('#searchbox').show(0);</script>
 181         </div>
 182       </div>
 183       <div class="clearer"></div>
 184     </div>
 185     <div class="footer">
 186       &copy;2019, SiFive Inc..
 187
 188       |
 189       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.5</a>
 190       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.11</a>
 191
 192       |
 193       <a href="../_sources/devguide/exceptions.rst.txt"
 194           rel="nofollow">Page source</a>
 195     </div>
 196
 197
 198
 199
 200   </body>
 201 </html>