ruby-vpi 13.0.0 → 14.0.0

data/doc/history.yml

@@ -1,3 +1,43 @@
+-
+  Version: 14.0.0
+
+  Date: 2006-12-30
+
+  Summary: |
+    This release adds support for simulation callbacks, renders Verilog benches _fully simplified_, and revises the user manual to reflect major changes.
+
+  Notice: |
+    * The @Vpi::relay_verilog@ method has been replaced by @Vpi::simulate@.
+
+      Please update you tests accordingly, because invoking the @Vpi::relay_verilog@ method directly will cause your tests to freeze/hang.
+
+    * Verilog benches no longer contain any clock generation code. They are now mere skeletons, whose _only_ purpose is to instantiate the design under test.
+
+      The clock generation code is now contained in the Ruby bench.
+
+    h3. New features
+
+    * The @RubyVpi::init_bench@ method now gives you _complete control_ over performing a clock/operation/whatever cycle for your design. This feature allows you to work with multi-clocked designs.
+
+    * Callbacks are now supported through the @Vpi::vpi_register_cb@ method. See "the callbacks section in the user manual":manual.html#usage.vpi.callbacks for details.
+
+    * Added the @Vpi::advance_time@ method, which makes the Verilog simulator simulate a given number of time steps.
+
+    * Added the @Vpi::simulation_time@ method, which gives you the current simulation time as a 64-bit integer.
+
+  Details: |
+    * Removed the monkey patch for the SWIG @va_list@ problem -- it no longer occurs.
+
+    * Cleansed the appearance of the user documentation.
+    ** Added indices to section headings, just like LaTeX.
+    ** Admonition boxes no longer interfere with surrounding text, and they don't have big gap above them.
+    ** Navigation menu is now elastic (fluid layout).
+
+    * Revised the user manual and added new content.
+    ** Moved "VPI utility layer" section from background chapter into usage chapter in user manual.
+    ** Added a nice introduction to entire manual with links to reference documentation.
+
+
 -
   Version: 13.0.0
 

data/doc/intro.inc

@@ -1,12 +1,16 @@
-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.
+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.
 
 
 h2(#intro.features). Features
 
+h3. Portable
+
 * Supports the _entire_ "IEEE Std 1364-2005"::http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 VPI standard.
 
 * Works with all "major Verilog simulators":manual.html#setup.reqs available today.
-** Compile _once_ (during "installation":manual.html#setup.installation) and use forever!
+** Compiled _just once_ during "installation":manual.html#setup.installation and used forever!
+
+h3. Agile
 
 * Enables "agile practices":http://agilemanifesto.org/ such as
 ** "test-driven":http://www.testdriven.com development
@@ -14,33 +18,51 @@ h2(#intro.features). Features
 ** "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.
+** "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.
+** There is absolutely _no compiling_!
+
+h3. Powerful
 
-* Utilizes the "power and elegance":http://www.ruby-lang.org/en/about/ of Ruby:
+* Inherits 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 infinitum_":http://rubyforge.org
 
+* 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.
 
 
-h3(#intro.applications). Applications
+h2(#intro.applications). Applications
+
+Here is a modest sampling of tasks that Ruby-VPI can be used to perform.
 
-Here is a modest sampling of tasks, paraphrased from "Pin Hong":http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/, that Ruby-VPI can be used to perform.
+* From the second edition of "_The Verilog PLI Handbook_":http://www.sutherland-hdl.com/publications.html:
+** C language bus-functional models
+** Reading test vector files
+** Delay calculation
+** Custom output displays
+** Co-simulation
+** Design debug utilities
+** Simulation analysis
 
-* Writing hardware models in Ruby
-* Dumping/processing netlist data from Verilog database
-* Dumping/processing simulation data
-* Feeding dynamic simulation stimuli
-* Back-annotating delay information
-* Interactive logic simulation
-* Building a distributed simulation
+* Adapted from "Pin Hong's":http://embedded.eecs.berkeley.edu/Alumni/pinhong/scriptEDA/ observations:
+** Writing hardware models in Ruby
+** Dumping or processing netlist data from Verilog database
+** Dumping or processing simulation data
+** Feeding dynamic simulation stimuli
+** Back-annotating delay information
+** Interactive logic simulation
+** Building a distributed simulation
 
 
-h3(#intro.appetizers). Appetizers
+h2(#intro.appetizers). Appetizers
 
 Here is a modest sampling of code to whet your appetite.
 
@@ -58,5 +80,5 @@ bq. @puts some_register@
 
 * Simulate fifteen clock cycles:
 
-bq. @15.times { relay_verilog }@
+bq. @15.times { simulate }@
 

data/doc/lib/doc_proxy.rb

@@ -23,7 +23,7 @@ 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
+  Heading = Struct.new :anchor, :title, :depth, :index
   @@anchorNum = 0
 
   CATEGORIES = {
@@ -67,12 +67,32 @@ class DocProxy < ErbProxy
 
     # 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, $3
+        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
@@ -81,7 +101,7 @@ class DocProxy < ErbProxy
             rest.insert 0, "(##{anchor})"
           end
 
-        @headings << Heading.new(anchor, title, depth.to_i)
+        @headings << Heading.new(anchor, title, depth, index)
         @blocks[:section] << Block.new(anchor, title, :section)
 
         head + rest
@@ -141,7 +161,7 @@ class DocProxy < ErbProxy
 
   # 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"
+    args.join("\n\n\n") << "\n\n\n"
   end
 
   # Removes the # from a HTML anchor so that only its name is preserved.