ruby-vpi 9.0.0 → 10.0.0

data/doc/manual.txt

@@ -16,8 +16,9 @@ in the section entitled "GNU Free Documentation License".
 
 Abstract
 
-This manual explains how to use Ruby-VPI. You can find the newest version of
-this manual at the Ruby-VPI website.
+This manual explains how to use Ruby-VPI. A plain-text version of this manual
+is also available. Finally, you can find the newest version of this manual at
+the Ruby-VPI website.
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -45,20 +46,25 @@ Table of Contents
         Initialization
         Execution
 
-3. Usage
+3. Setup
 
     Requirements
-    Recommendations
-    Installation and maintenance
+
+        Recommendations
+
+    Installation
 
         Installing on Windows
 
+    Maintenance
+
+4. Usage
+
     Tools
 
         Automated test generation
         Verilog to Ruby conversion
 
-    Examples
     Tutorial
 
         Start with a design
@@ -69,7 +75,9 @@ Table of Contents
         Implement the design
         Verify the design
 
-4. Known problems
+    Examples
+
+5. Known problems
 
     Ruby
 
@@ -107,17 +115,17 @@ List of Figures
 2.2. Detailed organization of a test
 2.3. Initialization of a test
 2.4. Execution of a test
-3.1. Declaration of a simple up-counter with synchronous reset
-3.2. Generating a test with specification in rSpec format
-3.3. Generating a test with specification in xUnit format
-3.4. Specification implemented in rSpec format
-3.5. Specification implemented in xUnit format
-3.6. Ruby prototype of our Verilog design
-3.7. Running a test with specification in rSpec format
-3.8. Running a test with specification in xUnit format
-3.9. Implementation of a simple up-counter with synchronous reset
-3.10. Running a test with specification in rSpec format
-3.11. Running a test with specification in xUnit format
+4.1. Declaration of a simple up-counter with synchronous reset
+4.2. Generating a test with specification in rSpec format
+4.3. Generating a test with specification in xUnit format
+4.4. Specification implemented in rSpec format
+4.5. Specification implemented in xUnit format
+4.6. Ruby prototype of our Verilog design
+4.7. Running a test with specification in rSpec format
+4.8. Running a test with specification in xUnit format
+4.9. Implementation of a simple up-counter with synchronous reset
+4.10. Running a test with specification in rSpec format
+4.11. Running a test with specification in xUnit format
 
 List of Tables
 
@@ -127,9 +135,9 @@ List of Tables
 List of Examples
 
 2.1. Accessing a handle's VPI properties
-4.1. Part of a bench which instantiates a Verilog design
-4.2. Bad design with unconnected registers
-4.3. Fixed design with wired registers
+5.1. Part of a bench which instantiates a Verilog design
+5.2. Bad design with unconnected registers
+5.3. Fixed design with wired registers
 
 Chapter 1. Introduction
 
@@ -356,7 +364,17 @@ VPI utility layer
 
 From a user's perspective, the VPI utility layer greatly enhances the ability
 to interact with handles. One simply invokes a handle's methods, which are
-carefully named in the following manner, to access its VPI properties.
+carefully named in the following manner, to access either (1) its children or
+(2) its VPI properties.
+
+The children of a handle are simply the handles that are immediately contained
+within it in. For example, suppose that you had a Verilog module that contains
+some registers. The children, of a handle to the module, would be handles to
+the registers.
+
+In the event that a child handle has the same name as a VPI property, the child
+is given priority. However, you can always access VPI properties explicitly via
+the get_value and put_value methods.
 
 Table 2.1. Naming format for accessing a handle's VPI properties
 
@@ -560,31 +578,19 @@ Procedure 2.2. Execution of a test
  3. When the Ruby interpreter invokes the Vpi::relay_verilog method, it is
     paused and the Verilog simulator is given control.
 
-Chapter 3. Usage
+Chapter 3. Setup
 
 Table of Contents
 
 Requirements
-Recommendations
-Installation and maintenance
 
-    Installing on Windows
-
-Tools
+    Recommendations
 
-    Automated test generation
-    Verilog to Ruby conversion
+Installation
 
