ruby-vpi 7.3.0 → 8.0.0

data/doc/src/manual.xml

@@ -10,7 +10,7 @@
   the file named "LICENSE".
 
   Source code formatting rules:
-     is a reserved keyword
+    <token> is a reserved keyword
     <type> is structure, class, variable type, etc.
     <varname> is a variable name
     <function> is function or method name
@@ -33,16 +33,17 @@
     <para>This problem was fixed in release 2.0.0 (2006-04-17). If it still occurs, then <link linkend='introduction.resources'>please report it</link>.</para>
   </note>">
 
-  <!ENTITY test-bench.gloss "<glossterm linkend='term..test-bench'>test bench</glossterm>">
-  <!ENTITY test.gloss "<glossterm linkend='term..test'>test</glossterm>">
-  <!ENTITY design.gloss "<glossterm linkend='term..design'>design</glossterm>">
-  <!ENTITY specification.gloss "<glossterm linkend='term..specification'>specification</glossterm>">
-  <!ENTITY bench.gloss "<glossterm linkend='term..bench'>bench</glossterm>">
-  <!ENTITY BDD.gloss "<glossterm linkend='term..BDD'>BDD</glossterm>">
-  <!ENTITY TDD.gloss "<glossterm linkend='term..TDD'>TDD</glossterm>">
-  <!ENTITY rspec.gloss "<glossterm linkend='term..rspec'>&rspec;</glossterm>">
-  <!ENTITY rake.gloss "<glossterm linkend='term..rake'>&rake;</glossterm>">
-  <!ENTITY handle.gloss "<glossterm linkend='term..handle'>handle</glossterm>">
+  <!ENTITY test-bench.gloss "<xref linkend='term..test-bench'/>">
+  <!ENTITY test.gloss "<xref linkend='term..test'/>">
+  <!ENTITY design.gloss "<xref linkend='term..design'/>">
+  <!ENTITY specification.gloss "<xref linkend='term..specification'/>">
+  <!ENTITY bench.gloss "<xref linkend='term..bench'/>">
+  <!ENTITY BDD.gloss "<xref linkend='term..BDD'/>">
+  <!ENTITY TDD.gloss "<xref linkend='term..TDD'/>">
+  <!ENTITY rspec.gloss "<xref linkend='term..rspec'/>">
+  <!ENTITY rake.gloss "<xref linkend='term..rake'/>">
+  <!ENTITY handle.gloss "<xref linkend='term..handle'/>">
+  <!ENTITY expectation.gloss "<xref linkend='term..expectation'/>">
 
   <!ENTITY rake "Rake">
   <!ENTITY rake.url "http://rake.rubyforge.org/">
@@ -121,7 +122,7 @@
         <varlistentry>
           <term><filename>lib</filename></term>
           <listitem>
-            <para>This directory contains libraries, written in the Ruby language, for use by specifications.</para>
+            <para>This directory contains Ruby libraries provided by &rv;.</para>
           </listitem>
         </varlistentry>
 
@@ -153,7 +154,7 @@
         </varlistentry>
 
         <varlistentry>
-          <term><ulink url="&rv.url-project;">Tracker</ulink></term>
+          <term><ulink url="&rv.url-tracker;">Tracker</ulink></term>
           <listitem>
             <para>Report problems, contribute patches, and more.</para>
           </listitem>
@@ -918,6 +919,7 @@
 
     <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>
@@ -961,7 +963,7 @@
       <section id="usage.tutorial.declare-design">
         <title>Start with a design</title>
 
-        <para>First, we need a design to verify. In this tutorial, <xref linkend="fig..counter.v_decl"/> will serve as our design. Its interface is composed of the following parts:
+        <para>First, we need a &design.gloss; to verify. In this tutorial, <xref linkend="fig..counter.v_decl"/> will serve as our design. Its interface is composed of the following parts:
           <variablelist>
             <varlistentry>
               <term><constant>Size</constant></term>
@@ -1003,10 +1005,10 @@
       <section id="usage.tutorial.generate-test">
         <title>Generate a test</title>
 
-        <para>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;, unit test, or our very own format. Each format represents a different software development methodology: &rspec; represents &BDD.gloss;, unit testing represents &TDD.gloss;, and our own format can represent another methodology.</para>
+        <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;, unit test, or our very own format. Each format represents a different software development methodology: &rspec; represents &BDD.gloss;, unit testing represents &TDD.gloss;, and our own format can represent another methodology.</para>
 
         <note>
-          <para>In this tutorial, we will see how to implement our specification in both &rspec; and unit test formats.</para>
+          <para>In this tutorial, you will see how specifications are implemented in <emphasis>both</emphasis> &rspec; and unit test 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:
@@ -1044,7 +1046,7 @@
           </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 to incorporate those changes into the test without diverting your focus from the specification.</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 (with the help of a smart merging tool, <ulink url="http://kdiff3.sourceforge.net/">such as <application>kdiff3</application></ulink>) into the test without diverting your focus from the specification.</para>
 
         <figure id="fig..generate-test.rspec">
           <title>Generating a test with specification in &rspec; format</title>
@@ -1084,7 +1086,7 @@ Parsed module: counter
       <section id="usage.tutorial.specification">
         <title>Specify your expectations</title>
 
