ruby-vpi 9.0.0 → 10.0.0

data/doc/src/manual.xml

@@ -54,6 +54,10 @@
   <!ENTITY rspec..ulink "<ulink url='&rspec.url;'>&rspec;</ulink>">
   <!ENTITY rspec-tutorial.url "http://rspec.rubyforge.org/tutorials/index.html">
   <!ENTITY rspec-tutorial..ulink "<ulink url='&rspec-tutorial.url;'>&rspec; tutorial</ulink>">
+
+  <!ENTITY kd "<application>kdiff3</application>">
+
+  <!ENTITY test-gen.link "<link linkend='usage.tools.generate-test'>automated test generator</link>">
 ]>
 <book lang="en">
   <bookinfo>
@@ -75,7 +79,7 @@
     </copyright>
 
     <abstract>
-      <para>This manual explains how to use &rv;. You can find the newest version of this manual at the <ulink url="&rv.url;">&rv; website</ulink>.</para>
+      <para>This manual explains how to use &rv;. A <ulink url="manual.txt">plain-text version of this manual</ulink> is also available. Finally, you can find the newest version of this manual at the <ulink url="&rv.url;">&rv; website</ulink>.</para>
     </abstract>
 
     <legalnotice>
@@ -323,7 +327,11 @@
 
         <section id="organization.vpi.util">
           <title>&vpi; utility layer</title>
-          <para>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.</para>
+          <para>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 either (1) its children or (2) its &vpi; properties.</para>
+
+          <para>The children of a handle are simply the handles that are immediately contained within it in. For example, suppose that you had a &v; module that contains some registers. The children, of a handle to the module, would be handles to the registers.</para>
+
+          <para>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 <function>get_value</function> and <function>put_value</function> methods.</para>
 
           <table id="table..handle-property-accessor-naming-format" frame='all'>
             <title>Naming format for accessing a handle's &vpi; properties</title>
@@ -801,10 +809,10 @@
     </section>
   </chapter>
 
-  <chapter id="usage">
-    <title>Usage</title>
+  <chapter id="setup">
+    <title>Setup</title>
 
-    <section id="usage.requirements">
+    <section id="setup.reqs">
       <title>Requirements</title>
       <para>The following software is necessary in order to use &rv;.</para>
 
@@ -847,7 +855,7 @@
         </varlistentry>
 
         <varlistentry>
-          <term><command>make</command></term>
+          <term><application>make</application></term>
           <listitem>
             <para><ulink url="http://www.gnu.org/software/make/">&gnu; make</ulink> is preferred but any distribution of <command>make</command> should be acceptable.</para>
           </listitem>
@@ -881,65 +889,65 @@
           </listitem>
         </varlistentry>
       </variablelist>
-    </section>
-
-    <section id="usage.recommendations">
-      <title>Recommendations</title>
-      <para>The following software may make your interactions with &rv; more pleasant.</para>
-
-      <variablelist>
-        <varlistentry>
-          <term>Text merging tool</term>
-          <listitem>
-            <para>An <emphasis>interactive</emphasis> 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 <link linkend="usage.tools.generate-test">automated test generator</link>. Below are a list of popular text merging tools.</para>
-
-            <variablelist>
-
-              <varlistentry>
-                <term><ulink url="http://elonen.iki.fi/code/imediff/">imediff2</ulink></term>
-                <listitem>
-                  <para>A textual, fullscreen two-way merging tool, which works in a terminal. Useful when working remotely via SSH.</para>
-                </listitem>
-              </varlistentry>
 
-              <varlistentry>
-                <term><ulink url="http://kdiff3.sourceforge.net/">kdiff3</ulink></term>
-                <listitem>
-                  <para>A graphical, three-way merging tool for KDE.</para>
-                </listitem>
-              </varlistentry>
+      <section id="setup.reqs.optional">
+        <title>Recommendations</title>
+        <para>The following software may make your interactions with &rv; more pleasant.</para>
 