-Examples
-Tutorial
+    Installing on Windows
 
-    Start with a design
-    Generate a test
-    Specify your expectations
-    Implement the prototype
-    Verify the prototype
-    Implement the design
-    Verify the design
+Maintenance
 
 Requirements
 
@@ -644,13 +650,9 @@ Text merging tool
 
     An interactive 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 automated test generator.
-    Below are a list of popular text merging tools.
-
-    imediff2
-
-        A textual, fullscreen two-way merging tool, which works in a terminal.
-        Useful when working remotely via SSH.
+    tools are especially beneficial when using the automated test generator. A
+    handful of the currently available open-source text merging tools are
+    listed below.
 
     kdiff3
 
@@ -669,7 +671,12 @@ Text merging tool
 
         A graphical, three-way merging tool.
 
-Installation and maintenance
+    imediff2
+
+        A textual, fullscreen two-way merging tool. This tool is useful when
+        you are working remotely via SSH.
+
+Installation
 
 Once you have satisfied the necessary requirements, you can install Ruby-VPI by
 running the command gem install ruby-vpi. RubyGems will install Ruby-VPI into
@@ -683,11 +690,6 @@ $ gem env gemdir
 $ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi-*
 /usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
 
-You can uninstall Ruby-VPI by running the command gem uninstall ruby-vpi.
-Furthermore, you can upgrade to the latest release of Ruby-VPI by running the
-command gem update ruby-vpi. Finally, you can learn more about using and
-manipulating RubyGems in the RubyGems user manual.
-
 Installing on Windows
 
  1. Install Cygwin, the Linux-like environment for Windows.
@@ -700,20 +702,61 @@ Installing on Windows
     x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' > /dev/null && echo $x;
     done in Cygwin.
 
-    If you are using Mentor Modelsim, the desired object file can be found at a
-    path similar to C:\Modeltech\win32\libvsim.dll.
+    [Tip] Tip
+          If you are using Mentor Modelsim, the desired object file can be
+          found at a path similar to C:\Modeltech\win32\libvsim.dll.
 
-    If you are using GPL Cver, the desired object file can be found at a path
-    similar to C:\gplcver\objs\v_vpi.o.
+    [Tip] Tip
+          If you are using GPL Cver, the desired object file can be found at a
+          path similar to C:\gplcver\objs\v_vpi.o.
 
  4. Assign the path of the object file (determined in the previous step) to the
     LDFLAGS environment variable. For example, if the object file's path is /
-    life/long/journey, then you would run the command export LDFLAGS=/life/long
-    /journey in Cygwin.
+    foo/bar/vpi.so, then you would run the command export LDFLAGS=/foo/bar/
+    vpi.so in Cygwin.
 
  5. You may now install Ruby-VPI by running the command gem install ruby-vpi in
     Cygwin.
 
+Maintenance
+
+You can uninstall Ruby-VPI by running the command gem uninstall ruby-vpi.
+Furthermore, you can upgrade to the latest release of Ruby-VPI by running the
+command gem update ruby-vpi. Finally, you can learn more about using and
+manipulating RubyGems in the RubyGems user manual.
+
+
+━━━━━━━━━━━━━━
+
+^[1] Because Ruby-VPI makes use of the VPI C-language interface, it links to
+symbols whose names begin with _vpi. It is possible for these symbols to be
+undefined when Ruby-VPI is compiled under GNU/Linux and similar operating
+systems. In contrast, one cannot compile a shared object file with references
+to undefined symbols under Windows. Thus, we must find a Verilog simulator's
+shared object file, which contains definitions of all VPI symbols, and give
+this file to the linker when compiling Ruby-VPI.
+
+Chapter 4. Usage
+
+Table of Contents
+
+Tools
+
+    Automated test generation
+    Verilog to Ruby conversion
+
+Tutorial
+
+    Start with a design
+    Generate a test
+    Specify your expectations
+    Implement the prototype
+    Verify the prototype
+    Implement the design
+    Verify the design
+
+Examples
+
 Tools
 
 The bin directory contains various utilities which ease the process of writing
