doc/manual.html in ruby-vpi-15.0.0 vs doc/manual.html in ruby-vpi-15.0.1
- old
+ new
@@ -1,27 +1,35 @@
<!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" />
+ <link rel="stylesheet" type="text/css" href="common.css" media="screen" />
+ <link rel="stylesheet" type="text/css" href="print.css" media="print" />
<link rel="alternate" type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml" title="RSS feed for this project." />
<title>Ruby-VPI user manual</title>
</head>
<body>
- <div id="navigation">
- <p><a href="readme.html"><img src="images/home.png" title="project home" alt="project home" /></a></p>
+ <br/><br/> <!-- give space below #menu -->
+
+ <p style="text-align:center;"><a href="readme.html"><img src="images/home.png" title="Return to main page" alt="Return to main page" /></a></p>
+
+ <div id="menu">
+ <a href="#index">Contents</a> · <a href="#figures">Figures</a> · <a href="#tables">Tables</a> · <a href="#examples">Examples</a> · <a href="#tips">Tips</a> · <a href="#notes">Notes</a> · <a href="#importants">Importants</a>
+ </div>
+
+ <div id="index">
<h1>Contents</h1>
<ul>
<li>1 <a href="#anchor4">Ruby-VPI user manual</a>
<ul>
<li>1.1 <a href="#terms">Terms</a></li>
</ul>
</li>
<li>2 <a href="#intro">Introduction</a>
<ul>
- <li>2.1 <a href="#intro.features">Features</a>
+ <li>2.1 <a href="#intro.features">Prominent features</a>
<ul>
<li>2.1.1 <a href="#anchor5">Portable</a></li>
<li>2.1.2 <a href="#anchor6">Agile</a></li>
<li>2.1.3 <a href="#anchor7">Powerful</a></li>
<li>2.1.4 <a href="#anchor8">Free</a></li>
@@ -151,57 +159,25 @@
<li>9.0 <a href="#glossary.test">Test</a></li>
<li>9.1 <a href="#glossary.test_bench">Test bench</a></li>
</ul></li>
</ul>
- <h1>Admonitions</h1>
+ <h1>Formals</h1>
- <h2>Tips</h2>
- <ol>
- <li><a href="#tip1">Add support for your Verilog simulator</a></li>
- <li><a href="#tip2">Running multiple tests at once.</a></li>
- <li><a href="#tip3">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
- <li><a href="#tip4">What can the test runner do?</a></li>
- </ol>
- <h2>Notes</h2>
- <ol>
- <li><a href="#note1">note1</a></li>
- <li><a href="#note2">Undefined symbols in Windows</a></li>
- <li><a href="#note3">note3</a></li>
- <li><a href="#note4">note4</a></li>
- <li><a href="#note5">note5</a></li>
- <li><a href="#note6">Fixed in 2.0.0.</a></li>
- <li><a href="#note7">Fixed in 2.0.0.</a></li>
- <li><a href="#note8">Fixed in 2.0.0.</a></li>
- </ol>
- <h2>Importants</h2>
- <ol>
- <li><a href="#important1">Before we continue…</a></li>
- <li><a href="#important2">Before we continue…</a></li>
- <li><a href="#important3">Before we continue…</a></li>
- <li><a href="#important4">Before we continue…</a></li>
- </ol>
- <h2>Cautions</h2>
- <ol>
- <li><a href="#caution1">caution1</a></li>
- </ol>
- <h1>Formals</h1>
-
- <h2>Figures</h2>
- <ol>
+ <h2 id="figures">Figures</h2>
+ <ol>
<li><a href="#fig..organization">Overall organization of a test</a></li>
<li><a href="#fig..organization.detail">Detailed organization of a test</a></li>
<li><a href="#fig..ruby_relay">Interaction between Ruby and Verilog</a></li>
<li><a href="#figure4">Method naming format for accessing a handle’s properties</a></li>
- <li><a href="#figure5">Output from <xref#ex..callback></a></li>
</ol>
- <h2>Tables</h2>
- <ol>
+ <h2 id="tables">Tables</h2>
+ <ol>
<li><a href="#tbl..accessors">Possible accessors and their implications</a></li>
</ol>
- <h2>Examples</h2>
- <ol>
+ <h2 id="examples">Examples</h2>
+ <ol>
<li><a href="#ex..properties">Examples of accessing a handle’s properties</a></li>
<li><a href="#ex..callback">Using a callback for value change notification</a></li>
<li><a href="#example3">Seeing what a test runner can do</a></li>
<li><a href="#example4">Running a test with environment variables</a></li>
<li><a href="#fig..counter.v_decl">Declaration of a simple up-counter with synchronous reset</a></li>
@@ -217,15 +193,42 @@
<li><a href="#fig..test-design.unit-test">Running a test with specification in xUnit format</a></li>
<li><a href="#ex..TestFoo">Part of a bench which instantiates a Verilog design</a></li>
<li><a href="#ex..TestFoo_bad">Bad design with unconnected registers</a></li>
<li><a href="#ex..TestFoo_fix">Fixed design with wired registers</a></li>
</ol>
- </div>
+ <h1>Admonitions</h1>
+
+ <h2 id="tips">Tips</h2>
+ <ol>
+ <li><a href="#tip1">Add support for your Verilog simulator</a></li>
+ <li><a href="#tip2">Running multiple tests at once.</a></li>
+ <li><a href="#tip3">Using <strong>kdiff3</strong> with the automated test generator.</a></li>
+ <li><a href="#tip4">What can the test runner do?</a></li>
+ </ol>
+ <h2 id="notes">Notes</h2>
+ <ol>
+ <li><a href="#note1">Glossary has definitions</a></li>
+ <li><a href="#note2">Undefined symbols in Windows</a></li>
+ <li><a href="#note3">No capitalization for <span class="caps">VPI</span> functions</a></li>
+ <li><a href="#note4"><code>Vpi::Handle</code> heritage</a></li>
+ <li><a href="#note5">note5</a></li>
+ <li><a href="#note6">Fixed in 2.0.0.</a></li>
+ <li><a href="#note7">Fixed in 2.0.0.</a></li>
+ <li><a href="#note8">Fixed in 2.0.0.</a></li>
+ </ol>
+ <h2 id="importants">Importants</h2>
+ <ol>
+ <li><a href="#important1">Before we continue…</a></li>
+ <li><a href="#important2">Before we continue…</a></li>
+ <li><a href="#important3">Before we continue…</a></li>
+ <li><a href="#important4">Before we continue…</a></li>
+ </ol>
+ </div>
<h1 id="anchor4">1 Ruby-VPI user manual</h1>
- <p>This manual was last updated on Sat Jan 13 16:42:19 <span class="caps">PST 2007</span>.</p>
+ <p>This manual was last updated on Mon Jan 15 10:16:44 <span class="caps">PST 2007</span>.</p>
<p>It is meant to be read in conjunction with the <a href="../ref/ruby/index.html">reference documentation for Ruby-VPI</a>. In addition, if you are new to <a href="http://www.ruby-lang.org">the Ruby language</a>, you are encouraged to <a href="http://www.ruby-lang.org/en/documentation/">explore its documentation</a> alongside this manual.</p>
@@ -236,11 +239,11 @@
<h2 id="terms">1.1 Terms</h2>
- <p>Copyright© 2006 Suraj N. Kurapati.</p>
+ <p>Copyright© 2006, 2007 Suraj N. Kurapati.</p>
<p>Permission is granted to copy, distribute and/or modify this document under the terms of the <a href="http://www.gnu.org/copyleft/fdl.html"><span class="caps">GNU</span> Free Documentation License</a>, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the the file named <a href="./LICENSE"><span class="caps">LICENSE</span></a>.</p>
@@ -251,13 +254,71 @@
<p>Ruby-VPI is a <a href="http://www.ruby-lang.org">Ruby</a> interface to <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE 1364</span>-2005 Verilog <span class="caps">VPI</span></a>. It lets you create complex Verilog test benches easily and wholly in Ruby.</p>
- <h2 id="intro.features">2.1 Features</h2>
+ <p class="title">Documentation</p>
+ <ul>
+ <li><a href="manual.html#usage.tutorial">Tutorial</a>
+ – learn how to use Ruby-VPI quickly.</li>
+ <li><a href="manual.html">Manual</a>
+ – complete documentation for users. <em>Start here!</em></li>
+ <li><a href="../ref/">Reference</a>
+ – <span class="caps">API</span> documentation for Ruby libraries and C extension.</li>
+ </ul>
+
+
+ <p class="title">Records</p>
+
+
+ <ul>
+ <li><a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon.png" title="RSS feed icon" alt="RSS feed icon" /> RSS feed</a>
+ – keep track of new releases at your leisure.</li>
+ <li><a href="history.html">Release history</a>
+ – record of all release notes.</li>
+ <li><a href="memo.html">Memorandum</a>
+ – pending tasks for future releases.</li>
+ </ul>
+
+
+ <p class="title">Facilities</p>
+
+
+ <ul>
+ <li><a href="http://rubyforge.org/projects/ruby-vpi">Project portal</a>
+ – hosted generously by <a href="http://rubyforge.org">RubyForge</a>.</li>
+ <li><a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi">Source code</a>
+ – browse online or obtain through <a href="http://abridgegame.org/darcs/">Darcs</a>.</li>
+ <li><a href="http://rubyforge.org/frs/?group_id=1339">Downloads</a>
+ – obtain release packages.</li>
+ <li><a href="http://rubyforge.org/tracker/?group_id=1339">Bugs</a>
+ – report defects in the software.</li>
+ <li><a href="http://rubyforge.org/tracker/?group_id=1339">Patches</a>
+ – submit patches to source code.</li>
+ <li><a href="http://rubyforge.org/tracker/?group_id=1339">Requests</a>
+ – request new features or get support.</li>
+ <li><a href="http://rubyforge.org/forum/?group_id=1339">Forums</a>
+ – discuss things and ask questions.</li>
+ </ul>
+
+
+ <p class="title">Outreach</p>
+
+
+ <ul>
+ <li><a href="http://ruby-vpi.rubyforge.org/news">News</a>
+ – see what’s cooking for the next release.</li>
+ <li><a href="http://ruby-vpi.rubyforge.org/talks">Talks</a>
+ – materials from presentations and seminars.</li>
+ </ul>
+
+
+ <h2 id="intro.features">2.1 Prominent features</h2>
+
+
<h3 id="anchor5">2.1.1 Portable</h3>
<ul>
<li>Supports the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
@@ -452,11 +513,11 @@
<div class="note" id="note1">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
- <p class="title">Note:</p>
+ <p class="title">Note: Glossary has definitions</p>
<p>Have a look at the <a href="#glossary">glossary</a> for definitions of terms used in this manual.</p>
@@ -736,42 +797,64 @@
<li>You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.</li>
<li>You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.</li>
</ul>
+ <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
+
+
+ <h1 id="usage">5 Usage</h1>
+
+
+ <h2 id="usage.vpi">5.1 <span class="caps">VPI</span> in Ruby</h2>
+
+
+ <p>The <em>entire</em> IEEE Std 1364-2005 <span class="caps">VPI</span> interface is available in Ruby, but with a few minor differences.</p>
+
+
+ <p class="title">Capitalize those names!</p>
+
+
+ <p>The names of all <span class="caps">VPI</span> types, structures, and constants become <em>capitalized</em> because Ruby requires that the names of constants begin with a capital letter.</p>
+
+
+ <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby.</p>
+
+
<div class="admonition">
<div class="note" id="note3">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
- <p class="title">Note:</p>
+ <p class="title">Note: No capitalization for <span class="caps">VPI</span> functions</p>
- <p>Learn more about using and manipulating RubyGems in <a href="http://www.rubygems.org">the RubyGems user manual</a>.</p>
+ <p>Ruby’s capitalization rule does <em>not</em> apply to <span class="caps">VPI</span> functions—their names remain unchanged in Ruby.</p>
</div>
</div>
- <h1 id="usage">5 Usage</h1>
+ <p class="title">Use Ruby’s <code class="code">printf</code></p>
- <h2 id="usage.vpi">5.1 <span class="caps">VPI</span> in Ruby</h2>
+ <p>The <span class="caps">VPI</span> functions <code class="code">vpi_vprintf</code> and <code class="code">vpi_mcd_vprintf</code> are not made accessible to Ruby. However, this isn’t a big problem because you can use Ruby’s <code class="code">printf</code> method instead.</p>
- <p>The <em>entire</em> IEEE Std 1364-2005 <span class="caps">VPI</span> interface is available in Ruby, but with one minor difference: the names of all <span class="caps">VPI</span> types, structures, and constants become <em>capitalized</em> because Ruby requires that the names of constants begin with a capital letter.</p>
+ <p>The reason for this limitation is that some C compilers have trouble with pointers to the <code class="code">va_list</code> type. For these compilers, the third line of source code shown below causes a “type mismatch” error.</p>
- <p>For example, the <code class="code">s_vpi_value</code> structure becomes the <code class="code"><span style="color:#036; font-weight:bold">S_vpi_value</span></code> class in Ruby. Likewise, the <code class="code">vpiIntVal</code> constant becomes the <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> constant in Ruby.</p>
+<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>
-
- <p>Note that this capitalization rule does <em>not</em> apply to <span class="caps">VPI</span> functions; their names remain unchanged in Ruby.</p>
-
-
<h3 id="usage.vpi.handles">5.1.1 Handles</h3>
<p>A <em>handle</em> is a reference to an object, such as a module, register, wire, and so on, inside the Verilog simulation. In short, handles allow you to inspect and manipulate the design under test and its components.</p>
@@ -781,11 +864,11 @@
<div class="note" id="note4">
<p style="float:left"><img src="images/note.png" title="note" alt="note" /></p>
- <p class="title">Note:</p>
+ <p class="title">Note: <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::<span style="color:#036; font-weight:bold">Handle</span></code> heritage</p>
<p>Handles 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>
@@ -946,11 +1029,11 @@
<table>
<tr>
<th rowspan="2">Ruby expression </th>
- <th colspan="6">Parts of speech </th>
+ <th colspan="6">Method naming format </th>
<th rowspan="2">Description </th>
</tr>
<tr>
<th>Operation </th>
<th>_ </th>
@@ -965,11 +1048,11 @@
<td> </td>
<td> vpiIntVal </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the logic value of the handle’s vpiIntVal property. </td>
+ <td rowspan="4">These expressions access the <strong>logic value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiIntVal_l</code> </td>
<td> </td>
<td> </td>
@@ -1002,11 +1085,11 @@
<td> </td>
<td> vpiIntVal </td>
<td> </td>
<td> </td>
<td> = </td>
- <td rowspan="4">These expressions assign the number 15 to the logic value of the handle’s vpiIntVal property. </td>
+ <td rowspan="4">These expressions assign the number 15 to the <strong>logic value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiIntVal</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiIntVal_l = <span style="color:#00D; font-weight:bold">15</span></code> </td>
<td> </td>
<td> </td>
@@ -1039,11 +1122,11 @@
<td> </td>
<td> vpiType </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the integer value of the handle’s vpiType property. </td>
+ <td rowspan="4">These expressions access the <strong>integer value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiType</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiType_i</code> </td>
<td> </td>
<td> </td>
@@ -1076,11 +1159,11 @@
<td> </td>
<td> vpiProtected </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="6">These expressions access the boolean value of the handle’s vpiProtected property. </td>
+ <td rowspan="6">These expressions access the <strong>boolean value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiProtected</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiProtected_b</code> </td>
<td> </td>
<td> </td>
@@ -1131,11 +1214,11 @@
<td> </td>
<td> vpiFullName </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the string value of the handle’s vpiFullName property. </td>
+ <td rowspan="4">These expressions access the <strong>string value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiFullName</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiFullName_s</code> </td>
<td> </td>
<td> </td>
@@ -1168,11 +1251,11 @@
<td> </td>
<td> vpiParent </td>
<td> </td>
<td> </td>
<td> </td>
- <td rowspan="4">These expressions access the handle value of the handle’s vpiParent property. </td>
+ <td rowspan="4">These expressions access the <strong>handle value</strong> of the handle’s <code class="code"><span style="color:#036; font-weight:bold">VpiParent</span></code> property. </td>
</tr>
<tr>
<td> <code class="code">handle.vpiParent_h</code> </td>
<td> </td>
<td> </td>
@@ -1308,27 +1391,13 @@
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>
- <p>To see this code in action, append it to the <tt>counter_rspec_spec.rb</tt> and <tt>counter_xunit_spec.rb</tt> files, which are provided in <a href="#usage.examples">the section named “Sample tests”</a> and discussed in <a href="#usage.tutorial.specification">the section named “Specify your expectations”</a>.</p>
+ <p>Shown below is the result of appending this code to the <tt>counter_rspec_spec.rb</tt> file (provided in <a href="#usage.examples">the section named “Sample tests”</a> and discussed in <a href="#usage.tutorial.specification">the section named “Specify your expectations”</a>) and running the <a href="#usage.tutorial">counter_rspec test</a>.</p>
-</div>
-
-</div>
-
-<div class="formal">
-
-<div class="figure" id="figure5">
-
- <p class="title">Figure 5. Output from <a href="#ex..callback">the example named “Using a callback for value change notification”</a></p>
-
-
- <p>Shown below is the output from running the <a href="#usage.tutorial">counter_rspec test</a> after appending the code shown in <a href="#ex..callback">the example named “Using a callback for value change notification”</a> to the <tt>counter_rspec_spec.rb</tt> file.</p>
-
-
<pre>
$ rake -f counter_rspec_runner.rake cver
(in /home/sun/src/ruby-vpi/samp/counter)
cver +loadvpi=/home/sun/src/ruby-vpi/lib/ruby-vpi/../../obj/ruby-vpi.cver.so:vlog_startup_routines_bootstrap counter.v counter_rspec_bench.v
@@ -1427,11 +1496,11 @@
<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>
-In order to create a prototype,
+To create a prototype,
<ol>
<li><a href="#usage.tutorial.declare-design">Determine the <strong>interface</strong></a> (Verilog module declaration) of your design.</li>
<li><a href="#usage.tutorial.generate-test">Generate a test</a> for that interface.</li>
<li><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>
@@ -1645,11 +1714,11 @@
<h2 id="usage.tutorial">5.7 Tutorial</h2>
<ol>
- <li><a href="#usage.tutorial.declare-design">Declare the design</a>, which is a Verilog module, using Verilog 2001 syntax.</li>
+ <li><a href="#usage.tutorial.declare-design">Declare a design</a> using Verilog 2001 syntax.</li>
<li><a href="#usage.tutorial.generate-test">Generate a test</a> for the design using the <a href="#usage.tools.generate-test">automated test generator</a> tool.</li>
<li><a href="#usage.tutorial.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>
@@ -2339,26 +2408,9 @@
</div>
<h3 id="problems.ivl.vpi_reset">7.2.2 Vpi::reset</h3>
-
-<div class="admonition">
-
-<div class="caution" id="caution1">
-
- <p style="float:left"><img src="images/caution.png" title="caution" alt="caution" /></p>
-
-
- <p class="title">Caution:</p>
-
-
- <p>The <code class="code">vpi_control</code> method was removed in release 3.0.0 (2006-04-23). Please use <code class="code"><span style="color:#036; font-weight:bold">Vpi</span>::vpi_control(<span style="color:#036; font-weight:bold">VpiReset</span>)</code> instead.</p>
-
-
-</div>
-
-</div>
<p>In version 0.8 of Icarus Verilog, the <code class="code">vpi_control(vpiReset)</code> VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.</p>
<h2 id="problems.vsim">7.3 Mentor Modelsim</h2>