-        <para>So far, the test generation tool has created a basic foundation for our test. Now we must build upon this foundation by identifying our expectations of the design. That is, how do we expect the design to <emphasis>behave</emphasis> under certain conditions?</para>
+        <para>So far, the test generation tool has created a basic foundation for our &test.gloss;. Now we must build upon this foundation by identifying our &expectation.gloss;s of the &design.gloss;. That is, how do we expect the design to <emphasis>behave</emphasis> under certain conditions?</para>
 
         <para>The following is a reasonable set of expectations for our simple counter:
           <itemizedlist>
@@ -1133,7 +1135,7 @@ Parsed module: counter
 <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>
 
-<function>include</function> <constant>Vpi</constant>
+<token>include</token> <constant>Vpi</constant>
 
 <function>context</function> <literal>"A resetted counter's value"</literal> <token>do</token>
   <function>setup</function> <token>do</token>
@@ -1178,7 +1180,7 @@ Parsed module: counter
 <constant>MAX</constant> = <constant>LIMIT</constant> - <literal>1</literal>             <remark># maximum allowed value for a counter</remark>
 
 <token>class</token> <constant>ResettedCounterValue</constant> &lt; <constant>Test</constant>::<constant>Unit</constant>::<constant>TestCase</constant>
-  <function>include</function> <constant>Vpi</constant>
+  <token>include</token> <constant>Vpi</constant>
 
   <token>def</token> <function>setup</function>
     <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
@@ -1198,7 +1200,7 @@ Parsed module: counter
 <token>end</token>
 
 <token>class</token> <constant>MaximumCounterValue</constant> &lt; <constant>Test</constant>::<constant>Unit</constant>::<constant>TestCase</constant>
-  <function>include</function> <constant>Vpi</constant>
+  <token>include</token> <constant>Vpi</constant>
 
   <token>def</token> <function>setup</function>
     <varname>@design</varname> = <constant>Counter</constant>.<function>new</function>
@@ -1220,7 +1222,8 @@ Parsed module: counter
 
       <section id="usage.tutorial.implement-proto">
         <title>Implement the prototype</title>
-        <para>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 &v;, and gain confidence in our work. <!--Furthermore, we will use the <emphasis>same</emphasis> specification later when verifying our design!--> <xref linkend="fig..counter_proto.rb"/> shows the completed prototype for our design.</para>
+
+        <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>
@@ -1230,7 +1233,7 @@ Parsed module: counter
         <figure id="fig..counter_proto.rb">
           <title>Ruby prototype of our &v; design</title>
 <programlisting>
-<token>class</token> <constant>CounterProto</constant> &lt; <constant>Counter</constant>
+<token>class</token> <constant>CounterPrototype</constant> &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>
@@ -1246,15 +1249,18 @@ Parsed module: counter
 
       <section id="usage.tutorial.test-proto">
         <title>Verify the prototype</title>
-        <para>Now that we have implemented our prototype, we are ready to verify it against our specification by running the test. <xref linkend="fig..test-proto.rspec"/> and <xref linkend="fig..test-proto.unit-test"/> illustrate this process.</para>
+        <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>
+          <para>The <emphasis>same</emphasis> specification can be used to verify both prototype and design.</para>
+        </tip>
 
-        <para>Here, the <varname>PROTO</varname> environment variable is set&mdash;any value is fine&mdash;before running the test in order to replace the design with the prototype in the simulation. Otherwise, instead of our prototype, our design will be verified against our specification. Furthermore, the manner in which the <varname>PROTO</varname> environment variable is set in these figures follows the syntax of the &bash; shell. If you use a different shell, you may have to use different syntax, or a different command altogether, in order to set this variable. Finally, the Icarus &v; simulator, denoted by <replaceable>ivl</replaceable>, is used to simulate our design.</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>ivl</replaceable>, is used to run the simulation.</para>
 
         <figure id="fig..test-proto.rspec">
           <title>Running a test with specification in &rspec; format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>export <replaceable>PROTO=1</replaceable></command></userinput>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspecTest_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspecTest_runner.rake</replaceable> <replaceable>ivl</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
 <computeroutput>counter_rspecTest: verifying prototype instead of design
 
 A resetted counter's value
@@ -1273,8 +1279,7 @@ Finished in 0.018199 seconds
         <figure id="fig..test-proto.unit-test">
           <title>Running a test with specification in unit test format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>export <replaceable>PROTO=1</replaceable></command></userinput>
-<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_unitTest_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
+<prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_unitTest_runner.rake</replaceable> <replaceable>ivl</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
 <computeroutput>counter_unitTest: verifying prototype instead of design
 
 Loaded suite counter_unitTest_bench
@@ -1290,7 +1295,7 @@ Finished in 0.040668 seconds.
       <section id="usage.tutorial.implement-design">
         <title>Implement the design</title>
 
-        <para>Now that we have implemented and verified our prototype, we are ready to implement our design. 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 implementations of our prototype and our design.</para>
+        <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>
@@ -1318,14 +1323,13 @@ Finished in 0.040668 seconds.
 
       <section id="usage.tutorial.test-design">
         <title>Verify the design</title>