@@ -722,28 +765,61 @@ option.
 
 Automated test generation
 
-The generate_test.rb tool can be used to automatically generate tests from
-Verilog 2001 module declarations (see the section called “Generate a test”).
-You can try it by running the command generate_test.rb --help.
+The automated test generator (generate_test.rb) generates tests from Verilog
+2001 module declarations, as demonstrated in the section called “Generate a
+test”. A generated test is composed of the following parts:
 
-Verilog to Ruby conversion
+Runner
 
-The header_to_ruby.rb tool can be used to convert Verilog header files into
-Ruby. You can try it by running the command header_to_ruby.rb --help.
+    Written in Rake, this file builds and runs the test.
 
-Examples
+Bench
 
-The samp directory contains several example tests which illustrate how Ruby-VPI
-can be used. Each example has an associated Rakefile which simplifies the
-process of running it. Therefore, simply navigate into an example directory and
-run the command rake to get started.
+    Written in Verilog and Ruby, these files define the testing environment.
 
-Also, some example specifications make use of BDD through the rSpec library.
-See the the section called “Methodology” for a discussion of rSpec.
+Design
+
+    Written in Ruby, this file provides an interface to the design being
+    verified.
+
+Prototype
+
+    Written in Ruby, this file defines a prototype of the design being
+    verified.
+
+Specification
+
+    Written in Ruby, this file verifies the design.
+
+The reason for dividing a single test into these parts is mainly to decouple
+the design from the specification. This allows you to focus on writing the
+specification while the remainder is automatically generated by the tool. For
+example, when the interface of a Verilog module changes, you would simply
+re-run this tool and incorporate those changes (using a text merging tool) into
+the test without diverting your focus from the specification.
+
+[Tip] Using kdiff3 with the automated test generator
+      Create a file named merge2 with the content below, make it executable,
+      and put it somewhere accessible by your PATH environment variable. Next,
+      update the MERGER environment variable by executing export MERGER=merge2.
+
+      #!/bin/sh
+      # args: old file, new file
+      kdiff3 --auto --merge --output "$2" "$@" 2>/dev/null
+
+      From now on, kdiff3 will be invoked to help you transfer your changes
+      between generated files. When you are finished transferring changes,
+      simply issue the "save the file" command and terminate kdiff3. Or, if you
+      do not want to transfer any changes, simply terminate kdiff3.
+
+Verilog to Ruby conversion
+
+The header_to_ruby.rb tool can be used to convert Verilog header files into
+Ruby. You can try it by running the command header_to_ruby.rb --help.
 
 Tutorial
 
-Procedure 3.2. Typical way of using Ruby-VPI
+Procedure 4.1. Typical way of using Ruby-VPI
 
  1. Declare the design, which is a Verilog module, using Verilog 2001 syntax.
 
@@ -762,7 +838,7 @@ Procedure 3.2. Typical way of using Ruby-VPI
 
 Start with a design
 
-First, we need a Design to verify. In this tutorial, Figure 3.1, “Declaration
+First, we need a Design to verify. In this tutorial, Figure 4.1, “Declaration
 of a simple up-counter with synchronous reset” will serve as our design. Its
 interface is composed of the following parts:
 
@@ -783,11 +859,7 @@ count
 
     This register contains the counter's value.
 
-[Important] Before we continue…
-            Save the source code shown in Figure 3.1, “Declaration of a simple
-            up-counter with synchronous reset” into a file named counter.v.
-
-Figure 3.1. Declaration of a simple up-counter with synchronous reset
+Figure 4.1. Declaration of a simple up-counter with synchronous reset
 
 module counter #(parameter Size = 5) (
   input clock,
@@ -796,54 +868,25 @@ module counter #(parameter Size = 5) (
 );
 endmodule
 
+[Important] Before we continue…
+            Save the source code shown in Figure 4.1, “Declaration of a simple
+            up-counter with synchronous reset” into a file named counter.v.
+
 Generate a test
 
 Now that we have a Design to verify, let us generate a Test for it using the
