ruby-vpi 15.0.2 → 16.0.0

data/doc/images/ruby/LICENSE

@@ -0,0 +1,15 @@
+The Ruby Logo is Copyright (c) 2006, Yukihiro Matsumoto. It is licensed
+under the terms of the Creative Commons Attribution-ShareAlike 2.5
+agreement:
+
+http://creativecommons.org/licenses/by-sa/2.5/
+
+We ask that you do not use the logo to represent something other than
+the Ruby Programming language. If you have questions about the logo,
+please join the VIT-Discuss mailing list and ask your questions there:
+
+http://rubyforge.org/mailman/listinfo/vit-discuss/
+
+Thank you,
+
+The Ruby Visual Identity Team

data/doc/intro.inc

@@ -1,5 +1,29 @@
-Ruby-VPI is a "Ruby":http://www.ruby-lang.org interface to "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945. It lets you create complex Verilog test benches easily and wholly in Ruby.
+Ruby-VPI is a platform for unit testing, rapid prototyping, and systems integration of Verilog modules through the "Ruby programming language":http://www.ruby-lang.org. It lets you:
 
+* Access the _entire_ "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 interface from Ruby.
+* Create complex Verilog test benches easily and wholly in Ruby.
+* Apply agile software development practices to develop hardware.
+* Perform "specification-driven functional verification":http://ruby-vpi.rubyforge.org/papers/masters_thesis.html ("PDF version":http://ruby-vpi.rubyforge.org/papers/masters_thesis.pdf).
+
+Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_software released under "this license":#intro.license.
+
+
+<div id="resources">
+
+h2. Resources
+
+p(title). Records
+
+<a type="application/rss+xml" href="<%= RSS_URL %>"><img src="images/feed-icon-28x28.png" alt="RSS feed for release notifications" style="float: right"/></a>
+
+* "What's new?":history.html
+  - a record of all release notes.
+* "Plans":memo.html
+  - pending tasks for future releases.
+* "Talks":http://ruby-vpi.rubyforge.org/talks/
+  - materials from presentations and seminars.
+* "Papers":http://ruby-vpi.rubyforge.org/papers/
+  - research publications.
 
 p(title). Documentation
 
@@ -10,53 +34,36 @@ p(title). Documentation
 * "Reference":../ref/
   - API documentation for Ruby libraries and C extension.
 
-
-p(title). Records
-
-* <a type="application/rss+xml" href="<%= RSS_URL %>">!images/feed-icon.png(RSS feed icon)! RSS feed</a>
-  - keep track of new releases at your leisure.
-* "Release history":history.html
-  - record of all release notes.
-* "Memorandum":memo.html
-  - pending tasks for future releases.
-
-
 p(title). Facilities
 
-* "Project portal":http://rubyforge.org/projects/ruby-vpi
-  - hosted generously by "RubyForge":http://rubyforge.org.
-* "Source code":http://ruby-vpi.rubyforge.org/src/ruby-vpi
-  - browse online or obtain through "Darcs":http://abridgegame.org/darcs/.
 * "Downloads":http://rubyforge.org/frs/?group_id=1339
   - obtain release packages.
+* "Source code":http://ruby-vpi.rubyforge.org/src/ruby-vpi
+  - browse online or obtain with "Darcs":http://darcs.net.
+* "Forums":http://rubyforge.org/forum/?group_id=1339
+  - discuss things and ask questions.
 * "Bugs":http://rubyforge.org/tracker/?group_id=1339
   - report defects in the software.
 * "Patches":http://rubyforge.org/tracker/?group_id=1339
   - submit patches to source code.
 * "Requests":http://rubyforge.org/tracker/?group_id=1339
   - request new features or get support.
-* "Forums":http://rubyforge.org/forum/?group_id=1339
-  - discuss things and ask questions.
-
-
-p(title). Outreach
+* "Project portal":http://rubyforge.org/projects/ruby-vpi
+  - hosted generously by "RubyForge":http://rubyforge.org.
 
-* "News":http://ruby-vpi.rubyforge.org/news
-  - see what's cooking for the next release.
-* "Talks":http://ruby-vpi.rubyforge.org/talks
-  - materials from presentations and seminars.
 
+</div>
 
