ruby-vpi 11.1.0 → 11.1.1

data/doc/intro.inc

@@ -0,0 +1,48 @@
+bq. Ruby-VPI is a "Ruby":http://www.ruby-lang.org interface to "Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945. It lets you create complex Verilog test benches easily and wholly in Ruby.
+
+
+h2(#intro.features). Features
+
+* Supports the _entire_ IEEE Std 1364-2005 VPI standard.
+
+* Works with all "major Verilog simulators":manual.html#setup.reqs available today.
+
+* Enables "agile practices":http://www.agilealliance.org/intro such as
+** "test-driven":http://www.testdriven.com development
+** "behavior-driven":http://behaviour-driven.org development
+** "rapid prototyping":manual.html#usage.tutorial.implement-proto for design exploration
+
+* Eliminates unneccesary work:
+** "Specifications":manual.html#usage.tutorial.specification are _readable_, portable, and executable.
+** The "automated test generator":manual.html#usage.tools.generate-test helps you accomodate design changes with _minimal_ effort.
+
+* Utilizes the "power and elegance":http://www.ruby-lang.org/en/about/ of Ruby:
+** Unlimited length integers
+** Regular expressions
+** Multi-threading
+** System calls and I/O
+** "_ad infinium_":http://rubyforge.org
+
+* Gives you the _freedom_ to study, modify, and distribute this software, in accordance with the "GNU General Public License":http://www.gnu.org/copyleft/gpl.html.
+
+
+h2(#intro.appetizers). Appetizers
+
+Here is a modest sampling to whet your appetite.
+
+* Assign the value 2^2048^ to a register:
+
+bq. @some_register.intVal = 2 ** 2048@
+
+* Check if all nets in a module are at high impedance:
+
+bq. @some_module.all_net? { |net| net.z? }@
+
+* See a register's path, width, and location (file & line number):
+
+bq. @puts some_register@
+
+* Simulate fifteen clock cycles:
+
+bq. @15.times { relay_verilog }@
+

data/doc/lib/doc_format.rb

@@ -0,0 +1,62 @@
+=begin
+  Copyright 2006 Suraj N. Kurapati
+
+  This file is part of Ruby-VPI.
+
+  Ruby-VPI is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License
+  as published by the Free Software Foundation; either version 2
+  of the License, or (at your option) any later version.
+
+  Ruby-VPI is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with Ruby-VPI; if not, write to the Free Software Foundation,
+  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+=end
+
+require 'cgi'
+require 'rubygems'
+require 'coderay'
+require 'redcloth'
+
+class String
+  # Returns the result of running this string through RedCloth.
+  def redcloth
+    RedCloth.new(self).to_html
+  end
+
+  # Adds syntax coloring to <code>...</code> elements in the given text. If the <code> tag has an attribute lang="...", then that is considered the programming language for which appropriate syntax coloring should be applied. Otherwise, the programming language is assumed to be ruby.
+  def coderay
+    gsub %r{<(code)(.*?)>(.*?)</\1>}m do
+      code = CGI.unescapeHTML($3)
+      atts = $2
+      lang =
+        if $2 =~ /lang=('|")(.*?)\1/i
+          $2
+        else
+          :ruby
+        end
+
+
+      type =
+        if code =~ /\n/
+          :pre
+        else
+          :code
+        end
+
+      html = CodeRay.scan(code, lang).html(:css => :style)
+
+      %{<#{type} class="code"#{atts}>#{html}</#{type}>}
+    end
+  end
+
+  def to_html
+    redcloth.coderay
+  end
+end
+

data/doc/lib/doc_proxy.rb

@@ -0,0 +1,160 @@
+=begin
+  Copyright 2006 Suraj N. Kurapati
+
+  This file is part of Ruby-VPI.
+
+  Ruby-VPI is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License
+  as published by the Free Software Foundation; either version 2
+  of the License, or (at your option) any later version.
+
+  Ruby-VPI is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with Ruby-VPI; if not, write to the Free Software Foundation,
+  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+=end
+
+require 'erb_proxy'
+
+# Processes ERB templates to produce documentation. Templates may contain "<xref...>" tags where the ... represents the target anchor of the cross-reference.
+class DocProxy < ErbProxy
+  Block = Struct.new :anchor, :title, :type
+  Heading = Struct.new :anchor, :title, :depth
+
+  attr_reader :blocks, :headings, :references
+
+  def initialize
+    super
+
+    @blocks = Hash.new {|h,k| h[k] = []}
+    @headings = []
+
+    # admonitions
+      [:tip, :note, :important, :caution, :warning].each do |type|
+        add_block_handler :admonition, type do |index, title, text|
+          join_redcloth_elements [
+            %{!<images/#{type}.png(#{type})!},
+            %{p(title). #{type.to_s.capitalize}: #{title}},
+            text,
+          ]
+        end
+      end
+
+    # formal blocks; see http://www.sagehill.net/docbookxsl/FormalTitles.html
+      [:figure, :table, :example, :equation, :procedure].each do |type|
+        add_block_handler :formal, type do |index, title, text|
+          join_redcloth_elements [
+            %{p(title). #{type.to_s.capitalize} #{index}. #{title}},
+            text,
+          ]
+        end
+      end
+  end
+
+  # Post-processes the given ERB template result by parsing the document structure and expanding cross-references, and returns the result.
+  def post_process! aResult
+    buffer = aResult
+
+    # parse document structure and insert anchors (so that the table of contents can link directly to these headings) where necessary
+      buffer.gsub! %r{^(\s*h(\d))(\.|\(.*?\)\.)(.*)$} do
+        target = $~.dup
+
+        title = target[4].strip
+        depth = target[2].to_i
+
+        hasAnchor = target[3] =~ /#([^#]+)\)/
+        anchor = $1 || "anchor#{headings.length}"
+
+
+        @headings << Heading.new(anchor, title, depth)
+        @blocks[:section] << Block.new(anchor, title, :section)
+
+
+        if hasAnchor
+          target.to_s
+        else
+          "#{target[1]}(##{anchor})#{target[3]}#{target[4]}"
+        end
+      end
+
+    # expand cross-references into links to their targets
+      blocks = @blocks.values.flatten
+
+      buffer.gsub! %r{<xref\s*(.+?)\s*/?>} do
+        anchor = unanchor($1)
+        target = blocks.find {|b| b.anchor == anchor}
+
+        if target
+          %{"the #{target.type} named &ldquo;#{target.title}&rdquo;":##{target.anchor}}
+        else
+          warn "unresolved cross-reference to #{anchor}"
+          %{"#{anchor}":##{anchor}}
+        end
+      end
+
+    buffer
+  end
+
+  # Adds a block handler for the given type of block and outputs the result in a <div> whose CSS class is the given category.
+  # The arguments for the block handler are:
+  # 1. number of the block
+  # 2. title of the block
+  # 3. content of the block
+  def add_block_handler aCategory, aType
+    raise ArgumentError unless block_given?
+
+    add_handler aType do |buf, text, title, anchor|
+      index = @blocks[aType].length + 1
+
+      unless anchor
+        anchor = "#{aType}#{index}"
+      end
+      anchor = unanchor(anchor)
+
+      @blocks[aType] << Block.new(anchor, title, aType)
+
+
+      elts = [
+        %{<div class="#{aCategory}">},
+          %{<div class="#{aType}" id="#{anchor}">},
+            yield(index, title, text),
+          '</div>',
+        '</div>',
+      ]
+
+      text = join_redcloth_elements(elts)
+      buf << text
+    end
+  end
+
+  private
+
+  # Joins the given elements by putting enough white-space between them so that RedCloth knows they're different elements.
+  def join_redcloth_elements *args
+    args.join "\n\n\n"
+  end
+
+  # Removes the # from a HTML anchor so that only its name is preserved.
+  def unanchor aAnchor
+    aAnchor.sub(/^#+/, '')
+  end
+
+  # update positions of xrefs so that they are later inserted in correct place
+  def update_xrefs aSrcPos, aSrcLen, aDstLen
+    # because it's a replacement, we delete the match and insert the replacement
+    change = 0 - aSrcLen + aDstLen
+
+    @references.select {|ref| ref.position >= aSrcPos}.each do |ref|
+      ref.position += change
+    end
+  end
+
+  def append_to_buffer aBuff, aText
+    update_xrefs aBuff.length, 0, aText.length
+    aBuff << aText
+  end
+end

data/doc/lib/erb_content.rb

@@ -0,0 +1,67 @@
+=begin
+  Copyright 2006 Suraj N. Kurapati
+
+  This file is part of Ruby-VPI.
+
+  Ruby-VPI is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License
+  as published by the Free Software Foundation; either version 2
+  of the License, or (at your option) any later version.
+
+  Ruby-VPI is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with Ruby-VPI; if not, write to the Free Software Foundation,
+  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+=end
+
+require 'erb'
+
+# Returns an array containing the current ERB buffer and the content that the given block will append to the buffer when it is invoked.
+#
+# == Example
+# Suppose your ERB template invoked a method with some arguments and some content in a block. You can pass the block to this method to obtain the content contained within the block.
+#
+## template = ERB.new <<-EOS
+## <% wrap_xml "message" do %>
+##   i love ruby!
+## <% end %>
+## EOS
+#
+# In this case, the ERB template invokes the _wrap_xml_ method to wrap some content within a pair of XML tags.
+#
+## def wrap_xml tag, &block
+##   buffer, content = ERB.buffer_and_content(&block)
+##   buffer << "<#{tag}>#{content}</#{tag}>"
+## end
+#
+# When we evaluate the template:
+## puts template.result(binding)
+#
+# we see the following output:
+## <message>
+##   i love ruby!
+## </message>
+#
+def ERB.buffer_and_content
+  raise ArgumentError unless block_given?
+
+  # buffer + content
+  buffer = yield
+  a = buffer.length
+
+  # buffer + content + content
+  yield
+  b = buffer.length
+
+  # buffer + content
+  content = buffer.slice! a..b
+
+  # buffer
+  buffer.slice!((-content.length)..-1)
+
+  [buffer, content]
+end

data/doc/lib/erb_proxy.rb

@@ -0,0 +1,48 @@
+=begin
+  Copyright 2006 Suraj N. Kurapati
+
+  This file is part of Ruby-VPI.
+
+  Ruby-VPI is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License
+  as published by the Free Software Foundation; either version 2
+  of the License, or (at your option) any later version.
+
+  Ruby-VPI is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with Ruby-VPI; if not, write to the Free Software Foundation,
+  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+=end
+
+require 'erb_content'
+
+class ErbProxy
+  attr_reader :handlers
+
+  def initialize
+    @handlers = {}
+  end
+
+  # Adds a new handler that can be invoked from a ERB template.
+  # The arguments passed to the handler are:
+  # 1. buffer containing the evaluated results of the ERB template (so far; at this point in time)
+  # 2. content that was passed to the handler from the ERB template
+  # 3. variable number of method arguments passed from the ERB template
+  def add_handler aName, &aHandler # :yields: buffer, content, *args
+    @handlers[aName] = aHandler
+
+    # using a string because define_method does not accept a block until Ruby 1.9
+    instance_eval %{
+      def #{aName} *args, &block
+        raise ArgumentError unless block_given?
+
+        args.unshift(*ERB.buffer_and_content(&block))
+        @handlers[#{aName.inspect}].call(*args)
+      end
+    }
+  end
+end

data/doc/manual.erb

@@ -0,0 +1,768 @@
+<div class="cover-page">
+
+h1. Ruby-VPI user manual
+
+Suraj N. Kurapati
+
+<%= Time.now %>
+
+</div>
+
+
+h2(#terms). Terms
+
+Permission is granted to copy, distribute and/or modify this document under the terms of the "GNU Free Documentation License":http://www.gnu.org/copyleft/fdl.html, 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":./LICENSE.
+
+Admonition and navigation graphics are Copyright (c) 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org. They are licensed under "these terms":./images/LICENSE.
+
+
+h1(#intro). Introduction
+
+<%= File.read 'intro.inc' %>
+
+
+h2(#intro.license). License
+
+Ruby-VPI is "free software":http://en.wikipedia.org/wiki/Free_software ; you can redistribute it and/or modify it under the terms of the "GNU General Public License":http://www.gnu.org/copyleft/gpl.html as published by the "Free Software Foundation":http://www.fsf.org ; either version 2 of the License, or (at your option) any later version.
+
+
+h2(#intro.related-works). Related works
+
+* "JOVE":http://jove.sourceforge.net is a Java interface to VPI.
+* "Teal":http://teal.sourceforge.net is a C++ interface to VPI.
+* "ScriptEDA":http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/ is a Perl, Python, and Tcl interface to VPI.
+* "RHDL":http://rhdl.rubyforge.org is a hardware description and verification language based on Ruby.
+* "MyHDL":http://myhdl.jandecaluwe.com is a hardware description and verification language based on Python, which features conversion to Verilog and co-simulation.
+
+
+h2(#intro.related-works.pli). Ye olde PLI
+
+The following projects utilize the archaic *tf* and *acc* PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.
+
+* "ScriptSim":http://www.nelsim.com is a Perl, Python, and Tcl/Tk interface to PLI.
+* "Verilog::Pli":http://www.veripool.com/verilog-pli.html is a Perl interface to PLI.
+* "JPLI":http://www.time-rover.com/jpli/ is a proprietary Java interface to PLI.
+
+
+h1(#background). Background
+
+Ruby-VPI is a "bench":#glossary.bench which lets you "test":#glossary.test Verilog modules using the Ruby language.
+
+
+h2(#background.methodology). Methodology
+
+Ruby-VPI presents an open-ended interface to VPI. Thus, you can use any methodology you wish when writing tests.
+
+
+h2(#background.vocab). Terminology
+
+<% tip do %>
+Have a look at the "glossary":#glossary for definitions of terms used in this manual.
+<% end %>
+
+As a newcomer into the world of Verilog, I often heard the term *test bench*: "I ran the test bench, but it didn't work!" or "Are you crazy?!! You _still_ haven't written the test bench?", 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 _throughout_ their being, as if mocking my ignorance of what seems to be universal knowledge.
+
+Defeated, I turned to my inner faculties to determine the answer. Let's see, the term _test bench_ has the word _test_&mdash;so it has something to do with testing&mdash;and it has the word _bench_&mdash;so maybe it's referring to a table where the testing should occur. 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.
+
+Aha! 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.
+
+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 _run_ a laboratory bench or to _write_ one. Thus, to avoid propagating such confusion into this manual, I have attempted to clarify the terminology by "simplifying and reintroducing it in a new light":#glossary.
+
+
+h2(#background.org). Organization
+
+<% figure "Overall organization of a test", "#fig..organization" do %>
+!figures/organization.png!
+<% end %>
+
+As <xref #fig..organization> shows, a test is composed of a bench, a design, and a specification. To extend the "analogy of an electronics laboratory":#background.vocab, 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.
+
+
+h3(#background.org.vpi). Interface to VPI
+
+<% figure "Detailed organization of a test", "#fig..organization.detail" do %>
+!figures/organization_detailed.png!
+<% end %>
+
+In <xref #fig..organization.detail>, Ruby-VPI acts as the bench, a Verilog simulator encapsulates the design, and a Ruby interpreter encapsulates the specification. Notice that Ruby-VPI 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, Ruby-VPI removes the burden of having to write C programs in order to access VPI.
+
+Furthermore, Ruby-VPI presents the _entire_ IEEE Std 1364-2005 VPI interface to the Ruby interpreter, but with the following minor changes.
+
+* The first letter in the name of every function, type, structure, and constant becomes capitalized. For example, the @s_vpi_value@ structure in C becomes the @S_vpi_value@ class in Ruby. Likewise, the @vpiIntVal@ constant in C becomes the @VpiIntVal@ constant in Ruby.
+
+* The VPI functions @vpi_vprintf@ and @vpi_mcd_vprintf@ are not made accessible to Ruby. However, this isn't a big problem because you can use Ruby's printf method instead.
+
+bq. The reason for this limitation is that some C compilers have trouble with pointers to the va_list type. For these compilers, the second line in the code shown below causes a "type mismatch" error.
+
+<code lang="c">
+void foo(va_list ap) {
+  va_list *p = &ap;
+}
+</code>
+
+
+h4(#background.org.vpi.util). VPI utility layer
+
+From a user's perspective, the VPI utility layer greatly enhances the ability to interact with handles. One simply invokes a handle's methods, which are carefully named in the following manner, to access either (1) its children or (2) its VPI properties.
+
+The children of a handle are simply the handles that are immediately contained within it in. For example, suppose that you had a Verilog module that contains some registers. The children, of a handle to the module, would be handles to the registers.
+
+In the event that a child handle has the same name as a VPI property, the child is given priority. However, you can always access VPI properties explicitly via the @Vpi::Handle.get_value@ and @Vpi::Handle.put_value@ methods.
+
+
+<% figure "Parts of speech for accessing a handle's VPI properties" do %>
+|_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum |
+|\2. optional       | required   |\3. optional                   |
+
+* *Operation* suggests a method that should be invoked in the context of the Property parameter.
+
+* *Property* suggests a VPI property that should be accessed. The "vpi" prefix, which is common to all VPI properties, can be omitted if you wish. For example, the VPI property "vpiFullName" is considered equivalent to "fullName" and "FullName", but not equivalent "full_name".
+
+* *Accessor* suggests a VPI function that should be used in order to access the VPI property. When this parameter is not specified, the VPI utility layer will attempt to _guess_ the value of this parameter ("see the source code":../ref/ruby/classes/Vpi/Handle/Property.html of the @Property.resolve@ method for details).
+
+* *Addendum* suggests that the specified VPI property should be queried as a boolean value when it is a question mark (?). This suggestion is the same as specifying "b" for the Accessor parameter. Also, when this parameter is an equal sign (=), it suggests that the specified VPI property should be written to.
+<% end %>
+
+<% table "Possible accessors and their implications" do %>
+|_. Accessor |_. Kind of value accessed |_. VPI functions used to access the value |
+| d | delay | @vpi_get_delays@, @vpi_put_delays@ |
+| l | logic | @vpi_get_value@, @vpi_put_value@ |
+| i | integer | @vpi_get@ |
+| b | boolean | @vpi_get@ |
+| s | string | @vpi_get_str@ |
+| h | handle | @vpi_handle@ |
+<% end %>
+
+<% example "Examples of accessing a handle's VPI properties" do %>
+|_/2. Ruby expression |_\6. Parts of speech |_/2. Description |
+||_. Operation |_. _ |_. Property |_. _ |_. Accessor |_. Addendum ||
+| @handle.vpiIntVal@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; |  &nbsp; | &nbsp; |/4. These expressions access the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal_l@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | &nbsp; |
+| @handle.intVal@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | &nbsp; |
+| @handle.intVal_l@ | &nbsp; | &nbsp; | intVal | _ | l | &nbsp; |
+| @handle.vpiIntVal = 15@ | &nbsp; | &nbsp; | vpiIntVal | &nbsp; | &nbsp; | = |/4. These expressions assign the number 15 to the logic value of the handle's vpiIntVal property. |
+| @handle.vpiIntVal_l = 15@ | &nbsp; | &nbsp; | vpiIntVal | _ | l | = |
+| @handle.intVal = 15@ | &nbsp; | &nbsp; | intVal | &nbsp; | &nbsp; | = |
+| @handle.intVal_l = 15@ | &nbsp; | &nbsp; | intVal | _ | l | = |
+| @handle.vpiType@ | &nbsp; | &nbsp; | vpiType | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the integer value of the handle's vpiType property. |
+| @handle.vpiType_i@ | &nbsp; | &nbsp; | vpiType | _ | i | &nbsp; |
+| @handle.type@ | &nbsp; | &nbsp; | type | &nbsp; | &nbsp; | &nbsp; |
+| @handle.type_i@ | &nbsp; | &nbsp; | type | _ | i | &nbsp; |
+| @handle.vpiProtected@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | &nbsp; |/6. These expressions access the boolean value of the handle's vpiProtected property. |
+| @handle.vpiProtected_b@ | &nbsp; | &nbsp; | vpiProtected | _ | b | &nbsp; |
+| @handle.vpiProtected?@ | &nbsp; | &nbsp; | vpiProtected | &nbsp; | &nbsp; | ? |
+| @handle.protected@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | &nbsp; |
+| @handle.protected_b@ | &nbsp; | &nbsp; | protected | _ | b | &nbsp; |
+| @handle.protected?@ | &nbsp; | &nbsp; | protected | &nbsp; | &nbsp; | ? |
+| @handle.vpiFullName@ | &nbsp; | &nbsp; | vpiFullName | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the string value of the handle's vpiFullName property. |
+| @handle.vpiFullName_s@ | &nbsp; | &nbsp; | vpiFullName | _ | s | &nbsp; |
+| @handle.fullName@ | &nbsp; | &nbsp; | fullName | &nbsp; | &nbsp; | &nbsp; |
+| @handle.fullName_s@ | &nbsp; | &nbsp; | fullName | _ | s | &nbsp; |
+| @handle.vpiParent@ | &nbsp; | &nbsp; | vpiParent | &nbsp; | &nbsp; | &nbsp; |/4. These expressions access the handle value of the handle's vpiParent property. |
+| @handle.vpiParent_h@ | &nbsp; | &nbsp; | vpiParent | _ | h | &nbsp; |
+| @handle.parent@ | &nbsp; | &nbsp; | parent | &nbsp; | &nbsp; | &nbsp; |
+| @handle.parent_h@ | &nbsp; | &nbsp; | parent | _ | h | &nbsp; |
+| <code>handle.each_vpiNet {|net| puts net.fullName}</code> | each | _ | vpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions print the full name of each vpiNet object associated with the handle. |
+| <code>handle.each_net {|net| puts net.fullName}</code> | each | _ | net | &nbsp; | &nbsp; | &nbsp; |
+| <code>handle.all_vpiReg? {|reg| reg.size == 1}</code> | all? | _ | vpiReg | &nbsp; | &nbsp; | &nbsp; |/2. These expressions check if all registers associated with the handle are capable of storing only one bit. |
+| <code>handle.all_reg? {|reg| reg.size == 1}</code> | all? | _ | reg | &nbsp; | &nbsp; | &nbsp; |
+| <code>handle.select_vpiNet {|net| net.x?}</code> | select | _ | VpiNet | &nbsp; | &nbsp; | &nbsp; |/2. These expressions return a list of nets whose logic value is unknown or "don't care" (x).|
+| <code>handle.select_net {|net| net.x?}</code> | select | _ | net | &nbsp; | &nbsp; | &nbsp; |
+<% end %>
+
+
+h2(#background.running-tests). Running a test
+
+Unlike an engineer who can verify an electronic component in real-time, the Verilog simulator and the Ruby interpreter (see <xref #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.
+
+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.
+
+
+h3(#background.running-tests.init). Initialization
+
+<% figure "Initialization of a test", "#fig..ruby_init" do %>
+!figures/ruby_init.png!
+<% end %>
+
+A test is first initialized before it is "executed":#background.running-tests.exec. <xref #fig..ruby_init> illustrates the initialization process "described below":#proc..ruby_init.
+
+# The Verilog simulator initializes the Ruby interpreter by invoking the @$ruby_init;@ system task/function, whose parameters represent the command-line invocation of the Ruby interpreter. For example, one would specify @$ruby_init("ruby", "-w");@ in Verilog to achieve the same effect as running <pre>ruby -w</pre> at a command-prompt.
+# The Verilog simulator is paused and the Ruby interpreter is initialized with the arguments of the @$ruby_init;@ system task/function.
+# When the Ruby interpreter invokes the @Vpi::relay_verilog@ method, it is paused and the Verilog simulator is given control.
+
+
+h3(#background.running-tests.exec). Execution
+
+After a test is "initialized":#background.running-tests.init, it is executed such that the design is verified against the specification. <xref #fig..ruby_relay> illustrates the execution process "described below":#proc..ruby_relay.
+
+<% figure "Execution of a test", "#fig..ruby_relay" do %>
+!figures/ruby_relay.png!
+<% end %>
+
+# The Verilog simulator transfers control to the Ruby interpreter by invoking the @$ruby_relay;@ system task/function.
+# The Verilog simulator is paused and the Ruby interpreter is given control.
+# When the Ruby interpreter invokes the @Vpi::relay_verilog@ method, it is paused and the Verilog simulator is given control.
+
+
+h1(#setup). Setup
+
+
+h2(#setup.manifest). Manifest
+
+When you extract a release package, the following is what you would expect to find.
+
+* <tt>doc</tt> contains user documentation in various formats.
+* <tt>ref</tt> contains reference API documentation in HTML format.
+* <tt>ext</tt> contains source code, written in the C language, for the "core of Ruby-VPI":#background.org.
+* <tt>lib</tt> contains Ruby libraries provided by Ruby-VPI.
+* <tt>bin</tt> contains various tools. See <xref #usage.tools> for more information.
+* <tt>samp</tt> contains example tests. See <xref #usage.examples> for more information.
+
+
+h2(#setup.reqs). Requirements
+
+The following software is necessary in order to use Ruby-VPI.
+
+* Verilog simulator
+  - Ruby-VPI is known to work with the following simulators. However, you should be able to use it with any Verilog simulator that supports VPI.
+** "GPL Cver":http://www.pragmatic-c.com/gpl-cver/
+  - version 2.11a or newer is acceptable.
+** "Icarus Verilog":http://www.icarus.com/eda/Verilog/
+  - version 0.8 or newer is acceptable.
+** "Synopsys VCS":http://www.synopsys.com/products/simulation/simulation.html
+  - any version that supports the <tt>-load</tt> option is acceptable.
+** "Mentor Modelsim":http://www.model.com
+  - any version that supports the <tt>-pli</tt> option is acceptable.
+
+* *make*
+  - any distribution should be acceptable.
+
+* C compiler
+  - the "GNU Compiler Collection (GCC)":http://www.gnu.org/software/gcc/ is preferred, but any C compiler should be acceptable.
+
+* "POSIX threads (pthreads)":http://en.wikipedia.org/wiki/Pthreads
+  - header and linkable object files, and operating system support for this library are necessary.
+
+* "Ruby":http://www.ruby-lang.org
+  - version 1.8 or newer, including header and linkable object files for building extensions, is necessary. You can install Ruby by following "these instructions":http://www.rubygarden.org/faq/section/show/3.
+
+* "RubyGems":http://rubyforge.org/frs/?group_id=126
+  - any recent version should be acceptable. You can install RubyGems by following "these instructions":http://www.rubygems.org/read/chapter/3.
+
+
+h2(#setup.recom). Recommendations
+
+The following software may make your interactions with Ruby-VPI more pleasant.
+
+
+h3(#setup.recom.merger). Text merging tool
+
+An _interactive_ text merging tool can greatly simplify the process of transferring wanted changes from one file to another. In particular, such tools are especially beneficial when using the "automated test generator":#usage.tools.generate-test. A handful of the currently available open-source text merging tools are listed below.
+** "*kdiff3*":http://kdiff3.sourceforge.net/ is a graphical, three-way merging tool for KDE.
+** "*meld*":http://meld.sourceforge.net/ is a graphical, three-way merging tool for GNOME.
+** "*tkdiff*":http://tkdiff.sourceforge.net/ is a graphical, two-way merging tool that uses the cross-platform Tk windowing toolkit.
+** "*xxdiff*":http://furius.ca/xxdiff/ is a graphical, three-way merging tool.
+** "*imediff2*":http://elonen.iki.fi/code/imediff/ is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via SSH.
+
+
+h2(#setup.installation). Installation
+
+Once you have satisfied the "necessary requirements":#setup.reqs, you can install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a "gems" subdirectory which contains the Ruby-VPI installation, as illustrated below.
+
+<pre>
+$ gem env gemdir
+/usr/lib/ruby/gems/1.8
+
+$ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
+/usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
+</pre>
+
+
+h3(#setup.installation.windows). Installing on Windows
+
+* Install "Cygwin":http://www.cygwin.com, the Linux-like environment for Windows.
+
+* Search for object files whose names end with <tt>.so</tt>, <tt>.o</tt>, or <tt>.dll</tt> in your Verilog simulator's installation directory.
+
+* Determine which object files, among those found in the previous step, contain symbols whose names begin with "_vpi" by running the <pre>for x in *.{o,so,dll}; do nm $x | grep -q '[Tt] _vpi' > /dev/null && echo $x; done</pre> command in Cygwin.
+** If you are using Mentor Modelsim, the desired object file can be found at a path similar to <tt>C:\Modeltech\win32\libvsim.dll</tt>.
+** If you are using GPL Cver, the desired object file can be found at a path similar to <tt>C:\gplcver\objs\v_vpi.o</tt>.
+
+<% note do %>
+Since Ruby-VPI makes use of the VPI C-language interface, it links to symbols whose names begin with "_vpi". It is possible for these symbols to be undefined when Ruby-VPI is compiled under GNU/Linux and similar operating systems. In contrast, one "cannot compile a shared object file with references to undefined symbols under Windows":http://sourceware.org/ml/cygwin/2001-12/msg01293.html. Thus, we must find a Verilog simulator's shared object file, which contains definitions of all VPI symbols, and give this file to the linker when compiling Ruby-VPI.
+<% end %>
+
+* Assign the path of the object file (determined in the previous step) to the @LDFLAGS@ environment variable. For example, if the object file's path is <tt>/foo/bar/vpi.so</tt>, then you would run the <pre>export LDFLAGS=/foo/bar/vpi.so</pre> command in Cygwin.
+
+* You may now install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command in Cygwin.
+
+
+h2(#setup.maintenance). Maintenance
+
+* You can uninstall Ruby-VPI by running the <pre>gem uninstall ruby-vpi</pre> command.
+* You can upgrade to the latest release of Ruby-VPI by running the <pre>gem update ruby-vpi</pre> command.
+
+<% note do %>
+Learn more about using and manipulating RubyGems in "the RubyGems user manual":http://www.rubygems.org.
+<% end %>
+
+
+h1(#usage). Usage
+
+h2(#usage.tools). Tools
+
+The <tt>bin</tt> directory contains various utilities which ease the process of writing tests. Each tool provides help and usage information invoked with the <tt>--help</tt> option.
+
+
+h3(#usage.tools.generate-test). Automated test generation
+
+The automated test generator (*generate_test.rb*) generates tests from Verilog 2001 module declarations, as demonstrated "in the tutorial":#usage.tutorial.generate-test. A generated test is composed of the following parts:
+
+* Runner
+  - written in Rake, this file builds and runs the test.
+* Bench
+  - written in Verilog and Ruby, these files define the testing environment.
+* Design
+  - written in Ruby, this file provides an interface to the design being verified.
+* Prototype
+  - written in Ruby, this file defines a prototype of the design being verified.
+* Specification
+  - written in Ruby, this file describes the expected behavior of the design.
+
+The reason for dividing a single test into these parts is mainly to decouple the design from the specification. This allows you to focus on writing the specification while the remainder is automatically generated by the tool. For example, when the interface of a Verilog module changes, you would simply re-run this tool and incorporate those changes (using a "text merging tool":#setup.recom) into the test without diverting your focus from the specification.
+
+<% tip "Using *kdiff3* with the automated test generator." do %>
+# Create a file named <tt>merge2</tt> with the following content: <code>
+#!/bin/sh
+# args: old file, new file
+kdiff3 --auto --output "$2" "$@"
+</code>
+# Make the file executable by running the <pre>chmod +x merge2</pre> command.
+# Place the file somewhere accessible by your @PATH@ environment variable.
+# Assign the value "merge2" to the @MERGER@ environment variable using your shell's *export* or *setenv* command.
+
+From now on, *kdiff3* will be invoked to help you transfer your changes between generated files. When you are finished transferring changes, simply issue the "save the file" command and terminate *kdiff3*. Or, if you do not want to transfer any changes, simply terminate *kdiff3*.
+<% end %>
+
+
+h3(#usage.tools.verilog-ruby-conv). Verilog to Ruby conversion
+
+The *header_to_ruby.rb* tool can be used to convert Verilog header files into Ruby. You can try it by running the <pre>header_to_ruby.rb --help</pre> command.
+
+
+h2(#usage.tutorial). Tutorial
+
+# "Declare the design":#usage.tutorial.declare-design, which is a Verilog module, using Verilog 2001 syntax.
+# "Generate a test":#usage.tutorial.generate-test for the design using the "automated test generator":#usage.tools.generate-test tool.
+# "Identify your expectations":#usage.tutorial.specification for the design and implement them in the specification.
+# (Optional) "Implement the prototype":#usage.tutorial.implement-proto of the design in Ruby.
+# (Optional) "Verify the prototype":#usage.tutorial.test-proto against the specification.
+# "Implement the design":#usage.tutorial.implement-design in Verilog once the prototype has been verified.
+# "Verify the design":#usage.tutorial.test-design against the specification.
+
+
+h3(#usage.tutorial.declare-design). Start with a design
+
+First, we need a "design":#glossary.design to verify. In this tutorial, <xref #fig..counter.v_decl> will serve as our design. Its interface is composed of the following parts:
+
+* @Size@ defines the number of bits used to represent the counter's value.
+* @clock@ causes the @count@ register to increment whenever it reaches a positive edge.
+* @reset@ causes the @count@ register to become zero when asserted.
+* @count@ is a register that contains the counter's value.
+
+<% example "Declaration of a simple up-counter with synchronous reset", "#fig..counter.v_decl" do %>
+<code lang="verilog">
+module counter #(parameter Size = 5) (
+  input clock,
+  input reset,
+  output reg [Size - 1 : 0] count
+);
+endmodule
+</code>
+<% end %>
+
+<% important "Before we continue..." do %>
+Save the source code shown in <xref #fig..counter.v_decl> into a file named <tt>counter.v</tt>.
+<% end %>
+
+
+h3(#usage.tutorial.generate-test). Generate a test
+
+Now that we have a "design":#glossary.design to verify, let us generate a "test":#glossary.test for it using the "automated test generator":#usage.tools.generate-test. This tool allows us to implement our specification in either rSpec, xUnit, or our very own format.
+
+Each format represents a different software development methodology:
+* rSpec represents "BDD":#glossary.BDD
+* xUnit represents "TDD":#glossary.TDD
+* our own format can represent another methodology
+
+Both rSpec and xUnit are presented in this tutorial.
+
+Once we have decided how we want to implement our specification, we can proceed to generate a test for our design. <xref #fig..generate-test.rspec> and <xref #fig..generate-test.unit-test> illustrate this process.
+
+<% example "Generating a test with specification in rSpec format", "#fig..generate-test.rspec" do %>
+<pre>
+$ generate_test.rb counter.v --rspec --name 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
+</pre>
+<% end %>
+
+<% example "Generating a test with specification in xUnit format", "#fig..generate-test.unit-test" do %>
+<pre>
+$ generate_test.rb counter.v --xunit --name 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
+</pre>
+<% end %>
+
+
+h3(#usage.tutorial.specification). Specify your expectations
+
+So far, the test generation tool has created a basic foundation for our "test":#glossary.test. Now we must build upon this foundation by identifying our "expectation":#glossary.expectation of the "design":#glossary.design. That is, how do we expect the design to _behave_ under certain conditions?
+
+Here are some reasonable expectations for our simple counter:
+* A resetted counter's value should be zero.
+* A resetted counter's value should increment by one count upon each rising clock edge.
+* A counter with the maximum value should overflow upon increment.
+
+Now that we have identified a set of expectations for our design, we are ready to implement them in our specification. <xref #fig..counter_rspec_spec.rb> and <xref #fig..counter_xunit_spec.rb> illustrate this process. Note the striking similarities between our expectations and their implementation.
+
+
+<% example "Specification implemented in rSpec format", "#fig..counter_rspec_spec.rb" do %>
+<code><%= File.read '../samp/counter/counter_rspec_spec.rb' %></code>
+<% end %>
+
+<% example "Specification implemented in xUnit format", "#fig..counter_xunit_spec.rb" do %>
+<code><%= File.read '../samp/counter/counter_xunit_spec.rb' %></code>
+<% end %>
+
+<% important "Before we continue..." do %>
+# Replace the contents of the file named <tt>counter_rspec_spec.rb</tt> with the source code shown in <xref #fig..counter_rspec_spec.rb>.
+# Replace the contents of the file named <tt>counter_xunit_spec.rb</tt> with the source code shown in <xref #fig..counter_xunit_spec.rb>.
+# Replace the contents of the files named <tt>counter_rspec_design.rb</tt> and <tt>counter_xunit_design.rb</tt> with the following code. This code defines the reset! method which resets our Verilog design. <code>
+def Counter.reset!
+  reset.intVal = 1
+
+  # simulate one clock cycle
+  relay_verilog
+
+  reset.intVal = 0
+end
+</code>
+<% end %>
+
+
+h3(#usage.tutorial.implement-proto). Implement the prototype
+
+
+Now that we have a "specification":#glossary.specification against which to verify our "design":#glossary.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. <xref #fig..counter_proto.rb> shows the completed prototype for our design.
+
+
+<% example "Ruby prototype of our Verilog design", "#fig..counter_proto.rb" do %>
+<code>
+def Counter.simulate!
+  if reset.intVal == 1
+    count.intVal = 0
+  else
+    count.intVal += 1
+  end
+end
+</code>
+<% end %>
+
+<% important "Before we continue..." do %>
+Replace the contents of the files named <tt>counter_rspec_proto.rb</tt> and <tt>counter_xunit_proto.rb</tt> with the source code shown in <xref #fig..counter_proto.rb>
+<% end %>
+
+
+h3(#usage.tutorial.test-proto). Verify the prototype
+
+Now that we have implemented our prototype, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. <xref #fig..test-proto.rspec> and <xref #fig..test-proto.unit-test> illustrate this process.
+
+<% tip "Reuse your specification." do %>
+The _same_ specification can be used to verify both prototype and design.
+<% end %>
+
+Here, the @PROTOTYPE@ environment variable is assigned a non-empty value while running the test, so that, instead of our design, our prototype is verified against our specification. You can also assign a value to @PROTOTYPE@ before running the test, by using your shell's *export* or *setenv* command. Finally, the Icarus Verilog simulator, denoted by _cver_, is used to run the simulation.
+
+<% tip "What can the test runner do?" do %>
+If you invoke the test runner (1) without any arguments or (2) with the <tt>-T</tt> option, it will show you a list of tasks that it can perform for you.
+<% end %>
+
+<% example "Running a test with specification in rSpec format", "#fig..test-proto.rspec" do %>
+<pre>
+$ rake -f counter_rspec_runner.rake cver PROTOTYPE=1
+
+Ruby-VPI: prototype has been enabled for test "counter_rspec"
+
+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
+</pre>
+<% end %>
+
+<% example "Running a test with specification in xUnit format", "#fig..test-proto.unit-test" do %>
+<pre>
+$ rake -f counter_xunit_runner.rake cver PROTOTYPE=1
+
+Ruby-VPI: prototype has been enabled for test "counter_xunit"
+
+Loaded suite counter_xunit_bench
+Started
+...
+Finished in 0.040668 seconds.
+
+3 tests, 35 assertions, 0 failures, 0 errors
+</pre>
+<% end %>
+
+
+h3(#usage.tutorial.implement-design). Implement the design
+
+Now that we have implemented and verified our prototype, we are ready to implement our "design":#glossary.design. This is often quite simple because we translate _existing_ code from Ruby (our prototype) into Verilog (our design). <xref #fig..counter.v_impl> illustrates the result of this process. Once again, note the striking similarities between the implementation of our prototype and design.
+
+
+<% example "Implementation of a simple up-counter with synchronous reset", "#fig..counter.v_impl" do %>
+<code lang="verilog"><%= File.read '../samp/counter/counter.v' %></code>
+<% end %>
+
+<% important "Before we continue..." do %>
+Replace the contents of the file named <tt>counter.v</tt> with the source code shown in <xref #fig..counter.v_impl>
+<% end %>
+
+
+h3(#usage.tutorial.test-design). Verify the design
+
+Now that we have implemented our "design":#glossary.design, we are ready to verify it against our "specification":#glossary.specification by running the "test":#glossary.test. <xref #fig..test-design.rspec> and <xref #fig..test-design.unit-test> illustrate this process.
+
+Here, the @PROTOTYPE@ environment variable is _not_ specified while running the test, so that our design, instead of our prototype, is verified against our specification. You can also achieve this effect by assigning an empty value to @PROTOTYPE@, or by using your shell's *unset* command. Finally, the GPL Cver Verilog simulator, denoted by _cver_, is used to run the simulation.
+
+<% tip "Running multiple tests at once." do %>
+Create a file named <tt>Rakefile</tt> containing the following line.
+
+bq. @require 'ruby-vpi/runner_proxy'@
+
+Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where _cver_ denotes the GPL Cver simulator).
+<% end %>
+
+<% example "Running a test with specification in rSpec format", "#fig..test-design.rspec" do %>
+<pre>
+$ rake -f counter_rspec_runner.rake cver
+
+A resetted counter's value
+- should be zero
+- should increment by one count upon each rising clock edge
+
+A counter with the maximum value
+- should overflow upon increment
+
+Finished in 0.005628 seconds
+
+3 specifications, 0 failures
+</pre>
+<% end %>
+
+<% example "Running a test with specification in xUnit format", "#fig..test-design.unit-test" do %>
+<pre>
+$ rake -f counter_xunit_runner.rake cver
+
+Loaded suite counter_xunit_bench
+Started
+...
+Finished in 0.006766 seconds.
+
+3 tests, 35 assertions, 0 failures, 0 errors
+</pre>
+<% end %>
+
+
+h2(#usage.examples). Examples
+
+The <tt>samp</tt> directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
+
+Also, some example specifications make use of BDD through the rSpec library. See <xref #background.methodology> for a discussion of rSpec.
+
+
+h1(#hacking). Hacking
+
+h2(#hacking.release-packages). Building release packages
+
+In addition to the "normal requirements":./doc/usage.requirements.html, you need the following software to build release packages:
+
+* "SWIG":http://www.swig.org/
+* "RedCloth":http://rubyforge.org/projects/redcloth/
+* "CodeRay":http://rubyforge.org/projects/coderay/
+
+Once you have satisfied these requirements, you can run <pre>rake release</pre> to build the release packages. Also, see the output of <pre>rake -T</pre> for more build options.
+
+
+h1(#problems). Known problems
+
+This chapter presents known problems and possible solutions. In addition, previously solved problems have been retained for historical reference.
+
+
+h2(#problems.ruby). Ruby
+
+
+h3(#problems.ruby.SystemStackError). SystemStackError
+
+<%= @fixed_in_2_0_0 %>
+
+If a "stack level too deep (SystemStackError)" error occurs during the simulation, then increase the system-resource limit for stack-size by running the <pre>ulimit -s unlimited</pre> command before starting the simulation.
+
+
+h3(#problems.ruby.xUnit). test/unit
+
+<%= @fixed_in_2_0_0 %>
+
+If your specification employs Ruby's unit testing framework, then you will encounter an error saying "[BUG] cross-thread violation on rb_gc()".
+
+
+h2(#problem.ivl). Icarus Verilog
+
+
+h3(#problems.ivl.vpi_handle_by_name). Vpi::vpi_handle_by_name
+
+
+h4(#problems.ivl.vpi_handle_by_name.absolute-paths). Give full paths to Verilog objects
+
+In version 0.8 and snapshot 20061009 of Icarus Verilog, the @vpi_handle_by_name@ function requires an _absolute_ path (including the name of the bench which instantiates the design) to a Verilog object. In addition, @vpi_handle_by_name@ is unable to retrieve the handle for a module parameter.
+
+For example, consider <xref #ex..TestFoo> Here, one needs to specify @TestFoo.my_foo.clk@ instead of @my_foo.clk@ in order to access the clk input of the my_foo module instance.
+
+<% example "Part of a bench which instantiates a Verilog design", "#ex..TestFoo" do %>
+<code lang="verilog">
+module TestFoo;
+  reg clk_reg;
+  Foo my_foo(.clk(clk_reg));
+endmodule
+</code>
+<% end %>
+
+h4(#problems.ivl.vpi_handle_by_name.connect-registers). Registers must be connected
+
+In version 0.8 of Icarus Verilog, 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 @nil@ value as the result of @vpi_handle_by_name@ method.
+
+For example, suppose you wanted to access the @clk_reg@ register, from the bench shown in <xref #ex..TestFoo_bad> If you execute the statement @clk_reg = vpi_handle_by_name("TestFoo.clk_reg", nil)@ in a specification, then you will discover that the @vpi_handle_by_name@ method returns @nil@ instead of a handle to the @clk_reg@ register.
+
+The solution is to change the design such that it appears like the one shown in <xref #ex..TestFoo_fix> where the register is connected to a wire, or <xref #ex..TestFoo> where the register is connected to a module instantiation.
+
+<% example "Bad design with unconnected registers", "#ex..TestFoo_bad" do %>
+<code lang="verilog">
+module TestFoo;
+  reg clk_reg;
+endmodule
+</code>
+
+Here the @clk_reg@ register is not connected to anything.
+<% end %>
+
+<% example "Fixed design with wired registers", "#ex..TestFoo_fix" do %>
+<code lang="verilog">
+module TestFoo;
+  reg clk_reg;
+  wire clk_wire;
+  assign clk_wire = clk_reg;
+endmodule
+</code>
+
+Here the @clk_reg@ register is connected to the @clk_wire@ wire.
+<% end %>
+
+
+h3(#problems.ivl.vpi_reset). Vpi::reset
+
+<div class="caution">The @vpi_control@ method was removed in release 3.0.0 (2006-04-23). Please use @Vpi::vpi_control(VpiReset)@ instead.</div>
+
+In version 0.8 of Icarus Verilog, the @vpi_control(vpiReset)@ VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.
+
+
+h2(#problems.vsim). Mentor Modelsim
+
+
+h3(#problems.vsim.ruby_run). ruby_run();
+
+<%= @fixed_in_2_0_0 %>
+
+Version 6.1b of Mentor Modelsim doesn't play nicely with either an embedded Ruby interpreter or POSIX threads in a PLI application. When Ruby-VPI invokes the ruby_run function (which starts the Ruby interpreter), the simulator terminates immediately with an exit status of 0.
+
+
+h1(#glossary). Glossary
+
+
+h2(#glossary.bench). Bench
+
+An environment in which a "design":#glossary.design is verified against a "specification":#glossary.specification. Often, it is used to emulate conditions in which the design will be eventually deployed.
+
+
+h2(#glossary.BDD). BDD
+
+Behavior driven development.
+
+A software development methodology which emphasizes thinking in terms of behavior when designing, implementing, and verifying software. See the "official wiki":http://behaviour-driven.org/ for more information.
+
+
+h2(#glossary.design). Design
+
+An idea or entity that is verified against a "specification":#glossary.specification in order to ensure correctness or soundness of its being. In other words, it is the thing being checked: does it work or not?
+
+
+h2(#glossary.expectation). Expectation
+
+The desired response to some stimulus.
+
+
+h2(#glossary.handle). Handle
+
+An object in a Verilog simulation. For example, a handle can represent a wire, register, module, if-statement, expression, and so on.
+
+
+h2(#glossary.rake). Rake
+
+bq. Rake is a build tool, written in Ruby, using Ruby as a build language. Rake is similar to make in scope and purpose. -- "Rake documentation":http://docs.rubyrake.org
+
+See the "Rake website":http://rake.rubyforge.org for more information.
+
+
+h2(#glossary.rspec). rSpec
+
+Ruby framework for BDD. See the "rSpec website":http://rspec.rubyforge.org and "tutorial":http://rspec.rubyforge.org/tutorials/index.html for more information.
+
+
+h2(#glossary.specification). Specification
+
+A set of "expectation":#glossary.expectations which define the desired behavior of a "design":#glossary.design when it is subjected to certain conditions.
+
+
+h2(#glossary.TDD). TDD
+
+Test Driven Development.
+
+
+h2(#glossary.test). Test
+
+Something that checks if a "design":#glossary.design satisfies a "specification":#glossary.specification.
+
+
+h2(#glossary.test_bench). Test bench
+
+An allusion to "a bench in an electronics laboratory":#background.vocab, or so it seems.