-automated test generator tool. This tool allows us to implement our
-Specification in either rSpec, xUnit, or our very own format. Each format
-represents a different software development methodology: rSpec represents BDD,
-xUnit represents TDD, and our own format can represent another methodology.
-
-[Note] Note
-       In this tutorial, you will see how specifications are implemented in
-       both rSpec and xUnit formats.
+automated test generator. This tool allows us to implement our Specification in
+either rSpec, xUnit, or our very own format. Each format represents a different
+software development methodology: rSpec represents BDD, xUnit represents TDD,
+and our own format can represent another methodology. Both rSpec and xUnit are
+presented in this tutorial.
 
 Once we have decided how we want to implement our specification, we can proceed
-to generate a test for our design. Figure 3.2, “Generating a test with
-specification in rSpec format” and Figure 3.3, “Generating a test with
-specification in xUnit format” illustrate this process. Here, the test
-generation tool produces a test composed of the following parts:
-
-Runner
-
-    Written in Rake, this file builds and runs the test.
-
-Bench
-
-    Written in Verilog and Ruby, these files define the testing environment.
-
-Design
-
-    Written in Ruby, this file provides an interface to the design being
-    verified.
-
-Prototype
-
-    Written in Ruby, this file defines a prototype of the design being
-    verified.
-
-Specification
-
-    Written in Ruby, this file verifies the design.
-
-The reason for dividing a single test into these parts is mainly to decouple
-the design from the specification. This allows you to focus on writing the
-specification while the remainder is automatically generated by the tool. For
-example, when the interface of a Verilog module changes, you would simply
-re-run this tool and incorporate those changes into the test without diverting
-your focus from the specification.
+to generate a test for our design. Figure 4.2, “Generating a test with
+specification in rSpec format” and Figure 4.3, “Generating a test with
+specification in xUnit format” illustrate this process.
 
-Figure 3.2. Generating a test with specification in rSpec format
+Figure 4.2. Generating a test with specification in rSpec format
 
 $ generate_test.rb counter.v --rspec --name rspec
 
@@ -859,7 +902,7 @@ $ generate_test.rb counter.v --rspec --name rspec
   create  counter_rspec_spec.rb
 
 
-Figure 3.3. Generating a test with specification in xUnit format
+Figure 4.3. Generating a test with specification in xUnit format
 
 $ generate_test.rb counter.v --xunit --name xunit
 
@@ -892,51 +935,31 @@ The following is a reasonable set of expectations for our simple counter:
   ● A counter with the maximum value should overflow upon increment.
 
 Now that we have identified a set of expectations for our design, we are ready
-to implement them in our specification. Figure 3.4, “Specification implemented
-in rSpec format” and Figure 3.5, “Specification implemented in xUnit format”
+to implement them in our specification. Figure 4.4, “Specification implemented
+in rSpec format” and Figure 4.5, “Specification implemented in xUnit format”
 illustrate this process. Note the striking similarities between our
 expectations and their implementation.
 
-[Important] Before we continue…
-              ● Append the following code to the files named
-                counter_rspec_design.rb and counter_xunit_design.rb.
+Figure 4.4. Specification implemented in rSpec format
 
-                class Counter
-                  def reset!
-                    @reset.intVal = 1
-                    relay_verilog # advance the clock
-                    @reset.intVal = 0
-                  end
-                end
-
-              ● Replace the contents of the file named counter_rspec_spec.rb
-                with the source code shown in Figure 3.4, “Specification
-                implemented in rSpec format”.
-
-              ● Replace the contents of the file named counter_xunit_spec.rb
-                with the source code shown in Figure 3.5, “Specification
-                implemented in xUnit format”.
+# lowest upper bound of counter's value
+LIMIT = 2 ** Counter.Size.intVal
 
-Figure 3.4. Specification implemented in rSpec format
-
-LIMIT = 2 ** Counter::Size  # lowest upper bound of counter's value
-MAX = LIMIT - 1             # maximum allowed value for a counter
-
-include Vpi
+# maximum allowed value for a counter
+MAX = LIMIT - 1
 
 context "A resetted counter's value" do
   setup do
-    @design = Counter.new
-    @design.reset!
+    Counter.reset!
   end
 
   specify "should be zero" do
