doc/manual.html in ruby-vpi-13.0.0 vs doc/manual.html in ruby-vpi-14.0.0
- old
+ new
@@ -10,166 +10,169 @@
<div id="navigation">
<p><a href="readme.html"><img src="images/home.png" title="project home" alt="project home" /></a></p>
<h1>Contents</h1>
<ul>
- <li><a href="#anchor5">Ruby-VPI user manual</a>
+ <li>1 <a href="#anchor4">Ruby-VPI user manual</a>
<ul>
- <li><a href="#terms">Terms</a></li>
+ <li>1.1 <a href="#terms">Terms</a></li>
</ul>
</li>
- <li><a href="#intro">Introduction</a>
+ <li>2 <a href="#intro">Introduction</a>
<ul>
- <li><a href="#intro.features">Features</a>
+ <li>2.1 <a href="#intro.features">Features</a>
<ul>
- <li><a href="#intro.applications">Applications</a></li>
- <li><a href="#intro.appetizers">Appetizers</a></li>
+ <li>2.1.1 <a href="#anchor5">Portable</a></li>
+ <li>2.1.2 <a href="#anchor6">Agile</a></li>
+ <li>2.1.3 <a href="#anchor7">Powerful</a></li>
+ <li>2.1.4 <a href="#anchor8">Free</a></li>
</ul>
</li>
- <li><a href="#intro.license">License</a></li>
- <li><a href="#intro.related-works">Related works</a>
+ <li>2.2 <a href="#intro.applications">Applications</a></li>
+ <li>2.3 <a href="#intro.appetizers">Appetizers</a></li>
+ <li>2.4 <a href="#intro.license">License</a></li>
+ <li>2.5 <a href="#intro.related-works">Related works</a>
<ul>
- <li><a href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li>
+ <li>2.5.1 <a href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li>
</ul>
</li>
</ul>
</li>
- <li><a href="#background">Background</a>
+ <li>3 <a href="#background">Background</a>
<ul>
- <li><a href="#background.methodology">Methodology</a></li>
- <li><a href="#background.vocab">Terminology</a></li>
- <li><a href="#background.org">Organization</a>
+ <li>3.1 <a href="#background.methodology">Methodology</a></li>
+ <li>3.2 <a href="#background.vocab">Terminology</a></li>
+ <li>3.3 <a href="#background.org">Organization</a></li>
+ <li>3.4 <a href="#background.relay">Ruby/Verilog interaction</a></li>
+ </ul>
+ </li>
+ <li>4 <a href="#setup">Setup</a>
<ul>
- <li><a href="#background.org.vpi">Interface to <span class="caps">VPI</span></a>
+ <li>4.1 <a href="#setup.manifest">Manifest</a></li>
+ <li>4.2 <a href="#setup.reqs">Requirements</a></li>
+ <li>4.3 <a href="#setup.recom">Recommendations</a>
<ul>
- <li><a href="#background.org.vpi.util"><span class="caps">VPI</span> utility layer</a></li>
+ <li>4.3.1 <a href="#setup.recom.merger">Text merging tool</a></li>
</ul>
</li>
- </ul>
- </li>
- <li><a href="#background.running-tests">Running a test</a>
+ <li>4.4 <a href="#setup.installation">Installation</a>
<ul>
- <li><a href="#background.running-tests.init">Initialization</a></li>
- <li><a href="#background.running-tests.exec">Execution</a></li>
+ <li>4.4.1 <a href="#setup.installation.windows">Installing on Windows</a></li>
</ul>
</li>
+ <li>4.5 <a href="#setup.maintenance">Maintenance</a></li>
</ul>
</li>
- <li><a href="#setup">Setup</a>
+ <li>5 <a href="#usage">Usage</a>
<ul>
- <li><a href="#setup.manifest">Manifest</a></li>
- <li><a href="#setup.reqs">Requirements</a></li>
- <li><a href="#setup.recom">Recommendations</a>
+ <li>5.1 <a href="#usage.vpi"><span class="caps">VPI</span> in Ruby</a>
<ul>
- <li><a href="#setup.recom.merger">Text merging tool</a></li>
- </ul>
- </li>
- <li><a href="#setup.installation">Installation</a>
+ <li>5.1.1 <a href="#usage.vpi.handles">Handles</a>
<ul>
- <li><a href="#setup.installation.windows">Installing on Windows</a></li>
+ <li>5.1.1.1 <a href="#anchor9">Accessing a handle’s relatives</a></li>
+ <li>5.1.1.2 <a href="#anchor10">Accessing a handle’s properties</a></li>
</ul>
</li>
- <li><a href="#setup.maintenance">Maintenance</a></li>
+ <li>5.1.2 <a href="#usage.vpi.callbacks">Callbacks</a></li>
</ul>
</li>
- <li><a href="#usage">Usage</a>
+ <li>5.2 <a href="#usage.debugger">Debugging</a>
<ul>
- <li><a href="#usage.tools">Tools</a>
- <ul>
- <li><a href="#usage.tools.generate-test">Automated test generation</a></li>
- <li><a href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li>
+ <li>5.2.1 <a href="#usage.debugger.init">Advanced initialization</a></li>
</ul>
</li>
- <li><a href="#usage.tutorial">Tutorial</a>
+ <li>5.3 <a href="#usage.test-runner">Test runner</a>
<ul>
- <li><a href="#usage.tutorial.declare-design">Start with a design</a></li>
- <li><a href="#usage.tutorial.generate-test">Generate a test</a></li>
- <li><a href="#usage.tutorial.specification">Specify your expectations</a></li>
- <li><a href="#usage.tutorial.implement-proto">Implement the prototype</a></li>
- <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>
+ <li>5.3.1 <a href="#usage.test-runner.env-vars">Environment variables</a></li>
</ul>
</li>
- <li><a href="#usage.test-runner">Test runner</a>
+ <li>5.4 <a href="#usage.examples">Sample tests</a></li>
+ <li>5.5 <a href="#usage.tools">Tools</a>
<ul>
- <li><a href="#usage.test-runner.env-vars">Environment variables</a></li>
+ <li>5.5.1 <a href="#usage.tools.generate-test">Automated test generation</a></li>
+ <li>5.5.2 <a href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li>
</ul>
</li>
- <li><a href="#usage.debugger">Interactive debugger</a>
+ <li>5.6 <a href="#usage.tutorial">Tutorial</a>
<ul>
- <li><a href="#usage.debugger.init">Advanced initialization</a></li>
+ <li>5.6.1 <a href="#usage.tutorial.declare-design">Start with a design</a></li>
+ <li>5.6.2 <a href="#usage.tutorial.generate-test">Generate a test</a></li>
+ <li>5.6.3 <a href="#usage.tutorial.specification">Specify your expectations</a></li>
+ <li>5.6.4 <a href="#usage.tutorial.implement-proto">Implement the prototype</a></li>
+ <li>5.6.5 <a href="#usage.tutorial.test-proto">Verify the prototype</a></li>
+ <li>5.6.6 <a href="#usage.tutorial.implement-design">Implement the design</a></li>
+ <li>5.6.7 <a href="#usage.tutorial.test-design">Verify the design</a></li>
</ul>
</li>
- <li><a href="#usage.examples">Sample tests</a></li>
</ul>
</li>
- <li><a href="#hacking">Hacking</a>
+ <li>6 <a href="#hacking">Hacking</a>
<ul>
- <li><a href="#hacking.release-packages">Building release packages</a></li>
+ <li>6.1 <a href="#hacking.release-packages">Building release packages</a></li>
</ul>
</li>
- <li><a href="#problems">Known problems</a>
+ <li>7 <a href="#problems">Known problems</a>
<ul>
- <li><a href="#problems.ruby">Ruby</a>
+ <li>7.1 <a href="#problems.ruby">Ruby</a>
<ul>
- <li><a href="#problems.ruby.SystemStackError">SystemStackError</a></li>
- <li><a href="#problems.ruby.xUnit">test/unit</a></li>
+ <li>7.1.1 <a href="#problems.ruby.SystemStackError">SystemStackError</a></li>
+ <li>7.1.2 <a href="#problems.ruby.xUnit">test/unit</a></li>
</ul>
</li>
- <li><a href="#problem.ivl">Icarus Verilog</a>
+ <li>7.2 <a href="#problem.ivl">Icarus Verilog</a>
<ul>
- <li><a href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a>
+ <li>7.2.1 <a href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a>
<ul>
- <li><a href="#problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</a></li>
- <li><a href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li>
+ <li>7.2.1.1 <a href="#problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</a></li>
+ <li>7.2.1.2 <a href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li>
</ul>
</li>
- <li><a href="#problems.ivl.vpi_reset">Vpi::reset</a></li>
+ <li>7.2.2 <a href="#problems.ivl.vpi_reset">Vpi::reset</a></li>
</ul>
</li>
- <li><a href="#problems.vsim">Mentor Modelsim</a>
+ <li>7.3 <a href="#problems.vsim">Mentor Modelsim</a>
<ul>
- <li><a href="#problems.vsim.ruby_run">ruby_run();</a></li>
+ <li>7.3.1 <a href="#problems.vsim.ruby_run">ruby_run();</a></li>
</ul>
</li>
</ul>
</li>
- <li><a href="#glossary">Glossary</a>
+ <li>8 <a href="#glossary">Glossary</a>
<ul>
- <li><a href="#glossary.bench">Bench</a></li>
- <li><a href="#glossary.BDD" title="BDD">Behavior driven development</a></li>
- <li><a href="#glossary.design">Design</a></li>
- <li><a href="#glossary.expectation">Expectation</a></li>
- <li><a href="#glossary.handle">Handle</a></li>
- <li><a href="#glossary.rake">Rake</a></li>
- <li><a href="#glossary.rspec">rSpec</a></li>
- <li><a href="#glossary.specification">Specification</a></li>
- <li><a href="#glossary.TDD" title="TDD">Test driven development</a></li>
- <li><a href="#glossary.test">Test</a></li>
- <li><a href="#glossary.test_bench">Test bench</a></li>
+ <li>8.1 <a href="#glossary.bench">Bench</a></li>
+ <li>8.2 <a href="#glossary.BDD" title="BDD">Behavior driven development</a></li>
+ <li>8.3 <a href="#glossary.design">Design</a></li>
+ <li>8.4 <a href="#glossary.expectation">Expectation</a></li>
+ <li>8.5 <a href="#glossary.handle">Handle</a></li>
+ <li>8.6 <a href="#glossary.rake">Rake</a></li>
+ <li>8.7 <a href="#glossary.rspec">rSpec</a></li>
+ <li>8.8 <a href="#glossary.specification">Specification</a></li>
+ <li>8.9 <a href="#glossary.TDD" title="TDD">Test driven development</a></li>
+ <li>9.0 <a href="#glossary.test">Test</a></li>
+ <li>9.1 <a href="#glossary.test_bench">Test bench</a></li>
</ul></li>
</ul>
<h1>Admonitions</h1>
<h2>Tips</h2>
<ol>
<li><a href="#tip1">Add support for your Verilog simulator</a></li>
- <li><a href="#tip2">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
- <li><a href="#tip3">What can the test runner do?</a></li>
- <li><a href="#tip4">Running multiple tests at once.</a></li>
+ <li><a href="#tip2">Running multiple tests at once.</a></li>
+ <li><a href="#tip3">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
+ <li><a href="#tip4">What can the test runner do?</a></li>
</ol>
<h2>Notes</h2>
<ol>
<li><a href="#note1">note1</a></li>
<li><a href="#note2">Undefined symbols in Windows</a></li>
<li><a href="#note3">note3</a></li>
<li><a href="#note4">note4</a></li>
- <li><a href="#note5">Fixed in 2.0.0.</a></li>
+ <li><a href="#note5">note5</a></li>
<li><a href="#note6">Fixed in 2.0.0.</a></li>
<li><a href="#note7">Fixed in 2.0.0.</a></li>
+ <li><a href="#note8">Fixed in 2.0.0.</a></li>
</ol>
<h2>Importants</h2>
<ol>
<li><a href="#important1">Before we continue…</a></li>
<li><a href="#important2">Before we continue…</a></li>
@@ -180,21 +183,24 @@
<h2>Figures</h2>
<ol>
<li><a href="#fig..organization">Overall organization of a test</a></li>
<li><a href="#fig..organization.detail">Detailed organization of a test</a></li>
- <li><a href="#figure3">Parts of speech for accessing a handle’s <span class="caps">VPI</span> properties</a></li>
- <li><a href="#fig..ruby_init">Initialization of a test</a></li>
- <li><a href="#fig..ruby_relay">Execution of a test</a></li>
+ <li><a href="#fig..ruby_relay">Interaction between Ruby and Verilog</a></li>
+ <li><a href="#figure4">Method naming format for accessing a handle’s properties</a></li>
+ <li><a href="#figure5">Output from <xref#ex..callback></a></li>
</ol>
<h2>Tables</h2>
<ol>
- <li><a href="#table1">Possible accessors and their implications</a></li>
+ <li><a href="#tbl..accessors">Possible accessors and their implications</a></li>
</ol>
<h2>Examples</h2>
<ol>
- <li><a href="#example1">Examples of accessing a handle’s <span class="caps">VPI</span> properties</a></li>
+ <li><a href="#ex..properties">Examples of accessing a handle’s properties</a></li>
+ <li><a href="#ex..callback">Using a callback for value change notification</a></li>
+ <li><a href="#example3">Seeing what a test runner can do</a></li>
+ <li><a href="#example4">Running a test with environment variables</a></li>
<li><a href="#fig..counter.v_decl">Declaration of a simple up-counter with synchronous reset</a></li>
<li><a href="#fig..generate-test.rspec">Generating a test with specification in rSpec format</a></li>
<li><a href="#fig..generate-test.unit-test">Generating a test with specification in xUnit format</a></li>
<li><a href="#fig..counter_rspec_spec.rb">Specification implemented in rSpec format</a></li>
<li><a href="#fig..counter_xunit_spec.rb">Specification implemented in xUnit format</a></li>
@@ -202,63 +208,70 @@
<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>
- <div class="cover-page">
+ <h1 id="anchor4">1 Ruby-VPI user manual</h1>
- <h1 id="anchor5">Ruby-VPI user manual</h1>
+ <p>This manual was last updated on Sat Dec 30 19:26:28 <span class="caps">PST 2006</span>.</p>
- <p>Suraj N. Kurapati</p>
+ <p>It is meant to be read in conjunction with the <a href="../ref/ruby/index.html">reference documentation for Ruby-VPI</a>. In addition, if you are new to <a href="http://www.ruby-lang.org">the Ruby language</a>, you are encouraged to <a href="http://www.ruby-lang.org/en/documentation/">explore its documentation</a> alongside this manual.</p>
- <p>Wed Dec 27 22:29:49 <span class="caps">PST 2006</span></p>
+ <p>You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the <a href="http://rubyforge.org/forum/?group_id=1339">project forums</a>.</p>
-</div>
- <h2 id="terms">Terms</h2>
+ <p><em>Happy reading!</em></p>
+ <h2 id="terms">1.1 Terms</h2>
+
+
+ <p>Copyright© 2006 Suraj N. Kurapati.</p>
+
+
<p>Permission is granted to copy, distribute and/or modify this document under the terms of the <a href="http://www.gnu.org/copyleft/fdl.html"><span class="caps">GNU</span> Free Documentation License</a>, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the the file named <a href="./LICENSE"><span class="caps">LICENSE</span></a>.</p>
- <p>Admonition and navigation graphics are Copyright© 2005, 2006 <a href="http://tango.freedesktop.org">Tango Desktop Project</a>. They are licensed under <a href="./images/LICENSE">these terms</a>.</p>
+ <p>The admonition and navigation graphics used in this manual are Copyright© 2005, 2006 <a href="http://tango.freedesktop.org">Tango Desktop Project</a> and are licensed under <a href="./images/LICENSE">these terms</a>.</p>
- <h1 id="intro">Introduction</h1>
+ <h1 id="intro">2 Introduction</h1>
- <blockquote>
- <p>Ruby-VPI is a <a href="http://www.ruby-lang.org">Ruby</a> interface to <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945">Verilog <span class="caps">VPI</span></a>. It lets you create complex Verilog test benches easily and wholly in Ruby.</p>
- </blockquote>
+ <p>Ruby-VPI is a <a href="http://www.ruby-lang.org">Ruby</a> interface to <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog <span class="caps">VPI</span></a>. It lets you create complex Verilog test benches easily and wholly in Ruby.</p>
- <h2 id="intro.features">Features</h2>
+ <h2 id="intro.features">2.1 Features</h2>
+ <h3 id="anchor5">2.1.1 Portable</h3>
+
+
<ul>
<li>Supports the <em>entire</em> <a href=":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
</ul>
<ul>
<li>Works with all <a href="manual.html#setup.reqs">major Verilog simulators</a> available today.
<ul>
- <li>Compile <em>once</em> (during <a href="manual.html#setup.installation">installation</a>) and use forever!</li>
+ <li>Compiled <em>just once</em> during <a href="manual.html#setup.installation">installation</a> and used forever!</li>
</ul></li>
</ul>
+ <h3 id="anchor6">2.1.2 Agile</h3>
+
+
<ul>
<li>Enables <a href="http://agilemanifesto.org/">agile practices</a> such as
<ul>
<li><a href="http://www.testdriven.com">test-driven</a> development</li>
<li><a href="http://behaviour-driven.org">behavior-driven</a> development</li>
@@ -268,18 +281,22 @@
<ul>
<li>Eliminates unneccesary work:
<ul>
- <li><a href="manual.html#usage.tutorial.specification">Specifications</a> are <em>readable</em>, portable, and executable.</li>
+ <li><a href="manual.html#usage.tutorial.specification">Specifications</a> are readable, portable, and <em>executable</em>.</li>
<li>The <a href="manual.html#usage.tools.generate-test">automated test generator</a> helps you accomodate design changes with <em>minimal</em> effort.</li>
+ <li>There is absolutely <em>no compiling</em>!</li>
</ul></li>
</ul>
+ <h3 id="anchor7">2.1.3 Powerful</h3>
+
+
<ul>
- <li>Utilizes the <a href="http://www.ruby-lang.org/en/about/">power and elegance</a> of Ruby:
+ <li>Inherits the <a href="http://www.ruby-lang.org/en/about/">power and elegance</a> of Ruby:
<ul>
<li>Unlimited length integers</li>
<li>Regular expressions</li>
<li>Multi-threading</li>
<li>System calls and I/O</li>
@@ -287,32 +304,58 @@
</ul></li>
</ul>
<ul>
+ <li>Uses <a href="http://rubyforge.org/projects/ruby-debug/">ruby-debug</a> for <a href="manual.html#usage.debugger">interactive debugging</a>.</li>
+ <li>Uses <a href="http://eigenclass.org/hiki.rb?rcov">rcov</a> for test <a href="manual.html#usage.test-runner.env-vars">coverage analysis and report generation</a>.</li>
+ </ul>
+
+
+ <h3 id="anchor8">2.1.4 Free</h3>
+
+
+ <ul>
<li>Gives you the <em>freedom</em> to study, modify, and distribute this software, in accordance with the <a href="http://www.gnu.org/copyleft/gpl.html"><span class="caps">GNU</span> General Public License</a>.</li>
</ul>
- <h3 id="intro.applications">Applications</h3>
+ <h2 id="intro.applications">2.2 Applications</h2>
- <p>Here is a modest sampling of tasks, paraphrased from <a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">Pin Hong</a>, that Ruby-VPI can be used to perform.</p>
+ <p>Here is a modest sampling of tasks that Ruby-VPI can be used to perform.</p>
<ul>
+ <li>From the second edition of <a href="http://www.sutherland-hdl.com/publications.html"><em>The Verilog <span class="caps">PLI</span> Handbook</em></a>:
+ <ul>
+ <li>C language bus-functional models</li>
+ <li>Reading test vector files</li>
+ <li>Delay calculation</li>
+ <li>Custom output displays</li>
+ <li>Co-simulation</li>
+ <li>Design debug utilities</li>
+ <li>Simulation analysis</li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>Adapted from <a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">Pin Hong’s</a> observations:
+ <ul>
<li>Writing hardware models in Ruby</li>
- <li>Dumping/processing netlist data from Verilog database</li>
- <li>Dumping/processing simulation data</li>
+ <li>Dumping or processing netlist data from Verilog database</li>
+ <li>Dumping or processing simulation data</li>
<li>Feeding dynamic simulation stimuli</li>
<li>Back-annotating delay information</li>
<li>Interactive logic simulation</li>
<li>Building a distributed simulation</li>
+ </ul></li>
</ul>
- <h3 id="intro.appetizers">Appetizers</h3>
+ <h2 id="intro.appetizers">2.3 Appetizers</h2>
<p>Here is a modest sampling of code to whet your appetite.</p>
@@ -350,21 +393,21 @@
<li>Simulate fifteen clock cycles:</li>
</ul>
<blockquote>
- <p><code class="code"><span style="color:#00D; font-weight:bold">15</span>.times { relay_verilog }</code></p>
+ <p><code class="code"><span style="color:#00D; font-weight:bold">15</span>.times { simulate }</code></p>
</blockquote>
- <h2 id="intro.license">License</h2>
+ <h2 id="intro.license">2.4 License</h2>
<p>Ruby-VPI is <a href="http://en.wikipedia.org/wiki/Free_software">free software</a> ; you can redistribute it and/or modify it under the terms of the <a href="http://www.gnu.org/copyleft/gpl.html"><span class="caps">GNU</span> General Public License</a> as published by the <a href="http://www.fsf.org">Free Software Foundation</a> ; either version 2 of the License, or (at your option) any later version.</p>
- <h2 id="intro.related-works">Related works</h2>
+ <h2 id="intro.related-works">2.5 Related works</h2>
<ul>
<li><a href="http://jove.sourceforge.net"><span class="caps">JOVE</span></a> is a Java interface to <span class="caps">VPI</span>.</li>
<li><a href="http://teal.sourceforge.net">Teal</a> is a C++ interface to <span class="caps">VPI</span>.</li>
@@ -372,11 +415,11 @@
<li><a href="http://rhdl.rubyforge.org"><span class="caps">RHDL</span></a> is a hardware description and verification language based on Ruby.</li>
<li><a href="http://myhdl.jandecaluwe.com">MyHDL</a> is a hardware description and verification language based on Python, which features conversion to Verilog and co-simulation.</li>
</ul>
- <h3 id="intro.related-works.pli">Ye olde <span class="caps">PLI</span></h3>
+ <h3 id="intro.related-works.pli">2.5.1 Ye olde <span class="caps">PLI</span></h3>
<p>The following projects utilize the archaic <strong>tf</strong> and <strong>acc</strong> PLI interfaces, which have been officially deprecated in <span class="caps">IEEE</span> Std 1364-2005.</p>
@@ -385,23 +428,20 @@
<li><a href="http://www.veripool.com/verilog-pli.html">Verilog::Pli</a> is a Perl interface to <span class="caps">PLI</span>.</li>
<li><a href="http://www.time-rover.com/jpli/"><span class="caps">JPLI</span></a> is a proprietary Java interface to <span class="caps">PLI</span>.</li>
</ul>
- <h1 id="background">Background</h1>
+ <h1 id="background">3 Background</h1>
- <p>Ruby-VPI is a <a href="#glossary.bench">bench</a> which lets you <a href="#glossary.test">test</a> Verilog modules using the Ruby language.</p>
+ <h2 id="background.methodology">3.1 Methodology</h2>
- <h2 id="background.methodology">Methodology</h2>
-
-
<p>Ruby-VPI presents an open-ended interface to <span class="caps">VPI</span>. Thus, you can use any methodology you wish when writing tests. However, being an agile language, Ruby makes it <em>very</em> easy to use agile development practies such as <a href="#glossary.TDD"><span class="caps">TDD</span></a> and <a href="#glossary.BDD"><span class="caps">BDD</span></a>.</p>
- <h2 id="background.vocab">Terminology</h2>
+ <h2 id="background.vocab">3.2 Terminology</h2>
<div class="admonition">
<div class="note" id="note1">
@@ -416,22 +456,24 @@
</div>
</div>
-As a newcomer into the world of Verilog, I often heard the term <strong>test bench</strong>: “I ran the test bench, but it didn’t work!” or “Are you crazy?!! You <em>still</em> haven’t written the test bench?”, for example. I poured through my textbook for a definition of the term, but it was to no avail. Instead, it nonchalantly employed the term <em>throughout</em> its being, as if mocking my ignorance of what seems to be universal knowledge.
+ <p>As a newcomer into the world of Verilog, I often heard the term <strong>test bench</strong>: “I ran the test bench, but it didn’t work!” or “Are you crazy?!! You <em>still</em> haven’t written the test bench?”, for example. I poured through my textbook for a definition of the term, but it was to no avail. Instead, it nonchalantly employed the term <em>throughout</em> its being, as if mocking my ignorance of what seems to be universal knowledge.</p>
+
+
<p>Defeated, I turned to my inner faculties to determine the answer. Let’s see, the term <em>test bench</em> has the word <em>test</em>—so it has something to do with testing—and it has the word <em>bench</em>—so maybe it’s referring to a table where the testing should occur. This reasoning grew increasingly familiar as my mind rummaged through towering stores of obsolescence and ultimately revealed dreaded memories of sleepless anguish: debugging electronics in the robotics laboratory.</p>
<p>Aha! I exclaimed, hesitantly, rushing to dismiss the past. The term has its roots in the testing of electronic devices, where an engineer would sit at a bench in an electronics laboratory and verify that an electronic component satisfies some criteria. The bench would be furnished with tools of measurement and manipulation—such as oscilloscopes, voltmeters, soldering irons, and so on—which help the engineer to verify the electronic component or locate the sources of defects in the component.</p>
<p>Alright, now I remember what a laboratory bench is, but how does that compare with the term test bench? Surely they cannot have the same meaning, because it doesn’t make sense to <em>run</em> a laboratory bench or to <em>write</em> one. Thus, to avoid propagating such confusion into this manual, I have attempted to clarify the terminology by <a href="#glossary">simplifying and reintroducing it in a new light</a>.</p>
- <h2 id="background.org">Organization</h2>
+ <h2 id="background.org">3.3 Organization</h2>
<div class="formal">
<div class="figure" id="fig..organization">
@@ -443,16 +485,15 @@
</div>
</div>
-As <a href="#fig..organization">the figure named “Overall organization of a test”</a> shows, a <a href="#glossary.test">test</a> is composed of a <a href="#glossary.bench">bench</a>, a <a href="#glossary.design">design</a>, and a <a href="#glossary.specification">specification</a>.
- <p>To extend the <a href="#background.vocab">analogy of an electronics laboratory</a>, the <em>bench</em> acts as the laboratory bench which provides measurement and manipulation tools. The <em>design</em> acts as the electronic component being verified by the engineer. And the <em>specification</em> acts as the engineer who measures, manipulates, and verifies the electronic component.</p>
+ <p>As <a href="#fig..organization">the figure named “Overall organization of a test”</a> shows, a <a href="#glossary.test">test</a> is composed of a <a href="#glossary.bench">bench</a>, a <a href="#glossary.design">design</a>, and a <a href="#glossary.specification">specification</a>.</p>
- <h3 id="background.org.vpi">Interface to <span class="caps">VPI</span></h3>
+ <p>To extend the <a href="#background.vocab">analogy of an electronics laboratory</a>, the <em>bench</em> acts as the laboratory bench which provides measurement and manipulation tools. The <em>design</em> acts as the electronic component being verified by the engineer. And the <em>specification</em> acts as the engineer who measures, manipulates, and verifies the electronic component.</p>
<div class="formal">
<div class="figure" id="fig..organization.detail">
@@ -464,56 +505,335 @@
</div>
</div>
-In <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>, Ruby-VPI acts as the <em>bench</em>, a Verilog simulator encapsulates the <em>design</em>, and a Ruby interpreter encapsulates the <em>specification</em>.
- <p>Notice that Ruby-VPI encapsulates all communication between the Ruby interpreter and <span class="caps">VPI</span>. This allows the specification, or any Ruby program in general, to access <span class="caps">VPI</span> using nothing more than the Ruby language! Thus, Ruby-VPI removes the burden of having to write C programs in order to access <span class="caps">VPI</span>.</p>
+ <p>Now, let us take a more detailed look at this organization, as illustrated in <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>.</p>
- <p>Furthermore, Ruby-VPI presents the <em>entire</em> IEEE Std 1364-2005 <span class="caps">VPI</span> interface to the Ruby interpreter, but with the following minor changes.</p>
+ <p>Notice that Ruby-VPI encapsulates all communication between the Ruby interpreter and <span class="caps">VPI</span>. This allows the specification, or any Ruby program in general, to access <span class="caps">VPI</span> using nothing more than the Ruby language! Thus, Ruby-VPI removes the burden of having to write C programs in order to use <span class="caps">VPI</span>.</p>
+ <h2 id="background.relay">3.4 Ruby/Verilog interaction</h2>
+
+
+ <p>In a typical <span class="caps">VPI</span> application written in C, the <em>Verilog simulator</em> is in charge. Verilog code temporarily transfers control to C by invoking C functions, which return control to Verilog when they finish.</p>
+
+
+ <p>In contrast, Ruby-VPI puts the <em>specification</em> in charge. The specification temporarily transfers control to the Verilog simulator by invoking the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::advance_time</code> method, which returns control to the specification when it finishes. This process is illustrated in <a href="#fig..ruby_relay">the figure named “Interaction between Ruby and Verilog”</a>.</p>
+
+
+ <p>Ruby-VPI’s approach is the same as any software testing framework, where the <em>specification</em> drives the design under test. Whereas, the typical <span class="caps">VPI</span> & C approach is literally <em>backwards</em> because the design under test drives the specification.</p>
+
+
+<div class="formal">
+
+<div class="figure" id="fig..ruby_relay">
+
+ <p class="title">Figure 3. Interaction between Ruby and Verilog</p>
+
+
+ <p><img src="figures/ruby_relay.png" alt="" /></p>
+
+
+ <ol>
+ <li>The current simulation time is <em>X</em>.</li>
+ <li>The specification invokes the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::advance_time</code> method with parameter <em>Y</em>, which specifies the number of simulation time steps to be simulated.</li>
+ <li>The Verilog simulator is now in control (temporarily).</li>
+ <li>The current simulation time has <em>not</em> changed; it is still <em>X</em>.</li>
+ <li>The Verilog simulator simulates <em>Y</em> simulation time steps.</li>
+ <li>The current simulation time is now <em>X + Y</em>.</li>
+ <li>The Verilog simulator returns control back to the specification.</li>
+ </ol>
+
+
+</div>
+
+</div>
+
+ <h1 id="setup">4 Setup</h1>
+
+
+ <h2 id="setup.manifest">4.1 Manifest</h2>
+
+
+ <p>When you extract a release package, the following is what you would expect to find.</p>
+
+
<ul>
- <li>The first letter in the name of every function, type, structure, and constant becomes capitalized. For example, the <code class="code">s_vpi_value</code> structure in C becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant in C becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby.</li>
+ <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 “Sample tests”</a> for more information.</li>
</ul>
+ <h2 id="setup.reqs">4.2 Requirements</h2>
+
+
+ <p>The following software is necessary in order to use Ruby-VPI.</p>
+
+
<ul>
- <li>The <span class="caps">VPI</span> functions <code class="code">vpi_vprintf</code> and <code class="code">vpi_mcd_vprintf</code> are not made accessible to Ruby. However, this isn’t a big problem because you can use Ruby’s printf method instead.</li>
+ <li>Verilog simulator
+ – Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports <span class="caps">VPI</span>.
+ <ul>
+ <li><a href="http://www.pragmatic-c.com/gpl-cver/"><span class="caps">GPL</span> Cver</a>
+ – version 2.11a or newer is acceptable.</li>
+ <li><a href="http://www.icarus.com/eda/Verilog/">Icarus Verilog</a>
+ – version 0.8 is <em>mostly</em> acceptable—you <strong>will not</strong> be able to <a href="#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained in <a href="#problems.ivl.vpi_handle_by_name.absolute-paths">the section named “Give full paths to Verilog objects”</a>.</li>
+ <li><a href="http://www.synopsys.com/products/simulation/simulation.html">Synopsys <span class="caps">VCS</span></a>
+ – any version that supports the <tt>-load</tt> option is acceptable.</li>
+ <li><a href="http://www.model.com">Mentor Modelsim</a>
+ – any version that supports the <tt>-pli</tt> option is acceptable.</li>
+ </ul></li>
</ul>
- <blockquote>
- <p>The reason for this limitation is that some C compilers have trouble with pointers to the va_list type. For these compilers, the second line in the code shown below causes a “type mismatch” error.</p>
- </blockquote>
+<div class="admonition">
+<div class="tip" id="tip1">
-<pre class="code" lang="c">
-<span style="color:#339; font-weight:bold">void</span> foo(va_list ap) {
- va_list *p = &ap;
-}
+ <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
+
+
+ <p class="title">Tip: Add support for your Verilog simulator</p>
+
+
+ <p>Write a <a href="http://rubyforge.org/tracker/?group_id=1339">support request</a> for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!</p>
+
+
+</div>
+
+</div>
+
+ <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>
+
+
+ <ul>
+ <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads"><span class="caps">POSIX</span> threads</a>
+ – header and linkable object files, and operating system support for this library are necessary.</li>
+ </ul>
+
+
+ <ul>
+ <li><a href="http://www.ruby-lang.org">Ruby</a>
+ – version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following <a href="http://www.rubygarden.org/faq/section/show/3">these instructions</a>.</li>
+ </ul>
+
+
+ <ul>
+ <li><a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a>
+ – any recent version should be acceptable. You can install RubyGems by following <a href="http://www.rubygems.org/read/chapter/3">these instructions</a>.</li>
+ </ul>
+
+
+ <h2 id="setup.recom">4.3 Recommendations</h2>
+
+
+ <p>The following software may make your interactions with Ruby-VPI more pleasant.</p>
+
+
+ <h3 id="setup.recom.merger">4.3.1 Text merging tool</h3>
+
+
+An <em>interactive</em> text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the <a href="#usage.tools.generate-test">automated test generator</a>. A handful of the currently available open-source text merging tools are listed below.
+ <ul>
+ <li><a href="http://kdiff3.sourceforge.net/"><strong>kdiff3</strong></a> is a graphical, three-way merging tool for <span class="caps">KDE</span>.</li>
+ <li><a href="http://meld.sourceforge.net/"><strong>meld</strong></a> is a graphical, three-way merging tool for <span class="caps">GNOME</span>.</li>
+ <li><a href="http://tkdiff.sourceforge.net/"><strong>tkdiff</strong></a> is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</li>
+ <li><a href="http://furius.ca/xxdiff/"><strong>xxdiff</strong></a> is a graphical, three-way merging tool.</li>
+ <li><a href="http://elonen.iki.fi/code/imediff/"><strong>imediff2</strong></a> is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via <span class="caps">SSH</span>.</li>
+ </ul>
+
+
+ <h2 id="setup.installation">4.4 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 -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
+
+$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
+/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
</pre>
- <h4 id="background.org.vpi.util"><span class="caps">VPI</span> utility layer</h4>
+ <h3 id="setup.installation.windows">4.4.1 Installing on Windows</h3>
- <p>From a user’s perspective, the <span class="caps">VPI</span> utility layer (see <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>) greatly enhances the ability to interact with <a href="#glossary.handle">handles</a>. One simply invokes a handle’s methods, which are carefully named in the following manner, to access either (1) its children or (2) its <span class="caps">VPI</span> properties.</p>
+ <ul>
+ <li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
+ </ul>
- <p>The children of a handle are simply the handles that are <em>immediately</em> contained within it in. For example, suppose that you had a Verilog module that contains some registers. The children of a handle to that module would be handles to that module’s registers.</p>
+<div class="admonition">
+<div class="note" id="note2">
- <p>In the event that a child handle has the same name as a <span class="caps">VPI</span> property, the child is given priority. However, you can always access <span class="caps">VPI</span> properties explicitly via the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span>.get_value</code> and <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span>.put_value</code> methods.</p>
+ <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p class="title">Note: Undefined symbols in Windows</p>
+
+
+ <p>After Ruby-VPI is compiled, it is linked to symbols whose names begin with <tt>_vpi</tt>. In <span class="caps">GNU</span>/Linux and similar operating systems, these symbols are allowed to be undefined. However, one <a href="http://sourceware.org/ml/cygwin/2001-12/msg01293.html">cannot compile a shared object file with references to undefined symbols in Windows</a>.</p>
+
+
+ <p>One solution is to supply the Verilog simulator’s <span class="caps">VPI</span> object file, which contains definitions of all <span class="caps">VPI</span> symbols, to the linker. The following steps illustrate this process.</p>
+
+
+</div>
+
+</div>
+
+ <ul>
+ <li>Search for object files whose names end with <tt>.so</tt>, <tt>.o</tt>, or <tt>.dll</tt> in your Verilog simulator’s installation directory.</li>
+ </ul>
+
+
+ <ul>
+ <li>Determine which object files, among those found in the previous step, contain symbols whose names begin with “_vpi” by running the <pre>for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' && echo $x; done</pre> command in Cygwin.
+ <ul>
+ <li>If you are using Mentor Modelsim, the desired object file can be found at a path similar to <tt>C:\Modeltech\win32\libvsim.dll</tt>.</li>
+ <li>If you are using <span class="caps">GPL</span> Cver, the desired object file can be found at a path similar to <tt>C:\gplcver\objs\v_vpi.o</tt>.</li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>Assign the path of the object file (determined in the previous step) to the <code class="code"><span style="color:#036; font-weight:bold">LDFLAGS</span></code> environment variable. For example, if the object file’s path is <tt>/foo/bar/vpi.so</tt>, then you would run the <pre>export LDFLAGS=/foo/bar/vpi.so</pre> command in Cygwin.</li>
+ </ul>
+
+
+ <ul>
+ <li>You may now install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command in Cygwin.</li>
+ </ul>
+
+
+ <h2 id="setup.maintenance">4.5 Maintenance</h2>
+
+
+ <ul>
+ <li>You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.</li>
+ <li>You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.</li>
+ </ul>
+
+
+<div class="admonition">
+
+<div class="note" id="note3">
+
+ <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+
+
+ <p class="title">Note:</p>
+
+
+ <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
+
+
+</div>
+
+</div>
+
+ <h1 id="usage">5 Usage</h1>
+
+
+ <h2 id="usage.vpi">5.1 <span class="caps">VPI</span> in Ruby</h2>
+
+
+ <p>The <em>entire</em> IEEE Std 1364-2005 <span class="caps">VPI</span> interface is available in Ruby, but with one minor difference: the names of all <span class="caps">VPI</span> types, structures, and constants become <em>capitalized</em> because Ruby requires that the names of constants begin with a capital letter.</p>
+
+
+ <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby.</p>
+
+
+ <p>Note that this capitalization rule does <strong>not</strong> apply to <span class="caps">VPI</span> functions; their names remain <em>unchanged</em> in Ruby.</p>
+
+
+ <h3 id="usage.vpi.handles">5.1.1 Handles</h3>
+
+
+ <p>A <em>handle</em> is a reference to an object, such as a module, register, wire, and so on, inside the Verilog simulation. In short, handles allow you to inspect and manipulate the design under test and its components.</p>
+
+
+<div class="admonition">
+
+<div class="note" id="note4">
+
+ <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+
+
+ <p class="title">Note:</p>
+
+
+ <p>Handles are instances of the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span></code> class (see <a href="../ref/ruby/classes/Vpi/Handle.html">reference documentation</a> for details) in Ruby-VPI.</p>
+
+
+</div>
+
+</div>
+
+ <p>Handles have various <em>properties</em>, which provide different kinds of information (see the “Kind of value accessed” column in <a href="#tbl..accessors">the table named “Possible accessors and their implications”</a>) about the underlying Verilog object represented by a handle. These properties are accessed through various functions, which are listed in the “VPI functions used to access the value” column in <a href="#tbl..accessors">the table named “Possible accessors and their implications”</a>.</p>
+
+
+ <p>Handles are typically obtained through the <code class="code">vpi_handle_by_name</code> and <code class="code">vpi_handle</code> functions. These functions are hierarchical in nature, because they allow you to obtain new handles that are related to existing handles. For example, to obtain a handle to a register inside a module, you would typically write: <code class="code">some_reg = vpi_handle(<span style="color:#036; font-weight:bold">VpiReg</span>, some_handle)</code>.</p>
+
+
+ <p class="title">Shortcuts for productivity</p>
+
+
+ <p>Given a handle, Ruby-VPI allows you to access (1) its relatives and (2) its properties by simply invoking its methods.</p>
+
+
+ <p>If a handle’s relative happens to have the same name as one of the handle’s properties, then the relative is given preference. However, if you <em>really</em> need to access a handle’s property in such a situation, then you can use the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span>.get_value</code> and <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span>.put_value</code> methods.</p>
+
+
+ <h4 id="anchor9">5.1.1.1 Accessing a handle’s relatives</h4>
+
+
+ <p>To access a handle’s relative (a handle related to it), simply invoke the relative’s name as a method on the handle.</p>
+
+
+ <p>For example, to access the <code class="code">reset</code> signal of the <code class="code">counter</code> module shown in <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a>, you would write the following:</p>
+
+
+<pre class="code">
+counter_module = vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">counter</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)
+
+reset_signal = counter_module.reset <span style="color:#888"># <== shortcut!</span>
+</pre>
+
+ <p>In this code, the shortcut is that you simply wrote <code class="code">counter_module.reset</code> instead of having to write <code class="code">vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">reset</span><span style="color:#710">"</span></span>, counter_module)</code>.</p>
+
+
+ <h4 id="anchor10">5.1.1.2 Accessing a handle’s properties</h4>
+
+
+ <p>To access a handle’s properties, invoke the proprty name, using the following format, as a method on the handle. <a href="#ex..properties">the example named “Examples of accessing a handle’s properties”</a> shows how this naming format is used.</p>
+
+
<div class="formal">
-<div class="figure" id="figure3">
+<div class="figure" id="figure4">
- <p class="title">Figure 3. Parts of speech for accessing a handle’s <span class="caps">VPI</span> properties</p>
+ <p class="title">Figure 4. Method naming format for accessing a handle’s properties</p>
<table>
<tr>
<th>Operation </th>
@@ -532,35 +852,40 @@
<ul>
- <li><strong>Operation</strong> suggests a method that should be invoked in the context of the Property parameter. All <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">methods in the Enumerable module</a> are available as operations.</li>
+ <li><strong>Operation</strong> suggests a method that should be invoked in the context of the Property parameter. All <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">methods in the Enumerable module</a> are valid <em>operations</em>.</li>
</ul>
<ul>
<li><strong>Property</strong> suggests a <span class="caps">VPI</span> property that should be accessed. The “vpi” prefix, which is common to all <span class="caps">VPI</span> properties, can be omitted if you wish. For example, the <span class="caps">VPI</span> property “vpiFullName” is considered equivalent to “fullName” and “FullName”, but not equivalent “full_name”.</li>
</ul>
<ul>
- <li><strong>Accessor</strong> suggests a <span class="caps">VPI</span> function that should be used in order to access the <span class="caps">VPI</span> property. When this parameter is not specified, the <span class="caps">VPI</span> utility layer will attempt to <em>guess</em> the value of this parameter (<a href="../ref/ruby/classes/Vpi/Handle/Property.html">see the source code</a> of the <code class="code"><span style="color:#036; font-weight:bold">Property</span>.resolve</code> method for details).</li>
+ <li><strong>Accessor</strong> suggests a <span class="caps">VPI</span> function that should be used in order to access the <span class="caps">VPI</span> property. When this parameter is not specified, Ruby-VPI will attempt to <em>guess</em> the value of this parameter.
+
+ <p><a href="#tbl..accessors">the table named “Possible accessors and their implications”</a> shows a list of valid accessors and how they affect the access to a property.</p></li>
</ul>
<ul>
- <li><strong>Addendum</strong> suggests that the specified <span class="caps">VPI</span> property should be queried as a boolean value when it is a question mark (?). This suggestion is the same as specifying “b” for the Accessor parameter. Also, when this parameter is an equal sign (=), it suggests that the specified <span class="caps">VPI</span> property should be written to.</li>
+ <li><strong>Addendum</strong> suggests that the specified <span class="caps">VPI</span> property should be queried as a boolean value when it is a question mark <code class="code">?</code>. This suggestion is the same as specifying <code class="code">b</code> for the Accessor parameter.
+
+ <p>Also, when this parameter is an equal sign <code class="code">=</code>, it suggests that the specified <span class="caps">VPI</span> property should be written to.</p></li>
</ul>
</div>
</div>
+
<div class="formal">
-<div class="table" id="table1">
+<div class="table" id="tbl..accessors">
<p class="title">Table 1. Possible accessors and their implications</p>
<table>
@@ -605,15 +930,16 @@
</div>
</div>
+
<div class="formal">
-<div class="example" id="example1">
+<div class="example" id="ex..properties">
- <p class="title">Example 1. Examples of accessing a handle’s <span class="caps">VPI</span> properties</p>
+ <p class="title">Example 1. Examples of accessing a handle’s properties</p>
<table>
<tr>
<th rowspan="2">Ruby expression </th>
@@ -932,278 +1258,307 @@
</div>
</div>
- <h2 id="background.running-tests">Running a test</h2>
+ <h3 id="usage.vpi.callbacks">5.1.2 Callbacks</h3>
- <p>Unlike an engineer who can verify an electronic component in real-time, the Verilog simulator and the Ruby interpreter (see <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>) take turns working with <a href="#glossary.handle">handles</a> when a <a href="#glossary.test">test</a> is run. In particular, they take turns manipulating the Verilog <a href="#glossary.design">design</a> and transfer control to each other when appropriate.</p>
+ <p>A <em>callback</em> is a mechanism that makes the Verilog simuluator execute a block of code, which is known as a “callback handler”, when some prescribed event occurs in the simulation. They are set up using the <code class="code">vpi_register_cb</code> function and torn down using the <code class="code">vpi_remove_cb</code> function.</p>
- <p>The situation is similar to a pair of friends playing catch. One friend throws a ball to the other, and the other throws it back. Either is able to inspect and modify the ball, but only when it is in hand.</p>
-
-
- <h3 id="background.running-tests.init">Initialization</h3>
-
-
- <p>A <a href="#glossary.test">test</a> is first initialized before it is <a href="#background.running-tests.exec">executed</a>. This process is illustrated by <a href="#fig..ruby_init">the figure named “Initialization of a test”</a>.</p>
-
-
<div class="formal">
-<div class="figure" id="fig..ruby_init">
+<div class="example" id="ex..callback">
- <p class="title">Figure 4. Initialization of a test</p>
+ <p class="title">Example 2. Using a callback for value change notification</p>
- <p><img src="figures/ruby_init.png" alt="" /></p>
+ <p>This example shows how to use a callback for notification of changes in a handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. When you no longer need this callback, you can tear it down using <code class="code">vpi_remove_cb(cb_handle)</code>.</p>
- <ol>
- <li>The Verilog simulator initializes the Ruby interpreter by invoking the <code class="code"><span style="color:#d70; font-weight:bold">$ruby_init</span>;</code> system task/function, whose parameters represent the command-line invocation of the Ruby interpreter. For example, one would specify <code class="code"><span style="color:#d70; font-weight:bold">$ruby_init</span>(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">ruby</span><span style="color:#710">"</span></span>, <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">-w</span><span style="color:#710">"</span></span>);</code> in Verilog to achieve the same effect as running <pre>ruby -w</pre> at a command-prompt.</li>
- <li>The Verilog simulator is paused and the Ruby interpreter is initialized with the arguments of the <code class="code"><span style="color:#d70; font-weight:bold">$ruby_init</span>;</code> system task/function.</li>
- <li>When the Ruby interpreter invokes the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::relay_verilog</code> method, it is paused and the Verilog simulator is given control.</li>
- </ol>
+ <p>In this example, the handle being monitored is the <code class="code"><span style="color:#036; font-weight:bold">Counter</span>.count</code> signal from <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a>.</p>
-</div>
+<pre class="code">
+cb_time = <span style="color:#036; font-weight:bold">S_vpi_time</span>.new
+cb_time.type = <span style="color:#036; font-weight:bold">VpiSimTime</span>
+cb_time.low = <span style="color:#00D; font-weight:bold">0</span>
+cb_time.high = <span style="color:#00D; font-weight:bold">0</span>
-</div>
+cb_value = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+cb_value.format = <span style="color:#036; font-weight:bold">VpiIntVal</span>
- <h3 id="background.running-tests.exec">Execution</h3>
+cb_data = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
+cb_data.reason = <span style="color:#036; font-weight:bold">CbValueChange</span>
+cb_data.obj = <span style="color:#036; font-weight:bold">Counter</span>.count
+cb_data.time = cb_time
+cb_data.value = cb_value
+cb_data.index = <span style="color:#00D; font-weight:bold">0</span>
+cb_handle = vpi_register_cb(cb_data) <span style="color:#080; font-weight:bold">do</span> |data|
- <p>After a <a href="#glossary.test">test</a> is <a href="#background.running-tests.init">initialized</a>, it is executed such that the design is verified against the <a href="#glossary.specification">specification</a>. This process is illustrated by <a href="#fig..ruby_relay">the figure named “Execution of a test”</a>.</p>
+ time = (data.time.high << <span style="color:#00D; font-weight:bold">32</span>) | data.time.low
+ count = data.value.value.integer
+ puts <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">hello from callback! time=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>time<span style="font-weight: bold; color: #888">}</span></span><span style="color:#D20"> count=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>count<span style="font-weight: bold; color: #888">}</span></span><span style="color:#710">"</span></span>
-<div class="formal">
+<span style="color:#080; font-weight:bold">end</span>
+</pre>
-<div class="figure" id="fig..ruby_relay">
+ <p>To see this code in action, append it to the <tt>counter_rspec_spec.rb</tt> and <tt>counter_xunit_spec.rb</tt> files, which are provided in <a href="#usage.examples">the section named “Sample tests”</a> and discussed in <a href="#usage.tutorial.specification">the section named “Specify your expectations”</a>.</p>
- <p class="title">Figure 5. Execution of a test</p>
-
- <p><img src="figures/ruby_relay.png" alt="" /></p>
-
-
- <ol>
- <li>The Verilog simulator transfers control to the Ruby interpreter by invoking the <code class="code"><span style="color:#d70; font-weight:bold">$ruby_relay</span>;</code> system task/function.</li>
- <li>The Verilog simulator is paused and the Ruby interpreter is given control.</li>
- <li>When the Ruby interpreter invokes the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::relay_verilog</code> method, it is paused and the Verilog simulator is given control.</li>
- </ol>
-
-
</div>
</div>
- <h1 id="setup">Setup</h1>
+<div class="formal">
+<div class="figure" id="figure5">
- <h2 id="setup.manifest">Manifest</h2>
+ <p class="title">Figure 5. Output from <a href="#ex..callback">the example named “Using a callback for value change notification”</a></p>
- <p>When you extract a release package, the following is what you would expect to find.</p>
+ <p>Shown below is the output from running the <a href="#usage.tutorial">counter_rspec test</a> after appending the code shown in <a href="#ex..callback">the example named “Using a callback for value change notification”</a> to the <tt>counter_rspec_spec.rb</tt> file.</p>
- <ul>
- <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 “Sample tests”</a> for more information.</li>
- </ul>
+<pre>
+$ rake -f counter_rspec_runner.rake cver
+(in /home/sun/src/ruby-vpi/samp/counter)
+cver +loadvpi=/home/sun/src/ruby-vpi/lib/ruby-vpi/../../obj/ruby-vpi.cver.so:vlog_startup_routines_bootstrap counter.v counter_rspec_bench.v
+GPLCVER_2.11a of 07/05/05 (Linux-elf).
+Copyright (c) 1991-2005 Pragmatic C Software Corp.
+ All Rights reserved. Licensed under the GNU General Public License (GPL).
+ See the 'COPYING' file for details. NO WARRANTY provided.
+Today is Sat Dec 30 09:24:09 2006.
+Compiling source file "counter.v"
+Compiling source file "counter_rspec_bench.v"
+Highest level modules:
+counter_rspec_bench
- <h2 id="setup.reqs">Requirements</h2>
+A resetted counter's value
+hello from callback! time=1 count=0
+- should be zero
+hello from callback! time=5 count=1
+hello from callback! time=7 count=2
+hello from callback! time=9 count=3
+hello from callback! time=11 count=4
+hello from callback! time=13 count=5
+hello from callback! time=15 count=6
+hello from callback! time=17 count=7
+hello from callback! time=19 count=8
+hello from callback! time=21 count=9
+hello from callback! time=23 count=10
+hello from callback! time=25 count=11
+hello from callback! time=27 count=12
+hello from callback! time=29 count=13
+hello from callback! time=31 count=14
+hello from callback! time=33 count=15
+hello from callback! time=35 count=16
+hello from callback! time=37 count=17
+hello from callback! time=39 count=18
+hello from callback! time=41 count=19
+hello from callback! time=43 count=20
+hello from callback! time=45 count=21
+hello from callback! time=47 count=22
+hello from callback! time=49 count=23
+hello from callback! time=51 count=24
+hello from callback! time=53 count=25
+hello from callback! time=55 count=26
+hello from callback! time=57 count=27
+hello from callback! time=59 count=28
+hello from callback! time=61 count=29
+hello from callback! time=63 count=30
+hello from callback! time=65 count=31
+hello from callback! time=67 count=0
+- should increment by one count upon each rising clock edge
+A counter with the maximum value
+hello from callback! time=71 count=1
+hello from callback! time=73 count=2
+hello from callback! time=75 count=3
+hello from callback! time=77 count=4
+hello from callback! time=79 count=5
+hello from callback! time=81 count=6
+hello from callback! time=83 count=7
+hello from callback! time=85 count=8
+hello from callback! time=87 count=9
+hello from callback! time=89 count=10
+hello from callback! time=91 count=11
+hello from callback! time=93 count=12
+hello from callback! time=95 count=13
+hello from callback! time=97 count=14
+hello from callback! time=99 count=15
+hello from callback! time=101 count=16
+hello from callback! time=103 count=17
+hello from callback! time=105 count=18
+hello from callback! time=107 count=19
+hello from callback! time=109 count=20
+hello from callback! time=111 count=21
+hello from callback! time=113 count=22
+hello from callback! time=115 count=23
+hello from callback! time=117 count=24
+hello from callback! time=119 count=25
+hello from callback! time=121 count=26
+hello from callback! time=123 count=27
+hello from callback! time=125 count=28
+hello from callback! time=127 count=29
+hello from callback! time=129 count=30
+hello from callback! time=131 count=31
+hello from callback! time=133 count=0
+- should overflow upon increment
- <p>The following software is necessary in order to use Ruby-VPI.</p>
+Finished in 0.042328 seconds
+3 specifications, 0 failures
+</pre>
- <ul>
- <li>Verilog simulator
- – Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports <span class="caps">VPI</span>.
- <ul>
- <li><a href="http://www.pragmatic-c.com/gpl-cver/"><span class="caps">GPL</span> Cver</a>
- – version 2.11a or newer is acceptable.</li>
- <li><a href="http://www.icarus.com/eda/Verilog/">Icarus Verilog</a>
- – version 0.8 is <em>mostly</em> acceptable—you <strong>will not</strong> be able to <a href="#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained in <a href="#problems.ivl.vpi_handle_by_name.absolute-paths">the section named “Give full paths to Verilog objects”</a>.</li>
- <li><a href="http://www.synopsys.com/products/simulation/simulation.html">Synopsys <span class="caps">VCS</span></a>
- – any version that supports the <tt>-load</tt> option is acceptable.</li>
- <li><a href="http://www.model.com">Mentor Modelsim</a>
- – any version that supports the <tt>-pli</tt> option is acceptable.</li>
- </ul></li>
- </ul>
-
-
-<div class="admonition">
-
-<div class="tip" id="tip1">
-
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
-
-
- <p class="title">Tip: Add support for your Verilog simulator</p>
-
-
- <p>Write a <a href="http://rubyforge.org/tracker/?group_id=1339">support request</a> for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!</p>
-
-
</div>
</div>
- <ul>
- <li><strong>make</strong>
- – any distribution should be acceptable.</li>
- </ul>
+ <h2 id="usage.debugger">5.2 Debugging</h2>
- <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>
+ <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>
- <ul>
- <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads"><span class="caps">POSIX</span> threads</a>
- – header and linkable object files, and operating system support for this library are necessary.</li>
- </ul>
+ <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>
- <ul>
- <li><a href="http://www.ruby-lang.org">Ruby</a>
- – version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following <a href="http://www.rubygarden.org/faq/section/show/3">these instructions</a>.</li>
- </ul>
+ <h3 id="usage.debugger.init">5.2.1 Advanced initialization</h3>
- <ul>
- <li><a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a>
- – any recent version should be acceptable. You can install RubyGems by following <a href="http://www.rubygems.org/read/chapter/3">these instructions</a>.</li>
- </ul>
+ <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>
- <h2 id="setup.recom">Recommendations</h2>
+ <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>
- <p>The following software may make your interactions with Ruby-VPI more pleasant.</p>
+ <h2 id="usage.test-runner">5.3 Test runner</h2>
- <h3 id="setup.recom.merger">Text merging tool</h3>
+ <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>
-An <em>interactive</em> text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the <a href="#usage.tools.generate-test">automated test generator</a>. A handful of the currently available open-source text merging tools are listed below.
- <ul>
- <li><a href="http://kdiff3.sourceforge.net/"><strong>kdiff3</strong></a> is a graphical, three-way merging tool for <span class="caps">KDE</span>.</li>
- <li><a href="http://meld.sourceforge.net/"><strong>meld</strong></a> is a graphical, three-way merging tool for <span class="caps">GNOME</span>.</li>
- <li><a href="http://tkdiff.sourceforge.net/"><strong>tkdiff</strong></a> is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</li>
- <li><a href="http://furius.ca/xxdiff/"><strong>xxdiff</strong></a> is a graphical, three-way merging tool.</li>
- <li><a href="http://elonen.iki.fi/code/imediff/"><strong>imediff2</strong></a> is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via <span class="caps">SSH</span>.</li>
- </ul>
+<div class="formal">
+<div class="example" id="example3">
- <h2 id="setup.installation">Installation</h2>
+ <p class="title">Example 3. Seeing what a test runner can do</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>
+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
-
-<pre>
-$ gem env gemdir
-/usr/lib/ruby/gems/1.8
-
-$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
-/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
+(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>
- <h3 id="setup.installation.windows">Installing on Windows</h3>
+</div>
+</div>
- <ul>
- <li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
- </ul>
+<div class="admonition">
+<div class="tip" id="tip2">
-<div class="admonition">
+ <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
-<div class="note" id="note2">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p class="title">Tip: Running multiple tests at once.</p>
- <p class="title">Note: Undefined symbols in Windows</p>
+ <p>Create a file named <tt>Rakefile</tt> containing the following line.</p>
- <p>After Ruby-VPI is compiled, it is linked to symbols whose names begin with <tt>_vpi</tt>. In <span class="caps">GNU</span>/Linux and similar operating systems, these symbols are allowed to be undefined. However, one <a href="http://sourceware.org/ml/cygwin/2001-12/msg01293.html">cannot compile a shared object file with references to undefined symbols in Windows</a>.</p>
+ <blockquote>
+ <p><code class="code">require <span style="background-color:#fff0f0"><span style="color:#710">'</span><span style="color:#D20">ruby-vpi/runner_proxy</span><span style="color:#710">'</span></span></code></p>
+ </blockquote>
- <p>One solution is to supply the Verilog simulator’s <span class="caps">VPI</span> object file, which contains definitions of all <span class="caps">VPI</span> symbols, to the linker. The following steps illustrate this process.</p>
+ <p>Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where <em>cver</em> denotes the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>).</p>
</div>
</div>
-* Search for object files whose names end with <tt>.so</tt>, <tt>.o</tt>, or <tt>.dll</tt> in your Verilog simulator’s installation directory.
- <ul>
- <li>Determine which object files, among those found in the previous step, contain symbols whose names begin with “_vpi” by running the <pre>for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' && echo $x; done</pre> command in Cygwin.
- <ul>
- <li>If you are using Mentor Modelsim, the desired object file can be found at a path similar to <tt>C:\Modeltech\win32\libvsim.dll</tt>.</li>
- <li>If you are using <span class="caps">GPL</span> Cver, the desired object file can be found at a path similar to <tt>C:\gplcver\objs\v_vpi.o</tt>.</li>
- </ul></li>
- </ul>
+ <h3 id="usage.test-runner.env-vars">5.3.1 Environment variables</h3>
- <ul>
- <li>Assign the path of the object file (determined in the previous step) to the <code class="code"><span style="color:#036; font-weight:bold">LDFLAGS</span></code> environment variable. For example, if the object file’s path is <tt>/foo/bar/vpi.so</tt>, then you would run the <pre>export LDFLAGS=/foo/bar/vpi.so</pre> command in Cygwin.</li>
- </ul>
+ <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>You may now install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command in Cygwin.</li>
+ <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>
- <h2 id="setup.maintenance">Maintenance</h2>
+ <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>
- <ul>
- <li>You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.</li>
- <li>You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.</li>
- </ul>
+ <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>
-<div class="admonition">
+ <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="note" id="note3">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+<div class="formal">
+<div class="example" id="example4">
- <p class="title">Note:</p>
+ <p class="title">Example 4. Running a test with environment variables</p>
- <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</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>
- <h1 id="usage">Usage</h1>
+ <h2 id="usage.examples">5.4 Sample tests</h2>
- <h2 id="usage.tools">Tools</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>
+ <h2 id="usage.tools">5.5 Tools</h2>
+
+
<p>The <tt>bin</tt> directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the <tt>--help</tt> option.</p>
- <h3 id="usage.tools.generate-test">Automated test generation</h3>
+ <h3 id="usage.tools.generate-test">5.5.1 Automated test generation</h3>
<p>The automated test generator (<strong>generate_test.rb</strong>) generates tests from Verilog 2001 module declarations, as demonstrated <a href="#usage.tutorial.generate-test">in the tutorial</a>. A generated test is composed of the following parts:</p>
@@ -1224,11 +1579,11 @@
<p>The reason for dividing a single test into these parts is mainly to decouple the design from the specification. This allows you to focus on writing the specification while the remainder is automatically generated by the tool. For example, when the interface of a Verilog module changes, you would simply re-run this tool and incorporate those changes (using a <a href="#setup.recom.merger">text merging tool</a>) into the test without diverting your focus from the specification.</p>
<div class="admonition">
-<div class="tip" id="tip2">
+<div class="tip" id="tip3">
<p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
<p class="title">Tip: Using <strong>kdiff3</strong> with the automated test generator.</p>
@@ -1251,20 +1606,20 @@
</div>
</div>
- <h3 id="usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</h3>
+ <h3 id="usage.tools.verilog-ruby-conv">5.5.2 Verilog to Ruby conversion</h3>
<p>The <strong>header_to_ruby.rb</strong> tool can be used to convert Verilog header files into Ruby. You can try it by running the <pre>header_to_ruby.rb --help</pre> command.</p>
<p>By converting Verilog header files into Ruby, your <a href="#glossary.test">test</a> can utilize the same <code class="code"><span style="background-color:#f0fff0"><span style="color:#161">`</span><span style="color:#2B2">define</span></span></code> constants that are used in the Verilog <a href="#glossary.design">design</a>.</p>
- <h2 id="usage.tutorial">Tutorial</h2>
+ <h2 id="usage.tutorial">5.6 Tutorial</h2>
<ol>
<li><a href="#usage.tutorial.declare-design">Declare the design</a>, which is a Verilog module, using Verilog 2001 syntax.</li>
<li><a href="#usage.tutorial.generate-test">Generate a test</a> for the design using the <a href="#usage.tools.generate-test">automated test generator</a> tool.</li>
@@ -1274,11 +1629,11 @@
<li><a href="#usage.tutorial.implement-design">Implement the design</a> in Verilog once the prototype has been verified.</li>
<li><a href="#usage.tutorial.test-design">Verify the design</a> against the specification.</li>
</ol>
- <h3 id="usage.tutorial.declare-design">Start with a design</h3>
+ <h3 id="usage.tutorial.declare-design">5.6.1 Start with a design</h3>
<p>First, we need a <a href="#glossary.design">design</a> to verify. In this tutorial, <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a> will serve as our design. Its interface is composed of the following parts:</p>
@@ -1292,11 +1647,11 @@
<div class="formal">
<div class="example" id="fig..counter.v_decl">
- <p class="title">Example 2. Declaration of a simple up-counter with synchronous reset</p>
+ <p class="title">Example 5. Declaration of a simple up-counter with synchronous reset</p>
<pre class="code" lang="verilog">
module counter #(parameter Size = 5) (
input clock,
@@ -1307,10 +1662,11 @@
</pre>
</div>
</div>
+
<div class="admonition">
<div class="important" id="important1">
<p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
@@ -1324,11 +1680,11 @@
</div>
</div>
- <h3 id="usage.tutorial.generate-test">Generate a test</h3>
+ <h3 id="usage.tutorial.generate-test">5.6.2 Generate a test</h3>
<p>Now that we have a <a href="#glossary.design">design</a> to verify, let us generate a <a href="#glossary.test">test</a> for it using the <a href="#usage.tools.generate-test">automated test generator</a>. This tool allows us to implement our specification in either rSpec, xUnit, or our very own format.</p>
@@ -1340,11 +1696,11 @@
</ul>
<div class="admonition">
-<div class="note" id="note4">
+<div class="note" id="note5">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
<p class="title">Note:</p>
@@ -1354,17 +1710,19 @@
</div>
</div>
-Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. This process is illustrated by <a href="#fig..generate-test.rspec">the example named “Generating a test with specification in rSpec format”</a> and <a href="#fig..generate-test.unit-test">the example named “Generating a test with specification in xUnit format”</a>.
+ <p>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. This process is illustrated by <a href="#fig..generate-test.rspec">the example named “Generating a test with specification in rSpec format”</a> and <a href="#fig..generate-test.unit-test">the example named “Generating a test with specification in xUnit format”</a>.</p>
+
+
<div class="formal">
<div class="example" id="fig..generate-test.rspec">
- <p class="title">Example 3. Generating a test with specification in rSpec format</p>
+ <p class="title">Example 6. Generating a test with specification in rSpec format</p>
<pre>
$ generate_test.rb counter.v --rspec --name rspec
@@ -1378,15 +1736,16 @@
</pre>
</div>
</div>
+
<div class="formal">
<div class="example" id="fig..generate-test.unit-test">
- <p class="title">Example 4. Generating a test with specification in xUnit format</p>
+ <p class="title">Example 7. Generating a test with specification in xUnit format</p>
<pre>
$ generate_test.rb counter.v --xunit --name xunit
@@ -1401,11 +1760,11 @@
</div>
</div>
- <h3 id="usage.tutorial.specification">Specify your expectations</h3>
+ <h3 id="usage.tutorial.specification">5.6.3 Specify your expectations</h3>
<p>So far, the test generation tool has created a basic foundation for our <a href="#glossary.test">test</a>. Now we must build upon this foundation by identifying our <a href="#glossary.expectation">expectation</a> of the <a href="#glossary.design">design</a>. That is, how do we expect the design to <em>behave</em> under certain conditions?</p>
@@ -1422,11 +1781,11 @@
<div class="formal">
<div class="example" id="fig..counter_rspec_spec.rb">
- <p class="title">Example 5. Specification implemented in rSpec format</p>
+ <p class="title">Example 8. Specification implemented in rSpec format</p>
<pre class="code"><span style="color:#888"># This file is a behavioral specification for the design under test.</span>
<span style="color:#888"># lowest upper bound of counter's value</span>
@@ -1445,39 +1804,40 @@
<span style="color:#080; font-weight:bold">end</span>
specify <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">should increment by one count upon each rising clock edge</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">LIMIT</span>.times <span style="color:#080; font-weight:bold">do</span> |i|
<span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == i
- relay_verilog <span style="color:#888"># increment the counter</span>
+ simulate <span style="color:#888"># increment the counter</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
context <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">A counter with the maximum value</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
setup <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#888"># increment the counter to maximum value</span>
- <span style="color:#036; font-weight:bold">MAX</span>.times {relay_verilog}
+ <span style="color:#036; font-weight:bold">MAX</span>.times {simulate}
<span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == <span style="color:#036; font-weight:bold">MAX</span>
<span style="color:#080; font-weight:bold">end</span>
specify <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">should overflow upon increment</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
- relay_verilog <span style="color:#888"># increment the counter</span>
+ simulate <span style="color:#888"># increment the counter</span>
<span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == <span style="color:#00D; font-weight:bold">0</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
</pre>
</div>
</div>
+
<div class="formal">
<div class="example" id="fig..counter_xunit_spec.rb">
- <p class="title">Example 6. Specification implemented in xUnit format</p>
+ <p class="title">Example 9. Specification implemented in xUnit format</p>
<pre class="code"><span style="color:#888"># This file is a behavioral specification for the design under test.</span>
<span style="color:#888"># lowest upper bound of counter's value</span>
@@ -1496,34 +1856,35 @@
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_increment</span>
<span style="color:#036; font-weight:bold">LIMIT</span>.times <span style="color:#080; font-weight:bold">do</span> |i|
assert_equal i, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
- relay_verilog <span style="color:#888"># increment the counter</span>
+ simulate <span style="color:#888"># increment the counter</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">class</span> <span style="color:#B06; font-weight:bold">MaximumCounterValue</span> < <span style="color:#036; font-weight:bold">Test</span>::<span style="color:#036; font-weight:bold">Unit</span>::<span style="color:#036; font-weight:bold">TestCase</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">setup</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#888"># increment the counter to maximum value</span>
- <span style="color:#036; font-weight:bold">MAX</span>.times {relay_verilog}
+ <span style="color:#036; font-weight:bold">MAX</span>.times {simulate}
assert_equal <span style="color:#036; font-weight:bold">MAX</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_overflow</span>
- relay_verilog <span style="color:#888"># increment the counter</span>
+ simulate <span style="color:#888"># increment the counter</span>
assert_equal <span style="color:#00D; font-weight:bold">0</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
</pre>
</div>
</div>
+
<div class="admonition">
<div class="important" id="important2">
<p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
@@ -1537,34 +1898,33 @@
<li>Replace the contents of the file named <tt>counter_xunit_spec.rb</tt> with the source code shown in <a href="#fig..counter_xunit_spec.rb">the example named “Specification implemented in xUnit format”</a>.</li>
<li>Replace the contents of the files named <tt>counter_rspec_design.rb</tt> and <tt>counter_xunit_design.rb</tt> with the following code. <pre class="code"><span style="color:#888"># This is a Ruby interface to the design under test.</span>
<span style="color:#888"># This method resets the design under test.</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#036; font-weight:bold">Counter</span>.reset!
- <span style="color:#888"># assert the reset signal for two clock cycles</span>
reset.intVal = <span style="color:#00D; font-weight:bold">1</span>
- <span style="color:#00D; font-weight:bold">2</span>.times {relay_verilog}
+ simulate
reset.intVal = <span style="color:#00D; font-weight:bold">0</span>
<span style="color:#080; font-weight:bold">end</span>
</pre></li>
</ol>
</div>
</div>
- <h3 id="usage.tutorial.implement-proto">Implement the prototype</h3>
+ <h3 id="usage.tutorial.implement-proto">5.6.4 Implement the prototype</h3>
<p>Now that we have a <a href="#glossary.specification">specification</a> against which to verify our <a href="#glossary.design">design</a>, let us build a prototype of our design. By doing so, we exercise our specification, experience potential problems that may arise when we later implement our design in Verilog, and gain confidence in our work. The result of this proceess is illustrated by <a href="#fig..counter_proto.rb">the example named “Ruby prototype of our Verilog design”</a>.</p>
<div class="formal">
<div class="example" id="fig..counter_proto.rb">
- <p class="title">Example 7. Ruby prototype of our Verilog design</p>
+ <p class="title">Example 10. Ruby prototype of our Verilog design</p>
<pre class="code">
<span style="color:#080; font-weight:bold">def</span> <span style="color:#036; font-weight:bold">Counter</span>.simulate!
<span style="color:#080; font-weight:bold">if</span> reset.intVal == <span style="color:#00D; font-weight:bold">1</span>
@@ -1576,10 +1936,11 @@
</pre>
</div>
</div>
+
<div class="admonition">
<div class="important" id="important3">
<p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
@@ -1593,21 +1954,21 @@
</div>
</div>
- <h3 id="usage.tutorial.test-proto">Verify the prototype</h3>
+ <h3 id="usage.tutorial.test-proto">5.6.5 Verify the prototype</h3>
<p>Now that we have implemented our prototype, we are ready to verify it against our <a href="#glossary.specification">specification</a> by running the <a href="#glossary.test">test</a>. This process is illustrated by <a href="#fig..test-proto.rspec">the example named “Running a test with specification in rSpec format”</a> and <a href="#fig..test-proto.unit-test">the example named “Running a test with specification in xUnit format”</a>.</p>
<div class="formal">
<div class="example" id="fig..test-proto.rspec">
- <p class="title">Example 8. Running a test with specification in rSpec format</p>
+ <p class="title">Example 11. Running a test with specification in rSpec format</p>
<pre>
$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
@@ -1626,15 +1987,16 @@
</pre>
</div>
</div>
+
<div class="formal">
<div class="example" id="fig..test-proto.unit-test">
- <p class="title">Example 9. Running a test with specification in xUnit format</p>
+ <p class="title">Example 12. Running a test with specification in xUnit format</p>
<pre>
$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1
@@ -1649,15 +2011,17 @@
</pre>
</div>
</div>
-In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> before running the test, by using your shell’s <strong>export</strong> or <strong>setenv</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.
+ <p>In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> before running the test, by using your shell’s <strong>export</strong> or <strong>setenv</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.</p>
+
+
<div class="admonition">
-<div class="tip" id="tip3">
+<div class="tip" id="tip4">
<p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
<p class="title">Tip: What can the test runner do?</p>
@@ -1668,21 +2032,21 @@
</div>
</div>
- <h3 id="usage.tutorial.implement-design">Implement the design</h3>
+ <h3 id="usage.tutorial.implement-design">5.6.6 Implement the design</h3>
<p>Now that we have implemented and verified our prototype, we are ready to implement our <a href="#glossary.design">design</a>. This is often quite simple because we translate <em>existing</em> code from Ruby (our prototype) into Verilog (our design). The result of this process is illustrated by <a href="#fig..counter.v_impl">the example named “Implementation of a simple up-counter with synchronous reset”</a>.</p>
<div class="formal">
<div class="example" id="fig..counter.v_impl">
- <p class="title">Example 10. Implementation of a simple up-counter with synchronous reset</p>
+ <p class="title">Example 13. Implementation of a simple up-counter with synchronous reset</p>
<pre class="code" lang="verilog">/**
A simple up-counter with synchronous reset.
@@ -1706,10 +2070,11 @@
</pre>
</div>
</div>
+
<div class="admonition">
<div class="important" id="important4">
<p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
@@ -1723,21 +2088,21 @@
</div>
</div>
- <h3 id="usage.tutorial.test-design">Verify the design</h3>
+ <h3 id="usage.tutorial.test-design">5.6.7 Verify the design</h3>
<p>Now that we have implemented our <a href="#glossary.design">design</a>, we are ready to verify it against our <a href="#glossary.specification">specification</a> by running the <a href="#glossary.test">test</a>. <a href="#fig..test-design.rspec">the example named “Running a test with specification in rSpec format”</a> and <a href="#fig..test-design.unit-test">the example named “Running a test with specification in xUnit format”</a> illustrate this process.</p>
<div class="formal">
<div class="example" id="fig..test-design.rspec">
- <p class="title">Example 11. Running a test with specification in rSpec format</p>
+ <p class="title">Example 14. Running a test with specification in rSpec format</p>
<pre>
$ rake -f counter_rspec_runner.rake cver
@@ -1754,15 +2119,16 @@
</pre>
</div>
</div>
+
<div class="formal">
<div class="example" id="fig..test-design.unit-test">
- <p class="title">Example 12. Running a test with specification in xUnit format</p>
+ <p class="title">Example 15. Running a test with specification in xUnit format</p>
<pre>
$ rake -f counter_xunit_runner.rake cver
@@ -1775,149 +2141,20 @@
</pre>
</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>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.</p>
- <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>
+ <h1 id="hacking">6 Hacking</h1>
-<div class="formal">
+ <h2 id="hacking.release-packages">6.1 Building release packages</h2>
-<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>
-
-
- <p class="title">Tip: Running multiple tests at once.</p>
-
-
- <p>Create a file named <tt>Rakefile</tt> containing the following line.</p>
-
-
- <blockquote>
- <p><code class="code">require <span style="background-color:#fff0f0"><span style="color:#710">'</span><span style="color:#D20">ruby-vpi/runner_proxy</span><span style="color:#710">'</span></span></code></p>
- </blockquote>
-
-
- <p>Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where <em>cver</em> denotes the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>).</p>
-
-
-</div>
-
-</div>
-
- <h3 id="usage.test-runner.env-vars">Environment variables</h3>
-
-
- <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>
-
-
<p>In addition to the <a href="#setup.reqs">normal requirements</a>, you need the following software to build release packages:</p>
<ul>
<li><a href="http://www.swig.org/"><span class="caps">SWIG</span></a></li>
@@ -1927,25 +2164,25 @@
<p>Once you have satisfied these requirements, you can run <pre>rake release</pre> to build the release packages. Also, see the output of <pre>rake -T</pre> for more build options.</p>
- <h1 id="problems">Known problems</h1>
+ <h1 id="problems">7 Known problems</h1>
<p>This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.</p>
- <h2 id="problems.ruby">Ruby</h2>
+ <h2 id="problems.ruby">7.1 Ruby</h2>
- <h3 id="problems.ruby.SystemStackError">SystemStackError</h3>
+ <h3 id="problems.ruby.SystemStackError">7.1.1 SystemStackError</h3>
<div class="admonition">
-<div class="note" id="note5">
+<div class="note" id="note6">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -1955,18 +2192,20 @@
</div>
</div>
-If a “stack level too deep (SystemStackError)” error occurs during the simulation, then increase the system-resource limit for stack-size by running the <pre>ulimit -s unlimited</pre> command before starting the simulation.
- <h3 id="problems.ruby.xUnit">test/unit</h3>
+ <p>If a “stack level too deep (SystemStackError)” error occurs during the simulation, then increase the system-resource limit for stack-size by running the <pre>ulimit -s unlimited</pre> command before starting the simulation.</p>
+ <h3 id="problems.ruby.xUnit">7.1.2 test/unit</h3>
+
+
<div class="admonition">
-<div class="note" id="note6">
+<div class="note" id="note7">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -1976,32 +2215,34 @@
</div>
</div>
-If your specification employs Ruby’s unit testing framework, then you will encounter an error saying “[BUG] cross-thread violation on rb_gc()”.
- <h2 id="problem.ivl">Icarus Verilog</h2>
+ <p>If your specification employs Ruby’s unit testing framework, then you will encounter an error saying “[BUG] cross-thread violation on rb_gc()”.</p>
- <h3 id="problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</h3>
+ <h2 id="problem.ivl">7.2 Icarus Verilog</h2>
- <h4 id="problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</h4>
+ <h3 id="problems.ivl.vpi_handle_by_name">7.2.1 Vpi::vpi_handle_by_name</h3>
+ <h4 id="problems.ivl.vpi_handle_by_name.absolute-paths">7.2.1.1 Give full paths to Verilog objects</h4>
+
+
<p>In version 0.8 and snapshot 20061009 of Icarus Verilog, the <code class="code">vpi_handle_by_name</code> function requires an <em>absolute</em> path (including the name of the bench which instantiates the design) to a Verilog object. In addition, <code class="code">vpi_handle_by_name</code> always returns <code class="code"><span style="color:#038; font-weight:bold">nil</span></code> when its second parameter is specified.</p>
<p>For example, consider <a href="#ex..TestFoo">the example named “Part of a bench which instantiates a Verilog design”</a>. Here, one must write <code class="code">vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">TestFoo.my_foo.clk</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)</code> instead of <code class="code">vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">my_foo.clk</span><span style="color:#710">"</span></span>, <span style="color:#036; font-weight:bold">TestFoo</span>)</code> in order to access the <code class="code">clk</code> input of the <code class="code">my_foo</code> module instance.</p>
<div class="formal">
<div class="example" id="ex..TestFoo">
- <p class="title">Example 15. Part of a bench which instantiates a Verilog design</p>
+ <p class="title">Example 16. Part of a bench which instantiates a Verilog design</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
@@ -2011,11 +2252,11 @@
</div>
</div>
- <h4 id="problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</h4>
+ <h4 id="problems.ivl.vpi_handle_by_name.connect-registers">7.2.1.2 Registers must be connected</h4>
<p>In version 0.8 of Icarus Verilog, if you want to access a register in a design, then it must be connected to something (either assigned to a wire or passed as a parameter to a module instantiation). Otherwise, you will get a <code class="code"><span style="color:#038; font-weight:bold">nil</span></code> value as the result of <code class="code">vpi_handle_by_name</code> method.</p>
@@ -2027,11 +2268,11 @@
<div class="formal">
<div class="example" id="ex..TestFoo_bad">
- <p class="title">Example 16. Bad design with unconnected registers</p>
+ <p class="title">Example 17. Bad design with unconnected registers</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
@@ -2042,15 +2283,16 @@
</div>
</div>
+
<div class="formal">
<div class="example" id="ex..TestFoo_fix">
- <p class="title">Example 17. Fixed design with wired registers</p>
+ <p class="title">Example 18. Fixed design with wired registers</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
@@ -2064,27 +2306,27 @@
</div>
</div>
- <h3 id="problems.ivl.vpi_reset">Vpi::reset</h3>
+ <h3 id="problems.ivl.vpi_reset">7.2.2 Vpi::reset</h3>
<div class="caution">The <code class="code">vpi_control</code> method was removed in release 3.0.0 (2006-04-23). Please use <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::vpi_control(<span style="color:#036; font-weight:bold">VpiReset</span>)</code> instead.</div>
<p>In version 0.8 of Icarus Verilog, the <code class="code">vpi_control(vpiReset)</code> VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.</p>
- <h2 id="problems.vsim">Mentor Modelsim</h2>
+ <h2 id="problems.vsim">7.3 Mentor Modelsim</h2>
- <h3 id="problems.vsim.ruby_run">ruby_run();</h3>
+ <h3 id="problems.vsim.ruby_run">7.3.1 ruby_run();</h3>
<div class="admonition">
-<div class="note" id="note7">
+<div class="note" id="note8">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -2094,49 +2336,51 @@
</div>
</div>
-Version 6.1b of Mentor Modelsim doesn’t play nicely with either an embedded Ruby interpreter or <span class="caps">POSIX</span> threads in a <span class="caps">PLI</span> application. When Ruby-VPI invokes the ruby_run function (which starts the Ruby interpreter), the simulator terminates immediately with an exit status of 0.
- <h1 id="glossary">Glossary</h1>
+ <p>Version 6.1b of Mentor Modelsim doesn’t play nicely with either an embedded Ruby interpreter or <span class="caps">POSIX</span> threads in a <span class="caps">PLI</span> application. When Ruby-VPI invokes the ruby_run function (which starts the Ruby interpreter), the simulator terminates immediately with an exit status of 0.</p>
- <h2 id="glossary.bench">Bench</h2>
+ <h1 id="glossary">8 Glossary</h1>
+ <h2 id="glossary.bench">8.1 Bench</h2>
+
+
<p>An environment in which a <a href="#glossary.design">design</a> is verified against a <a href="#glossary.specification">specification</a>. Often, it is used to emulate conditions in which the design will be eventually deployed.</p>
- <h2 id="glossary.BDD">Behavior driven development (BDD)</h2>
+ <h2 id="glossary.BDD">8.2 Behavior driven development (BDD)</h2>
<p>An <a href="http://agilemanifesto.org/">agile software development methodology</a> which emphasizes thinking in terms of behavior when designing, implementing, and verifying software.</p>
<p>See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
- <h2 id="glossary.design">Design</h2>
+ <h2 id="glossary.design">8.3 Design</h2>
<p>A Verilog module that is verified against a <a href="#glossary.specification">specification</a> in order to ensure correctness or soundness of its being. In other words, it is the thing being checked: does it work or not?</p>
- <h2 id="glossary.expectation">Expectation</h2>
+ <h2 id="glossary.expectation">8.4 Expectation</h2>
<p>The desired response to some stimulus.</p>
- <h2 id="glossary.handle">Handle</h2>
+ <h2 id="glossary.handle">8.5 Handle</h2>
<p>A reference to an object inside the Verilog simulation that was obtained through the <code class="code">vpi_handle_by_name</code> function.</p>
- <h2 id="glossary.rake">Rake</h2>
+ <h2 id="glossary.rake">8.6 Rake</h2>
<blockquote>
<p>Rake is a build tool, written in Ruby, using Ruby as a build language. Rake is similar to <strong>make</strong> in scope and purpose.</p>
</blockquote>
@@ -2145,40 +2389,40 @@
<blockquote>
<p style="text-align:right;">—<a href="http://docs.rubyrake.org">Rake documentation</a></p>
</blockquote>
- <h2 id="glossary.rspec">rSpec</h2>
+ <h2 id="glossary.rspec">8.7 rSpec</h2>
<p>The <a href="#glossary.BDD"><span class="caps">BDD</span></a> framework for Ruby.</p>
<p>See the <a href="http://rspec.rubyforge.org">rSpec website</a> and <a href="http://rspec.rubyforge.org/tutorials/index.html">tutorial</a> for more information.</p>
- <h2 id="glossary.specification">Specification</h2>
+ <h2 id="glossary.specification">8.8 Specification</h2>
<p>A set of <a href="#glossary.expectations">expectations</a> which define the desired behavior of a <a href="#glossary.design">design</a> when it is subjected to certain stimulus.</p>
- <h2 id="glossary.TDD">Test driven development (TDD)</h2>
+ <h2 id="glossary.TDD">8.9 Test driven development (TDD)</h2>
<p>An <a href="http://agilemanifesto.org/">agile software development methodology</a> which emphasizes (1) testing functionality before implementing it and (2) refactoring.</p>
<p>See <a href="http://www.agiledata.org/essays/tdd.html">this introductory article</a> for more information.</p>
- <h2 id="glossary.test">Test</h2>
+ <h2 id="glossary.test">9.0 Test</h2>
<p>Something that checks if a <a href="#glossary.design">design</a> satisfies a <a href="#glossary.specification">specification</a>.</p>
- <h2 id="glossary.test_bench">Test bench</h2>
+ <h2 id="glossary.test_bench">9.1 Test bench</h2>
<p>An allusion to <a href="#background.vocab">a bench in an electronics laboratory</a>, or so it seems.</p>
</body>
</html>