-h2(#intro.features). Prominent features
 
-h3. Portable
+h2(#intro.features). Features
 
-* Supports the _entire_ "IEEE Std 1364-2005":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 VPI standard.
+p(title). Portable
 
-* Works with all "major Verilog simulators":manual.html#setup.reqs available today.
-** Compiled _just once_ during "installation":manual.html#setup.installation and used forever!
+* Supports the _entire_ "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 standard.
+* Works with all "major Verilog simulators":#intro.reqs available today.
+* Compiled _just once_ during "installation":manual.html#setup.installation and used forever!
 
-h3. Agile
+p(title). Agile
 
 * Enables "agile practices":http://agilemanifesto.org/ such as
 ** "test-driven":http://www.testdriven.com development
@@ -68,7 +75,7 @@ h3. Agile
 ** The "automated test generator":manual.html#usage.tools.generate-test helps you accomodate design changes with _minimal_ effort.
 ** There is absolutely _no compiling_!
 
-h3. Powerful
+p(title). Powerful
 
 * Inherits the "power and elegance":http://www.ruby-lang.org/en/about/ of Ruby:
 ** Unlimited length integers
@@ -80,14 +87,53 @@ h3. Powerful
 * Uses "ruby-debug":http://rubyforge.org/projects/ruby-debug/ for "interactive debugging":manual.html#usage.debugger.
 * Uses "rcov":http://eigenclass.org/hiki.rb?rcov for test "coverage analysis and report generation":manual.html#usage.test-runner.env-vars.
 
-h3. Free
 
-* 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.reqs). Requirements
+
+The following software is necessary in order to use Ruby-VPI.
+
+p(title). 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.
+
+* "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.
+
+* "Cadence NC-Sim / NC-Verilog":http://www.cadence.com/products/functional_ver/nc-verilog/
+ - any version that supports the <tt>+loadvpi</tt> option is acceptable.
+
+* "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 is _mostly_ acceptable -- you *will not* be able to "access child handles through method calls":manual.html#background.org.vpi.util. The reason for this limitation is explained "in the user manual":#problems.ivl.vpi_handle_by_name.absolute-paths.
+
+p(title). Compilers
+
+* "make":http://en.wikipedia.org/wiki/Make
+  - any flavor 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.
+
+* "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.
+
+p(title). Libraries
+
+* "POSIX threads (pthreads)":http://en.wikipedia.org/wiki/Pthreads
+  - header and linkable object files, and operating system support for this library are necessary.
+
+* "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(#intro.applications). Applications
 
-Here is a modest sampling of tasks that Ruby-VPI can be used to perform.
+Examples of tasks that can be performed with Ruby-VPI are:
 
 * From the second edition of "_The Verilog PLI Handbook_":http://www.sutherland-hdl.com/publications.html:
 ** C language bus-functional models
@@ -110,7 +156,7 @@ Here is a modest sampling of tasks that Ruby-VPI can be used to perform.
 
 h2(#intro.appetizers). Appetizers
 
-Here is a modest sampling of code to whet your appetite.
+Here is a tiny sampling of code to whet your appetite. See "the tutorial":manual.html#usage.tutorial for more samples.
 
 * Assign the value 2^2048^ to a register:
 
@@ -127,3 +173,26 @@ bq. @puts some_register@
 * Simulate fifteen clock cycles:
 
 bq. @15.times { simulate }@
+
+
+h2(#intro.license). License
+
+<%= File.read '../LICENSE' %>
+
+
+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.
+
+
+h3(#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.

data/doc/lib/doc_format.rb

@@ -1,22 +1,6 @@
-=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
+#--
+# Copyright 2006-2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
 
 require 'cgi'
 require 'rubygems'
@@ -24,29 +8,49 @@ require 'coderay'
 require 'redcloth'
 
 class String
-  # The content of these HTML tags will be preserved verbatim when they are processed by Textile.
+  # The content of these HTML tags will be preserved verbatim when they are
+  # processed by Textile.
   PRESERVED_TAGS = [:code, :tt]
 
   # Transforms this string into HTML.
   def to_html
     text = dup
 
-    # prevent the content of these tags from being transformed by Textile
-    # for example, Textile transforms quotation marks in code into curly ones ( ) -- this ruins any source code in the content of the tags!
+    # prevent the content of these tags from being transformed by Textile.
+    # for example, Textile transforms quotation marks in code into curly ones
+    # ( ) -- this ruins any source code in the content of the tags!
       PRESERVED_TAGS.each do |tag|
-        text.gsub! %r{<#{tag}(.*?)>(.*?)</#{tag}>}m, %{<pre tag=#{tag.inspect}\\1>\\2</pre>}
+        text.gsub! \
+          %r{<#{tag}(.*?)>(.*?)</#{tag}>}m,
+          %{<pre tag=#{tag.inspect}\\1>\\2</pre>}
       end
 
     html = text.redcloth
 
+    # redcloth wraps a single item within paragraph tags, which prevents the
+    # item's HTML from being validly injected within other block-level
+    # elements, such as headings (h1, h2, etc.)
+    html.sub! %r{^<p>(.*)</p>$}m do |match|
+      payload = $1
+
+      if payload =~ /<p>/
+        match
+      else
+        payload
+      end
+    end
+
     # restore the original tags for the preserved tags
-      # unescape content of <pre> tags because they may contain nested preserved tags (redcloth escapes the content of <pre> tags)
+      # unescape content of <pre> tags because they may contain nested
+      # preserved tags (redcloth escapes the content of <pre> tags)
         html.gsub! %r{(<pre>)(.*?)(</pre>)}m do
           $1 + CGI.unescapeHTML($2) + $3
         end
 
       PRESERVED_TAGS.each do |tag|
-        html.gsub! %r{<pre tag=#{tag.inspect}(.*?)>(.*?)</pre>}m, %{<#{tag}\\1>\\2</#{tag}>}
+        html.gsub! \
+          %r{<pre tag=#{tag.inspect}(.*?)>(.*?)</pre>}m,
+          %{<#{tag}\\1>\\2</#{tag}>}
       end
 
       # assume that indented text in Textile is NOT source code
@@ -65,10 +69,10 @@ class String
     RedCloth.new(self).to_html
   end
 
-  # Adds syntax coloring to <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.
+  # Adds syntax coloring to <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
@@ -93,4 +97,122 @@ class String
       %{<#{tag} class="code"#{atts}>#{html}</#{tag}>}
     end
   end
+
+
+  # Transforms this string into a valid XHTML anchor (ID attribute).
+  # See http://www.nmt.edu/tcc/help/pubs/xhtml/id-type.html
+  def to_html_anchor
+    # The first or only character must be a letter.
+      buf =
+        if self[0,1] =~ /[[:alpha:]]/
+          self
+        else
+          'a' + self
+        end
+
+    # The remaining characters must be letters, digits, hyphens (-),
+    # underscores (_), colons (:), or periods (.) [or Unicode characters]
+      buf.unpack('U*').map! do |code|
+        if code > 0xFF or code.chr =~ /[[:alnum:]\-_:\.]/
+          code
+        else
+          ?_
+        end
+      end.pack('U*')
+  end
+
+  @@anchors = []
+
+  # Resets the list of anchors encountered thus far.
+  def String.reset_anchors
+    @@anchors.clear
+  end
+
+  # Builds a table of contents from XHTML headings (<h1>, <h2>, etc.) found
+  # in this string and returns an array containing [toc, text] where:
+  #
+  # toc::   the generated table of contents
+  #
+  # text::  a modified version of this string which contains anchors for the
+  #         hyperlinks in the table of contents (so that the TOC can link to
+  #         the content in this string)
+  #
+  # If a block is given, it will be invoked every time a heading is found, with
+  # information about the found heading.
+  #
+  def table_of_contents
+    toc = '<ul>'
+    prevDepth = 0
+    prevIndex = ''
+
+    text = gsub %r{<h(\d)(.*?)>(.*?)</h\1>$}m do
+      depth, atts, title = $1.to_i, $2, $3.strip
+
+      # generate a LaTeX-style index (section number) for the heading
+        depthDiff = (depth - prevDepth).abs
+
+        index =
+          if depth > prevDepth
+            toc << '<li><ul>' * depthDiff
+
+            s = prevIndex + ('.1' * depthDiff)
+            s.sub(/^\./, '')
+
+          elsif depth < prevDepth
+            toc << '</ul></li>' * depthDiff
+
+            s = prevIndex.sub(/(\.\d+){#{depthDiff}}$/, '')
+            s.next
+
+          else
+            prevIndex.next
+
+          end
+
+        prevDepth = depth
+        prevIndex = index
+
+      # generate a unique HTML anchor for the heading
+        anchor = CGI.unescape(
+          if atts =~ /id=('|")(.*?)\1/
+            atts = $` + $'
+            $2
+          else
+            title
+          end
+        ).to_html_anchor
+
+        anchor << anchor.object_id.to_s while @@anchors.include? anchor
+        @@anchors << anchor
+
+      yield title, anchor, index, depth, atts if block_given?
+
+      # provide hyperlinks for traveling between TOC and heading
+        dst = anchor
+        src = dst.object_id.to_s.to_html_anchor
+
+        # forward link from TOC to heading
+        toc << %{<li><a id="#{src}" href="##{dst}">#{title}</a></li>}
+
+        # reverse link from heading to TOC
+        %{<h#{depth}#{atts}><a id="#{dst}" href="##{src}">#{index}</a> &nbsp; #{title}</h#{depth}>}
+    end
+
+    if prevIndex.empty?
+      toc = nil # there were no headings
+    else
+      toc << '</ul></li>' * prevDepth
+      toc << '</ul>'
+
+      # collapse redundant list elements
+      while toc.gsub! %r{(<li>.*?)</li><li>(<ul>)}, '\1\2'
+      end
+
+      # collapse unnecessary levels
+      while toc.gsub! %r{(<ul>)<li><ul>(.*)</ul></li>(</ul>)}, '\1\2\3'
+      end
+    end
+
+    [toc, text]
+  end
 end

data/doc/lib/doc_proxy.rb

@@ -1,31 +1,17 @@
-=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
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
 
 require 'erb_proxy'
+require 'doc_format'
 
-# Processes ERB templates to produce documentation. Templates may contain "<xref...>" tags where the ... represents the target anchor of the cross-reference.
+# 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, :index
   Index = Struct.new :name, :items
-  @@anchorNum = 0
 
   CATEGORIES = {
     :admonition => [:tip, :note, :important, :caution, :warning],
@@ -46,7 +32,7 @@ class DocProxy < ErbProxy
     CATEGORIES[:admonition].each do |type|
       add_block_handler :admonition, type do |index, title, text|
         join_redcloth_elements [
-          %{!<images/#{type}.png(#{type})!},
+          %{!<images/tango/#{type}.png(#{type})!},
           %{p(title). #{type.to_s.capitalize}: #{title}},
           text,
         ]
@@ -63,61 +49,28 @@ class DocProxy < ErbProxy
     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
-        head, depth, rest = $1, $2.to_i, $3
-
-        # parse title and class attributes
-          rest =~ /^([\{\(\[].*?[\]\)\}])?\.(.*)$/
-          atts, title = $1, $2.strip
-
-        # put heading index in title
-          prevDepth = @headings.last.depth rescue 0
-          prevIndex = @headings.last.index rescue ""
-          depthDiff = (depth - prevDepth).abs
-
-          index =
-            if depth > prevDepth
-              s = prevIndex + ('.1' * depthDiff)
-              s.sub /^\./, ''
-
-            elsif depth < prevDepth
-              s = prevIndex.sub /(\.\d+){#{depthDiff}}$/, ''
-              s.next
-
-            else
-              prevIndex.next
-            end
-
-          rest = "#{atts}. #{index} &nbsp; #{title}"
-
-        # parse and insert anchor if necessary
-          if atts =~ /#(.*?)\)/
-            anchor = $1
-          else
-            anchor = "anchor#{@@anchorNum += 1}"
-            rest.insert 0, "(##{anchor})"
-          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
+    text = aResult.to_html
+    anchors = []
 
+    # parse document structure and insert anchors (so that the table of contents
+    # can link directly to these headings) where necessary
+      toc, text = text.table_of_contents do |title, anchor, index, depth, atts|
         @headings << Heading.new(anchor, title, depth, index)
         @blocks[:section] << Block.new(anchor, title, :section)
-
-        head + rest
       end
 
     # expand cross-references into links to their targets
       blocks = @blocks.values.flatten
 
-      buffer.gsub! %r{<xref\s*(.+?)\s*/?>} do
+      text.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}}
+          %{<a href="##{target.anchor}">the #{target.type} named &ldquo;#{target.title}&rdquo;</a>}
         else
           warn "unresolved cross-reference to #{anchor}"
           %{"#{anchor}":##{anchor}}
@@ -138,14 +91,19 @@ class DocProxy < ErbProxy
         end
       end
 
-    buffer
+    [toc, text]
   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:
+  # 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?
 
@@ -175,7 +133,8 @@ class DocProxy < ErbProxy
 
   private
 
-  # Joins the given elements by putting enough white-space between them so that RedCloth knows they're different elements.
+  # 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") << "\n\n\n"
   end