-        <para>Now that we have implemented our design, we are ready to verify it against our specification by running the test. <xref linkend="fig..test-design.rspec"/> and <xref linkend="fig..test-design.unit-test"/> illustrate this process.</para>
+        <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>PROTO</varname> environment variable is unset before the test is run in order to prevent the design from being replaced by the prototype. Otherwise, our prototype will be verified&mdash;instead of our design&mdash;against our specification. Furthermore, the manner in which the <varname>PROTO</varname> environment variable is unset in these figures follows the syntax of the &bash; shell. If you use a different shell, you may have to use different syntax, or a different command altogether, in order to set this variable. Finally, the Icarus &v; simulator, denoted by <replaceable>ivl</replaceable>, is used to simulate our design.</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>
 
         <figure id="fig..test-design.rspec">
           <title>Running a test with specification in &rspec; format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>unset <replaceable>PROTO</replaceable></command></userinput>
 <prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_rspecTest_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
 <computeroutput>A resetted counter's value
 - should be zero
@@ -1343,7 +1347,6 @@ Finished in 0.005628 seconds
         <figure id="fig..test-design.unit-test">
           <title>Running a test with specification in unit test format</title>
 <screen>
-<prompt>$</prompt> <userinput><command>unset <replaceable>PROTO</replaceable></command></userinput>
 <prompt>$</prompt> <userinput><command>rake <option>-f</option> <replaceable>counter_unitTest_runner.rake</replaceable> <replaceable>ivl</replaceable></command></userinput>
 <computeroutput>Loaded suite counter_unitTest_bench
 Started
@@ -1476,7 +1479,7 @@ Finished in 0.006766 seconds.
       <glossentry id="term..bench">
         <glossterm>Bench</glossterm>
         <glossdef>
-          <para>An environment in which a design is verified against a specification. Often, it is used to emulate conditions in which the design will be eventually deployed.</para>
+          <para>An environment in which a &design.gloss; is verified against a &specification.gloss;. Often, it is used to emulate conditions in which the design will be eventually deployed.</para>
         </glossdef>
       </glossentry>
 
@@ -1499,7 +1502,18 @@ Finished in 0.006766 seconds.
       <glossentry id="term..design">
         <glossterm>Design</glossterm>
         <glossdef>
-          <para>An idea or entity that is verified against a specification in order to ensure correctness or soundness of its being.</para>
+          <para>An idea or entity that is verified against a &specification.gloss; in order to ensure correctness or soundness of its being. In other words, it is the thing being checked: does it work or not?</para>
+        </glossdef>
+      </glossentry>
+    </glossdiv>
+
+    <glossdiv>
+      <title>E</title>
+
+      <glossentry id="term..expectation">
+        <glossterm>Expectation</glossterm>
+        <glossdef>
+          <para>The desired response to some stimulus.</para>
         </glossdef>
       </glossentry>
     </glossdiv>
@@ -1510,7 +1524,7 @@ Finished in 0.006766 seconds.
       <glossentry id="term..handle">
         <glossterm>Handle</glossterm>
         <glossdef>
-          <para>An object in a &v; simulation.</para>
+          <para>An object in a &v; simulation. For example, a handle can represent a wire, register, module, if-statement, expression, and so on.</para>
         </glossdef>
       </glossentry>
     </glossdiv>
@@ -1546,7 +1560,7 @@ Finished in 0.006766 seconds.
       <glossentry id="term..specification">
         <glossterm>Specification</glossterm>
         <glossdef>
-          <para>A collection of expectations that must be satisfied by a design when subjected to certain conditions.</para>
+          <para>A set of &expectation.gloss;s which define the desired behavior of a &design.gloss; when it is subjected to certain conditions.</para>
         </glossdef>
       </glossentry>
     </glossdiv>
@@ -1565,7 +1579,7 @@ Finished in 0.006766 seconds.
       <glossentry id="term..test">
         <glossterm>Test</glossterm>
         <glossdef>
-          <para>The act of verifying a design against a specification in a bench.</para>
+          <para>Something that checks if a &design.gloss; satisfies a &specification.gloss;.</para>
           <glossseealso otherterm="term..test-bench"/>
         </glossdef>
       </glossentry>

data/doc/src/shared.dtd

@@ -16,8 +16,7 @@
 <!ENTITY rv.url-download "http://rubyforge.org/frs/?group_id=1339">
 <!ENTITY rv.url-tracker "http://rubyforge.org/tracker/?group_id=1339">
 <!ENTITY rv.url-forum "http://rubyforge.org/forum/?group_id=1339">
-<!ENTITY rv.url-source-repo "svn://rubyforge.org//var/svn/ruby-vpi">
-<!ENTITY rv.url-source "http://rubyforge.org/scm/?group_id=1339">
+<!ENTITY rv.url-source "&rv.url;/src/ruby-vpi">
 <!ENTITY rv..ulink "<ulink url='&rv.url;'>&rv;</ulink>">
 
 

data/doc/{xhtml/styles → styles}/manual.css