-              <varlistentry>
-                <term><ulink url="http://meld.sourceforge.net/">meld</ulink></term>
-                <listitem>
-                  <para>A graphical, three-way merging tool for GNOME.</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term><ulink url="http://tkdiff.sourceforge.net/">tkdiff</ulink></term>
-                <listitem>
-                  <para>A graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term><ulink url="http://furius.ca/xxdiff/">xxdiff</ulink></term>
-                <listitem>
-                  <para>A graphical, three-way merging tool.</para>
-                </listitem>
-              </varlistentry>
-
-            </variablelist>
-          </listitem>
-        </varlistentry>
-      </variablelist>
+        <variablelist>
+          <varlistentry>
+            <term>Text merging tool</term>
+            <listitem>
+              <para>An <emphasis>interactive</emphasis> 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 &test-gen.link;. A handful of the currently available open-source text merging tools are listed below.</para>
+
+              <variablelist>
+
+                <varlistentry>
+                  <term><ulink url="http://kdiff3.sourceforge.net/">&kd;</ulink></term>
+                  <listitem>
+                    <para>A graphical, three-way merging tool for KDE.</para>
+                  </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                  <term><ulink url="http://meld.sourceforge.net/"><application>meld</application></ulink></term>
+                  <listitem>
+                    <para>A graphical, three-way merging tool for GNOME.</para>
+                  </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                  <term><ulink url="http://tkdiff.sourceforge.net/"><application>tkdiff</application></ulink></term>
+                  <listitem>
+                    <para>A graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.</para>
+                  </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                  <term><ulink url="http://furius.ca/xxdiff/"><application>xxdiff</application></ulink></term>
+                  <listitem>
+                    <para>A graphical, three-way merging tool.</para>
+                  </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                  <term><ulink url="http://elonen.iki.fi/code/imediff/"><application>imediff2</application></ulink></term>
+                  <listitem>
+                    <para>A textual, fullscreen two-way merging tool. This tool is useful when you are working remotely via SSH.</para>
+                  </listitem>
+                </varlistentry>
+
+              </variablelist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </section>
     </section>
 
-    <section id="usage.installation">
-      <title>Installation and maintenance</title>
+    <section id="setup.installation">
+      <title>Installation</title>
 
-      <para>Once you have satisfied the <link linkend="usage.requirements">necessary requirements</link>, you can install &rv; by running the command <command>gem <action>install</action> <replaceable>ruby-vpi</replaceable></command>. RubyGems will install &rv; into the system gem directory, whose path can be determined by running the command <command>gem <action>env</action> <replaceable>gemdir</replaceable></command>. Within this directory, there is a "gems" subdirectory which contains the &rv; installation, as illustrated below.</para>
+      <para>Once you have satisfied the <link linkend="setup.reqs">necessary requirements</link>, you can install &rv; by running the command <command>gem <action>install</action> <replaceable>ruby-vpi</replaceable></command>. RubyGems will install &rv; into the system gem directory, whose path can be determined by running the command <command>gem <action>env</action> <replaceable>gemdir</replaceable></command>. Within this directory, there is a "gems" subdirectory which contains the &rv; installation, as illustrated below.</para>
 
 <screen>
 <prompt>$</prompt> <userinput><command>gem <action>env</action> <replaceable>gemdir</replaceable></command></userinput>
@@ -949,10 +957,7 @@
 <computeroutput>/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/</computeroutput>
 </screen>
 
-
-      <para>You can uninstall &rv; by running the command <command>gem <action>uninstall</action> <replaceable>ruby-vpi</replaceable></command>. Furthermore, you can upgrade to the latest release of &rv; by running the command <command>gem <action>update</action> <replaceable>ruby-vpi</replaceable></command>. Finally, you can learn more about using and manipulating RubyGems in <ulink url="http://www.rubygems.org">the RubyGems user manual</ulink>.</para>
-
-      <section id="usage.installation.windows">
+      <section id="setup.installation.windows">
         <title>Installing on Windows</title>
 
         <procedure>
@@ -963,14 +968,18 @@
             <para>Search for object files whose names end with <filename>.so</filename>, <filename>.o</filename>, or <filename>.dll</filename> in your &v; simulator's installation directory.</para>
           </step>
           <step>
-            <para>Determine which object files, among those found in the previous step, contain symbols whose names begin with <symbol>_vpi</symbol><footnote><para>Because &rv; makes use of the &v; &vpi; C-language interface, it links to symbols whose names begin with <symbol>_vpi</symbol>. It is possible for these symbols to be undefined when &rv; is compiled under GNU/Linux and similar operating systems. In contrast, one <ulink url="http://sourceware.org/ml/cygwin/2001-12/msg01292.html">cannot compile a shared object file with references to undefined symbols under Windows</ulink>. 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 &rv;.</para></footnote> by running the command <command>for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' > /dev/null &amp;&amp; echo $x; done</command> in Cygwin.</para>
+            <para>Determine which object files, among those found in the previous step, contain symbols whose names begin with <symbol>_vpi</symbol><footnote><para>Because &rv; makes use of the &vpi; C-language interface, it links to symbols whose names begin with <symbol>_vpi</symbol>. It is possible for these symbols to be undefined when &rv; is compiled under GNU/Linux and similar operating systems. In contrast, one <ulink url="http://sourceware.org/ml/cygwin/2001-12/msg01293.html">cannot compile a shared object file with references to undefined symbols under Windows</ulink>. 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 &rv;.</para></footnote> by running the command <command>for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' > /dev/null &amp;&amp; echo $x; done</command> in Cygwin.</para>
 