-    @design.count.intVal.should_equal 0
+    Counter.count.intVal.should_equal 0
   end
 
   specify "should increment by one count upon each rising clock edge" do
     LIMIT.times do |i|
-      @design.count.intVal.should_equal i
+      Counter.count.intVal.should_equal i
       relay_verilog # advance the clock
     end
   end
@@ -944,107 +967,129 @@ end
 
 context "A counter with the maximum value" do
   setup do
-    @design = Counter.new
-    @design.reset!
+    Counter.reset!
 
     # increment the counter to maximum value
     MAX.times do relay_verilog end
-    @design.count.intVal.should_equal MAX
+    Counter.count.intVal.should_equal MAX
   end
 
   specify "should overflow upon increment" do
     relay_verilog # increment the counter
-    @design.count.intVal.should_equal 0
+    Counter.count.intVal.should_equal 0
   end
 end
 
-Figure 3.5. Specification implemented in xUnit format
+Figure 4.5. Specification implemented in xUnit format
 
-LIMIT = 2 ** Counter::Size  # lowest upper bound of counter's value
-MAX = LIMIT - 1             # maximum allowed value for a counter
+# lowest upper bound of counter's value
+LIMIT = 2 ** Counter.Size.intVal
 
-class ResettedCounterValue < Test::Unit::TestCase
-  include Vpi
+# maximum allowed value for a counter
+MAX = LIMIT - 1
 
+class ResettedCounterValue < Test::Unit::TestCase
   def setup
-    @design = Counter.new
-    @design.reset!
+    Counter.reset!
   end
 
   def test_zero
-    assert_equal 0, @design.count.intVal
+    assert_equal 0, Counter.count.intVal
   end
 
   def test_increment
     LIMIT.times do |i|
-      assert_equal i, @design.count.intVal
+      assert_equal i, Counter.count.intVal
       relay_verilog # advance the clock
     end
   end
 end
 
 class MaximumCounterValue < Test::Unit::TestCase
-  include Vpi
-
   def setup
-    @design = Counter.new
-    @design.reset!
+    Counter.reset!
 
     # increment the counter to maximum value
     MAX.times do relay_verilog end
-    assert_equal MAX, @design.count.intVal
+    assert_equal MAX, Counter.count.intVal
   end
 
   def test_overflow
     relay_verilog # increment the counter
-    assert_equal 0, @design.count.intVal
+    assert_equal 0, Counter.count.intVal
   end
 end
 
+[Important] Before we continue…
+              ● Replace the contents of the file named counter_rspec_spec.rb
+                with the source code shown in Figure 4.4, “Specification
+                implemented in rSpec format”.
+
+              ● Replace the contents of the file named counter_xunit_spec.rb
+                with the source code shown in Figure 4.5, “Specification
+                implemented in xUnit format”.
+
+              ● Replace the contents of the files named counter_rspec_design.rb
+                and counter_xunit_design.rb with the following code. This code
+                defines the reset! method which resets our Verilog design.
+
+                class << Counter
+                  def reset!
+                    reset.intVal = 1
+                    relay_verilog # advance the clock
+                    reset.intVal = 0
+                  end
+                end
+
+
 Implement the prototype
 
 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. Figure 3.6, “Ruby prototype of our
+in Verilog, and gain confidence in our work. Figure 4.6, “Ruby prototype of our
 Verilog design” shows the completed prototype for our design.
 
-[Important] Before we continue…
-            Replace the contents of the files named counter_rspec_proto.rb and
-            counter_xunit_proto.rb with the source code shown in Figure 3.6,
-            “Ruby prototype of our Verilog design”.
-
-Figure 3.6. Ruby prototype of our Verilog design
+Figure 4.6. Ruby prototype of our Verilog design
 
-class CounterPrototype < Counter
+class << Counter
   def simulate!
-    if @reset.intVal == 1
-      @count.intVal = 0
+    if reset.intVal == 1
+      count.intVal = 0
     else
-      @count.intVal += 1
+      count.intVal += 1
     end
   end
 end
 
