doc/manual.html in ruby-vpi-12.0.2 vs doc/manual.html in ruby-vpi-12.1.0
- old
+ new
@@ -88,13 +88,23 @@
<li><a href="#usage.tutorial.test-proto">Verify the prototype</a></li>
<li><a href="#usage.tutorial.implement-design">Implement the design</a></li>
<li><a href="#usage.tutorial.test-design">Verify the design</a></li>
</ul>
</li>
- <li><a href="#usage.examples">Examples</a></li>
+ <li><a href="#usage.test-runner">Test runner</a>
+ <ul>
+ <li><a href="#usage.test-runner.env-vars">Environment variables</a></li>
</ul>
</li>
+ <li><a href="#usage.debugger">Interactive debugger</a>
+ <ul>
+ <li><a href="#usage.debugger.init">Advanced initialization</a></li>
+ </ul>
+ </li>
+ <li><a href="#usage.examples">Sample tests</a></li>
+ </ul>
+ </li>
<li><a href="#hacking">Hacking</a>
<ul>
<li><a href="#hacking.release-packages">Building release packages</a></li>
</ul>
</li>
@@ -192,10 +202,12 @@
<li><a href="#fig..test-proto.rspec">Running a test with specification in rSpec format</a></li>
<li><a href="#fig..test-proto.unit-test">Running a test with specification in xUnit format</a></li>
<li><a href="#fig..counter.v_impl">Implementation of a simple up-counter with synchronous reset</a></li>
<li><a href="#fig..test-design.rspec">Running a test with specification in rSpec format</a></li>
<li><a href="#fig..test-design.unit-test">Running a test with specification in xUnit format</a></li>
+ <li><a href="#example13">Seeing what a test runner can do</a></li>
+ <li><a href="#example14">Running a test with environment variables</a></li>
<li><a href="#ex..TestFoo">Part of a bench which instantiates a Verilog design</a></li>
<li><a href="#ex..TestFoo_bad">Bad design with unconnected registers</a></li>
<li><a href="#ex..TestFoo_fix">Fixed design with wired registers</a></li>
</ol>
</div>
@@ -205,11 +217,11 @@
<p>Suraj N. Kurapati</p>
- <p>Mon Dec 18 15:23:49 <span class="caps">PST 2006</span></p>
+ <p>Fri Dec 22 21:43:06 <span class="caps">PST 2006</span></p>
</div>
<h2 id="terms">Terms</h2>
@@ -998,11 +1010,11 @@
<li><tt>doc</tt> contains user documentation in various formats.</li>
<li><tt>ref</tt> contains reference <span class="caps">API</span> documentation in <span class="caps">HTML</span> format.</li>
<li><tt>ext</tt> contains source code, written in the C language, for the <a href="#background.org">core of Ruby-VPI</a>.</li>
<li><tt>lib</tt> contains Ruby libraries provided by Ruby-VPI.</li>
<li><tt>bin</tt> contains various tools. See <a href="#usage.tools">the section named “Tools”</a> for more information.</li>
- <li><tt>samp</tt> contains example tests. See <a href="#usage.examples">the section named “Examples”</a> for more information.</li>
+ <li><tt>samp</tt> contains example tests. See <a href="#usage.examples">the section named “Sample tests”</a> for more information.</li>
</ul>
<h2 id="setup.reqs">Requirements</h2>
@@ -1040,14 +1052,18 @@
</div>
</div>
-* <strong>make</strong>
- – any distribution should be acceptable.
<ul>
+ <li><strong>make</strong>
+ – any distribution should be acceptable.</li>
+ </ul>
+
+
+ <ul>
<li>C compiler
– the <a href="http://www.gnu.org/software/gcc/" title="GCC"><span class="caps">GNU</span> Compiler Collection</a> is preferred, but any C compiler should be acceptable.</li>
</ul>
@@ -1089,11 +1105,11 @@
<h2 id="setup.installation">Installation</h2>
- <p>Once you have satisfied the <a href="#setup.reqs">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a “gems” subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
+ <p>Once you have satisfied the <a href="#setup.reqs">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
<pre>
$ gem env gemdir
/usr/lib/ruby/gems/1.8
@@ -1761,10 +1777,39 @@
</div>
</div>
In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is <em>not</em> specified while running the test, so that our design, instead of our prototype, is verified against our specification. You can also achieve this effect by assigning an empty value to <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code>, or by using your shell’s <strong>unset</strong> command. Finally, the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>, denoted by <em>cver</em>, is used to run the simulation.
+ <h2 id="usage.test-runner">Test runner</h2>
+
+
+ <p>A test runner is a file, generated by the <a href="#usage.tools.generate-test">automated test generator</a>, whose name ends with <tt>.rake</tt>. It helps you run generated tests—you can think of it as a <em>makefile</em> if you are familiar with C programming in a <span class="caps">UNIX</span> environment.</p>
+
+
+<div class="formal">
+
+<div class="example" id="example13">
+
+ <p class="title">Example 13. Seeing what a test runner can do</p>
+
+
+When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f some_test_runner.rake
+
+(in /home/sun/src/ruby-vpi/doc)
+rake clean # Remove any temporary products.
+rake clobber # Remove any generated file.
+rake cver # Simulate with GPL Cver.
+rake default # Show a list of available tasks.
+rake ivl # Simulate with Icarus Verilog.
+rake vcs # Simulate with Synopsys VCS.
+rake vsim # Simulate with Mentor Modelsim.
+</pre>
+
+</div>
+
+</div>
<div class="admonition">
<div class="tip" id="tip4">
<p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
@@ -1786,16 +1831,87 @@
</div>
</div>
- <h2 id="usage.examples">Examples</h2>
+ <h3 id="usage.test-runner.env-vars">Environment variables</h3>
- <p>The <tt>samp</tt> directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.</p>
+ <p>Test runners support the following <em>environment</em> variables, which allow you to easily change the behavior of the test runner.</p>
+ <ul>
+ <li><code class="code"><span style="color:#036; font-weight:bold">COVERAGE</span></code> enables code coverage analysis and generation of code coverage reports.</li>
+ <li><code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> enables the <a href="#usage.debugger">interactive debugger</a> in its <a href="http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging">post-mortem debugging mode</a>.</li>
+ <li><code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> enables the Ruby prototype for the design under test.</li>
+ </ul>
+
+
+ <p>To activate these variables, simply assign a non-empty value to them. For example, <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=<span style="color:#00D; font-weight:bold">1</span></code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=yes</code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=foo_bar_baz</code> all activate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+
+
+ <p>To deactivate these variables, simply assign an <em>empty</em> value to them, <strong>unset</strong> them in your shell, or do not specify them as command-line arguments to rake. For example, both <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=</code> dectivates the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+
+
+ <p>In addition, you can specify variable assignments as arguments to the <strong>rake</strong> command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
+$ DEBUG=1
+$ export DEBUG
+$ rake
+</pre> in Bourne shell or <pre>
+% setenv DEBUG 1
+% rake
+</pre> in C shell.</p>
+
+
+<div class="formal">
+
+<div class="example" id="example14">
+
+ <p class="title">Example 14. Running a test with environment variables</p>
+
+
+Here we enable the prototype and code coverage analysis:
+<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+
+Here we <em>disable</em> the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
+<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+
+</div>
+
+</div>
+
+ <h2 id="usage.debugger">Interactive debugger</h2>
+
+
+ <p>The <a href="http://www.datanoise.com/articles/category/ruby-debug">ruby-debug project</a> serves as the interactive debugger for Ruby-VPI.</p>
+
+
+ <ol>
+ <li>Enable the debugger by activating the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable (see <a href="#usage.test-runner">the section named “Test runner”</a> for details).</li>
+ <li>Put the <code class="code">debugger</code> command in your code—anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.</li>
+ </ol>
+
+
+ <h3 id="usage.debugger.init">Advanced initialization</h3>
+
+
+ <p>By default, Ruby-VPI enables the debugger by invoking the <code class="code"><span style="color:#036; font-weight:bold">Debugger</span>.start</code> method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an <span class="caps">IDE</span> (see <a href="http://www.datanoise.com/articles/category/ruby-debug">the ruby-debug documentation</a> for details), then:</p>
+
+
+ <ol>
+ <li>Deactivate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable.</li>
+ <li>Put your own code, which initializes the debugger, above the <code class="code"><span style="color:#036; font-weight:bold">RubyVpi</span>.init_bench</code> line in your generated <tt>spec.rb</tt> file.</li>
+ </ol>
+
+
+ <h2 id="usage.examples">Sample tests</h2>
+
+
+ <p>The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.</p>
+
+
<h1 id="hacking">Hacking</h1>
<h2 id="hacking.release-packages">Building release packages</h2>
@@ -1881,11 +1997,11 @@
<div class="formal">
<div class="example" id="ex..TestFoo">
- <p class="title">Example 13. Part of a bench which instantiates a Verilog design</p>
+ <p class="title">Example 15. Part of a bench which instantiates a Verilog design</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
@@ -1911,11 +2027,11 @@
<div class="formal">
<div class="example" id="ex..TestFoo_bad">
- <p class="title">Example 14. Bad design with unconnected registers</p>
+ <p class="title">Example 16. Bad design with unconnected registers</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
@@ -1930,10 +2046,10 @@
</div>
<div class="formal">
<div class="example" id="ex..TestFoo_fix">
- <p class="title">Example 15. Fixed design with wired registers</p>
+ <p class="title">Example 17. Fixed design with wired registers</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;