ruby-vpi 14.0.0 → 15.0.0

data/doc/history.yml

@@ -1,3 +1,37 @@
+-
+  Version: 15.0.0
+
+  Date: 2007-01-13
+
+  Summary: |
+    This release fixes a problem with compilation of the C extension, and makes clock generation code correctly affect Ruby prototypes.
+
+  Acknowledgment: |
+    Thanks to Derek Graham for reporting the problem with compilation of the C extension.
+
+  Notice: |
+    * The @Vpi::advance_time@ method (instead of the @Vpi::simulate@ method) now invokes the design's @simulate!@ method when prototyping is enabled.
+
+      This makes clock generation code (passed to the @RubyVpi::init_bench@ method) affect Ruby prototypes, just as it affects a real Verilog design.
+
+      As a result, Ruby prototypes may need to check for edge-triggering through the new @Vpi::Handle.posedge?@ and @Vpi::Handle.negedge?@ methods. For example, see the "new implementation of the Counter prototype":manual.html#fig..counter_proto.rb.
+
+    h3. New features
+
+    * Added @Vpi::Handle.posedge?@ and @Vpi::Handle.negedge?@ methods which check if a handle's logic value is currently at a positive or negative edge, respectively.
+
+    * Added @Vpi::S_vpi_time.integer@ and @Vpi::S_vpi_time.integer=@ methods which access the @high@ and @low@ integer fields as a single 64-bit integer.
+
+    * Added utility methods for accessing the @value@ field in the @Vpi::S_vpi_value@ structure.
+
+  Details: |
+    * Fixed problem with incorrect Ruby library flag in <tt>ext/extconf.rb</tt>. It happens that the @mkmf@ library determines the correct library flag all by itself!
+
+    * Added new "prototyping section":manual.html#usage.prototyping to user manual.
+
+    * Fixed some broken URLs in user documentation.
+
+
 -
   Version: 14.0.0
 
@@ -851,7 +885,7 @@
   Date: 1999-10-31
 
   Summary: |
-    This is Kazuhiro HIWADA's initial testing release of Ruby-VPI. See its "original announcement":http://www.ruby-talk.org/cgi-bin/scat.rb/ruby/ruby-list/18193 and "source code":http://easter.kuee.kyoto-u.ac.jp/~hiwada/ruby/memo/src/ruby-vpi-test.tgz.
+    This is Kazuhiro HIWADA's initial testing release of Ruby-VPI. See its "original announcement":http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/18193 and "source code":http://rubyforge.org/frs/?group_id=1339&release_id=8852.
 
   Details: |
     * Added ability to relay control from Verilog test bench to Ruby (using @$ruby_callback@) and vice versa (using @PLI::relay_Verilog@).

data/doc/intro.inc