+[Important] Before we continue…
+            Replace the contents of the files named counter_rspec_proto.rb and
+            counter_xunit_proto.rb with the source code shown in Figure 4.6,
+            “Ruby prototype of our Verilog design”.
+
 Verify the prototype
 
 Now that we have implemented our prototype, we are ready to verify it against
-our Specification by running the Test. Figure 3.7, “Running a test with
-specification in rSpec format” and Figure 3.8, “Running a test with
+our Specification by running the Test. Figure 4.7, “Running a test with
+specification in rSpec format” and Figure 4.8, “Running a test with
 specification in xUnit format” illustrate this process.
 
-[Tip] Tip
+[Tip] Reuse your past efforts!
       The same specification can be used to verify both prototype and design.
 
 Here, 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
-Icarus Verilog simulator, denoted by ivl, is used to run the simulation.
+Icarus Verilog simulator, denoted by cver, is used to run the simulation.
 
-Figure 3.7. Running a test with specification in rSpec format
+[Tip] What can the test runner do?
+      If you invoke the test runner (1) without any arguments or (2) with the
+      -T option, it will show you a list of tasks that it can perform for you.
 
-$ rake -f counter_rspec_runner.rake ivl PROTOTYPE=1
+Figure 4.7. Running a test with specification in rSpec format
+
+$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
 counter_rspec: verifying prototype instead of design
 
 A resetted counter's value
@@ -1058,9 +1103,9 @@ Finished in 0.018199 seconds
 
 3 specifications, 0 failures
 
-Figure 3.8. Running a test with specification in xUnit format
+Figure 4.8. Running a test with specification in xUnit format
 
-$ rake -f counter_xunit_runner.rake ivl PROTOTYPE=1
+$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1
 counter_xunit: verifying prototype instead of design
 
 Loaded suite counter_xunit_bench
@@ -1074,17 +1119,12 @@ Implement the design
 
 Now that we have implemented and verified our prototype, we are ready to
 implement our Design. This is often quite simple because we translate existing
-code from Ruby (our prototype) into Verilog (our design). Figure 3.9,
+code from Ruby (our prototype) into Verilog (our design). Figure 4.9,
 “Implementation of a simple up-counter with synchronous reset” illustrates the
 result of this process. Once again, note the striking similarities between the
 implementation of our prototype and design.
 
-[Important] Before we continue…
-            Replace the contents of the file named counter.v with the source
-            code shown in Figure 3.9, “Implementation of a simple up-counter
-            with synchronous reset”.
-
-Figure 3.9. Implementation of a simple up-counter with synchronous reset
+Figure 4.9. Implementation of a simple up-counter with synchronous reset
 
 module counter #(parameter Size = 5) (
   input clock,
@@ -1099,22 +1139,35 @@ module counter #(parameter Size = 5) (
   end
 endmodule
 
+[Important] Before we continue…
+            Replace the contents of the file named counter.v with the source
+            code shown in Figure 4.9, “Implementation of a simple up-counter
+            with synchronous reset”.
+
 Verify the design
 
 Now that we have implemented our Design, we are ready to verify it against our
-Specification by running the Test. Figure 3.10, “Running a test with
-specification in rSpec format” and Figure 3.11, “Running a test with
+Specification by running the Test. Figure 4.10, “Running a test with
+specification in rSpec format” and Figure 4.11, “Running a test with
 specification in xUnit format” illustrate this process.
 
 Here, 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 Icarus Verilog
-simulator, denoted by ivl, is used to run the simulation.
+PROTOTYPE, or by using your shell's unset command. Finally, the GPL Cver
+Verilog simulator, denoted by cver, is used to run the simulation.
+
+[Tip] Running multiple tests
+      Create a file named Rakefile containing the following line.
+
+      require 'ruby-vpi/runner_proxy'
 
-Figure 3.10. Running a test with specification in rSpec format
+      Now you can invoke all test runners in the current directory simply by
+      executing rake cver (where cver denotes the GPL Cver simulator).
 
-$ rake -f counter_rspec_runner.rake ivl
+Figure 4.10. Running a test with specification in rSpec format
+
+$ rake -f counter_rspec_runner.rake cver
 A resetted counter's value
 - should be zero
 - should increment by one count upon each rising clock edge