-            <para>If you are using Mentor Modelsim, the desired object file can be found at a path similar to <filename>C:\Modeltech\win32\libvsim.dll</filename>.</para>
+            <tip>
+              <para>If you are using Mentor Modelsim, the desired object file can be found at a path similar to <filename>C:\Modeltech\win32\libvsim.dll</filename>.</para>
+            </tip>
 
-            <para>If you are using GPL Cver, the desired object file can be found at a path similar to <filename>C:\gplcver\objs\v_vpi.o</filename>.</para>
+            <tip>
+              <para>If you are using GPL Cver, the desired object file can be found at a path similar to <filename>C:\gplcver\objs\v_vpi.o</filename>.</para>
+            </tip>
           </step>
           <step>
-            <para>Assign the path of the object file (determined in the previous step) to the <varname>LDFLAGS</varname> environment variable. For example, if the object file's path is <replaceable>/life/long/journey</replaceable>, then you would run the command <command>export <varname>LDFLAGS</varname>=<replaceable>/life/long/journey</replaceable></command> in Cygwin.</para>
+            <para>Assign the path of the object file (determined in the previous step) to the <varname>LDFLAGS</varname> environment variable. For example, if the object file's path is <replaceable>/foo/bar/vpi.so</replaceable>, then you would run the command <command>export <varname>LDFLAGS</varname>=<replaceable>/foo/bar/vpi.so</replaceable></command> in Cygwin.</para>
           </step>
           <step>
             <para>You may now install &rv; by running the command <command>gem <action>install</action> <replaceable>ruby-vpi</replaceable></command> in Cygwin.</para>
@@ -979,6 +988,16 @@
       </section>
     </section>
 
+    <section id="setup.maintenance">
+      <title>Maintenance</title>
+
+      <para>You can uninstall &rv; by running the command <command>gem <action>uninstall</action> <replaceable>ruby-vpi</replaceable></command>. Furthermore, you can upgrade to the latest release of &rv; by running the command <command>gem <action>update</action> <replaceable>ruby-vpi</replaceable></command>. Finally, you can learn more about using and manipulating RubyGems in <ulink url="http://www.rubygems.org">the RubyGems user manual</ulink>.</para>
+    </section>
+  </chapter>
+
+  <chapter id="usage">
+    <title>Usage</title>
+
     <section id="usage.tools">
       <title>Tools</title>
       <para>The <filename>bin</filename> directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the <option>--help</option> option.</para>
@@ -986,7 +1005,55 @@
       <section id="usage.tools.generate-test">
         <title>Automated test generation</title>
 
-        <para>The <command>generate_test.rb</command> tool can be used to automatically generate tests from &v; 2001 module declarations (see <xref linkend="usage.tutorial.generate-test"/>). You can try it by running the command <command>generate_test.rb <option>--help</option></command>.</para>
+        <para>The automated test generator (<command>generate_test.rb</command>) generates tests from &v; 2001 module declarations, as demonstrated in <xref linkend="usage.tutorial.generate-test"/>. A generated test is composed of the following parts:
+          <variablelist>
+            <varlistentry>
+              <term>Runner</term>
+              <listitem>
+                <para>Written in Rake, this file builds and runs the test.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>Bench</term>
+              <listitem>
+                <para>Written in Verilog and Ruby, these files define the testing environment.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>Design</term>
+              <listitem>
+                <para>Written in Ruby, this file provides an interface to the design being verified.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>Prototype</term>
+              <listitem>
+                <para>Written in Ruby, this file defines a prototype of the design being verified.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>Specification</term>
+              <listitem>
+                <para>Written in Ruby, this file verifies the design.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </para>
+
+        <para>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 &v; module changes, you would simply re-run this tool and incorporate those changes (using a <link linkend="setup.reqs.optional">text merging tool</link>) into the test without diverting your focus from the specification.</para>
+
+        <tip>
+          <title>Using &kd; with the automated test generator</title>
+          <para>Create a file named <filename>merge2</filename> with the content below, make it executable, and put it somewhere accessible by your <varname>PATH</varname> environment variable. Next, update the <varname>MERGER</varname> environment variable by executing <command>export <varname>MERGER</varname>=<replaceable>merge2</replaceable></command>.</para>
+
+<programlisting>
+#!/bin/sh
+# args: old file, new file
+kdiff3 --auto --merge --output "$2" "$@" 2>/dev/null
+</programlisting>
+
+          <para>From now on, &kd; 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 &kd;. Or, if you do not want to transfer any changes, simply terminate &kd;.</para>
+        </tip>
       </section>
 
       <section id="usage.tools.verilog-ruby-conv">
