ruby-vpi 16.0.1 → 17.0.0

data/doc/history.rb

@@ -11,3 +11,12 @@ require 'yaml'
     end
   end
 end
+
+path = File.join(File.dirname(__FILE__), 'history.inc')
+unless File.exist? path
+  File.open(path, 'w') do |f|
+    @history.each do |entry|
+      f << %{<% section "Version #{entry['Version']} (#{entry['Date']})", "#{entry['Version']}" do %>#{entry['Record']}<% end %>}
+    end
+  end
+end

data/doc/history.yaml

@@ -1,3 +1,72 @@
+-
+  Version: 17.0.0
+
+  Date: 2007-07-22
+
+  Record: |
+    This release makes the Ruby-VPI testing framework more lightweight by reducing the number of files and parameters involved.
+
+
+    h2. Caution
+
+    * The *generate_test.rb* and *convert.rb* executables have been replaced by a single *ruby-vpi* executable to avoid name conflicts with other software. They are now accessed using the <pre>ruby-vpi generate</pre> and <pre>ruby-vpi convert</pre> commands respectively.
+
+    * The <tt>--name</tt> parameter has been removed from the automated test generator. Similarly, you can no longer insert an arbitrary name in a test's file names (see the "user manual":manual.html#Do_not_rename_generated_files for details).
+
+    * The @DEBUG@ environment variable, which controls wether the test runner starts the interactive debugger, has been renamed to @DEBUGGER@.
+
+    * The @SIMULATOR_TARGET@ and @SIMULATOR_INCLUDES@ parameters have been eliminated from test runners. The former is detected automatically. As for the latter, you can specify paths to directories in the @SIMULATOR_SOURCES@ parameter instead.
+
+    * The <tt>bench.rb</tt> and <tt>bench.v</tt> files of a generated test are (1) no longer generated by the test generator and (2) are now ignored. You must move the functionality provided by these files into <tt>design.rb</tt> and your Verilog module's source file respectively.
+
+    * The <tt>design.rb</tt> and <tt>proto.rb</tt> files are now loaded into a separate namespace (Ruby module). For example, if the Verilog module under test has the name "counter" and the <tt>design.rb</tt> file defines a class named "Foo", then that class will be accessible as "Counter::Foo".
+
+    * The global @Vpi::simulate@ method has been replaced by the @cycle!@ method in the <tt>design.rb</tt> file.
+
+    * The @simulate!@ method in the <tt>proto.rb</tt> file has been renamed to @feign!@ for accuracy.
+
+    * The @RubyVpi@ module has been renamed to @RubyVPI@.
+
+    * RSpec >= 1.0.0 is now required by Ruby-VPI.
+
+    * The "project license":readme.html#intro.license has been further simplified.
+
+
+    h2. Repairs
+
+    * Restored support for Enumerable methods in @Vpi::Handle@.
+
+    * The specification now begins to execute at simulation time 0. Previously it began at simulation time 1.
+
+
+    h2. Improvements
+
+    * The <tt>bench.rb</tt> and <tt>bench.v</tt> files of a generated test have been eliminated!
+
+      One important benefit is that the Ruby interface to the Verilog module under test is now a direct reference, whereas previously it was an _indirect_ reference (it pointed to the Verilog module defined in <tt>bench.v</tt>, which in turn wrapped around the actual Verilog module under test).
+
+      As a result, you can now access the internals of the Verilog module under test by simply calling methods on the Ruby interface, as you would naturally expect to be the case.
+
+    * The "a" accessor, which returns an _array_ of child handles, has been added to "the method naming format":manual.html#tbl:accessors for accessing child handles.
+
+    * All parameter objects in the Verilog module under test are automatically made available as constants. For example, if the Verilog module under test has the name @counter@ and has a parameter object named @WIDTH@, then you can access the integer value of that parameter using @Counter::WIDTH@.
+
+    * The automated test generator now tries to automatically detect the clock and reset signal from Verilog module declarations.
+
+    * The automated test generator now supports Verilog 95 style module declarations.
+
+    * Exceptions are now raised when you try to write to a read-only VPI property, such as @VpiName@.
+
+    * Added @high?@, @high!@, @low?@, and @low!@ methods to the @Vpi::Handle@ class.
+
+    * Revised the user manual by removing unnecessary sections and adding newer material from my master's thesis.
+
+
+    h2. Contributions
+
+    * Added Jacinto Shy II's "register file example":http://jacintoshy.blogspot.com/2007/05/hacking-verilog-with-ruby-part-2.html to Ruby-VPI. It can be found in <tt>samp/register_file/</tt>.
+
+
 -
   Version: 16.0.1
 

data/doc/intro.inc

@@ -8,191 +8,183 @@ Ruby-VPI is a platform for unit testing, rapid prototyping, and systems integrat
 Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_software released under "this license":#intro.license.
 
 
-<div id="resources">
+<% section "Resources", "resources" do %>
+  <% paragraph "Records" do %>
+    <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 history 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.
+    * "Motivation":http://ruby-vpi.rubyforge.org/papers/masters_thesis.html#tth_sEc5.2
+      - why does Ruby-VPI exist?
+  <% end %>
+
+  <% paragraph "Documentation" do %>
+    * "User manual":manual.html
+      - complete documentation for users. _Start here!_
+    ** "Tutorial":manual.html#usage.tutorial
+      - learn how to use Ruby-VPI quickly.
+    * "Reference":../ref/
+      - API documentation for Ruby libraries and C extension.
+  <% end %>
+
+  <% paragraph "Facilities" do %>
+    * "Downloads":<%= downloadURL %>
+      - obtain release packages
+    * "Source code":<%= codeURL %>
+      - browse online or obtain with "Darcs":http://darcs.net.
+    * "Forums":<%= forumURL %>
+      - discuss things and ask questions.
+    * "Bugs":<%= trackerURL %>
+      - report defects in the software.
+    * "Patches":<%= trackerURL %>
+      - submit patches to source code.
+    * "Requests":<%= trackerURL %>
+      - request new features or get support.
+    * "Project portal":<%= portalURL %>
+      - hosted generously by "RubyForge":http://rubyforge.org.
+  <% end %>
+<% end %>
+
+
+<% section "Features", "intro.features" do %>
+  <% paragraph "Portable" do %>
+    * Supports the _entire_ "IEEE 1364-2005 Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 standard.
+    * Works with all <%= xref "intro.reqs", "major Verilog simulators" %> available today.
+    * Compiled _just once_ during "installation":manual.html#setup.installation and used forever!
+  <% end %>
+
+  <% paragraph "Agile" do %>
+    * Enables "agile practices":http://agilemanifesto.org/ 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.
+    ** There is absolutely _no compiling_!
+  <% end %>
+
+  <% paragraph "Powerful" do %>
+    * 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.
+  <% end %>
+<% end %>
+
+
+<% section "Requirements", "intro.reqs" do %>
+  The following software is necessary in order to use Ruby-VPI.
+
+  <% paragraph "Verilog simulator" do %>
+    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":manual.html#problems.ivl.vpi_handle_by_name.absolute-paths.
+  <% end %>
+
+  <% paragraph "Compilers" do %>
+    * "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.
+  <% end %>
+
+  <% paragraph "Libraries" do %>
+    * "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.
+  <% end %>
+<% end %>
+
+
+<% section "Applications", "intro.applications" do %>
+  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
+  ** Reading test vector files
+  ** Delay calculation
+  ** Custom output displays
+  ** Co-simulation
+  ** Design debug utilities
+  ** Simulation analysis
+
+  * 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
+<% end %>
+
+
+<% section "Appetizers", "intro.appetizers" do %>
+  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:
+
+  bq. @your_register.intVal = 2 ** 2048@
 
-h2. Resources
+  * Check if all nets in a module are at high impedance:
+
+  bq. @your_module.all_net? { |net| net.z? }@
+
+  * See a register's path, width, and location (file & line number):
+
+  bq. @puts your_register@
 
-p(title). Records
+  * Access the first five elements in a memory:
+
+  bq. @your_memory.memoryWord_a[0..4]@
 
-<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>
+  * Clear a memory by filling it with zeroes:
 
-* "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.
+  bq. @your_memory.each_memoryWord {|w| w.intVal = 0}@
+<% end %>
 
-p(title). Documentation
 
-* "Tutorial":manual.html#usage.tutorial
-  - learn how to use Ruby-VPI quickly.
-* "Manual":manual.html
-  - complete documentation for users. _Start here!_
-* "Reference":../ref/
-  - API documentation for Ruby libraries and C extension.
+<% section "License", "intro.license" do %>
+  <%=h File.read('../LICENSE') %>
+<% end %>
 
-p(title). Facilities
 
-* "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.
-* "Project portal":http://rubyforge.org/projects/ruby-vpi
-  - hosted generously by "RubyForge":http://rubyforge.org.
+<% section "Related works", "intro.related-works" do %>
+  * "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.
 
+  <% section "Ye olde PLI", "intro.related-works.pli" do %>
+    The following projects utilize the archaic *tf* and *acc* PLI interfaces, which have been officially deprecated in IEEE Std 1364-2005.
 
-</div>
-
-
-h2(#intro.features). Features
-
-p(title). Portable
-
-* 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!
-
-p(title). Agile
-
-* Enables "agile practices":http://agilemanifesto.org/ 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.
-** There is absolutely _no compiling_!
-
-p(title). Powerful
-
-* 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.
-
-
-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
-
-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
-** Reading test vector files
-** Delay calculation
-** Custom output displays
-** Co-simulation
-** Design debug utilities
-** Simulation analysis
-
-* 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
-
-
-h2(#intro.appetizers). Appetizers
-
-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:
-
-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 { 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.
+    * "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.
+  <% end %>
+<% end %>