ruby-vpi 12.0.2 → 12.1.0

data/doc/history.yml

@@ -1,3 +1,30 @@
+-
+  Version: 12.1.0
+
+  Date: 2006-12-22
+
+  Summary: |
+    This release adds interactive debugging support, adds new sections to the user manual, and cleanses some internals.
+
+  Notice: |
+    * The <tt>lib/ruby-vpi/rspec.rb</tt> and <tt>lib/ruby-vpi/xx.rb</tt> files has been removed because they are no longer necessary.
+
+    * rSpec 0.7.0 or newer is now required because the sample tests utilize the @should ==@ syntax -- which was introduced in rSpec 0.7.0.
+
+  Detail: |
+    * Test runners now support the @DEBUG@ environment variable, which enables the interactive debugger (ruby-debug) in "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
+    ** The @debugger@ can now be used when @DEBUG@ environment variable is not activated.
+    ** ruby-debug is now a gem dependency for Ruby-VPI.
+
+    * Status messages, which are shown during initialization of a Ruby bench, now appear in simulators' log files.
+
+    * Added documentation about "test runners":manual.html#usage.test-runner and the "interactive debugger":manual.html#usage.debugger in the user manual.
+
+    * Added a <tt>README</tt> file with hint about where to find the user manual.
+
+    * Removed code that wasn't being used, according to code coverage analysis, from the pipelined ALU sample.
+
+
 -
   Version: 12.0.2
 

data/doc/manual.doc

@@ -242,6 +242,7 @@ The following software is necessary in order to use Ruby-VPI.
 Write a "support request":http://rubyforge.org/tracker/?group_id=1339 for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!
 <% end %>
 
+
 * *make*
   - any distribution should be acceptable.
 