@@ -996,14 +1063,6 @@
       </section>
     </section>
 
-    <section id="usage.examples">
-      <title>Examples</title>
-
-      <para>The <filename>samp</filename> directory contains several example tests which illustrate how &rv; can be used. Each example has an associated <filename>Rakefile</filename> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the command <command>rake</command> to get started.</para>
-
-      <para>Also, some example specifications make use of BDD through the <application>rSpec</application> library. See the <xref linkend="background.methodology"/> for a discussion of <application>rSpec</application>.</para>
-    </section>
-
     <section id="usage.tutorial">
       <title>Tutorial</title>
 
@@ -1015,7 +1074,7 @@
         </step>
 
         <step>
-          <para><link linkend="usage.tutorial.generate-test">Generate a test</link> for the design using the <link linkend="usage.tools.generate-test">automated test generator</link> tool.</para>
+          <para><link linkend="usage.tutorial.generate-test">Generate a test</link> for the design using the &test-gen.link; tool.</para>
         </step>
 
         <step>
@@ -1063,11 +1122,6 @@
           </variablelist>
         </para>
 
-        <important>
-          <title>Before we continue&hellip;</title>
-          <para>Save the source code shown in <xref linkend="fig..counter.v_decl"/> into a file named <filename>counter.v</filename>.</para>
-        </important>
-
         <figure id="fig..counter.v_decl">
           <title>Declaration of a simple up-counter with synchronous reset</title>
 <programlisting>
@@ -1079,53 +1133,19 @@
 <token>endmodule</token>
 </programlisting>
         </figure>
+
+        <important>
+          <title>Before we continue&hellip;</title>
+          <para>Save the source code shown in <xref linkend="fig..counter.v_decl"/> into a file named <filename>counter.v</filename>.</para>
+        </important>
       </section>
 
       <section id="usage.tutorial.generate-test">
         <title>Generate a test</title>
 
-        <para>Now that we have a &design.gloss; to verify, let us generate a &test.gloss; for it using the automated test generator tool. This tool allows us to implement our &specification.gloss; in either &rspec;, xUnit, or our very own format. Each format represents a different software development methodology: &rspec; represents &BDD.gloss;, xUnit represents &TDD.gloss;, and our own format can represent another methodology.</para>
-
-        <note>
-          <para>In this tutorial, you will see how specifications are implemented in <emphasis>both</emphasis> &rspec; and xUnit formats.</para>
-        </note>
-
-        <para>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <xref linkend="fig..generate-test.rspec"/> and <xref linkend="fig..generate-test.unit-test"/> illustrate this process. Here, the test generation tool produces a test composed of the following parts:
-          <variablelist>
-            <varlistentry>
-              <term>Runner</term>
-              <listitem>
-                <para>Written in Rake, this file builds and runs the test.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Bench</term>
-              <listitem>
-                <para>Written in Verilog and Ruby, these files define the testing environment.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Design</term>
-              <listitem>
-                <para>Written in Ruby, this file provides an interface to the design being verified.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Prototype</term>
-              <listitem>
-                <para>Written in Ruby, this file defines a prototype of the design being verified.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Specification</term>
-              <listitem>
-                <para>Written in Ruby, this file verifies the design.</para>
-              </listitem>
-            </varlistentry>
-          </variablelist>
-        </para>
+        <para>Now that we have a &design.gloss; to verify, let us generate a &test.gloss; for it using the &test-gen.link;. This tool allows us to implement our &specification.gloss; in either &rspec;, xUnit, or our very own format. Each format represents a different software development methodology: &rspec; represents &BDD.gloss;, xUnit represents &TDD.gloss;, and our own format can represent another methodology. Both &rspec; and xUnit are presented in this tutorial.</para>
 
-        <para>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 &v; module changes, you would simply re-run this tool and <link linkend="usage.recommendations">incorporate those changes</link> into the test without diverting your focus from the specification.</para>
+        <para>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <xref linkend="fig..generate-test.rspec"/> and <xref linkend="fig..generate-test.unit-test"/> illustrate this process.</para>
 
         <figure id="fig..generate-test.rspec">
           <title>Generating a test with specification in &rspec; format</title>