@@ -5,8 +5,6 @@ body {
 
 /* admonitions */
   .tip, .note, .important, .caution, .warning {
-    /* border: thin solid lightgreen;
-    background-color: honeydew; */
     border: thin solid steelblue;
     background-color: aliceblue;
     padding: 1em;
@@ -36,34 +34,32 @@ body {
   }
 
   .function {
-    color: orangered;
   }
 
   .constant {
-    color: brown;
+    color: green;
     font-weight: bold;
   }
 
   .literal {
-    color: darkgreen;
-    background-color: honeydew;
+    color: blue;
   }
 
   .varname {
     color: magenta;
-    /*background-color: ghostwhite;*/
   }
 
   .token {
-    color: midnightblue;
+    font-weight: bold;
+    color: indigo;
   }
 
   .type {
-    color: royalblue;
+    color: red;
   }
 
   .remark {
-    color: gray;
+    color: orangered;
   }
 
   .command {

data/doc/{xhtml/usage.tutorial.html → usage.tutorial.html}

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Tutorial</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="usage.html" title="Chapter 3. Usage" /><link rel="prev" href="usage.examples.html" title="Examples" /><link rel="next" href="problems.html" title="Chapter 4. Known problems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Tutorial</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="usage.examples.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 3. Usage</th><td width="20%" align="right"> <a accesskey="n" href="problems.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usage.tutorial"></a>Tutorial</h2></div></div></div><div class="procedure"><a id="id2523047"></a><p class="title"><b>Procedure 3.1. Typical way of using <span class="application">Ruby-VPI</span></b></p><ol type="1"><li><p><a href="usage.tutorial.html#usage.tutorial.declare-design" title="Start with a design">Declare the design</a>, which is a Verilog module, using Verilog 2001 syntax.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.generate-test" title="Generate a test">Generate a test</a> for the design using the <a href="usage.tools.html#usage.tools.generate-test" title="Automated test generation">automated test generator</a> tool.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.specification" title="Specify your expectations">Identify your expectations</a> for the design and implement them in the specification.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.implement-proto" title="Implement the prototype">Implement the prototype</a> of the design in Ruby.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.test-proto" title="Verify the prototype">Verify the prototype</a> against the specification.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.implement-design" title="Implement the design">Implement the design</a> in Verilog once the prototype has been verified.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.test-design" title="Verify the design">Verify the design</a> against the specification.</p></li></ol></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.declare-design"></a>Start with a design</h3></div></div></div><p>First, we need a design to verify. In this tutorial, <a href="usage.tutorial.html#fig..counter.v_decl" title="Figure 3.1. Declaration of a simple up-counter with synchronous reset">Figure 3.1, “Declaration of a simple up-counter with synchronous reset”</a> will serve as our design. Its interface is composed of the following parts:
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Tutorial</title><link rel="stylesheet" href="styles/manual.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.68.1" /><link rel="start" href="index.html" title="Ruby-VPI user manual" /><link rel="up" href="usage.html" title="Chapter 3. Usage" /><link rel="prev" href="usage.examples.html" title="Examples" /><link rel="next" href="problems.html" title="Chapter 4. Known problems" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Tutorial</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="usage.examples.html"><img src="images/prev.png" alt="Prev" /></a> </td><th width="60%" align="center">Chapter 3. Usage</th><td width="20%" align="right"> <a accesskey="n" href="problems.html"><img src="images/next.png" alt="Next" /></a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usage.tutorial"></a>Tutorial</h2></div></div></div><div class="procedure"><a id="id2523048"></a><p class="title"><b>Procedure 3.1. Typical way of using <span class="application">Ruby-VPI</span></b></p><ol type="1"><li><p><a href="usage.tutorial.html#usage.tutorial.declare-design" title="Start with a design">Declare the design</a>, which is a Verilog module, using Verilog 2001 syntax.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.generate-test" title="Generate a test">Generate a test</a> for the design using the <a href="usage.tools.html#usage.tools.generate-test" title="Automated test generation">automated test generator</a> tool.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.specification" title="Specify your expectations">Identify your expectations</a> for the design and implement them in the specification.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.implement-proto" title="Implement the prototype">Implement the prototype</a> of the design in Ruby.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.test-proto" title="Verify the prototype">Verify the prototype</a> against the specification.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.implement-design" title="Implement the design">Implement the design</a> in Verilog once the prototype has been verified.</p></li><li><p><a href="usage.tutorial.html#usage.tutorial.test-design" title="Verify the design">Verify the design</a> against the specification.</p></li></ol></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.declare-design"></a>Start with a design</h3></div></div></div><p>First, we need a <a href="glossary.html#term..design">Design</a> to verify. In this tutorial, <a href="usage.tutorial.html#fig..counter.v_decl" title="Figure 3.1. Declaration of a simple up-counter with synchronous reset">Figure 3.1, “Declaration of a simple up-counter with synchronous reset”</a> will serve as our design. Its interface is composed of the following parts:
           </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">Size</code></span></dt><dd><p>This parameter defines the number of bits used to represent the counter's value.</p></dd><dt><span class="term"><code class="varname">clock</code></span></dt><dd><p>Each positive edge of this signal causes the <code class="varname">count</code> register to increment.</p></dd><dt><span class="term"><code class="varname">reset</code></span></dt><dd><p>Assertion of this signal causes the <code class="varname">count</code> register to become zero.</p></dd><dt><span class="term"><code class="varname">count</code></span></dt><dd><p>This register contains the counter's value.</p></dd></dl></div><p>
         </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><p>Save the source code shown in <a href="usage.tutorial.html#fig..counter.v_decl" title="Figure 3.1. Declaration of a simple up-counter with synchronous reset">Figure 3.1, “Declaration of a simple up-counter with synchronous reset”</a> into a file named <code class="filename">counter.v</code>.</p></td></tr></table></div><div class="figure"><a id="fig..counter.v_decl"></a><p class="title"><b>Figure 3.1. Declaration of a simple up-counter with synchronous reset</b></p><pre class="programlisting">
 <span class="token">module</span> counter #(<span class="token">parameter</span> <code class="constant">Size</code> = <code class="literal">5</code>) (
@@ -9,9 +9,9 @@
   <span class="token">output</span> <span class="type">reg</span> [<code class="constant">Size</code> - <code class="literal">1</code> : <code class="literal">0</code>] <code class="varname">count</code>
 );
 <span class="token">endmodule</span>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.generate-test"></a>Generate a test</h3></div></div></div><p>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, unit test, or our very own format. Each format represents a different software development methodology: RSpec represents <a href="glossary.html#term..BDD"><em class="glossterm">BDD</em></a>, unit testing represents <a href="glossary.html#term..TDD"><em class="glossterm">TDD</em></a>, and our own format can represent another methodology.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In this tutorial, we will see how to implement our specification in both RSpec and unit test formats.</p></td></tr></table></div><p>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <a href="usage.tutorial.html#fig..generate-test.rspec" title="Figure 3.2. Generating a test with specification in RSpec format">Figure 3.2, “Generating a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..generate-test.unit-test" title="Figure 3.3. Generating a test with specification in unit test format">Figure 3.3, “Generating a test with specification in unit test format”</a> illustrate this process. Here, the test generation tool produces a test composed of the following parts:
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.generate-test"></a>Generate a test</h3></div></div></div><p>Now that we have a <a href="glossary.html#term..design">Design</a> to verify, let us generate a <a href="glossary.html#term..test">Test</a> for it using the automated test generator tool. This tool allows us to implement our <a href="glossary.html#term..specification">Specification</a> in either RSpec, unit test, or our very own format. Each format represents a different software development methodology: RSpec represents <a href="glossary.html#term..BDD"><span class="acronym">BDD</span></a>, unit testing represents <a href="glossary.html#term..TDD">TDD</a>, and our own format can represent another methodology.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png" /></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In this tutorial, you will see how specifications are implemented in <span class="emphasis"><em>both</em></span> RSpec and unit test formats.</p></td></tr></table></div><p>Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <a href="usage.tutorial.html#fig..generate-test.rspec" title="Figure 3.2. Generating a test with specification in RSpec format">Figure 3.2, “Generating a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..generate-test.unit-test" title="Figure 3.3. Generating a test with specification in unit test format">Figure 3.3, “Generating a test with specification in unit test format”</a> illustrate this process. Here, the test generation tool produces a test composed of the following parts:
           </p><div class="variablelist"><dl><dt><span class="term">Runner</span></dt><dd><p>Written in Rake, this file builds and runs the test.</p></dd><dt><span class="term">Bench</span></dt><dd><p>Written in Verilog and Ruby, these files define the testing environment.</p></dd><dt><span class="term">Design</span></dt><dd><p>Written in Ruby, this file provides an interface to the design being verified.</p></dd><dt><span class="term">Prototype</span></dt><dd><p>Written in Ruby, this file defines a prototype of the design being verified.</p></dd><dt><span class="term">Specification</span></dt><dd><p>Written in Ruby, this file verifies the design.</p></dd></dl></div><p>
-        </p><p>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 to incorporate those changes into the test without diverting your focus from the specification.</p><div class="figure"><a id="fig..generate-test.rspec"></a><p class="title"><b>Figure 3.2. Generating a test with specification in RSpec format</b></p><pre class="screen">
+        </p><p>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 (with the help of a smart merging tool, <a href="http://kdiff3.sourceforge.net/" target="_top">such as <span class="application">kdiff3</span></a>) into the test without diverting your focus from the specification.</p><div class="figure"><a id="fig..generate-test.rspec"></a><p class="title"><b>Figure 3.2. Generating a test with specification in RSpec format</b></p><pre class="screen">
 <code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">generate_test.rb <em class="replaceable"><code>counter.v</code></em> <code class="option">--rspec</code> <code class="option">--name</code> <em class="replaceable"><code>rspecTest</code></em></strong></span></code></strong>
 <code class="computeroutput">Using name `rspecTest' for generated test.
 Using RSpec specification format.
@@ -35,7 +35,7 @@ Parsed module: counter
 - Generated design:           counter_unitTest_design.rb
 - Generated prototype:        counter_unitTest_proto.rb
 - Generated specification:    counter_unitTest_spec.rb</code>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.specification"></a>Specify your expectations</h3></div></div></div><p>So far, the test generation tool has created a basic foundation for our test. Now we must build upon this foundation by identifying our expectations of the design. That is, how do we expect the design to <span class="emphasis"><em>behave</em></span> under certain conditions?</p><p>The following is a reasonable set of expectations for our simple counter:
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.specification"></a>Specify your expectations</h3></div></div></div><p>So far, the test generation tool has created a basic foundation for our <a href="glossary.html#term..test">Test</a>. Now we must build upon this foundation by identifying our <a href="glossary.html#term..expectation">Expectation</a>s of the <a href="glossary.html#term..design">Design</a>. That is, how do we expect the design to <span class="emphasis"><em>behave</em></span> under certain conditions?</p><p>The following is a reasonable set of expectations for our simple counter:
           </p><div class="itemizedlist"><ul type="disc"><li><p>A resetted counter's value should be zero.</p></li><li><p>A resetted counter's value should increment by one count upon each rising clock edge.</p></li><li><p>A counter with the maximum value should overflow upon increment.</p></li></ul></div><p>
         </p><p>Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. <a href="usage.tutorial.html#fig..counter_rspecTest_spec.rb" title="Figure 3.4. Specification implemented in RSpec format">Figure 3.4, “Specification implemented in RSpec format”</a> and <a href="usage.tutorial.html#fig..counter_unitTest_spec.rb" title="Figure 3.5. Specification implemented in unit test format">Figure 3.5, “Specification implemented in unit test format”</a> illustrate this process. Note the striking similarities between our expectations and their implementation.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><div class="itemizedlist"><ul type="disc"><li><p>Append the following code to the files named <code class="filename">counter_rspecTest_design.rb</code> and <code class="filename">counter_unitTest_design.rb</code>.</p><pre class="programlisting">
 <span class="token">class</span> <code class="constant">Counter</code>
@@ -49,7 +49,7 @@ Parsed module: counter
 <code class="constant">LIMIT</code> = <code class="literal">2</code> ** <code class="constant">Counter</code>::<code class="constant">Size</code>  <em><span class="remark"># lowest upper bound of counter's value</span></em>
 <code class="constant">MAX</code> = <code class="constant">LIMIT</code> - <code class="literal">1</code>             <em><span class="remark"># maximum allowed value for a counter</span></em>
 
-<code class="function">include</code> <code class="constant">Vpi</code>
+<span class="token">include</span> <code class="constant">Vpi</code>
 
 <code class="function">context</code> <code class="literal">"A resetted counter's value"</code> <span class="token">do</span>
   <code class="function">setup</code> <span class="token">do</span>
@@ -89,7 +89,7 @@ Parsed module: counter
 <code class="constant">MAX</code> = <code class="constant">LIMIT</code> - <code class="literal">1</code>             <em><span class="remark"># maximum allowed value for a counter</span></em>
 
 <span class="token">class</span> <code class="constant">ResettedCounterValue</code> &lt; <code class="constant">Test</code>::<code class="constant">Unit</code>::<code class="constant">TestCase</code>
-  <code class="function">include</code> <code class="constant">Vpi</code>
+  <span class="token">include</span> <code class="constant">Vpi</code>
 
   <span class="token">def</span> <code class="function">setup</code>
     <code class="varname">@design</code> = <code class="constant">Counter</code>.<code class="function">new</code>
@@ -109,7 +109,7 @@ Parsed module: counter
 <span class="token">end</span>
 
 <span class="token">class</span> <code class="constant">MaximumCounterValue</code> &lt; <code class="constant">Test</code>::<code class="constant">Unit</code>::<code class="constant">TestCase</code>
-  <code class="function">include</code> <code class="constant">Vpi</code>
+  <span class="token">include</span> <code class="constant">Vpi</code>
 
   <span class="token">def</span> <code class="function">setup</code>
     <code class="varname">@design</code> = <code class="constant">Counter</code>.<code class="function">new</code>
@@ -125,8 +125,8 @@ Parsed module: counter
     <code class="function">assert_equal</code> <code class="literal">0</code>, <code class="varname">@design</code>.<code class="function">count</code>.<code class="function">intVal</code>
   <span class="token">end</span>
 <span class="token">end</span>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.implement-proto"></a>Implement the prototype</h3></div></div></div><p>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.  <a href="usage.tutorial.html#fig..counter_proto.rb" title="Figure 3.6. Ruby prototype of our Verilog design">Figure 3.6, “Ruby prototype of our Verilog design”</a> shows the completed prototype for our design.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><p>Replace the contents of the files named <code class="filename">counter_rspecTest_proto.rb</code> and <code class="filename">counter_unitTest_proto.rb</code> with the source code shown in <a href="usage.tutorial.html#fig..counter_proto.rb" title="Figure 3.6. Ruby prototype of our Verilog design">Figure 3.6, “Ruby prototype of our Verilog design”</a>.</p></td></tr></table></div><div class="figure"><a id="fig..counter_proto.rb"></a><p class="title"><b>Figure 3.6. Ruby prototype of our Verilog design</b></p><pre class="programlisting">
-<span class="token">class</span> <code class="constant">CounterProto</code> &lt; <code class="constant">Counter</code>
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.implement-proto"></a>Implement the prototype</h3></div></div></div><p>Now that we have a <a href="glossary.html#term..specification">Specification</a> against which to verify our <a href="glossary.html#term..design">Design</a>, let us build a prototype of our design. By doing so, we exercise our specification, experience potential problems that may arise when we later implement our design in Verilog, and gain confidence in our work. <a href="usage.tutorial.html#fig..counter_proto.rb" title="Figure 3.6. Ruby prototype of our Verilog design">Figure 3.6, “Ruby prototype of our Verilog design”</a> shows the completed prototype for our design.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><p>Replace the contents of the files named <code class="filename">counter_rspecTest_proto.rb</code> and <code class="filename">counter_unitTest_proto.rb</code> with the source code shown in <a href="usage.tutorial.html#fig..counter_proto.rb" title="Figure 3.6. Ruby prototype of our Verilog design">Figure 3.6, “Ruby prototype of our Verilog design”</a>.</p></td></tr></table></div><div class="figure"><a id="fig..counter_proto.rb"></a><p class="title"><b>Figure 3.6. Ruby prototype of our Verilog design</b></p><pre class="programlisting">
+<span class="token">class</span> <code class="constant">CounterPrototype</code> &lt; <code class="constant">Counter</code>
   <span class="token">def</span> <code class="function">simulate!</code>
     <span class="token">if</span> <code class="varname">@reset</code>.<code class="function">intVal</code> == <code class="literal">1</code>
       <code class="varname">@count</code>.<code class="function">intVal</code> = <code class="literal">0</code>
@@ -135,9 +135,8 @@ Parsed module: counter
     <span class="token">end</span>
   <span class="token">end</span>
 <span class="token">end</span>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.test-proto"></a>Verify the prototype</h3></div></div></div><p>Now that we have implemented our prototype, we are ready to verify it against our specification by running the test. <a href="usage.tutorial.html#fig..test-proto.rspec" title="Figure 3.7. Running a test with specification in RSpec format">Figure 3.7, “Running a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..test-proto.unit-test" title="Figure 3.8. Running a test with specification in unit test format">Figure 3.8, “Running a test with specification in unit test format”</a> illustrate this process.</p><p>Here, the <code class="varname">PROTO</code> environment variable is set—any value is fine—before running the test in order to replace the design with the prototype in the simulation. Otherwise, instead of our prototype, our design will be verified against our specification. Furthermore, the manner in which the <code class="varname">PROTO</code> environment variable is set in these figures follows the syntax of the <span class="application"><span class="acronym">GNU</span> <span class="acronym">BASH</span></span> shell. If you use a different shell, you may have to use different syntax, or a different command altogether, in order to set this variable. Finally, the Icarus Verilog simulator, denoted by <em class="replaceable"><code>ivl</code></em>, is used to simulate our design.</p><div class="figure"><a id="fig..test-proto.rspec"></a><p class="title"><b>Figure 3.7. Running a test with specification in RSpec format</b></p><pre class="screen">
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">export <em class="replaceable"><code>PROTO=1</code></em></strong></span></code></strong>
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_rspecTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em></strong></span></code></strong>
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.test-proto"></a>Verify the prototype</h3></div></div></div><p>Now that we have implemented our prototype, we are ready to verify it against our <a href="glossary.html#term..specification">Specification</a> by running the <a href="glossary.html#term..test">Test</a>. <a href="usage.tutorial.html#fig..test-proto.rspec" title="Figure 3.7. Running a test with specification in RSpec format">Figure 3.7, “Running a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..test-proto.unit-test" title="Figure 3.8. Running a test with specification in unit test format">Figure 3.8, “Running a test with specification in unit test format”</a> illustrate this process.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png" /></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The <span class="emphasis"><em>same</em></span> specification can be used to verify both prototype and design.</p></td></tr></table></div><p>Here, the <code class="varname">PROTOTYPE</code> environment variable is assigned a non-empty value while running the test, so that, instead of our design, our prototype is verified against our specification. You can also assign a value to <code class="varname">PROTOTYPE</code> before running the test, by using your shell's <span><strong class="command">export</strong></span> or <span><strong class="command">setenv</strong></span> command. Finally, the Icarus Verilog simulator, denoted by <em class="replaceable"><code>ivl</code></em>, is used to run the simulation.</p><div class="figure"><a id="fig..test-proto.rspec"></a><p class="title"><b>Figure 3.7. Running a test with specification in RSpec format</b></p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_rspecTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em> <code class="varname">PROTOTYPE</code>=<em class="replaceable"><code>1</code></em></strong></span></code></strong>
 <code class="computeroutput">counter_rspecTest: verifying prototype instead of design
 
 A resetted counter's value
@@ -151,8 +150,7 @@ Finished in 0.018199 seconds
 
 3 specifications, 0 failures</code>
 </pre></div><div class="figure"><a id="fig..test-proto.unit-test"></a><p class="title"><b>Figure 3.8. Running a test with specification in unit test format</b></p><pre class="screen">
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">export <em class="replaceable"><code>PROTO=1</code></em></strong></span></code></strong>
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_unitTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em></strong></span></code></strong>
+<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_unitTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em> <code class="varname">PROTOTYPE</code>=<em class="replaceable"><code>1</code></em></strong></span></code></strong>
 <code class="computeroutput">counter_unitTest: verifying prototype instead of design
 
 Loaded suite counter_unitTest_bench
@@ -161,7 +159,7 @@ Started
 Finished in 0.040668 seconds.
 
 3 tests, 35 assertions, 0 failures, 0 errors</code>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.implement-design"></a>Implement the design</h3></div></div></div><p>Now that we have implemented and verified our prototype, we are ready to implement our design. This is often quite simple because we translate <span class="emphasis"><em>existing</em></span> code from Ruby (our prototype) into Verilog (our design). <a href="usage.tutorial.html#fig..counter.v_impl" title="Figure 3.9. Implementation of a simple up-counter with synchronous reset">Figure 3.9, “Implementation of a simple up-counter with synchronous reset”</a> illustrates the result of this process. Once again, note the striking similarities between the implementations of our prototype and our design.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><p>Replace the contents of the file named <code class="filename">counter.v</code> with the source code shown in <a href="usage.tutorial.html#fig..counter.v_impl" title="Figure 3.9. Implementation of a simple up-counter with synchronous reset">Figure 3.9, “Implementation of a simple up-counter with synchronous reset”</a>.</p></td></tr></table></div><div class="figure"><a id="fig..counter.v_impl"></a><p class="title"><b>Figure 3.9. Implementation of a simple up-counter with synchronous reset</b></p><pre class="programlisting">
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.implement-design"></a>Implement the design</h3></div></div></div><p>Now that we have implemented and verified our prototype, we are ready to implement our <a href="glossary.html#term..design">Design</a>. This is often quite simple because we translate <span class="emphasis"><em>existing</em></span> code from Ruby (our prototype) into Verilog (our design). <a href="usage.tutorial.html#fig..counter.v_impl" title="Figure 3.9. Implementation of a simple up-counter with synchronous reset">Figure 3.9, “Implementation of a simple up-counter with synchronous reset”</a> illustrates the result of this process. Once again, note the striking similarities between the implementation of our prototype and design.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important: Before we continue…"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png" /></td><th align="left">Before we continue…</th></tr><tr><td align="left" valign="top"><p>Replace the contents of the file named <code class="filename">counter.v</code> with the source code shown in <a href="usage.tutorial.html#fig..counter.v_impl" title="Figure 3.9. Implementation of a simple up-counter with synchronous reset">Figure 3.9, “Implementation of a simple up-counter with synchronous reset”</a>.</p></td></tr></table></div><div class="figure"><a id="fig..counter.v_impl"></a><p class="title"><b>Figure 3.9. Implementation of a simple up-counter with synchronous reset</b></p><pre class="programlisting">
 <span class="token">module</span> counter #(<span class="token">parameter</span> <code class="constant">Size</code> = <code class="literal">5</code>) (
   <span class="token">input</span> <code class="varname">clock</code>,
   <span class="token">input</span> <code class="varname">reset</code>,
@@ -174,8 +172,7 @@ Finished in 0.040668 seconds.
       <code class="varname">count</code> &lt;= <code class="varname">count</code> + <code class="literal">1</code>;
   <span class="token">end</span>
 <span class="token">endmodule</span>
-</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.test-design"></a>Verify the design</h3></div></div></div><p>Now that we have implemented our design, we are ready to verify it against our specification by running the test. <a href="usage.tutorial.html#fig..test-design.rspec" title="Figure 3.10. Running a test with specification in RSpec format">Figure 3.10, “Running a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..test-design.unit-test" title="Figure 3.11. Running a test with specification in unit test format">Figure 3.11, “Running a test with specification in unit test format”</a> illustrate this process.</p><p>Here, the <code class="varname">PROTO</code> environment variable is unset before the test is run in order to prevent the design from being replaced by the prototype. Otherwise, our prototype will be verified—instead of our design—against our specification. Furthermore, the manner in which the <code class="varname">PROTO</code> environment variable is unset in these figures follows the syntax of the <span class="application"><span class="acronym">GNU</span> <span class="acronym">BASH</span></span> shell. If you use a different shell, you may have to use different syntax, or a different command altogether, in order to set this variable. Finally, the Icarus Verilog simulator, denoted by <em class="replaceable"><code>ivl</code></em>, is used to simulate our design.</p><div class="figure"><a id="fig..test-design.rspec"></a><p class="title"><b>Figure 3.10. Running a test with specification in RSpec format</b></p><pre class="screen">
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">unset <em class="replaceable"><code>PROTO</code></em></strong></span></code></strong>
+</pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="usage.tutorial.test-design"></a>Verify the design</h3></div></div></div><p>Now that we have implemented our <a href="glossary.html#term..design">Design</a>, we are ready to verify it against our <a href="glossary.html#term..specification">Specification</a> by running the <a href="glossary.html#term..test">Test</a>. <a href="usage.tutorial.html#fig..test-design.rspec" title="Figure 3.10. Running a test with specification in RSpec format">Figure 3.10, “Running a test with specification in RSpec format”</a> and <a href="usage.tutorial.html#fig..test-design.unit-test" title="Figure 3.11. Running a test with specification in unit test format">Figure 3.11, “Running a test with specification in unit test format”</a> illustrate this process.</p><p>Here, the <code class="varname">PROTOTYPE</code> environment variable is <span class="emphasis"><em>not</em></span> 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="varname">PROTOTYPE</code>, or by using your shell's <span><strong class="command">unset</strong></span> command. Finally, the Icarus Verilog simulator, denoted by <em class="replaceable"><code>ivl</code></em>, is used to run the simulation.</p><div class="figure"><a id="fig..test-design.rspec"></a><p class="title"><b>Figure 3.10. Running a test with specification in RSpec format</b></p><pre class="screen">
 <code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_rspecTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em></strong></span></code></strong>
 <code class="computeroutput">A resetted counter's value
 - should be zero
@@ -188,7 +185,6 @@ Finished in 0.005628 seconds
 
 3 specifications, 0 failures</code>
 </pre></div><div class="figure"><a id="fig..test-design.unit-test"></a><p class="title"><b>Figure 3.11. Running a test with specification in unit test format</b></p><pre class="screen">
-<code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">unset <em class="replaceable"><code>PROTO</code></em></strong></span></code></strong>
 <code class="prompt">$</code> <strong class="userinput"><code><span><strong class="command">rake <code class="option">-f</code> <em class="replaceable"><code>counter_unitTest_runner.rake</code></em> <em class="replaceable"><code>ivl</code></em></strong></span></code></strong>
 <code class="computeroutput">Loaded suite counter_unitTest_bench
 Started

data/gem_extconf.rb

@@ -2,7 +2,7 @@
 
 require 'fileutils'
 
-system('rake build config_gem_install') &&
+system('rake build gem_config_inst') &&
 FileUtils.touch('Makefile')
 
 exit $?.exitstatus