ruby-vpi 16.0.1 → 17.0.0

data/doc/history.inc

@@ -0,0 +1,909 @@
+<% section "Version 17.0.0 (2007-07-22)", "17.0.0" do %>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>.
+<% end %><% section "Version 16.0.1 (2007-05-27)", "16.0.1" do %>This release restores support for installation on Mac OS X.
+
+h2. Thanks
+
+* Mark Thompson "reported and solved":http://rubyforge.org/tracker/index.php?func=detail&aid=11125&group_id=1339&atid=5281 the problem.
+
+h2. Repairs
+
+* Shared-object files have a file extension of <tt>.so</tt> in Linux and <tt>.bundle</tt> on Mac OS X.  Previously, only the Linux file extension was supported.
+<% end %><% section "Version 16.0.0 (2007-05-02)", "16.0.0" do %>This release adds support for the "Cadence NC-Sim / NC-Verilog":http://www.cadence.com/products/functional_ver/nc-verilog/ simulator, improves the project website and documentation, simplifies interaction with VPI, and comes with a more permissive license.
+
+
+h2. Caution
+
+* The @Integer.ensure_min@ and @Integer.ensure_max@ methods have been removed from the <tt>ruby-vpi/integer.rb</tt> library because Ruby already has idioms for these operations: <pre>
+>> 5.ensure_min 10
+=> 10
+>> [5, 10].max
+=> 10
+
+>> 5.ensure_max 10
+=> 5
+>> [5, 10].min
+=> 5
+</pre>
+
+* Ruby-VPI is now developed under a "more permissive license":readme.html#intro.license that better reflects my ethical beliefs than "the previous license":http://www.gnu.org/copyleft/gpl.html.
+
+
+h2. New features
+
+* The "Cadence NC-Sim / NC-Verilog":http://www.cadence.com/products/functional_ver/nc-verilog/ (ncsim) simulator is now supported.
+
+* VPI structures (whose names begin with "S_") now allow initialization of their members through their constructor, in the style of Ruby on Rails. For example, the expression @time = S_vpi_time.new :type => VpiSuppressTime@ is equivalent to: <code>
+time      = S_vpi_time.new
+time.type = VpiSuppressTime
+</code>
+
+* Added the @Vpi::Handle.cbValueChange@ method which simplifies the registration of a value-change callback for a particular VPI handle. For instance, the user manual's "example of setting up a value-change callback":manual.html#ex..callback can now be written as follows: <code>
+Counter.count.cbValueChange do |s_cb_data|
+  puts "hello from callback! time=#{s_cb_data.time.to_i} count=#{s_cb_data.obj.intVal}"
+end
+</code>
+
+
+h2. Details
+
+* Revised the project website according to the "Producing OSS":http://producingoss.com guidelines.
+
+* Added instructions for checking out source code and generating documentation.
+<% end %><% section "Version 15.0.2 (2007-01-22)", "15.0.2" do %>This release fixes problems with linking of the C extension and installation of the gem.
+
+
+h2. Details
+
+* Added checks for POSIX threads & Ruby libraries before creating makefile. Otherwise the <tt>.so</tt> files were not being linked to those libraries on the MASC machine!
+
+* The *make* program on the MASC machine does not like an empty Makefile. It was causing gem installation to fail.
+<% end %><% section "Version 15.0.1 (2007-01-15)", "15.0.1" do %>This release fixes another problem with compilation of the C extension and improves the user documentation's appearance.
+
+
+h2. Thanks
+
+* Derek Graham reported the problem with compilation of the C extension.
+
+
+h2. Details
+
+* Restored the monkey patch, which was removed in release 14.0.0, for the SWIG @va_list@ problem.
+
+* Made table of contents in-line with the content in user documentation.
+
+* Added printer-friendly stylesheet for user documentation.
+<% end %><% section "Version 15.0.0 (2007-01-13)", "15.0.0" do %>This release fixes a problem with compilation of the C extension, and makes clock generation code correctly affect Ruby prototypes.
+
+
+h2. Thanks
+
+* Derek Graham reported the problem with compilation of the C extension.
+
+
+h2. Caution
+
+* The @Vpi::advance_time@ method (instead of the @Vpi::simulate@ method) now invokes the design's @simulate!@ method when prototyping is enabled.
+
+  This makes clock generation code (passed to the @RubyVpi::init_bench@ method) affect Ruby prototypes, just as it affects a real Verilog design.
+
+  As a result, Ruby prototypes may need to check for edge-triggering through the new @Vpi::Handle.posedge?@ and @Vpi::Handle.negedge?@ methods. For example, see the "new implementation of the Counter prototype":manual.html#fig..counter_proto.rb.
+
+h3. New features
+
+* Added @Vpi::Handle.posedge?@ and @Vpi::Handle.negedge?@ methods which check if a handle's logic value is currently at a positive or negative edge, respectively.
+
+* Added @Vpi::S_vpi_time.integer@ and @Vpi::S_vpi_time.integer=@ methods which access the @high@ and @low@ integer fields as a single 64-bit integer.
+
+* Added utility methods for accessing the @value@ field in the @Vpi::S_vpi_value@ structure.
+
+
+h2. Details
+
+* Fixed problem with incorrect Ruby library flag in <tt>ext/extconf.rb</tt>. It happens that the @mkmf@ library determines the correct library flag all by itself!
+
+* Added new "prototyping section":manual.html#usage.prototyping to user manual.
+
+* Fixed some broken URLs in user documentation.
+<% end %><% section "Version 14.0.0 (2006-12-30)", "14.0.0" do %>This release adds support for simulation callbacks, renders Verilog benches _fully simplified_, and revises the user manual to reflect major changes.
+
+
+h2. Caution
+
+* 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.
+
+
+h2. 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.
+<% end %><% section "Version 13.0.0 (2006-12-27)", "13.0.0" do %>This release fixes a _major_ instability bug, simplifies generated Verilog benches, and purifies the API reference documentation.
+
+
+h2. Caution
+
+* The @$ruby_init@ and @$ruby_relay@ system task/functions have been removed. Generated Verilog benches no longer use them.
+** To pass your own command-line options to Ruby, set the @RUBYOPT@ environment variable before running a test.
+
+h3. New features
+
+* You can now choose when @Vpi::relay_verilog@ is triggered: upon positive/negative edge of the clock signal, or any other criteria. This is done by passing a block to the @RubyVpi::init_bench@ method (see "the API reference documentation":../ref/ruby/classes/RubyVpi.html for details).
+
+
+h2. Details
+
+* Fixed a major instability bug that was randomly causing segmentation faults and pthread assertion failures.
+
+  The problem was that the @$ruby_init@ system task/function was mischeviously unlocking a pthread mutex. From then onward, all code assumed that the mutex was still locked -- but in reality, the mutex was already unlocked.
+
+* Replaced the @$ruby_init@ and @$ruby_relay@ system task/functions with callbacks.
+
+* Excluded internal stuff from the API reference documentation for Ruby.
+
+* Removed system-dependent path <tt>/usr/bin/ruby</tt> from the tools.
+<% end %><% section "Version 12.1.0 (2006-12-22)", "12.1.0" do %>This release adds interactive debugging support, adds new sections to the user manual, and cleanses some internals.
+
+
+h2. Caution
+
+* The <tt>lib/ruby-vpi/rspec.rb</tt> and <tt>lib/ruby-vpi/xx.rb</tt> files have been removed because they are no longer necessary.
+
+* rSpec 0.7.0 or newer is now required because the sample tests utilize the @should ==@ syntax.
+
+h3. New features
+
+* Test runners now support the @DEBUG@ environment variable, which enables the interactive debugger (ruby-debug) in "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
+** The @debugger@ command can also be used when the @DEBUG@ environment variable is not activated.
+
+* Status messages, which are shown during initialization of a Ruby bench, now appear in your simulator's log files.
+
+
+h2. Details
+
+* ruby-debug is now a gem dependency for Ruby-VPI.
+
+* Added documentation about "test runners":manual.html#usage.test-runner and the "interactive debugger":manual.html#usage.debugger in the user manual.
+
+* Added a <tt>README</tt> file with hint about where to find the user manual.
+
+* Removed code that wasn't being used, according to code coverage analysis, from the pipelined ALU sample.
+<% end %><% section "Version 12.0.2 (2006-12-18)", "12.0.2" do %>This release fixes a problem in the 12.0.1 gem, where the *generate_test.rb* and *header_to_ruby.rb* tools were not being installed properly.
+<% end %><% section "Version 12.0.1 (2006-12-18)", "12.0.1" do %>This release fixes a problem in code coverage analysis.
+
+
+h2. Thanks
+
+* Mauricio Fernandez helped me solve the problem with code coverage analysis.
+
+
+h2. Details
+
+Previously, code coverage reports were not providing any useful information because they were being generated _before_ the test had a chance to run. This problem has been fixed -- code coverage reports are now generated _after_ the test has finished running.
+
+This problem occurred because I had forgotten that @Kernel.at_exit@ invokes the blocks passed to it in _reverse_ order. So, the coverage report was being generated before Test::Unit had a chance to run (it also uses @Kernel.at_exit@).
+<% end %><% section "Version 12.0.0 (2006-12-07)", "12.0.0" do %>This release adds support for the "test/spec":http://chneukirchen.org/blog/archive/2006/10/announcing-test-spec-0-2-a-bdd-interface-for-test-unit.html library, fixes some bugs, and improves the user manual and generated tests.
+
+
+h2. Caution
+
+* Icarus Verilog 0.8 has been demoted to a "mostly acceptable":manual.html#setup.reqs status.
+
+* Generated Verilog benches no longer supply the <tt>-w</tt> option to the @$ruby_init@ task.
+
+* The @ruby-vpi/runner_proxy@ library now invokes test runners
+** just before exiting. Thus, you can invoke tasks in the main <tt>Rakefile</tt> before the test runners are invoked.
+** located within any directory that is a descendant of the current working directory.
+
+* The @SIMULATOR_ARGS@ parameter of generated runners has been renamed to @SIMULATOR_ARGUMENTS@ for clarity.
+
+* The automated test generator
+** no longer displays the *backup* status indicator.
+** now supplies a third argument to the @MERGER@ command.
+** no longer replaces existing files with newly generated content during the *update* action. Instead, it now writes the newly generated output to a <tt>.new</tt> file and then invokes the @MERGER@ command.
+
+
+h2. Details
+
+* The @Vpi::Handle@ class has two new methods: @x!@ and @z!@, which set the handle's logic value to _unknown_ and _high impedance_ respectively.
+
+* The tests for the simple up-counter example were randomly failing because the specifications were not asserting the design's @reset@ signal long enough. So the design was getting into weird states and behaving in a non-deterministic way. This problem has been fixed.
+
+* The user manual has been revised and some minor issues have been fixed.
+
+h3. Test generation
+
+* The automated test generator accepts new command-line options:
+** <tt>--test-unit</tt>
+** <tt>--test-spec</tt>
+** <tt>--tspec</tt>
+
+* The automated test generator was crashing when parsing module parameters of an input file which did not have any module parameters. This has been fixed.
+
+* Generated Verilog benches now contain simpler clock generation code.
+
+* Generated runners now contain
+** a @:setup@ task which is invoked before the simulator runs. It can be used to make preprations, such as converting Verilog header files into Ruby, for the simulation.
+** better explanations to accomodate new users.
+
+* Specifications generated in the *generic* format no longer contain a class that is instantiated in the generated Ruby bench.
+<% end %><% section "Version 11.1.1 (2006-11-15)", "11.1.1" do %>This release fixes a bug in the automated test generator, unifies the user manual and the website into a single documentation system, and adds support for rSpec 0.7.2.
+
+
+h2. Thanks
+
+* John Burr found the bug in the automated test generator.
+
+
+h2. Caution
+
+* The user manual is now available _only_ in HTML format. If you still wish to have a plain-text version, you can use a text-based browser, such as "lynx":http://lynx.browser.org/, to perform the necessary conversion.
+
+
+h2. Details
+
+* The automated test generator no longer crashes when parsing a Verilog module declaration that contains multiple module parameters.
+
+* The user manual and the website are now written using a custom documentation system based on RedCloth and ERB instead of DocBook-XML. This makes it easier to edit the user manual and reuse its content in other areas of the website.
+<% end %><% section "Version 11.1.0 (2006-11-08)", "11.1.0" do %>This release fixes a bug in generated benches, improves the "the @Vpi::Handle@ class":../ref/ruby/classes/Vpi/Handle.html, and improves performance by roughly 20%.
+
+
+h2. Thanks
+
+* Matt Fischler found the bug in generated benches (see below).
+
+
+h2. Caution
+
+* A bug in generated Verilog and Ruby benches, which caused the <pre>ruby: no such file to load -- ruby-vpi (LoadError)</pre> error, has been fixed. Please regenerate your tests to apply this bug fix to your tests.
+
+
+h2. Details
+
+* The class @SWIG::TYPE_p_unsigned_int@ has been aliased as @Vpi::Handle@ for easier access.
+
+* @Vpi::Handle.to_s@ and @Vpi::Handle.inspect@ now produce more informative output. For example, what used to appear as <pre>#<SWIG::TYPE_p_unsigned_int:0x2aaab6574fa0></pre> now appears as <pre>#<Vpi::Handle vpiModule fullName=counter_rspec_bench, size=-1, file=counter_rspec_bench.v, lineNo=2></pre> in this release.
+** You can also provide a list of VPI properties, as names or integer constants, to those methods to see additional information in the output.
+
+* @Vpi::Handle@ now implements all methods from @Enumerable@, such as @map@, @each@, @select@, and so on. However, unlike their counterparts in @Enumerable@, these methods also accept a list of VPI properties, as names or integer constants. Thus, you are now able to write @handle.select(:reg, :net) {|h| h.size > 5}@ to obtain a list of child handles to registers and nets whose capacity is greater than 5 bits.
+
+* The @Vpi::Handle.[]@, @Vpi::Handle.get_value@, and @Vpi::Handle.put_value@ methods now accept names of VPI properties as well as their integer constants. Thus, you are now able to write @handle[:reg, :net]@ to obtain a list of handles to all child registers and nets.
+
+* @Vpi::Handle.method_missing@ has been refactored to cache queries. There is now, approximately, 20% improvement in performance.
+
+* @Vpi::Handle.method_missing@ has been fixed to accept operations with multiple underscores. For example, before this release, you could not write @handle.find_all_reg {|r| r.name =~ /foo/}@ because the "find_all_reg" method would be interpreted as the operation "find" and the VPI property "all_reg".
+
+* @Vpi::Handle.method_missing@ no longer requires that the first letter of a method be lower case. For example, now you can now write @handle.IntVal@ in addition to @handle.intVal@.
+
+* The @IntegerGenerator@ class, in the pipelined ALU example, has been fixed so that multiple instances do not interfere with the generation of each other's prime integers.
+
+* Due to a bug in the <tt>Rakefile</tt>, the reference documentation was not included in the previous few releases. This has been fixed.
+<% end %><% section "Version 11.0.0 (2006-11-05)", "11.0.0" do %>This release shortens generated Ruby benches and uses the less confusing notation for defining "singleton methods":http://wiki.rubygarden.org/Ruby/page/show/SingletonTutorial in generated designs and prototypes.
+
+
+h2. Caution
+
+* The arguments for the "@RubyVPI.init_bench@ method":../ref/ruby/classes/RubyVpi.html have changed.
+
+* *generate_test.rb* no longer emits undocumented status indicators: _name_ and _format_.
+
+* The source code is no longer distributed as a *zip* package, because it seems to be quite underutilized in comparison to the *tgz* and *gem* packages.
+
+
+h2. Details
+
+* Generated Ruby benches have been shortened to just _one_ line of code!
+
+* The less confusing notation of <code>def some_object.a_singleton_method
+  do_stuff
+end</code> is now used instead of the <code>class << some_object
+  def a_singleton_method
+    do_stuff
+  end
+end</code> notation.
+** The tutorial and examples have been updated accordingly.
+
+* The pipelined ALU example now has an updated @IntegerGenerator@ class.
+<% end %><% section "Version 10.0.0 (2006-11-05)", "10.0.0" do %>This release adds the ability to access a handle's children and reduces the amount of code produced by the automated test generator.
+
+
+h2. Thanks
+
+* Matt Fischler found the problem of misdirected compilation errors in Verilog benches.
+
+
+h2. Caution
+
+* The way in which Ruby-VPI and generated tests interact has changed: the design is now a VPI handle object and the <tt>design.rb</tt> and <tt>proto.rb</tt> files define "singleton methods":http://wiki.rubygarden.org/Ruby/page/show/SingletonTutorial for that object.
+** I suggest that you regenerate your existing tests (just run *generate_test.rb* again) whilst employing the service of a text merging tool (see the user manual).
+
+* You can now access a handle's children by simply calling methods on it. 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 @get_value@ and @put_value@ methods.
+
+* *generate_test.rb* no longer accepts the <pre>-s</pre> and <pre>-u</pre> options. Use their longer counterparts <pre>--rspec</pre> and <pre>--xunit</pre> instead.
+
+
+
+h2. Details
+
+h3. Automated test generator
+
+* Generated Verilog benches no longer divert compilation errors from Verilog design files. That is, if the Verilog simulator finds compilation errors in a Verilog design file, it will report that the Verilog design file is at fault (instead of reporting that the generated Verilog bench is at fault).
+
+* The user is now notified when a backup of an existing file is made.
+
+* Generated tests have been greatly simplified to reduce the amount of work for the user.
+** The design is now just a handle to the module in the Verilog bench.
+** @include Vpi@ and @@design@ are no longer generated.
+** The tutorial and examples have been updated accordingly.
+
+h3. User manual
+
+* Revised the stylesheet to make disjoint sections readily distinguishable from each other, through generous spacing and minor coloring.
+
+* Added tips about <tt>ruby-vpi/runner_proxy</tt>, <pre>rake -T</pre>, and using *kdiff3* with *generate_test.rb*.
+
+* Moved installation information into a new "setup" chapter.
+<% end %><% section "Version 9.0.0 (2006-10-28)", "9.0.0" do %>This release improves the automated test generator and adds new content to the user manual.
+
+
+h2. Thanks
+
+* Matt Fischler helped test and debug the installation of Ruby-VPI on Windows.
+
+
+h2. Caution
+
+* The command-line options for *generate_test.rb* have changed. Run the command <pre>generate_test.rb --help</pre> for details.
+
+
+h2. Details
+
+* Test runners now attempt to resolve paths in @SIMULATOR_SOURCES@ by searching for them within the directories specified in @SIMULATOR_INCLUDES@.
+
+* Synopsys VCS is now used in a better way (via the <pre>-load</pre> option).
+** The old PLI table file (<tt>synopsys_vcs.tab</tt>) has been removed.
+** The C extension has been revised accordingly.
+
+** The C extension now compiles without errors in Cygwin.
+
+* The automated test generator now:
+** Only creates output files when necessary.
+** Updates existing output files using "text merging tools":manual.html#setup.recom if possible. (Refer to @MERGER@ in the help information of *generate_test.rb*.)
+** Emits progress information similar to Ruby on Rails.
+
+* The user manual now:
+** Includes instructions for installing on Windows (via Cygwin).
+** Has a recommended software section, with links to text merging tools.
+** Uses the term "xUnit":http://en.wikipedia.org/wiki/XUnit instead of "unit test".
+** Correctly spells "rSpec".
+<% end %><% section "Version 8.2.0 (2006-10-24)", "8.2.0" do %>This release simplifies configuration of generated tests.
+
+
+h2. Thanks
+
+* "Students in the CMPE-126 class":http://www.soe.ucsc.edu/classes/cmpe126/Fall06/ for their comments and criticisms.
+
+
+h2. Caution
+
+* Generated runners now have a @SIMULATOR_INCLUDES@ array, whose entries specify places where Verilog source files, needed by the Verilog design, reside.
+
+
+h2. Details
+
+* Generated Verilog benches now inherit all @`include@ and @`define@ directives from the Verilog design in a simpler manner.
+* A generated test no longer requires its Verilog design to reside in the same directory.
+* The sample tests have been updated accordingly.
+<% end %><% section "Version 8.1.0 (2006-10-21)", "8.1.0" do %>This release adds an integer library and renames the vpi_util library.
+
+
+h2. Caution
+
+* The *vpi_util* library has been renamed to *vpi*. This change should not affect your code unless you explicitly imported this library via @require 'ruby-vpi/vpi_util'@. In which case, you should update your code to use @require 'ruby-vpi/vpi'@ accordingly.
+
+
+h2. Details
+
+* An integer library has been added to simplify common tasks related to hardware and the binary number system. You can import this library for use via @require 'ruby-vpi/integer'@.
+<% end %><% section "Version 8.0.0 (2006-10-13)", "8.0.0" do %>This release renames some identifiers for consistency, updates the documentation, and improves integration with RubyGems.
+
+
+h2. Caution
+
+* The @RubyVPI@ module has been renamed to @RubyVpi@.
+
+* The @PROTO@ environment variable has been renamed to @PROTOTYPE@.
+** In addition to using *unset*, you can now disable simulation of the prototype by assigning an empty value to this variable.
+
+
+h2. Details
+
+* We now use "Darcs":http://darcs.net for revision control, instead of Subversion. The source repository can now be accessed at "http://ruby-vpi.rubyforge.org/src/ruby-vpi":http://ruby-vpi.rubyforge.org/src/ruby-vpi.
+
+* The source code is now distributed in tar.gz and zip form, in addition to gem.
+
+* Some identifiers have been renamed for better consistency.
+
+* The user manual now resides directly within the <tt>doc/</tt> directory.
+** The integration of documentation in *gem_server* has been improved.
+
+* The glossary and tutorial in the user manual have been revised.
+<% end %><% section "Version 7.3.0 (2006-09-30)", "7.3.0" do %>This release fixes a bug in generated Verilog benches, includes parsed constants in generated tests, and adds new methods to handles.
+
+
+h2. Caution
+
+* Handles now have two new methods:
+** @handle.x?@ checks if the logic value is "don't care"
+** @handle.z?@ checks if the logic value is high impedance
+
+
+h2. Details
+
+* Module instantiation code in generated Verilog benches has been fixed. Whitespace between the module type and instance variable was missing.
+
+* The test generator tool now provides parsed Verilog constants and include-directives in generated Verilog benches; and parsed Verilog constants in generated Ruby designs.
+** The pipelined ALU example has been revised accordingly.
+
+* A library for parsing Verilog source code has been added as <tt>lib/ruby-vpi/verilog_parser.rb</tt>.
+<% end %><% section "Version 7.2.0 (2006-09-15)", "7.2.0" do %>This release adds initial support for code coverage analysis via the "rcov library":http://eigenclass.org/hiki.rb?rcov.
+
+
+h2. Thanks
+
+* Mauricio Fernandez helped me use rcov without its runner.
+
+
+h2. Details
+
+* Added initial support (full capabilites of the rcov library, such as its various analysis modes, are not yet utilized) for code coverage analysis, which can be enabled by setting the @COVERAGE@ environment variable to a non-empty value before running a test.
+** For example, you can run a test with the GPL Cver simulator while enabling the generation of code coverage reports as follows: <pre>export COVERAGE=1; rake cver</pre>
+
+* Coverage reports are generated in text and HTML formats.
+<% end %><% section "Version 7.1.0 (2006-08-29)", "7.1.0" do %>This release simplifies running of multiple tests, restores compatibility with Synopsys VCS, and better integrates with RubyGems.
+
+
+h2. Details
+
+* Added <tt>lib/ruby-vpi/runner_proxy.rb</tt> library which, when embedded into a Rakefile, runs all generated tests in the working directory with any specified arguments. For example, have a look at the <tt>samp/counter/Rakefile</tt> file.
+
+* Fixed a bug that prevented one from running tests with Synopsys VCS.
+
+* Ruby-VPI documentation is now available through RubyGems' "*gem_server* web interface":http://docs.rubygems.org/read/chapter/2#page10.
+
+* The user manual now discusses how to determine the location of a Ruby-VPI installation.
+
+* The <tt>tpl/</tt> directory has been removed.
+<% end %><% section "Version 7.0.0 (2006-08-29)", "7.0.0" do %>This release distributes Ruby-VPI as a gem, improves portability of generated tests, and fixes a bug.
+
+
+h2. Caution
+
+* @put_value()@ now accomodates register value overflows when verifying the value it has written.
+
+* The test generator's templates and the examples have been updated as follows:
+** Test runners no longer have to specify the path to Ruby-VPI installation directory. Instead, they simply @require 'ruby-vpi/runner'@. Thus, you can run your tests on any machine with Ruby-VPI without having to know where it is installed.
+** Ruby benches now invoke @RubyVPI.init_bench@ instead of @require 'bench'; setup_bench@ to become initialized.
+
+* All Ruby libraries in the <tt>lib/</tt> directory have been moved into <tt>lib/ruby-vpi/</tt> to prevent load-path clashes with other gems. You should access these libraries by prefixing their path with "ruby-vpi". For example, @require 'vpi_util'@ should now be written as @require 'ruby-vpi/vpi_util'@.
+
+* The <tt>src/</tt> directory has been renamed to <tt>ext/</tt> to follow RubyGems convention.
+
+
+h2. Details
+
+* Ruby-VPI is now distributed only as a "source gem":http://www.rubygems.org. You can decompress the gem without installing it onto your system by running the command <pre>gem install -i output_directory ruby-vpi-7.0.0.gem</pre>. In addition, you can still obtain the source code directly from the Subversion repository.
+
+* The tools in <tt>bin/</tt> become available in your system's <tt>bin/</tt> directory when the gem is installed.
+** Usage and help information has been added to the *header_to_ruby.rb* tool.
+
+* Incorrect spelling of GPL Cver (v should be uncapitalized) has been fixed.
+
+* Incorrect link to GPL Cver website has been fixed.
+
+* The user manual has been updated according to all of the above changes.
+<% end %><% section "Version 6.3.0 (2006-08-27)", "6.3.0" do %>This release adds support for the GPL Cver simulator, provides both binary and source packages, and explicitly defines the version numbering system.
+
+
+h2. Caution
+
+* Ruby-VPI now only needs to be built once.
+** You can run tests with different Verilog simulators without having to re-compile Ruby-VPI.
+
+
+h2. Details
+
+* The GPL Cver simulator is now supported.
+
+* Release packages are now available in both source and binary form.
+
+* The RSpec based specifications for the counter example now use the @should_equal@ instead of the @should_be@ assertion, because the latter ensures strict equivalence. For instance, it will fail when a Fixnum is compared to a Bignum.
+
+* We now follow the RubyGems project's "rational versioning policy":http://www.rubygems.org/read/chapter/7. The version numbers of previous releases have been revised accordingly:
+|_. Release date |_. Original version number |_. New version number |
+| 1999-10-31 | 0.0   | 0.0.0 |
+| 2006-02-26 | 0.1   | 1.0.0 |
+| 2006-04-17 | 0.2   | 2.0.0 |
+| 2006-04-23 | 0.3   | 3.0.0 |
+| 2006-04-28 | 0.4   | 3.1.0 |
+| 2006-05-13 | 0.5   | 3.2.0 |
+| 2006-05-25 | 0.6   | 4.0.0 |
+| 2006-07-22 | 0.7   | 5.0.0 |
+| 2006-07-29 | 0.8   | 5.1.0 |
+| 2006-08-04 | 0.8.1 | 5.1.1 |
+| 2006-08-07 | 0.9   | 6.0.0 |
+| 2006-08-09 | 0.9.1 | 6.1.0 |
+| 2006-08-26 | 0.9.2 | 6.2.0 |
+<% end %><% section "Version 6.2.0 (2006-08-26)", "6.2.0" do %>This release beautifies generated tests, adds checks to find signal width bugs, and includes a new tool.
+
+
+h2. Caution
+
+* @put_value()@ now returns the value it puts. Therefore, it is easier to chain together a series of assignments: @foo.intVal = bar.intVal = baz.intVal = 10@
+
+* @put_value()@ now verifies that the value it puts was written correctly. This helps to find bugs regarding invalid assumptions about the number of bits supported by a signal.
+
+
+h2. Details
+
+* The test generator now uses ERB templates which ensures nice indentation of generated output.
+
+* The test generator now decouples Ruby-VPI paths from Verilog benches via the RUBYLIB environment variable.
+
+* A tool which converts Verilog headers into Ruby has been added.
+
+* The source code is now indented with two spaces instead of one tab character.
+<% end %><% section "Version 6.1.0 (2006-08-09)", "6.1.0" do %>This release simplifies generated tests and fixes a bug.
+
+
+h2. Details
+
+* The test generator now produces simpler Ruby benches and specifications.
+** A template used by generated specifications has been added.
+** The counter example and tutorial have also been simplified accordingly.
+
+* Boolean VPI property values are now correctly converted into Ruby truth values.
+<% end %><% section "Version 6.0.0 (2006-08-07)", "6.0.0" do %>This release adds support and documentation for rapid prototyping of Verilog designs in Ruby.
+
+
+h2. Caution
+
+* The directory structure has been reorganized as follows:
+** <tt>ext</tt> &rarr; <tt>src</tt>
+** <tt>tools</tt> &rarr; <tt>bin</tt>
+** <tt>examples</tt> &rarr; <tt>samp</tt>
+
+* All template files have been moved into the <tt>tpl</tt> directory.
+
+
+h2. Details
+
+* Support for prototyping designs in Ruby, before they are implemented in Verilog, has been added.
+** The _same_ specification can be used to verify both prototype _and_ design! :-)
+** The tutorial in the user manual has been updated to discuss prototyping.
+*** Prototypes have been added to the counter example.
+
+* The user manual has been revised for consistency.
+<% end %><% section "Version 5.1.1 (2006-08-04)", "5.1.1" do %>This release fixes unreadable syntax coloring in the user manual.
+
+
+h2. Thanks
+
+* Todd Nagengast and Matt Fischler notified me about unreadable text in the user manual.
+
+
+h2. Details
+
+* Source code comments in the user manual are now readable.
+
+* The <tt>README</tt> and <tt>HISTORY</tt> files have been converted to "textile":http://www.textism.com/tools/textile/ format.
+<% end %><% section "Version 5.1.0 (2006-07-29)", "5.1.0" do %>This release adds a tutorial to the user manual, and improves the tools and examples.
+
+
+h2. Thanks
+
+* Phil Tomson corrected the URL of the RHDL website in the user manual.
+
+
+h2. Details
+
+h3. User manual
+
+* A tutorial, based on the counter example, has been added to the user manual.
+
+* The user manual's appearance has been dramatically improved with syntax coloring for source code, and "graphics for admonitions and navigation":http://tango.freedesktop.org.
+
+h3. Examples
+
+* A specification, expressed in unit test format, has been added to the counter example.
+
+* The <pre>--name</pre> and <pre>-n</pre> options, which lets you specify an identifier for a generated test, have been added to the *generate_test.rb* tool.
+
+* Running <pre>rake clobber</pre> in an example directory no longer destroys documentation in the Ruby-VPI directory.
+
+* The examples' Rakefiles now invoke all tests present in the directory via the <tt>launcher_template.rake</tt> template.
+
+* The Rake template for test runners (generated by <tt>tools/generate_test.rb</tt>) has moved from <tt>examples/template.rake</tt> to <tt>examples/runner_template.rake</tt>.
+
+h3. VPI utility layer
+
+* The value of a handle's boolean VPI property is treated as @false@ if it is zero, because zero is @false@ in the C language.
+<% end %><% section "Version 5.0.0 (2006-07-22)", "5.0.0" do %>This release enhances the VPI utility layer and adds new content to the user manual.
+
+
+h2. Thanks
+
+* Jan Decaluwe corrected the description of MyHDL in the user manual.
+
+
+h2. Caution
+
+* SWIG is no longer required for users because its output is included in the release package.
+
+* The @handle.value@ and @handle.value=@ methods have been removed.
+
+
+h2. Details
+
+* The VPI utility layer provides access to VPI properties of handles in a "simpler, more powerful way":manual.html#background.org.vpi.
+
+** All VPI properties, except delay values, are now accessible from a handle.
+
+* The user manual has been revised and new content in the organization and usage sections has been added.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Mentor Modelsim 6.1d on x86_64 GNU/Linux
+<% end %><% section "Version 4.0.0 (2006-05-25)", "4.0.0" do %>This release adds a comprehensive user manual, upgrades from make to "Rake":http://rake.rubyforge.org, and improves the test generation tool.
+
+
+h2. Thanks
+
+* Jose Renau solved the problem of strange delays that occurred whenever a design was reset.
+
+
+h2. Caution
+
+* Rake has replaced the role of *make*. All makefiles have been converted accordingly.
+
+* The test generation tool now generates multiple files (runner, bench, design, spec) and makes backups of existing files. See its help information for details.
+
+
+h2. Details
+
+* A comprehensive user manual, written in DocBook-XML, has been added.
+
+* Support for RSpec 0.5.4 has been added.
+** The counter example now makes use of RSpec.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Mentor Modelsim 6.1d on x86_64 GNU/Linux
+<% end %><% section "Version 3.2.0 (2006-05-13)", "3.2.0" do %>This release adds a tool which generates test benches, and adds support for "Behavior Driven Development":http://behaviour-driven.org via the "RSpec":http://rspec.rubyforge.org library.
+
+
+h2. Thanks
+
+* Scott L Holmes helped me "use the RSpec library without its runner":http://article.gmane.org/gmane.comp.lang.ruby.general/150087 program.
+
+
+h2. Details
+
+* A tool, which generates most of a Ruby-VPI test bench from a Verilog 2001 module declaration, has been added.
+
+* Ability to use RSpec in a test bench has been added.
+
+* Ability to specify arbitrary command-line arguments to Verilog simulators has been added in the examples' makefile template.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Mentor Modelsim 6.1d on x86_64 GNU/Linux
+<% end %><% section "Version 3.1.0 (2006-04-28)", "3.1.0" do %>This release adds simple ways of reading and writing values to VPI handles, adds documentation for the VPI utility layer, and fixes the pipelined ALU example.
+
+
+h2. Caution
+
+* The *msim* Makefile target for Mentor Modelsim has been renamed back to *vsim*.
+
+
+h2. Details
+
+* Simple, consistent ways of reading and writing values to handles have been added to the VPI utility layer. These ways are described in the @SWIG::TYPE_p_unsigned_int@ class' documentation.
+
+* The makefiles now use the *rbconfig* library to determine the default compiler and linker flags for Ruby.
+
+* A race condition in the pipelined ALU example has been fixed. This example should now run successfully in all Verilog simulators.
+
+* The project wiki has been abandoned in favor of RDoc.
+
+* The project website is now generated by RDoc.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Mentor Modelsim 6.1d on x86_64 GNU/Linux
+<% end %><% section "Version 3.0.0 (2006-04-23)", "3.0.0" do %>This release adds support for the _entire_ "IEEE Std. 1364-2005":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945 VPI interface, and updates the examples into unit tests.
+
+
+h2. Thanks
+
+* The "SWIG developers":http://www.swig.org/guilty.html made this project _much_ easier! ;-)
+
+
+h2. Caution
+
+* The *vsim* Makefile target for Mentor Modelsim has been renamed to *msim*.
+
+
+h2. Details
+
+* The Ruby interface to VPI is now generated by "SWIG":http://www.swig.org.
+** The main @VPI@ module has been renamed to @Vpi@.
+** The @VPI::Handle@ class has been removed.
+** The @VPI::stop@, @VPI::finish@, and @VPI::reset@ methods have been removed.
+
+* The "_final ballot_ version":http://www.boydtechinc.com/ptf/archive/ptf_2005/0737.html of the <tt>vpi_user.h</tt> header file is now packaged along with and used by Ruby-VPI.
+
+* The VPI module, its sub-classes, and its functionality have been replaced by the VPI utility layer (see <tt>src/vpi_util.rb</tt>).
+
+* The examples now make use of the *test/unit* unit testing framework.
+
+* The makefiles for the examples have been simplified through the use of a common template.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Mentor Modelsim 6.1d on x86_64 GNU/Linux
+<% end %><% section "Version 2.0.0 (2006-04-17)", "2.0.0" do %>This release fixes major bugs, adds support for Mentor Modelsim, and removes the @$ruby_task@ callback.
+
+
+h2. Thanks
+
+* Nobu Nakada explained the "cross-thread violation on rb_gc()":http://article.gmane.org/gmane.comp.lang.ruby.general/146653 error.
+
+
+h2. Caution
+
+* Removed @$ruby_task@ callback and ability to dynamically register system tasks from Ruby because inter-process communication is complicated at present.
+
+
+h2. Details
+
+* The "cross-thread violation on rb_gc()" error has been fixed.
+** The "stack level too deep (SystemStackError)" error has been fixed.
+** The test/unit library can be used in Ruby test bench.
+** Mentor Modelsim Verilog simulator works with Ruby-VPI.
+
+* Added piplelined ALU example.
+
+* This release was tested and developed using:
+** Ruby 1.8.4 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4 and Modelsim 6.1d on x86_64 GNU/Linux
+** Ruby 1.8.4 and Synopsys VCS-MX X-2005.06-SP1 on SPARC4 SunOS 5.10
+<% end %><% section "Version 1.0.0 (2006-02-26)", "1.0.0" do %>This release adds enough Verilog VPI functionality to make Ruby-VPI usable for simple test benches:
+* access Verilog objects through VPI handles
+* read and change VPI handle values
+* stop, finish, restart the simulation
+
+
+h2. Thanks
+
+* Jose Renau helped me debug how Synopsys VCS works with Verilog VPI. The problem was that VCS required calltf signatures to be @void (*)(void)@, whereas the Verilog standard defines a calltf signature as @PLI_INT32 (*)(PLI_BYTE8*)@.
+
+* Ross Bamford, Eric Hodel, and Yukihiro Matsumoto "helped me discover":http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/180662 why the @SystemStackError@ was happening.
+
+
+h2. Details
+
+* Implemented some Verilog VPI functionality:
+** @VPI::handle_by_name(string, VPI::Handle)@ &rarr; @VPI::Handle@
+** @VPI::handle_by_name(string)@ &rarr; @VPI::Handle@
+** @VPI::Handle.put_value(integer)@
+** @VPI::Handle.value = integer@
+** @VPI::Handle.get_value@ &rarr; @integer@
+** @VPI::Handle.value@ &rarr; @integer@
+** @VPI::stop@
+** @VPI::finish@
+** @VPI::reset@
+
+* Implemented some additional functionality:
+** @VPI::register_task(string, &proc)@
+
+* Added ability to pass arbitrary command-line arguments to the Ruby interpreter (using @$ruby_init@). Now you can invoke any Ruby script you want, instead of <tt>pli_init.rb</tt>.
+
+* Added ability to dynamically register system tasks from Ruby, using @VPI::register_task("task name")@, and call them from Verilog, using @$ruby_task("task name")@.
+
+* Added @VPI::Handle@ class which encapsulates a @vpiHandle@ VPI object.
+
+* This release was tested and developed using:
+** Ruby 1.8.2 and Icarus Verilog 0.8 on i686 GNU/Linux
+** Ruby 1.8.4, Synopsys VCS X-2005.06, and Mentor Modelsim 6.1b on i686 GNU/Linux
+<% end %><% section "Version 0.0.0 (1999-10-31)", "0.0.0" do %>This is Kazuhiro HIWADA's initial testing release of Ruby-VPI. See its "original announcement":http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/18193 and "source code":http://rubyforge.org/frs/?group_id=1339&release_id=8852.
+
+
+h2. Details
+
+* Added ability to relay control from Verilog test bench to Ruby (using @$ruby_callback@) and vice versa (using @PLI::relay_Verilog@).
+
+* Tested and developed using Ruby 1.4 and Verilog-XL from Cadence systems, on a SPARC machine running Solaris 2.6.
+<% end %>