@@ -1187,52 +1207,27 @@
 
         <para>Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. <xref linkend="fig..counter_rspec_spec.rb"/> and <xref linkend="fig..counter_xunit_spec.rb"/> illustrate this process. Note the striking similarities between our expectations and their implementation.</para>
 
-        <important>
-          <title>Before we continue&hellip;</title>
-          <itemizedlist>
-            <listitem>
-              <para>Append the following code to the files named <filename>counter_rspec_design.rb</filename> and <filename>counter_xunit_design.rb</filename>.</para>
-
-<programlisting>
-<token>class</token> <constant>Counter</constant>
-  <token>def</token> <function>reset!</function>
-    <varname>@reset</varname>.<function>intVal</function> = <literal>1</literal>
-    <function>relay_verilog</function> <remark># advance the clock</remark>
-    <varname>@reset</varname>.<function>intVal</function> = <literal>0</literal>
-  <token>end</token>
-<token>end</token>
-</programlisting>
-            </listitem>
-            <listitem>
-              <para>Replace the contents of the file named <filename>counter_rspec_spec.rb</filename> with the source code shown in <xref linkend="fig..counter_rspec_spec.rb"/>.</para>
-            </listitem>
-            <listitem>
-              <para>Replace the contents of the file named <filename>counter_xunit_spec.rb</filename> with the source code shown in <xref linkend="fig..counter_xunit_spec.rb"/>.</para>
-            </listitem>
-          </itemizedlist>
-        </important>
-
         <figure id="fig..counter_rspec_spec.rb">
           <title>Specification implemented in &rspec; format</title>
 <programlisting>
-<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>::<constant>Size</constant>  <remark># lowest upper bound of counter's value</remark>
-<constant>MAX</constant> = <constant>LIMIT</constant> - <literal>1</literal>             <remark># maximum allowed value for a counter</remark>
+<remark># lowest upper bound of counter's value</remark>
+<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>.<function>Size</function>.<function>intVal</function>
 
-<token>include</token> <constant>Vpi</constant>
+<remark># maximum allowed value for a counter</remark>
+<constant>MAX</constant> = <constant>LIMIT</constant> - <literal>1</literal>
 
 <function>context</function> <literal>"A resetted counter's value"</literal> <token>do</token>
   <function>setup</function> <token>do</token>
-    <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
-    <varname>@design</varname>.<function>reset!</function>
+    <constant>Counter</constant>.<function>reset!</function>
   <token>end</token>
 
   <function>specify</function> <literal>"should be zero"</literal> <token>do</token>
-    <varname>@design</varname>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <literal>0</literal>
+    <constant>Counter</constant>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <literal>0</literal>
   <token>end</token>
 
   <function>specify</function> <literal>"should increment by one count upon each rising clock edge"</literal> <token>do</token>
     <constant>LIMIT</constant>.<function>times</function> <token>do</token> |<varname>i</varname>|
-      <varname>@design</varname>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <varname>i</varname>
+      <constant>Counter</constant>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <varname>i</varname>
       <function>relay_verilog</function> <remark># advance the clock</remark>
     <token>end</token>
   <token>end</token>
@@ -1240,17 +1235,16 @@
 
 <function>context</function> <literal>"A counter with the maximum value"</literal> <token>do</token>
   <function>setup</function> <token>do</token>
-    <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
-    <varname>@design</varname>.<function>reset!</function>
+    <constant>Counter</constant>.<function>reset!</function>
 
     <remark># increment the counter to maximum value</remark>
     <constant>MAX</constant>.<function>times</function> <token>do</token> <function>relay_verilog</function> <token>end</token>
-    <varname>@design</varname>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <constant>MAX</constant>
+    <constant>Counter</constant>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <constant>MAX</constant>
   <token>end</token>
 
   <function>specify</function> <literal>"should overflow upon increment"</literal> <token>do</token>
     <function>relay_verilog</function> <remark># increment the counter</remark>
-    <varname>@design</varname>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <literal>0</literal>
+    <constant>Counter</constant>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <literal>0</literal>
   <token>end</token>
 <token>end</token>
 </programlisting>
@@ -1259,48 +1253,70 @@
         <figure id="fig..counter_xunit_spec.rb">
           <title>Specification implemented in xUnit format</title>
 <programlisting>
