doc/manual.html in ruby-vpi-15.0.2 vs doc/manual.html in ruby-vpi-16.0.0
- old
+ new
@@ -6,162 +6,21 @@
<link rel="stylesheet" type="text/css" href="print.css" media="print" />
<link rel="alternate" type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml" title="RSS feed for this project." />
<title>Ruby-VPI user manual</title>
</head>
<body>
+ <h1 style="margin-top: 0">Ruby-VPI user manual</h1>
- <br/><br/> <!-- give space below #menu -->
+ <p style="text-align:center;"><a href="readme.html"><img src="images/tango/home.png" title="Return to main page" alt="Return to main page" /></a></p>
- <p style="text-align:center;"><a href="readme.html"><img src="images/home.png" title="Return to main page" alt="Return to main page" /></a></p>
-
<div id="menu">
<a href="#index">Contents</a> · <a href="#figures">Figures</a> · <a href="#tables">Tables</a> · <a href="#examples">Examples</a> · <a href="#tips">Tips</a> · <a href="#notes">Notes</a> · <a href="#importants">Importants</a>
</div>
<div id="index">
<h1>Contents</h1>
- <ul>
- <li>1 <a href="#anchor4">Ruby-VPI user manual</a>
- <ul>
- <li>1.1 <a href="#terms">Terms</a></li>
- </ul>
- </li>
- <li>2 <a href="#intro">Introduction</a>
- <ul>
- <li>2.1 <a href="#intro.features">Prominent features</a>
- <ul>
- <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>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>2.5.1 <a href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li>3 <a href="#background">Background</a>
- <ul>
- <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>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>4.3.1 <a href="#setup.recom.merger">Text merging tool</a></li>
- </ul>
- </li>
- <li>4.4 <a href="#setup.installation">Installation</a>
- <ul>
- <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>5 <a href="#usage">Usage</a>
- <ul>
- <li>5.1 <a href="#usage.vpi"><span class="caps">VPI</span> in Ruby</a>
- <ul>
- <li>5.1.1 <a href="#usage.vpi.handles">Handles</a>
- <ul>
- <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>5.1.2 <a href="#usage.vpi.callbacks">Callbacks</a></li>
- </ul>
- </li>
- <li>5.2 <a href="#usage.prototyping">Prototyping</a></li>
- <li>5.3 <a href="#usage.debugger">Debugging</a>
- <ul>
- <li>5.3.1 <a href="#usage.debugger.init">Advanced initialization</a></li>
- </ul>
- </li>
- <li>5.4 <a href="#usage.test-runner">Test runner</a>
- <ul>
- <li>5.4.1 <a href="#usage.test-runner.env-vars">Environment variables</a></li>
- </ul>
- </li>
- <li>5.5 <a href="#usage.examples">Sample tests</a></li>
- <li>5.6 <a href="#usage.tools">Tools</a>
- <ul>
- <li>5.6.1 <a href="#usage.tools.generate-test">Automated test generation</a></li>
- <li>5.6.2 <a href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li>
- </ul>
- </li>
- <li>5.7 <a href="#usage.tutorial">Tutorial</a>
- <ul>
- <li>5.7.1 <a href="#usage.tutorial.declare-design">Start with a design</a></li>
- <li>5.7.2 <a href="#usage.tutorial.generate-test">Generate a test</a></li>
- <li>5.7.3 <a href="#usage.tutorial.specification">Specify your expectations</a></li>
- <li>5.7.4 <a href="#usage.tutorial.implement-proto">Implement the prototype</a></li>
- <li>5.7.5 <a href="#usage.tutorial.test-proto">Verify the prototype</a></li>
- <li>5.7.6 <a href="#usage.tutorial.implement-design">Implement the design</a></li>
- <li>5.7.7 <a href="#usage.tutorial.test-design">Verify the design</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li>6 <a href="#hacking">Hacking</a>
- <ul>
- <li>6.1 <a href="#hacking.release-packages">Building release packages</a></li>
- </ul>
- </li>
- <li>7 <a href="#problems">Known problems</a>
- <ul>
- <li>7.1 <a href="#problems.ruby">Ruby</a>
- <ul>
- <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>7.2 <a href="#problem.ivl">Icarus Verilog</a>
- <ul>
- <li>7.2.1 <a href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a>
- <ul>
- <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>7.2.2 <a href="#problems.ivl.vpi_reset">Vpi::reset</a></li>
- </ul>
- </li>
- <li>7.3 <a href="#problems.vsim">Mentor Modelsim</a>
- <ul>
- <li>7.3.1 <a href="#problems.vsim.ruby_run">ruby_run();</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li>8 <a href="#glossary">Glossary</a>
- <ul>
- <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>
+ <ul><li><a id="a-606992228" href="#Ruby-VPI_user_manual">Ruby-VPI user manual</a><ul><li><a id="a-606993518" href="#legal">Legalities</a></li></ul></li><li><a id="a-606994448" href="#intro">Introduction</a><ul><li><a id="a-606995298" href="#Resources">Resources</a></li><li><a id="a-606996238" href="#intro.features">Features</a></li><li><a id="a-606997278" href="#intro.reqs">Requirements</a></li><li><a id="a-606998228" href="#intro.applications">Applications</a></li><li><a id="a-606999338" href="#intro.appetizers">Appetizers</a></li><li><a id="a-607000438" href="#intro.license">License</a></li><li><a id="a-606014748" href="#intro.related-works">Related works</a><ul><li><a id="a-606035648" href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li></ul></li></ul></li><li><a id="a-606053288" href="#background">Background</a><ul><li><a id="a-606069898" href="#background.methodology">Methodology</a></li><li><a id="a-606106808" href="#background.vocab">Terminology</a></li><li><a id="a-606127698" href="#background.org">Organization</a></li><li><a id="a-606150238" href="#background.relay">Ruby/Verilog interaction</a></li></ul></li><li><a id="a-606180548" href="#setup">Setup</a><ul><li><a id="a-606192588" href="#setup.manifest">Manifest</a></li><li><a id="a-606206048" href="#setup.reqs">Requirements</a></li><li><a id="a-606213438" href="#setup.recom">Recommendations</a><ul><li><a id="a-606235588" href="#setup.recom.merger">Text merging tool</a></li></ul></li><li><a id="a-606251368" href="#setup.installation">Installation</a><ul><li><a id="a-606273678" href="#setup.installation.windows">Installing on Windows</a></li></ul></li><li><a id="a-606278328" href="#setup.maintenance">Maintenance</a></li></ul></li><li><a id="a-606285848" href="#usage">Usage</a><ul><li><a id="a-606290248" href="#usage.vpi"><span class="caps">VPI</span> in Ruby</a><ul><li><a id="a-606294778" href="#usage.vpi.handles">Handles</a><ul><li><a id="a-606297428" href="#Accessing_a_handle__8217_s_relatives">Accessing a handle’s relatives</a></li><li><a id="a-606305088" href="#Accessing_a_handle__8217_s_properties">Accessing a handle’s properties</a></li></ul></li><li><a id="a-605776528" href="#usage.vpi.callbacks">Callbacks</a></li></ul></li><li><a id="a-605820298" href="#usage.prototyping">Prototyping</a></li><li><a id="a-605856998" href="#usage.debugger">Debugging</a><ul><li><a id="a-605861038" href="#usage.debugger.init">Advanced initialization</a></li></ul></li><li><a id="a-605886638" href="#usage.test-runner">Test runner</a><ul><li><a id="a-605692898" href="#usage.test-runner.env-vars">Environment variables</a></li></ul></li><li><a id="a-605713518" href="#usage.examples">Sample tests</a></li><li><a id="a-605735618" href="#usage.tools">Tools</a><ul><li><a id="a-606420358" href="#usage.tools.generate-test">Automated test generation</a></li><li><a id="a-606426458" href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li></ul></li><li><a id="a-606430138" href="#usage.tutorial">Tutorial</a><ul><li><a id="a-606439718" href="#usage.tutorial.declare-design">Start with a design</a></li><li><a id="a-606447618" href="#usage.tutorial.generate-test">Generate a test</a></li><li><a id="a-606455858" href="#usage.tutorial.specification">Specify your expectations</a></li><li><a id="a-606466508" href="#usage.tutorial.implement-proto">Implement the prototype</a></li><li><a id="a-606469388" href="#usage.tutorial.test-proto">Verify the prototype</a></li><li><a id="a-606472858" href="#usage.tutorial.implement-design">Implement the design</a></li><li><a id="a-606480598" href="#usage.tutorial.test-design">Verify the design</a></li></ul></li></ul></li><li><a id="a-606487878" href="#hacking">Hacking</a><ul><li><a id="a-606495208" href="#hacking.scm">Getting the source code</a></li><li><a id="a-606502868" href="#hacking.release-packages">Building release packages</a></li></ul></li><li><a id="a-606510668" href="#problems">Known problems</a><ul><li><a id="a-606514648" href="#problems.ruby">Ruby</a><ul><li><a id="a-606529698" href="#problems.ruby.SystemStackError">SystemStackError</a></li><li><a id="a-606545738" href="#problems.ruby.xUnit">test/unit</a></li></ul></li><li><a id="a-606557578" href="#problem.ivl">Icarus Verilog</a><ul><li><a id="a-606563378" href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a><ul><li><a id="a-606577748" href="#problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</a></li><li><a id="a-606588618" href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li></ul></li><li><a id="a-606593458" href="#problems.ivl.vpi_reset">Vpi::reset</a></li></ul></li><li><a id="a-606596948" href="#problems.vsim">Mentor Modelsim</a><ul><li><a id="a-606600738" href="#problems.vsim.ruby_run">ruby_run();</a></li></ul></li></ul></li><li><a id="a-606604778" href="#glossary">Glossary</a><ul><li><a id="a-606606678" href="#glossary.bench">Bench</a></li><li><a id="a-606613558" href="#glossary.BDD">Behavior driven development (BDD)</a></li><li><a id="a-606620958" href="#glossary.design">Design</a></li><li><a id="a-606623008" href="#glossary.expectation">Expectation</a></li><li><a id="a-606624858" href="#glossary.handle">Handle</a></li><li><a id="a-606628418" href="#glossary.rake">Rake</a></li><li><a id="a-606630878" href="#glossary.rspec">rSpec</a></li><li><a id="a-606636388" href="#glossary.specification">Specification</a></li><li><a id="a-606640878" href="#glossary.TDD">Test driven development (TDD)</a></li><li><a id="a-606643148" href="#glossary.test">Test</a></li><li><a id="a-606646838" href="#glossary.test_bench">Test bench</a></li></ul></li></ul>
<h1>Formals</h1>
<h2 id="figures">Figures</h2>
<ol>
@@ -221,14 +80,14 @@
<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>
</div>
- <h1 id="anchor4">1 Ruby-VPI user manual</h1>
+ <h1><a id="Ruby-VPI_user_manual" href="#a-606992228">1</a> Ruby-VPI user manual</h1>
- <p>This manual was last updated on Mon Jan 22 16:30:33 <span class="caps">PST 2007</span>.</p>
+ <p>This manual was last updated on Wed May 02 23:05:05 <span class="caps">PDT 2007</span>.</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>
@@ -236,28 +95,59 @@
<p><em>Happy reading!</em></p>
- <h2 id="terms">1.1 Terms</h2>
+ <h2 ><a id="legal" href="#a-606993518">1.1</a> Legalities</h2>
- <p>Copyright© 2006, 2007 Suraj N. Kurapati.</p>
+ <p>This manual is distributed under <a href="#intro.license">the same license as Ruby-VPI</a>.</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>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/tango/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 ><a id="intro" href="#a-606994448">2</a> Introduction</h1>
- <h1 id="intro">2 Introduction</h1>
+ <p>Ruby-VPI is a platform for unit testing, rapid prototyping, and systems integration of Verilog modules through the <a href="http://www.ruby-lang.org">Ruby programming language</a>. It lets you:</p>
- <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>
+ <ul>
+ <li>Access the <em>entire</em> <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> interface from Ruby.</li>
+ <li>Create complex Verilog test benches easily and wholly in Ruby.</li>
+ <li>Apply agile software development practices to develop hardware.</li>
+ <li>Perform <a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.html">specification-driven functional verification</a> (<a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.pdf"><span class="caps">PDF</span> version</a>).</li>
+ </ul>
+ <p>Ruby-VPI is <a href="http://en.wikipedia.org/wiki/Open_source_software">open source software</a> released under <a href="#intro.license">this license</a>.</p>
+
+
+<div id="resources">
+
+ <h2><a id="Resources" href="#a-606995298">2.1</a> Resources</h2>
+
+
+ <p class="title">Records</p>
+
+
+ <p><a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon-28x28.png" alt="RSS feed for release notifications" style="float: right"/></a></p>
+
+
+ <ul>
+ <li><a href="history.html">What’s new?</a>
+ – a record of all release notes.</li>
+ <li><a href="memo.html">Plans</a>
+ – pending tasks for future releases.</li>
+ <li><a href="http://ruby-vpi.rubyforge.org/talks/">Talks</a>
+ – materials from presentations and seminars.</li>
+ <li><a href="http://ruby-vpi.rubyforge.org/papers/">Papers</a>
+ – research publications.</li>
+ </ul>
+
+
<p class="title">Documentation</p>
<ul>
<li><a href="manual.html#usage.tutorial">Tutorial</a>
@@ -267,77 +157,49 @@
<li><a href="../ref/">Reference</a>
– <span class="caps">API</span> documentation for Ruby libraries and C extension.</li>
</ul>
- <p class="title">Records</p>
-
-
- <ul>
- <li><a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon.png" title="RSS feed icon" alt="RSS feed icon" /> RSS feed</a>
- – keep track of new releases at your leisure.</li>
- <li><a href="history.html">Release history</a>
- – record of all release notes.</li>
- <li><a href="memo.html">Memorandum</a>
- – pending tasks for future releases.</li>
- </ul>
-
-
<p class="title">Facilities</p>
<ul>
- <li><a href="http://rubyforge.org/projects/ruby-vpi">Project portal</a>
- – hosted generously by <a href="http://rubyforge.org">RubyForge</a>.</li>
- <li><a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi">Source code</a>
- – browse online or obtain through <a href="http://abridgegame.org/darcs/">Darcs</a>.</li>
- <li><a href="http://rubyforge.org/frs/?group_id=1339">Downloads</a>
+ <li><a href="http://rubyforge.org/frs/?group_id=1339">Downloads</a>
– obtain release packages.</li>
+ <li><a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi">Source code</a>
+ – browse online or obtain with <a href="http://darcs.net">Darcs</a>.</li>
+ <li><a href="http://rubyforge.org/forum/?group_id=1339">Forums</a>
+ – discuss things and ask questions.</li>
<li><a href="http://rubyforge.org/tracker/?group_id=1339">Bugs</a>
– report defects in the software.</li>
<li><a href="http://rubyforge.org/tracker/?group_id=1339">Patches</a>
– submit patches to source code.</li>
<li><a href="http://rubyforge.org/tracker/?group_id=1339">Requests</a>
– request new features or get support.</li>
- <li><a href="http://rubyforge.org/forum/?group_id=1339">Forums</a>
- – discuss things and ask questions.</li>
+ <li><a href="http://rubyforge.org/projects/ruby-vpi">Project portal</a>
+ – hosted generously by <a href="http://rubyforge.org">RubyForge</a>.</li>
</ul>
- <p class="title">Outreach</p>
+</div>
+ <h2 ><a id="intro.features" href="#a-606996238">2.2</a> Features</h2>
- <ul>
- <li><a href="http://ruby-vpi.rubyforge.org/news">News</a>
- – see what’s cooking for the next release.</li>
- <li><a href="http://ruby-vpi.rubyforge.org/talks">Talks</a>
- – materials from presentations and seminars.</li>
- </ul>
+ <p class="title">Portable</p>
- <h2 id="intro.features">2.1 Prominent 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>
+ <li>Supports the <em>entire</em> <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> standard.</li>
+ <li>Works with all <a href="#intro.reqs">major Verilog simulators</a> available today.</li>
+ <li>Compiled <em>just once</em> during <a href="manual.html#setup.installation">installation</a> and used forever!</li>
</ul>
- <ul>
- <li>Works with all <a href="manual.html#setup.reqs">major Verilog simulators</a> available today.
- <ul>
- <li>Compiled <em>just once</em> during <a href="manual.html#setup.installation">installation</a> and used forever!</li>
- </ul></li>
- </ul>
+ <p class="title">Agile</p>
- <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>
@@ -354,11 +216,11 @@
<li>There is absolutely <em>no compiling</em>!</li>
</ul></li>
</ul>
- <h3 id="anchor7">2.1.3 Powerful</h3>
+ <p class="title">Powerful</p>
<ul>
<li>Inherits the <a href="http://www.ruby-lang.org/en/about/">power and elegance</a> of Ruby:
<ul>
@@ -375,25 +237,95 @@
<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>
+ <h2 ><a id="intro.reqs" href="#a-606997278">2.3</a> Requirements</h2>
+ <p>The following software is necessary in order to use Ruby-VPI.</p>
+
+
+ <p class="title">Verilog simulator</p>
+
+
+ <p>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>.</p>
+
+
<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>
+ <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>
</ul>
- <h2 id="intro.applications">2.2 Applications</h2>
+ <ul>
+ <li><a href="http://www.model.com">Mentor Modelsim</a>
+ – any version that supports the <tt>-pli</tt> option is acceptable.</li>
+ </ul>
- <p>Here is a modest sampling of tasks that Ruby-VPI can be used to perform.</p>
+ <ul>
+ <li><a href="http://www.cadence.com/products/functional_ver/nc-verilog/">Cadence NC-Sim / NC-Verilog</a>
+ – any version that supports the <tt>+loadvpi</tt> option is acceptable.</li>
+ </ul>
<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>
+ </ul>
+
+
+ <ul>
+ <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="manual.html#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained <a href="#problems.ivl.vpi_handle_by_name.absolute-paths">in the user manual</a>.</li>
+ </ul>
+
+
+ <p class="title">Compilers</p>
+
+
+ <ul>
+ <li><a href="http://en.wikipedia.org/wiki/Make">make</a>
+ – any flavor 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://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>
+
+
+ <p class="title">Libraries</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>
+
+
+ <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 ><a id="intro.applications" href="#a-606998228">2.4</a> Applications</h2>
+
+
+ <p>Examples of tasks that can be performed with Ruby-VPI are:</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>
@@ -417,14 +349,14 @@
<li>Building a distributed simulation</li>
</ul></li>
</ul>
- <h2 id="intro.appetizers">2.3 Appetizers</h2>
+ <h2 ><a id="intro.appetizers" href="#a-606999338">2.5</a> Appetizers</h2>
- <p>Here is a modest sampling of code to whet your appetite.</p>
+ <p>Here is a tiny sampling of code to whet your appetite. See <a href="manual.html#usage.tutorial">the tutorial</a> for more samples.</p>
<ul>
<li>Assign the value 2<sup>2048</sup> to a register:</li>
</ul>
@@ -463,29 +395,54 @@
<blockquote>
<p><code class="code"><span style="color:#00D; font-weight:bold">15</span>.times { simulate }</code></p>
</blockquote>
- <h2 id="intro.license">2.4 License</h2>
+ <h2 ><a id="intro.license" href="#a-607000438">2.6</a> 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>
+ <p>Copyright© 2006-2007 Suraj N. Kurapati</p>
- <h2 id="intro.related-works">2.5 Related works</h2>
+ <p>Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:</p>
+ <p>All copies and portions of the Software (together the “Derivatives”) and
+their corresponding machine-readable source code (the “Code”) must include the
+above copyright notice and this permission notice. The Code must reflect all
+modifications made to the Derivatives. The Derivatives must be distributed
+either with the Code or, if the Code is obtainable for no more than the cost
+of distribution plus a nominal fee, with information on how to obtain the Code.</p>
+
+
+ <p><span class="caps">THE SOFTWARE IS PROVIDED</span> “AS IS”, <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS OR
+<span class="caps">IMPLIED</span>, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>,
+<span class="caps">FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. <span class="caps">IN NO EVENT SHALL</span>
+<span class="caps">THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER</span>
+<span class="caps">LIABILITY</span>, WHETHER <span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING <span class="caps">FROM</span>,
+<span class="caps">OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN</span>
+<span class="caps">THE SOFTWARE</span>.</p>
+
+
+ <h2 ><a id="intro.related-works" href="#a-606014748">2.7</a> 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>
<li><a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">ScriptEDA</a> is a Perl, Python, and Tcl interface to <span class="caps">VPI</span>.</li>
<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">2.5.1 Ye olde <span class="caps">PLI</span></h3>
+ <h3 ><a id="intro.related-works.pli" href="#a-606035648">2.7.1</a> 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>
@@ -494,27 +451,27 @@
<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">3 Background</h1>
+ <h1 ><a id="background" href="#a-606053288">3</a> Background</h1>
- <h2 id="background.methodology">3.1 Methodology</h2>
+ <h2 ><a id="background.methodology" href="#a-606069898">3.1</a> 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">3.2 Terminology</h2>
+ <h2 ><a id="background.vocab" href="#a-606106808">3.2</a> Terminology</h2>
<div class="admonition">
<div class="note" id="note1">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: Glossary has definitions</p>
@@ -535,11 +492,11 @@
<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">3.3 Organization</h2>
+ <h2 ><a id="background.org" href="#a-606127698">3.3</a> Organization</h2>
<div class="formal">
<div class="figure" id="fig..organization">
@@ -578,11 +535,11 @@
<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>
+ <h2 ><a id="background.relay" href="#a-606150238">3.4</a> 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>
@@ -615,14 +572,14 @@
</div>
</div>
- <h1 id="setup">4 Setup</h1>
+ <h1 ><a id="setup" href="#a-606180548">4</a> Setup</h1>
- <h2 id="setup.manifest">4.1 Manifest</h2>
+ <h2 ><a id="setup.manifest" href="#a-606192588">4.1</a> Manifest</h2>
<p>When you extract a release package, the following is what you would expect to find.</p>
@@ -634,37 +591,21 @@
<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>
+ <h2 ><a id="setup.reqs" href="#a-606206048">4.2</a> Requirements</h2>
- <p>The following software is necessary in order to use Ruby-VPI.</p>
+ <p>See <a href="#intro.reqs">the section named “Requirements”</a> above.</p>
- <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 style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
<p class="title">Tip: Add support for your Verilog simulator</p>
@@ -673,47 +614,17 @@
</div>
</div>
- <ul>
- <li><strong>make</strong>
- – any distribution should be acceptable.</li>
- </ul>
+ <h2 ><a id="setup.recom" href="#a-606213438">4.3</a> Recommendations</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>
-
-
- <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>
+ <h3 ><a id="setup.recom.merger" href="#a-606235588">4.3.1</a> 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>
@@ -722,11 +633,11 @@
<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>
+ <h2 ><a id="setup.installation" href="#a-606251368">4.4</a> 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>
@@ -736,11 +647,11 @@
$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
</pre>
- <h3 id="setup.installation.windows">4.4.1 Installing on Windows</h3>
+ <h3 ><a id="setup.installation.windows" href="#a-606273678">4.4.1</a> Installing on Windows</h3>
<ul>
<li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
</ul>
@@ -748,11 +659,11 @@
<div class="admonition">
<div class="note" id="note2">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: Undefined symbols in Windows</p>
@@ -788,11 +699,11 @@
<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>
+ <h2 ><a id="setup.maintenance" href="#a-606278328">4.5</a> 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>
@@ -800,14 +711,14 @@
<p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
- <h1 id="usage">5 Usage</h1>
+ <h1 ><a id="usage" href="#a-606285848">5</a> Usage</h1>
- <h2 id="usage.vpi">5.1 <span class="caps">VPI</span> in Ruby</h2>
+ <h2 ><a id="usage.vpi" href="#a-606290248">5.1</a> <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 a few minor differences.</p>
@@ -822,11 +733,11 @@
<div class="admonition">
<div class="note" id="note3">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: No capitalization for <span class="caps">VPI</span> functions</p>
@@ -851,21 +762,21 @@
<span style="color:#339; font-weight:bold">void</span> foo(va_list ap) {
va_list *p = &ap;
}
</pre>
- <h3 id="usage.vpi.handles">5.1.1 Handles</h3>
+ <h3 ><a id="usage.vpi.handles" href="#a-606294778">5.1.1</a> 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 style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span></code> heritage</p>
@@ -889,11 +800,11 @@
<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>
+ <h4><a id="Accessing_a_handle__8217_s_relatives" href="#a-606297428">5.1.1.1</a> 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>
@@ -907,14 +818,14 @@
</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>
+ <h4><a id="Accessing_a_handle__8217_s_properties" href="#a-606305088">5.1.1.2</a> Accessing a handle’s properties</h4>
- <p>To access a handle’s properties, invoke the property 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>
+ <p>To access a handle’s properties, invoke the property 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="figure4">
@@ -952,11 +863,11 @@
<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, 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>
+<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.</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 <code class="code">?</code>. This suggestion is the same as specifying <code class="code">b</code> for the Accessor parameter.
@@ -1288,11 +1199,11 @@
<td> _ </td>
<td> vpiNet </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="2">These expressions print the full name of each vpiNet object associated with the handle. </td>
+ <td rowspan="2">These expressions print the full name of each <code class="code"><span style="color:#036; font-weight:bold">VpiNet</span></code> object associated with the handle. </td>
</tr>
<tr>
<td> <code class="code">handle.each_net {|net| puts net.fullName}</code> </td>
<td> each </td>
<td> _ </td>
@@ -1326,11 +1237,11 @@
<td> _ </td>
<td> VpiNet </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="2">These expressions return a list of nets whose logic value is unknown or “don’t care” (x).</td>
+ <td rowspan="2">These expressions return a list of nets whose <strong>logic value</strong> is unknown or “don’t care” (x).</td>
</tr>
<tr>
<td> <code class="code">handle.select_net {|net| net.x?}</code> </td>
<td> select </td>
<td> _ </td>
@@ -1346,11 +1257,11 @@
</div>
</div>
- <h3 id="usage.vpi.callbacks">5.1.2 Callbacks</h3>
+ <h3 ><a id="usage.vpi.callbacks" href="#a-605776528">5.1.2</a> Callbacks</h3>
<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>
@@ -1490,11 +1401,11 @@
</div>
</div>
- <h2 id="usage.prototyping">5.2 Prototyping</h2>
+ <h2 ><a id="usage.prototyping" href="#a-605820298">5.2</a> Prototyping</h2>
<p>Ruby-VPI enables you to rapidly prototype your designs in Ruby without having to do full-scale implementations in Verilog. This lets you explore and evaluate different design choices quickly.</p>
@@ -1511,11 +1422,11 @@
<p>Once your design has been implemented in Verilog, you can use the <em>same</em> specification, which was originally used to verify your prototype, to verify your Verilog design.</p>
- <h2 id="usage.debugger">5.3 Debugging</h2>
+ <h2 ><a id="usage.debugger" href="#a-605856998">5.3</a> Debugging</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>
@@ -1523,11 +1434,11 @@
<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">5.3.1 Advanced initialization</h3>
+ <h3 ><a id="usage.debugger.init" href="#a-605861038">5.3.1</a> 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>
@@ -1535,11 +1446,11 @@
<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.test-runner">5.4 Test runner</h2>
+ <h2 ><a id="usage.test-runner" href="#a-605886638">5.4</a> Test runner</h2>
<p>A test runner is a file, generated by the <a href="#usage.tools.generate-test">automated test generator</a>, whose name ends with <tt>.rake</tt>. It helps you run generated tests—you can think of it as a <em>makefile</em> if you are familiar with C programming in a <span class="caps">UNIX</span> environment.</p>
@@ -1557,10 +1468,11 @@
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 ncsim # Simulate with Cadence NC-Sim.
rake vcs # Simulate with Synopsys VCS.
rake vsim # Simulate with Mentor Modelsim.
</pre>
</div>
@@ -1569,32 +1481,30 @@
<div class="admonition">
<div class="tip" id="tip2">
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
+ <p style="float:left"><img src="images/tango/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>
+ <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><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>
<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">5.4.1 Environment variables</h3>
+ <h3 ><a id="usage.test-runner.env-vars" href="#a-605692898">5.4.1</a> 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>
@@ -1637,23 +1547,23 @@
</div>
</div>
- <h2 id="usage.examples">5.5 Sample tests</h2>
+ <h2 ><a id="usage.examples" href="#a-605713518">5.5</a> 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>
- <h2 id="usage.tools">5.6 Tools</h2>
+ <h2 ><a id="usage.tools" href="#a-605735618">5.6</a> 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">5.6.1 Automated test generation</h3>
+ <h3 ><a id="usage.tools.generate-test" href="#a-606420358">5.6.1</a> 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>
@@ -1676,11 +1586,11 @@
<div class="admonition">
<div class="tip" id="tip3">
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
+ <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
<p class="title">Tip: Using <strong>kdiff3</strong> with the automated test generator.</p>
@@ -1701,20 +1611,20 @@
</div>
</div>
- <h3 id="usage.tools.verilog-ruby-conv">5.6.2 Verilog to Ruby conversion</h3>
+ <h3 ><a id="usage.tools.verilog-ruby-conv" href="#a-606426458">5.6.2</a> 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">5.7 Tutorial</h2>
+ <h2 ><a id="usage.tutorial" href="#a-606430138">5.7</a> Tutorial</h2>
<ol>
<li><a href="#usage.tutorial.declare-design">Declare a design</a> 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>
@@ -1724,11 +1634,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">5.7.1 Start with a design</h3>
+ <h3 ><a id="usage.tutorial.declare-design" href="#a-606439718">5.7.1</a> 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>
@@ -1762,11 +1672,11 @@
<div class="admonition">
<div class="important" id="important1">
- <p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
+ <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
<p class="title">Important: Before we continue…</p>
@@ -1775,11 +1685,11 @@
</div>
</div>
- <h3 id="usage.tutorial.generate-test">5.7.2 Generate a test</h3>
+ <h3 ><a id="usage.tutorial.generate-test" href="#a-606447618">5.7.2</a> 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>
@@ -1793,11 +1703,11 @@
<div class="admonition">
<div class="note" id="note5">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note:</p>
@@ -1855,11 +1765,11 @@
</div>
</div>
- <h3 id="usage.tutorial.specification">5.7.3 Specify your expectations</h3>
+ <h3 ><a id="usage.tutorial.specification" href="#a-606455858">5.7.3</a> 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>
@@ -1980,11 +1890,11 @@
<div class="admonition">
<div class="important" id="important2">
- <p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
+ <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
<p class="title">Important: Before we continue…</p>
@@ -2005,11 +1915,11 @@
</div>
</div>
- <h3 id="usage.tutorial.implement-proto">5.7.4 Implement the prototype</h3>
+ <h3 ><a id="usage.tutorial.implement-proto" href="#a-606466508">5.7.4</a> 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>
@@ -2041,11 +1951,11 @@
<div class="admonition">
<div class="important" id="important3">
- <p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
+ <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
<p class="title">Important: Before we continue…</p>
@@ -2054,11 +1964,11 @@
</div>
</div>
- <h3 id="usage.tutorial.test-proto">5.7.5 Verify the prototype</h3>
+ <h3 ><a id="usage.tutorial.test-proto" href="#a-606469388">5.7.5</a> 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>
@@ -2119,11 +2029,11 @@
<div class="admonition">
<div class="tip" id="tip4">
- <p style="float:left"><img src="images/tip.png" title="tip" alt="tip" /></p>
+ <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
<p class="title">Tip: What can the test runner do?</p>
@@ -2132,11 +2042,11 @@
</div>
</div>
- <h3 id="usage.tutorial.implement-design">5.7.6 Implement the design</h3>
+ <h3 ><a id="usage.tutorial.implement-design" href="#a-606472858">5.7.6</a> 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>
@@ -2175,11 +2085,11 @@
<div class="admonition">
<div class="important" id="important4">
- <p style="float:left"><img src="images/important.png" title="important" alt="important" /></p>
+ <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
<p class="title">Important: Before we continue…</p>
@@ -2188,11 +2098,11 @@
</div>
</div>
- <h3 id="usage.tutorial.test-design">5.7.7 Verify the design</h3>
+ <h3 ><a id="usage.tutorial.test-design" href="#a-606480598">5.7.7</a> 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>
@@ -2245,16 +2155,25 @@
</div>
</div>
- <h1 id="hacking">6 Hacking</h1>
+ <h1 ><a id="hacking" href="#a-606487878">6</a> Hacking</h1>
- <h2 id="hacking.release-packages">6.1 Building release packages</h2>
+ <h2 ><a id="hacking.scm" href="#a-606495208">6.1</a> Getting the source code</h2>
+ <p>Check out the source code using <a href="http://darcs.net">Darcs</a> from the project repository:</p>
+
+
+ <pre>darcs get http://ruby-vpi.rubyforge.org/src/ruby-vpi</pre>
+
+
+ <h2 ><a id="hacking.release-packages" href="#a-606502868">6.2</a> 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>
@@ -2264,27 +2183,27 @@
<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">7 Known problems</h1>
+ <h1 ><a id="problems" href="#a-606510668">7</a> 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">7.1 Ruby</h2>
+ <h2 ><a id="problems.ruby" href="#a-606514648">7.1</a> Ruby</h2>
- <h3 id="problems.ruby.SystemStackError">7.1.1 SystemStackError</h3>
+ <h3 ><a id="problems.ruby.SystemStackError" href="#a-606529698">7.1.1</a> SystemStackError</h3>
<div class="admonition">
<div class="note" id="note6">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -2296,18 +2215,18 @@
</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>
- <h3 id="problems.ruby.xUnit">7.1.2 test/unit</h3>
+ <h3 ><a id="problems.ruby.xUnit" href="#a-606545738">7.1.2</a> test/unit</h3>
<div class="admonition">
<div class="note" id="note7">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -2319,17 +2238,17 @@
</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>
- <h2 id="problem.ivl">7.2 Icarus Verilog</h2>
+ <h2 ><a id="problem.ivl" href="#a-606557578">7.2</a> Icarus Verilog</h2>
- <h3 id="problems.ivl.vpi_handle_by_name">7.2.1 Vpi::vpi_handle_by_name</h3>
+ <h3 ><a id="problems.ivl.vpi_handle_by_name" href="#a-606563378">7.2.1</a> 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>
+ <h4 ><a id="problems.ivl.vpi_handle_by_name.absolute-paths" href="#a-606577748">7.2.1.1</a> 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>
@@ -2352,11 +2271,11 @@
</div>
</div>
- <h4 id="problems.ivl.vpi_handle_by_name.connect-registers">7.2.1.2 Registers must be connected</h4>
+ <h4 ><a id="problems.ivl.vpi_handle_by_name.connect-registers" href="#a-606588618">7.2.1.2</a> 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>
@@ -2406,27 +2325,27 @@
</div>
</div>
- <h3 id="problems.ivl.vpi_reset">7.2.2 Vpi::reset</h3>
+ <h3 ><a id="problems.ivl.vpi_reset" href="#a-606593458">7.2.2</a> Vpi::reset</h3>
<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">7.3 Mentor Modelsim</h2>
+ <h2 ><a id="problems.vsim" href="#a-606596948">7.3</a> Mentor Modelsim</h2>
- <h3 id="problems.vsim.ruby_run">7.3.1 ruby_run();</h3>
+ <h3 ><a id="problems.vsim.ruby_run" href="#a-606600738">7.3.1</a> ruby_run();</h3>
<div class="admonition">
<div class="note" id="note8">
- <p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
+ <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
<p class="title">Note: Fixed in 2.0.0.</p>
@@ -2438,89 +2357,87 @@
</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>
- <h1 id="glossary">8 Glossary</h1>
+ <h1 ><a id="glossary" href="#a-606604778">8</a> Glossary</h1>
- <h2 id="glossary.bench">8.1 Bench</h2>
+ <h2 ><a id="glossary.bench" href="#a-606606678">8.1</a> 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">8.2 Behavior driven development (BDD)</h2>
+ <h2 ><a id="glossary.BDD" href="#a-606613558">8.2</a> 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">8.3 Design</h2>
+ <h2 ><a id="glossary.design" href="#a-606620958">8.3</a> 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">8.4 Expectation</h2>
+ <h2 ><a id="glossary.expectation" href="#a-606623008">8.4</a> Expectation</h2>
<p>The desired response to some stimulus.</p>
- <h2 id="glossary.handle">8.5 Handle</h2>
+ <h2 ><a id="glossary.handle" href="#a-606624858">8.5</a> 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">8.6 Rake</h2>
+ <h2 ><a id="glossary.rake" href="#a-606628418">8.6</a> 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>
- <blockquote>
- <p style="text-align:right;">—<a href="http://docs.rubyrake.org">Rake documentation</a></p>
- </blockquote>
+ <p style="text-align:right;">—<a href="http://docs.rubyrake.org">Rake documentation</a></p>
- <h2 id="glossary.rspec">8.7 rSpec</h2>
+ <h2 ><a id="glossary.rspec" href="#a-606630878">8.7</a> 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">8.8 Specification</h2>
+ <h2 ><a id="glossary.specification" href="#a-606636388">8.8</a> 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">8.9 Test driven development (TDD)</h2>
+ <h2 ><a id="glossary.TDD" href="#a-606640878">8.9</a> 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">9.0 Test</h2>
+ <h2 ><a id="glossary.test" href="#a-606643148">9.0</a> 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">9.1 Test bench</h2>
+ <h2 ><a id="glossary.test_bench" href="#a-606646838">9.1</a> 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>