ruby-vpi 11.1.0 → 11.1.1

data/doc/src/manual.xml

@@ -1,1824 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
-  Copyright 2006 Suraj N. Kurapati.
-
-  Permission is granted to copy, distribute and/or modify this
-  document under the terms of the GNU Free Documentation License,
-  Version 1.1 or any later version published by the Free Software
-  Foundation; with no Invariant Sections, no Front-Cover Texts and
-  no Back-Cover Texts.  A copy of the license is included in the
-  the file named "LICENSE".
-
-  Source code formatting rules:
-    <token> is a reserved keyword
-    <type> is structure, class, variable type, etc.
-    <varname> is a variable name
-    <function> is function or method name
-    <literal> is for strings, numbers, etc. anything literal
-    <constant> is a constant variable name
-    <remark> is a comment
--->
-
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-  <!-- imports -->
-  <!ENTITY % sharedDTD SYSTEM "shared.dtd"> %sharedDTD;
-  <!ENTITY license SYSTEM "license.xml">
-
-
-  <!-- content -->
-  <!ENTITY background.step3 "<para>When the Ruby interpreter invokes the <code><constant>Vpi</constant>::<function>relay_verilog</function></code> method, it is paused and the &v; simulator is given control.</para>">
-
-  <!ENTITY fixed-in-2.0.0 "<note>
-    <title>Problem solved</title>
-    <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 "<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/">
-  <!ENTITY rake-doc.url "http://docs.rubyrake.org/">
-
-  <!ENTITY rspec "rSpec">
-  <!ENTITY rspec.url "http://rspec.rubyforge.org">
-  <!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>
-    <title>&rv; user manual</title>
-
-    &snk..copyright;
-
-    <copyright>
-      <year>2005</year>
-      <year>2006</year>
-      <holder><ulink url="http://tango.freedesktop.org">Tango Desktop Project</ulink> <remark>for admonition and navigation graphics released under <ulink url="images/COPYING">this license</ulink>.</remark></holder>
-    </copyright>
-
-    <copyright>
-      <year>1999</year>
-      <year>2000</year>
-      <year>2001</year>
-      <holder>Norman Walsh <remark>for DocBook graphics released under <ulink url="images/copyright">this license</ulink>.</remark></holder>
-    </copyright>
-
-    <abstract>
-      <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>
-      <para>Permission is granted to copy, distribute and/or modify this document under the terms of the &gnu; Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "&gnu; Free Documentation License".</para>
-    </legalnotice>
-  </bookinfo>
-
-  <chapter id="introduction">
-    <title>Introduction</title>
-    <para>&rv; is a &r..ulink; interface to <ulink url="http://en.wikipedia.org/wiki/Verilog">&vpi;</ulink>. It lets you create complex &v; test benches easily and wholly in Ruby.</para>
-
-    <section id="introduction.license">
-      <title>License</title>
-      <para>&rv; is <ulink url="http://en.wikipedia.org/wiki/Free_software">free software</ulink>; you can redistribute it and/or modify it under the terms of the <ulink url="http://www.gnu.org/copyleft/gpl.html">&gnu; General Public License</ulink> as published by the <ulink url="http://www.fsf.org">Free Software Foundation</ulink>; either version 2 of the License, or (at your option) any later version.</para>
-    </section>
-
-    <section id="introduction.manifest">
-      <title>Manifest</title>
-
-      <para>When you extract a &rv; release package, the following is what you would expect to find.</para>
-
-      <variablelist>
-        <varlistentry>
-          <term><filename>doc</filename></term>
-          <listitem>
-            <para>This directory contains user documentation in various formats.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><filename>ref</filename></term>
-          <listitem>
-            <para>This directory contains reference <acronym>API</acronym> documentation in &html; format.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><filename>ext</filename></term>
-          <listitem>
-            <para>This directory contains source code, written in the C language, for the <link linkend="background.organization">core of &rv;</link>.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><filename>lib</filename></term>
-          <listitem>
-            <para>This directory contains Ruby libraries provided by &rv;.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><filename>bin</filename></term>
-          <listitem>
-            <para>This directory contains various tools. See <xref linkend="usage.tools"/> for more information.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><filename>samp</filename></term>
-          <listitem>
-            <para>This directory contains example tests. See <xref linkend="usage.examples"/> for more information.</para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-    </section>
-
-    <section id="introduction.resources">
-      <title>Resources</title>
-
-      <variablelist>
-        <varlistentry>
-          <term><ulink url="&rv.url-project;">Project</ulink></term>
-          <listitem>
-            <para>Access project facilities, hosted generously by <ulink url="http://rubyforge.org">RubyForge</ulink>.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="&rv.url-tracker;">Tracker</ulink></term>
-          <listitem>
-            <para>Report problems, contribute patches, and more.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="&rv.url-download;">Releases</ulink></term>
-          <listitem>
-            <para>Download the newest release of &rv;.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="&rv.url-source;">Sources</ulink></term>
-          <listitem>
-            <para>Browse or access the source code repository.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="&rv.url-forum;">Forums</ulink></term>
-          <listitem>
-            <para>Ask for help, give feedback, or discuss.</para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-    </section>
-
-    <section id="introduction.related-works">
-      <title>Related works</title>
-
-      <para>You may wish to consider the following projects, which are similar to &rv;.</para>
-
-      <variablelist>
-        <varlistentry>
-          <term><ulink url="http://rhdl.rubyforge.org">RHDL</ulink></term>
-          <listitem>
-            <para>Hardware description and verification language based on Ruby.</para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><ulink url="http://myhdl.jandecaluwe.com">MyHDL</ulink></term>
-          <listitem>
-            <para>Hardware description and verification language based on Python, which features conversion to &v; and co-simulation.</para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><ulink url="http://jove.sourceforge.net">JOVE</ulink></term>
-          <listitem>
-            <para>Java interface to &vpi;.</para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><ulink url="http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/">ScriptEDA</ulink></term>
-          <listitem>
-            <para>Perl, Python, and Tcl interface to &vpi;.</para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-
-      <section id="introduction.related-works.pli">
-        <title>Ye olde PLI</title>
-        <para>The following projects utilize the archaic <acronym>tf</acronym> and <abbrev>acc</abbrev> PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.</para>
-
-        <variablelist>
-          <varlistentry>
-            <term><ulink url="http://www.nelsim.com">ScriptSim</ulink></term>
-            <listitem>
-              <para>Perl, Python, and Tcl/Tk interface to PLI.</para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><ulink url="http://www.veripool.com/verilog-pli.html">&v;::Pli</ulink></term>
-            <listitem>
-              <para>Perl interface to PLI.</para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><ulink url="http://www.time-rover.com/jpli/">JPLI</ulink></term>
-            <listitem>
-              <para>Java interface to PLI.</para>
-            </listitem>
-          </varlistentry>
-        </variablelist>
-      </section>
-    </section>
-  </chapter>
-
-  <chapter id="background">
-    <title>Background</title>
-
-    <para>&rv; is a &bench.gloss; which lets you &test.gloss; &v; modules using the Ruby language.</para>
-
-    <section id="background.methodology">
-      <title>Methodology</title>
-
-      <para>&rv; presents an open-ended interface to &vpi;. Thus, you can use any methodology you wish when writing tests. However, &BDD.gloss; is emphasized in this project because it greatly simplifies thinking about <emphasis>how</emphasis> to verify a design.</para>
-    </section>
-
-    <section id="background.terminology">
-      <title>Terminology</title>
-
-      <tip>
-        <para>Have a look at the <xref linkend="glossary"/> for definitions of terms used in this manual.</para>
-      </tip>
-
-      <para>As a newcomer into the world of &v;, I often heard the term <emphasis>test bench</emphasis>: <quote>I ran the test bench, but it didn't work!</quote> or <quote>Are you crazy?!! You <emphasis>still</emphasis> haven't written the test bench? o_O</quote>, for example. I flipped through my textbook and surfed the Internet for a definition of the term, but it was to no avail. Instead, both resources nonchalantly employed the term <emphasis>throughout</emphasis> their being, as if mocking my ignorance of what seems to be universal knowledge.</para>
-
-      <para>Defeated, I turned to my inner faculties to determine the answer. <quote>Let's see, the term <emphasis>test bench</emphasis> has the word <emphasis>test</emphasis>&mdash;so it has something to do with testing&mdash;and it has the word <emphasis>bench</emphasis>&mdash;so maybe it's referring to a table where the testing should occur</quote>. This reasoning grew increasingly familiar as my mind rummaged through towering stores of obsolescence and ultimately revealed dreaded memories of sleepless anguish: debugging electronics in the robotics laboratory.</para>
-
-      <para><quote>Aha!</quote>, I exclaimed hesitantly, trying to dismiss the past. The term has its roots in the testing of electronic devices, where an engineer would sit at a bench in an electronics laboratory and verify that an electronic component satisfies some criteria. The bench would be furnished with tools of measurement and manipulation&mdash;such as oscilloscopes, voltmeters, soldering irons, and so on&mdash;which help the engineer to verify the electronic component or locate the sources of defects in the component.</para>
-
-      <para>Alright, now I remember what a laboratory bench is, but how does that compare with the term test bench? Surely they cannot have the same meaning, because it doesn't make sense to <emphasis>run</emphasis> a laboratory bench or to <emphasis>write</emphasis> one. Thus, to avoid propagating such confusion into this manual, I have attempted to clarify the terminology by <link linkend="glossary">simplifying and reintroducing it in a new light</link>.</para>
-    </section>
-
-    <section id="background.organization">
-      <title>Organization</title>
-
-      <figure id="fig..organization">
-        <title>Overall organization of a test</title>
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="figures/organization.png"/>
-          </imageobject>
-        </mediaobject>
-      </figure>
-
-      <para>As <xref linkend="fig..organization"/> shows, a test is composed of a bench, a design, and a specification. To extend the <link linkend="background.terminology">analogy of an electronics laboratory</link>, the first acts as the laboratory bench which provides measurement and manipulation tools. The second acts as the electronic component being verified by the engineer. And the third acts as the engineer who measures, manipulates, and verifies the electronic component.</para>
-
-      <section id="organization.vpi">
-        <title>Interface to &vpi;</title>
-
-        <figure id="fig..organization.detail">
-          <title>Detailed organization of a test</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata fileref="figures/organization_detailed.png"/>
-            </imageobject>
-          </mediaobject>
-        </figure>
-
-        <para>In <xref linkend="fig..organization.detail"/>, &rv; acts as the bench, a &v; simulator encapsulates the design, and a Ruby interpreter encapsulates the specification. Notice that &rv; encapsulates all communication between the Ruby interpreter and &vpi;. This allows the specification, or any Ruby program in general, to access &vpi; using nothing more than the Ruby language! Thus, &rv; removes the burden of having to write C programs in order to access &vpi;.</para>
-
-        <para>Furthermore, &rv; presents the <emphasis>entire</emphasis> IEEE Std 1364-2005 &vpi; interface to the Ruby interpreter, but with the following minor changes.
-
-          <itemizedlist>
-            <listitem>
-              <para>The first letter in the name of every function, type, structure, and constant becomes capitalized.</para>
-
-              <para>For example, the <type>s_vpi_value</type> structure in C becomes the <type>S_vpi_value</type> class in Ruby. Likewise, the <constant>vpiIntVal</constant> constant in C becomes the <constant>VpiIntVal</constant> constant in Ruby.</para>
-            </listitem>
-
-            <listitem>
-              <para>The &vpi; functions <function>vpi_vprintf</function> and <function>vpi_mcd_vprintf</function> are not made accessible to Ruby. However, this isn't a big problem because you can use Ruby's <function>printf</function> method instead.</para>
-
-              <para>The reason for this limitation is that some C compilers have trouble with pointers to the <type>va_list</type> type. For these compilers, the second line in the code shown below causes a <quote>type mismatch</quote> error.</para>
-
-  <programlisting>
-<type>void</type> <function>foo</function>(<parameter><type>va_list</type> <varname>ap</varname></parameter>) {
-  <type>va_list</type> *<varname>p</varname> = &amp;<varname>ap</varname>;
-}
-</programlisting>
-            </listitem>
-          </itemizedlist>
-        </para>
-
-        <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 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>
-            <tgroup cols='6'>
-              <colspec colname='c1'/>
-              <colspec colname='c2'/>
-              <colspec colname='c3'/>
-              <colspec colname='c4'/>
-              <colspec colname='c5'/>
-              <colspec colname='c6'/>
-              <thead>
-                <row>
-                  <entry>Operation</entry>
-                  <entry>_</entry>
-                  <entry>Property</entry>
-                  <entry>_</entry>
-                  <entry>Accessor</entry>
-                  <entry>Addendum</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry namest="c1" nameend="c2">optional</entry>
-                  <entry>required</entry>
-                  <entry namest="c4" nameend="c5">optional</entry>
-                  <entry>optional</entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </table>
-
-          <variablelist>
-            <varlistentry>
-              <term>Operation</term>
-              <listitem>
-                <para>This parameter suggests a method that should be invoked in the context of the Property parameter.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Property</term>
-              <listitem>
-                <para>This parameter suggests which &vpi; property should be accessed. The first letter of this parameter's value should be lower case, and the <emphasis>vpi</emphasis> prefix&mdash;common to all &vpi; properties&mdash;can be omitted.</para>
-
-                <para>For example, the &vpi; property <emphasis>vpiFullName</emphasis> is considered equivalent to <emphasis>fullName</emphasis> but not equivalent to either <emphasis>FullName</emphasis> or <emphasis>full_name</emphasis>.</para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Accessor</term>
-              <listitem>
-                <para>This parameter suggests which &vpi; function should be used to access the &vpi; property. When this parameter is not specified, the &vpi; utility layer will attempt to <emphasis>guess</emphasis> the value of this parameter (<ulink url="../ref/ruby/classes/Vpi/Handle/Property.html">see the source code</ulink> of the <code><constant>Property</constant>.<function>resolve</function></code> method for details).</para>
-
-                <table frame='all'>
-                  <title>Possible accessors and their implications</title>
-                  <tgroup cols='0'>
-                    <thead>
-                      <row>
-                        <entry>Accessor</entry>
-                        <entry>Kind of value accessed</entry>
-                        <entry>&vpi; functions used to access the value</entry>
-                      </row>
-                    </thead>
-                    <tbody>
-                      <row>
-                        <entry>d</entry>
-                        <entry>delay</entry>
-                        <entry><function>vpi_get_delays</function>, <function>vpi_put_delays</function></entry>
-                      </row>
-                      <row>
-                        <entry>l</entry>
-                        <entry>logic</entry>
-                        <entry><function>vpi_get_value</function>, <function>vpi_put_value</function></entry>
-                      </row>
-                      <row>
-                        <entry>i</entry>
-                        <entry>integer</entry>
-                        <entry><function>vpi_get</function></entry>
-                      </row>
-                      <row>
-                        <entry>b</entry>
-                        <entry>boolean</entry>
-                        <entry><function>vpi_get</function></entry>
-                      </row>
-                      <row>
-                        <entry>s</entry>
-                        <entry>string</entry>
-                        <entry><function>vpi_get_str</function></entry>
-                      </row>
-                      <row>
-                        <entry>h</entry>
-                        <entry>handle</entry>
-                        <entry><function>vpi_handle</function></entry>
-                      </row>
-                    </tbody>
-                  </tgroup>
-                </table>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Addendum</term>
-              <listitem>
-                <para>When this parameter is a question mark (<emphasis>?</emphasis>), it suggests that the specified &vpi; property should be queried as a boolean value. This produces the same effect as specifying <emphasis>b</emphasis> for the Accessor parameter.</para>
-
-                <para>When this parameter is an equal sign (<emphasis>=</emphasis>), it suggests that the specified &vpi; property should be written to.</para>
-              </listitem>
-            </varlistentry>
-          </variablelist>
-
-          <example id="ex..handle-property-accessor-naming-format">
-            <title>Accessing a handle's &vpi; properties</title>
-
-            <informaltable frame='all'>
-              <tgroup cols='6'>
-                <colspec colname='c1'/>
-                <colspec colname='c2'/>
-                <colspec colname='c3'/>
-                <colspec colname='c4'/>
-                <colspec colname='c5'/>
-                <colspec colname='c6'/>
-                <colspec colname='c7'/>
-                <colspec colname='c8'/>
-                <thead>
-                  <row>
-                    <entry morerows="1">Ruby expression</entry>
-                    <entry namest="c2" nameend="c7">Naming format</entry>
-                    <entry morerows="1">Description</entry>
-                  </row>
-                  <row>
-                    <entry namest="c2">Operation</entry>
-                    <entry>_</entry>
-                    <entry>Property</entry>
-                    <entry>_</entry>
-                    <entry>Accessor</entry>
-                    <entry>Addendum</entry>
-                  </row>
-                </thead>
-                <tbody>
-                  <!-- each -->
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>each_vpiNet</function> {|<varname>net</varname>| <function>puts</function> <varname>net</varname>.<function>fullName</function>}</code></entry>
-                      <entry>each</entry>
-                      <entry>_</entry>
-                      <entry>vpiNet</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry morerows="1">These expressions print the full name of each <constant>vpiNet</constant> object associated with the handle.</entry>
-                    </row>
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>each_net</function> {|<varname>net</varname>| <function>puts</function> <varname>net</varname>.<function>fullName</function>}</code></entry>
-                      <entry>each</entry>
-                      <entry>_</entry>
-                      <entry>net</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                  <!-- all? -->
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>all_reg?</function> {|<varname>reg</varname>| <varname>reg</varname>.<function>size</function> == <literal>1</literal>}</code></entry>
-                      <entry>all?</entry>
-                      <entry>_</entry>
-                      <entry>vpiReg</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry morerows="1">These expressions check if all registers associated with the handle are capable of storing only one bit.</entry>
-                    </row>
-
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>all_reg?</function> {|<varname>reg</varname>| <varname>reg</varname>.<function>size</function> == <literal>1</literal>}</code></entry>
-                      <entry>all?</entry>
-                      <entry>_</entry>
-                      <entry>reg</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                  <!-- select -->
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>select_vpiNet</function> {|<varname>net</varname>| <varname>net</varname>.<function>x?</function>}</code></entry>
-                      <entry>select</entry>
-                      <entry>_</entry>
-                      <entry>vpiReg</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry morerows="4">These expressions return a list of nets whose logic value is <quote>don't care</quote>.</entry>
-                    </row>
-
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>select_net</function> {|<varname>net</varname>| <varname>net</varname>.<function>x?</function>}</code></entry>
-                      <entry>select</entry>
-                      <entry>_</entry>
-                      <entry>net</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>select</function>(<constant>VpiNet</constant>) {|<varname>net</varname>| <varname>net</varname>.<function>x?</function>}</code></entry>
-                      <entry>select</entry>
-                      <entry>_</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>select</function>(<literal>:VpiNet</literal>) {|<varname>net</varname>| <varname>net</varname>.<function>x?</function>}</code></entry>
-                      <entry>select</entry>
-                      <entry>_</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                    <row>
-                      <entry><code><varname>handle</varname>.<function>select</function>(<literal>:net</literal>) {|<varname>net</varname>| <varname>net</varname>.<function>x?</function>}</code></entry>
-                      <entry>select</entry>
-                      <entry>_</entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                      <entry></entry>
-                    </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiIntVal</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiIntVal</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry morerows="3">These expressions access the logic value of the handle's <constant>vpiIntVal</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiIntVal_l</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiIntVal</entry>
-                    <entry>_</entry>
-                    <entry>l</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>intVal</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>intVal</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>intVal_l</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>intVal</entry>
-                    <entry>_</entry>
-                    <entry>l</entry>
-                    <entry></entry>
-                  </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiIntVal</function> = <literal>15</literal></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiIntVal</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>=</entry>
-                    <entry morerows="3">These expressions assign the number 15 to the logic value of the handle's <constant>vpiIntVal</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiIntVal_l</function> = <literal>15</literal></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiIntVal</entry>
-                    <entry>_</entry>
-                    <entry>l</entry>
-                    <entry>=</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>intVal</function> = <literal>15</literal></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>intVal</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>=</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>intVal</function>_l = <literal>15</literal></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>intVal</entry>
-                    <entry>_</entry>
-                    <entry>l</entry>
-                    <entry>=</entry>
-                  </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiType</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiType</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry morerows="3">These expressions access the integer value of the handle's <constant>vpiType</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiType_i</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiType</entry>
-                    <entry>_</entry>
-                    <entry>i</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>type</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>type</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>type_i</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>type</entry>
-                    <entry>_</entry>
-                    <entry>i</entry>
-                    <entry></entry>
-                  </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiProtected</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiProtected</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry morerows="5">These expressions access the boolean value of the handle's <constant>vpiProtected</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiProtected_b</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiProtected</entry>
-                    <entry>_</entry>
-                    <entry>b</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiProtected?</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiProtected</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>?</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>protected</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>protected</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>protected_b</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>protected</entry>
-                    <entry>_</entry>
-                    <entry>b</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>protected?</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>protected</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>?</entry>
-                  </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiFullName</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiFullName</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry morerows="3">These expressions access the string value of the handle's <constant>vpiFullName</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiFullName_s</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiFullName</entry>
-                    <entry>_</entry>
-                    <entry>s</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>fullName</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>fullName</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>fullName_s</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>fullName</entry>
-                    <entry>_</entry>
-                    <entry>s</entry>
-                    <entry></entry>
-                  </row>
-
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiParent</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiParent</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry morerows="3">These expressions access the handle value of the handle's <constant>vpiParent</constant> property.</entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>vpiParent_h</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>vpiParent</entry>
-                    <entry>_</entry>
-                    <entry>h</entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>parent</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>parent</entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry></entry>
-                  </row>
-                  <row>
-                    <entry><code><varname>handle</varname>.<function>parent_h</function></code></entry>
-                    <entry></entry>
-                    <entry></entry>
-                    <entry>parent</entry>
-                    <entry>_</entry>
-                    <entry>h</entry>
-                    <entry></entry>
-                  </row>
-
-                </tbody>
-              </tgroup>
-            </informaltable>
-          </example>
-        </section>
-      </section>
-    </section>
-
-    <section id="background.running-tests">
-      <title>Running a test</title>
-
-      <para>Unlike an engineer who can verify an electronic component in real-time, the &v; simulator and the Ruby interpreter (see <xref linkend="fig..organization.detail"/>) take turns working with objects in a simulation when a test is run. In particular, they take turns manipulating the design and transfer control to each other when appropriate.</para>
-
-      <para>The situation is similar to a pair of friends playing catch. One friend throws a ball to the other, and the other throws it back. Either is able to inspect and modify the ball, but only when it is in hand.</para>
-
-      <section id="background.running-tests.init">
-        <title>Initialization</title>
-
-        <para>A test is first initialized before it is <link linkend="background.running-tests.exec">executed</link>. <xref linkend="fig..ruby_init"/> illustrates the initialization process <link linkend="proc..ruby_init">described below</link>.</para>
-
-        <figure id="fig..ruby_init">
-          <title>Initialization of a test</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata fileref="figures/ruby_init.png"/>
-            </imageobject>
-          </mediaobject>
-        </figure>
-
-        <procedure id="proc..ruby_init">
-          <title>Initialization of a test</title>
-
-          <step>
-            <para>The &v; simulator initializes the Ruby interpreter by invoking the <code><function>$ruby_init</function>;</code> system task/function, whose parameters represent the command-line invocation of the Ruby interpreter. For example, one would specify <code><function>$ruby_init</function>(<parameter><literal>"ruby"</literal></parameter>, <parameter><literal>"-w"</literal></parameter>);</code> in &v; to achieve the same effect as specifying <command>ruby <option>-w</option></command> at a command-prompt.</para>
-          </step>
-
-          <step>
-            <para>The &v; simulator is paused and the Ruby interpreter is initialized with the arguments of the <code><function>$ruby_init</function>;</code> system task/function.</para>
-          </step>
-
-          <step>&background.step3;</step>
-        </procedure>
-      </section>
-
-      <section id="background.running-tests.exec">
-        <title>Execution</title>
-
-        <para>After a test is <link linkend="background.running-tests.init">initialized</link>, it is executed such that the design is verified against the specification. <xref linkend="fig..ruby_relay"/> illustrates the execution process <link linkend="proc..ruby_relay">described below</link>.</para>
-
-        <figure id="fig..ruby_relay">
-          <title>Execution of a test</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata fileref="figures/ruby_relay.png"/>
-            </imageobject>
-          </mediaobject>
-        </figure>
-
-        <procedure id="proc..ruby_relay">
-          <title>Execution of a test</title>
-
-          <step>
-            <para>The &v; simulator transfers control to the Ruby interpreter by invoking the <code><function>$ruby_relay</function>;</code> system task/function.</para>
-          </step>
-
-          <step>
-            <para>The &v; simulator is paused and the Ruby interpreter is given control.</para>
-          </step>
-
-          <step>&background.step3;</step>
-        </procedure>
-      </section>
-    </section>
-  </chapter>
-
-  <chapter id="setup">
-    <title>Setup</title>
-
-    <section id="setup.reqs">
-      <title>Requirements</title>
-      <para>The following software is necessary in order to use &rv;.</para>
-
-      <variablelist>
-        <varlistentry>
-          <term>&v; simulator</term>
-          <listitem>
-            <para>&rv; is known to work with the following simulators. Nevertheless, you should be able to use it with any &v; simulator that supports &vpi;.</para>
-
-            <variablelist>
-              <varlistentry>
-                <term><ulink url="http://www.icarus.com/eda/&v;/">Icarus &v;</ulink></term>
-                <listitem>
-                  <para>Version 0.8 or newer is acceptable.</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term><ulink url="http://www.pragmatic-c.com/gpl-cver/">GPL Cver</ulink></term>
-                <listitem>
-                  <para>Version 2.11a or newer is acceptable.</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term><ulink url="http://www.synopsys.com/products/simulation/simulation.html">Synopsys VCS</ulink></term>
-                <listitem>
-                  <para>Any version that supports the <option>-load</option> option is acceptable.</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term><ulink url="http://www.model.com">Mentor Modelsim</ulink></term>
-                <listitem>
-                  <para>Any version that supports the <option>-pli</option> option is acceptable.</para>
-                </listitem>
-              </varlistentry>
-            </variablelist>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <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>
-        </varlistentry>
-
-        <varlistentry>
-          <term>C compiler</term>
-          <listitem>
-            <para><ulink url="http://www.gnu.org/software/gcc/">&gnu; Compiler Collection (<acronym>GCC</acronym>)</ulink> is preferred but any C compiler should be acceptable.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="http://en.wikipedia.org/wiki/Pthreads"><acronym>POSIX</acronym> threads (pthreads)</ulink></term>
-          <listitem>
-            <para>Header and linkable object files, and operating system support for this library are necessary.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="http://www.ruby-lang.org">Ruby</ulink></term>
-          <listitem>
-            <para>Version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following <ulink url="http://www.rubygarden.org/faq/section/show/3">these instructions</ulink>.</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><ulink url="http://rubyforge.org/frs/?group_id=126">RubyGems</ulink></term>
-          <listitem>
-            <para>Any recent version should be acceptable. You can install RubyGems by following <ulink url="http://www.rubygems.org/read/chapter/3">these instructions</ulink>.</para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-
-      <section id="setup.reqs.optional">
-        <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 &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="setup.installation">
-      <title>Installation</title>
-
-      <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>
-<computeroutput>/usr/lib/ruby/gems/1.8</computeroutput>
-
-<prompt>$</prompt> <userinput><command>ls <option>-d</option> <replaceable>/usr/lib/ruby/gems/1.8</replaceable>/gems/ruby-vpi-*</command></userinput>
-<computeroutput>/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/</computeroutput>
-</screen>
-
-      <section id="setup.installation.windows">
-        <title>Installing on Windows</title>
-
-        <procedure>
-          <step>
-            <para>Install <ulink url="http://www.cygwin.com">Cygwin</ulink>, the Linux-like environment for Windows.</para>
-          </step>
-          <step>
-            <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 &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>
-
-            <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>
-
-            <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>/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>
-          </step>
-        </procedure>
-      </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>
-
-      <section id="usage.tools.generate-test">
-        <title>Automated test generation</title>
-
-        <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">
-        <title>&v; to &r; conversion</title>
-
-        <para>The <command>header_to_ruby.rb</command> tool can be used to convert &v; header files into &r;. You can try it by running the command <command>header_to_ruby.rb <option>--help</option></command>.</para>
-      </section>
-    </section>
-
-    <section id="usage.tutorial">
-      <title>Tutorial</title>
-
-      <procedure>
-        <title>Typical way of using &rv;</title>
-
-        <step>
-          <para><link linkend="usage.tutorial.declare-design">Declare the design</link>, which is a &v; module, using &v; 2001 syntax.</para>
-        </step>
-
-        <step>
-          <para><link linkend="usage.tutorial.generate-test">Generate a test</link> for the design using the &test-gen.link; tool.</para>
-        </step>
-
-        <step>
-          <para><link linkend="usage.tutorial.specification">Identify your expectations</link> for the design and implement them in the specification.</para>
-        </step>
-
-        <step>
-          <para>(Optional) <link linkend="usage.tutorial.implement-proto">Implement the prototype</link> of the design in &r;.</para>
-        </step>
-
-        <step>
-          <para>(Optional) <link linkend="usage.tutorial.test-proto">Verify the prototype</link> against the specification.</para>
-        </step>
-
-        <step>
-          <para><link linkend="usage.tutorial.implement-design">Implement the design</link> in &v; once the prototype has been verified.</para>
-        </step>
-
-        <step>
-          <para><link linkend="usage.tutorial.test-design">Verify the design</link> against the specification.</para>
-        </step>
-      </procedure>
-
-      <section id="usage.tutorial.declare-design">
-        <title>Start with a design</title>
-
-        <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>
-              <listitem><para>This parameter defines the number of bits used to represent the counter's value.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><varname>clock</varname></term>
-              <listitem><para>Each positive edge of this signal causes the <varname>count</varname> register to increment.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><varname>reset</varname></term>
-              <listitem><para>Assertion of this signal causes the <varname>count</varname> register to become zero.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><varname>count</varname></term>
-              <listitem><para>This register contains the counter's value.</para></listitem>
-            </varlistentry>
-          </variablelist>
-        </para>
-
-        <figure id="fig..counter.v_decl">
-          <title>Declaration of a simple up-counter with synchronous reset</title>
-<programlisting>
-<token>module</token> counter #(<token>parameter</token> <constant>Size</constant> = <literal>5</literal>) (
-  <token>input</token> <varname>clock</varname>,
-  <token>input</token> <varname>reset</varname>,
-  <token>output</token> <type>reg</type> [<constant>Size</constant> - <literal>1</literal> : <literal>0</literal>] <varname>count</varname>
-);
-<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 &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>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>
-<screen>
-<prompt>$</prompt> <userinput><command>generate_test.rb <replaceable>counter.v</replaceable> <option>--rspec</option> <option>--name</option> <replaceable>rspec</replaceable></command></userinput>
-<computeroutput>
-    name  rspec
-  format  rSpec
-
-  module  counter
-  create  counter_rspec_runner.rake
-  create  counter_rspec_bench.v
-  create  counter_rspec_bench.rb
-  create  counter_rspec_design.rb
-  create  counter_rspec_proto.rb
-  create  counter_rspec_spec.rb
-</computeroutput>
-</screen>
-        </figure>
-
-        <figure id="fig..generate-test.unit-test">
-          <title>Generating a test with specification in xUnit format</title>
-<screen>
-<prompt>$</prompt> <userinput><command>generate_test.rb <replaceable>counter.v</replaceable> <option>--xunit</option> <option>--name</option> <replaceable>xunit</replaceable></command></userinput>
-<computeroutput>
-    name  xunit
-  format  xUnit
-
-  module  counter
-  create  counter_xunit_runner.rake
-  create  counter_xunit_bench.v
-  create  counter_xunit_bench.rb
-  create  counter_xunit_design.rb
-  create  counter_xunit_proto.rb
-  create  counter_xunit_spec.rb
-</computeroutput>
-</screen>
-          </figure>
-      </section>
-
-      <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.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>
-            <listitem>
-              <para>A resetted counter's value should be zero.</para>
-            </listitem>
-            <listitem>
-              <para>A resetted counter's value should increment by one count upon each rising clock edge.</para>
-            </listitem>
-            <listitem>
-              <para>A counter with the maximum value should overflow upon increment.</para>
-            </listitem>
-          </itemizedlist>
-        </para>
-
-        <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>
-
-        <figure id="fig..counter_rspec_spec.rb">
-          <title>Specification implemented in &rspec; format</title>
-<programlisting>
-<remark># lowest upper bound of counter's value</remark>
-<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>.<function>Size</function>.<function>intVal</function>
-
-<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>
-    <constant>Counter</constant>.<function>reset!</function>
-  <token>end</token>
-
-  <function>specify</function> <literal>"should be zero"</literal> <token>do</token>
-    <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>|
-      <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>
-<token>end</token>
-
-<function>context</function> <literal>"A counter with the maximum value"</literal> <token>do</token>
-  <function>setup</function> <token>do</token>
-    <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>
-    <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>
-    <constant>Counter</constant>.<function>count</function>.<function>intVal</function>.<function>should_equal</function> <literal>0</literal>
-  <token>end</token>
-<token>end</token>
-</programlisting>
-        </figure>
-
-        <figure id="fig..counter_xunit_spec.rb">
-          <title>Specification implemented in xUnit format</title>
-<programlisting>
-<remark># lowest upper bound of counter's value</remark>
-<constant>LIMIT</constant> = <literal>2</literal> ** <constant>Counter</constant>.<function>Size</function>.<function>intVal</function>
-
-<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>
-    <constant>Counter</constant>.<function>reset!</function>
-  <token>end</token>
-
-  <token>def</token> <function>test_zero</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>, <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>def</token> <function>setup</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>, <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>, <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>def</token> <constant>Counter</constant>.<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>
-</programlisting>
-            </listitem>
-          </itemizedlist>
-        </important>
-      </section>
-
-      <section id="usage.tutorial.implement-proto">
-        <title>Implement the prototype</title>
-
-        <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>
-
-        <figure id="fig..counter_proto.rb">
-          <title>Ruby prototype of our &v; design</title>
-<programlisting>
-<token>def</token> <constant>Counter</constant>.<function>simulate!</function>
-  <token>if</token> <function>reset</function>.<function>intVal</function> == <literal>1</literal>
-    <function>count</function>.<function>intVal</function> = <literal>0</literal>
-  <token>else</token>
-    <function>count</function>.<function>intVal</function> += <literal>1</literal>
-  <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">
-        <title>Verify the prototype</title>
-        <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>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>cver</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
-<computeroutput>counter_rspec: verifying prototype instead of design
-
-A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-
-A counter with the maximum value
-- should overflow upon increment
-
-Finished in 0.018199 seconds
-
-3 specifications, 0 failures</computeroutput>
-</screen>
-        </figure>
-
-        <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>cver</replaceable> <varname>PROTOTYPE</varname>=<replaceable>1</replaceable></command></userinput>
-<computeroutput>counter_xunit: verifying prototype instead of design
-
-Loaded suite counter_xunit_bench
-Started
-...
-Finished in 0.040668 seconds.
-
-3 tests, 35 assertions, 0 failures, 0 errors</computeroutput>
-</screen>
-        </figure>
-      </section>
-
-      <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.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>
-
-        <figure id="fig..counter.v_impl">
-          <title>Implementation of a simple up-counter with synchronous reset</title>
-<programlisting>
-<token>module</token> counter #(<token>parameter</token> <constant>Size</constant> = <literal>5</literal>) (
-  <token>input</token> <varname>clock</varname>,
-  <token>input</token> <varname>reset</varname>,
-  <token>output</token> <type>reg</type> [<constant>Size</constant> - <literal>1</literal> : <literal>0</literal>] <varname>count</varname>
-);
-  <token>always</token> @(<token>posedge</token> <varname>clock</varname>) <token>begin</token>
-    <token>if</token> (<varname>reset</varname>)
-      <varname>count</varname> &lt;= <literal>0</literal>;
-    <token>else</token>
-      <varname>count</varname> &lt;= <varname>count</varname> + <literal>1</literal>;
-  <token>end</token>
-<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 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>cver</replaceable></command></userinput>
-<computeroutput>A resetted counter's value
-- should be zero
-- should increment by one count upon each rising clock edge
-
-A counter with the maximum value
-- should overflow upon increment
-
-Finished in 0.005628 seconds
-
-3 specifications, 0 failures</computeroutput>
-</screen>
-        </figure>
-
-        <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>cver</replaceable></command></userinput>
-<computeroutput>Loaded suite counter_xunit_bench
-Started
-...
-Finished in 0.006766 seconds.
-
-3 tests, 35 assertions, 0 failures, 0 errors</computeroutput>
-</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>
-
-  <chapter id="hacking">
-    <title>Hacking</title>
-
-    <section id="hacking.release-packages">
-      <title>Building release packages</title>
-      <para>In addition to the "normal requirements":./doc/usage.requirements.html, you need the following software to build release packages:
-
-      <variablelist>
-        <varlistentry>
-          <term><ulink url="http://www.docbook.org/">DocBook-XML</ulink></term>
-          <listitem><para/></listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>xsltproc</term>
-          <listitem><para/></listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>xmlto</term>
-          <listitem><para/></listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><ulink url="http://rubyforge.org/projects/redcloth/">RedCloth</ulink></term>
-          <listitem><para/></listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><ulink url="http://www.swig.org/">SWIG</ulink></term>
-          <listitem><para/></listitem>
-        </varlistentry>
-      </variablelist>
-
-      Once you have satisfied these requirements, you can run <command>rake <action>release</action></command> to build the release packages. Also, see the output of <command>rake <option>-T</option></command> for more build options.</para>
-    </section>
-
-  </chapter>
-
-  <chapter id="problems">
-    <title>Known problems</title>
-
-    <para>This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.</para>
-
-    <section id="problems.ruby">
-      <title>Ruby</title>
-
-      <section id="problems.ruby.SystemStackError">
-        <title>SystemStackError</title>
-
-        &fixed-in-2.0.0;
-
-        <para>If a <quote>stack level too deep (SystemStackError)</quote> error occurs during the simulation, then increase the system-resource limit for stack-size by running the command <command>ulimit <option>-s</option> <replaceable>unlimited</replaceable></command> before starting the simulation.</para>
-      </section>
-
-      <section id="problems.ruby.xUnit">
-        <title>test/unit</title>
-
-        &fixed-in-2.0.0;
-
-        <para>If your specification employs Ruby's unit testing framework, then you will encounter the error: <quote>[BUG] cross-thread violation on rb_gc()</quote>.</para>
-      </section>
-    </section>
-
-    <section id="problem.ivl">
-      <title>Icarus &v;</title>
-
-      <section id="problems.ivl.vpi_handle_by_name">
-        <title>vpi_handle_by_name</title>
-
-        <section id="problems.ivl.vpi_handle_by_name.absolute-paths">
-          <title>Give full paths to &v; objects</title>
-
-          <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>
-
-          <example id="ex..TestFoo">
-            <title>Part of a bench which instantiates a &v; design</title>
-<programlisting>
-<token>module</token> TestFoo;
-  <type>reg</type> <varname>clk_reg</varname>;
-  Foo <varname>my_foo</varname>(<parameter>.clk</parameter>(<varname>clk_reg</varname>));
-<token>endmodule</token>
-</programlisting>
-          </example>
-        </section>
-
-        <section id="problems.ivl.vpi_handle_by_name.connect-registers">
-          <title>Registers must be connected</title>
-
-          <para>In version 0.8 of Icarus &v;, if you want to access a register in a design, then it must be connected to something (either assigned to a wire or passed as a parameter to a module instantiation). Otherwise, you will get a <literal>nil</literal> value as the result of <function>vpi_handle_by_name</function> method.</para>
-
-          <para>For example, suppose you wanted to access the <varname>clk_reg</varname> register, from the bench shown in <xref linkend="ex..TestFoo_bad"/>. If you execute the statement <code><varname>clk_reg</varname> = <function>vpi_handle_by_name</function>(<parameter><literal>"TestFoo.clk_reg"</literal></parameter>, <parameter><literal>nil</literal></parameter>)</code> in a specification, then you will discover that the <function>vpi_handle_by_name</function> method returns <literal>nil</literal> instead of a handle to the <varname>clk_reg</varname> register.</para>
-
-          <para>The solution is to change the design such that it appears like the one shown in <xref linkend="ex..TestFoo_fix"/> where the register is connected to a wire, or <xref linkend="ex..TestFoo"/> where the register is connected to a module instantiation.</para>
-
-          <example id="ex..TestFoo_bad">
-            <title>Bad design with unconnected registers</title>
-
-            <para>Here the <varname>clk_reg</varname> register is not connected to anything.</para>
-
-<programlisting>
-<token>module</token> TestFoo;
-  <type>reg</type> <varname>clk_reg</varname>;
-<token>endmodule</token>
-</programlisting>
-          </example>
-
-          <example id="ex..TestFoo_fix">
-            <title>Fixed design with wired registers</title>
-
-            <para>Here the <varname>clk_reg</varname> register is connected to the <varname>clk_wire</varname> wire.</para>
-
-<programlisting>
-<token>module</token> TestFoo;
-  <type>reg</type> <varname>clk_reg</varname>;
-  <type>wire</type> <varname>clk_wire</varname>;
-  <token>assign</token> <varname>clk_wire</varname> = <varname>clk_reg</varname>;
-<token>endmodule</token>
-</programlisting>
-          </example>
-        </section>
-      </section>
-
-      <section id="problems.ivl.vpi_reset">
-        <title>Vpi::reset</title>
-
-        <caution>
-          <title>Deprecated method</title>
-          <para>The <function>vpi_control</function> method was removed in release 3.0.0 (2006-04-23) of &rv;, and is deprecated. Please use <code><constant>Vpi</constant>::<function>vpi_control</function>(<parameter><constant>VpiReset</constant></parameter>)</code> instead.</para>
-        </caution>
-
-        <para>In version 0.8 of Icarus &v;, the <code><function>vpi_control</function>(<parameter><constant>vpiReset</constant></parameter>)</code> &vpi; function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.</para>
-      </section>
-    </section>
-
-    <section id="problems.vsim">
-      <title>Mentor Modelsim</title>
-
-      <section id="problems.vsim.ruby_run">
-        <title>ruby_run()</title>
-
-        &fixed-in-2.0.0;
-
-        <para>Version 6.1b of Mentor Modelsim doesn't play nicely with either an embedded Ruby interpreter or POSIX threads in a PLI application. When &rv; invokes the <function>ruby_run</function> function (which starts the Ruby interpreter), the simulator terminates immediately with an exit status of 0.</para>
-      </section>
-    </section>
-  </chapter>
-
-  <glossary id="glossary">
-    <glossdiv>
-      <title>B</title>
-
-      <glossentry id="term..bench">
-        <glossterm>Bench</glossterm>
-        <glossdef>
-          <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>
-
-      <glossentry id="term..BDD">
-        <glossterm><acronym>BDD</acronym></glossterm>
-
-        <glossdef>
-          <para>Behavior driven development.</para>
-          <para>A software development methodology which emphasizes thinking in terms of behavior when designing, implementing, and verifying software. See the <ulink url="http://behaviour-driven.org/">official wiki</ulink> for more information.</para>
-
-          <glossseealso otherterm="term..TDD"/>
-          <glossseealso otherterm="term..rspec"/>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-
-    <glossdiv>
-      <title>D</title>
-
-      <glossentry id="term..design">
-        <glossterm>Design</glossterm>
-        <glossdef>
-          <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>
-
-    <glossdiv>
-      <title>H</title>
-
-      <glossentry id="term..handle">
-        <glossterm>Handle</glossterm>
-        <glossdef>
-          <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>
-
-    <glossdiv>
-      <title>R</title>
-
-      <glossentry id="term..rake">
-        <glossterm>&rake;</glossterm>
-        <glossdef>
-          <blockquote>
-            <attribution><ulink url="&rake-doc.url;">&rake; documentation</ulink></attribution>
-            <para>Rake is a build tool, written in Ruby, using Ruby as a build language. Rake is similar to make in scope and purpose.</para>
-          </blockquote>
-
-          <para>See the <ulink url="&rake.url;">&rake; website</ulink> for more information.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry id="term..rspec">
-        <glossterm>&rspec;</glossterm>
-        <glossdef>
-          <para>Ruby framework for BDD. See the <ulink url="&rspec.url;">&rspec; website</ulink> and &rspec-tutorial..ulink; for more information.</para>
-
-          <glossseealso otherterm="term..BDD"/>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-
-    <glossdiv>
-      <title>S</title>
-
-      <glossentry id="term..specification">
-        <glossterm>Specification</glossterm>
-        <glossdef>
-          <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>
-
-    <glossdiv>
-      <title>T</title>
-
-      <glossentry id="term..TDD">
-        <glossterm>TDD</glossterm>
-        <glossdef>
-          <para>Test Driven Development.</para>
-          <glossseealso otherterm="term..BDD"/>
-        </glossdef>
-      </glossentry>
-
-      <glossentry id="term..test">
-        <glossterm>Test</glossterm>
-        <glossdef>
-          <para>Something that checks if a &design.gloss; satisfies a &specification.gloss;.</para>
-          <glossseealso otherterm="term..test-bench"/>
-        </glossdef>
-      </glossentry>
-
-      <glossentry id="term..test-bench">
-        <glossterm>Test bench</glossterm>
-        <glossdef>
-          <para>An allusion to <link linkend="background.terminology">a bench in an electronics laboratory</link>, or so it seems.</para>
-          <glossseealso otherterm="term..test"/>
-        </glossdef>
-      </glossentry>
-    </glossdiv>
-  </glossary>
-
-  &license;
-</book>