-<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>::<constant>Size</constant>  <remark># lowest upper bound of counter's value</remark>
-<constant>MAX</constant> = <constant>LIMIT</constant> - <literal>1</literal>             <remark># maximum allowed value for a counter</remark>
+<remark># lowest upper bound of counter's value</remark>
+<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>.<function>Size</function>.<function>intVal</function>
 
-<token>class</token> <constant>ResettedCounterValue</constant> &lt; <constant>Test</constant>::<constant>Unit</constant>::<constant>TestCase</constant>
-  <token>include</token> <constant>Vpi</constant>
+<remark># maximum allowed value for a counter</remark>
+<constant>MAX</constant> = <constant>LIMIT</constant> - <literal>1</literal>
 
+<token>class</token> <constant>ResettedCounterValue</constant> &lt; <constant>Test</constant>::<constant>Unit</constant>::<constant>TestCase</constant>
   <token>def</token> <function>setup</function>
-    <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
-    <varname>@design</varname>.<function>reset!</function>
+    <constant>Counter</constant>.<function>reset!</function>
   <token>end</token>
 
   <token>def</token> <function>test_zero</function>
-    <function>assert_equal</function> <literal>0</literal>, <varname>@design</varname>.<function>count</function>.<function>intVal</function>
+    <function>assert_equal</function> <literal>0</literal>, <constant>Counter</constant>.<function>count</function>.<function>intVal</function>
   <token>end</token>
 
   <token>def</token> <function>test_increment</function>
     <constant>LIMIT</constant>.<function>times</function> <token>do</token> |<varname>i</varname>|
-      <function>assert_equal</function> <varname>i</varname>, <varname>@design</varname>.<function>count</function>.<function>intVal</function>
+      <function>assert_equal</function> <varname>i</varname>, <constant>Counter</constant>.<function>count</function>.<function>intVal</function>
       <function>relay_verilog</function> <remark># advance the clock</remark>
     <token>end</token>
   <token>end</token>
 <token>end</token>
 
 <token>class</token> <constant>MaximumCounterValue</constant> &lt; <constant>Test</constant>::<constant>Unit</constant>::<constant>TestCase</constant>
-  <token>include</token> <constant>Vpi</constant>
-
   <token>def</token> <function>setup</function>
-    <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
-    <varname>@design</varname>.<function>reset!</function>
+    <constant>Counter</constant>.<function>reset!</function>
 
     <remark># increment the counter to maximum value</remark>
     <constant>MAX</constant>.<function>times</function> <token>do</token> <function>relay_verilog</function> <token>end</token>
-    <function>assert_equal</function> <constant>MAX</constant>, <varname>@design</varname>.<function>count</function>.<function>intVal</function>
+    <function>assert_equal</function> <constant>MAX</constant>, <constant>Counter</constant>.<function>count</function>.<function>intVal</function>
   <token>end</token>
 
   <token>def</token> <function>test_overflow</function>
     <function>relay_verilog</function> <remark># increment the counter</remark>
-    <function>assert_equal</function> <literal>0</literal>, <varname>@design</varname>.<function>count</function>.<function>intVal</function>
+    <function>assert_equal</function> <literal>0</literal>, <constant>Counter</constant>.<function>count</function>.<function>intVal</function>
   <token>end</token>
 <token>end</token>
 </programlisting>
         </figure>
+
+        <important>
+          <title>Before we continue&hellip;</title>
+          <itemizedlist>
+            <listitem>
+              <para>Replace the contents of the file named <filename>counter_rspec_spec.rb</filename> with the source code shown in <xref linkend="fig..counter_rspec_spec.rb"/>.</para>
+            </listitem>
+            <listitem>
+              <para>Replace the contents of the file named <filename>counter_xunit_spec.rb</filename> with the source code shown in <xref linkend="fig..counter_xunit_spec.rb"/>.</para>
+            </listitem>
+            <listitem>
+              <para>Replace the contents of the files named <filename>counter_rspec_design.rb</filename> and <filename>counter_xunit_design.rb</filename> with the following code. This code defines the <function>reset!</function> method which resets our &v; design.</para>
+
+<programlisting>
+<token>class</token> &lt;&lt; <constant>Counter</constant>
+  <token>def</token> <function>reset!</function>
+    <function>reset</function>.<function>intVal</function> = <literal>1</literal>
+    <function>relay_verilog</function> <remark># advance the clock</remark>
+    <function>reset</function>.<function>intVal</function> = <literal>0</literal>
+  <token>end</token>
+<token>end</token>
+</programlisting>
+            </listitem>
+          </itemizedlist>
+        </important>
       </section>
 
       <section id="usage.tutorial.implement-proto">