@@ -1126,9 +1179,9 @@ Finished in 0.005628 seconds
 
 3 specifications, 0 failures
 
-Figure 3.11. Running a test with specification in xUnit format
+Figure 4.11. Running a test with specification in xUnit format
 
-$ rake -f counter_xunit_runner.rake ivl
+$ rake -f counter_xunit_runner.rake cver
 Loaded suite counter_xunit_bench
 Started
 ...
@@ -1136,18 +1189,17 @@ Finished in 0.006766 seconds.
 
 3 tests, 35 assertions, 0 failures, 0 errors
 
+Examples
 
-━━━━━━━━━━━━━━
+The samp directory contains several example tests which illustrate how Ruby-VPI
+can be used. Each example has an associated Rakefile which simplifies the
+process of running it. Therefore, simply navigate into an example directory and
+run the command rake to get started.
 
-^[1] Because Ruby-VPI makes use of the Verilog VPI C-language interface, it
-links to symbols whose names begin with _vpi. It is possible for these symbols
-to be undefined when Ruby-VPI is compiled under GNU/Linux and similar operating
-systems. In contrast, one cannot compile a shared object file with references
-to undefined symbols under Windows. Thus, we must find a Verilog simulator's
-shared object file, which contains definitions of all VPI symbols, and give
-this file to the linker when compiling Ruby-VPI.
+Also, some example specifications make use of BDD through the rSpec library.
+See the the section called “Methodology” for a discussion of rSpec.
 
-Chapter 4. Known problems
+Chapter 5. Known problems
 
 Table of Contents
 
@@ -1195,15 +1247,16 @@ vpi_handle_by_name
 
 Give full paths to Verilog objects
 
-In version 0.8 of Icarus Verilog, the vpi_handle_by_name function requires an
-absolute path (including the name of the bench which instantiates the design)
-to a Verilog object.
+In version 0.8 and snapshot 20061009 of Icarus Verilog, the vpi_handle_by_name
+function requires an absolute path (including the name of the bench which
+instantiates the design) to a Verilog object. In addition, vpi_handle_by_name
+is unable to retrieve the handle for a module parameter.
 
-For example, consider Example 4.1, “Part of a bench which instantiates a
+For example, consider Example 5.1, “Part of a bench which instantiates a
 Verilog design”. Here, one needs to specify TestFoo.my_foo.clk instead of
 my_foo.clk in order to access the clk input of the my_foo module instance.
 
-Example 4.1. Part of a bench which instantiates a Verilog design
+Example 5.1. Part of a bench which instantiates a Verilog design
 
 module TestFoo;
   reg clk_reg;
@@ -1218,17 +1271,17 @@ a parameter to a module instantiation). Otherwise, you will get a nil value as
 the result of vpi_handle_by_name method.
 
 For example, suppose you wanted to access the clk_reg register, from the bench
-shown in Example 4.2, “Bad design with unconnected registers”. If you execute
+shown in Example 5.2, “Bad design with unconnected registers”. If you execute
 the statement clk_reg = vpi_handle_by_name("TestFoo.clk_reg", nil) in a
 specification, then you will discover that the vpi_handle_by_name method
 returns nil instead of a handle to the clk_reg register.
 
 The solution is to change the design such that it appears like the one shown in
-Example 4.3, “Fixed design with wired registers” where the register is
-connected to a wire, or Example 4.1, “Part of a bench which instantiates a
+Example 5.3, “Fixed design with wired registers” where the register is
+connected to a wire, or Example 5.1, “Part of a bench which instantiates a
 Verilog design” where the register is connected to a module instantiation.
 
-Example 4.2. Bad design with unconnected registers
+Example 5.2. Bad design with unconnected registers
 
 Here the clk_reg register is not connected to anything.
 
@@ -1236,7 +1289,7 @@ module TestFoo;
   reg clk_reg;
 endmodule
 
-Example 4.3. Fixed design with wired registers
+Example 5.3. Fixed design with wired registers
 
 Here the clk_reg register is connected to the clk_wire wire.