@@ -275,7 +276,7 @@ An _interactive_ text merging tool can greatly simplify the process of transferr
 
 h2(#setup.installation). Installation
 
-Once you have satisfied the "necessary requirements":#setup.reqs, you can install Ruby-VPI by running the <pre>gem install 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 "gems" subdirectory which contains the Ruby-VPI installation, as illustrated below.
+Once you have satisfied the "necessary requirements":#setup.reqs, 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.
 
 <pre>
 $ gem env gemdir
@@ -584,6 +585,18 @@ Finished in 0.006766 seconds.
 
 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.
 
+
+h2(#usage.test-runner). Test runner
+
+A test runner is a file, generated by the "automated test generator":#usage.tools.generate-test, whose name ends with <tt>.rake</tt>. It helps you run generated tests -- you can think of it as a _makefile_ if you are familiar with C programming in a UNIX environment.
+
+<% example "Seeing what a test runner can do" do %>
+When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f some_test_runner.rake
+
+<%= `rake -f ../samp/counter/counter_rspec_runner.rake` %></pre>
+<% end %>
+
 <% tip "Running multiple tests at once." do %>
 Create a file named <tt>Rakefile</tt> containing the following line.
 
@@ -593,9 +606,58 @@ Now you can invoke all test runners in the current directory simply by executing
 <% end %>
 
 
-h2(#usage.examples). Examples
+h3(#usage.test-runner.env-vars). Environment variables
+
+Test runners support the following _environment_ variables, which allow you to easily change the behavior of the test runner.
+
+* @COVERAGE@ enables code coverage analysis and generation of code coverage reports.
+* @DEBUG@ enables the "interactive debugger":#usage.debugger in its "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
+* @PROTOTYPE@ enables the Ruby prototype for the design under test.
+
+To activate these variables, simply assign a non-empty value to them. For example, @DEBUG=1@ and @DEBUG=yes@ and @DEBUG=foo_bar_baz@ all activate the @DEBUG@ variable.
+
+To deactivate these variables, simply assign an _empty_ value to them, *unset* them in your shell, or do not specify them as command-line arguments to rake. For example, both @DEBUG=@ dectivates the @DEBUG@ variable.
+
+In addition, you can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
+$ DEBUG=1
+$ export DEBUG
+$ rake
+</pre> in Bourne shell or <pre>
+% setenv DEBUG 1
+% rake
+</pre> in C shell.
+
+<% example "Running a test with environment variables" do %>
+
+Here we enable the prototype and code coverage analysis:
+<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+
+Here we _disable_ the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
+<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+<% end %>
+
+
+h2(#usage.debugger). Interactive debugger
+
+The "ruby-debug project":http://www.datanoise.com/articles/category/ruby-debug serves as the interactive debugger for Ruby-VPI.
+
+# Enable the debugger by activating the @DEBUG@ environment variable (see <xref #usage.test-runner> for details).
+# Put the @debugger@ 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.
+
+
+h3(#usage.debugger.init). Advanced initialization
+
+By default, Ruby-VPI enables the debugger by invoking the @Debugger.start@ method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see "the ruby-debug documentation":http://www.datanoise.com/articles/category/ruby-debug for details), then:
+
+# Deactivate the @DEBUG@ environment variable.
+# Put your own code, which initializes the debugger, above the @RubyVpi.init_bench@ line in your generated <tt>spec.rb</tt> file.
+
+
+
+h2(#usage.examples). Sample tests
 
-The <tt>samp</tt> directory 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.
+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.
 
 
 h1(#hacking). Hacking

data/doc/manual.html

@@ -90,7 +90,17 @@
 		<li><a href="#usage.tutorial.test-design">Verify the design</a></li>
 	</ul>
 	</li>
-		<li><a href="#usage.examples">Examples</a></li>
+		<li><a href="#usage.test-runner">Test runner</a>
+	<ul>
+	<li><a href="#usage.test-runner.env-vars">Environment variables</a></li>
+	</ul>
+	</li>
+		<li><a href="#usage.debugger">Interactive debugger</a>
+	<ul>
+	<li><a href="#usage.debugger.init">Advanced initialization</a></li>
+	</ul>
+	</li>
+		<li><a href="#usage.examples">Sample tests</a></li>
 	</ul>
 	</li>
 		<li><a href="#hacking">Hacking</a>
@@ -194,6 +204,8 @@
 		<li><a href="#fig..counter.v_impl">Implementation of a simple up-counter with synchronous reset</a></li>
 		<li><a href="#fig..test-design.rspec">Running a test with specification in rSpec format</a></li>
 		<li><a href="#fig..test-design.unit-test">Running a test with specification in xUnit format</a></li>
+		<li><a href="#example13">Seeing what a test runner can do</a></li>
+		<li><a href="#example14">Running a test with environment variables</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>
@@ -207,7 +219,7 @@
 	<p>Suraj N. Kurapati</p>
 
 
-	<p>Mon Dec 18 15:23:49 <span class="caps">PST 2006</span></p>
+	<p>Fri Dec 22 21:43:06 <span class="caps">PST 2006</span></p>
 
 
 </div>
@@ -1000,7 +1012,7 @@ In <a href="#fig..organization.detail">the figure named &ldquo;Detailed organiza
 		<li><tt>ext</tt> contains source code, written in the C language, for the <a href="#background.org">core of Ruby-VPI</a>.</li>
 		<li><tt>lib</tt> contains Ruby libraries provided by Ruby-VPI.</li>
 		<li><tt>bin</tt> contains various tools. See <a href="#usage.tools">the section named &ldquo;Tools&rdquo;</a> for more information.</li>
-		<li><tt>samp</tt> contains example tests. See <a href="#usage.examples">the section named &ldquo;Examples&rdquo;</a> for more information.</li>
+		<li><tt>samp</tt> contains example tests. See <a href="#usage.examples">the section named &ldquo;Sample tests&rdquo;</a> for more information.</li>
 	</ul>
 
 
@@ -1042,8 +1054,12 @@ In <a href="#fig..organization.detail">the figure named &ldquo;Detailed organiza
 </div>
 
 </div>
-* <strong>make</strong>
-  &#8211; any distribution should be acceptable.
+
+	<ul>
+	<li><strong>make</strong>
+  &#8211; any distribution should be acceptable.</li>
+	</ul>
+
 
 	<ul>
 	<li>C compiler
@@ -1091,7 +1107,7 @@ An <em>interactive</em> text merging tool can greatly simplify the process of tr
 	<h2 id="setup.installation">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 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 &#8220;gems&#8221; subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
+	<p>Once you have satisfied the <a href="#setup.reqs">necessary requirements</a>, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.</p>
 
 
 <pre>
@@ -1763,6 +1779,35 @@ Finished in 0.006766 seconds.
 </div>
 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.
 
+	<h2 id="usage.test-runner">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>
+
+
+<div class="formal">
+
+<div class="example" id="example13">
+
+	<p class="title">Example 13. Seeing what a test runner can do</p>
+
+
+When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f some_test_runner.rake
+
+(in /home/sun/src/ruby-vpi/doc)
+rake clean    # Remove any temporary products.
+rake clobber  # Remove any generated file.
+rake cver     # Simulate with GPL Cver.
+rake default  # Show a list of available tasks.
+rake ivl      # Simulate with Icarus Verilog.
+rake vcs      # Simulate with Synopsys VCS.
+rake vsim     # Simulate with Mentor Modelsim.
+</pre>
+
+</div>
+
+</div>
 <div class="admonition">
 
 <div class="tip" id="tip4">
@@ -1788,10 +1833,81 @@ In these examples, the <code class="code"><span style="color:#036; font-weight:b
 
 </div>
 
-	<h2 id="usage.examples">Examples</h2>
+	<h3 id="usage.test-runner.env-vars">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">DEBUG</span></code> enables the <a href="#usage.debugger">interactive debugger</a> in its <a href="http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging">post-mortem debugging mode</a>.</li>
+		<li><code class="code"><span style="color:#036; font-weight:bold">PROTOTYPE</span></code> enables the Ruby prototype for the design under test.</li>
+	</ul>
+
+
+	<p>To activate these variables, simply assign a non-empty value to them. For example, <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=<span style="color:#00D; font-weight:bold">1</span></code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=yes</code> and <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=foo_bar_baz</code> all activate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+
+
+	<p>To deactivate these variables, simply assign an <em>empty</em> value to them, <strong>unset</strong> them in your shell, or do not specify them as command-line arguments to rake. For example, both <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span>=</code> dectivates the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> variable.</p>
+
+
+	<p>In addition, you can specify variable assignments as arguments to the <strong>rake</strong> command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
+$ DEBUG=1
+$ export DEBUG
+$ rake
+</pre> in Bourne shell or <pre>
+% setenv DEBUG 1
+% rake
+</pre> in C shell.</p>
+
+
+<div class="formal">
+
+<div class="example" id="example14">
+
+	<p class="title">Example 14. Running a test with environment variables</p>
+
+
+Here we enable the prototype and code coverage analysis:
+<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+
+Here we <em>disable</em> the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
+<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+
+</div>
+
+</div>
+
+	<h2 id="usage.debugger">Interactive debugger</h2>
+
+
+	<p>The <a href="http://www.datanoise.com/articles/category/ruby-debug">ruby-debug project</a> serves as the interactive debugger for Ruby-VPI.</p>
+
+
+	<ol>
+	<li>Enable the debugger by activating the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable (see <a href="#usage.test-runner">the section named &ldquo;Test runner&rdquo;</a> for details).</li>
+		<li>Put the <code class="code">debugger</code> command in your code&#8212;anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.</li>
+	</ol>
+
+
+	<h3 id="usage.debugger.init">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>
+
+
+	<ol>
+	<li>Deactivate the <code class="code"><span style="color:#036; font-weight:bold">DEBUG</span></code> environment variable.</li>
+		<li>Put your own code, which initializes the debugger, above the <code class="code"><span style="color:#036; font-weight:bold">RubyVpi</span>.init_bench</code> line in your generated <tt>spec.rb</tt> file.</li>
+	</ol>
+
+
+	<h2 id="usage.examples">Sample tests</h2>
 
 
-	<p>The <tt>samp</tt> directory 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.</p>
+	<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>
 
 
 	<h1 id="hacking">Hacking</h1>
@@ -1883,7 +1999,7 @@ If your specification employs Ruby&#8217;s unit testing framework, then you will
 
 <div class="example" id="ex..TestFoo">
 
-	<p class="title">Example 13. Part of a bench which instantiates a Verilog design</p>
+	<p class="title">Example 15. Part of a bench which instantiates a Verilog design</p>
 
 
 <pre class="code" lang="verilog">
@@ -1913,7 +2029,7 @@ endmodule
 
 <div class="example" id="ex..TestFoo_bad">
 
-	<p class="title">Example 14. Bad design with unconnected registers</p>
+	<p class="title">Example 16. Bad design with unconnected registers</p>
 
 
 <pre class="code" lang="verilog">
@@ -1932,7 +2048,7 @@ endmodule
 
 <div class="example" id="ex..TestFoo_fix">
 
-	<p class="title">Example 15. Fixed design with wired registers</p>
+	<p class="title">Example 17. Fixed design with wired registers</p>
 
 
 <pre class="code" lang="verilog">

data/doc/readme.html

@@ -65,7 +65,7 @@
 
 </div>
 
-	<h1 id="anchor105">Welcome to Ruby-VPI
+	<h1 id="anchor108">Welcome to Ruby-VPI
 <a type="application/rss+xml" href="http://ruby-vpi.rubyforge.org/doc/rss.xml"><img src="images/feed-icon.png" title="RSS feed for this project." alt="RSS feed for this project." /></a></h1>
 
 

data/doc/rss.xml

@@ -4,6 +4,13 @@
   <title>Ruby-VPI</title>
   <link>http://ruby-vpi.rubyforge.org</link>
   <description>Ruby-VPI is a Ruby interface to IEEE 1364-2005 Verilog VPI. It lets you create complex Verilog test benches easily and wholly in Ruby.</description>
+  <item>
+    <title>Version 12.1.0 released</title>
+    <link>http://ruby-vpi.rubyforge.org/doc/history.html#12.1.0</link>
+    <guid>http://ruby-vpi.rubyforge.org/doc/history.html#12.1.0</guid>
+    <description>&lt;p&gt;This release adds interactive debugging support, adds new sections to the user manual, and cleanses some internals.&lt;/p&gt;</description>
+    <pubDate>Fri, 22 Dec 2006 00:00:00 PST</pubDate>
+  </item>
   <item>
     <title>Version 12.0.2 released</title>
     <link>http://ruby-vpi.rubyforge.org/doc/history.html#12.0.2</link>

data/index.html

@@ -1 +1,2 @@
 <META HTTP-EQUIV=REFRESH CONTENT="0; URL=./doc/readme.html">
+This page will redirect you to: <tt>./doc/readme.html</tt>.

data/lib/ruby-vpi.rb

@@ -33,18 +33,15 @@ module RubyVpi
       raise 'Unable to determine name of test.'
     end
 
-    # set up the VPI utility layer
-      require 'ruby-vpi/vpi'
-
-      Object.class_eval do
-        include Vpi
-      end
+    useDebugger = !(ENV['DEBUG'] || '').empty?
+    useCoverage = !(ENV['COVERAGE'] || '').empty?
+    usePrototype = !(ENV['PROTOTYPE'] || '').empty?
 
     # service the $ruby_init() task
-      relay_verilog
+      Vpi::relay_verilog
 
     # set up code coverage analysis
-      unless (ENV['COVERAGE'] || '').empty?
+      if useCoverage
         require 'ruby-vpi/rcov'
 
         RubyVpi.with_coverage_analysis do |a|
@@ -53,6 +50,8 @@ module RubyVpi
             Rcov::HTMLCoverage.new(:destdir => "#{testName}_coverage")
           ]
         end
+
+        Vpi::vpi_printf "#{Config::PROJECT_NAME}: coverage analysis is enabled for test #{testName.inspect}\n"
       end
 
     # set up the specification library
@@ -62,13 +61,39 @@ module RubyVpi
 
         when :rSpec
           ARGV.concat %w[-f s]
-          require 'ruby-vpi/rspec'
+          require 'spec'
 
         when :tSpec
           ARGV << '-rs'
           require 'test/spec'
       end
 
+    # set up the interactive debugger
+      if useDebugger
+        require 'ruby-debug'
+
+        Debugger.start
+        Debugger.post_mortem
+
+        Vpi::vpi_printf "#{Config::PROJECT_NAME}: debugger is enabled for test #{testName.inspect}\n"
+      end
+
+      # suppress undefined method errors when debugger is not enabled
+        unless Kernel.respond_to? :debugger
+          Kernel.class_eval do
+            define_method :debugger do
+              # this is a dummy method!
+            end
+          end
+        end
+
+    # set up the VPI utility layer
+      require 'ruby-vpi/vpi'
+
+      Object.class_eval do
+        include Vpi
+      end
+
     # load the design under test
       unless design = vpi_handle_by_name("#{testName}_bench", nil)
         raise "Verilog bench for test #{testName.inspect} is inaccessible."
@@ -78,7 +103,7 @@ module RubyVpi
       require "#{testName}_design.rb"
 
     # load the design's prototype
-      unless (ENV['PROTOTYPE'] || '').empty?
+      if usePrototype
         require "#{testName}_proto.rb"
 
         Vpi.class_eval do
@@ -87,7 +112,7 @@ module RubyVpi
           end
         end
 
-        puts "#{Config::PROJECT_NAME}: prototype has been enabled for test #{testName.inspect}"
+        Vpi::vpi_printf "#{Config::PROJECT_NAME}: prototype is enabled for test #{testName.inspect}\n"
       end
 
     # load the design's specification