@@ -1308,26 +1324,25 @@
 
         <para>Now that we have a &specification.gloss; against which to verify our &design.gloss;, 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 &v;, and gain confidence in our work. <xref linkend="fig..counter_proto.rb"/> shows the completed prototype for our design.</para>
 
-        <important>
-          <title>Before we continue&hellip;</title>
-          <para>Replace the contents of the files named <filename>counter_rspec_proto.rb</filename> and <filename>counter_xunit_proto.rb</filename> with the source code shown in <xref linkend="fig..counter_proto.rb"/>.</para>
-        </important>
-
         <figure id="fig..counter_proto.rb">
           <title>Ruby prototype of our &v; design</title>
 <programlisting>
-<token>class</token> <constant>CounterPrototype</constant> &lt; <constant>Counter</constant>
+<token>class</token> &lt;&lt; <constant>Counter</constant>
   <token>def</token> <function>simulate!</function>
-    <token>if</token> <varname>@reset</varname>.<function>intVal</function> == <literal>1</literal>
-      <varname>@count</varname>.<function>intVal</function> = <literal>0</literal>
+    <token>if</token> <function>reset</function>.<function>intVal</function> == <literal>1</literal>
+      <function>count</function>.<function>intVal</function> = <literal>0</literal>
     <token>else</token>
-      <varname>@count</varname>.<function>intVal</function> += <literal>1</literal>
+      <function>count</function>.<function>intVal</function> += <literal>1</literal>
     <token>end</token>
   <token>end</token>
 <token>end</token>
 </programlisting>
         </figure>
 
+        <important>
+          <title>Before we continue&hellip;</title>
+          <para>Replace the contents of the files named <filename>counter_rspec_proto.rb</filename> and <filename>counter_xunit_proto.rb</filename> with the source code shown in <xref linkend="fig..counter_proto.rb"/>.</para>
+        </important>
       </section>
 
       <section id="usage.tutorial.test-proto">
@@ -1335,15 +1350,21 @@
         <para>Now that we have implemented our prototype, we are ready to verify it against our &specification.gloss; by running the &test.gloss;. <xref linkend="fig..test-proto.rspec"/> and <xref linkend="fig..test-proto.unit-test"/> illustrate this process.</para>
 
         <tip>
+          <title>Reuse your past efforts!</title>
           <para>The <emphasis>same</emphasis> specification can be used to verify both prototype and design.</para>
         </tip>
 
-        <para>Here, the <varname>PROTOTYPE</varname> 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 <varname>PROTOTYPE</varname> before running the test, by using your shell's <command>export</command> or <command>setenv</command> command. Finally, the Icarus &v; simulator, denoted by <replaceable>ivl</replaceable>, is used to run the simulation.</para>
+        <para>Here, the <varname>PROTOTYPE</varname> 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 <varname>PROTOTYPE</varname> before running the test, by using your shell's <command>export</command> or <command>setenv</command> command. Finally, the Icarus &v; simulator, denoted by <replaceable>cver</replaceable>, is used to run the simulation.</para>
+
+        <tip>
+          <title>What can the test runner do?</title>
+          <para>If you invoke the test runner (1) without any arguments or (2) with the <option>-T</option> option, it will show you a list of tasks that it can perform for you.</para>
+        </tip>
 
         <figure id="fig..test-proto.rspec">
           <title>Running a test with specification in &rspec; format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspec_runner.rake</replaceable> <replaceable>ivl</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspec_runner.rake</replaceable> <replaceable>cver</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
 <computeroutput>counter_rspec: verifying prototype instead of design
 
 A resetted counter's value
@@ -1362,7 +1383,7 @@ Finished in 0.018199 seconds
         <figure id="fig..test-proto.unit-test">
           <title>Running a test with specification in xUnit format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_xunit_runner.rake</replaceable> <replaceable>ivl</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_xunit_runner.rake</replaceable> <replaceable>cver</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
 <computeroutput>counter_xunit: verifying prototype instead of design
 
 Loaded suite counter_xunit_bench
@@ -1380,11 +1401,6 @@ Finished in 0.040668 seconds.
 
         <para>Now that we have implemented and verified our prototype, we are ready to implement our &design.gloss;. This is often quite simple because we translate <emphasis>existing</emphasis> code from &r; (our prototype) into &v; (our design). <xref linkend="fig..counter.v_impl"/> illustrates the result of this process. Once again, note the striking similarities between the implementation of our prototype and design.</para>
 
