ruby-vpi 7.0.0

data/HISTORY

@@ -0,0 +1,398 @@
+h1. Release history
+
+This is a record of important changes that have occurred with each release of "Ruby-VPI":http://ruby-vpi.rubyforge.org.
+
+h2. Version numbering system
+
+We _strictly_ follow the RubyGems project's "rational versioning policy":http://www.rubygems.org/read/chapter/7 since release 6.3.0. To summarize[1] this "major.minor.build" numbering policy,
+* an increase in the *major* number indicates that *functionally incompatible* have occurred. Thus, what may have worked in the previous version may not work in the new one.
+* an increase in the *minor* number indicates that *functionally compatible* changes have occurred. Thus, what worked in the previous version will work in the new one.
+* an increase in the *build* number indicates that the *underlying implementation* has changed. The functionality has not changed and no features have been added. Thus, what worked in the previous version will work in the new one.
+
+fn1. C. Gross, "Explaining Open Source Version Numbers", [Online document], 2005 Nov 28, [cited 2006 Aug 27], Available HTTP: "http://ablog.apress.com/?p=738":http://ablog.apress.com/?p=738
+
+
+h1. Version 7.0.0 (2006-08-29)
+
+h2. Summary
+
+This release distributes Ruby-VPI as a gem, improves portability of generated tests, and fixes a bug.
+
+h2. Details
+
+* @put_value()@ now accomodates register value overflows when verifying the value it has written.
+
+* 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 @gem install -i output_directory ruby-vpi-7.0.0.gem@. In addition, you can still obtain the source code directly from the Subversion repository.
+
+* 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 @lib/@ directory have been moved into @lib/ruby-vpi/@ 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 @src/@ directory has been renamed to @ext/@ to follow RubyGems convention.
+
+* The tools in @bin/@ become available in your system's @bin/@ 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.
+
+
+h1. Version 6.3.0 (2006-08-27)
+
+h2. Summary
+
+This release adds support for the GPL Cver simulator, provides both binary and source packages, and explicitly defines the version numbering system.
+
+h2. Details
+
+* The GPL Cver simulator is now supported.
+
+* Ruby-VPI now only needs to be built once.
+** You can run tests with different Verilog simulators without having to re-compile Ruby-VPI.
+** 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 |
+
+
+h1. Version 6.2.0 (2006-08-26)
+
+h2. Summary
+
+This release beautifies generated tests, adds checks to find signal width bugs, and includes a new tool.
+
+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.
+
+* @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.
+
+* The source code is now indented with two spaces instead of one tab character.
+
+
+h1. Version 6.1.0 (2006-08-09)
+
+h2. Summary
+
+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.
+
+
+h1. Version 6.0.0 (2006-08-07)
+
+h2. Summary
+
+This release adds support and documentation for rapid prototyping of Verilog designs in Ruby.
+
+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 directory structure has been reorganized as follows:
+** @ext@ → @src@
+** @tools@ → @bin@
+** @examples@ → @samp@
+
+* All template files have been moved into the @tpl@ directory.
+
+* The user manual has been revised for consistency.
+
+
+h1. Version 5.1.1 (2006-08-04)
+
+h2. Summary
+
+This release fixes unreadable syntax coloring in the user manual.
+
+h2. Details
+
+* Source code comments in the user manual are now readable.
+
+* The @README@ and @HISTORY@ files have been converted to "textile":http://www.textism.com/tools/textile/ format.
+
+h2. Acknowledgment
+
+* Thanks to Todd Nagengast and Matt Fischler for notifying me about unreadable text in the user manual.
+
+
+h1. Version 5.1.0 (2006-07-29)
+
+h2. Summary
+
+This release adds a tutorial to the user manual, and improves the tools and examples.
+
+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 @--name@ and @-n@ options, which lets you specify an identifier for a generated test, have been added to the @generate_test.rb@ tool.
+
+* Running @rake clobber@ 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 @launcher_template.rake@ template.
+
+* The Rake template for test runners (generated by @tools/generate_test.rb@) has moved from @examples/template.rake@ to @examples/runner_template.rake@.
+
+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.
+
+h2. Acknowledgment
+
+* Thanks to Phil Tomson for correcting the URL of the RHDL website, in the user manual.
+
+
+h1. Version 5.0.0 (2006-07-22)
+
+h2. Summary
+
+This release enhances the VPI utility layer and adds new content to the user manual.
+
+h2. Details
+
+* SWIG is no longer required for users because its output is included in the release package.
+
+* The VPI utility layer provides access to VPI properties of handles in a "simpler, more powerful way":http://ruby-vpi.rubyforge.org/doc/background.organization.html#organization.vpi.
+
+** All VPI properties, except delay values, are now accessible from a handle.
+
+** The @handle.value@ and @handle.value=@ methods have been removed.
+
+* 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
+
+h2. Acknowledgment
+
+* Thanks to Jan Decaluwe for correcting the description of MyHDL in the user manual.
+
+
+h1. Version 4.0.0 (2006-05-25)
+
+h2. Summary
+
+This release adds a comprehensive user manual, upgrades from make to "Rake":http://rake.rubyforge.org, and improves the test generation tool.
+
+h2. Details
+
+* A comprehensive user manual, written in DocBook-XML, has been added.
+
+* 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.
+
+* 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
+
+h2. Acknowledgment
+
+* Thanks to Jose Renau for solving the problem of strange delays that occurred whenever a design was reset.
+
+
+h1. Version 3.2.0 (2006-05-13)
+
+h2. Summary
+
+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. 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
+
+h2. Acknowledgment
+
+* Thanks to Scott L Holmes for helping me "use the RSpec library without its runner":http://article.gmane.org/gmane.comp.lang.ruby.general/150087 program.
+
+
+h1. Version 3.1.0 (2006-04-28)
+
+h2. Summary
+
+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. 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
+
+
+h1. Version 3.0.0 (2006-04-23)
+
+h2. Summary
+
+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. 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 @vpi_user.h@ 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 @src/vpi_util.rb@).
+
+* 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.
+** The *vsim* target for Mentor Modelsim has been renamed to *msim*.
+
+* 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
+
+h2. Acknowledgment
+
+* Thanks to the "SWIG developers":http://www.swig.org/guilty.html for making this project _much_ easier! ;-)
+
+
+h1. Version 2.0.0 (2006-04-17)
+
+h2. Summary
+
+This release fixes major bugs, adds support for Mentor Modelsim, and removes the @$ruby_task@ callback.
+
+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.
+
+* Removed @$ruby_task@ callback and ability to dynamically register system tasks from Ruby because inter-process communication is complicated at present.
+
+* 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
+
+h2. Acknowledgment
+
+* Thanks to Nobu Nakada for explaining the "cross-thread violation on rb_gc()":http://article.gmane.org/gmane.comp.lang.ruby.general/146653 error.
+
+
+h1. Version 1.0.0 (2006-02-26)
+
+h2. Summary
+
+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. Details
+
+* Implemented some Verilog VPI functionality:
+** @VPI::handle_by_name(string, VPI::Handle)@ → @VPI::Handle@
+** @VPI::handle_by_name(string)@ → @VPI::Handle@
+** @VPI::Handle#put_value(integer)@
+** @VPI::Handle#value = integer@
+** @VPI::Handle#get_value@ → @integer@
+** @VPI::Handle#value@ → @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 @pli_init.rb@.
+
+* 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
+
+h2. Acknowledgment
+
+* Thanks to Jose Renau for helping 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*)@.
+
+* Thanks to Ross Bamford, Eric Hodel, and Yukihiro Matsumoto for "helping me discover":http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/180662 why the @SystemStackError@ was happening.
+
+
+h1. Version 0.0.0 (1999-10-31)
+
+h2. Summary
+
+This is Kazuhiro HIWADA's initial testing release of Ruby-VPI. See its "original announcement":http://www.ruby-talk.org/cgi-bin/scat.rb/ruby/ruby-list/18193 and "source code":http://easter.kuee.kyoto-u.ac.jp/~hiwada/ruby/memo/src/ruby-vpi-test.tgz.
+
+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.