doc/manual.html in ruby-vpi-18.0.2 vs doc/manual.html in ruby-vpi-19.0.0
- old
+ new
@@ -1,39 +1,101 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<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="screen.css" media="screen" />
<link rel="stylesheet" type="text/css" href="print.css" media="print" />
+ <link rel="alternate stylesheet" type="text/css" href="print.css" title="Print Preview" />
<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 18.0.2 user manual</title>
+ <title>Ruby-VPI user manual</title>
</head>
<body>
- <div id="site-links">
- <a href="readme.html">Home</a>
- · <a href="manual.html">Manual</a>
- · <a href="memo.html">Memo</a>
- · <a href="history.html">History</a>
- <hr style="display: none"/>
- </div>
+ <div id="menu">
+ <h1>Site navigation</h1>
+ <ul id="site-links">
+ <li><a href="readme.html">Home</a></li>
+ <li><a href="manual.html">Manual</a></li>
+ <li><a href="memo.html">Memo</a></li>
+ <li><a href="history.html">History</a></li>
+ </ul>
- <div id="toc-links">
- <a href="#toc:contents">Contents</a> · <a href="#toc:tip">Tips</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>
- </div>
-
+ <h1>Menu navigation</h1>
+ <ul id="toc-links">
+ <li><a href="#toc-contents">Contents</a></li><li><a href="#toc:tip">Tips</a></li><li><a href="#toc:note">Notes</a></li><li><a href="#toc:caution">Cautions</a></li><li><a href="#toc:figure">Figures</a></li><li><a href="#toc:table">Tables</a></li><li><a href="#toc:example">Examples</a></li>
+ </ul>
+
+ <div id="toc">
+ <h1 id="toc-contents">Contents</h1>
+ <ul><li>1 <a id="a-607060028" href="#Ruby-VPI_user_manual" class="ref">Ruby-VPI user manual</a><ul><li>1.1 <a id="a-607052878" href="#About_this_manual" class="ref">About this manual</a></li><li>1.2 <a id="a-607055408" href="#Legal_notice" class="ref">Legal notice</a></li></ul></li><li>2 <a id="a-607140228" href="#intro" class="ref">Welcome</a><ul><li>2.1 <a id="a-607073948" href="#resources" class="ref">Resources</a><ul><li>2.1.1 <a id="a-607063268" href="#Records" class="ref">Records</a></li><li>2.1.2 <a id="a-607065648" href="#Documentation" class="ref">Documentation</a></li><li>2.1.3 <a id="a-607068348" href="#Facilities" class="ref">Facilities</a></li></ul></li><li>2.2 <a id="a-607086258" href="#intro.features" class="ref">Features</a><ul><li>2.2.1 <a id="a-607076588" href="#Portable" class="ref">Portable</a></li><li>2.2.2 <a id="a-607078988" href="#Agile" class="ref">Agile</a></li><li>2.2.3 <a id="a-607081388" href="#Powerful" class="ref">Powerful</a></li></ul></li><li>2.3 <a id="a-607098488" href="#intro.reqs" class="ref">Requirements</a><ul><li>2.3.1 <a id="a-607088898" href="#Verilog_simulator" class="ref">Verilog simulator</a></li><li>2.3.2 <a id="a-607091338" href="#Compilers" class="ref">Compilers</a></li><li>2.3.3 <a id="a-607093658" href="#Libraries" class="ref">Libraries</a></li></ul></li><li>2.4 <a id="a-607101288" href="#intro.appetizers" class="ref">Appetizers</a></li><li>2.5 <a id="a-607103848" href="#intro.applications" class="ref">Applications</a></li><li>2.6 <a id="a-607109258" href="#intro.related-works" class="ref">Related works</a><ul><li>2.6.1 <a id="a-607106308" href="#intro.related-works.pli" class="ref">Ye olde PLI</a></li></ul></li><li>2.7 <a id="a-607112128" href="#intro.license" class="ref">License</a></li></ul></li><li>3 <a id="a-607180888" href="#setup" class="ref">Setup</a><ul><li>3.1 <a id="a-607143418" href="#setup.manifest" class="ref">Manifest</a></li><li>3.2 <a id="a-607148858" href="#setup.reqs" class="ref">Requirements</a></li><li>3.3 <a id="a-607155028" href="#setup.recom" class="ref">Recommendations</a><ul><li>3.3.1 <a id="a-607151688" href="#setup.recom.merger" class="ref">Text merging tool</a></li></ul></li><li>3.4 <a id="a-607164168" href="#setup.inst" class="ref">Installation</a><ul><li>3.4.1 <a id="a-607160108" href="#setup.inst.windows" class="ref">Installing on Windows</a></li></ul></li><li>3.5 <a id="a-607166448" href="#setup.maintenance" class="ref">Maintenance</a></li></ul></li><li>4 <a id="a-607194908" href="#organization" class="ref">Organization</a><ul><li>4.1 <a id="a-607189198" href="#organization.tests" class="ref">Tests</a></li></ul></li><li>5 <a id="a-607339858" href="#usage" class="ref">Usage</a><ul><li>5.1 <a id="a-607201128" href="#overview.relay" class="ref">Interacting with the Verilog simulator</a></li><li>5.2 <a id="a-607084798" href="#vpi" class="ref">VPI in Ruby</a><ul><li>5.2.1 <a id="a-607039078" href="#vpi.handles" class="ref">Handles</a><ul><li>5.2.1.1 <a id="a-607206178" href="#Shortcuts_for_productivity" class="ref">Shortcuts for productivity</a></li><li>5.2.1.2 <a id="a-607208738" href="#Accessing_a_handle_s_relatives" class="ref">Accessing a handle’s relatives</a></li><li>5.2.1.3 <a id="a-607211678" href="#Accessing_a_handle_s_properties" class="ref">Accessing a handle’s properties</a></li></ul></li><li>5.2.2 <a id="a-607049268" href="#vpi.callbacks" class="ref">Callbacks</a></li></ul></li><li>5.3 <a id="a-607113668" href="#usage.concurrency" class="ref">Concurrency</a><ul><li>5.3.1 <a id="a-607100498" href="#Creating_a_concurrent_process" class="ref">Creating a concurrent process</a></li></ul></li><li>5.4 <a id="a-607122918" href="#usage.prototyping" class="ref">Prototyping</a><ul><li>5.4.1 <a id="a-607117988" href="#Creating_a_prototype" class="ref">Creating a prototype</a></li></ul></li><li>5.5 <a id="a-607128648" href="#usage.debugger" class="ref">Interactive debugging</a><ul><li>5.5.1 <a id="a-607125578" href="#usage.debugger.init" class="ref">Advanced initialization</a></li></ul></li><li>5.6 <a id="a-607150648" href="#usage.runner" class="ref">Test runner</a><ul><li>5.6.1 <a id="a-607138328" href="#usage.runner.env-vars" class="ref">Environment variables</a><ul><li>5.6.1.1 <a id="a-607131748" href="#Variables_as_command-line_arguments" class="ref">Variables as command-line arguments</a></li></ul></li></ul></li><li>5.7 <a id="a-607177328" href="#usage.tools" class="ref">Tools</a><ul><li>5.7.1 <a id="a-607165778" href="#usage.tools.generate" class="ref">Automated test generation</a></li><li>5.7.2 <a id="a-607169418" href="#usage.tools.convert" class="ref">Verilog to Ruby conversion</a></li></ul></li><li>5.8 <a id="a-607179568" href="#usage.examples" class="ref">Example tests</a></li><li>5.9 <a id="a-607105538" href="#usage.tutorial" class="ref">Tutorial</a><ul><li>5.9.1 <a id="a-607192538" href="#usage.tutorial.declare-design" class="ref">Start with a Verilog design</a></li><li>5.9.2 <a id="a-607217768" href="#usage.tutorial.generate-test" class="ref">Generate a test</a></li><li>5.9.3 <a id="a-607227868" href="#usage.tutorial.specification" class="ref">Specify your expectations</a></li><li>5.9.4 <a id="a-607233858" href="#usage.tutorial.implement-proto" class="ref">Implement the prototype</a></li><li>5.9.5 <a id="a-607247108" href="#usage.tutorial.test-proto" class="ref">Verify the prototype</a></li><li>5.9.6 <a id="a-607253098" href="#usage.tutorial.implement-design" class="ref">Implement the design</a></li><li>5.9.7 <a id="a-607037508" href="#usage.tutorial.test-design" class="ref">Verify the design</a></li></ul></li></ul></li><li>6 <a id="a-607355358" href="#hacking" class="ref">Hacking</a><ul><li>6.1 <a id="a-607342188" href="#hacking.scm" class="ref">Getting the latest source code</a></li><li>6.2 <a id="a-607344708" href="#Installing_without_really_installing" class="ref">Installing without really installing</a></li><li>6.3 <a id="a-607347318" href="#hacking.release-packages" class="ref">Building release packages</a></li><li>6.4 <a id="a-607349668" href="#hacking.manual" class="ref">Editing this manual</a></li></ul></li><li>7 <a id="a-607403828" href="#problems" class="ref">Known problems</a><ul><li>7.1 <a id="a-607383948" href="#problem.ivl" class="ref">Icarus Verilog</a><ul><li>7.1.1 <a id="a-607361328" href="#problems.ivl.vpi_handle_by_name.absolute-paths" class="ref">Give full paths to Verilog objects</a></li><li>7.1.2 <a id="a-607371018" href="#problems.ivl.vpi_handle_by_name.connect-registers" class="ref">Registers must be connected</a></li><li>7.1.3 <a id="a-607373268" href="#problems.ivl.vpi_reset" class="ref">VPI::reset</a></li></ul></li></ul></li><li>8 <a id="a-607436278" href="#glossary" class="ref">Glossary</a><ul><li>8.1 <a id="a-607406658" href="#glossary.test" class="ref">Test</a></li><li>8.2 <a id="a-607409158" href="#glossary.design" class="ref">Design</a></li><li>8.3 <a id="a-607411918" href="#glossary.specification" class="ref">Specification</a></li><li>8.4 <a id="a-607414138" href="#glossary.expectation" class="ref">Expectation</a></li><li>8.5 <a id="a-607416618" href="#glossary.handle" class="ref">Handle</a></li><li>8.6 <a id="a-607418878" href="#glossary.rake" class="ref">Rake</a></li><li>8.7 <a id="a-607421418" href="#glossary.RSpec" class="ref">RSpec</a></li><li>8.8 <a id="a-607423678" href="#glossary.TDD" class="ref">Test driven development</a></li><li>8.9 <a id="a-607425938" href="#glossary.BDD" class="ref">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-607145888">Add support for your Verilog simulator</a></li>
+ <li><a href="#Tuning_for_maximum_performance" id="a-607157578">Tuning for maximum performance</a></li>
+ <li><a href="#Using__kdiff3__with_the_automated_test_generator." id="a-607159448">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
+ <li><a href="#What_can_the_test_runner_do_" id="a-607241748">What can the test runner do?</a></li>
+ </ol>
+ <h1 id="toc:note">Notes</h1>
+ <ol>
+ <li><a href="#Constants_are_capitalized_in_Ruby" id="a-607203518">Constants are capitalized in Ruby</a></li>
+ </ol>
+ <h1 id="toc:caution">Cautions</h1>
+ <ol>
+ <li><a href="#Do_not_rename_generated_files" id="a-607154698">Do not rename generated files</a></li>
+ </ol>
+ <h1 id="toc:figure">Figures</h1>
+ <ol>
+ <li><a href="#fig:organization.detail" id="a-607183488">Where does Ruby-VPI fit in?</a></li>
+ <li><a href="#fig:organization" id="a-607186098">Organization of a test in Ruby-VPI</a></li>
+ <li><a href="#fig:ruby_relay" id="a-607197648">Interaction between Ruby and Verilog</a></li>
+ <li><a href="#fig:method_naming_format" id="a-607214478">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-607216908">Possible accessors and their implications</a></li>
+ <li><a href="#ex:properties" id="a-607004748">Examples of accessing a handle’s properties</a></li>
+ </ol>
+ <h1 id="toc:example">Examples</h1>
+ <ol>
+ <li><a href="#ex:callback" id="a-607043828">Using a callback for value change notification</a></li>
+ <li><a href="#An_edge-triggered__always__block" id="a-607088908">An edge-triggered “always” block</a></li>
+ <li><a href="#A_change-triggered__combinational___always__block" id="a-607094288">A change-triggered (combinational) “always” block</a></li>
+ <li><a href="#Running_a_test_with_environment_variables" id="a-607134148">Running a test with environment variables</a></li>
+ <li><a href="#fig:counter.v_decl" id="a-607186858">Declaration of a simple up-counter with synchronous reset</a></li>
+ <li><a href="#fig:generate-test.RSpec" id="a-607199068">Generating a test with specification in RSpec format</a></li>
+ <li><a href="#fig:generate-test.xUnit" id="a-607205488">Generating a test with specification in xUnit format</a></li>
+ <li><a href="#fig:RSpec_counter_spec.rb" id="a-607220678">Specification implemented in RSpec format</a></li>
+ <li><a href="#fig:xUnit_counter_spec.rb" id="a-607223038">Specification implemented in xUnit format</a></li>
+ <li><a href="#fig:counter_proto.rb" id="a-607230458">Ruby prototype of our Verilog design</a></li>
+ <li><a href="#fig:test-proto.RSpec" id="a-607236978">Running a test with specification in RSpec format</a></li>
+ <li><a href="#fig:test-proto.unit-test" id="a-607239478">Running a test with specification in xUnit format</a></li>
+ <li><a href="#fig:counter.v_impl" id="a-607249698">Implementation of a simple up-counter with synchronous reset</a></li>
+ <li><a href="#fig:test-design.RSpec" id="a-607000458">Running a test with specification in RSpec format</a></li>
+ <li><a href="#fig:test-design.unit-test" id="a-607031948">Running a test with specification in xUnit format</a></li>
+ <li><a href="#ex:TestFoo" id="a-607358168">Part of a bench which instantiates a Verilog design</a></li>
+ <li><a href="#ex:TestFoo_bad" id="a-607364228">Bad design with unconnected registers</a></li>
+ <li><a href="#ex:TestFoo_fix" id="a-607366668">Fixed design with wired registers</a></li>
+ </ol>
+ </div>
+ </div>
+
<div id="body">
+
<hr style="display: none"/>
- <div id="Ruby-VPI_18.0.2_user_manual" class="front_cover">
- <h1 class="title"><big>Ruby-VPI 18.0.2 user manual</big></h1>
+ <div id="Ruby-VPI_user_manual" class="front_cover">
+ <h1 class="title"><big>Ruby-VPI user manual</big></h1>
<h2 class="author">Suraj N. Kurapati</h2>
- <h3 class="date">03 August 2007</h3>
+ <h3 class="date">27 August 2007</h3>
+ <p style="text-align:center;"><a href="history.html#a19.0.0">Version 19.0.0</a></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>
@@ -42,17 +104,20 @@
<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>You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the <a href="http://ruby-vpi.rubyforge.org/forum/">project forums</a>. Furthermore, you can <a href="#hacking.manual">edit this manual</a> and contribute your improvements to the <a href="http://ruby-vpi.rubyforge.org/tracker/">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>
+ <p>Finally, this manual comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the <a href="http://mozilla.org">Mozilla</a> family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the “print preview” function of a graphical web browser to see how this manual will appear when printed.</p>
+
+
+ <p>You can give feedback about this manual and, in general, any aspect of the Ruby-VPI project on the <a href="http://ruby-vpi.rubyforge.org/forum/">project forums</a>. Furthermore, you can <a href="#hacking.manual" class="ref">edit this manual</a> yourself and contribute your improvements to the <a href="http://ruby-vpi.rubyforge.org/tracker/">project patches</a> tracker. 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>
+ <p>This manual is distributed under <a href="#intro.license" class="ref">the same license as Ruby-VPI</a>.</p>
<p>The admonition graphics used in this manual are Copyright 2005, 2006 <a href="http://tango.freedesktop.org/Tango_Desktop_Project">Tango Desktop Project</a> and are distributed under <a href="./images/tango/LICENSE">these terms</a>.</p>
</div>
</p>
@@ -62,11 +127,11 @@
<hr style="display: none"/>
<div id="intro" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607321098">2</a>
+ Chapter <a href="#a-607140228" class="ref">2</a>
<br/><br/>
<big>Welcome</big>
</h1>
@@ -88,23 +153,23 @@
<p>
<hr style="display: none"/>
<div id="resources" class="section">
<h2 class="title">
- <a href="#a-607255258">2.1</a>
+ <a href="#a-607073948" class="ref">2.1</a>
Resources
</h2>
<div id="Records" class="paragraph">
<p class="title">Records</p>
<ul>
- <li><a href="history.html#a18.0.2">What’s new</a>
- – release notes for version 18.0.2.
+ <li><a href="history.html#a19.0.0">What’s new</a>
+ – release notes for version 19.0.0.
<ul>
<li><a href="history.html">History</a>
– a record of all release notes.</li>
<li><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 announcements" style="float: right"/></a> <a href="http://ruby-vpi.rubyforge.org/doc/rss.xml">RSS feed</a>
– keep track of new releases at your leisure.</li>
@@ -168,11 +233,11 @@
<p>
<hr style="display: none"/>
<div id="intro.features" class="section">
<h2 class="title">
- <a href="#a-607267568">2.2</a>
+ <a href="#a-607086258" class="ref">2.2</a>
Features
</h2>
@@ -180,11 +245,11 @@
<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>Works with all <a href="#intro.reqs" class="ref">major Verilog simulators</a> available today.</li>
<li>Compiled <em>just once</em> during <a href="manual.html#setup.inst">installation</a> and used forever!</li>
</ul>
</div>
@@ -239,11 +304,11 @@
<p>
<hr style="display: none"/>
<div id="intro.reqs" class="section">
<h2 class="title">
- <a href="#a-607279798">2.3</a>
+ <a href="#a-607098488" class="ref">2.3</a>
Requirements
</h2>
@@ -269,11 +334,11 @@
</ul>
<ul>
<li><a href="http://www.cadence.com/products/functional_ver/nc-verilog/">Cadence NC-Sim</a>
- – any version that supports the <tt>+loadvpi</tt> option should be acceptable. However, version 05.83-s003 is <em>mostly</em> acceptable because you <strong>will not</strong> be able to <a href="manual.html#problem.ncsim.vpiForceFlag">force values onto wires</a>.</li>
+ – any version that supports the <tt>+loadvpi</tt> option should be acceptable.</li>
</ul>
<ul>
<li><a href="http://www.pragmatic-c.com/gpl-cver/">GPL Cver</a>
@@ -335,13 +400,84 @@
<p>
<hr style="display: none"/>
+ <div id="intro.appetizers" class="section">
+ <h2 class="title">
+ <a href="#a-607101288" class="ref">2.4</a>
+
+
+
+ Appetizers
+ </h2>
+
+ Here is a tiny sampling of code to whet your appetite. See <a href="manual.html#usage.tutorial">the tutorial</a> for more samples.
+
+
+ <ul>
+ <li>Assign the value 2<sup>2048</sup> to a register:
+ <ul>
+ <li><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></li>
+ <li><code class="code">your_register.put_value <span style="color:#00D; font-weight:bold">2</span> ** <span style="color:#00D; font-weight:bold">2048</span></code></li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>Check if all nets in a module are at high impedance:
+ <ul>
+ <li><code class="code">your_module.all_net? { |your_net| your_net.z? }</code></li>
+ <li><pre class="code">
+your_nets = your_module.net_a
+your_nets.all? { |net| net.z? }</pre></li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>See a register’s path, width, and location (file & line number):
+ <ul>
+ <li><code class="code">puts your_register</code></li>
+ <li><pre class="code">
+p <span style="color:#A60">:path</span> => your_register.fullName
+p <span style="color:#A60">:width</span> => your_register.size
+p <span style="color:#A60">:file</span> => your_register.fileName
+p <span style="color:#A60">:file</span> => your_register.lineNo</pre></li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>Access the first five elements in a memory:
+ <ul>
+ <li><code class="code">your_memory.memoryWord_a.first(<span style="color:#00D; font-weight:bold">5</span>)</code></li>
+ <li><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></li>
+ <li><code class="code">your_memory.memoryWord_a[<span style="color:#00D; font-weight:bold">0</span>, <span style="color:#00D; font-weight:bold">5</span>]</code></li>
+ </ul></li>
+ </ul>
+
+
+ <ul>
+ <li>Clear a memory by filling it with zeroes:
+ <ul>
+ <li><code class="code">your_memory.each_memoryWord { |w| w.zero! }</code></li>
+ <li><code class="code">your_memory.each_memoryWord { |w| w.intVal = <span style="color:#00D; font-weight:bold">0</span> }</code></li>
+ <li><code class="code">your_memory.each_memoryWord { |w| w.put_value <span style="color:#00D; font-weight:bold">0</span> }</code></li>
+ </ul></li>
+ </ul>
+
+ </div>
+ </p>
+
+
+ <p>
+ <hr style="display: none"/>
+
<div id="intro.applications" class="section">
<h2 class="title">
- <a href="#a-607282358">2.4</a>
+ <a href="#a-607103848" class="ref">2.5</a>
Applications
</h2>
@@ -381,81 +517,62 @@
<p>
<hr style="display: none"/>
- <div id="intro.appetizers" class="section">
+ <div id="intro.related-works" class="section">
<h2 class="title">
- <a href="#a-607284958">2.5</a>
+ <a href="#a-607109258" class="ref">2.6</a>
- Appetizers
+ Related works
</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>
+ <li><a href="http://anvil.sourceforge.net">ANVIL</a> is a C++ interface to VPI.</li>
+ <li><a href="http://teal.sourceforge.net">Teal</a> is a C++ interface to VPI.</li>
+ <li><a href="http://jove.sourceforge.net">JOVE</a> is a Java 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>
- <blockquote>
- <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>
+ <p>
+ <hr style="display: none"/>
+ <div id="intro.related-works.pli" class="section">
+ <h3 class="title">
+ <a href="#a-607106308" class="ref">2.6.1</a>
- <ul>
- <li>Check if all nets in a module are at high impedance:</li>
- </ul>
+
+ Ye olde PLI
+ </h3>
- <blockquote>
- <p><code class="code">your_module.all_net? { |net| net.z? }</code></p>
- </blockquote>
+ 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.
<ul>
- <li>See a register’s path, width, and location (file & line number):</li>
+ <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>
- <blockquote>
- <p><code class="code">puts your_register</code></p>
- </blockquote>
-
-
- <ul>
- <li>Access the first five elements in a memory:</li>
- </ul>
-
-
- <blockquote>
- <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>
-
-
- <ul>
- <li>Clear a memory by filling it with zeroes:</li>
- </ul>
-
-
- <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>
<hr style="display: none"/>
<div id="intro.license" class="section">
<h2 class="title">
- <a href="#a-607287828">2.6</a>
+ <a href="#a-607112128" class="ref">2.7</a>
License
</h2>
@@ -490,66 +607,18 @@
<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>
</div>
</p>
-
-
- <p>
- <hr style="display: none"/>
-
- <div id="intro.related-works" class="section">
- <h2 class="title">
- <a href="#a-607293218">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>
-
-
- <p>
- <hr style="display: none"/>
-
- <div id="intro.related-works.pli" class="section">
- <h3 class="title">
- <a href="#a-607290278">2.7.1</a>
-
-
-
- Ye olde PLI
- </h3>
-
- 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.
-
-
- <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>
- </p>
- </div>
<hr style="display: none"/>
<div id="setup" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607361758">3</a>
+ Chapter <a href="#a-607180888" class="ref">3</a>
<br/><br/>
<big>Setup</big>
</h1>
@@ -557,11 +626,11 @@
<hr style="display: none"/>
<div id="setup.manifest" class="section">
<h2 class="title">
- <a href="#a-607324288">3.1</a>
+ <a href="#a-607143418" class="ref">3.1</a>
Manifest
</h2>
@@ -570,41 +639,41 @@
<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>ext</tt> contains source code, written in the C language, for the <a href="#organization" class="ref">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>
+ <li><tt>bin</tt> contains various tools. See <a href="#usage.tools" class="ref">Section 5.7</a> for more information.</li>
+ <li><tt>examples</tt> contains example tests. See <a href="#usage.examples" class="ref">Section 5.8</a> for more information.</li>
</ul>
</div>
<hr style="display: none"/>
<div id="setup.reqs" class="section">
<h2 class="title">
- <a href="#a-607329728">3.2</a>
+ <a href="#a-607148858" class="ref">3.2</a>
Requirements
</h2>
- <p>See <a href="#intro.reqs">Section 2.3</a> above.</p>
+ <p>See <a href="#intro.reqs" class="ref">Section 2.3</a> above.</p>
<p>
<hr style="display: none"/>
<div class="admonition">
<div class="tip" id="Add_support_for_your_Verilog_simulator">
<img src="images/tango/tip.png" alt="tip" class="icon"/>
- <p class="title"><a href="#a-607326758">Tip 1</a>. Add support for your Verilog simulator</p>
+ <p class="title"><a href="#a-607145888" class="ref">Tip 1</a>. Add support for your Verilog simulator</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>
@@ -614,11 +683,11 @@
<hr style="display: none"/>
<div id="setup.recom" class="section">
<h2 class="title">
- <a href="#a-607335898">3.3</a>
+ <a href="#a-607155028" class="ref">3.3</a>
Recommendations
</h2>
@@ -629,18 +698,18 @@
<p>
<hr style="display: none"/>
<div id="setup.recom.merger" class="section">
<h3 class="title">
- <a href="#a-607332558">3.3.1</a>
+ <a href="#a-607151688" class="ref">3.3.1</a>
Text merging tool
</h3>
- An <em>interactive</em> text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the <a href="#usage.tools.generate">automated test generator</a>. A handful of the currently available open-source text merging tools are listed below.
+ 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" class="ref">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 KDE.</li>
</ul>
@@ -673,18 +742,18 @@
<hr style="display: none"/>
<div id="setup.inst" class="section">
<h2 class="title">
- <a href="#a-607345038">3.4</a>
+ <a href="#a-607164168" class="ref">3.4</a>
Installation
</h2>
- <p>Once you have satisfied the <a href="#setup.reqs">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
+ <p>Once you have satisfied the <a href="#setup.reqs" class="ref">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
<pre>
$ gem env gemdir
/usr/lib/ruby/gems/1.8
@@ -699,22 +768,22 @@
<div class="admonition">
<div class="tip" id="Tuning_for_maximum_performance">
<img src="images/tango/tip.png" alt="tip" class="icon"/>
- <p class="title"><a href="#a-607338448">Tip 2</a>. Tuning for maximum performance</p>
+ <p class="title"><a href="#a-607157578" class="ref">Tip 2</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>
<hr style="display: none"/>
<div id="setup.inst.windows" class="section">
<h3 class="title">
- <a href="#a-607340978">3.4.1</a>
+ <a href="#a-607160108" class="ref">3.4.1</a>
Installing on Windows
</h3>
@@ -761,11 +830,11 @@
<hr style="display: none"/>
<div id="setup.maintenance" class="section">
<h2 class="title">
- <a href="#a-607347318">3.5</a>
+ <a href="#a-607166448" class="ref">3.5</a>
Maintenance
</h2>
@@ -785,18 +854,18 @@
<hr style="display: none"/>
<div id="organization" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607368998">4</a>
+ Chapter <a href="#a-607194908" class="ref">4</a>
<br/><br/>
<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>
+ <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" class="ref">TDD</a> and <a href="#glossary.BDD" class="ref">BDD</a> to the realm of hardware development with Verilog.</p>
<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>
@@ -805,91 +874,42 @@
<div class="formal">
<div class="figure" id="fig:organization.detail">
- <p class="title"><a href="#a-607364358">Figure 1</a>. Where does Ruby-VPI fit in?</p>
+ <p class="title"><a href="#a-607183488" class="ref">Figure 1</a>. Where does Ruby-VPI fit in?</p>
<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>
+As <a href="#fig:organization.detail" class="ref">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>
<p>
<hr style="display: none"/>
- <div id="overview.relay" class="section">
- <h2 class="title">
- <a href="#a-607370648">4.1</a>
-
-
-
- Ruby/Verilog interaction
- </h2>
-
- <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>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>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>
- <hr style="display: none"/>
-
- <div class="formal">
- <div class="figure" id="fig:ruby_relay">
-
-
- <p class="title"><a href="#a-607367168">Figure 2</a>. Interaction between Ruby and Verilog</p>
-
- <img src="figures/ruby_relay.png" alt="" />
-
-
- <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>
-
- </div>
-
-
- <hr style="display: none"/>
-
<div id="organization.tests" class="section">
<h2 class="title">
- <a href="#a-607376218">4.2</a>
+ <a href="#a-607189198" class="ref">4.1</a>
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>
+ <p>In Ruby-VPI, the process of functional verification is neatly packaged into self-contained, executable tests. As <a href="#fig:organization" class="ref">Figure 2</a> illustrates, a test is composed of a <strong>bench</strong>, a <strong>design</strong>, and a <strong>specification</strong>.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="figure" id="fig:organization">
- <p class="title"><a href="#a-607373118">Figure 3</a>. Organization of a test in Ruby-VPI</p>
+ <p class="title"><a href="#a-607186098" class="ref">Figure 2</a>. Organization of a test in Ruby-VPI</p>
<img src="figures/organization.png" alt="" />
</div>
</div>
@@ -901,116 +921,123 @@
<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>
+ </div>
+
+ <hr style="display: none"/>
- <p>
+ <div id="usage" class="chapter">
+ <h1 class="title">
+ Chapter <a href="#a-607339858" class="ref">5</a>
+
+ <br/><br/>
+
+ <big>Usage</big>
+ </h1>
+
+
<hr style="display: none"/>
- <div id="VPI_in_Ruby" class="section">
+ <div id="overview.relay" class="section">
<h2 class="title">
- <a href="#a-607291858">4.3</a>
+ <a href="#a-607201128" class="ref">5.1</a>
- VPI in Ruby
+ Interacting with the Verilog simulator
</h2>
-
-<hr style="display: none"/>
+ <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>
-<div id="Deviations_from_the_VPI_standard" class="section">
- <h3 class="title">
- <a href="#a-607385138">4.3.1</a>
-
+ <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 after a given number of time steps. This process is illustrated in <a href="#fig:ruby_relay" class="ref">Figure 3</a>. You can also use the <code class="code">wait</code> method, which is just an alias to the <code class="code">advance_time</code> method, if you prefer.</p>
- Deviations from the VPI standard
- </h3>
- <p>Ruby-VPI makes the entire IEEE Std 1364-2005 VPI interface available to Ruby, but with the following minor differences.</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>
-<hr style="display: none"/>
+ <hr style="display: none"/>
-<div id="Names_are_capitalized" class="section">
- <h4 class="title">
- <a href="#a-607378708">4.3.1.1</a>
+ <div class="formal">
+ <div class="figure" id="fig:ruby_relay">
+
-
+ <p class="title"><a href="#a-607197648" class="ref">Figure 3</a>. Interaction between Ruby and Verilog</p>
- Names are capitalized
- </h4>
+ <img src="figures/ruby_relay.png" alt="" />
- <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>
+ <ol>
+ <li>The current simulation time is <em>X</em>.</li>
+ <li>The specification invokes the <code class="code">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" class="ref">VPI callback</a>.</p>
- <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby. However, the <code class="code">vpi_handle</code> function remains as <code class="code">vpi_handle</code> in Ruby.</p>
+ </div>
+
-</div>
- </p>
+ <hr style="display: none"/>
+ <div id="vpi" class="section">
+ <h2 class="title">
+ <a href="#a-607084798" class="ref">5.2</a>
- <p>
-<hr style="display: none"/>
+
-<div id="a_vprintf__is__printf_" class="section">
- <h4 class="title">
- <a href="#a-607381208">4.3.1.2</a>
+ VPI in Ruby
+ </h2>
-
+ <p>Ruby-VPI provides the <em>entire</em> IEEE Std 1364-2005 VPI interface to Ruby. This section will show you how to make use of it.</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:
+ <p>
+ <hr style="display: none"/>
+ <div class="admonition">
+ <div class="note" id="Constants_are_capitalized_in_Ruby">
+ <img src="images/tango/note.png" alt="note" class="icon"/>
- <ul>
- <li>Ruby represents <a href="http://phrogz.net/ProgrammingRuby/tut_methods.html#variablelengthargumentlists">variable argument lists as arrays</a> instead of defining a special datatype, such as <code class="code">va_list</code>, for them.</li>
- </ul>
+ <p class="title"><a href="#a-607203518" class="ref">Note 1</a>. Constants are capitalized in Ruby</p>
+ <p>In the remainder of this manual, you may be surprised to see that VPI constants such as <code class="code">vpiIntVal</code> are written with a captialized name, as <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code>. The reason for this discrepancy is that in Ruby, the names of constants are capitalized.</p>
- <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>
+ <p>However, keep in mind that Ruby-VPI provides all VPI constants in both (1) their original, uncapitalized form and (2) their capitalized Ruby form. You may use either version according to your preference; they are functionally equivalent.</p>
+ </div>
+ </div>
+
- <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>
-
-</div>
- </p>
-
-</div>
-
-
<hr style="display: none"/>
<div id="vpi.handles" class="section">
<h3 class="title">
- <a href="#a-607236168">4.3.2</a>
+ <a href="#a-607039078" class="ref">5.2.1</a>
Handles
</h3>
- <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>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>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 have various <strong>properties</strong>, listed in the second column of <a href="#tbl:accessors" class="ref">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" class="ref">Table 1</a>.</p>
- <p>Handles are typically obtained through the <code class="code">vpi_handle_by_name</code> and <code class="code">vpi_handle</code> functions. These functions are hierarchical in nature, 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>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: <pre class="code">your_reg = vpi_handle( <span style="color:#036; font-weight:bold">VpiReg</span>, your_handle )</pre></p>
<p>
<div id="Shortcuts_for_productivity" class="paragraph">
<p class="title">Shortcuts for productivity</p>
@@ -1022,11 +1049,11 @@
<p>
<hr style="display: none"/>
<div id="Accessing_a_handle_s_relatives" class="section">
<h4 class="title">
- <a href="#a-607390358">4.3.2.2</a>
+ <a href="#a-607208738" class="ref">5.2.1.2</a>
Accessing a handle’s relatives
</h4>
@@ -1035,35 +1062,34 @@
<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>
+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>or by writing:</p>
- <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>
+ <pre 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> )</pre>
<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>
- <code class="code">foo.bar.baz</code>
+ <pre class="code">foo.bar.baz</pre>
</div>
</p>
<p>
<hr style="display: none"/>
<div id="Accessing_a_handle_s_properties" class="section">
<h4 class="title">
- <a href="#a-607393298">4.3.2.3</a>
+ <a href="#a-607211678" class="ref">5.2.1.3</a>
Accessing a handle’s properties
</h4>
@@ -1073,40 +1099,38 @@
<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>
+result = wrapper.value.integer</pre>
<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>
<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>
+result = wrapper.value.str.to_i( <span style="color:#00D; font-weight:bold">16</span> )</pre>
- <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>
+ <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" class="ref">Figure 4</a>, as methods on the handle:</p>
- <code class="code">result = foo.bar.intVal</code>
+ <pre class="code">result = foo.bar.intVal</pre>
</div>
<hr style="display: none"/>
<div class="formal">
<div class="figure" id="fig:method_naming_format">
- <p class="title"><a href="#a-607396098">Figure 4</a>. Method naming format for accessing a handle’s properties</p>
+ <p class="title"><a href="#a-607214478" class="ref">Figure 4</a>. Method naming format for accessing a handle’s properties</p>
<table>
<tr>
<th>Operation </th>
<th>_ </th>
@@ -1136,11 +1160,11 @@
<ul>
<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.
- <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>
+ <p><a href="#tbl:accessors" class="ref">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>When <strong>Addendum</strong> is an equal sign (=), it suggests that the specified VPI property should be written to.
@@ -1155,11 +1179,11 @@
<div class="formal">
<div class="table" id="tbl:accessors">
- <p class="title"><a href="#a-607398528">Table 1</a>. Possible accessors and their implications</p>
+ <p class="title"><a href="#a-607216908" class="ref">Table 1</a>. Possible accessors and their implications</p>
<table>
<tr>
<th>Accessor </th>
<th>Kind of value accessed </th>
@@ -1209,11 +1233,11 @@
<div class="formal">
<div class="table" id="ex:properties">
- <p class="title"><a href="#a-607223948">Table 2</a>. Examples of accessing a handle’s properties</p>
+ <p class="title"><a href="#a-607004748" class="ref">Table 2</a>. Examples of accessing a handle’s properties</p>
<table>
<tr>
<th rowspan="2">Ruby expression </th>
<th colspan="6">Method naming format </th>
@@ -1534,11 +1558,11 @@
<hr style="display: none"/>
<div id="vpi.callbacks" class="section">
<h3 class="title">
- <a href="#a-607249768">4.3.3</a>
+ <a href="#a-607049268" class="ref">5.2.2</a>
Callbacks
</h3>
@@ -1554,157 +1578,231 @@
<div class="formal">
<div class="example" id="ex:callback">
- <p class="title"><a href="#a-607242918">Example 1</a>. Using a callback for value change notification</p>
+ <p class="title"><a href="#a-607043828" class="ref">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</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">Example 3</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" class="ref">Example 5</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>
+time = <span style="color:#036; font-weight:bold">S_vpi_time</span>.new
+time.type = <span style="color:#036; font-weight:bold">VpiSimTime</span>
+time.low = <span style="color:#00D; font-weight:bold">0</span>
+time.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>
+value = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+value.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>
+alarm = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
+alarm.reason = <span style="color:#036; font-weight:bold">CbValueChange</span>
+alarm.obj = <span style="color:#036; font-weight:bold">Counter</span>.count
+alarm.time = time
+alarm.value = value
+alarm.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
+vpi_register_cb( alarm ) <span style="color:#080; font-weight:bold">do</span> |info|
+ time = info.time.integer
+ count = info.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>
+<span style="color:#080; font-weight:bold">end</span></pre>
- <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>
+ <p>Append this code to the <tt>RSpec/counter_spec.rb</tt> file (provided in <a href="#usage.examples" class="ref">Section 5.8</a> and discussed in <a href="#usage.tutorial.specification" class="ref">Section 5.9.3</a>) and run the <a href="#usage.tutorial" class="ref">counter_RSpec test</a></p>
</div>
</div>
</p>
</div>
+</p>
-
</div>
- </p>
- </div>
-
+
- <hr style="display: none"/>
-
- <div id="usage" class="chapter">
- <h1 class="title">
- Chapter <a href="#a-607488938">5</a>
-
- <br/><br/>
-
- <big>Usage</big>
- </h1>
-
-
<hr style="display: none"/>
- <div id="usage.prototyping" class="section">
+ <div id="usage.concurrency" class="section">
<h2 class="title">
- <a href="#a-607395418">5.1</a>
+ <a href="#a-607113668" class="ref">5.3</a>
- Prototyping
+ Concurrency
</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 provides a concurrency model that allows you to run blocks of code in parallel. These blocks of code are known as <em>concurrent processes</em> and they represent the same idea as “initial”, “always”, and “forever” blocks do in Verilog.</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>
+ <p>Ruby-VPI’s concurrency model imposes two important constraints, which are inspired by <a href="http://en.wikipedia.org/wiki/GPGPU">GPGPU and fragment/vertex shader programming</a>, in order to avoid race conditions and to make parallel programming simpler.</p>
- <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>First, <strong>all processes execute in the same time step</strong>. That is, we only advance the <em>entire</em> simulation to the next time step when <em>all</em> processes are finished with the current time step. In this manner, we avoid race conditions where a process advances the entire simulation to a future time step but the other processes still think they are executing in the original time step (because they were not notified of the advancement).</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>Second, <strong>all processes see the same input</strong> (the state of the simulation database at the start of the current time step) while executing in a time step. That is, when a process modifies the simulation database, say, by changing the logic value of a register, the modification only takes effect at the <em>end</em> of the current time step. In this manner, we avoid race conditions where one process modifies the simulation midflight but some/all of other processes are unaware of that modification (because they were not notified of its occurence).</p>
+ <p>Note that these constraints are automatically enforced “under the hood”, so to speak, by Ruby-VPI. As a user, you need not do anything extra to implement or support these constraints; they are already taken care of.</p>
+
+
<p>
- <div id="Getting_started" class="paragraph">
- <p class="title">Getting started</p>
- To create a prototype,
- <ol>
- <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>
+ <div id="Creating_a_concurrent_process" class="paragraph">
+ <p class="title">Creating a concurrent process</p>
+ <p>You can create a concurrent proceess by passing a block of code to the <code class="code">process</code> method.</p>
- <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>You can also create concurrent processes that loop forever using the <code class="code">always</code> and <code class="code">forever</code> methods, which mimic the “always” and “forever” blocks, respectively, of the Verilog language. However, due to the constraints of the concurrency model (see above), there is one limitation: all assignments are treated like Verilog’s non-blocking assignments.</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>
+ <p>
+ <hr style="display: none"/>
+
+ <div class="formal">
+ <div class="example" id="An_edge-triggered__always__block">
+
+
+ <p class="title"><a href="#a-607088908" class="ref">Example 2</a>. An edge-triggered “always” block</p>
+
+ <p>Suppose you have the following Verilog code:</p>
+
+
+ <pre class="code" lang="verilog">
+always @(posedge clock1 and negedge clock2) begin
+ foo <= foo + 1;
+ bar = bar + 5;
+end</pre>
+
+
+ <p>In Ruby-VPI, this code would be written as:</p>
+
+
+ <pre class="code">
+always <span style="color:#080; font-weight:bold">do</span>
+ wait <span style="color:#080; font-weight:bold">until</span> clock.posedge? <span style="color:#080; font-weight:bold">and</span> clock2.negedge?
+
+ foo.intVal += <span style="color:#00D; font-weight:bold">1</span>
+ bar.intVal += <span style="color:#00D; font-weight:bold">5</span> <span style="color:#888"># this is a NON-blocking assignment!</span>
+<span style="color:#080; font-weight:bold">end</span></pre>
+ </div>
+ </div>
+
+
+ <hr style="display: none"/>
+
+ <div class="formal">
+ <div class="example" id="A_change-triggered__combinational___always__block">
+
+
+ <p class="title"><a href="#a-607094288" class="ref">Example 3</a>. A change-triggered (combinational) “always” block</p>
+
+ <p>Suppose you have the following Verilog code:</p>
+
+
+ <pre class="code" lang="verilog">
+always @(apple, banana, cherry, date) begin
+ $display("Yum! Fruits are good for health!");
+end</pre>
+
+
+ <p>In Ruby-VPI, this code would be written as:</p>
+
+
+ <pre class="code">
+always <span style="color:#080; font-weight:bold">do</span>
+ wait <span style="color:#080; font-weight:bold">until</span> apple.change? <span style="color:#080; font-weight:bold">or</span> banana.change? <span style="color:#080; font-weight:bold">and</span> cherry.change? <span style="color:#080; font-weight:bold">or</span> date.change?
+ puts <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">Yum! Fruits are good for health!</span><span style="color:#710">"</span></span>
+<span style="color:#080; font-weight:bold">end</span></pre>
+
+
+ <p>Or, if you are lazy like I am, you can express the sensitivity list programatically:</p>
+
+
+ <pre class="code">
+always <span style="color:#080; font-weight:bold">do</span>
+ wait <span style="color:#080; font-weight:bold">until</span> [apple, banana, cherry, date].any? {|x| x.change?}
+ puts <span style="background-color:#fff0f0"><span style="color:#710">"</span><span style="color:#D20">Yum! Fruits are good for health!</span><span style="color:#710">"</span></span>
+<span style="color:#080; font-weight:bold">end</span></pre>
+ </div>
+ </div>
+ </p>
</div>
+</p>
+ </div>
+
- <hr style="display: none"/>
+ <hr style="display: none"/>
- <div id="How_does_prototyping_work_" class="section">
- <h3 class="title">
- <a href="#a-607383008">5.1.2</a>
+ <div id="usage.prototyping" class="section">
+ <h2 class="title">
+ <a href="#a-607122918" class="ref">5.4</a>
-
+
- How does prototyping work?
- </h3>
+ Prototyping
+ </h2>
- <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>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>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>
+ <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. 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" class="ref">Example 13</a> with its Ruby prototype shown in figure <a href="#fig:counter_proto.rb" class="ref">Example 10</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="Creating_a_prototype" class="paragraph">
+ <p class="title">Creating a prototype</p>
+ <ol>
+ <li>Start with a <a href="#usage.tutorial.declare-design" class="ref">Verilog module declaration</a> for your design.</li>
+ <li><a href="#usage.tutorial.generate-test" class="ref">Generate a test</a> using that module declaration.</li>
+ <li><a href="#usage.tutorial.implement-proto" class="ref">Implement the prototype</a> in the generated <tt>proto.rb</tt> file.</li>
+ <li><a href="#usage.tutorial.test-proto" class="ref">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" class="ref">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 (see <a href="#usage.runner" class="ref">Section 5.6</a> for details).</p>
</div>
</p>
</div>
<hr style="display: none"/>
<div id="usage.debugger" class="section">
<h2 class="title">
- <a href="#a-607403488">5.2</a>
+ <a href="#a-607128648" class="ref">5.5</a>
- Debugging
+ Interactive 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">DEBUGGER</span></code> environment variable (see <a href="#usage.test-runner">Section 5.3</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.runner" class="ref">Section 5.6</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>
<p>
<hr style="display: none"/>
<div id="usage.debugger.init" class="section">
<h3 class="title">
- <a href="#a-607400418">5.2.1</a>
+ <a href="#a-607125578" class="ref">5.5.1</a>
Advanced initialization
</h3>
@@ -1723,24 +1821,24 @@
</div>
<hr style="display: none"/>
- <div id="usage.test-runner" class="section">
+ <div id="usage.runner" class="section">
<h2 class="title">
- <a href="#a-607420258">5.3</a>
+ <a href="#a-607150648" class="ref">5.6</a>
Test runner
</h2>
- <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>A test runner is a file, generated by the <a href="#usage.tools.generate" class="ref">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>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
+<pre>% rake -f your_test_runner.rake
(in /home/sun/src/ruby-vpi/doc)
rake clean # Remove any temporary products.
rake clobber # Remove any generated file.
rake cver # Simulate with GPL Cver.
@@ -1753,46 +1851,47 @@
<p>
<hr style="display: none"/>
- <div id="usage.test-runner.env-vars" class="section">
+ <div id="usage.runner.env-vars" class="section">
<h3 class="title">
- <a href="#a-607413148">5.3.1</a>
+ <a href="#a-607138328" class="ref">5.6.1</a>
Environment variables
</h3>
<p>Test runners support the following <em>environment</em> variables, which allow you to easily change the behavior of the test runner.</p>
<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>
+ <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>
+ <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">PROFILER</span></code> enables the <a href="http://ruby-prof.rubyforge.org">ruby-prof</a> Ruby code profiler, which collects statistics on the runtime usage of the source code. This data allows you to identify performance bottlenecks.</li>
+ <li><code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span></code> enables the <a href="#usage.debugger" class="ref">interactive debugger</a> in its <a href="http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging">post-mortem debugging mode</a>.</li>
</ul>
- <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>To activate these variables, simply assign the number 1 to them. For example, <code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span>=<span style="color:#00D; font-weight:bold">1</span></code> activates the <code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span></code> variable.</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>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">DEBUGGER</span>=<span style="color:#00D; font-weight:bold">0</span></code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span>=</code> dectivate the <code class="code"><span style="color:#036; font-weight:bold">DEBUGGER</span></code> variable.</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
+ You can specify variable assignments as arguments to the <strong>rake</strong> command. For example, <pre>rake DEBUGGER=1</pre> is equivalent to
<pre>
-DEBUG=1
-export DEBUG
+DEBUGGER=1
+export DEBUGGER
rake
</pre> in Bourne shell or
<pre>
-setenv DEBUG 1
+setenv DEBUGGER 1
rake
</pre> in C shell.
</div>
</p>
@@ -1802,11 +1901,11 @@
<div class="formal">
<div class="example" id="Running_a_test_with_environment_variables">
- <p class="title"><a href="#a-607408978">Example 2</a>. Running a test with environment variables</p>
+ <p class="title"><a href="#a-607134148" class="ref">Example 4</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>
@@ -1826,11 +1925,11 @@
<hr style="display: none"/>
<div id="usage.tools" class="section">
<h2 class="title">
- <a href="#a-607439408">5.4</a>
+ <a href="#a-607177328" class="ref">5.7</a>
Tools
</h2>
@@ -1849,24 +1948,24 @@
Tools:
convert Converts Verilog source code into Ruby.
generate Generates Ruby-VPI tests from Verilog 2001 and Verilog 95 module declarations.
Simulators:
- cver GPL Cver
ivl Icarus Verilog
vcs Synopsys VCS
vsim Mentor Modelsim
ncsim Cadence NC-Sim
+ cver GPL Cver
</pre>
<p>
<hr style="display: none"/>
<div id="usage.tools.generate" class="section">
<h3 class="title">
- <a href="#a-607429588">5.4.1</a>
+ <a href="#a-607165778" class="ref">5.7.1</a>
Automated test generation
</h3>
@@ -1882,21 +1981,21 @@
<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>
- <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>As <a href="#fig:generate-test.RSpec" class="ref">Example 6</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>
<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"/>
- <p class="title"><a href="#a-607423018">Caution 1</a>. Do not rename generated files</p>
+ <p class="title"><a href="#a-607154698" class="ref">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>
@@ -1911,18 +2010,17 @@
<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-607425508">Tip 3</a>. Using <strong>kdiff3</strong> with the automated test generator.</p>
+ <p class="title"><a href="#a-607159448" class="ref">Tip 3</a>. Using <strong>kdiff3</strong> with the automated test generator.</p>
<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>
-</pre></li>
+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>
@@ -1937,11 +2035,11 @@
<hr style="display: none"/>
<div id="usage.tools.convert" class="section">
<h3 class="title">
- <a href="#a-607431878">5.4.2</a>
+ <a href="#a-607169418" class="ref">5.7.2</a>
Verilog to Ruby conversion
</h3>
@@ -1959,57 +2057,57 @@
<hr style="display: none"/>
<div id="usage.examples" class="section">
<h2 class="title">
- <a href="#a-607441648">5.5</a>
+ <a href="#a-607179568" class="ref">5.8</a>
- Sample tests
+ Example tests
</h2>
- The <tt>samp</tt> directory (<a href="http://ruby-vpi.rubyforge.org/code//samp/">browse it online</a>) 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.
+ The <tt>examples</tt> directory (<a href="http://ruby-vpi.rubyforge.org/code//examples/">browse it online</a>) contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
</div>
<hr style="display: none"/>
<div id="usage.tutorial" class="section">
<h2 class="title">
- <a href="#a-607314468">5.6</a>
+ <a href="#a-607105538" class="ref">5.9</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">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>
+ <li><a href="#usage.tutorial.declare-design" class="ref">Declare a design</a> using Verilog 2001 syntax.</li>
+ <li><a href="#usage.tutorial.generate-test" class="ref">Generate a test</a> for the design using the <a href="#usage.tools.generate" class="ref">automated test generator</a> tool.</li>
+ <li><a href="#usage.tutorial.specification" class="ref">Identify your expectations</a> for the design and implement them in the specification.</li>
+ <li>(Optional) <a href="#usage.tutorial.implement-proto" class="ref">Implement the prototype</a> of the design in Ruby.</li>
+ <li>(Optional) <a href="#usage.tutorial.test-proto" class="ref">Verify the prototype</a> against the specification.</li>
+ <li><a href="#usage.tutorial.implement-design" class="ref">Implement the design</a> in Verilog once the prototype has been verified.</li>
+ <li><a href="#usage.tutorial.test-design" class="ref">Verify the design</a> against the specification.</li>
</ol>
<p>
<hr style="display: none"/>
<div id="usage.tutorial.declare-design" class="section">
<h3 class="title">
- <a href="#a-607449058">5.6.1</a>
+ <a href="#a-607192538" class="ref">5.9.1</a>
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>
+ <p>First, we need a Verilog design to test. In this tutorial, <a href="#fig:counter.v_decl" class="ref">Example 5</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>
@@ -2023,71 +2121,70 @@
<div class="formal">
<div class="example" id="fig:counter.v_decl">
- <p class="title"><a href="#a-607445548">Example 3</a>. Declaration of a simple up-counter with synchronous reset</p>
+ <p class="title"><a href="#a-607186858" class="ref">Example 5</a>. Declaration of a simple up-counter with synchronous reset</p>
<pre class="code" lang="verilog">
module counter #(parameter Size = 5) (
input clock,
input reset,
output reg [Size-1 : 0] count
);
-endmodule
-</pre>
+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>
+Before we continue, save the source code shown in <a href="#fig:counter.v_decl" class="ref">Example 5</a> into a file named <tt>counter.v</tt>.</p>
</div>
</p>
<p>
<hr style="display: none"/>
<div id="usage.tutorial.generate-test" class="section">
<h3 class="title">
- <a href="#a-607459658">5.6.2</a>
+ <a href="#a-607217768" class="ref">5.9.2</a>
Generate a test
</h3>
- <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>Now that we have a Verilog design to test, we shall use the <a href="#usage.tools.generate" class="ref">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>
Each format represents a different software development methodology:
<ul>
- <li>RSpec represents <a href="#glossary.BDD">BDD</a></li>
- <li>xUnit represents <a href="#glossary.TDD">TDD</a></li>
+ <li>RSpec represents <a href="#glossary.BDD" class="ref">BDD</a></li>
+ <li>xUnit represents <a href="#glossary.TDD" class="ref">TDD</a></li>
<li>our own format can represent another methodology</li>
</ul>
<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
+mkdir RSpec xUnit
+cp counter.v RSpec
+cp counter.v xUnit
</pre></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>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" class="ref">Example 6</a> and <a href="#fig:generate-test.xUnit" class="ref">Example 7</a>.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:generate-test.RSpec">
- <p class="title"><a href="#a-607452398">Example 4</a>. Generating a test with specification in RSpec format</p>
+ <p class="title"><a href="#a-607199068" class="ref">Example 6</a>. Generating a test with specification in RSpec format</p>
<pre>
$ ruby-vpi generate counter.v --RSpec
module counter
@@ -2105,11 +2202,11 @@
<div class="formal">
<div class="example" id="fig:generate-test.xUnit">
- <p class="title"><a href="#a-607454858">Example 5</a>. Generating a test with specification in xUnit format</p>
+ <p class="title"><a href="#a-607205488" class="ref">Example 7</a>. Generating a test with specification in xUnit format</p>
<pre>
$ ruby-vpi generate counter.v --xUnit
module counter
@@ -2130,39 +2227,39 @@
<p>
<hr style="display: none"/>
<div id="usage.tutorial.specification" class="section">
<h3 class="title">
- <a href="#a-607469758">5.6.3</a>
+ <a href="#a-607227868" class="ref">5.9.3</a>
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>
+ <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" class="ref">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:RSpec_counter_spec.rb">Example 6</a> and <a href="#fig:xUnit_counter_spec.rb">Example 7</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" class="ref">Example 8</a> and <a href="#fig:xUnit_counter_spec.rb" class="ref">Example 9</a>.</p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:RSpec_counter_spec.rb">
- <p class="title"><a href="#a-607462568">Example 6</a>. Specification implemented in RSpec format</p>
+ <p class="title"><a href="#a-607220678" class="ref">Example 8</a>. Specification implemented in RSpec format</p>
<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>
@@ -2198,23 +2295,22 @@
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>
+<span style="color:#080; font-weight:bold">end</span></pre>
</div>
</div>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:xUnit_counter_spec.rb">
- <p class="title"><a href="#a-607464928">Example 7</a>. Specification implemented in xUnit format</p>
+ <p class="title"><a href="#a-607223038" class="ref">Example 9</a>. Specification implemented in xUnit format</p>
<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>
<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>
@@ -2250,19 +2346,18 @@
<span style="color:#080; font-weight:bold">def</span> <span style="color:#06B; font-weight:bold">test_overflow</span>
<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>
+<span style="color:#080; font-weight:bold">end</span></pre>
</div>
</div>
Before we continue,
<ol>
- <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 file named <tt>RSpec/counter_spec.rb</tt> with the source code shown in <a href="#fig:RSpec_counter_spec.rb" class="ref">Example 8</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" class="ref">Example 9</a>.</li>
</ol>
</div>
</p>
@@ -2270,75 +2365,73 @@
<p>
<hr style="display: none"/>
<div id="usage.tutorial.implement-proto" class="section">
<h3 class="title">
- <a href="#a-607475748">5.6.4</a>
+ <a href="#a-607233858" class="ref">5.9.4</a>
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>
+ <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" class="ref">Example 10</a>.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:counter_proto.rb">
- <p class="title"><a href="#a-607472348">Example 8</a>. Ruby prototype of our Verilog design</p>
+ <p class="title"><a href="#a-607230458" class="ref">Example 10</a>. Ruby prototype of our Verilog design</p>
- <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.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>
+ <pre class="code">always <span style="color:#080; font-weight:bold">do</span>
+ wait <span style="color:#080; font-weight:bold">until</span> clock.posedge?
+
+ <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>
-</pre>
+<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>
+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" class="ref">Example 10</a>.</p>
</div>
</p>
<p>
<hr style="display: none"/>
<div id="usage.tutorial.test-proto" class="section">
<h3 class="title">
- <a href="#a-607231778">5.6.5</a>
+ <a href="#a-607247108" class="ref">5.9.5</a>
Verify the prototype
</h3>
- <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>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" class="ref">Example 11</a> and <a href="#fig:test-proto.unit-test" class="ref">Example 12</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>
+ <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.runner.env-vars" class="ref">Section 5.6.1</a> for details). Also, the <a href="#setup.reqs" class="ref">GPL Cver simulator</a> denoted by <em>cver</em>, is used to run the simulation.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:test-proto.RSpec">
- <p class="title"><a href="#a-607478868">Example 9</a>. Running a test with specification in RSpec format</p>
+ <p class="title"><a href="#a-607236978" class="ref">Example 11</a>. Running a test with specification in RSpec format</p>
<pre>
$ cd RSpec
$ rake cver PROTOTYPE=1
@@ -2358,11 +2451,11 @@
<div class="formal">
<div class="example" id="fig:test-proto.unit-test">
- <p class="title"><a href="#a-607481368">Example 10</a>. Running a test with specification in xUnit format</p>
+ <p class="title"><a href="#a-607239478" class="ref">Example 12</a>. Running a test with specification in xUnit format</p>
<pre>
$ cd xUnit
$ rake cver PROTOTYPE=1
@@ -2382,11 +2475,11 @@
<div class="admonition">
<div class="tip" id="What_can_the_test_runner_do_">
<img src="images/tango/tip.png" alt="tip" class="icon"/>
- <p class="title"><a href="#a-607223748">Tip 4</a>. What can the test runner do?</p>
+ <p class="title"><a href="#a-607241748" class="ref">Tip 4</a>. What can the test runner do?</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.
</div>
</div>
</p>
@@ -2398,28 +2491,28 @@
<p>
<hr style="display: none"/>
<div id="usage.tutorial.implement-design" class="section">
<h3 class="title">
- <a href="#a-607245728">5.6.6</a>
+ <a href="#a-607253098" class="ref">5.9.6</a>
Implement the design
</h3>
- <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>
+ <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" class="ref">Example 13</a>.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:counter.v_impl">
- <p class="title"><a href="#a-607235998">Example 11</a>. Implementation of a simple up-counter with synchronous reset</p>
+ <p class="title"><a href="#a-607249698" class="ref">Example 13</a>. Implementation of a simple up-counter with synchronous reset</p>
<pre class="code" lang="verilog">/**
A simple up-counter with synchronous reset.
@param Size Number of bits used to represent the counter's value.
@@ -2436,47 +2529,46 @@
if (reset)
count <= 0;
else
count <= count + 1;
end
-endmodule
-</pre>
+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>
+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" class="ref">Example 13</a></p>
</div>
</p>
<p>
<hr style="display: none"/>
<div id="usage.tutorial.test-design" class="section">
<h3 class="title">
- <a href="#a-607263938">5.6.7</a>
+ <a href="#a-607037508" class="ref">5.9.7</a>
Verify the design
</h3>
- <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>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" class="ref">Example 14</a> and <a href="#fig:test-design.unit-test" class="ref">Example 15</a> illustrate this process.</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>
+ <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" class="ref">GPL Cver simulator</a> denoted by <em>cver</em>, is used to run the simulation.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="fig:test-design.RSpec">
- <p class="title"><a href="#a-607252508">Example 12</a>. Running a test with specification in RSpec format</p>
+ <p class="title"><a href="#a-607000458" class="ref">Example 14</a>. Running a test with specification in RSpec format</p>
<pre>
$ cd RSpec
$ rake cver
@@ -2494,11 +2586,11 @@
<div class="formal">
<div class="example" id="fig:test-design.unit-test">
- <p class="title"><a href="#a-607255018">Example 13</a>. Running a test with specification in xUnit format</p>
+ <p class="title"><a href="#a-607031948" class="ref">Example 15</a>. Running a test with specification in xUnit format</p>
<pre>
$ cd xUnit
$ rake cver
@@ -2523,11 +2615,11 @@
<hr style="display: none"/>
<div id="hacking" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607500728">6</a>
+ Chapter <a href="#a-607355358" class="ref">6</a>
<br/><br/>
<big>Hacking</big>
</h1>
@@ -2535,15 +2627,15 @@
<p>
<hr style="display: none"/>
<div id="hacking.scm" class="section">
<h2 class="title">
- <a href="#a-607491268">6.1</a>
+ <a href="#a-607342188" class="ref">6.1</a>
- Getting the source code
+ Getting the latest source code
</h2>
Check out the source code using <a href="http://darcs.net">Darcs</a> from the project repository:
@@ -2554,25 +2646,45 @@
<p>
<hr style="display: none"/>
+ <div id="Installing_without_really_installing" class="section">
+ <h2 class="title">
+ <a href="#a-607344708" class="ref">6.2</a>
+
+
+
+ Installing without really installing
+ </h2>
+
+ <p>After you’ve obtained the latest source code (see <a href="#hacking.scm" class="ref">Section 6.1</a>), you can use it immediately without having to build or install a Ruby-VPI gem. To do this, set the <code class="code"><span style="color:#036; font-weight:bold">RUBYLIB</span></code> environment variable to the path where you checked out the source code <em>plus</em> the <tt>lib/</tt> directory.</p>
+
+
+ <p>For example, if you checked out the source code into <tt>/home/foo/ruby-vpi/</tt> then you would set the value of the <code class="code"><span style="color:#036; font-weight:bold">RUBYLIB</span></code> environment variable to <tt>/home/foo/ruby-vpi/lib/</tt>. Henceforth, any Ruby-VPI tests you run will use the checked-out source code directly.</p>
+
+ </div>
+ </p>
+
+
+ <p>
+ <hr style="display: none"/>
+
<div id="hacking.release-packages" class="section">
<h2 class="title">
- <a href="#a-607493898">6.2</a>
+ <a href="#a-607347318" class="ref">6.3</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" class="ref">normal requirements</a> you need the following software to build release packages:</p>
<ul>
- <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/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>
@@ -2584,29 +2696,46 @@
<p>
<hr style="display: none"/>
<div id="hacking.manual" class="section">
<h2 class="title">
- <a href="#a-607496128">6.3</a>
+ <a href="#a-607349668" class="ref">6.4</a>
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.
+ <p>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.
+ <p>In addition, the <tt>doc/README</tt> file says: <blockquote>The *.doc files in this directory are plain-text files!</p>
+</p>
+
+
+ <p>To transform them into XHTML, you need the following software:</p>
+
+
+ <ul>
+ <li>Rake: http://docs.rubyrake.org/</li>
+ <li>RedCloth: http://whytheluckystiff.net/ruby/redcloth/</li>
+ <li>Coderay: http://coderay.rubychan.de/</li>
+ </ul>
+
+
+Once you have the above software, simply run the “rake” command.
+</blockquote>
+
</div>
</p>
</div>
<hr style="display: none"/>
<div id="problems" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607556918">7</a>
+ Chapter <a href="#a-607403828" class="ref">7</a>
<br/><br/>
<big>Known problems</big>
</h1>
@@ -2617,11 +2746,11 @@
<p>
<hr style="display: none"/>
<div id="problem.ivl" class="section">
<h2 class="title">
- <a href="#a-607529318">7.1</a>
+ <a href="#a-607383948" class="ref">7.1</a>
Icarus Verilog
</h2>
@@ -2632,38 +2761,37 @@
<p>
<hr style="display: none"/>
<div id="problems.ivl.vpi_handle_by_name.absolute-paths" class="section">
<h3 class="title">
- <a href="#a-607506698">7.1.1</a>
+ <a href="#a-607361328" class="ref">7.1.1</a>
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>
- <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>For example, consider <a href="#ex:TestFoo" class="ref">Example 16</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>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="ex:TestFoo">
- <p class="title"><a href="#a-607503538">Example 14</a>. Part of a bench which instantiates a Verilog design</p>
+ <p class="title"><a href="#a-607358168" class="ref">Example 16</a>. Part of a bench which instantiates a Verilog design</p>
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
Foo my_foo(.clk(clk_reg));
-endmodule
-</pre>
+endmodule</pre>
</div>
</div>
</p>
</div>
@@ -2671,65 +2799,63 @@
<hr style="display: none"/>
<div id="problems.ivl.vpi_handle_by_name.connect-registers" class="section">
<h3 class="title">
- <a href="#a-607516388">7.1.2</a>
+ <a href="#a-607371018" class="ref">7.1.2</a>
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">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>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" class="ref">Example 17</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">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>
+ <p>The solution is to change the design such that it appears like the one shown in <a href="#ex:TestFoo_fix" class="ref">Example 18</a> where the register is connected to a wire, or <a href="#ex:TestFoo" class="ref">Example 16</a> where the register is connected to a module instantiation.</p>
<p>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="ex:TestFoo_bad">
- <p class="title"><a href="#a-607509598">Example 15</a>. Bad design with unconnected registers</p>
+ <p class="title"><a href="#a-607364228" class="ref">Example 17</a>. Bad design with unconnected registers</p>
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>
+endmodule</pre>
</div>
</div>
<hr style="display: none"/>
<div class="formal">
<div class="example" id="ex:TestFoo_fix">
- <p class="title"><a href="#a-607512038">Example 16</a>. Fixed design with wired registers</p>
+ <p class="title"><a href="#a-607366668" class="ref">Example 18</a>. Fixed design with wired registers</p>
Here the <code class="code">clk_reg</code> register is connected to the <code class="code">clk_wire</code> wire.
<pre class="code" lang="verilog">
module TestFoo;
reg clk_reg;
wire clk_wire;
assign clk_wire = clk_reg;
-endmodule
-</pre>
+endmodule</pre>
</div>
</div>
</p>
</div>
@@ -2737,72 +2863,32 @@
<hr style="display: none"/>
<div id="problems.ivl.vpi_reset" class="section">
<h3 class="title">
- <a href="#a-607518638">7.1.3</a>
+ <a href="#a-607373268" class="ref">7.1.3</a>
- Vpi::reset
+ VPI::reset
</h3>
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.
</div>
</p>
</div>
-
-
- <hr style="display: none"/>
-
- <div id="problem.ncsim" class="section">
- <h2 class="title">
- <a href="#a-607534708">7.2</a>
-
-
-
- Cadence NC-Sim
- </h2>
-
- <p>The following sections describe problems that occur when Cadence NC-Sim (version 05.83-s003) is used with Ruby-VPI.</p>
-
-
- <p>
- <hr style="display: none"/>
-
- <div id="problem.ncsim.vpiForceFlag" class="section">
- <h3 class="title">
- <a href="#a-607531748">7.2.1</a>
-
-
-
- Cannot force values onto handles
- </h3>
-
- <p>When you write to a handle’s value using <code class="code">vpi_put_value()</code> with the <code class="code"><span style="color:#036; font-weight:bold">VpiForceFlag</span></code> propagation parameter, it does not have any effect. As a result, the “register_file” sample test fails when you run it with NC-Sim.</p>
-
-
- <p>This might be a bug in NC-Sim itself: even though I specified the “+access+rwc” command-line option for NC-Sim, I’m thinking that the force/release capability is not really enabled. However, it’s more likely that there’s a bug in the “register_file” sample test.</p>
-
-
- <p>If you happen to know the solution, please tell me either on the project forums or via e-mail (see the LICENSE file for my e-mail address). Thanks.</p>
-
- </div>
-</p>
-
- </div>
</p>
</div>
<hr style="display: none"/>
<div id="glossary" class="chapter">
<h1 class="title">
- Chapter <a href="#a-607589368">8</a>
+ Chapter <a href="#a-607436278" class="ref">8</a>
<br/><br/>
<big>Glossary</big>
</h1>
@@ -2810,59 +2896,59 @@
<hr style="display: none"/>
<div id="glossary.test" class="section">
<h2 class="title">
- <a href="#a-607559748">8.1</a>
+ <a href="#a-607406658" class="ref">8.1</a>
Test
</h2>
- Something that checks if a <a href="#glossary.design">design</a> satisfies a <a href="#glossary.specification">specification</a>
+ Something that checks if a <a href="#glossary.design" class="ref">design</a> satisfies a <a href="#glossary.specification" class="ref">specification</a>
</div>
<hr style="display: none"/>
<div id="glossary.design" class="section">
<h2 class="title">
- <a href="#a-607562248">8.2</a>
+ <a href="#a-607409158" class="ref">8.2</a>
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?
+ A Verilog module that is verified against a <a href="#glossary.specification" class="ref">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?
</div>
<hr style="display: none"/>
<div id="glossary.specification" class="section">
<h2 class="title">
- <a href="#a-607565008">8.3</a>
+ <a href="#a-607411918" class="ref">8.3</a>
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.
+ A set of <a href="#glossary.expectation" class="ref">expectations</a> which define the desired behavior of a <a href="#glossary.design" class="ref">design</a> when it is subjected to certain stimulus.
</div>
<hr style="display: none"/>
<div id="glossary.expectation" class="section">
<h2 class="title">
- <a href="#a-607567228">8.4</a>
+ <a href="#a-607414138" class="ref">8.4</a>
Expectation
</h2>
@@ -2874,27 +2960,27 @@
<hr style="display: none"/>
<div id="glossary.handle" class="section">
<h2 class="title">
- <a href="#a-607569708">8.5</a>
+ <a href="#a-607416618" class="ref">8.5</a>
Handle
</h2>
- A reference to an object inside the Verilog simulation. See <a href="#vpi.handles">Section 4.3.2</a> for usage instructions.
+ A reference to an object inside the Verilog simulation. See <a href="#vpi.handles" class="ref">Section 5.2.1</a> for usage instructions.
</div>
<hr style="display: none"/>
<div id="glossary.rake" class="section">
<h2 class="title">
- <a href="#a-607571968">8.6</a>
+ <a href="#a-607418878" class="ref">8.6</a>
Rake
</h2>
@@ -2911,18 +2997,18 @@
<hr style="display: none"/>
<div id="glossary.RSpec" class="section">
<h2 class="title">
- <a href="#a-607574508">8.7</a>
+ <a href="#a-607421418" class="ref">8.7</a>
RSpec
</h2>
- <p>The <a href="#glossary.BDD">BDD</a> framework for Ruby.</p>
+ <p>The <a href="#glossary.BDD" class="ref">BDD</a> framework for Ruby.</p>
<p>See the <a href="http://rspec.rubyforge.org">RSpec website</a> and <a href="http://rspec.rubyforge.org/documentation/index.html">tutorial</a> for more information.</p>
</div>
@@ -2930,11 +3016,11 @@
<hr style="display: none"/>
<div id="glossary.TDD" class="section">
<h2 class="title">
- <a href="#a-607576768">8.8</a>
+ <a href="#a-607423678" class="ref">8.8</a>
Test driven development
</h2>
@@ -2949,11 +3035,11 @@
<hr style="display: none"/>
<div id="glossary.BDD" class="section">
<h2 class="title">
- <a href="#a-607579028">8.9</a>
+ <a href="#a-607425938" class="ref">8.9</a>
Behavior driven development
</h2>
@@ -2964,57 +3050,12 @@
<p>See the <a href="http://behaviour-driven.org/">official wiki</a> for more information.</p>
</div>
</div>
+
+ <br/>
+ <hr/>
+ This website is maintained by Suraj N. Kurapati (SNK at GNA dot ORG). This particular webpage was last updated on Mon Aug 27 19:26:43 -0700 2007.
</div>
-
- <hr style="display: none"/>
- <div id="toc">
- <h1 id="toc:contents">Contents</h1>
- <ul><li><span class="hide">1 </span><a id="a-607241338" href="#Ruby-VPI_18.0.2_user_manual">Ruby-VPI 18.0.2 user manual</a><ul><li><span class="hide">1.1 </span><a id="a-607234498" href="#About_this_manual">About this manual</a></li><li><span class="hide">1.2 </span><a id="a-607237028" href="#Legal_notice">Legal notice</a></li></ul></li><li><span class="hide">2 </span><a id="a-607321098" href="#intro">Welcome</a><ul><li><span class="hide">2.1 </span><a id="a-607255258" href="#resources">Resources</a><ul><li><span class="hide">2.1.1 </span><a id="a-607244578" href="#Records">Records</a></li><li><span class="hide">2.1.2 </span><a id="a-607246958" href="#Documentation">Documentation</a></li><li><span class="hide">2.1.3 </span><a id="a-607249658" href="#Facilities">Facilities</a></li></ul></li><li><span class="hide">2.2 </span><a id="a-607267568" href="#intro.features">Features</a><ul><li><span class="hide">2.2.1 </span><a id="a-607257898" href="#Portable">Portable</a></li><li><span class="hide">2.2.2 </span><a id="a-607260298" href="#Agile">Agile</a></li><li><span class="hide">2.2.3 </span><a id="a-607262698" href="#Powerful">Powerful</a></li></ul></li><li><span class="hide">2.3 </span><a id="a-607279798" href="#intro.reqs">Requirements</a><ul><li><span class="hide">2.3.1 </span><a id="a-607270208" href="#Verilog_simulator">Verilog simulator</a></li><li><span class="hide">2.3.2 </span><a id="a-607272648" href="#Compilers">Compilers</a></li><li><span class="hide">2.3.3 </span><a id="a-607274968" href="#Libraries">Libraries</a></li></ul></li><li><span class="hide">2.4 </span><a id="a-607282358" href="#intro.applications">Applications</a></li><li><span class="hide">2.5 </span><a id="a-607284958" href="#intro.appetizers">Appetizers</a></li><li><span class="hide">2.6 </span><a id="a-607287828" href="#intro.license">License</a></li><li><span class="hide">2.7 </span><a id="a-607293218" href="#intro.related-works">Related works</a><ul><li><span class="hide">2.7.1 </span><a id="a-607290278" href="#intro.related-works.pli">Ye olde PLI</a></li></ul></li></ul></li><li><span class="hide">3 </span><a id="a-607361758" href="#setup">Setup</a><ul><li><span class="hide">3.1 </span><a id="a-607324288" href="#setup.manifest">Manifest</a></li><li><span class="hide">3.2 </span><a id="a-607329728" href="#setup.reqs">Requirements</a></li><li><span class="hide">3.3 </span><a id="a-607335898" href="#setup.recom">Recommendations</a><ul><li><span class="hide">3.3.1 </span><a id="a-607332558" href="#setup.recom.merger">Text merging tool</a></li></ul></li><li><span class="hide">3.4 </span><a id="a-607345038" href="#setup.inst">Installation</a><ul><li><span class="hide">3.4.1 </span><a id="a-607340978" href="#setup.inst.windows">Installing on Windows</a></li></ul></li><li><span class="hide">3.5 </span><a id="a-607347318" href="#setup.maintenance">Maintenance</a></li></ul></li><li><span class="hide">4 </span><a id="a-607368998" href="#organization">Organization</a><ul><li><span class="hide">4.1 </span><a id="a-607370648" href="#overview.relay">Ruby/Verilog interaction</a></li><li><span class="hide">4.2 </span><a id="a-607376218" href="#organization.tests">Tests</a></li><li><span class="hide">4.3 </span><a id="a-607291858" href="#VPI_in_Ruby">VPI in Ruby</a><ul><li><span class="hide">4.3.1 </span><a id="a-607385138" 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-607378708" href="#Names_are_capitalized">Names are capitalized</a></li><li><span class="hide">4.3.1.2 </span><a id="a-607381208" 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-607236168" href="#vpi.handles">Handles</a><ul><li><span class="hide">4.3.2.1 </span><a id="a-607387798" href="#Shortcuts_for_productivity">Shortcuts for productivity</a></li><li><span class="hide">4.3.2.2 </span><a id="a-607390358" 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-607393298" 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-607249768" href="#vpi.callbacks">Callbacks</a></li></ul></li></ul></li><li><span class="hide">5 </span><a id="a-607488938" href="#usage">Usage</a><ul><li><span class="hide">5.1 </span><a id="a-607395418" href="#usage.prototyping">Prototyping</a><ul><li><span class="hide">5.1.1 </span><a id="a-607378568" href="#Getting_started">Getting started</a></li><li><span class="hide">5.1.2 </span><a id="a-607383008" href="#How_does_prototyping_work_">How does prototyping work?</a></li></ul></li><li><span class="hide">5.2 </span><a id="a-607403488" href="#usage.debugger">Debugging</a><ul><li><span class="hide">5.2.1 </span><a id="a-607400418" href="#usage.debugger.init">Advanced initialization</a></li></ul></li><li><span class="hide">5.3 </span><a id="a-607420258" href="#usage.test-runner">Test runner</a><ul><li><span class="hide">5.3.1 </span><a id="a-607413148" href="#usage.test-runner.env-vars">Environment variables</a><ul><li><span class="hide">5.3.1.1 </span><a id="a-607406578" 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-607439408" href="#usage.tools">Tools</a><ul><li><span class="hide">5.4.1 </span><a id="a-607429588" href="#usage.tools.generate">Automated test generation</a></li><li><span class="hide">5.4.2 </span><a id="a-607431878" href="#usage.tools.convert">Verilog to Ruby conversion</a></li></ul></li><li><span class="hide">5.5 </span><a id="a-607441648" href="#usage.examples">Sample tests</a></li><li><span class="hide">5.6 </span><a id="a-607314468" href="#usage.tutorial">Tutorial</a><ul><li><span class="hide">5.6.1 </span><a id="a-607449058" href="#usage.tutorial.declare-design">Start with a Verilog design</a></li><li><span class="hide">5.6.2 </span><a id="a-607459658" href="#usage.tutorial.generate-test">Generate a test</a></li><li><span class="hide">5.6.3 </span><a id="a-607469758" href="#usage.tutorial.specification">Specify your expectations</a></li><li><span class="hide">5.6.4 </span><a id="a-607475748" href="#usage.tutorial.implement-proto">Implement the prototype</a></li><li><span class="hide">5.6.5 </span><a id="a-607231778" href="#usage.tutorial.test-proto">Verify the prototype</a></li><li><span class="hide">5.6.6 </span><a id="a-607245728" href="#usage.tutorial.implement-design">Implement the design</a></li><li><span class="hide">5.6.7 </span><a id="a-607263938" href="#usage.tutorial.test-design">Verify the design</a></li></ul></li></ul></li><li><span class="hide">6 </span><a id="a-607500728" href="#hacking">Hacking</a><ul><li><span class="hide">6.1 </span><a id="a-607491268" href="#hacking.scm">Getting the source code</a></li><li><span class="hide">6.2 </span><a id="a-607493898" href="#hacking.release-packages">Building release packages</a></li><li><span class="hide">6.3 </span><a id="a-607496128" href="#hacking.manual">Editing this manual</a></li></ul></li><li><span class="hide">7 </span><a id="a-607556918" href="#problems">Known problems</a><ul><li><span class="hide">7.1 </span><a id="a-607529318" href="#problem.ivl">Icarus Verilog</a><ul><li><span class="hide">7.1.1 </span><a id="a-607506698" 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-607516388" href="#problems.ivl.vpi_handle_by_name.connect-registers">Registers must be connected</a></li><li><span class="hide">7.1.3 </span><a id="a-607518638" href="#problems.ivl.vpi_reset">Vpi::reset</a></li></ul></li><li><span class="hide">7.2 </span><a id="a-607534708" href="#problem.ncsim">Cadence NC-Sim</a><ul><li><span class="hide">7.2.1 </span><a id="a-607531748" href="#problem.ncsim.vpiForceFlag">Cannot force values onto handles</a></li></ul></li></ul></li><li><span class="hide">8 </span><a id="a-607589368" href="#glossary">Glossary</a><ul><li><span class="hide">8.1 </span><a id="a-607559748" href="#glossary.test">Test</a></li><li><span class="hide">8.2 </span><a id="a-607562248" href="#glossary.design">Design</a></li><li><span class="hide">8.3 </span><a id="a-607565008" href="#glossary.specification">Specification</a></li><li><span class="hide">8.4 </span><a id="a-607567228" href="#glossary.expectation">Expectation</a></li><li><span class="hide">8.5 </span><a id="a-607569708" href="#glossary.handle">Handle</a></li><li><span class="hide">8.6 </span><a id="a-607571968" href="#glossary.rake">Rake</a></li><li><span class="hide">8.7 </span><a id="a-607574508" href="#glossary.RSpec">RSpec</a></li><li><span class="hide">8.8 </span><a id="a-607576768" href="#glossary.TDD">Test driven development</a></li><li><span class="hide">8.9 </span><a id="a-607579028" 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-607326758">Add support for your Verilog simulator</a></li>
- <li><a href="#Tuning_for_maximum_performance" id="a-607338448">Tuning for maximum performance</a></li>
- <li><a href="#Using__kdiff3__with_the_automated_test_generator." id="a-607425508">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
- <li><a href="#What_can_the_test_runner_do_" id="a-607223748">What can the test runner do?</a></li>
- </ol>
- <h1 id="toc:caution">Cautions</h1>
- <ol>
- <li><a href="#Do_not_rename_generated_files" id="a-607423018">Do not rename generated files</a></li>
- </ol>
- <h1 id="toc:figure">Figures</h1>
- <ol>
- <li><a href="#fig:organization.detail" id="a-607364358">Where does Ruby-VPI fit in?</a></li>
- <li><a href="#fig:ruby_relay" id="a-607367168">Interaction between Ruby and Verilog</a></li>
- <li><a href="#fig:organization" id="a-607373118">Organization of a test in Ruby-VPI</a></li>
- <li><a href="#fig:method_naming_format" id="a-607396098">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-607398528">Possible accessors and their implications</a></li>
- <li><a href="#ex:properties" id="a-607223948">Examples of accessing a handle’s properties</a></li>
- </ol>
- <h1 id="toc:example">Examples</h1>
- <ol>
- <li><a href="#ex:callback" id="a-607242918">Using a callback for value change notification</a></li>
- <li><a href="#Running_a_test_with_environment_variables" id="a-607408978">Running a test with environment variables</a></li>
- <li><a href="#fig:counter.v_decl" id="a-607445548">Declaration of a simple up-counter with synchronous reset</a></li>
- <li><a href="#fig:generate-test.RSpec" id="a-607452398">Generating a test with specification in RSpec format</a></li>
- <li><a href="#fig:generate-test.xUnit" id="a-607454858">Generating a test with specification in xUnit format</a></li>
- <li><a href="#fig:RSpec_counter_spec.rb" id="a-607462568">Specification implemented in RSpec format</a></li>
- <li><a href="#fig:xUnit_counter_spec.rb" id="a-607464928">Specification implemented in xUnit format</a></li>
- <li><a href="#fig:counter_proto.rb" id="a-607472348">Ruby prototype of our Verilog design</a></li>
- <li><a href="#fig:test-proto.RSpec" id="a-607478868">Running a test with specification in RSpec format</a></li>
- <li><a href="#fig:test-proto.unit-test" id="a-607481368">Running a test with specification in xUnit format</a></li>
- <li><a href="#fig:counter.v_impl" id="a-607235998">Implementation of a simple up-counter with synchronous reset</a></li>
- <li><a href="#fig:test-design.RSpec" id="a-607252508">Running a test with specification in RSpec format</a></li>
- <li><a href="#fig:test-design.unit-test" id="a-607255018">Running a test with specification in xUnit format</a></li>
- <li><a href="#ex:TestFoo" id="a-607503538">Part of a bench which instantiates a Verilog design</a></li>
- <li><a href="#ex:TestFoo_bad" id="a-607509598">Bad design with unconnected registers</a></li>
- <li><a href="#ex:TestFoo_fix" id="a-607512038">Fixed design with wired registers</a></li>
- </ol>
- </div>
- </body>
+ </body>
</html>