doc/manual.html in ruby-vpi-11.1.1 vs doc/manual.html in ruby-vpi-12.0.0
- old
+ new
@@ -5,11 +5,11 @@
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" type="text/css" href="common.css" />
<title>Ruby-VPI user manual</title>
</head>
<body>
-
+
<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>
@@ -18,17 +18,24 @@
<li><a href="#terms">Terms</a></li>
</ul>
</li>
<li><a href="#intro">Introduction</a>
<ul>
- <li><a href="#intro.features">Features</a></li>
+ <li><a href="#intro.features">Features</a>
+ <ul>
+ <li><a href="#intro.applications">Applications</a></li>
<li><a href="#intro.appetizers">Appetizers</a></li>
+ </ul>
+ </li>
<li><a href="#intro.license">License</a></li>
- <li><a href="#intro.related-works">Related works</a></li>
- <li><a href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li>
+ <li><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>
</ul>
</li>
+ </ul>
+ </li>
<li><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>
@@ -119,25 +126,89 @@
</ul>
</li>
<li><a href="#glossary">Glossary</a>
<ul>
<li><a href="#glossary.bench">Bench</a></li>
- <li><a href="#glossary.BDD"><span class="caps">BDD</span></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"><span class="caps">TDD</span></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>
</ul></li>
</ul>
- <h2>Examples</h2>
-<ol>
+
+ <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>
+ </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="#note6">Fixed in 2.0.0.</a></li>
+ <li><a href="#note7">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>
+ <li><a href="#important3">Before we continue…</a></li>
+ <li><a href="#important4">Before we continue…</a></li>
+ </ol>
+
+
+
+
+
+
+
+ <h1>Formals</h1>
+
+
+
+ <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>
+ </ol>
+
+
+
+ <h2>Tables</h2>
+ <ol>
+ <li><a href="#table1">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="#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>
@@ -150,127 +221,28 @@
<li><a href="#fig..test-design.unit-test">Running a test with specification in xUnit format</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>
-
- <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>
- </ol>
-
- <h2>Importants</h2>
-<ol>
- <li><a href="#important1">Before we continue…</a></li>
- <li><a href="#important2">Before we continue…</a></li>
- <li><a href="#important3">Before we continue…</a></li>
- <li><a href="#important4">Before we continue…</a></li>
- </ol>
-
- <h2>Notes</h2>
-<ol>
- <li><a href="#note1">Fixed in 2.0.0.</a></li>
- <li><a href="#note2">note2</a></li>
- <li><a href="#note3">note3</a></li>
- </ol>
-
- <h2>Sections</h2>
-<ol>
- <li><a href="#anchor0">Ruby-VPI user manual</a></li>
- <li><a href="#terms">Terms</a></li>
- <li><a href="#intro">Introduction</a></li>
- <li><a href="#intro.features">Features</a></li>
- <li><a href="#intro.appetizers">Appetizers</a></li>
- <li><a href="#intro.license">License</a></li>
- <li><a href="#intro.related-works">Related works</a></li>
- <li><a href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li>
- <li><a href="#background">Background</a></li>
- <li><a href="#background.methodology">Methodology</a></li>
- <li><a href="#background.vocab">Terminology</a></li>
- <li><a href="#background.org">Organization</a></li>
- <li><a href="#background.org.vpi">Interface to <span class="caps">VPI</span></a></li>
- <li><a href="#background.org.vpi.util"><span class="caps">VPI</span> utility layer</a></li>
- <li><a href="#background.running-tests">Running a test</a></li>
- <li><a href="#background.running-tests.init">Initialization</a></li>
- <li><a href="#background.running-tests.exec">Execution</a></li>
- <li><a href="#setup">Setup</a></li>
- <li><a href="#setup.manifest">Manifest</a></li>
- <li><a href="#setup.reqs">Requirements</a></li>
- <li><a href="#setup.recom">Recommendations</a></li>
- <li><a href="#setup.recom.merger">Text merging tool</a></li>
- <li><a href="#setup.installation">Installation</a></li>
- <li><a href="#setup.installation.windows">Installing on Windows</a></li>
- <li><a href="#setup.maintenance">Maintenance</a></li>
- <li><a href="#usage">Usage</a></li>
- <li><a href="#usage.tools">Tools</a></li>
- <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><a href="#usage.tutorial">Tutorial</a></li>
- <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><a href="#usage.examples">Examples</a></li>
- <li><a href="#hacking">Hacking</a></li>
- <li><a href="#hacking.release-packages">Building release packages</a></li>
- <li><a href="#problems">Known problems</a></li>
- <li><a href="#problems.ruby">Ruby</a></li>
- <li><a href="#problems.ruby.SystemStackError">SystemStackError</a></li>
- <li><a href="#problems.ruby.xUnit">test/unit</a></li>
- <li><a href="#problem.ivl">Icarus Verilog</a></li>
- <li><a href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a></li>
- <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><a href="#problems.ivl.vpi_reset">Vpi::reset</a></li>
- <li><a href="#problems.vsim">Mentor Modelsim</a></li>
- <li><a href="#problems.vsim.ruby_run">ruby_run();</a></li>
- <li><a href="#glossary">Glossary</a></li>
- <li><a href="#glossary.bench">Bench</a></li>
- <li><a href="#glossary.BDD"><span class="caps">BDD</span></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"><span class="caps">TDD</span></a></li>
- <li><a href="#glossary.test">Test</a></li>
- <li><a href="#glossary.test_bench">Test bench</a></li>
- </ol>
-
- <h2>Tables</h2>
-<ol>
- <li><a href="#table1">Possible accessors and their implications</a></li>
- </ol>
-
- <h2>Tips</h2>
-<ol>
- <li><a href="#tip1">tip1</a></li>
- <li><a href="#tip2">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
- <li><a href="#tip3">Reuse your specification.</a></li>
- <li><a href="#tip4">What can the test runner do?</a></li>
- <li><a href="#tip5">Running multiple tests at once.</a></li>
- </ol>
-
+
+
+
+
+
+
+
</div>
-
+
<div class="cover-page">
<h1 id="anchor0">Ruby-VPI user manual</h1>
<p>Suraj N. Kurapati</p>
- <p>Wed Nov 15 19:34:23 <span class="caps">PST 2006</span></p>
+ <p>Thu Dec 07 15:09:49 <span class="caps">PST 2006</span></p>
</div>
<h2 id="terms">Terms</h2>
@@ -297,16 +269,19 @@
<li>Supports the <em>entire</em> IEEE Std 1364-2005 <span class="caps">VPI</span> standard.</li>
</ul>
<ul>
- <li>Works with all <a href="manual.html#setup.reqs">major Verilog simulators</a> available today.</li>
+ <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>
+ </ul></li>
</ul>
<ul>
- <li>Enables <a href="http://www.agilealliance.org/intro">agile practices</a> such as
+ <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>
<li><a href="manual.html#usage.tutorial.implement-proto">rapid prototyping</a> for design exploration</li>
</ul></li>
@@ -327,27 +302,44 @@
<ul>
<li>Unlimited length integers</li>
<li>Regular expressions</li>
<li>Multi-threading</li>
<li>System calls and I/O</li>
- <li><a href="http://rubyforge.org"><em>ad infinium</em></a></li>
+ <li><a href="http://rubyforge.org"><em>ad infinitum</em></a></li>
</ul></li>
</ul>
<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>
- <h2 id="intro.appetizers">Appetizers</h2>
+ <h3 id="intro.applications">Applications</h3>
- <p>Here is a modest sampling to whet your appetite.</p>
+ <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>
<ul>
+ <li>Writing hardware models in Ruby</li>
+ <li>Dumping/processing netlist data from Verilog database</li>
+ <li>Dumping/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>
+
+
+ <h3 id="intro.appetizers">Appetizers</h3>
+
+
+ <p>Here is a modest sampling of code to whet your appetite.</p>
+
+
+ <ul>
<li>Assign the value 2<sup>2048</sup> to a register:</li>
</ul>
<blockquote>
@@ -401,11 +393,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>
- <h2 id="intro.related-works.pli">Ye olde <span class="caps">PLI</span></h2>
+ <h3 id="intro.related-works.pli">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>
@@ -423,40 +415,40 @@
<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.</p>
+ <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>
<div class="admonition">
-<div class="tip" id="tip1">
+<div class="note" id="note1">
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
+ <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
- <p class="title">Tip:</p>
+ <p class="title">Note:</p>
<p>Have a look at the <a href="#glossary">glossary</a> for definitions of terms used in this manual.</p>
</div>
</div>
- <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 flipped through my textbook and surfed the Internet for a definition of the term, but it was to no avail. Instead, both resources nonchalantly employed the term <em>throughout</em> their being, as if mocking my ignorance of what seems to be universal knowledge.</p>
+ <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, trying 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>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>
@@ -475,13 +467,16 @@
</div>
</div>
- <p>As <a href="#fig..organization">the figure named “Overall organization of a test”</a> shows, a test is composed of a bench, a design, and a specification. To extend the <a href="#background.vocab">analogy of an electronics laboratory</a>, the first acts as the laboratory bench which provides measurement and manipulation tools. The second acts as the electronic component being verified by the engineer. And the third 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>
+ <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>
+
+
<h3 id="background.org.vpi">Interface to <span class="caps">VPI</span></h3>
<div class="formal">
@@ -495,13 +490,16 @@
</div>
</div>
- <p>In <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>, Ruby-VPI acts as the bench, a Verilog simulator encapsulates the design, and a Ruby interpreter encapsulates the specification. 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>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>
+ <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>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>
<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>
@@ -525,14 +523,14 @@
</pre>
<h4 id="background.org.vpi.util"><span class="caps">VPI</span> utility layer</h4>
- <p>From a user’s perspective, the <span class="caps">VPI</span> utility layer greatly enhances the ability to interact with handles. 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>
+ <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>
- <p>The children of a handle are simply the handles that are immediately contained within it in. For example, suppose that you had a Verilog module that contains some registers. The children, of a handle to the module, would be handles to the registers.</p>
+ <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>
<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>
@@ -966,47 +964,47 @@
</div>
<h2 id="background.running-tests">Running a test</h2>
- <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 objects in a simulation when a test is run. In particular, they take turns manipulating the design and transfer control to each other when appropriate.</p>
+ <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>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">
<p class="title">Figure 4. Initialization of a test</p>
<p><img src="figures/ruby_init.png" alt="" /></p>
-</div>
-
-</div>
-
- <p>A test is first initialized before it is <a href="#background.running-tests.exec">executed</a>. <a href="#fig..ruby_init">the figure named “Initialization of a test”</a> illustrates the initialization process <a href="#proc..ruby_init">described below</a>.</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>
+</div>
+
+</div>
+
<h3 id="background.running-tests.exec">Execution</h3>
- <p>After a test is <a href="#background.running-tests.init">initialized</a>, it is executed such that the design is verified against the specification. <a href="#fig..ruby_relay">the figure named “Execution of a test”</a> illustrates the execution process <a href="#proc..ruby_relay">described below</a>.</p>
+ <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>
<div class="formal">
<div class="figure" id="fig..ruby_relay">
@@ -1015,21 +1013,21 @@
<p><img src="figures/ruby_relay.png" alt="" /></p>
-</div>
-
-</div>
-
<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>
<h2 id="setup.manifest">Manifest</h2>
@@ -1058,19 +1056,36 @@
– 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 or newer is acceptable.</li>
+ – 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>
@@ -1138,42 +1153,45 @@
<ul>
<li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
</ul>
- <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' > /dev/null && 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>
-
-
<div class="admonition">
<div class="note" id="note2">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
- <p class="title">Note:</p>
+ <p class="title">Note: Undefined symbols in Windows</p>
- <p>Since Ruby-VPI makes use of the <span class="caps">VPI C</span>-language interface, it links to symbols whose names begin with “_vpi”. It is possible for these symbols to be undefined when Ruby-VPI is compiled under <span class="caps">GNU</span>/Linux and similar operating systems. In contrast, one <a href="http://sourceware.org/ml/cygwin/2001-12/msg01293.html">cannot compile a shared object file with references to undefined symbols under Windows</a>. Thus, we must find a Verilog simulator’s shared object file, which contains definitions of all <span class="caps">VPI</span> symbols, and give this file to the linker when compiling Ruby-VPI.</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>
@@ -1211,22 +1229,22 @@
<h2 id="usage.tools">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>
+ <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>-h</tt> option.</p>
<h3 id="usage.tools.generate-test">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>
<ul>
<li>Runner
- – written in Rake, this file builds and runs the test.</li>
+ – written in <a href="#glossary.rake">Rake</a>, this file builds and runs the test.</li>
<li>Bench
– written in Verilog and Ruby, these files define the testing environment.</li>
<li>Design
– written in Ruby, this file provides an interface to the design being verified.</li>
<li>Prototype
@@ -1234,11 +1252,11 @@
<li>Specification
– written in Ruby, this file describes the expected behavior of the design.</li>
</ul>
- <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">text merging tool</a>) into the test without diverting your focus from the specification.</p>
+ <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">
@@ -1259,11 +1277,11 @@
<li>Place the file somewhere accessible by your <code class="code"><span style="color:#036; font-weight:bold">PATH</span></code> environment variable.</li>
<li>Assign the value “merge2” to the <code class="code"><span style="color:#036; font-weight:bold">MERGER</span></code> environment variable using your shell’s <strong>export</strong> or <strong>setenv</strong> command.</li>
</ol>
- <p>From now on, <strong>kdiff3</strong> will be invoked to help you transfer your changes between generated files. When you are finished transferring changes, simply issue the “save the file” command and terminate <strong>kdiff3</strong>. Or, if you do not want to transfer any changes, simply terminate <strong>kdiff3</strong>.</p>
+ <p>From now on, <strong>kdiff3</strong> will be invoked to help you transfer your changes between generated files. When you are finished transferring changes, simply issue the “save the file” command and quit <strong>kdiff3</strong>. Or, if you do not want to transfer any changes, simply quit <strong>kdiff3</strong> <em>without</em> saving the file.</p>
</div>
</div>
@@ -1272,10 +1290,13 @@
<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>
<ol>
<li><a href="#usage.tutorial.declare-design">Declare the design</a>, which is a Verilog module, using Verilog 2001 syntax.</li>
@@ -1351,16 +1372,30 @@
<li>xUnit represents <a href="#glossary.TDD"><span class="caps">TDD</span></a></li>
<li>our own format can represent another methodology</li>
</ul>
- <p>Both rSpec and xUnit are presented in this tutorial.</p>
+<div class="admonition">
+<div class="note" id="note4">
- <p>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <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> illustrate this process.</p>
+ <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p class="title">Note:</p>
+
+
+ <p>Both rSpec and xUnit formats are presented in this tutorial.</p>
+
+
+</div>
+
+</div>
+
+ <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>
@@ -1417,11 +1452,11 @@
<li>A resetted counter’s value should increment by one count upon each rising clock edge.</li>
<li>A counter with the maximum value should overflow upon increment.</li>
</ul>
- <p>Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. <a href="#fig..counter_rspec_spec.rb">the example named “Specification implemented in rSpec format”</a> and <a href="#fig..counter_xunit_spec.rb">the example named “Specification implemented in xUnit format”</a> illustrate this process. Note the striking similarities between our expectations and their implementation.</p>
+ <p>Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. This process is illustrated by <a href="#fig..counter_rspec_spec.rb">the example named “Specification implemented in rSpec format”</a> and <a href="#fig..counter_xunit_spec.rb">the example named “Specification implemented in xUnit format”</a>.</p>
<div class="formal">
<div class="example" id="fig..counter_rspec_spec.rb">
@@ -1441,16 +1476,16 @@
setup <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<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 be zero</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
- <span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should_equal <span style="color:#00D; font-weight:bold">0</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>
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_equal i
+ <span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == i
relay_verilog <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>
@@ -1458,16 +1493,16 @@
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">Counter</span>.count.intVal.should_equal <span style="color:#036; font-weight:bold">MAX</span>
+ <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>
- <span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should_equal <span style="color:#00D; font-weight:bold">0</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>
@@ -1537,17 +1572,17 @@
<ol>
<li>Replace the contents of the file named <tt>counter_rspec_spec.rb</tt> with the source code shown in <a href="#fig..counter_rspec_spec.rb">the example named “Specification implemented in rSpec format”</a>.</li>
<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. This code defines the reset! method which resets our Verilog design. <pre class="code">
+ <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 five clock cycles</span>
reset.intVal = <span style="color:#00D; font-weight:bold">1</span>
-
- <span style="color:#888"># simulate one clock cycle</span>
- relay_verilog
-
+ <span style="color:#00D; font-weight:bold">5</span>.times {relay_verilog}
reset.intVal = <span style="color:#00D; font-weight:bold">0</span>
<span style="color:#080; font-weight:bold">end</span>
</pre></li>
</ol>
@@ -1557,11 +1592,11 @@
</div>
<h3 id="usage.tutorial.implement-proto">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. <a href="#fig..counter_proto.rb">the example named “Ruby prototype of our Verilog design”</a> shows the completed prototype for our design.</p>
+ <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">
@@ -1601,50 +1636,13 @@
</div>
<h3 id="usage.tutorial.test-proto">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>. <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> illustrate this process.</p>
+ <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="admonition">
-
-<div class="tip" id="tip3">
-
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
-
-
- <p class="title">Tip: Reuse your specification.</p>
-
-
- <p>The <em>same</em> specification can be used to verify both prototype and design.</p>
-
-
-</div>
-
-</div>
-
- <p>Here, 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 Icarus Verilog simulator, denoted by <em>cver</em>, is used to run the simulation.</p>
-
-
-<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: What can the test runner do?</p>
-
-
- <p>If you invoke the test runner (1) without any arguments or (2) with the <tt>-T</tt> option, it will show you a list of tasks that it can perform for you.</p>
-
-
-</div>
-
-</div>
-
<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>
@@ -1693,14 +1691,34 @@
</div>
</div>
+ <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">
+
+ <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>
+
+
+ <p>If you invoke the test runner (1) without any arguments or (2) with the <tt>-T</tt> option, it will show you a list of tasks that it can perform for you.</p>
+
+
+</div>
+
+</div>
+
<h3 id="usage.tutorial.implement-design">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). <a href="#fig..counter.v_impl">the example named “Implementation of a simple up-counter with synchronous reset”</a> illustrates the result of this process. Once again, note the striking similarities between the implementation of our prototype and design.</p>
+ <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">
@@ -1755,38 +1773,10 @@
<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>
- <p>Here, 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 <span class="caps">GPL</span> Cver Verilog simulator, denoted by <em>cver</em>, is used to run the simulation.</p>
-
-
-<div class="admonition">
-
-<div class="tip" id="tip5">
-
- <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 <span class="caps">GPL</span> Cver simulator).</p>
-
-
-</div>
-
-</div>
-
<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>
@@ -1831,26 +1821,51 @@
</div>
</div>
- <h2 id="usage.examples">Examples</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>The <tt>samp</tt> directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.</p>
+<div class="admonition">
+<div class="tip" id="tip4">
- <p>Also, some example specifications make use of <span class="caps">BDD</span> through the rSpec library. See <a href="#background.methodology">the section named “Methodology”</a> for a discussion of rSpec.</p>
+ <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>
+
+ <h2 id="usage.examples">Examples</h2>
+
+
+ <p>The <tt>samp</tt> directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.</p>
+
+
<h1 id="hacking">Hacking</h1>
<h2 id="hacking.release-packages">Building release packages</h2>
- <p>In addition to the <a href="./doc/usage.requirements.html">normal requirements</a>, you need the following software to build release packages:</p>
+ <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>
<li><a href="http://rubyforge.org/projects/redcloth/">RedCloth</a></li>
@@ -1873,18 +1888,21 @@
<h3 id="problems.ruby.SystemStackError">SystemStackError</h3>
<div class="admonition">
-<div class="note" id="note1">
+<div class="note" id="note5">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
+ <p>This problem was fixed in release 2.0.0 (2006-04-17).</p>
+
+
</div>
</div>
<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>
@@ -1893,18 +1911,21 @@
<h3 id="problems.ruby.xUnit">test/unit</h3>
<div class="admonition">
-<div class="note" id="note1">
+<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>
+ <p>This problem was fixed in release 2.0.0 (2006-04-17).</p>
+
+
</div>
</div>
<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>
@@ -1917,14 +1938,14 @@
<h4 id="problems.ivl.vpi_handle_by_name.absolute-paths">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> is unable to retrieve the handle for a module parameter.</p>
+ <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 needs to specify <code class="code"><span style="color:#036; font-weight:bold">TestFoo</span>.my_foo.clk</code> instead of <code class="code">my_foo.clk</code> in order to access the clk input of the my_foo module instance.</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">
@@ -2011,18 +2032,21 @@
<h3 id="problems.vsim.ruby_run">ruby_run();</h3>
<div class="admonition">
-<div class="note" id="note1">
+<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>
+ <p>This problem was fixed in release 2.0.0 (2006-04-17).</p>
+
+
</div>
</div>
<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>
@@ -2035,23 +2059,23 @@
<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"><span class="caps">BDD</span></h2>
+ <h2 id="glossary.BDD">Behavior driven development (BDD)</h2>
- <p>Behavior driven development.</p>
+ <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>A software development methodology which emphasizes thinking in terms of behavior when designing, implementing, and verifying software. See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
+ <p>See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
<h2 id="glossary.design">Design</h2>
- <p>An idea or entity 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>
+ <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>
@@ -2059,39 +2083,47 @@
<h2 id="glossary.handle">Handle</h2>
- <p>An object in a Verilog simulation. For example, a handle can represent a wire, register, module, if-statement, expression, and so on.</p>
+ <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>
<blockquote>
- <p>Rake is a build tool, written in Ruby, using Ruby as a build language. Rake is similar to make in scope and purpose. —<a href="http://docs.rubyrake.org">Rake documentation</a></p>
+ <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>
- <p>See the <a href="http://rake.rubyforge.org">Rake website</a> for more information.</p>
+ <blockquote>
+ <p style="text-align:right;">—<a href="http://docs.rubyrake.org">Rake documentation</a></p>
+ </blockquote>
<h2 id="glossary.rspec">rSpec</h2>
- <p>Ruby framework for <span class="caps">BDD</span>. 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>
+ <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>
- <p>A set of <a href="#glossary.expectations">expectation</a> which define the desired behavior of a <a href="#glossary.design">design</a> when it is subjected to certain conditions.</p>
+ <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"><span class="caps">TDD</span></h2>
+ <h2 id="glossary.TDD">Test driven development (TDD)</h2>
- <p>Test Driven Development.</p>
+ <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>