doc/manual.html in ruby-vpi-16.0.1 vs doc/manual.html in ruby-vpi-17.0.0
- old
+ new
@@ -3,170 +3,144 @@
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" type="text/css" href="common.css" media="screen" />
<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>
+ <title>Ruby-VPI 17.0.0 user manual</title>
</head>
<body>
- <h1 style="margin-top: 0">Ruby-VPI user manual</h1>
-
- <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>
-
- <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 id="toc-links">
+ <a href="#toc:contents">Contents</a> ·
+ <a href="#toc:tip">Tips</a> ·
+ <a href="#toc:note">Notes</a> ·
+ <a href="#toc:caution">Cautions</a> ·
+ <a href="#toc:figure">Figures</a> ·
+ <a href="#toc:table">Tables</a> ·
+ <a href="#toc:example">Examples</a> ·
+
+ <a href="readme.html" style="color: green; font-size: larger;">Home page</a>
</div>
+
+ <div id="body">
+ <hr style="display: none"/>
- <div id="index">
- <h1>Contents</h1>
- <ul><li><a id="a-607892658" href="#Ruby-VPI_user_manual">Ruby-VPI user manual</a><ul><li><a id="a-607893938" href="#legal">Legalities</a></li></ul></li><li><a id="a-607894868" href="#intro">Introduction</a><ul><li><a id="a-607895718" href="#Resources">Resources</a></li><li><a id="a-607896658" href="#intro.features">Features</a></li><li><a id="a-607897688" href="#intro.reqs">Requirements</a></li><li><a id="a-607898638" href="#intro.applications">Applications</a></li><li><a id="a-607899748" href="#intro.appetizers">Appetizers</a></li><li><a id="a-607900808" href="#intro.license">License</a></li><li><a id="a-607901818" href="#intro.related-works">Related works</a><ul><li><a id="a-607903008" href="#intro.related-works.pli">Ye olde <span class="caps">PLI</span></a></li></ul></li></ul></li><li><a id="a-607904308" href="#background">Background</a><ul><li><a id="a-607905318" href="#background.methodology">Methodology</a></li><li><a id="a-607906508" href="#background.vocab">Terminology</a></li><li><a id="a-607907578" href="#background.org">Organization</a></li><li><a id="a-607908608" href="#background.relay">Ruby/Verilog interaction</a></li></ul></li><li><a id="a-607909748" href="#setup">Setup</a><ul><li><a id="a-607910668" href="#setup.manifest">Manifest</a></li><li><a id="a-607911698" href="#setup.reqs">Requirements</a></li><li><a id="a-607912638" href="#setup.recom">Recommendations</a><ul><li><a id="a-607913678" href="#setup.recom.merger">Text merging tool</a></li></ul></li><li><a id="a-607914868" href="#setup.installation">Installation</a><ul><li><a id="a-607916038" href="#setup.installation.windows">Installing on Windows</a></li></ul></li><li><a id="a-607917378" href="#setup.maintenance">Maintenance</a></li></ul></li><li><a id="a-607918548" href="#usage">Usage</a><ul><li><a id="a-607919458" href="#usage.vpi"><span class="caps">VPI</span> in Ruby</a><ul><li><a id="a-607920448" href="#usage.vpi.handles">Handles</a><ul><li><a id="a-607921548" href="#Accessing_a_handle__8217_s_relatives">Accessing a handle’s relatives</a></li><li><a id="a-607922938" href="#Accessing_a_handle__8217_s_properties">Accessing a handle’s properties</a></li></ul></li><li><a id="a-607924498" href="#usage.vpi.callbacks">Callbacks</a></li></ul></li><li><a id="a-607925708" href="#usage.prototyping">Prototyping</a></li><li><a id="a-607926808" href="#usage.debugger">Debugging</a><ul><li><a id="a-607927888" href="#usage.debugger.init">Advanced initialization</a></li></ul></li><li><a id="a-607929098" href="#usage.test-runner">Test runner</a><ul><li><a id="a-607930258" href="#usage.test-runner.env-vars">Environment variables</a></li></ul></li><li><a id="a-607931608" href="#usage.examples">Sample tests</a></li><li><a id="a-607932628" href="#usage.tools">Tools</a><ul><li><a id="a-607933658" href="#usage.tools.generate-test">Automated test generation</a></li><li><a id="a-607934908" href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li></ul></li><li><a id="a-607936328" href="#usage.tutorial">Tutorial</a><ul><li><a id="a-607937408" href="#usage.tutorial.declare-design">Start with a design</a></li><li><a id="a-607938748" href="#usage.tutorial.generate-test">Generate a test</a></li><li><a id="a-607940058" href="#usage.tutorial.specification">Specify your expectations</a></li><li><a id="a-607941368" href="#usage.tutorial.implement-proto">Implement the prototype</a></li><li><a id="a-607942708" href="#usage.tutorial.test-proto">Verify the prototype</a></li><li><a id="a-607943958" href="#usage.tutorial.implement-design">Implement the design</a></li><li><a id="a-607945338" href="#usage.tutorial.test-design">Verify the design</a></li></ul></li></ul></li><li><a id="a-607946678" href="#hacking">Hacking</a><ul><li><a id="a-607947628" href="#hacking.scm">Getting the source code</a></li><li><a id="a-607948608" href="#hacking.release-packages">Building release packages</a></li></ul></li><li><a id="a-607949918" href="#problems">Known problems</a><ul><li><a id="a-607950878" href="#problems.ruby">Ruby</a><ul><li><a id="a-607951958" href="#problems.ruby.SystemStackError">SystemStackError</a></li><li><a id="a-607953298" href="#problems.ruby.xUnit">test/unit</a></li></ul></li><li><a id="a-607954508" href="#problem.ivl">Icarus Verilog</a><ul><li><a id="a-607955538" href="#problems.ivl.vpi_handle_by_name">Vpi::vpi_handle_by_name</a><ul><li><a id="a-607956978" href="#problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</a></li><li><a id="a-607958638" href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li></ul></li><li><a id="a-607960458" href="#problems.ivl.vpi_reset">Vpi::reset</a></li></ul></li><li><a id="a-607961718" href="#problems.vsim">Mentor Modelsim</a><ul><li><a id="a-607962798" href="#problems.vsim.ruby_run">ruby_run();</a></li></ul></li></ul></li><li><a id="a-607964068" href="#glossary">Glossary</a><ul><li><a id="a-607965038" href="#glossary.bench">Bench</a></li><li><a id="a-607966068" href="#glossary.BDD">Behavior driven development (BDD)</a></li><li><a id="a-607967048" href="#glossary.design">Design</a></li><li><a id="a-607968108" href="#glossary.expectation">Expectation</a></li><li><a id="a-607969248" href="#glossary.handle">Handle</a></li><li><a id="a-607970298" href="#glossary.rake">Rake</a></li><li><a id="a-607971318" href="#glossary.rspec">rSpec</a></li><li><a id="a-607972348" href="#glossary.specification">Specification</a></li><li><a id="a-607973538" href="#glossary.TDD">Test driven development (TDD)</a></li><li><a id="a-607974518" href="#glossary.test">Test</a></li><li><a id="a-607975528" href="#glossary.test_bench">Test bench</a></li></ul></li></ul>
+ <div id="Ruby-VPI_17.0.0_user_manual" class="front_cover">
+ <h1 class="title"><big>Ruby-VPI 17.0.0 user manual</big></h1>
- <h1>Formals</h1>
+ <h2 class="author">Suraj N. Kurapati</h2>
- <h2 id="figures">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="#fig..ruby_relay">Interaction between Ruby and Verilog</a></li>
- <li><a href="#figure4">Method naming format for accessing a handle’s properties</a></li>
- </ol>
- <h2 id="tables">Tables</h2>
- <ol>
- <li><a href="#tbl..accessors">Possible accessors and their implications</a></li>
- </ol>
- <h2 id="examples">Examples</h2>
- <ol>
- <li><a href="#ex..properties">Examples of accessing a handle’s properties</a></li>
- <li><a href="#ex..callback">Using a callback for value change notification</a></li>
- <li><a href="#example3">Seeing what a test runner can do</a></li>
- <li><a href="#example4">Running a test with environment variables</a></li>
- <li><a href="#fig..counter.v_decl">Declaration of a simple up-counter with synchronous reset</a></li>
- <li><a href="#fig..generate-test.rspec">Generating a test with specification in rSpec format</a></li>
- <li><a href="#fig..generate-test.unit-test">Generating a test with specification in xUnit format</a></li>
- <li><a href="#fig..counter_rspec_spec.rb">Specification implemented in rSpec format</a></li>
- <li><a href="#fig..counter_xunit_spec.rb">Specification implemented in xUnit format</a></li>
- <li><a href="#fig..counter_proto.rb">Ruby prototype of our Verilog design</a></li>
- <li><a href="#fig..test-proto.rspec">Running a test with specification in rSpec format</a></li>
- <li><a href="#fig..test-proto.unit-test">Running a test with specification in xUnit format</a></li>
- <li><a href="#fig..counter.v_impl">Implementation of a simple up-counter with synchronous reset</a></li>
- <li><a href="#fig..test-design.rspec">Running a test with specification in rSpec format</a></li>
- <li><a href="#fig..test-design.unit-test">Running a test with specification in xUnit format</a></li>
- <li><a href="#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>
- <h1>Admonitions</h1>
- <h2 id="tips">Tips</h2>
- <ol>
- <li><a href="#tip1">Add support for your Verilog simulator</a></li>
- <li><a href="#tip2">Running multiple tests at once.</a></li>
- <li><a href="#tip3">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
- <li><a href="#tip4">What can the test runner do?</a></li>
- </ol>
- <h2 id="notes">Notes</h2>
- <ol>
- <li><a href="#note1">Glossary has definitions</a></li>
- <li><a href="#note2">Undefined symbols in Windows</a></li>
- <li><a href="#note3">No capitalization for <span class="caps">VPI</span> functions</a></li>
- <li><a href="#note4"><code>Vpi::Handle</code> heritage</a></li>
- <li><a href="#note5">note5</a></li>
- <li><a href="#note6">Fixed in 2.0.0.</a></li>
- <li><a href="#note7">Fixed in 2.0.0.</a></li>
- <li><a href="#note8">Fixed in 2.0.0.</a></li>
- </ol>
- <h2 id="importants">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>
- </div>
- <h1><a id="Ruby-VPI_user_manual" href="#a-607892658">1</a> Ruby-VPI user manual</h1>
+ <h3 class="date">22 July 2007</h3>
- <p>This manual was last updated on Sun May 27 14:47:38 -0700 2007.</p>
+ <p>
+ <div id="About_this_manual" class="paragraph">
+ <p class="title">About this manual</p>
+ <p>This manual 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> as necessary.</p>
- <p>It is meant to be read in conjunction with the <a href="../ref/ruby/index.html">reference documentation for Ruby-VPI</a>. In addition, if you are new to <a href="http://www.ruby-lang.org">the Ruby language</a>, you are encouraged to <a href="http://www.ruby-lang.org/en/documentation/">explore its documentation</a> alongside this manual.</p>
+ <p>In this manual, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate this manual, especially for users of text-only web browsers.</p>
- <p>You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the <a href="http://rubyforge.org/forum/?group_id=1339">project forums</a>.</p>
+ <p>In addition, this manual is distributed as one big HTML file so that you can easily search for a particular topic using nothing more than your web browser’s built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.</p>
- <p><em>Happy reading!</em></p>
+ <p>You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the <a href="http://rubyforge.org/forum/?group_id=1339">project forums</a>. Furthermore, you can <a href="#hacking.manual">edit this manual</a> and contribute your improvements to the <a href="http://rubyforge.org/tracker/?group_id=1339">project patches</a>. Finally, you can find the newest version of this manual at the <a href="http://ruby-vpi.rubyforge.org">Ruby-VPI project website</a>.</p>
+ </div>
+
+ <div id="Legal_notice" class="paragraph">
+ <p class="title">Legal notice</p>
+ <p>This manual is distributed under <a href="#intro.license">the same license as Ruby-VPI</a>.</p>
- <h2 ><a id="legal" href="#a-607893938">1.1</a> Legalities</h2>
+ <p>The admonition graphics used in this manual are Copyright 2005, 2006 <a href="http://tango.freedesktop.org">Tango Desktop Project</a> and are distributed under <a href="./images/tango/LICENSE">these terms</a>.</p>
+ </div>
+ </p>
- <p>This manual is distributed under <a href="#intro.license">the same license as Ruby-VPI</a>.</p>
+ </div>
+
+ <hr style="display: none"/>
- <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>
+ <div id="intro" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607687748">2</a>
+ <br/><br/>
- <h1 ><a id="intro" href="#a-607894868">2</a> Introduction</h1>
+ <big>Welcome</big>
+ </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 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>
-
<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>Access the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog VPI</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>
+ <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">PDF 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">
+ <p>
+ <hr style="display: none"/>
- <h2><a id="Resources" href="#a-607895718">2.1</a> Resources</h2>
+ <div id="resources" class="section">
+ <h2 class="title">
+ <a href="#a-607624238">2.1</a>
+
- <p class="title">Records</p>
+ Resources
+ </h2>
+
+ <div id="Records" class="paragraph">
+ <p class="title">Records</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><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="history.html">What’s new</a>
+ – a history 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>
+ <li><a href="http://ruby-vpi.rubyforge.org/papers/masters_thesis.html#tth_sEc5.2">Motivation</a>
+ – why does Ruby-VPI exist?</li>
</ul>
+ </div>
+
-
- <p class="title">Documentation</p>
-
-
+ <div id="Documentation" class="paragraph">
+ <p class="title">Documentation</p>
+ <ul>
+ <li><a href="manual.html">User manual</a>
+ – complete documentation for users. <em>Start here!</em>
<ul>
<li><a href="manual.html#usage.tutorial">Tutorial</a>
– learn how to use Ruby-VPI quickly.</li>
- <li><a href="manual.html">Manual</a>
- – complete documentation for users. <em>Start here!</em></li>
+ </ul>
+ </li>
<li><a href="../ref/">Reference</a>
- – <span class="caps">API</span> documentation for Ruby libraries and C extension.</li>
+ – API documentation for Ruby libraries and C extension.</li>
</ul>
+ </div>
+
-
- <p class="title">Facilities</p>
-
-
- <ul>
+ <div id="Facilities" class="paragraph">
+ <p class="title">Facilities</p>
+ <ul>
<li><a href="http://rubyforge.org/frs/?group_id=1339">Downloads</a>
- – obtain release packages.</li>
+ – 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>
@@ -176,31 +150,43 @@
<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/projects/ruby-vpi">Project portal</a>
– hosted generously by <a href="http://rubyforge.org">RubyForge</a>.</li>
</ul>
+ </div>
+
+ </div>
+ </p>
-</div>
- <h2 ><a id="intro.features" href="#a-607896658">2.2</a> Features</h2>
+ <p>
+ <hr style="display: none"/>
+ <div id="intro.features" class="section">
+ <h2 class="title">
+ <a href="#a-607636548">2.2</a>
- <p class="title">Portable</p>
+
+ Features
+ </h2>
- <ul>
- <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>
+
+ <div id="Portable" class="paragraph">
+ <p class="title">Portable</p>
+ <ul>
+ <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 VPI</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>
+ </div>
+
-
- <p class="title">Agile</p>
-
-
- <ul>
+ <div id="Agile" class="paragraph">
+ <p class="title">Agile</p>
+ <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>
<li><a href="manual.html#usage.tutorial.implement-proto">rapid prototyping</a> for design exploration</li>
@@ -214,16 +200,16 @@
<li><a href="manual.html#usage.tutorial.specification">Specifications</a> are readable, portable, and <em>executable</em>.</li>
<li>The <a href="manual.html#usage.tools.generate-test">automated test generator</a> helps you accomodate design changes with <em>minimal</em> effort.</li>
<li>There is absolutely <em>no compiling</em>!</li>
</ul></li>
</ul>
+ </div>
+
-
- <p class="title">Powerful</p>
-
-
- <ul>
+ <div id="Powerful" class="paragraph">
+ <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>
<li>Unlimited length integers</li>
<li>Regular expressions</li>
<li>Multi-threading</li>
@@ -235,98 +221,98 @@
<ul>
<li>Uses <a href="http://rubyforge.org/projects/ruby-debug/">ruby-debug</a> for <a href="manual.html#usage.debugger">interactive debugging</a>.</li>
<li>Uses <a href="http://eigenclass.org/hiki.rb?rcov">rcov</a> for test <a href="manual.html#usage.test-runner.env-vars">coverage analysis and report generation</a>.</li>
</ul>
+ </div>
+
+ </div>
+ </p>
- <h2 ><a id="intro.reqs" href="#a-607897688">2.3</a> Requirements</h2>
+ <p>
+ <hr style="display: none"/>
- <p>The following software is necessary in order to use Ruby-VPI.</p>
+ <div id="intro.reqs" class="section">
+ <h2 class="title">
+ <a href="#a-607648378">2.3</a>
+
- <p class="title">Verilog simulator</p>
+ Requirements
+ </h2>
+ <p>The following software is necessary in order to use Ruby-VPI.</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>
+ <p>
+ <div id="Verilog_simulator" class="paragraph">
+ <p class="title">Verilog simulator</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 VPI.
- <ul>
- <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>
-
<ul>
- <li><a href="http://www.model.com">Mentor Modelsim</a>
+ <li><a href="http://www.synopsys.com/products/simulation/simulation.html">Synopsys VCS</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>
-
-
- <ul>
- <li><a href="http://www.cadence.com/products/functional_ver/nc-verilog/">Cadence NC-Sim / NC-Verilog</a>
+ <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>
+ <li><a href="http://www.pragmatic-c.com/gpl-cver/">GPL 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="manual.html#background.org.vpi.util">access child handles through method calls</a>. The reason for this limitation is explained <a href="manual.html#problems.ivl.vpi_handle_by_name.absolute-paths">in the user manual</a>.</li>
</ul>
+ </div>
+
-
- <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>
+ <div id="Compilers" class="paragraph">
+ <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>
+ <li>C compiler
+ – the <a href="http://www.gnu.org/software/gcc/" title="GCC">GNU Compiler Collection</a> is preferred, but any C compiler should be acceptable.</li>
+ <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>
+ </div>
+
-
- <p class="title">Libraries</p>
-
-
- <ul>
- <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads"><span class="caps">POSIX</span> threads</a>
+ <div id="Libraries" class="paragraph">
+ <p class="title">Libraries</p>
+ <ul>
+ <li><a href="http://en.wikipedia.org/wiki/Pthreads" title="pthreads">POSIX threads</a>
– header and linkable object files, and operating system support for this library are necessary.</li>
+ <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>
+ </div>
+ </p>
+ </div>
+ </p>
- <ul>
- <li><a href="http://rubyforge.org/frs/?group_id=126">RubyGems</a>
- – any recent version should be acceptable. You can install RubyGems by following <a href="http://www.rubygems.org/read/chapter/3">these instructions</a>.</li>
- </ul>
+ <p>
+ <hr style="display: none"/>
- <h2 ><a id="intro.applications" href="#a-607898638">2.4</a> Applications</h2>
+ <div id="intro.applications" class="section">
+ <h2 class="title">
+ <a href="#a-607650938">2.4</a>
+
- <p>Examples of tasks that can be performed with Ruby-VPI are:</p>
+ Applications
+ </h2>
+ Examples of tasks that can be performed with Ruby-VPI are:
+
<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>:
+ <li>From the second edition of <a href="http://www.sutherland-hdl.com/publications.html"><em>The Verilog PLI Handbook</em></a>:
<ul>
<li>C language bus-functional models</li>
<li>Reading test vector files</li>
<li>Delay calculation</li>
<li>Custom output displays</li>
@@ -348,494 +334,739 @@
<li>Interactive logic simulation</li>
<li>Building a distributed simulation</li>
</ul></li>
</ul>
+ </div>
+ </p>
- <h2 ><a id="intro.appetizers" href="#a-607899748">2.5</a> Appetizers</h2>
+ <p>
+ <hr style="display: none"/>
- <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>
+ <div id="intro.appetizers" class="section">
+ <h2 class="title">
+ <a href="#a-607653538">2.5</a>
+
+ Appetizers
+ </h2>
+
+ <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>
<blockquote>
- <p><code class="code">some_register.intVal = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#00D; font-weight:bold">2048</span></code></p>
+ <p><code class="code">your_register.intVal = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#00D; font-weight:bold">2048</span></code></p>
</blockquote>
<ul>
<li>Check if all nets in a module are at high impedance:</li>
</ul>
<blockquote>
- <p><code class="code">some_module.all_net? { |net| net.z? }</code></p>
+ <p><code class="code">your_module.all_net? { |net| net.z? }</code></p>
</blockquote>
<ul>
<li>See a register’s path, width, and location (file & line number):</li>
</ul>
<blockquote>
- <p><code class="code">puts some_register</code></p>
+ <p><code class="code">puts your_register</code></p>
</blockquote>
<ul>
- <li>Simulate fifteen clock cycles:</li>
+ <li>Access the first five elements in a memory:</li>
</ul>
<blockquote>
- <p><code class="code"><span style="color:#00D; font-weight:bold">15</span>.times { simulate }</code></p>
+ <p><code class="code">your_memory.memoryWord_a[<span style="color:#00D; font-weight:bold">0</span>..<span style="color:#00D; font-weight:bold">4</span>]</code></p>
</blockquote>
- <h2 ><a id="intro.license" href="#a-607900808">2.6</a> License</h2>
+ <ul>
+ <li>Clear a memory by filling it with zeroes:</li>
+ </ul>
- <p>Copyright© 2006-2007 Suraj N. Kurapati</p>
+ <blockquote>
+ <p><code class="code">your_memory.each_memoryWord {|w| w.intVal = <span style="color:#00D; font-weight:bold">0</span>}</code></p>
+ </blockquote>
+ </div>
+ </p>
- <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>
+ <hr style="display: none"/>
- <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>
+ <div id="intro.license" class="section">
+ <h2 class="title">
+ <a href="#a-607656258">2.6</a>
+
- <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>
+ License
+ </h2>
+ <p>Copyright 2006 Suraj N. Kurapati <snk@gna.org></p>
- <h2 ><a id="intro.related-works" href="#a-607901818">2.7</a> 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>
- <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>
+ <p>1. All modified and unmodified copies and substantial portions of the Software
+ (the "Derivatives") and their corresponding machine-readable source code (the
+ "Code") must include the above copyright notice and this permission notice.</p>
- <h3 ><a id="intro.related-works.pli" href="#a-607903008">2.7.1</a> Ye olde <span class="caps">PLI</span></h3>
+ <p>2. Upon distribution, the Derivatives must be accompanied either by the Code or,
+ if the Code is obtainable for no more than the cost of distribution plus a
+ nominal fee, by information on how to obtain the Code.</p>
- <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>
+ <p><span class="caps">THE SOFTWARE IS PROVIDED</span> "AS IS", <span class="caps">WITHOUT WARRANTY OF ANY KIND</span>, EXPRESS OR
+IMPLIED, INCLUDING <span class="caps">BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY</span>, FITNESS
+<span class="caps">FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT</span>. IN <span class="caps">NO EVENT SHALL THE AUTHORS OR</span>
+<span class="caps">COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM</span>, DAMAGES <span class="caps">OR OTHER LIABILITY</span>, WHETHER
+<span class="caps">IN AN ACTION OF CONTRACT</span>, TORT <span class="caps">OR OTHERWISE</span>, ARISING FROM, OUT <span class="caps">OF OR IN</span>
+<span class="caps">CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE</span>.</p>
- <ul>
- <li><a href="http://www.nelsim.com">ScriptSim</a> is a Perl, Python, and Tcl/Tk interface to <span class="caps">PLI</span>.</li>
- <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>
+ </div>
+ </p>
+
+
+ <p>
+ <hr style="display: none"/>
+
+ <div id="intro.related-works" class="section">
+ <h2 class="title">
+ <a href="#a-607661648">2.7</a>
+
+
+
+ Related works
+ </h2>
+
+ <ul>
+ <li><a href="http://jove.sourceforge.net">JOVE</a> is a Java interface to VPI.</li>
+ <li><a href="http://teal.sourceforge.net">Teal</a> is a C++ interface to VPI.</li>
+ <li><a href="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">ScriptEDA</a> is a Perl, Python, and Tcl interface to VPI.</li>
+ <li><a href="http://rhdl.rubyforge.org">RHDL</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>
- <h1 ><a id="background" href="#a-607904308">3</a> Background</h1>
+ <p>
+ <hr style="display: none"/>
+ <div id="intro.related-works.pli" class="section">
+ <h3 class="title">
+ <a href="#a-607658708">2.7.1</a>
- <h2 ><a id="background.methodology" href="#a-607905318">3.1</a> Methodology</h2>
+
+ Ye olde PLI
+ </h3>
- <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>
+ The following projects utilize the archaic <strong>tf</strong> and <strong>acc</strong> PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.
- <h2 ><a id="background.vocab" href="#a-607906508">3.2</a> Terminology</h2>
+ <ul>
+ <li><a href="http://www.nelsim.com">ScriptSim</a> is a Perl, Python, and Tcl/Tk interface to PLI.</li>
+ <li><a href="http://www.veripool.com/verilog-pli.html">Verilog::Pli</a> is a Perl interface to PLI.</li>
+ </ul>
+ </div>
+ </p>
-<div class="admonition">
+ </div>
+ </p>
+ </div>
+
-<div class="note" id="note1">
+ <hr style="display: none"/>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <div id="setup" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607728418">3</a>
+ <br/><br/>
- <p class="title">Note: Glossary has definitions</p>
+ <big>Setup</big>
+ </h1>
+
+ <hr style="display: none"/>
- <p>Have a look at the <a href="#glossary">glossary</a> for definitions of terms used in this manual.</p>
+ <div id="setup.manifest" class="section">
+ <h2 class="title">
+ <a href="#a-607690938">3.1</a>
+
-</div>
+ Manifest
+ </h2>
-</div>
+ When you extract a release package, the following is what you would expect to find.
- <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>
+ <ul>
+ <li><tt>doc</tt> contains user documentation in various formats.</li>
+ <li><tt>ref</tt> contains reference API documentation in HTML format.</li>
+ <li><tt>ext</tt> contains source code, written in the C language, for the <a href="#organization">core of Ruby-VPI</a></li>
+ <li><tt>lib</tt> contains Ruby libraries provided by Ruby-VPI.</li>
+ <li><tt>bin</tt> contains various tools. See <a href="#usage.tools">Section 5.4</a> for more information.</li>
+ <li><tt>samp</tt> contains example tests. See <a href="#usage.examples">Section 5.5</a> for more information.</li>
+ </ul>
- <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>
+ </div>
+
+ <hr style="display: none"/>
- <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>
+ <div id="setup.reqs" class="section">
+ <h2 class="title">
+ <a href="#a-607696378">3.2</a>
+
- <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>
+ Requirements
+ </h2>
+ <p>See <a href="#intro.reqs">Section 2.3</a> above.</p>
- <h2 ><a id="background.org" href="#a-607907578">3.3</a> Organization</h2>
+ <p>
+ <hr style="display: none"/>
-<div class="formal">
+ <div class="admonition">
+ <div class="tip" id="Add_support_for_your_Verilog_simulator">
+ <img src="images/tango/tip.png" alt="tip" class="icon"/>
-<div class="figure" id="fig..organization">
+ <p class="title"><a href="#a-607693408">Tip 1</a>. Add support for your Verilog simulator</p>
- <p class="title">Figure 1. Overall organization of a test</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 I will add support for your simulator in the next release!
+ </div>
+ </div>
+ </p>
+ </div>
+
- <p><img src="figures/organization.png" alt="" /></p>
+ <hr style="display: none"/>
+ <div id="setup.recom" class="section">
+ <h2 class="title">
+ <a href="#a-607702548">3.3</a>
-</div>
+
-</div>
+ Recommendations
+ </h2>
- <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>The following software may make your interactions with Ruby-VPI more pleasant.</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>
+ <p>
+ <hr style="display: none"/>
+ <div id="setup.recom.merger" class="section">
+ <h3 class="title">
+ <a href="#a-607699208">3.3.1</a>
-<div class="formal">
+
-<div class="figure" id="fig..organization.detail">
+ Text merging tool
+ </h3>
- <p class="title">Figure 2. Detailed organization of a test</p>
+ An <em>interactive</em> text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the <a href="#usage.tools.generate">automated test generator</a>. A handful of the currently available open-source text merging tools are listed below.
- <p><img src="figures/organization_detailed.png" alt="" /></p>
+ <ul>
+ <li><a href="http://kdiff3.sourceforge.net/"><strong>kdiff3</strong></a> is a graphical, three-way merging tool for KDE.</li>
+ </ul>
-</div>
+ <ul>
+ <li><a href="http://meld.sourceforge.net/"><strong>meld</strong></a> is a graphical, three-way merging tool for GNOME.</li>
+ </ul>
-</div>
- <p>Now, let us take a more detailed look at this organization, as illustrated in <a href="#fig..organization.detail">the figure named “Detailed organization of a test”</a>.</p>
+ <ul>
+ <li><a href="http://tkdiff.sourceforge.net/"><strong>tkdiff</strong></a> is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</li>
+ </ul>
- <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>
+ <ul>
+ <li><a href="http://furius.ca/xxdiff/"><strong>xxdiff</strong></a> is a graphical, three-way merging tool.</li>
+ </ul>
- <h2 ><a id="background.relay" href="#a-607908608">3.4</a> Ruby/Verilog interaction</h2>
+ <ul>
+ <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 SSH.</li>
+ </ul>
+ </div>
+</p>
- <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>
+ </div>
+
+ <hr style="display: none"/>
- <p>In contrast, Ruby-VPI puts the <em>specification</em> in charge. The specification temporarily transfers control to the Verilog simulator by invoking the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::advance_time</code> method, which returns control to the specification when it finishes. This process is illustrated in <a href="#fig..ruby_relay">the figure named “Interaction between Ruby and Verilog”</a>.</p>
+ <div id="setup.inst" class="section">
+ <h2 class="title">
+ <a href="#a-607711698">3.4</a>
+
- <p>Ruby-VPI’s approach is the same as any software testing framework, where the <em>specification</em> drives the design under test. Whereas, the typical <span class="caps">VPI</span> & C approach is literally <em>backwards</em> because the design under test drives the specification.</p>
+ 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>
-<div class="formal">
-<div class="figure" id="fig..ruby_relay">
+ <pre>
+$ gem env gemdir
+/usr/lib/ruby/gems/1.8
- <p class="title">Figure 3. Interaction between Ruby and Verilog</p>
+$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
+/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
+</pre>
- <p><img src="figures/ruby_relay.png" alt="" /></p>
+ <p>
+ <hr style="display: none"/>
+ <div class="admonition">
+ <div class="note" id="Tuning_for_maximum_performance">
+ <img src="images/tango/note.png" alt="note" class="icon"/>
- <ol>
- <li>The current simulation time is <em>X</em>.</li>
- <li>The specification invokes the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::advance_time</code> method with parameter <em>Y</em>, which specifies the number of simulation time steps to be simulated.</li>
- <li>The Verilog simulator is now in control (temporarily).</li>
- <li>The current simulation time has <em>not</em> changed; it is still <em>X</em>.</li>
- <li>The Verilog simulator simulates <em>Y</em> simulation time steps.</li>
- <li>The current simulation time is now <em>X + Y</em>.</li>
- <li>The Verilog simulator returns control back to the specification.</li>
- </ol>
+ <p class="title"><a href="#a-607705108">Note 1</a>. Tuning for maximum performance</p>
+ You can tune your installation of Ruby-VPI for maximum performance by adding your C compiler’s optimization flag to the <code class="code"><span style="color:#036; font-weight:bold">CFLAGS</span></code> environment variable <em>before</em> you run the <pre>gem install -y ruby-vpi</pre> command. For example, if your C compiler is GCC, then you can set <code class="code"><span style="color:#036; font-weight:bold">CFLAGS</span></code> to <tt>-O9</tt> for maximum optimization.
+ </div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
-</div>
+ <div id="setup.inst.windows" class="section">
+ <h3 class="title">
+ <a href="#a-607707638">3.4.1</a>
- <h1 ><a id="setup" href="#a-607909748">4</a> Setup</h1>
+
+ Installing on Windows
+ </h3>
- <h2 ><a id="setup.manifest" href="#a-607910668">4.1</a> Manifest</h2>
+ <p>After Ruby-VPI is compiled, it is linked to symbols whose names begin with <tt>_vpi</tt>. In GNU/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>When you extract a release package, the following is what you would expect to find.</p>
+ <p>One solution to this problem is to supply the Verilog simulator’s VPI object file, which contains definitions of all VPI symbols, to the linker. The following steps illustrate this process.</p>
<ul>
- <li><tt>doc</tt> contains user documentation in various formats.</li>
- <li><tt>ref</tt> contains reference <span class="caps">API</span> documentation in <span class="caps">HTML</span> format.</li>
- <li><tt>ext</tt> contains source code, written in the C language, for the <a href="#background.org">core of Ruby-VPI</a>.</li>
- <li><tt>lib</tt> contains Ruby libraries provided by Ruby-VPI.</li>
- <li><tt>bin</tt> contains various tools. See <a href="#usage.tools">the section named “Tools”</a> for more information.</li>
- <li><tt>samp</tt> contains example tests. See <a href="#usage.examples">the section named “Sample tests”</a> for more information.</li>
+ <li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
</ul>
- <h2 ><a id="setup.reqs" href="#a-607911698">4.2</a> Requirements</h2>
+ <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>
- <p>See <a href="#intro.reqs">the section named “Requirements”</a> above.</p>
+ <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 GPL 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">
+ <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>
-<div class="tip" id="tip1">
- <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
+ <ul>
+ <li>You may now install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command in Cygwin.</li>
+ </ul>
+ </div>
+</p>
- <p class="title">Tip: Add support for your Verilog simulator</p>
+ </div>
+
+ <hr style="display: none"/>
- <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 id="setup.maintenance" class="section">
+ <h2 class="title">
+ <a href="#a-607713978">3.5</a>
+
-</div>
+ Maintenance
+ </h2>
-</div>
+ <ul>
+ <li>You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.</li>
+ <li>You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.</li>
+ </ul>
- <h2 ><a id="setup.recom" href="#a-607912638">4.3</a> Recommendations</h2>
+ <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
- <p>The following software may make your interactions with Ruby-VPI more pleasant.</p>
+ </div>
+
+ </div>
+
+ <hr style="display: none"/>
- <h3 ><a id="setup.recom.merger" href="#a-607913678">4.3.1</a> Text merging tool</h3>
+ <div id="organization" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607211338">4</a>
+ <br/><br/>
-An <em>interactive</em> text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the <a href="#usage.tools.generate-test">automated test generator</a>. A handful of the currently available open-source text merging tools are listed below.
- <ul>
- <li><a href="http://kdiff3.sourceforge.net/"><strong>kdiff3</strong></a> is a graphical, three-way merging tool for <span class="caps">KDE</span>.</li>
- <li><a href="http://meld.sourceforge.net/"><strong>meld</strong></a> is a graphical, three-way merging tool for <span class="caps">GNOME</span>.</li>
- <li><a href="http://tkdiff.sourceforge.net/"><strong>tkdiff</strong></a> is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</li>
- <li><a href="http://furius.ca/xxdiff/"><strong>xxdiff</strong></a> is a graphical, three-way merging tool.</li>
- <li><a href="http://elonen.iki.fi/code/imediff/"><strong>imediff2</strong></a> is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via <span class="caps">SSH</span>.</li>
- </ul>
+ <big>Organization</big>
+ </h1>
+ <p>Ruby-VPI is a bridge between <span class="caps">IEEE 1364</span>-2005 Verilog VPI and the Ruby language. It enables Ruby programs to use VPI either (1) in the same, verbose way that C programs do, or (2) in a simpler, higher level way. In addition, it serves as a vehicle for the application of agile software development practices, such as <a href="#glossary.TDD">TDD</a> and <a href="#glossary.BDD">BDD</a> to the realm of hardware development with Verilog.</p>
- <h2 ><a id="setup.installation" href="#a-607914868">4.4</a> Installation</h2>
+ <p>Ruby-VPI can be used with any Verilog simulator that supports VPI. In particular, it is known to operate with (1) Synopsys VCS and Mentor Modelsim, the two <a href="http://www.eetimes.com/news/design/showArticle.jhtml?articleID=47204415">most prominent Verilog simulators</a> in the Electronic Design Automation (EDA) industry; as well as (2) GPL Cver and Icarus Verilog, the two most prevalent open source Verilog simulators today.</p>
- <p>Once you have satisfied the <a href="#setup.reqs">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
+ <p>
+ <hr style="display: none"/>
-<pre>
-$ gem env gemdir
-/usr/lib/ruby/gems/1.8
+ <div class="formal">
+ <div class="figure" id="fig:organization.detail">
+
-$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
-/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
-</pre>
+ <p class="title"><a href="#a-607731018">Figure 1</a>. Where does Ruby-VPI fit in?</p>
- <h3 ><a id="setup.installation.windows" href="#a-607916038">4.4.1</a> Installing on Windows</h3>
+ <img src="figures/organization_detailed.png" alt="" />
+ </div>
+ </div>
+
+As <a href="#fig:organization.detail">Figure 1</a> shows, Ruby-VPI is composed of two complementary parts: one interacts with VPI through the C language, while the other interacts with an executable specification written in the Ruby language. The former is complied during installation to produce dynamically loadable C libraries—-each tailored to accommodate the quirks of its respective Verilog simulator. The latter is not compiled because Ruby programs are interpreted dynamically.</p>
- <ul>
- <li>Install <a href="http://www.cygwin.com">Cygwin</a>, the Linux-like environment for Windows.</li>
- </ul>
+ <p>
+ <hr style="display: none"/>
+ <div id="overview.relay" class="section">
+ <h2 class="title">
+ <a href="#a-607737308">4.1</a>
-<div class="admonition">
+
-<div class="note" id="note2">
+ Ruby/Verilog interaction
+ </h2>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <p>In a typical VPI application written in C, the <em>Verilog simulator</em> is in charge. Verilog code temporarily transfers control to C by invoking C functions, which return control to Verilog when they finish.</p>
- <p class="title">Note: Undefined symbols in Windows</p>
+ <p>In contrast, Ruby-VPI puts the <em>specification</em> in charge. The specification temporarily transfers control to the Verilog simulator by invoking the <code class="code">advance_time</code> method, which returns control to the specification when it finishes. This process is illustrated in <a href="#fig:ruby_relay">Figure 2</a>.</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>Ruby-VPI’s approach is the same as any software testing framework, where the <em>specification</em> drives the design under test. Whereas, the typical VPI & C approach is literally <em>backwards</em> because the design under test drives the specification.</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>
+ <p>
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="figure" id="fig:ruby_relay">
+
-</div>
+ <p class="title"><a href="#a-607733828">Figure 2</a>. Interaction between Ruby and Verilog</p>
-</div>
+ <img src="figures/ruby_relay.png" alt="" />
- <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>
+ <ol>
+ <li>The current simulation time is <em>X</em>.</li>
+ <li>The specification invokes the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::advance_time</code> method with parameter <em>Y</em>, which specifies the number of simulation time steps to be simulated.</li>
+ <li>The Verilog simulator is now in control (temporarily).</li>
+ <li>The current simulation time has <em>not</em> changed; it is still <em>X</em>.</li>
+ <li>The Verilog simulator simulates <em>Y</em> simulation time steps.</li>
+ <li>The current simulation time is now <em>X + Y</em>.</li>
+ <li>The Verilog simulator returns control back to the specification.</li>
+ </ol>
+ </div>
+ </div>
+
+Another means of transferring control from the specification to the Verilog simulator is the <a href="#vpi.callbacks">VPI callback</a>.</p>
- <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>
+ </div>
+
+ <hr style="display: none"/>
- <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>
+ <div id="organization.tests" class="section">
+ <h2 class="title">
+ <a href="#a-607073988">4.2</a>
+
- <ul>
- <li>You may now install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command in Cygwin.</li>
- </ul>
+ Tests
+ </h2>
+ <p>In Ruby-VPI, the process of functional verification is neatly packaged into self-contained, executable tests. As <a href="#fig:organization">Figure 3</a> illustrates, a test is composed of a <strong>bench</strong>, a <strong>design</strong>, and a <strong>specification</strong>.</p>
- <h2 ><a id="setup.maintenance" href="#a-607917378">4.5</a> Maintenance</h2>
+ <p>
+ <hr style="display: none"/>
- <ul>
- <li>You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.</li>
- <li>You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.</li>
- </ul>
+ <div class="formal">
+ <div class="figure" id="fig:organization">
+
+ <p class="title"><a href="#a-607070888">Figure 3</a>. Organization of a test in Ruby-VPI</p>
- <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
+ <img src="figures/organization.png" alt="" />
+ </div>
+ </div>
+
+<strong>The bench</strong> is Ruby-VPI. It defines the environment in which functional verification takes place. This is analogous to a workbench in an electronics laboratory that is furnished with tools of measurement and manipulation such as oscilloscopes, voltmeters, soldering irons, and so on which enable engineers to verify electronic components and locate the source of defects within those components.</p>
- <h1 ><a id="usage" href="#a-607918548">5</a> Usage</h1>
+ <p><strong>The design</strong> is an instantiated Verilog module. To extend the analogy of the electronics laboratory, it corresponds to the electronic component that is verified by an engineer.</p>
- <h2 ><a id="usage.vpi" href="#a-607919458">5.1</a> <span class="caps">VPI</span> in Ruby</h2>
+ <p><strong>The specification</strong> is a Ruby program. In the electronics laboratory analogy, it corresponds to the engineer who inspects, manipulates, and verifies the electronic component. In terms of specification-driven functional verification, it corresponds to the executable specification.</p>
+ </div>
+ </p>
- <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>
+ <p>
+ <hr style="display: none"/>
- <p class="title">Capitalize those names!</p>
+ <div id="VPI_in_Ruby" class="section">
+ <h2 class="title">
+ <a href="#a-607153008">4.3</a>
+
- <p>The names of all <span class="caps">VPI</span> types, structures, and constants become <em>capitalized</em> because Ruby requires that the names of constants begin with a capital letter.</p>
+ VPI in Ruby
+ </h2>
+
+<hr style="display: none"/>
- <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby.</p>
+<div id="Deviations_from_the_VPI_standard" class="section">
+ <h3 class="title">
+ <a href="#a-607082938">4.3.1</a>
+
-<div class="admonition">
+ Deviations from the VPI standard
+ </h3>
-<div class="note" id="note3">
+ <p>Ruby-VPI makes the entire IEEE Std 1364-2005 VPI interface available to Ruby, but with the following minor differences.</p>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <p>
+<hr style="display: none"/>
- <p class="title">Note: No capitalization for <span class="caps">VPI</span> functions</p>
+<div id="Names_are_capitalized" class="section">
+ <h4 class="title">
+ <a href="#a-607076508">4.3.1.1</a>
+
- <p>Ruby’s capitalization rule does <em>not</em> apply to <span class="caps">VPI</span> functions—their names remain unchanged in Ruby.</p>
+ Names are capitalized
+ </h4>
+ <p>The names of all VPI types, structures, and constants become <em>capitalized</em> because Ruby requires that the names of constants begin with a capital letter. However, note that Ruby’s capitalization rule does <em>not</em> apply to VPI functions.</p>
-</div>
+ <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby. However, the <code class="code">vpi_handle</code> function remains as <code class="code">vpi_handle</code> in Ruby.</p>
+
</div>
+ </p>
- <p class="title">Use Ruby’s <code class="code">printf</code></p>
+ <p>
+<hr style="display: none"/>
- <p>The <span class="caps">VPI</span> functions <code class="code">vpi_vprintf</code> and <code class="code">vpi_mcd_vprintf</code> are not made accessible to Ruby. However, this isn’t a big problem because you can use Ruby’s <code class="code">printf</code> method instead.</p>
+<div id="a_vprintf__is__printf_" class="section">
+ <h4 class="title">
+ <a href="#a-607079008">4.3.1.2</a>
+
- <p>The reason for this limitation is that some C compilers have trouble with pointers to the <code class="code">va_list</code> type. For these compilers, the third line of source code shown below causes a “type mismatch” error.</p>
+ <code class="code">vprintf</code> is <code class="code">printf</code>
+ </h4>
+ The <code class="code">vpi_vprintf</code> and <code class="code">vpi_mcd_vprintf</code> VPI functions are aliased to <code class="code">vpi_printf</code> and <code class="code">vpi_mcd_printf</code> respectively because:
-<pre class="code" lang="c">
+
+ <ul>
+ <li>Ruby represents <a href="http://www.rubycentral.com/book/tut_methods.html#UA">variable argument lists as arrays</a> instead of defining a special datatype, such as <code class="code">va_list</code>, for them.</li>
+ </ul>
+
+
+ <ul>
+ <li>Some C compilers have trouble with pointers to the <code class="code">va_list</code> type. For these compilers, the third line of source code shown below causes a “type mismatch” error.</li>
+ </ul>
+
+
+ <pre class="code" lang="c">
<span style="color:#579">#include</span> <span style="color:#B44; font-weight:bold"><stdarg.h></span>
<span style="color:#339; font-weight:bold">void</span> foo(va_list ap) {
va_list *p = &ap;
}
</pre>
- <h3 ><a id="usage.vpi.handles" href="#a-607920448">5.1.1</a> Handles</h3>
+</div>
+ </p>
+</div>
+
- <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>
+ <hr style="display: none"/>
+ <div id="vpi.handles" class="section">
+ <h3 class="title">
+ <a href="#a-607114548">4.3.2</a>
-<div class="admonition">
+
-<div class="note" id="note4">
+ Handles
+ </h3>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <p>A <strong>handle</strong> is a reference to an object (such as a module, register, wire, and so on) inside the Verilog simulation. Handles allows you to inspect and manipulate the design under test and its internal components. They are instances of the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span></code> class (see <a href="../ref/ruby/classes/Vpi/Handle.html">reference documentation</a> for details) in Ruby-VPI.</p>
- <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>
+ <p>Handles have various <strong>properties</strong>, listed in the second column of <a href="#tbl:accessors">Table 1</a>, which provide different kinds of information about the underlying Verilog objects they represent. These properties are accessed through the VPI functions listed in the last column of <a href="#tbl:accessors">Table 1</a>.</p>
- <p>Handles are instances of the <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span></code> class (see <a href="../ref/ruby/classes/Vpi/Handle.html">reference documentation</a> for details) in Ruby-VPI.</p>
+ <p>Handles are typically obtained through the <code class="code">vpi_handle_by_name</code> and <code class="code">vpi_handle</code> functions. These functions are hierarchical in nature, as they allow you to obtain new handles that are related to existing ones. For example, to obtain a handle to a register contained within a module, one would typically write: <code class="code">your_reg = vpi_handle( <span style="color:#036; font-weight:bold">VpiReg</span>, your_handle )</code></p>
+ <p>
+<div id="Shortcuts_for_productivity" class="paragraph">
+ <p class="title">Shortcuts for productivity</p>
+ Given a handle, Ruby-VPI allows you to access (1) its relatives and (2) its properties simply by invoking methods on the handle. If a handle’s relative happens to have the same name as one its properties, then the relative is given priority because a handle’s properties can always be accessed explicitly through the <code class="code">handle.get_value</code> and <code class="code">handle.put_value</code> methods.
</div>
+ </p>
-</div>
- <p>Handles have various <em>properties</em>, which provide different kinds of information (see the “Kind of value accessed” column in <a href="#tbl..accessors">the table named “Possible accessors and their implications”</a>) about the underlying Verilog object represented by a handle. These properties are accessed through various functions, which are listed in the “VPI functions used to access the value” column in <a href="#tbl..accessors">the table named “Possible accessors and their implications”</a>.</p>
+ <p>
+<hr style="display: none"/>
+<div id="Accessing_a_handle_s_relatives" class="section">
+ <h4 class="title">
+ <a href="#a-607088158">4.3.2.2</a>
- <p>Handles are typically obtained through the <code class="code">vpi_handle_by_name</code> and <code class="code">vpi_handle</code> functions. These functions are hierarchical in nature, because they allow you to obtain new handles that are related to existing handles. For example, to obtain a handle to a register inside a module, you would typically write: <code class="code">some_reg = vpi_handle(<span style="color:#036; font-weight:bold">VpiReg</span>, some_handle)</code>.</p>
+
+ Accessing a handle’s relatives
+ </h4>
- <p class="title">Shortcuts for productivity</p>
+ <p>Imagine that the design under test, say <em>foo</em>, instantiated a Verilog module named <em>bar</em>, which in turn contained a register named <em>baz</em>. To access baz from Ruby, one could employ VPI idioms by writing:</p>
- <p>Given a handle, Ruby-VPI allows you to access (1) its relatives and (2) its properties by simply invoking its methods.</p>
+ <pre class="code">
+foo = vpi_handle_by_name( <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">foo</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span> )
+bar = vpi_handle_by_name( <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">bar</span><span style="color:#710">"</span></span>, foo )
+baz = vpi_handle_by_name( <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">baz</span><span style="color:#710">"</span></span>, bar )
+</pre>
- <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>
+ <p>or by writing:</p>
- <h4><a id="Accessing_a_handle__8217_s_relatives" href="#a-607921548">5.1.1.1</a> Accessing a handle’s relatives</h4>
+ <code class="code">baz = vpi_handle_by_name( <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">foo.bar.bar</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span> )</code>
- <p>To access a handle’s relative (a handle related to it), simply invoke the relative’s name as a method on the handle.</p>
+ <p>These idioms seem excessively verbose in a higher level language such as Ruby, so Ruby-VPI allows you to access a handle’s relative by simply invoking the relative’s name as a method on the handle:</p>
- <p>For example, to access the <code class="code">reset</code> signal of the <code class="code">counter</code> module shown in <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a>, you would write the following:</p>
+ <code class="code">foo.bar.baz</code>
+</div>
+ </p>
-<pre class="code">
-counter_module = vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">counter</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)
-reset_signal = counter_module.reset <span style="color:#888"># <== shortcut!</span>
+ <p>
+<hr style="display: none"/>
+
+<div id="Accessing_a_handle_s_properties" class="section">
+ <h4 class="title">
+ <a href="#a-607091098">4.3.2.3</a>
+
+
+
+ Accessing a handle’s properties
+ </h4>
+
+ <p>Imagine that the design under test, say <em>foo</em>, contained a register named <em>bar</em>. To access the integer value of <em>bar</em> in Ruby-VPI, one could employ VPI idioms by writing:</p>
+
+
+ <pre class="code">
+wrapper = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+wrapper.format = <span style="color:#036; font-weight:bold">VpiIntVal</span>
+vpi_get_value( foo.bar, wrapper )
+result = wrapper.value.integer
</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>
+ <p>or, if <em>bar</em> is capable of storing more than 32 bits, one would convert a string representation of bar’s integer value into a limitless Ruby integer by writing:</p>
- <h4><a id="Accessing_a_handle__8217_s_properties" href="#a-607922938">5.1.1.2</a> Accessing a handle’s properties</h4>
+ <pre class="code">
+wrapper = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+wrapper.format = <span style="color:#036; font-weight:bold">VpiHexStrVal</span>
+vpi_get_value( foo.bar, wrapper )
+result = wrapper.value.str.to_i( <span style="color:#00D; font-weight:bold">16</span> )
+</pre>
- <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>These idioms seem excessively verbose in a higher level language such as Ruby, so Ruby-VPI allows you to access a handle’s properties by simply invoking property names, using the special naming format shown in <a href="#fig:method_naming_format">Figure 4</a>, as methods on the handle:</p>
-<div class="formal">
-<div class="figure" id="figure4">
+ <code class="code">result = foo.bar.intVal</code>
- <p class="title">Figure 4. Method naming format for accessing a handle’s properties</p>
+</div>
+
+ <hr style="display: none"/>
- <table>
+ <div class="formal">
+ <div class="figure" id="fig:method_naming_format">
+
+
+ <p class="title"><a href="#a-607093898">Figure 4</a>. Method naming format for accessing a handle’s properties</p>
+
+ <table>
<tr>
<th>Operation </th>
<th>_ </th>
<th>Property </th>
<th>_ </th>
@@ -851,97 +1082,98 @@
<ul>
- <li><strong>Operation</strong> suggests a method that should be invoked in the context of the Property parameter. All <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">methods in the Enumerable module</a> are valid <em>operations</em>.</li>
+ <li><strong>Operation</strong> suggests a method that should be invoked in the context of the <strong>Property</strong> parameter. All methods in <a href="http://www.ruby-doc.org/core/classes/Enumerable.html">Ruby’s <code class="code"><span style="color:#036; font-weight:bold">Enumerable</span></code> module</a> are valid operations.</li>
</ul>
<ul>
- <li><strong>Property</strong> suggests a <span class="caps">VPI</span> property that should be accessed. The “vpi” prefix, which is common to all <span class="caps">VPI</span> properties, can be omitted if you wish. For example, the <span class="caps">VPI</span> property “vpiFullName” is considered equivalent to “fullName” and “FullName”, but not equivalent “full_name”.</li>
+ <li><strong>Property</strong> suggests a VPI property that should be accessed. The “vpi” prefix, which is common to all VPI properties, can be omitted if you wish. For example, the VPI property “vpiFullName” is considered equivalent to “fullName” and “FullName”, but not equivalent to “full_name”.</li>
</ul>
<ul>
- <li><strong>Accessor</strong> suggests a <span class="caps">VPI</span> function that should be used in order to access the <span class="caps">VPI</span> property. When this parameter is not specified, Ruby-VPI will attempt to <em>guess</em> the value of this parameter.
+ <li><strong>Accessor</strong> suggests a VPI function that should be used in order to access the VPI property. When this parameter is not specified, Ruby-VPI will attempt to <em>guess</em> the value of this parameter.
-<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>
+ <p><a href="#tbl:accessors">Table 1</a> shows a list of valid accessors and how they influence the means by which a property is accessed.</p></li>
</ul>
<ul>
- <li><strong>Addendum</strong> suggests that the specified <span class="caps">VPI</span> property should be queried as a boolean value when it is a question mark <code class="code">?</code>. This suggestion is the same as specifying <code class="code">b</code> for the Accessor parameter.
+ <li>When <strong>Addendum</strong> is an equal sign (=), it suggests that the specified VPI property should be written to.
- <p>Also, when this parameter is an equal sign <code class="code">=</code>, it suggests that the specified <span class="caps">VPI</span> property should be written to.</p></li>
+ <p>When it is a question mark (?), it suggests that the specified VPI property should be accessed as a boolean value. This suggestion is the same as specifying “b” as the <strong>Accessor</strong>.</p></li>
</ul>
+ </div>
+ </div>
+
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="table" id="tbl:accessors">
+
-</div>
+ <p class="title"><a href="#a-607096328">Table 1</a>. Possible accessors and their implications</p>
-<div class="formal">
-
-<div class="table" id="tbl..accessors">
-
- <p class="title">Table 1. Possible accessors and their implications</p>
-
-
- <table>
+ <table>
<tr>
<th>Accessor </th>
<th>Kind of value accessed </th>
- <th><span class="caps">VPI</span> functions used to access the value </th>
+ <th>VPI functions used to access the value </th>
</tr>
<tr>
<td> d </td>
- <td> delay </td>
+ <td> delay </td>
<td> <code class="code">vpi_get_delays</code>, <code class="code">vpi_put_delays</code> </td>
</tr>
<tr>
<td> l </td>
- <td> logic </td>
- <td> <code class="code">vpi_get_value</code>, <code class="code">vpi_put_value</code> </td>
+ <td> logic </td>
+ <td> <code class="code">vpi_get_value</code>, <code class="code">vpi_put_value</code> </td>
</tr>
<tr>
<td> i </td>
<td> integer </td>
- <td> <code class="code">vpi_get</code> </td>
+ <td> <code class="code">vpi_get</code> </td>
</tr>
<tr>
<td> b </td>
<td> boolean </td>
- <td> <code class="code">vpi_get</code> </td>
+ <td> <code class="code">vpi_get</code> </td>
</tr>
<tr>
<td> s </td>
- <td> string </td>
- <td> <code class="code">vpi_get_str</code> </td>
+ <td> string </td>
+ <td> <code class="code">vpi_get_str</code> </td>
</tr>
<tr>
<td> h </td>
- <td> handle </td>
- <td> <code class="code">vpi_handle</code> </td>
+ <td> handle </td>
+ <td> <code class="code">vpi_handle</code> </td>
</tr>
+ <tr>
+ <td> a </td>
+ <td> array </td>
+ <td> <code class="code">vpi_iterate</code> </td>
+ </tr>
</table>
+ </div>
+ </div>
+
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="table" id="ex:properties">
+
+ <p class="title"><a href="#a-607099288">Table 2</a>. Examples of accessing a handle’s properties</p>
-</div>
-
-</div>
-
-<div class="formal">
-
-<div class="example" id="ex..properties">
-
- <p class="title">Example 1. Examples of accessing a handle’s properties</p>
-
-
- <table>
+ <table>
<tr>
<th rowspan="2">Ruby expression </th>
<th colspan="6">Method naming format </th>
<th rowspan="2">Description </th>
</tr>
@@ -959,11 +1191,11 @@
<td> </td>
<td> vpiIntVal </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the <strong>logic value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
+ <td rowspan="4">Obtain the <em>logic value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiIntVal_l</code> </td>
<td> </td>
<td> </td>
@@ -996,11 +1228,11 @@
<td> </td>
<td> vpiIntVal </td>
<td> </td>
<td> </td>
<td> = </td>
- <td rowspan="4">These expressions assign the number 15 to the <strong>logic value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
+ <td rowspan="4">Assign the integer 15 to the <em>logic value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiIntVal_l = <span style="color:#00D; font-weight:bold">15</span></code> </td>
<td> </td>
<td> </td>
@@ -1033,11 +1265,11 @@
<td> </td>
<td> vpiType </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the <strong>integer value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiType</span></code> property. </td>
+ <td rowspan="4">Obtain the <em>integer value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiType</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiType_i</code> </td>
<td> </td>
<td> </td>
@@ -1070,11 +1302,11 @@
<td> </td>
<td> vpiProtected </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="6">These expressions access the <strong>boolean value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiProtected</span></code> property. </td>
+ <td rowspan="6">Obtain the <em>boolean value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiProtected</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiProtected_b</code> </td>
<td> </td>
<td> </td>
@@ -1125,11 +1357,11 @@
<td> </td>
<td> vpiFullName </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the <strong>string value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiFullName</span></code> property. </td>
+ <td rowspan="4">Obtain the <em>string value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiFullName</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiFullName_s</code> </td>
<td> </td>
<td> </td>
@@ -1162,11 +1394,11 @@
<td> </td>
<td> vpiParent </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the <strong>handle value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiParent</span></code> property. </td>
+ <td rowspan="4">Obtain the <em>handle value</em> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiParent</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiParent_h</code> </td>
<td> </td>
<td> </td>
@@ -1199,11 +1431,11 @@
<td> _ </td>
<td> vpiNet </td>
<td> </td>
<td> </td>
<td> </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>
+ <td rowspan="2">Use the <code class="code">each</code> operation to 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>
@@ -1218,11 +1450,11 @@
<td> _ </td>
<td> vpiReg </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="2">These expressions check if all registers associated with the handle are capable of storing only one bit. </td>
+ <td rowspan="2">Use the <code class="code">all?</code> operation to check whether all <code class="code"><span style="color:#036; font-weight:bold">VpiReg</span></code> objects associated with the handle are capable of storing only one bit of information. </td>
</tr>
<tr>
<td> <code class="code">handle.all_reg? {|reg| reg.size == <span style="color:#00D; font-weight:bold">1</span>}</code> </td>
<td> all? </td>
<td> _ </td>
@@ -1237,11 +1469,11 @@
<td> _ </td>
<td> VpiNet </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="2">These expressions return a list of nets whose <strong>logic value</strong> is unknown or “don’t care” (x).</td>
+ <td rowspan="2">Use the <code class="code">select</code> operation to obtain a list of <code class="code"><span style="color:#036; font-weight:bold">VpiNet</span></code> objects whose <em>logic value</em> is unknown (x).</td>
</tr>
<tr>
<td> <code class="code">handle.select_net {|net| net.x?}</code> </td>
<td> select </td>
<td> _ </td>
@@ -1249,1196 +1481,1474 @@
<td> </td>
<td> </td>
<td> </td>
</tr>
</table>
+ </div>
+ </div>
+ </p>
+ </div>
+ <hr style="display: none"/>
-</div>
+ <div id="vpi.callbacks" class="section">
+ <h3 class="title">
+ <a href="#a-607126458">4.3.3</a>
-</div>
+
- <h3 ><a id="usage.vpi.callbacks" href="#a-607924498">5.1.2</a> Callbacks</h3>
+ 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.</p>
- <p>A <em>callback</em> is a mechanism that makes the Verilog simuluator execute a block of code, which is known as a “callback handler”, when some prescribed event occurs in the simulation. They are set up using the <code class="code">vpi_register_cb</code> function and torn down using the <code class="code">vpi_remove_cb</code> function.</p>
+ <p>Callbacks are added using the <code class="code">vpi_register_cb</code> function and removed using the <code class="code">vpi_remove_cb</code> function. However, instead of storing the address of a C function in the <code class="code">cb_rtn</code> field of the <code class="code">s_cb_data</code> structure (as you would do in C) you pass a block of code to the <code class="code">vpi_register_cb</code> method in Ruby. This block will be executed whenever the callback occurs.</p>
-<div class="formal">
-<div class="example" id="ex..callback">
+ <p>
+ <hr style="display: none"/>
- <p class="title">Example 2. Using a callback for value change notification</p>
+ <div class="formal">
+ <div class="example" id="ex:callback">
+
+ <p class="title"><a href="#a-607121788">Example 1</a>. Using a callback for value change notification</p>
- <p>This example shows how to use a callback for notification of changes in a handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. When you no longer need this callback, you can tear it down using <code class="code">vpi_remove_cb(cb_handle)</code>.</p>
+ <p>This example shows how to use a callback for notification of changes in a handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. When you no longer need this callback, you can tear it down using <code class="code">vpi_remove_cb(cb_handle)</code>.</p>
- <p>In this example, the handle being monitored is the <code class="code"><span style="color:#036; font-weight:bold">Counter</span>.count</code> signal from <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a>.</p>
+ <p>In this example, the handle being monitored is the <code class="code"><span style="color:#036; font-weight:bold">Counter</span>.count</code> signal from <a href="#fig:counter.v_decl">Example 3</a>.</p>
-<pre class="code">
-cbTime = <span style="color:#036; font-weight:bold">S_vpi_time</span>.new
-cbTime.type = <span style="color:#036; font-weight:bold">VpiSimTime</span>
-cbTime.low = <span style="color:#00D; font-weight:bold">0</span>
-cbTime.high = <span style="color:#00D; font-weight:bold">0</span>
+ <pre class="code">
+cbTime = <span style="color:#036; font-weight:bold">S_vpi_time</span>.new
+cbTime.type = <span style="color:#036; font-weight:bold">VpiSimTime</span>
+cbTime.low = <span style="color:#00D; font-weight:bold">0</span>
+cbTime.high = <span style="color:#00D; font-weight:bold">0</span>
-cbValue = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
-cbValue.format = <span style="color:#036; font-weight:bold">VpiIntVal</span>
+cbValue = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+cbValue.format = <span style="color:#036; font-weight:bold">VpiIntVal</span>
-cbData = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
-cbData.reason = <span style="color:#036; font-weight:bold">CbValueChange</span>
-cbData.obj = <span style="color:#036; font-weight:bold">Counter</span>.count
-cbData.time = cbTime
-cbData.value = cbValue
-cbData.index = <span style="color:#00D; font-weight:bold">0</span>
+cbData = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
+cbData.reason = <span style="color:#036; font-weight:bold">CbValueChange</span>
+cbData.obj = <span style="color:#036; font-weight:bold">Counter</span>.count
+cbData.time = cbTime
+cbData.value = cbValue
+cbData.index = <span style="color:#00D; font-weight:bold">0</span>
cbHandle = vpi_register_cb(cbData) <span style="color:#080; font-weight:bold">do</span> |data|
+ time = (data.time.high << <span style="color:#00D; font-weight:bold">32</span>) | data.time.low
+ count = data.value.value.integer
+ puts <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">hello from callback! time=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>time<span style="font-weight: bold; color: #888">}</span></span><span style="color:#D20"> count=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>count<span style="font-weight: bold; color: #888">}</span></span><span style="color:#710">"</span></span>
+<span style="color:#080; font-weight:bold">end</span>
+</pre>
- time = (data.time.high << <span style="color:#00D; font-weight:bold">32</span>) | data.time.low
- count = data.value.value.integer
- puts <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">hello from callback! time=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>time<span style="font-weight: bold; color: #888">}</span></span><span style="color:#D20"> count=</span><span style="background: #eee"><span style="font-weight: bold; color: #888">#{</span>count<span style="font-weight: bold; color: #888">}</span></span><span style="color:#710">"</span></span>
+ <p>Append this code to the <tt>RSpec/counter_spec.rb</tt> file (provided in <a href="#usage.examples">Section 5.5</a> and discussed in <a href="#usage.tutorial.specification">Section 5.6.3</a>) and run the <a href="#usage.tutorial">counter_RSpec test</a></p>
+ </div>
+ </div>
+ </p>
-<span style="color:#080; font-weight:bold">end</span>
-</pre>
+ </div>
- <p>Shown below is the result of appending this code to the <tt>counter_rspec_spec.rb</tt> file (provided in <a href="#usage.examples">the section named “Sample tests”</a> and discussed in <a href="#usage.tutorial.specification">the section named “Specify your expectations”</a>) and running the <a href="#usage.tutorial">counter_rspec test</a>.</p>
+ </div>
+ </p>
+ </div>
+
-<pre>
-$ rake -f counter_rspec_runner.rake cver
+ <hr style="display: none"/>
-(in /home/sun/src/ruby-vpi/samp/counter)
-cver +loadvpi=/home/sun/src/ruby-vpi/lib/ruby-vpi/../../obj/ruby-vpi.cver.so:vlog_startup_routines_bootstrap counter.v counter_rspec_bench.v
-GPLCVER_2.11a of 07/05/05 (Linux-elf).
-Copyright (c) 1991-2005 Pragmatic C Software Corp.
- All Rights reserved. Licensed under the GNU General Public License (GPL).
- See the 'COPYING' file for details. NO WARRANTY provided.
-Today is Sat Dec 30 09:24:09 2006.
-Compiling source file "counter.v"
-Compiling source file "counter_rspec_bench.v"
-Highest level modules:
-counter_rspec_bench
+ <div id="usage" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607321458">5</a>
-A resetted counter's value
-hello from callback! time=1 count=0
-- should be zero
-hello from callback! time=5 count=1
-hello from callback! time=7 count=2
-hello from callback! time=9 count=3
-hello from callback! time=11 count=4
-hello from callback! time=13 count=5
-hello from callback! time=15 count=6
-hello from callback! time=17 count=7
-hello from callback! time=19 count=8
-hello from callback! time=21 count=9
-hello from callback! time=23 count=10
-hello from callback! time=25 count=11
-hello from callback! time=27 count=12
-hello from callback! time=29 count=13
-hello from callback! time=31 count=14
-hello from callback! time=33 count=15
-hello from callback! time=35 count=16
-hello from callback! time=37 count=17
-hello from callback! time=39 count=18
-hello from callback! time=41 count=19
-hello from callback! time=43 count=20
-hello from callback! time=45 count=21
-hello from callback! time=47 count=22
-hello from callback! time=49 count=23
-hello from callback! time=51 count=24
-hello from callback! time=53 count=25
-hello from callback! time=55 count=26
-hello from callback! time=57 count=27
-hello from callback! time=59 count=28
-hello from callback! time=61 count=29
-hello from callback! time=63 count=30
-hello from callback! time=65 count=31
-hello from callback! time=67 count=0
-- should increment by one count upon each rising clock edge
+ <br/><br/>
-A counter with the maximum value
-hello from callback! time=71 count=1
-hello from callback! time=73 count=2
-hello from callback! time=75 count=3
-hello from callback! time=77 count=4
-hello from callback! time=79 count=5
-hello from callback! time=81 count=6
-hello from callback! time=83 count=7
-hello from callback! time=85 count=8
-hello from callback! time=87 count=9
-hello from callback! time=89 count=10
-hello from callback! time=91 count=11
-hello from callback! time=93 count=12
-hello from callback! time=95 count=13
-hello from callback! time=97 count=14
-hello from callback! time=99 count=15
-hello from callback! time=101 count=16
-hello from callback! time=103 count=17
-hello from callback! time=105 count=18
-hello from callback! time=107 count=19
-hello from callback! time=109 count=20
-hello from callback! time=111 count=21
-hello from callback! time=113 count=22
-hello from callback! time=115 count=23
-hello from callback! time=117 count=24
-hello from callback! time=119 count=25
-hello from callback! time=121 count=26
-hello from callback! time=123 count=27
-hello from callback! time=125 count=28
-hello from callback! time=127 count=29
-hello from callback! time=129 count=30
-hello from callback! time=131 count=31
-hello from callback! time=133 count=0
-- should overflow upon increment
+ <big>Usage</big>
+ </h1>
-Finished in 0.042328 seconds
+
+ <hr style="display: none"/>
-3 specifications, 0 failures
-</pre>
+ <div id="usage.prototyping" class="section">
+ <h2 class="title">
+ <a href="#a-607223668">5.1</a>
-</div>
+
-</div>
+ Prototyping
+ </h2>
- <h2 ><a id="usage.prototyping" href="#a-607925708">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>
- <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>
+ <p>The prototyping process is completely transparent: there is absolutely no difference, in the eyes of your executable specification, between a real Verilog design or its Ruby prototype.</p>
-To create a prototype,
+ <p>In addition, the prototyping process is completely standard-based: Ruby prototypes emulate the behavior of real Verilog designs using <em>nothing more</em> than the VPI itself.</p>
+
+
+ <p>For example, compare the Verilog design shown in <a href="#fig:counter.v_impl">Example 11</a> with its Ruby prototype shown in figure <a href="#fig:counter_proto.rb">Example 8</a>. The prototype uses only VPI to (1) detect changes in its inputs and (2) manipulate its outputs accordingly. In addition, notice how well the prototype’s syntax reflects the intended behavior of the Verilog design. This similarity facilitates rapid translation of a prototype from Ruby into Verilog later in the design process.</p>
+
+
+ <p>
+ <div id="Getting_started" class="paragraph">
+ <p class="title">Getting started</p>
+ To create a prototype,
<ol>
- <li><a href="#usage.tutorial.declare-design">Determine the <strong>interface</strong></a> (Verilog module declaration) of your design.</li>
- <li><a href="#usage.tutorial.generate-test">Generate a test</a> for that interface.</li>
+ <li>Start with a <a href="#usage.tutorial.declare-design">Verilog module declaration</a> for your design.</li>
+ <li><a href="#usage.tutorial.generate-test">Generate a test</a> using that module declaration.</li>
<li><a href="#usage.tutorial.implement-proto">Implement the prototype</a> in the generated <tt>proto.rb</tt> file.</li>
<li><a href="#usage.tutorial.test-proto">Verify the prototype</a> against its specification.</li>
</ol>
<p>Once you are satisfied with your prototype, you can proceed to <a href="#usage.tutorial.implement-design">implement your design in Verilog</a>. This process is often a simple translation your Ruby prototype into your Verilog. At the very least, your prototype serves as a reference while you are implementing your Verilog design.</p>
- <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>
+ <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 (see <a href="#usage.test-runner">Section 5.3</a> for details).</p>
+ </div>
- <h2 ><a id="usage.debugger" href="#a-607926808">5.3</a> Debugging</h2>
+ <hr style="display: none"/>
+ <div id="How_does_prototyping_work_" class="section">
+ <h3 class="title">
+ <a href="#a-607218048">5.1.2</a>
- <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>
+
+ How does prototyping work?
+ </h3>
+ <p>The <code class="code">advance_time</code> method normally transfers control from the executable specification to the Verilog simulator. However, when prototyping is enabled, Ruby-VPI redefines it so that the <code class="code">feign!</code> method (which is defined in a test’s <tt>proto.rb</tt> file) is invoked on the design under test. The <code class="code">feign!</code> method artificially simulates the behavior of the real Verilog design.</p>
+
+
+ <p>In this manner, control is kept within the Ruby interpreter when prototyping is enabled. An advantage of this approach is that it reduces the total execution time of a Ruby-VPI test by allowing Ruby’s POSIX thread to commandeer the Verilog simulator’s process. A disadvantage of this approach is that callbacks, which require the transfer of control to the Verilog simulator, must be ignored.</p>
+
+ </div>
+</p>
+
+ </div>
+
+
+ <hr style="display: none"/>
+
+ <div id="usage.debugger" class="section">
+ <h2 class="title">
+ <a href="#a-607229298">5.2</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>
+
+
<ol>
- <li>Enable the debugger by activating the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable (see <a href="#usage.test-runner">the section named “Test runner”</a> for details).</li>
+ <li>Enable the debugger by activating the <code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span></code> environment variable (see <a href="#usage.test-runner">Section 5.3</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 ><a id="usage.debugger.init" href="#a-607927888">5.3.1</a> Advanced initialization</h3>
+ <p>
+ <hr style="display: none"/>
+ <div id="usage.debugger.init" class="section">
+ <h3 class="title">
+ <a href="#a-607226228">5.2.1</a>
- <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>
+
+ Advanced initialization
+ </h3>
+ 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 IDE (see <a href="http://www.datanoise.com/articles/category/ruby-debug">the ruby-debug documentation</a> for details), then:
+
+
<ol>
<li>Deactivate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable.</li>
- <li>Put your own code, which initializes the debugger, above the <code class="code"><span style="color:#036; font-weight:bold">RubyVpi</span>.init_bench</code> line in your generated <tt>spec.rb</tt> file.</li>
+ <li>Put your own code, which initializes the debugger, at the top of your test’s <tt>spec.rb</tt> file.</li>
</ol>
+ </div>
+</p>
- <h2 ><a id="usage.test-runner" href="#a-607929098">5.4</a> Test runner</h2>
+ </div>
+
+ <hr style="display: none"/>
- <p>A test runner is a file, generated by the <a href="#usage.tools.generate-test">automated test generator</a>, whose name ends with <tt>.rake</tt>. It helps you run generated tests—you can think of it as a <em>makefile</em> if you are familiar with C programming in a <span class="caps">UNIX</span> environment.</p>
+ <div id="usage.test-runner" class="section">
+ <h2 class="title">
+ <a href="#a-607246068">5.3</a>
+
-<div class="formal">
+ Test runner
+ </h2>
-<div class="example" id="example3">
+ <p>A test runner is a file, generated by the <a href="#usage.tools.generate">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 UNIX environment.</p>
- <p class="title">Example 3. Seeing what a test runner can do</p>
+ <p>When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f your_test_runner.rake
-When you invoke a test runner without any arguments, it will show you a list of available tasks:
-<pre>$ rake -f some_test_runner.rake
-
(in /home/sun/tmp/ruby-vpi/doc)
rake clean # Remove any temporary products.
rake clobber # Remove any generated file.
rake cver # Simulate with GPL Cver.
rake default # Show a list of available tasks.
rake ivl # Simulate with Icarus Verilog.
rake ncsim # Simulate with Cadence NC-Sim.
rake vcs # Simulate with Synopsys VCS.
rake vsim # Simulate with Mentor Modelsim.
-</pre>
+</pre></p>
-</div>
-</div>
+ <p>
+ <hr style="display: none"/>
-<div class="admonition">
+ <div id="usage.test-runner.env-vars" class="section">
+ <h3 class="title">
+ <a href="#a-607238958">5.3.1</a>
-<div class="tip" id="tip2">
+
- <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
+ 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>
- <p class="title">Tip: Running multiple tests at once.</p>
+ <ul>
+ <li><code class="code"><span style="color:#036; font-weight:bold">COVERAGE</span></code> enables code coverage analysis and generation of code coverage reports.</li>
+ <li><code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span></code> enables the <a href="#usage.debugger">interactive debugger</a> in its <a href="http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging">post-mortem debugging mode</a>.</li>
+ <li><code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> enables the Ruby prototype for the design under test so that the prototype, rather than the real Verilog design, is verified by the specification.</li>
+ </ul>
- <p>Create a file named <tt>Rakefile</tt> containing the following line:</p>
+ <p>To activate these variables, simply assign the number 1 to them. For example, <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=<span style="color:#00D; font-weight:bold">1</span></code> activates the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
- <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>To deactivate these variables, simply assign a different value to them or <strong>unset</strong> them in your shell. For example, both <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=<span style="color:#00D; font-weight:bold">0</span></code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=</code> dectivate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</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>
-
+ <p>
+<div id="Variables_as_command-line_arguments" class="paragraph">
+ <p class="title">Variables as command-line arguments</p>
+ You can specify variable assignments as arguments to the <strong>rake</strong> command. For example, <pre>rake DEBUG=1</pre> is equivalent to
+<pre>
+DEBUG=1
+export DEBUG
+rake
+</pre> in Bourne shell or
+<pre>
+setenv DEBUG 1
+rake
+</pre> in C shell.
</div>
+ </p>
-</div>
- <h3 ><a id="usage.test-runner.env-vars" href="#a-607930258">5.4.1</a> Environment variables</h3>
+ <p>
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="example" id="Running_a_test_with_environment_variables">
+
- <p>Test runners support the following <em>environment</em> variables, which allow you to easily change the behavior of the test runner.</p>
+ <p class="title"><a href="#a-607234788">Example 2</a>. Running a test with environment variables</p>
+ <p>Below, we enable the prototype and code coverage analysis:
+<pre>rake -f your_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre></p>
- <ul>
- <li><code class="code"><span style="color:#036; font-weight:bold">COVERAGE</span></code> enables code coverage analysis and generation of code coverage reports.</li>
- <li><code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> enables the <a href="#usage.debugger">interactive debugger</a> in its <a href="http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging">post-mortem debugging mode</a>.</li>
- <li><code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> enables the Ruby prototype for the design under test.</li>
- </ul>
+ <p>Below, we <em>disable</em> the prototype and enable the code coverage analysis. These invocations are equivalent if the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is unset.
+<pre>rake -f your_test_runner.rake PROTOTYPE=0 COVERAGE=1</pre>
+<pre>rake -f your_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f your_test_runner.rake COVERAGE=1</pre></p>
+ </div>
+ </div>
+ </p>
- <p>To activate these variables, simply assign a non-empty value to them. For example, <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=<span style="color:#00D; font-weight:bold">1</span></code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=yes</code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=foo_bar_baz</code> all activate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+ </div>
+</p>
+ </div>
+
- <p>To deactivate these variables, simply assign an <em>empty</em> value to them, <strong>unset</strong> them in your shell, or do not specify them as command-line arguments to rake. For example, both <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=</code> dectivates the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+ <hr style="display: none"/>
+ <div id="usage.tools" class="section">
+ <h2 class="title">
+ <a href="#a-607265218">5.4</a>
- <p>In addition, you can specify variable assignments as arguments to the <strong>rake</strong> command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
-$ DEBUG=1
-$ export DEBUG
-$ rake
-</pre> in Bourne shell or <pre>
-% setenv DEBUG 1
-% rake
-</pre> in C shell.</p>
+
+ Tools
+ </h2>
-<div class="formal">
+ <p>The <strong>ruby-vpi</strong> command serves as a front-end to the tools provided by Ruby-VPI. You can see its help information (reproduced below) by simply running the command without any arguments.</p>
-<div class="example" id="example4">
- <p class="title">Example 4. Running a test with environment variables</p>
+ <pre>This is a front-end for tools provided by Ruby-VPI.
+Usage:
-Here we enable the prototype and code coverage analysis:
-<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+ ruby-vpi Show this help message
+ ruby-vpi TOOL --help Show help message for TOOL
+ ruby-vpi TOOL arguments... Run TOOL with some arguments
-Here we <em>disable</em> the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
-<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
-<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+Tools:
+ convert Converts Verilog source code into Ruby.
+ generate Generates Ruby-VPI tests from Verilog 2001 and Verilog 95 module declarations.
-</div>
+Simulators:
+ cver GPL Cver
+ ivl Icarus Verilog
+ vcs Synopsys VCS
+ vsim Mentor Modelsim
+ ncsim Cadence NC-Sim
+</pre>
-</div>
- <h2 ><a id="usage.examples" href="#a-607931608">5.5</a> Sample tests</h2>
+ <p>
+ <hr style="display: none"/>
+ <div id="usage.tools.generate" class="section">
+ <h3 class="title">
+ <a href="#a-607255398">5.4.1</a>
- <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>
+
+ Automated test generation
+ </h3>
- <h2 ><a id="usage.tools" href="#a-607932628">5.6</a> Tools</h2>
+ <p>The <strong>generate</strong> tool generates scaffolding for Ruby-VPI tests from Verilog module declarations (written in either Verilog 2001 or Verilog 95 style).</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>--help</tt> option.</p>
+A Ruby-VPI test is composed of the following files:
+ <ul>
+ <li><tt>runner.rake</tt> runs the test by starting a Verilog simulator and loading Ruby-VPI into it.</li>
+ <li><tt>spec.rb</tt> is the executable specification for the design under test.</li>
+ <li><tt>design.rb</tt> is an optional file that provides convenience methods for controlling the design under test.</li>
+ <li><tt>proto.rb</tt> is an optional file that defines a Ruby prototype of the design under test.</li>
+ <li><tt>Rakefile</tt> is an optional file that recursively executes all <tt>runner.rake</tt> files found immediately within or beneath the current directory. It lets you simply run <pre>rake ...</pre> instead of having to write <pre>rake -f runner.rake ...</pre> every time.</li>
+ </ul>
- <h3 ><a id="usage.tools.generate-test" href="#a-607933658">5.6.1</a> Automated test generation</h3>
+ <p>As <a href="#fig:generate-test.RSpec">Example 4</a> shows, the name of each generated file is prefixed with the name of the Verilog module for which the test was generated. This convention helps organize tests within the file system, so that they are readily distinguishable from one another.</p>
- <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>
+ <p>
+ <hr style="display: none"/>
+ <div class="admonition">
+ <div class="caution" id="Do_not_rename_generated_files">
+ <img src="images/tango/caution.png" alt="caution" class="icon"/>
- <ul>
- <li>Runner
- – 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
- – written in Ruby, this file defines a prototype of the design being verified.</li>
- <li>Specification
- – written in Ruby, this file describes the expected behavior of the design.</li>
- </ul>
+ <p class="title"><a href="#a-607248828">Caution 1</a>. Do not rename generated files</p>
+ Ruby-VPI uses the convention described above to dynamically create a direct Ruby interface to the design under test, so <em>do not</em> rename the generated files arbitrarily.
+ </div>
+ </div>
+
+By producing multiple files, the automated test generator physically decouples the various parts of a test. As a result, when the interface of a Verilog module changes, you can simply regenerate the test to incorporate those changes without diverting your focus from the task at hand. Furthermore, the incorporation of changes can be catalyzed by interactive text merging tools, which allow you to selectively accept or reject the merging of changes into your source code. Fully automated text merging tools may also be used for this purpose.</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>
+ <p>You can try this tool by running the <pre>ruby-vpi generate --help</pre> command.</p>
-<div class="admonition">
-<div class="tip" id="tip3">
+ <p>
+ <hr style="display: none"/>
- <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
+ <div class="admonition">
+ <div class="tip" id="Using__kdiff3__with_the_automated_test_generator.">
+ <img src="images/tango/tip.png" alt="tip" class="icon"/>
+ <p class="title"><a href="#a-607251318">Tip 2</a>. Using <strong>kdiff3</strong> with the automated test generator.</p>
- <p class="title">Tip: Using <strong>kdiff3</strong> with the automated test generator.</p>
-
-
- <ol>
+ <ol>
<li>Create a file named <tt>merge2</tt> with the following content: <pre class="code">
<span style="color:#888">#!/bin/sh</span>
<span style="color:#888"># args: old file, new file</span>
-kdiff3 --auto --output <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">$2</span><span style="color:#710">"</span></span> <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">$@</span><span style="color:#710">"</span></span>
+kdiff3 --auto --output <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">$2</span><span style="color:#710">"</span></span> <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">$@</span><span style="color:#710">"</span></span>
</pre></li>
<li>Make the file executable by running the <pre>chmod +x merge2</pre> command.</li>
<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 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>
+ </p>
+ </div>
-</div>
-</div>
+ <hr style="display: none"/>
- <h3 ><a id="usage.tools.verilog-ruby-conv" href="#a-607934908">5.6.2</a> Verilog to Ruby conversion</h3>
+ <div id="usage.tools.convert" class="section">
+ <h3 class="title">
+ <a href="#a-607257688">5.4.2</a>
+
- <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>
+ Verilog to Ruby conversion
+ </h3>
+ <p>The <strong>convert</strong> tool can be used to convert Verilog header files into Ruby. You can try it by running the <pre>ruby-vpi convert --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>
+ <p>By converting Verilog header files into Ruby, your test 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 design.</p>
- <h2 ><a id="usage.tutorial" href="#a-607936328">5.7</a> Tutorial</h2>
+ </div>
+</p>
+ </div>
+
- <ol>
+ <hr style="display: none"/>
+
+ <div id="usage.examples" class="section">
+ <h2 class="title">
+ <a href="#a-607267438">5.5</a>
+
+
+
+ Sample tests
+ </h2>
+
+ 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.
+
+ </div>
+
+
+ <hr style="display: none"/>
+
+ <div id="usage.tutorial" class="section">
+ <h2 class="title">
+ <a href="#a-607188458">5.6</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>
+ <li><a href="#usage.tutorial.generate-test">Generate a test</a> for the design using the <a href="#usage.tools.generate">automated test generator</a> tool.</li>
<li><a href="#usage.tutorial.specification">Identify your expectations</a> for the design and implement them in the specification.</li>
<li>(Optional) <a href="#usage.tutorial.implement-proto">Implement the prototype</a> of the design in Ruby.</li>
<li>(Optional) <a href="#usage.tutorial.test-proto">Verify the prototype</a> against the specification.</li>
<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 ><a id="usage.tutorial.declare-design" href="#a-607937408">5.7.1</a> Start with a design</h3>
+ <p>
+ <hr style="display: none"/>
+ <div id="usage.tutorial.declare-design" class="section">
+ <h3 class="title">
+ <a href="#a-607274848">5.6.1</a>
- <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>
+
+ Start with a Verilog design
+ </h3>
+ <p>First, we need a Verilog design to test. In this tutorial, <a href="#fig:counter.v_decl">Example 3</a> will serve as our design under test. Its interface is composed of the following parts:</p>
+
+
<ul>
<li><code class="code"><span style="color:#036; font-weight:bold">Size</span></code> defines the number of bits used to represent the counter’s value.</li>
<li><code class="code">clock</code> causes the <code class="code">count</code> register to increment whenever it reaches a positive edge.</li>
<li><code class="code">reset</code> causes the <code class="code">count</code> register to become zero when asserted.</li>
<li><code class="code">count</code> is a register that contains the counter’s value.</li>
</ul>
-<div class="formal">
+ <p>
+ <hr style="display: none"/>
-<div class="example" id="fig..counter.v_decl">
+ <div class="formal">
+ <div class="example" id="fig:counter.v_decl">
+
- <p class="title">Example 5. Declaration of a simple up-counter with synchronous reset</p>
+ <p class="title"><a href="#a-607271338">Example 3</a>. Declaration of a simple up-counter with synchronous reset</p>
-
-<pre class="code" lang="verilog">
+ <pre class="code" lang="verilog">
module counter #(parameter Size = 5) (
- input clock,
- input reset,
- output reg [Size - 1 : 0] count
+ input clock,
+ input reset,
+ output reg [Size-1 : 0] count
);
endmodule
</pre>
+ </div>
+ </div>
+
+Before we continue, save the source code shown in <a href="#fig:counter.v_decl">Example 3</a> into a file named <tt>counter.v</tt>.</p>
-</div>
+ </div>
+</p>
-</div>
-<div class="admonition">
+ <p>
+ <hr style="display: none"/>
-<div class="important" id="important1">
+ <div id="usage.tutorial.generate-test" class="section">
+ <h3 class="title">
+ <a href="#a-607081228">5.6.2</a>
- <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
+
+ Generate a test
+ </h3>
- <p class="title">Important: Before we continue…</p>
+ <p>Now that we have a Verilog design to test, we shall use the <a href="#usage.tools.generate">generate</a> tool to generate some scaffolding for our test. This tool allows us to implement our specification using RSpec, xUnit, or any other format.</p>
- <p>Save the source code shown in <a href="#fig..counter.v_decl">the example named “Declaration of a simple up-counter with synchronous reset”</a> into a file named <tt>counter.v</tt>.</p>
-
-
-</div>
-
-</div>
-
- <h3 ><a id="usage.tutorial.generate-test" href="#a-607938748">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>
-
-
Each format represents a different software development methodology:
<ul>
- <li>rSpec represents <a href="#glossary.BDD"><span class="caps">BDD</span></a></li>
- <li>xUnit represents <a href="#glossary.TDD"><span class="caps">TDD</span></a></li>
+ <li>RSpec represents <a href="#glossary.BDD">BDD</a></li>
+ <li>xUnit represents <a href="#glossary.TDD">TDD</a></li>
<li>our own format can represent another methodology</li>
</ul>
-<div class="admonition">
+ <p>In this tutorial, you will see how both RSpec and xUnit formats are used. So let us make separate directories for both formats to avoid generated tests from overwriting each other:
+<pre>
+$ mkdir RSpec xUnit
+$ cp counter.v RSpec
+$ cp counter.v xUnit
+</pre></p>
-<div class="note" id="note5">
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <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">Example 4</a> and <a href="#fig:generate-test.xUnit">Example 5</a>.</p>
- <p class="title">Note:</p>
+ <p>
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="example" id="fig:generate-test.RSpec">
+
- <p>Both rSpec and xUnit formats are presented in this tutorial.</p>
+ <p class="title"><a href="#a-607278188">Example 4</a>. Generating a test with specification in RSpec format</p>
+ <pre>
+$ ruby-vpi generate counter.v --RSpec
-</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 6. Generating a test with specification in rSpec format</p>
-
-
-<pre>
-$ generate_test.rb counter.v --rspec --name rspec
-
module counter
- create counter_rspec_runner.rake
- create counter_rspec_bench.v
- create counter_rspec_bench.rb
- create counter_rspec_design.rb
- create counter_rspec_proto.rb
- create counter_rspec_spec.rb
+ create counter_runner.rake
+ create counter_design.rb
+ create counter_proto.rb
+ create counter_spec.rb
+ create Rakefile
</pre>
+ </div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="example" id="fig:generate-test.xUnit">
+
-<div class="formal">
+ <p class="title"><a href="#a-607073088">Example 5</a>. Generating a test with specification in xUnit format</p>
-<div class="example" id="fig..generate-test.unit-test">
+ <pre>
+$ ruby-vpi generate counter.v --xUnit
- <p class="title">Example 7. Generating a test with specification in xUnit format</p>
-
-
-<pre>
-$ generate_test.rb counter.v --xunit --name xunit
-
module counter
- create counter_xunit_runner.rake
- create counter_xunit_bench.v
- create counter_xunit_bench.rb
- create counter_xunit_design.rb
- create counter_xunit_proto.rb
- create counter_xunit_spec.rb
+ create counter_runner.rake
+ create counter_design.rb
+ create counter_proto.rb
+ create counter_spec.rb
+ create Rakefile
</pre>
+ </div>
+ </div>
+ </p>
-</div>
+ </div>
+</p>
-</div>
- <h3 ><a id="usage.tutorial.specification" href="#a-607940058">5.7.3</a> Specify your expectations</h3>
+ <p>
+ <hr style="display: none"/>
+ <div id="usage.tutorial.specification" class="section">
+ <h3 class="title">
+ <a href="#a-607098358">5.6.3</a>
- <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>
+
+ Specify your expectations
+ </h3>
+ <p>So far, the test generation tool has created a basic foundation for our test Now we must build upon this foundation by identifying our <a href="#glossary.expectation">expectation</a> of the design under test. That is, how do we expect the design to <em>behave</em> under certain conditions?</p>
+
+
Here are some reasonable expectations for our simple counter:
<ul>
<li>A resetted counter’s value should be zero.</li>
<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. 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>
+ <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:RSpec_counter_spec.rb">Example 6</a> and <a href="#fig:xUnit_counter_spec.rb">Example 7</a>.</p>
-<div class="formal">
-<div class="example" id="fig..counter_rspec_spec.rb">
+ <hr style="display: none"/>
- <p class="title">Example 8. Specification implemented in rSpec format</p>
+ <div class="formal">
+ <div class="example" id="fig:RSpec_counter_spec.rb">
+
+ <p class="title"><a href="#a-607085368">Example 6</a>. Specification implemented in RSpec format</p>
-<pre class="code"><span style="color:#888"># This file is a behavioral specification for the design under test.</span>
+ <pre class="code">require <span style="background-color:#fff0f0"><span style="color:#710">'</span><span style="color:#D20">spec</span><span style="color:#710">'</span></span>
<span style="color:#888"># lowest upper bound of counter's value</span>
-<span style="color:#036; font-weight:bold">LIMIT</span> = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#036; font-weight:bold">Counter</span>.<span style="color:#036; font-weight:bold">Size</span>.intVal
+<span style="color:#036; font-weight:bold">LIMIT</span> = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#036; font-weight:bold">Counter</span>::<span style="color:#036; font-weight:bold">Size</span>
<span style="color:#888"># maximum allowed value for a counter</span>
<span style="color:#036; font-weight:bold">MAX</span> = <span style="color:#036; font-weight:bold">LIMIT</span> - <span style="color:#00D; font-weight:bold">1</span>
-context <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">A resetted counter's value</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
+describe <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">A resetted counter's value</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
setup <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#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>
+ it <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 == <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>
+ it <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">should increment upon each rising clock edge</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">LIMIT</span>.times <span style="color:#080; font-weight:bold">do</span> |i|
<span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == i
- simulate <span style="color:#888"># increment the counter</span>
+ <span style="color:#036; font-weight:bold">Counter</span>.cycle! <span style="color:#888"># increment the counter</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
-context <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">A counter with the maximum value</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
+describe <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">A counter with the maximum value</span><span style="color:#710">"</span></span> <span style="color:#080; font-weight:bold">do</span>
setup <span style="color:#080; font-weight:bold">do</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#888"># increment the counter to maximum value</span>
- <span style="color:#036; font-weight:bold">MAX</span>.times {simulate}
+ <span style="color:#036; font-weight:bold">MAX</span>.times { <span style="color:#036; font-weight:bold">Counter</span>.cycle! }
<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>
- simulate <span style="color:#888"># increment the counter</span>
+ it <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>
+ <span style="color:#036; font-weight:bold">Counter</span>.cycle! <span style="color:#888"># increment the counter</span>
<span style="color:#036; font-weight:bold">Counter</span>.count.intVal.should == <span style="color:#00D; font-weight:bold">0</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
</pre>
+ </div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="example" id="fig:xUnit_counter_spec.rb">
+
-<div class="formal">
+ <p class="title"><a href="#a-607089898">Example 7</a>. Specification implemented in xUnit format</p>
-<div class="example" id="fig..counter_xunit_spec.rb">
+ <pre class="code">require <span style="background-color:#fff0f0"><span style="color:#710">'</span><span style="color:#D20">test/unit</span><span style="color:#710">'</span></span>
- <p class="title">Example 9. Specification implemented in xUnit format</p>
-
-
-<pre class="code"><span style="color:#888"># This file is a behavioral specification for the design under test.</span>
-
<span style="color:#888"># lowest upper bound of counter's value</span>
-<span style="color:#036; font-weight:bold">LIMIT</span> = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#036; font-weight:bold">Counter</span>.<span style="color:#036; font-weight:bold">Size</span>.intVal
+<span style="color:#036; font-weight:bold">LIMIT</span> = <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#036; font-weight:bold">Counter</span>::<span style="color:#036; font-weight:bold">Size</span>
<span style="color:#888"># maximum allowed value for a counter</span>
<span style="color:#036; font-weight:bold">MAX</span> = <span style="color:#036; font-weight:bold">LIMIT</span> - <span style="color:#00D; font-weight:bold">1</span>
<span style="color:#080; font-weight:bold">class</span> <span style="color:#B06; font-weight:bold">ResettedCounterValue</span> < <span style="color:#036; font-weight:bold">Test</span>::<span style="color:#036; font-weight:bold">Unit</span>::<span style="color:#036; font-weight:bold">TestCase</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">setup</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_zero</span>
- assert_equal <span style="color:#00D; font-weight:bold">0</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
+ assert_equal( <span style="color:#00D; font-weight:bold">0</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal )
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_increment</span>
<span style="color:#036; font-weight:bold">LIMIT</span>.times <span style="color:#080; font-weight:bold">do</span> |i|
- assert_equal i, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
- simulate <span style="color:#888"># increment the counter</span>
+ assert_equal( i, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal )
+ <span style="color:#036; font-weight:bold">Counter</span>.cycle! <span style="color:#888"># increment the counter</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">class</span> <span style="color:#B06; font-weight:bold">MaximumCounterValue</span> < <span style="color:#036; font-weight:bold">Test</span>::<span style="color:#036; font-weight:bold">Unit</span>::<span style="color:#036; font-weight:bold">TestCase</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">setup</span>
<span style="color:#036; font-weight:bold">Counter</span>.reset!
<span style="color:#888"># increment the counter to maximum value</span>
- <span style="color:#036; font-weight:bold">MAX</span>.times {simulate}
- assert_equal <span style="color:#036; font-weight:bold">MAX</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
+ <span style="color:#036; font-weight:bold">MAX</span>.times { <span style="color:#036; font-weight:bold">Counter</span>.cycle! }
+ assert_equal( <span style="color:#036; font-weight:bold">MAX</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal )
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_overflow</span>
- simulate <span style="color:#888"># increment the counter</span>
- assert_equal <span style="color:#00D; font-weight:bold">0</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal
+ <span style="color:#036; font-weight:bold">Counter</span>.cycle! <span style="color:#888"># increment the counter</span>
+ assert_equal( <span style="color:#00D; font-weight:bold">0</span>, <span style="color:#036; font-weight:bold">Counter</span>.count.intVal )
<span style="color:#080; font-weight:bold">end</span>
<span style="color:#080; font-weight:bold">end</span>
</pre>
-
-</div>
-
-</div>
-
-<div class="admonition">
-
-<div class="important" id="important2">
-
- <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
-
-
- <p class="title">Important: Before we continue…</p>
-
-
+ </div>
+ </div>
+
+Before we continue,
<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. <pre class="code"><span style="color:#888"># This is a Ruby interface to the design under test.</span>
+ <li>Replace the contents of the file named <tt>RSpec/counter_spec.rb</tt> with the source code shown in <a href="#fig:RSpec_counter_spec.rb">Example 6</a>.</li>
+ <li>Replace the contents of the file named <tt>xUnit/counter_spec.rb</tt> with the source code shown in <a href="#fig:xUnit_counter_spec.rb">Example 7</a>.</li>
+ <li>Replace the contents of the files named <tt>RSpec/counter_design.rb</tt> and <tt>xUnit/counter_design.rb</tt> with the following code. <pre class="code">
+<span style="color:#888"># Simulates the design under test for one clock cycle.</span>
+<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">cycle!</span>
+ clock.high!
+ advance_time
+ clock.low!
+ advance_time
+<span style="color:#080; font-weight:bold">end</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!
- reset.intVal = <span style="color:#00D; font-weight:bold">1</span>
- simulate
- reset.intVal = <span style="color:#00D; font-weight:bold">0</span>
+<span style="color:#888"># Brings the design under test into a blank state.</span>
+<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">reset!</span>
+ reset.high!
+ cycle!
+ reset.low!
<span style="color:#080; font-weight:bold">end</span>
</pre></li>
</ol>
+ </div>
+</p>
-</div>
-</div>
+ <p>
+ <hr style="display: none"/>
- <h3 ><a id="usage.tutorial.implement-proto" href="#a-607941368">5.7.4</a> Implement the prototype</h3>
+ <div id="usage.tutorial.implement-proto" class="section">
+ <h3 class="title">
+ <a href="#a-607106078">5.6.4</a>
+
- <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>
+ Implement the prototype
+ </h3>
+ <p>Now that we have a specification against which to verify our design 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">Example 8</a>.</p>
-<div class="formal">
-<div class="example" id="fig..counter_proto.rb">
+ <p>
+ <hr style="display: none"/>
- <p class="title">Example 10. Ruby prototype of our Verilog design</p>
+ <div class="formal">
+ <div class="example" id="fig:counter_proto.rb">
+
+ <p class="title"><a href="#a-607102138">Example 8</a>. Ruby prototype of our Verilog design</p>
-<pre class="code"><span style="color:#888"># This is a prototype of the design under test.</span>
-
-<span style="color:#888"># When prototyping is enabled, Vpi::advance_time invokes this</span>
-<span style="color:#888"># method instead of transferring control to the Verilog simulator.</span>
-<span style="color:#080; font-weight:bold">def</span> <span style="color:#036; font-weight:bold">Counter</span>.simulate!
+ <pre class="code"><span style="color:#888"># Ruby prototype of the design under test's Verilog implementation.</span>
+<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">feign!</span>
<span style="color:#080; font-weight:bold">if</span> clock.posedge?
- <span style="color:#080; font-weight:bold">if</span> reset.intVal == <span style="color:#00D; font-weight:bold">1</span>
+ <span style="color:#080; font-weight:bold">if</span> reset.high?
count.intVal = <span style="color:#00D; font-weight:bold">0</span>
<span style="color:#080; font-weight:bold">else</span>
count.intVal += <span style="color:#00D; font-weight:bold">1</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>
</pre>
+ </div>
+ </div>
+
+Before we continue, replace the contents of the files named <tt>RSpec/counter_proto.rb</tt> and <tt>xUnit/counter_proto.rb</tt> with the source code shown in <a href="#fig:counter_proto.rb">Example 8</a>.</p>
-</div>
+ </div>
+</p>
-</div>
-<div class="admonition">
+ <p>
+ <hr style="display: none"/>
-<div class="important" id="important3">
+ <div id="usage.tutorial.test-proto" class="section">
+ <h3 class="title">
+ <a href="#a-607132558">5.6.5</a>
- <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
+
+ Verify the prototype
+ </h3>
- <p class="title">Important: Before we continue…</p>
+ <p>Now that we have implemented our prototype, we are ready to verify it against our specification by running the test This process is illustrated by <a href="#fig:test-proto.RSpec">Example 9</a> and <a href="#fig:test-proto.unit-test">Example 10</a>.</p>
- <p>Replace the contents of the files named <tt>counter_rspec_proto.rb</tt> and <tt>counter_xunit_proto.rb</tt> with the source code shown in <a href="#fig..counter_proto.rb">the example named “Ruby prototype of our Verilog design”</a></p>
+ <p>In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is assigned the value 1 while running the test so that, instead of our design, our prototype is verified against our specification (see <a href="#usage.test-runner.env-vars">Section 5.3.1</a> for details). Also, the <a href="#setup.reqs">GPL Cver simulator</a> denoted by <em>cver</em>, is used to run the simulation.</p>
-</div>
+ <p>
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="example" id="fig:test-proto.RSpec">
+
- <h3 ><a id="usage.tutorial.test-proto" href="#a-607942708">5.7.5</a> Verify the prototype</h3>
+ <p class="title"><a href="#a-607119008">Example 9</a>. Running a test with specification in RSpec format</p>
+ <pre>
+$ cd RSpec
+$ rake cver PROTOTYPE=1
- <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>
+Ruby-VPI: prototype is enabled
+...
+Finished in 0.05106 seconds
- <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="formal">
-
-<div class="example" id="fig..test-proto.rspec">
-
- <p class="title">Example 11. Running a test with specification in rSpec format</p>
-
-
-<pre>
-$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
-
-Ruby-VPI: prototype has been enabled for test "counter_rspec"
-
-A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-
-A counter with the maximum value
-- should overflow upon increment
-
-Finished in 0.018199 seconds
-
-3 specifications, 0 failures
+3 examples, 0 failures
+cd -
</pre>
+ </div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="example" id="fig:test-proto.unit-test">
+
-<div class="formal">
+ <p class="title"><a href="#a-607123158">Example 10</a>. Running a test with specification in xUnit format</p>
-<div class="example" id="fig..test-proto.unit-test">
+ <pre>
+$ cd xUnit
+$ rake cver PROTOTYPE=1
- <p class="title">Example 12. Running a test with specification in xUnit format</p>
-
-
-<pre>
-$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1
-
-Ruby-VPI: prototype has been enabled for test "counter_xunit"
-
-Loaded suite counter_xunit_bench
+Ruby-VPI: prototype is enabled
+Loaded suite counter
Started
...
-Finished in 0.040668 seconds.
+Finished in 0.043859 seconds.
3 tests, 35 assertions, 0 failures, 0 errors
</pre>
+ </div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
-</div>
+ <div class="admonition">
+ <div class="tip" id="What_can_the_test_runner_do_">
+ <img src="images/tango/tip.png" alt="tip" class="icon"/>
-<div class="admonition">
+ <p class="title"><a href="#a-607126068">Tip 3</a>. What can the test runner do?</p>
-<div class="tip" id="tip4">
+ If you invoke the test runner (1) without any arguments or (2) with the <tt>--tasks</tt> option, it will show you a list of tasks that it can perform for you.
+ </div>
+ </div>
+ </p>
- <p style="float:left"><img src="images/tango/tip.png" title="tip" alt="tip" /></p>
+ </div>
+</p>
- <p class="title">Tip: What can the test runner do?</p>
+ <p>
+ <hr style="display: none"/>
+ <div id="usage.tutorial.implement-design" class="section">
+ <h3 class="title">
+ <a href="#a-607138718">5.6.6</a>
- <p>If you invoke the test runner (1) without any arguments or (2) with the <tt>--tasks</tt> option, it will show you a list of tasks that it can perform for you.</p>
+
+ Implement the design
+ </h3>
-</div>
+ <p>Now that we have implemented and verified our prototype, we are ready to implement our design 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">Example 11</a>.</p>
-</div>
- <h3 ><a id="usage.tutorial.implement-design" href="#a-607943958">5.7.6</a> Implement the design</h3>
+ <p>
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="example" id="fig:counter.v_impl">
+
- <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>
+ <p class="title"><a href="#a-607135238">Example 11</a>. Implementation of a simple up-counter with synchronous reset</p>
-
-<div class="formal">
-
-<div class="example" id="fig..counter.v_impl">
-
- <p class="title">Example 13. Implementation of a simple up-counter with synchronous reset</p>
-
-
-<pre class="code" lang="verilog">/**
+ <pre class="code" lang="verilog">/**
A simple up-counter with synchronous reset.
- @param Size Number of bits used to represent the counter's value.
- @param clock Increments the counter's value upon each positive edge.
- @param reset Zeroes the counter's value when asserted.
- @param count The counter's value.
+ @param Size Number of bits used to represent the counter's value.
+ @param clock Increments the counter's value upon each positive edge.
+ @param reset Zeroes the counter's value when asserted.
+ @param count The counter's value.
*/
module counter #(parameter Size = 5) (
- input clock,
- input reset,
- output reg [Size - 1 : 0] count
+ input clock,
+ input reset,
+ output reg [Size-1 : 0] count
);
always @(posedge clock) begin
if (reset)
count <= 0;
else
count <= count + 1;
end
endmodule
</pre>
+ </div>
+ </div>
+
+Before we continue, replace the contents of the files named <tt>RSpec/counter.v</tt> and <tt>xUnit/counter.v</tt> with the source code shown in <a href="#fig:counter.v_impl">Example 11</a></p>
-</div>
+ </div>
+</p>
-</div>
-<div class="admonition">
+ <p>
+ <hr style="display: none"/>
-<div class="important" id="important4">
+ <div id="usage.tutorial.test-design" class="section">
+ <h3 class="title">
+ <a href="#a-607149178">5.6.7</a>
- <p style="float:left"><img src="images/tango/important.png" title="important" alt="important" /></p>
+
+ Verify the design
+ </h3>
- <p class="title">Important: Before we continue…</p>
+ <p>Now that we have implemented our design we are ready to verify it against our specification by running the test <a href="#fig:test-design.RSpec">Example 12</a> and <a href="#fig:test-design.unit-test">Example 13</a> illustrate this process.</p>
- <p>Replace the contents of the file named <tt>counter.v</tt> with the source code shown in <a href="#fig..counter.v_impl">the example named “Implementation of a simple up-counter with synchronous reset”</a></p>
+ <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">GPL Cver simulator</a> denoted by <em>cver</em>, is used to run the simulation.</p>
-</div>
+ <p>
+ <hr style="display: none"/>
-</div>
+ <div class="formal">
+ <div class="example" id="fig:test-design.RSpec">
+
- <h3 ><a id="usage.tutorial.test-design" href="#a-607945338">5.7.7</a> Verify the design</h3>
+ <p class="title"><a href="#a-607141778">Example 12</a>. Running a test with specification in RSpec format</p>
+ <pre>
+$ cd RSpec
+$ rake cver
- <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>
+...
+Finished in 0.041198 seconds
- <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>
+3 examples, 0 failures
+</pre>
+ </div>
+ </div>
+
+ <hr style="display: none"/>
-<div class="formal">
+ <div class="formal">
+ <div class="example" id="fig:test-design.unit-test">
+
-<div class="example" id="fig..test-design.rspec">
+ <p class="title"><a href="#a-607144398">Example 13</a>. Running a test with specification in xUnit format</p>
- <p class="title">Example 14. Running a test with specification in rSpec format</p>
+ <pre>
+$ cd xUnit
+$ rake cver
+Loaded suite counter
+Started
+...
+Finished in 0.040262 seconds.
-<pre>
-$ rake -f counter_rspec_runner.rake cver
-
-A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-
-A counter with the maximum value
-- should overflow upon increment
-
-Finished in 0.005628 seconds
-
-3 specifications, 0 failures
+3 tests, 35 assertions, 0 failures, 0 errors
</pre>
+ </div>
+ </div>
+ </p>
-</div>
+ </div>
+</p>
-</div>
+ </div>
+
+ </div>
+
-<div class="formal">
+ <hr style="display: none"/>
-<div class="example" id="fig..test-design.unit-test">
+ <div id="hacking" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607333248">6</a>
- <p class="title">Example 15. Running a test with specification in xUnit format</p>
+ <br/><br/>
+ <big>Hacking</big>
+ </h1>
-<pre>
-$ rake -f counter_xunit_runner.rake cver
+ <p>
+ <hr style="display: none"/>
-Loaded suite counter_xunit_bench
-Started
-...
-Finished in 0.006766 seconds.
+ <div id="hacking.scm" class="section">
+ <h2 class="title">
+ <a href="#a-607323788">6.1</a>
-3 tests, 35 assertions, 0 failures, 0 errors
-</pre>
+
-</div>
+ Getting the source code
+ </h2>
-</div>
+ Check out the source code using <a href="http://darcs.net">Darcs</a> from the project repository:
- <h1 ><a id="hacking" href="#a-607946678">6</a> Hacking</h1>
+ <pre>darcs get http://ruby-vpi.rubyforge.org/src/ruby-vpi</pre>
- <h2 ><a id="hacking.scm" href="#a-607947628">6.1</a> Getting the source code</h2>
+ </div>
+ </p>
- <p>Check out the source code using <a href="http://darcs.net">Darcs</a> from the project repository:</p>
+ <p>
+ <hr style="display: none"/>
+ <div id="hacking.release-packages" class="section">
+ <h2 class="title">
+ <a href="#a-607326418">6.2</a>
- <pre>darcs get http://ruby-vpi.rubyforge.org/src/ruby-vpi</pre>
+
+ Building release packages
+ </h2>
- <h2 ><a id="hacking.release-packages" href="#a-607948608">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>
- <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://www.swig.org/">SWIG</a></li>
<li><a href="http://rubyforge.org/projects/redcloth/">RedCloth</a></li>
<li><a href="http://rubyforge.org/projects/coderay/">CodeRay</a></li>
</ul>
<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>
+ </div>
+ </p>
- <h1 ><a id="problems" href="#a-607949918">7</a> Known problems</h1>
+ <p>
+ <hr style="display: none"/>
- <p>This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.</p>
+ <div id="hacking.manual" class="section">
+ <h2 class="title">
+ <a href="#a-607328648">6.3</a>
+
- <h2 ><a id="problems.ruby" href="#a-607950878">7.1</a> Ruby</h2>
+ Editing this manual
+ </h2>
+ The “doc” files inside the <tt>doc/</tt> directory are really <em>plain text</em> files that contain the source code of this manual. You can edit these files and run the <pre>rake</pre> command to automatically generate the HTML documentation you are currently viewing.
- <h3 ><a id="problems.ruby.SystemStackError" href="#a-607951958">7.1.1</a> SystemStackError</h3>
+ </div>
+ </p>
+ </div>
+
+ <hr style="display: none"/>
-<div class="admonition">
+ <div id="problems" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607380138">7</a>
-<div class="note" id="note6">
+ <br/><br/>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <big>Known problems</big>
+ </h1>
+ <p>This chapter presents known problems and possible solutions.</p>
- <p class="title">Note: Fixed in 2.0.0.</p>
+ <p>
+ <hr style="display: none"/>
- <p>This problem was fixed in release 2.0.0 (2006-04-17).</p>
+ <div id="problem.ivl" class="section">
+ <h2 class="title">
+ <a href="#a-607358828">7.1</a>
+
-</div>
+ Icarus Verilog
+ </h2>
-</div>
+
+<hr style="display: none"/>
- <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>
+<div id="problems.ivl.vpi_handle_by_name.absolute-paths" class="section">
+ <h3 class="title">
+ <a href="#a-607339198">7.1.1</a>
+
- <h3 ><a id="problems.ruby.xUnit" href="#a-607953298">7.1.2</a> test/unit</h3>
+ Give full paths to Verilog objects
+ </h3>
+ <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>
-<div class="admonition">
-<div class="note" id="note7">
+ <p>For example, consider <a href="#ex:TestFoo">Example 14</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>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <p>
+ <hr style="display: none"/>
- <p class="title">Note: Fixed in 2.0.0.</p>
+ <div class="formal">
+ <div class="example" id="ex:TestFoo">
+
+ <p class="title"><a href="#a-607336038">Example 14</a>. Part of a bench which instantiates a Verilog design</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>
-
-
- <h2 ><a id="problem.ivl" href="#a-607954508">7.2</a> Icarus Verilog</h2>
-
-
- <h3 ><a id="problems.ivl.vpi_handle_by_name" href="#a-607955538">7.2.1</a> Vpi::vpi_handle_by_name</h3>
-
-
- <h4 ><a id="problems.ivl.vpi_handle_by_name.absolute-paths" href="#a-607956978">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>
-
-
- <p>For example, consider <a href="#ex..TestFoo">the example named “Part of a bench which instantiates a Verilog design”</a>. Here, one must write <code class="code">vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">TestFoo.my_foo.clk</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)</code> instead of <code class="code">vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">my_foo.clk</span><span style="color:#710">"</span></span>, <span style="color:#036; font-weight:bold">TestFoo</span>)</code> in order to access the <code class="code">clk</code> input of the <code class="code">my_foo</code> module instance.</p>
-
-
-<div class="formal">
-
-<div class="example" id="ex..TestFoo">
-
- <p class="title">Example 16. Part of a bench which instantiates a Verilog design</p>
-
-
-<pre class="code" lang="verilog">
+ <pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
Foo my_foo(.clk(clk_reg));
endmodule
</pre>
+ </div>
+ </div>
+ </p>
</div>
+
-</div>
+ <hr style="display: none"/>
- <h4 ><a id="problems.ivl.vpi_handle_by_name.connect-registers" href="#a-607958638">7.2.1.2</a> Registers must be connected</h4>
+ <div id="problems.ivl.vpi_handle_by_name.connect-registers" class="section">
+ <h3 class="title">
+ <a href="#a-607348888">7.1.2</a>
+
- <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>
+ Registers must be connected
+ </h3>
+ <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>
- <p>For example, suppose you wanted to access the <code class="code">clk_reg</code> register, from the bench shown in <a href="#ex..TestFoo_bad">the example named “Bad design with unconnected registers”</a> If you execute the statement <code class="code">clk_reg = vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">TestFoo.clk_reg</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)</code> in a specification, then you will discover that the <code class="code">vpi_handle_by_name</code> method returns <code class="code"><span style="color:#038; font-weight:bold">nil</span></code> instead of a handle to the <code class="code">clk_reg</code> register.</p>
+ <p>For example, suppose you wanted to access the <code class="code">clk_reg</code> register, from the bench shown in <a href="#ex:TestFoo_bad">Example 15</a> If you execute the statement <code class="code">clk_reg = vpi_handle_by_name(<span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">TestFoo.clk_reg</span><span style="color:#710">"</span></span>, <span style="color:#038; font-weight:bold">nil</span>)</code> in a specification, then you will discover that the <code class="code">vpi_handle_by_name</code> method returns <code class="code"><span style="color:#038; font-weight:bold">nil</span></code> instead of a handle to the <code class="code">clk_reg</code> register.</p>
- <p>The solution is to change the design such that it appears like the one shown in <a href="#ex..TestFoo_fix">the example named “Fixed design with wired registers”</a> where the register is connected to a wire, or <a href="#ex..TestFoo">the example named “Part of a bench which instantiates a Verilog design”</a> where the register is connected to a module instantiation.</p>
+ <p>The solution is to change the design such that it appears like the one shown in <a href="#ex:TestFoo_fix">Example 16</a> where the register is connected to a wire, or <a href="#ex:TestFoo">Example 14</a> where the register is connected to a module instantiation.</p>
-<div class="formal">
-<div class="example" id="ex..TestFoo_bad">
+ <p>
+ <hr style="display: none"/>
- <p class="title">Example 17. Bad design with unconnected registers</p>
+ <div class="formal">
+ <div class="example" id="ex:TestFoo_bad">
+
+ <p class="title"><a href="#a-607342098">Example 15</a>. Bad design with unconnected registers</p>
-<pre class="code" lang="verilog">
+ Here the <code class="code">clk_reg</code> register is not connected to anything.
+
+
+ <pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
endmodule
</pre>
+ </div>
+ </div>
+
- <p>Here the <code class="code">clk_reg</code> register is not connected to anything.</p>
+ <hr style="display: none"/>
+ <div class="formal">
+ <div class="example" id="ex:TestFoo_fix">
+
-</div>
+ <p class="title"><a href="#a-607344538">Example 16</a>. Fixed design with wired registers</p>
-</div>
+ Here the <code class="code">clk_reg</code> register is connected to the <code class="code">clk_wire</code> wire.
-<div class="formal">
-<div class="example" id="ex..TestFoo_fix">
-
- <p class="title">Example 18. Fixed design with wired registers</p>
-
-
-<pre class="code" lang="verilog">
+ <pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
wire clk_wire;
assign clk_wire = clk_reg;
endmodule
</pre>
+ </div>
+ </div>
+ </p>
- <p>Here the <code class="code">clk_reg</code> register is connected to the <code class="code">clk_wire</code> wire.</p>
+ </div>
-</div>
+ </div>
+
-</div>
+ <hr style="display: none"/>
- <h3 ><a id="problems.ivl.vpi_reset" href="#a-607960458">7.2.2</a> Vpi::reset</h3>
+ <div id="problems.ivl.vpi_reset" class="section">
+ <h2 class="title">
+ <a href="#a-607361048">7.2</a>
+
- <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>
+ Vpi::reset
+ </h2>
+ 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.
- <h2 ><a id="problems.vsim" href="#a-607961718">7.3</a> Mentor Modelsim</h2>
+ </div>
+ </p>
+ </div>
+
+ <hr style="display: none"/>
- <h3 ><a id="problems.vsim.ruby_run" href="#a-607962798">7.3.1</a> ruby_run();</h3>
+ <div id="glossary" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607138038">8</a>
+ <br/><br/>
-<div class="admonition">
+ <big>Glossary</big>
+ </h1>
-<div class="note" id="note8">
+
+ <hr style="display: none"/>
- <p style="float:left"><img src="images/tango/note.png" title="note" alt="note" /></p>
+ <div id="glossary.test" class="section">
+ <h2 class="title">
+ <a href="#a-607382968">8.1</a>
+
- <p class="title">Note: Fixed in 2.0.0.</p>
+ Test
+ </h2>
+ Something that checks if a <a href="#glossary.design">design</a> satisfies a <a href="#glossary.specification">specification</a>
- <p>This problem was fixed in release 2.0.0 (2006-04-17).</p>
+ </div>
+
+ <hr style="display: none"/>
-</div>
+ <div id="glossary.design" class="section">
+ <h2 class="title">
+ <a href="#a-607385468">8.2</a>
-</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>
+ Design
+ </h2>
+ 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?
- <h1 ><a id="glossary" href="#a-607964068">8</a> Glossary</h1>
+ </div>
+
+ <hr style="display: none"/>
- <h2 ><a id="glossary.bench" href="#a-607965038">8.1</a> Bench</h2>
+ <div id="glossary.specification" class="section">
+ <h2 class="title">
+ <a href="#a-607076108">8.3</a>
+
- <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>
+ Specification
+ </h2>
+ A set of <a href="#glossary.expectation">expectations</a> which define the desired behavior of a <a href="#glossary.design">design</a> when it is subjected to certain stimulus.
- <h2 ><a id="glossary.BDD" href="#a-607966068">8.2</a> Behavior driven development (BDD)</h2>
+ </div>
+
+ <hr style="display: none"/>
- <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>
+ <div id="glossary.expectation" class="section">
+ <h2 class="title">
+ <a href="#a-607080598">8.4</a>
+
- <p>See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
+ Expectation
+ </h2>
+ The desired response to some stimulus.
- <h2 ><a id="glossary.design" href="#a-607967048">8.3</a> Design</h2>
+ </div>
+
+ <hr style="display: none"/>
- <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>
+ <div id="glossary.handle" class="section">
+ <h2 class="title">
+ <a href="#a-607087288">8.5</a>
+
- <h2 ><a id="glossary.expectation" href="#a-607968108">8.4</a> Expectation</h2>
+ Handle
+ </h2>
+ A reference to an object inside the Verilog simulation. See <a href="#vpi.handles">Section 4.3.2</a> for usage instructions.
- <p>The desired response to some stimulus.</p>
+ </div>
+
+ <hr style="display: none"/>
- <h2 ><a id="glossary.handle" href="#a-607969248">8.5</a> Handle</h2>
+ <div id="glossary.rake" class="section">
+ <h2 class="title">
+ <a href="#a-607093708">8.6</a>
+
- <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>
+ Rake
+ </h2>
-
- <h2 ><a id="glossary.rake" href="#a-607970298">8.6</a> Rake</h2>
-
-
- <blockquote>
+ <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>
<p style="text-align:right;">—<a href="http://docs.rubyrake.org">Rake documentation</a></p>
+ </div>
+
- <h2 ><a id="glossary.rspec" href="#a-607971318">8.7</a> rSpec</h2>
+ <hr style="display: none"/>
+ <div id="glossary.RSpec" class="section">
+ <h2 class="title">
+ <a href="#a-607099278">8.7</a>
- <p>The <a href="#glossary.BDD"><span class="caps">BDD</span></a> framework for Ruby.</p>
+
+ RSpec
+ </h2>
- <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>
+ <p>The <a href="#glossary.BDD">BDD</a> framework for Ruby.</p>
- <h2 ><a id="glossary.specification" href="#a-607972348">8.8</a> Specification</h2>
+ <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>
+ </div>
+
- <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>
+ <hr style="display: none"/>
+ <div id="glossary.TDD" class="section">
+ <h2 class="title">
+ <a href="#a-607104428">8.8</a>
- <h2 ><a id="glossary.TDD" href="#a-607973538">8.9</a> Test driven development (TDD)</h2>
+
+ Test driven development
+ </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>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>
+ </div>
+
- <h2 ><a id="glossary.test" href="#a-607974518">9.0</a> Test</h2>
+ <hr style="display: none"/>
+ <div id="glossary.BDD" class="section">
+ <h2 class="title">
+ <a href="#a-607113088">8.9</a>
- <p>Something that checks if a <a href="#glossary.design">design</a> satisfies a <a href="#glossary.specification">specification</a>.</p>
+
+ Behavior driven development
+ </h2>
- <h2 ><a id="glossary.test_bench" href="#a-607975528">9.1</a> Test bench</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>An allusion to <a href="#background.vocab">a bench in an electronics laboratory</a>, or so it seems.</p>
- </body>
+ <p>See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
+
+ </div>
+
+ </div>
+ </div>
+
+ <hr style="display: none"/>
+ <div id="toc">
+ <h1 id="toc:contents">Contents</h1>
+ <ul><li><span class="hide">1 </span><a id="a-607611558" href="#Ruby-VPI_17.0.0_user_manual">Ruby-VPI 17.0.0 user manual</a><ul><li><span class="hide">1.1 </span><a id="a-607604718" href="#About_this_manual">About this manual</a></li><li><span class="hide">1.2 </span><a id="a-607607248" href="#Legal_notice">Legal notice</a></li></ul></li><li><span class="hide">2 </span><a id="a-607687748" href="#intro">Welcome</a><ul><li><span class="hide">2.1 </span><a id="a-607624238" href="#resources">Resources</a><ul><li><span class="hide">2.1.1 </span><a id="a-607614278" href="#Records">Records</a></li><li><span class="hide">2.1.2 </span><a id="a-607616618" href="#Documentation">Documentation</a></li><li><span class="hide">2.1.3 </span><a id="a-607619258" href="#Facilities">Facilities</a></li></ul></li><li><span class="hide">2.2 </span><a id="a-607636548" href="#intro.features">Features</a><ul><li><span class="hide">2.2.1 </span><a id="a-607626878" href="#Portable">Portable</a></li><li><span class="hide">2.2.2 </span><a id="a-607629278" href="#Agile">Agile</a></li><li><span class="hide">2.2.3 </span><a id="a-607631678" href="#Powerful">Powerful</a></li></ul></li><li><span class="hide">2.3 </span><a id="a-607648378" href="#intro.reqs">Requirements</a><ul><li><span class="hide">2.3.1 </span><a id="a-607639108" href="#Verilog_simulator">Verilog simulator</a></li><li><span class="hide">2.3.2 </span><a id="a-607641448" href="#Compilers">Compilers</a></li><li><span class="hide">2.3.3 </span><a id="a-607643748" href="#Libraries">Libraries</a></li></ul></li><li><span class="hide">2.4 </span><a id="a-607650938" href="#intro.applications">Applications</a></li><li><span class="hide">2.5 </span><a id="a-607653538" href="#intro.appetizers">Appetizers</a></li><li><span class="hide">2.6 </span><a id="a-607656258" href="#intro.license">License</a></li><li><span class="hide">2.7 </span><a id="a-607661648" href="#intro.related-works">Related works</a><ul><li><span class="hide">2.7.1 </span><a id="a-607658708" href="#intro.related-works.pli">Ye olde PLI</a></li></ul></li></ul></li><li><span class="hide">3 </span><a id="a-607728418" href="#setup">Setup</a><ul><li><span class="hide">3.1 </span><a id="a-607690938" href="#setup.manifest">Manifest</a></li><li><span class="hide">3.2 </span><a id="a-607696378" href="#setup.reqs">Requirements</a></li><li><span class="hide">3.3 </span><a id="a-607702548" href="#setup.recom">Recommendations</a><ul><li><span class="hide">3.3.1 </span><a id="a-607699208" href="#setup.recom.merger">Text merging tool</a></li></ul></li><li><span class="hide">3.4 </span><a id="a-607711698" href="#setup.inst">Installation</a><ul><li><span class="hide">3.4.1 </span><a id="a-607707638" href="#setup.inst.windows">Installing on Windows</a></li></ul></li><li><span class="hide">3.5 </span><a id="a-607713978" href="#setup.maintenance">Maintenance</a></li></ul></li><li><span class="hide">4 </span><a id="a-607211338" href="#organization">Organization</a><ul><li><span class="hide">4.1 </span><a id="a-607737308" href="#overview.relay">Ruby/Verilog interaction</a></li><li><span class="hide">4.2 </span><a id="a-607073988" href="#organization.tests">Tests</a></li><li><span class="hide">4.3 </span><a id="a-607153008" href="#VPI_in_Ruby">VPI in Ruby</a><ul><li><span class="hide">4.3.1 </span><a id="a-607082938" href="#Deviations_from_the_VPI_standard">Deviations from the VPI standard</a><ul><li><span class="hide">4.3.1.1 </span><a id="a-607076508" href="#Names_are_capitalized">Names are capitalized</a></li><li><span class="hide">4.3.1.2 </span><a id="a-607079008" href="#a_vprintf__is__printf_"><code class="code">vprintf</code> is <code class="code">printf</code></a></li></ul></li><li><span class="hide">4.3.2 </span><a id="a-607114548" href="#vpi.handles">Handles</a><ul><li><span class="hide">4.3.2.1 </span><a id="a-607085598" href="#Shortcuts_for_productivity">Shortcuts for productivity</a></li><li><span class="hide">4.3.2.2 </span><a id="a-607088158" href="#Accessing_a_handle_s_relatives">Accessing a handle’s relatives</a></li><li><span class="hide">4.3.2.3 </span><a id="a-607091098" href="#Accessing_a_handle_s_properties">Accessing a handle’s properties</a></li></ul></li><li><span class="hide">4.3.3 </span><a id="a-607126458" href="#vpi.callbacks">Callbacks</a></li></ul></li></ul></li><li><span class="hide">5 </span><a id="a-607321458" href="#usage">Usage</a><ul><li><span class="hide">5.1 </span><a id="a-607223668" href="#usage.prototyping">Prototyping</a><ul><li><span class="hide">5.1.1 </span><a id="a-607215768" href="#Getting_started">Getting started</a></li><li><span class="hide">5.1.2 </span><a id="a-607218048" href="#How_does_prototyping_work_">How does prototyping work?</a></li></ul></li><li><span class="hide">5.2 </span><a id="a-607229298" href="#usage.debugger">Debugging</a><ul><li><span class="hide">5.2.1 </span><a id="a-607226228" href="#usage.debugger.init">Advanced initialization</a></li></ul></li><li><span class="hide">5.3 </span><a id="a-607246068" href="#usage.test-runner">Test runner</a><ul><li><span class="hide">5.3.1 </span><a id="a-607238958" href="#usage.test-runner.env-vars">Environment variables</a><ul><li><span class="hide">5.3.1.1 </span><a id="a-607232388" href="#Variables_as_command-line_arguments">Variables as command-line arguments</a></li></ul></li></ul></li><li><span class="hide">5.4 </span><a id="a-607265218" href="#usage.tools">Tools</a><ul><li><span class="hide">5.4.1 </span><a id="a-607255398" href="#usage.tools.generate">Automated test generation</a></li><li><span class="hide">5.4.2 </span><a id="a-607257688" href="#usage.tools.convert">Verilog to Ruby conversion</a></li></ul></li><li><span class="hide">5.5 </span><a id="a-607267438" href="#usage.examples">Sample tests</a></li><li><span class="hide">5.6 </span><a id="a-607188458" href="#usage.tutorial">Tutorial</a><ul><li><span class="hide">5.6.1 </span><a id="a-607274848" href="#usage.tutorial.declare-design">Start with a Verilog design</a></li><li><span class="hide">5.6.2 </span><a id="a-607081228" href="#usage.tutorial.generate-test">Generate a test</a></li><li><span class="hide">5.6.3 </span><a id="a-607098358" href="#usage.tutorial.specification">Specify your expectations</a></li><li><span class="hide">5.6.4 </span><a id="a-607106078" href="#usage.tutorial.implement-proto">Implement the prototype</a></li><li><span class="hide">5.6.5 </span><a id="a-607132558" href="#usage.tutorial.test-proto">Verify the prototype</a></li><li><span class="hide">5.6.6 </span><a id="a-607138718" href="#usage.tutorial.implement-design">Implement the design</a></li><li><span class="hide">5.6.7 </span><a id="a-607149178" href="#usage.tutorial.test-design">Verify the design</a></li></ul></li></ul></li><li><span class="hide">6 </span><a id="a-607333248" href="#hacking">Hacking</a><ul><li><span class="hide">6.1 </span><a id="a-607323788" href="#hacking.scm">Getting the source code</a></li><li><span class="hide">6.2 </span><a id="a-607326418" href="#hacking.release-packages">Building release packages</a></li><li><span class="hide">6.3 </span><a id="a-607328648" href="#hacking.manual">Editing this manual</a></li></ul></li><li><span class="hide">7 </span><a id="a-607380138" href="#problems">Known problems</a><ul><li><span class="hide">7.1 </span><a id="a-607358828" href="#problem.ivl">Icarus Verilog</a><ul><li><span class="hide">7.1.1 </span><a id="a-607339198" href="#problems.ivl.vpi_handle_by_name.absolute-paths">Give full paths to Verilog objects</a></li><li><span class="hide">7.1.2 </span><a id="a-607348888" href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li></ul></li><li><span class="hide">7.2 </span><a id="a-607361048" href="#problems.ivl.vpi_reset">Vpi::reset</a></li></ul></li><li><span class="hide">8 </span><a id="a-607138038" href="#glossary">Glossary</a><ul><li><span class="hide">8.1 </span><a id="a-607382968" href="#glossary.test">Test</a></li><li><span class="hide">8.2 </span><a id="a-607385468" href="#glossary.design">Design</a></li><li><span class="hide">8.3 </span><a id="a-607076108" href="#glossary.specification">Specification</a></li><li><span class="hide">8.4 </span><a id="a-607080598" href="#glossary.expectation">Expectation</a></li><li><span class="hide">8.5 </span><a id="a-607087288" href="#glossary.handle">Handle</a></li><li><span class="hide">8.6 </span><a id="a-607093708" href="#glossary.rake">Rake</a></li><li><span class="hide">8.7 </span><a id="a-607099278" href="#glossary.RSpec">RSpec</a></li><li><span class="hide">8.8 </span><a id="a-607104428" href="#glossary.TDD">Test driven development</a></li><li><span class="hide">8.9 </span><a id="a-607113088" href="#glossary.BDD">Behavior driven development</a></li></ul></li></ul>
+
+ <h1 id="toc:tip">Tips</h1>
+ <ol>
+ <li><a href="#Add_support_for_your_Verilog_simulator" id="a-607693408">Add support for your Verilog simulator</a></li>
+ <li><a href="#Using__kdiff3__with_the_automated_test_generator." id="a-607251318">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
+ <li><a href="#What_can_the_test_runner_do_" id="a-607126068">What can the test runner do?</a></li>
+ </ol>
+ <h1 id="toc:note">Notes</h1>
+ <ol>
+ <li><a href="#Tuning_for_maximum_performance" id="a-607705108">Tuning for maximum performance</a></li>
+ </ol>
+ <h1 id="toc:caution">Cautions</h1>
+ <ol>
+ <li><a href="#Do_not_rename_generated_files" id="a-607248828">Do not rename generated files</a></li>
+ </ol>
+ <h1 id="toc:figure">Figures</h1>
+ <ol>
+ <li><a href="#fig:organization.detail" id="a-607731018">Where does Ruby-VPI fit in?</a></li>
+ <li><a href="#fig:ruby_relay" id="a-607733828">Interaction between Ruby and Verilog</a></li>
+ <li><a href="#fig:organization" id="a-607070888">Organization of a test in Ruby-VPI</a></li>
+ <li><a href="#fig:method_naming_format" id="a-607093898">Method naming format for accessing a handle’s properties</a></li>
+ </ol>
+ <h1 id="toc:table">Tables</h1>
+ <ol>
+ <li><a href="#tbl:accessors" id="a-607096328">Possible accessors and their implications</a></li>
+ <li><a href="#ex:properties" id="a-607099288">Examples of accessing a handle’s properties</a></li>
+ </ol>
+ <h1 id="toc:example">Examples</h1>
+ <ol>
+ <li><a href="#ex:callback" id="a-607121788">Using a callback for value change notification</a></li>
+ <li><a href="#Running_a_test_with_environment_variables" id="a-607234788">Running a test with environment variables</a></li>
+ <li><a href="#fig:counter.v_decl" id="a-607271338">Declaration of a simple up-counter with synchronous reset</a></li>
+ <li><a href="#fig:generate-test.RSpec" id="a-607278188">Generating a test with specification in RSpec format</a></li>
+ <li><a href="#fig:generate-test.xUnit" id="a-607073088">Generating a test with specification in xUnit format</a></li>
+ <li><a href="#fig:RSpec_counter_spec.rb" id="a-607085368">Specification implemented in RSpec format</a></li>
+ <li><a href="#fig:xUnit_counter_spec.rb" id="a-607089898">Specification implemented in xUnit format</a></li>
+ <li><a href="#fig:counter_proto.rb" id="a-607102138">Ruby prototype of our Verilog design</a></li>
+ <li><a href="#fig:test-proto.RSpec" id="a-607119008">Running a test with specification in RSpec format</a></li>
+ <li><a href="#fig:test-proto.unit-test" id="a-607123158">Running a test with specification in xUnit format</a></li>
+ <li><a href="#fig:counter.v_impl" id="a-607135238">Implementation of a simple up-counter with synchronous reset</a></li>
+ <li><a href="#fig:test-design.RSpec" id="a-607141778">Running a test with specification in RSpec format</a></li>
+ <li><a href="#fig:test-design.unit-test" id="a-607144398">Running a test with specification in xUnit format</a></li>
+ <li><a href="#ex:TestFoo" id="a-607336038">Part of a bench which instantiates a Verilog design</a></li>
+ <li><a href="#ex:TestFoo_bad" id="a-607342098">Bad design with unconnected registers</a></li>
+ <li><a href="#ex:TestFoo_fix" id="a-607344538">Fixed design with wired registers</a></li>
+ </ol>
+ </div>
+ </body>
</html>