@@ -5,7 +5,7 @@ h2(#intro.features). Features
 
 h3. Portable
 
-* Supports the _entire_ "IEEE Std 1364-2005"::http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 VPI standard.
+* Supports the _entire_ "IEEE Std 1364-2005":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 VPI standard.
 
 * Works with all "major Verilog simulators":manual.html#setup.reqs available today.
 ** Compiled _just once_ during "installation":manual.html#setup.installation and used forever!

data/doc/manual.doc

@@ -227,7 +227,7 @@ The _entire_ IEEE Std 1364-2005 VPI interface is available in Ruby, but with one
 
 For example, the @s_vpi_value@ structure becomes the @S_vpi_value@ class in Ruby. Likewise, the @vpiIntVal@ constant becomes the @VpiIntVal@ constant in Ruby.
 
-Note that this capitalization rule does *not* apply to VPI functions; their names remain _unchanged_ in Ruby.
+Note that this capitalization rule does _not_ apply to VPI functions; their names remain unchanged in Ruby.
 
 
 h3(#usage.vpi.handles). Handles
@@ -267,7 +267,7 @@ In this code, the shortcut is that you simply wrote @counter_module.reset@ inste
 
 h4. Accessing a handle's properties
 
-To access a handle's properties, invoke the proprty name, using the following format, as a method on the handle. <xref ex..properties> shows how this naming format is used.
+To access a handle's properties, invoke the property name, using the following format, as a method on the handle. <xref ex..properties> shows how this naming format is used.
 
 <% figure "Method naming format for accessing a handle's properties" do %>
 |_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum |
@@ -344,22 +344,22 @@ This example shows how to use a callback for notification of changes in a handle
 In this example, the handle being monitored is the @Counter.count@ signal from <xref#fig..counter.v_decl>.
 
 <code>
-cb_time           = S_vpi_time.new
-cb_time.type      = VpiSimTime
-cb_time.low       = 0
-cb_time.high      = 0
+cbTime           = S_vpi_time.new
+cbTime.type      = VpiSimTime
+cbTime.low       = 0
+cbTime.high      = 0
 
-cb_value          = S_vpi_value.new
-cb_value.format   = VpiIntVal
+cbValue          = S_vpi_value.new
+cbValue.format   = VpiIntVal
 
-cb_data           = S_cb_data.new
-cb_data.reason    = CbValueChange
-cb_data.obj       = Counter.count
-cb_data.time      = cb_time
-cb_data.value     = cb_value
-cb_data.index     = 0
+cbData           = S_cb_data.new
+cbData.reason    = CbValueChange
+cbData.obj       = Counter.count
+cbData.time      = cbTime
+cbData.value     = cbValue
+cbData.index     = 0
 
-cb_handle = vpi_register_cb(cb_data) do |data|
+cbHandle = vpi_register_cb(cbData) do |data|
 
   time = (data.time.high << 32) | data.time.low
   count = data.value.value.integer
@@ -470,6 +470,21 @@ Finished in 0.042328 seconds
 <% end %>
 
 
+h2(#usage.prototyping). Prototyping
+
+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.
+
+In order to create a prototype,
+# "Determine the *interface*":#usage.tutorial.declare-design (Verilog module declaration) of your design.
+# "Generate a test":#usage.tutorial.generate-test for that interface.
+# "Implement the prototype":#usage.tutorial.implement-proto in the generated <tt>proto.rb</tt> file.
+# "Verify the prototype":#usage.tutorial.test-proto against its specification.
+
+Once you are satisfied with your prototype, you can proceed to "implement your design in Verilog":#usage.tutorial.implement-design. 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.
+
+Once your design has been implemented in Verilog, you can use the _same_ specification, which was originally used to verify your prototype, to verify your Verilog design.
+
+
 h2(#usage.debugger). Debugging
 
 The "ruby-debug project":http://www.datanoise.com/articles/category/ruby-debug serves as the interactive debugger for Ruby-VPI.
@@ -697,15 +712,7 @@ h3(#usage.tutorial.implement-proto). Implement the prototype
 Now that we have a "specification":#glossary.specification against which to verify our "design":#glossary.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 <xref #fig..counter_proto.rb>.
 
 <% example "Ruby prototype of our Verilog design", "#fig..counter_proto.rb" do %>
-<code>
-def Counter.simulate!
-  if reset.intVal == 1
-    count.intVal = 0
-  else
-    count.intVal += 1
-  end
-end
-</code>
+<code><%= File.read '../samp/counter/counter_rspec_proto.rb' %></code>
 <% end %>
 
 <% important "Before we continue..." do %>
@@ -717,6 +724,8 @@ h3(#usage.tutorial.test-proto). Verify the prototype
 
 Now that we have implemented our prototype, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. This process is illustrated by <xref #fig..test-proto.rspec> and <xref #fig..test-proto.unit-test>.
 
+In these examples, the @PROTOTYPE@ environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to @PROTOTYPE@ before running the test, by using your shell's *export* or *setenv* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
+
 <% example "Running a test with specification in rSpec format", "#fig..test-proto.rspec" do %>
 <pre>
 $ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
@@ -751,8 +760,6 @@ Finished in 0.040668 seconds.
 </pre>
 <% end %>
 
-In these examples, the @PROTOTYPE@ environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to @PROTOTYPE@ before running the test, by using your shell's *export* or *setenv* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
-
 <% tip "What can the test runner do?" do %>
 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.
 <% end %>
@@ -776,6 +783,8 @@ h3(#usage.tutorial.test-design). Verify the design
 
 Now that we have implemented our "design":#glossary.design, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. <xref #fig..test-design.rspec> and <xref #fig..test-design.unit-test> illustrate this process.
 
+In these examples, the @PROTOTYPE@ environment variable is _not_ 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 @PROTOTYPE@, or by using your shell's *unset* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
+
 <% example "Running a test with specification in rSpec format", "#fig..test-design.rspec" do %>
 <pre>
 $ rake -f counter_rspec_runner.rake cver
@@ -806,8 +815,6 @@ Finished in 0.006766 seconds.
 </pre>
 <% end %>
 
-In these examples, the @PROTOTYPE@ environment variable is _not_ 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 @PROTOTYPE@, or by using your shell's *unset* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
-
 
 h1(#hacking). Hacking
 
@@ -903,7 +910,9 @@ Here the @clk_reg@ register is connected to the @clk_wire@ wire.
 
 h3(#problems.ivl.vpi_reset). Vpi::reset
 
-<div class="caution">The @vpi_control@ method was removed in release 3.0.0 (2006-04-23). Please use @Vpi::vpi_control(VpiReset)@ instead.</div>
+<% caution do %>
+The @vpi_control@ method was removed in release 3.0.0 (2006-04-23). Please use @Vpi::vpi_control(VpiReset)@ instead.
+<% end %>
 
 In version 0.8 of Icarus Verilog, the @vpi_control(vpiReset)@ VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.
 

data/doc/manual.html

@@ -75,32 +75,33 @@
 		<li>5.1.2 <a href="#usage.vpi.callbacks">Callbacks</a></li>
 	</ul>
 	</li>
-		<li>5.2 <a href="#usage.debugger">Debugging</a>
+		<li>5.2 <a href="#usage.prototyping">Prototyping</a></li>
+		<li>5.3 <a href="#usage.debugger">Debugging</a>
 	<ul>
-	<li>5.2.1 <a href="#usage.debugger.init">Advanced initialization</a></li>
+	<li>5.3.1 <a href="#usage.debugger.init">Advanced initialization</a></li>
 	</ul>
 	</li>
-		<li>5.3 <a href="#usage.test-runner">Test runner</a>
+		<li>5.4 <a href="#usage.test-runner">Test runner</a>
 	<ul>
-	<li>5.3.1 <a href="#usage.test-runner.env-vars">Environment variables</a></li>
+	<li>5.4.1 <a href="#usage.test-runner.env-vars">Environment variables</a></li>
 	</ul>
 	</li>
-		<li>5.4 <a href="#usage.examples">Sample tests</a></li>
-		<li>5.5 <a href="#usage.tools">Tools</a>
+		<li>5.5 <a href="#usage.examples">Sample tests</a></li>
+		<li>5.6 <a href="#usage.tools">Tools</a>
 	<ul>
-	<li>5.5.1 <a href="#usage.tools.generate-test">Automated test generation</a></li>
-		<li>5.5.2 <a href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li>
+	<li>5.6.1 <a href="#usage.tools.generate-test">Automated test generation</a></li>
+		<li>5.6.2 <a href="#usage.tools.verilog-ruby-conv">Verilog to Ruby conversion</a></li>
 	</ul>
 	</li>
-		<li>5.6 <a href="#usage.tutorial">Tutorial</a>
-	<ul>
-	<li>5.6.1 <a href="#usage.tutorial.declare-design">Start with a design</a></li>
-		<li>5.6.2 <a href="#usage.tutorial.generate-test">Generate a test</a></li>
-		<li>5.6.3 <a href="#usage.tutorial.specification">Specify your expectations</a></li>
-		<li>5.6.4 <a href="#usage.tutorial.implement-proto">Implement the prototype</a></li>
-		<li>5.6.5 <a href="#usage.tutorial.test-proto">Verify the prototype</a></li>
-		<li>5.6.6 <a href="#usage.tutorial.implement-design">Implement the design</a></li>
-		<li>5.6.7 <a href="#usage.tutorial.test-design">Verify the design</a></li>
+		<li>5.7 <a href="#usage.tutorial">Tutorial</a>
+	<ul>
+	<li>5.7.1 <a href="#usage.tutorial.declare-design">Start with a design</a></li>
+		<li>5.7.2 <a href="#usage.tutorial.generate-test">Generate a test</a></li>
+		<li>5.7.3 <a href="#usage.tutorial.specification">Specify your expectations</a></li>
+		<li>5.7.4 <a href="#usage.tutorial.implement-proto">Implement the prototype</a></li>
+		<li>5.7.5 <a href="#usage.tutorial.test-proto">Verify the prototype</a></li>
+		<li>5.7.6 <a href="#usage.tutorial.implement-design">Implement the design</a></li>
+		<li>5.7.7 <a href="#usage.tutorial.test-design">Verify the design</a></li>
 	</ul>
 	</li>
 	</ul>
@@ -179,7 +180,11 @@
 		<li><a href="#important3">Before we continue&#8230;</a></li>
 		<li><a href="#important4">Before we continue&#8230;</a></li>
 	</ol>
-                                                                    <h1>Formals</h1>
+                                        <h2>Cautions</h2>
+            <ol>
+	<li><a href="#caution1">caution1</a></li>
+	</ol>
+                                                  <h1>Formals</h1>
 
                               <h2>Figures</h2>
             <ol>
@@ -218,7 +223,7 @@
       <h1 id="anchor4">1 &nbsp; Ruby-VPI user manual</h1>
 
 
-	<p>This manual was last updated on Sat Dec 30 19:26:28 <span class="caps">PST 2006</span>.</p>
+	<p>This manual was last updated on Sat Jan 13 16:42:19 <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>
@@ -255,7 +260,7 @@
 
 
 	<ul>
-	<li>Supports the <em>entire</em> <a href=":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
+	<li>Supports the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
 	</ul>
 
 
@@ -762,7 +767,7 @@ $ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
 	<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>
 
 
-	<p>Note that this capitalization rule does <strong>not</strong> apply to <span class="caps">VPI</span> functions; their names remain <em>unchanged</em> in Ruby.</p>
+	<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 &nbsp; Handles</h3>
@@ -824,7 +829,7 @@ reset_signal = counter_module.reset <span style="color:#888"># &lt;== shortcut!<
 	<h4 id="anchor10">5.1.1.2 &nbsp; Accessing a handle&#8217;s properties</h4>
 
 
-	<p>To access a handle&#8217;s properties, invoke the proprty name, using the following format, as a method on the handle. <a href="#ex..properties">the example named &ldquo;Examples of accessing a handle&#8217;s properties&rdquo;</a> shows how this naming format is used.</p>
+	<p>To access a handle&#8217;s properties, invoke the property name, using the following format, as a method on the handle. <a href="#ex..properties">the example named &ldquo;Examples of accessing a handle&#8217;s properties&rdquo;</a> shows how this naming format is used.</p>
 
 
 <div class="formal">
@@ -1280,22 +1285,22 @@ reset_signal = counter_module.reset <span style="color:#888"># &lt;== shortcut!<
 
 
 <pre class="code">
-cb_time           = <span style="color:#036; font-weight:bold">S_vpi_time</span>.new
-cb_time.type      = <span style="color:#036; font-weight:bold">VpiSimTime</span>
-cb_time.low       = <span style="color:#00D; font-weight:bold">0</span>
-cb_time.high      = <span style="color:#00D; font-weight:bold">0</span>
+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>
 
-cb_value          = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
-cb_value.format   = <span style="color:#036; font-weight:bold">VpiIntVal</span>
+cbValue          = <span style="color:#036; font-weight:bold">S_vpi_value</span>.new
+cbValue.format   = <span style="color:#036; font-weight:bold">VpiIntVal</span>
 
-cb_data           = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
-cb_data.reason    = <span style="color:#036; font-weight:bold">CbValueChange</span>
-cb_data.obj       = <span style="color:#036; font-weight:bold">Counter</span>.count
-cb_data.time      = cb_time
-cb_data.value     = cb_value
-cb_data.index     = <span style="color:#00D; font-weight:bold">0</span>
+cbData           = <span style="color:#036; font-weight:bold">S_cb_data</span>.new
+cbData.reason    = <span style="color:#036; font-weight:bold">CbValueChange</span>
+cbData.obj       = <span style="color:#036; font-weight:bold">Counter</span>.count
+cbData.time      = cbTime
+cbData.value     = cbValue
+cbData.index     = <span style="color:#00D; font-weight:bold">0</span>
 
-cb_handle = vpi_register_cb(cb_data) <span style="color:#080; font-weight:bold">do</span> |data|
+cbHandle = vpi_register_cb(cbData) <span style="color:#080; font-weight:bold">do</span> |data|
 
   time = (data.time.high &lt;&lt; <span style="color:#00D; font-weight:bold">32</span>) | data.time.low
   count = data.value.value.integer
@@ -1418,7 +1423,28 @@ Finished in 0.042328 seconds
 
 </div>
 
-	<h2 id="usage.debugger">5.2 &nbsp; Debugging</h2>
+	<h2 id="usage.prototyping">5.2 &nbsp; Prototyping</h2>
+
+
+	<p>Ruby-VPI enables you to rapidly prototype your designs in Ruby without having to do full-scale implementations in Verilog. This lets you explore and evaluate different design choices quickly.</p>
+
+
+In order 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>
+	</ol>
+
+
+	<p>Once you are satisfied with your prototype, you can proceed to <a href="#usage.tutorial.implement-design">implement your design in Verilog</a>. This process is often a simple translation your Ruby prototype into your Verilog. At the very least, your prototype serves as a reference while you are implementing your Verilog design.</p>
+
+
+	<p>Once your design has been implemented in Verilog, you can use the <em>same</em> specification, which was originally used to verify your prototype, to verify your Verilog design.</p>
+
+
+	<h2 id="usage.debugger">5.3 &nbsp; 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>
@@ -1430,7 +1456,7 @@ Finished in 0.042328 seconds
 	</ol>
 
 
-	<h3 id="usage.debugger.init">5.2.1 &nbsp; Advanced initialization</h3>
+	<h3 id="usage.debugger.init">5.3.1 &nbsp; Advanced initialization</h3>
 
 
 	<p>By default, Ruby-VPI enables the debugger by invoking the <code class="code"><span style="color:#036; font-weight:bold">Debugger</span>.start</code> method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an <span class="caps">IDE</span> (see <a href="http://www.datanoise.com/articles/category/ruby-debug">the ruby-debug documentation</a> for details), then:</p>
@@ -1442,7 +1468,7 @@ Finished in 0.042328 seconds
 	</ol>
 
 
-	<h2 id="usage.test-runner">5.3 &nbsp; Test runner</h2>
+	<h2 id="usage.test-runner">5.4 &nbsp; Test runner</h2>
 
 
 	<p>A test runner is a file, generated by the <a href="#usage.tools.generate-test">automated test generator</a>, whose name ends with <tt>.rake</tt>. It helps you run generated tests&#8212;you can think of it as a <em>makefile</em> if you are familiar with C programming in a <span class="caps">UNIX</span> environment.</p>
@@ -1497,7 +1523,7 @@ rake vsim     # Simulate with Mentor Modelsim.
 
 </div>
 
-	<h3 id="usage.test-runner.env-vars">5.3.1 &nbsp; Environment variables</h3>
+	<h3 id="usage.test-runner.env-vars">5.4.1 &nbsp; 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>
@@ -1544,19 +1570,19 @@ Here we <em>disable</em> the prototype and enable the code coverage analysis. No
 
 </div>
 
-	<h2 id="usage.examples">5.4 &nbsp; Sample tests</h2>
+	<h2 id="usage.examples">5.5 &nbsp; Sample tests</h2>
 
 
 	<p>The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.</p>
 
 
-	<h2 id="usage.tools">5.5 &nbsp; Tools</h2>
+	<h2 id="usage.tools">5.6 &nbsp; Tools</h2>
 
 
 	<p>The <tt>bin</tt> directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the <tt>--help</tt> option.</p>
 
 
-	<h3 id="usage.tools.generate-test">5.5.1 &nbsp; Automated test generation</h3>
+	<h3 id="usage.tools.generate-test">5.6.1 &nbsp; Automated test generation</h3>
 
 
 	<p>The automated test generator (<strong>generate_test.rb</strong>) generates tests from Verilog 2001 module declarations, as demonstrated <a href="#usage.tutorial.generate-test">in the tutorial</a>. A generated test is composed of the following parts:</p>
@@ -1608,7 +1634,7 @@ kdiff3 --auto --output <span style="background-color:#fff0f0"><span style="color
 
 </div>
 
-	<h3 id="usage.tools.verilog-ruby-conv">5.5.2 &nbsp; Verilog to Ruby conversion</h3>
+	<h3 id="usage.tools.verilog-ruby-conv">5.6.2 &nbsp; Verilog to Ruby conversion</h3>
 
 
 	<p>The <strong>header_to_ruby.rb</strong> tool can be used to convert Verilog header files into Ruby. You can try it by running the <pre>header_to_ruby.rb --help</pre> command.</p>
@@ -1617,7 +1643,7 @@ kdiff3 --auto --output <span style="background-color:#fff0f0"><span style="color
 	<p>By converting Verilog header files into Ruby, your <a href="#glossary.test">test</a> can utilize the same <code class="code"><span style="background-color:#f0fff0"><span style="color:#161">`</span><span style="color:#2B2">define</span></span></code> constants that are used in the Verilog <a href="#glossary.design">design</a>.</p>
 
 
-	<h2 id="usage.tutorial">5.6 &nbsp; Tutorial</h2>
+	<h2 id="usage.tutorial">5.7 &nbsp; Tutorial</h2>
 
 
 	<ol>
@@ -1631,7 +1657,7 @@ kdiff3 --auto --output <span style="background-color:#fff0f0"><span style="color
 	</ol>
 
 
-	<h3 id="usage.tutorial.declare-design">5.6.1 &nbsp; Start with a design</h3>
+	<h3 id="usage.tutorial.declare-design">5.7.1 &nbsp; Start with a design</h3>
 
 
 	<p>First, we need a <a href="#glossary.design">design</a> to verify. In this tutorial, <a href="#fig..counter.v_decl">the example named &ldquo;Declaration of a simple up-counter with synchronous reset&rdquo;</a> will serve as our design. Its interface is composed of the following parts:</p>
@@ -1682,7 +1708,7 @@ endmodule
 
 </div>
 
-	<h3 id="usage.tutorial.generate-test">5.6.2 &nbsp; Generate a test</h3>
+	<h3 id="usage.tutorial.generate-test">5.7.2 &nbsp; Generate a test</h3>
 
 
 	<p>Now that we have a <a href="#glossary.design">design</a> to verify, let us generate a <a href="#glossary.test">test</a> for it using the <a href="#usage.tools.generate-test">automated test generator</a>. This tool allows us to implement our specification in either rSpec, xUnit, or our very own format.</p>
@@ -1762,7 +1788,7 @@ $ generate_test.rb counter.v --xunit --name xunit
 
 </div>
 
-	<h3 id="usage.tutorial.specification">5.6.3 &nbsp; Specify your expectations</h3>
+	<h3 id="usage.tutorial.specification">5.7.3 &nbsp; Specify your expectations</h3>
 
 
 	<p>So far, the test generation tool has created a basic foundation for our <a href="#glossary.test">test</a>. Now we must build upon this foundation by identifying our <a href="#glossary.expectation">expectation</a> of the <a href="#glossary.design">design</a>. That is, how do we expect the design to <em>behave</em> under certain conditions?</p>
@@ -1912,7 +1938,7 @@ context <span style="background-color:#fff0f0"><span style="color:#710">&quot;</
 
 </div>
 
-	<h3 id="usage.tutorial.implement-proto">5.6.4 &nbsp; Implement the prototype</h3>
+	<h3 id="usage.tutorial.implement-proto">5.7.4 &nbsp; Implement the prototype</h3>
 
 
 	<p>Now that we have a <a href="#glossary.specification">specification</a> against which to verify our <a href="#glossary.design">design</a>, let us build a prototype of our design. By doing so, we exercise our specification, experience potential problems that may arise when we later implement our design in Verilog, and gain confidence in our work. The result of this proceess is illustrated by <a href="#fig..counter_proto.rb">the example named &ldquo;Ruby prototype of our Verilog design&rdquo;</a>.</p>
@@ -1925,12 +1951,17 @@ context <span style="background-color:#fff0f0"><span style="color:#710">&quot;</
 	<p class="title">Example 10. Ruby prototype of our Verilog design</p>
 
 
-<pre class="code">
+<pre class="code"><span style="color:#888"># This is a prototype of the design under test.</span>
+
+<span style="color:#888"># When prototyping is enabled, Vpi::advance_time invokes this</span>
+<span style="color:#888"># method instead of transferring control to the Verilog simulator.</span>
 <span style="color:#080; font-weight:bold">def</span> <span style="color:#036; font-weight:bold">Counter</span>.simulate!
-  <span style="color:#080; font-weight:bold">if</span> reset.intVal == <span style="color:#00D; font-weight:bold">1</span>
-    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">if</span> clock.posedge?
+    <span style="color:#080; font-weight:bold">if</span> reset.intVal == <span style="color:#00D; font-weight:bold">1</span>
+      count.intVal = <span style="color:#00D; font-weight:bold">0</span>
+    <span style="color:#080; font-weight:bold">else</span>
+      count.intVal += <span style="color:#00D; font-weight:bold">1</span>
+    <span style="color:#080; font-weight:bold">end</span>
   <span style="color:#080; font-weight:bold">end</span>
 <span style="color:#080; font-weight:bold">end</span>
 </pre>
@@ -1956,12 +1987,15 @@ context <span style="background-color:#fff0f0"><span style="color:#710">&quot;</
 
 </div>
 
-	<h3 id="usage.tutorial.test-proto">5.6.5 &nbsp; Verify the prototype</h3>
+	<h3 id="usage.tutorial.test-proto">5.7.5 &nbsp; Verify the prototype</h3>
 
 
 	<p>Now that we have implemented our prototype, we are ready to verify it against our <a href="#glossary.specification">specification</a> by running the <a href="#glossary.test">test</a>. This process is illustrated by <a href="#fig..test-proto.rspec">the example named &ldquo;Running a test with specification in rSpec format&rdquo;</a> and <a href="#fig..test-proto.unit-test">the example named &ldquo;Running a test with specification in xUnit format&rdquo;</a>.</p>
 
 
+	<p>In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> before running the test, by using your shell&#8217;s <strong>export</strong> or <strong>setenv</strong> command. Finally, the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>, denoted by <em>cver</em>, is used to run the simulation.</p>
+
+
 <div class="formal">
 
 <div class="example" id="fig..test-proto.rspec">
@@ -2014,9 +2048,6 @@ Finished in 0.040668 seconds.
 
 </div>
 
-	<p>In these examples, the <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> environment variable is assigned a non-empty value while running the test so that, instead of our design, our prototype is verified against our specification. You can also assign a value to <code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> before running the test, by using your shell&#8217;s <strong>export</strong> or <strong>setenv</strong> command. Finally, the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>, denoted by <em>cver</em>, is used to run the simulation.</p>
-
-
 <div class="admonition">
 
 <div class="tip" id="tip4">
@@ -2034,7 +2065,7 @@ Finished in 0.040668 seconds.
 
 </div>
 
-	<h3 id="usage.tutorial.implement-design">5.6.6 &nbsp; Implement the design</h3>
+	<h3 id="usage.tutorial.implement-design">5.7.6 &nbsp; Implement the design</h3>
 
 
 	<p>Now that we have implemented and verified our prototype, we are ready to implement our <a href="#glossary.design">design</a>. This is often quite simple because we translate <em>existing</em> code from Ruby (our prototype) into Verilog (our design). The result of this process is illustrated by <a href="#fig..counter.v_impl">the example named &ldquo;Implementation of a simple up-counter with synchronous reset&rdquo;</a>.</p>
@@ -2090,12 +2121,15 @@ endmodule
 
 </div>
 
-	<h3 id="usage.tutorial.test-design">5.6.7 &nbsp; Verify the design</h3>
+	<h3 id="usage.tutorial.test-design">5.7.7 &nbsp; Verify the design</h3>
 
 
 	<p>Now that we have implemented our <a href="#glossary.design">design</a>, we are ready to verify it against our <a href="#glossary.specification">specification</a> by running the <a href="#glossary.test">test</a>. <a href="#fig..test-design.rspec">the example named &ldquo;Running a test with specification in rSpec format&rdquo;</a> and <a href="#fig..test-design.unit-test">the example named &ldquo;Running a test with specification in xUnit format&rdquo;</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&#8217;s <strong>unset</strong> command. Finally, the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>, denoted by <em>cver</em>, is used to run the simulation.</p>
+
+
 <div class="formal">
 
 <div class="example" id="fig..test-design.rspec">
@@ -2144,9 +2178,6 @@ Finished in 0.006766 seconds.
 
 </div>
 
-	<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&#8217;s <strong>unset</strong> command. Finally, the <a href="#setup.reqs"><span class="caps">GPL</span> Cver simulator</a>, denoted by <em>cver</em>, is used to run the simulation.</p>
-
-
 	<h1 id="hacking">6 &nbsp; Hacking</h1>
 
 
@@ -2311,7 +2342,22 @@ endmodule
 	<h3 id="problems.ivl.vpi_reset">7.2.2 &nbsp; Vpi::reset</h3>
 
 
-<div class="caution">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.</div>
+<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>
 

data/doc/readme.html

@@ -74,7 +74,7 @@
 
 </div>
 
-	<h1 id="anchor122">1 &nbsp; Welcome to Ruby-VPI</h1>
+	<h1 id="anchor127">1 &nbsp; Welcome to Ruby-VPI</h1>
 
 
 	<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>
@@ -83,11 +83,11 @@
 	<h2 id="intro.features">1.1 &nbsp; Features</h2>
 
 
-	<h3 id="anchor123">1.1.1 &nbsp; Portable</h3>
+	<h3 id="anchor128">1.1.1 &nbsp; Portable</h3>
 
 
 	<ul>
-	<li>Supports the <em>entire</em> <a href=":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
+	<li>Supports the <em>entire</em> <a href="http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945"><span class="caps">IEEE</span> Std 1364-2005</a> VPI standard.</li>
 	</ul>
 
 
@@ -99,7 +99,7 @@
 	</ul>
 
 
-	<h3 id="anchor124">1.1.2 &nbsp; Agile</h3>
+	<h3 id="anchor129">1.1.2 &nbsp; Agile</h3>
 
 
 	<ul>
@@ -122,7 +122,7 @@
 	</ul>
 
 
-	<h3 id="anchor125">1.1.3 &nbsp; Powerful</h3>
+	<h3 id="anchor130">1.1.3 &nbsp; Powerful</h3>
 
 
 	<ul>
@@ -143,7 +143,7 @@
 	</ul>
 
 
-	<h3 id="anchor126">1.1.4 &nbsp; Free</h3>
+	<h3 id="anchor131">1.1.4 &nbsp; Free</h3>
 
 
 	<ul>