-        <important>
-          <title>Before we continue&hellip;</title>
-          <para>Replace the contents of the file named <filename>counter.v</filename> with the source code shown in <xref linkend="fig..counter.v_impl"/>.</para>
-        </important>
-
         <figure id="fig..counter.v_impl">
           <title>Implementation of a simple up-counter with synchronous reset</title>
 <programlisting>
@@ -1402,18 +1418,32 @@ Finished in 0.040668 seconds.
 <token>endmodule</token>
 </programlisting>
         </figure>
+
+        <important>
+          <title>Before we continue&hellip;</title>
+          <para>Replace the contents of the file named <filename>counter.v</filename> with the source code shown in <xref linkend="fig..counter.v_impl"/>.</para>
+        </important>
       </section>
 
       <section id="usage.tutorial.test-design">
         <title>Verify the design</title>
         <para>Now that we have implemented our &design.gloss;, we are ready to verify it against our &specification.gloss; by running the &test.gloss;. <xref linkend="fig..test-design.rspec"/> and <xref linkend="fig..test-design.unit-test"/> illustrate this process.</para>
 
-        <para>Here, the <varname>PROTOTYPE</varname> environment variable is <emphasis>not</emphasis> 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 <varname>PROTOTYPE</varname>, or by using your shell's <command>unset</command> command. Finally, the Icarus &v; simulator, denoted by <replaceable>ivl</replaceable>, is used to run the simulation.</para>
+        <para>Here, the <varname>PROTOTYPE</varname> environment variable is <emphasis>not</emphasis> 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 <varname>PROTOTYPE</varname>, or by using your shell's <command>unset</command> command. Finally, the GPL Cver &v; simulator, denoted by <replaceable>cver</replaceable>, is used to run the simulation.</para>
+
+        <tip>
+          <title>Running multiple tests</title>
+          <para>Create a file named <filename>Rakefile</filename> containing the following line.</para>
+
+          <programlisting>require 'ruby-vpi/runner_proxy'</programlisting>
+
+          <para>Now you can invoke all test runners in the current directory simply by executing <command>rake <replaceable>cver</replaceable></command> (where <replaceable>cver</replaceable> denotes the GPL Cver simulator).</para>
+        </tip>
 
         <figure id="fig..test-design.rspec">
           <title>Running a test with specification in &rspec; format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspec_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspec_runner.rake</replaceable> <replaceable>cver</replaceable></command></userinput>
 <computeroutput>A resetted counter's value
 - should be zero
 - should increment by one count upon each rising clock edge
@@ -1430,7 +1460,7 @@ Finished in 0.005628 seconds
         <figure id="fig..test-design.unit-test">
           <title>Running a test with specification in xUnit format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_xunit_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_xunit_runner.rake</replaceable> <replaceable>cver</replaceable></command></userinput>
 <computeroutput>Loaded suite counter_xunit_bench
 Started
 ...
@@ -1440,7 +1470,14 @@ Finished in 0.006766 seconds.
 </screen>
         </figure>
       </section>
+    </section>
+
+    <section id="usage.examples">
+      <title>Examples</title>
 
+      <para>The <filename>samp</filename> directory contains several example tests which illustrate how &rv; can be used. Each example has an associated <filename>Rakefile</filename> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the command <command>rake</command> to get started.</para>
+
+      <para>Also, some example specifications make use of BDD through the <application>rSpec</application> library. See the <xref linkend="background.methodology"/> for a discussion of <application>rSpec</application>.</para>
     </section>
   </chapter>
 
@@ -1478,7 +1515,7 @@ Finished in 0.006766 seconds.
         <section id="problems.ivl.vpi_handle_by_name.absolute-paths">
           <title>Give full paths to &v; objects</title>
 
-          <para>In version 0.8 of Icarus &v;, the <function>vpi_handle_by_name</function> function requires an <emphasis>absolute</emphasis> path (including the name of the bench which instantiates the design) to a &v; object.</para>
+          <para>In version 0.8 and snapshot 20061009 of Icarus &v;, the <function>vpi_handle_by_name</function> function requires an <emphasis>absolute</emphasis> path (including the name of the bench which instantiates the design) to a &v; object. In addition, <function>vpi_handle_by_name</function> is unable to retrieve the handle for a module parameter.</para>
 
           <para>For example, consider <xref linkend="ex..TestFoo"/>. Here, one needs to specify <code>TestFoo.my_foo.clk</code> instead of <code>my_foo.clk</code> in order to access the <varname>clk</varname> input of the <varname>my_foo</varname> module instance.</para>