ruby-vpi 17.0.0 → 18.0.0

data/doc/history.inc

@@ -1,4 +1,56 @@
-<% 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.
+<% section "Version 18.0.0 (2007-07-31)", "18.0.0" do %>This release restores support for Synopsys VCS and Cadence NC-Sim, improves portability and performance, and enhances the VPI abstraction layer.
+
+
+h2. Thanks
+
+* Calvin Wong discovered "how to bypass the following error":http://rubyforge.org/forum/message.php?msg_id=25691 emitted by Synopsys VCS when loading the Ruby-VPI shared object file.
+
+  <pre>
+  Could not open library specified in -load option obj/vcs
+  obj/vcs: undefined symbol: vpi_put_data
+  </pre>
+
+
+h2. Caution
+
+* "SWIG":http://www.swig.org/ is now required in order to compile and install Ruby-VPI.
+
+* @Vpi::Handle.put_value@ no longer checks whether the value written matches the value read back after writing because that only works when there is no VPI delay associated with the write.
+
+* When @Vpi::Handle.put_value@ is used to write a value to a wire (VpiNet), it now _forces_ the value. This is done to ensure portability:
+
+  Synopsys VCS and Cadence NC-Sim forget the value written to a wire during the next simulation time step, whereas Mentor Modelsim and GPL Cver remember the value (thereby treating wires as registers).
+
+  Note that you have to release a forced value (using @Vpi::Handle.release_value@) on a wire after writing to the wire if you want the design under test have the ability to update the value of the wire later on:
+
+  <code>
+  your_wire.intVal = 15
+  your_wire.release_value
+  advance_time # let the Verilog DUT modify your_wire
+  </code>
+
+  In addition, you can check if a wire has a forced value using the @Vpi::Handle.value_forced?@ method.
+
+* If the format is not specified, @Vpi::Handle.get_value@ now assumes that you want to read the value in VpiIntVal format (because this is the most common case).
+
+* The definition of "Derivatives" has been reworded for clarity in the "project license":readme.html#intro.license.
+
+
+h2. Repairs
+
+* Synopsys VCS and Cadence NC-Sim simulators now correctly load Ruby-VPI. Also, the 64-bit versions of these simulators are now supported.
+
+
+h2. Improvements
+
+* Added "force_value", "release_value", and "value_forced?" methods to the @Vpi::Handle@ class.
+
+* @Vpi::Handle.put_value@ now tries to automatically detect the format of the value to be written. As a result, you can now write @your_handle.put_value 35@ in lieu of writing @your_handle.intVal = 35@.
+
+* @Vpi::Handle.inspect@ now shows the hexStrVal of the handle (because it is a common case to want to see a handle's logic value along with its other information).
+
+* Added method caching (memoizing) for VPI property accesses on handles.
+<% end %><% 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
@@ -68,7 +120,7 @@ h2. Thanks
 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.
+<% end %><% section "Version 16.0.0 (2007-05-02)", "16.0.0" do %>This release adds support for the "Cadence NC-Sim":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
@@ -90,7 +142,7 @@ h2. Caution
 
 h2. New features
 
-* The "Cadence NC-Sim / NC-Verilog":http://www.cadence.com/products/functional_ver/nc-verilog/ (ncsim) simulator is now supported.
+* The "Cadence NC-Sim":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

data/doc/history.yaml

@@ -1,3 +1,63 @@
+-
+  Version: 18.0.0
+
+  Date: 2007-07-31
+
+  Record: |
+    This release restores support for Synopsys VCS and Cadence NC-Sim, improves portability and performance, and enhances the VPI abstraction layer.
+
+
+    h2. Thanks
+
+    * Calvin Wong discovered "how to bypass the following error":http://rubyforge.org/forum/message.php?msg_id=25691 emitted by Synopsys VCS when loading the Ruby-VPI shared object file.
+
+      <pre>
+      Could not open library specified in -load option obj/vcs
+      obj/vcs: undefined symbol: vpi_put_data
+      </pre>
+
+
+    h2. Caution
+
+    * "SWIG":http://www.swig.org/ is now required in order to compile and install Ruby-VPI.
+
+    * @Vpi::Handle.put_value@ no longer checks whether the value written matches the value read back after writing because that only works when there is no VPI delay associated with the write.
+
+    * When @Vpi::Handle.put_value@ is used to write a value to a wire (VpiNet), it now _forces_ the value. This is done to ensure portability:
+
+      Synopsys VCS and Cadence NC-Sim forget the value written to a wire during the next simulation time step, whereas Mentor Modelsim and GPL Cver remember the value (thereby treating wires as registers).
+
+      Note that you have to release a forced value (using @Vpi::Handle.release_value@) on a wire after writing to the wire if you want the design under test have the ability to update the value of the wire later on:
+
+      <code>
+      your_wire.intVal = 15
+      your_wire.release_value
+      advance_time # let the Verilog DUT modify your_wire
+      </code>
+
+      In addition, you can check if a wire has a forced value using the @Vpi::Handle.value_forced?@ method.
+
+    * If the format is not specified, @Vpi::Handle.get_value@ now assumes that you want to read the value in VpiIntVal format (because this is the most common case).
+
+    * The definition of "Derivatives" has been reworded for clarity in the "project license":readme.html#intro.license.
+
+
+    h2. Repairs
+
+    * Synopsys VCS and Cadence NC-Sim simulators now correctly load Ruby-VPI. Also, the 64-bit versions of these simulators are now supported.
+
+
+    h2. Improvements
+
+    * Added "force_value", "release_value", and "value_forced?" methods to the @Vpi::Handle@ class.
+
+    * @Vpi::Handle.put_value@ now tries to automatically detect the format of the value to be written. As a result, you can now write @your_handle.put_value 35@ in lieu of writing @your_handle.intVal = 35@.
+
+    * @Vpi::Handle.inspect@ now shows the hexStrVal of the handle (because it is a common case to want to see a handle's logic value along with its other information).
+
+    * Added method caching (memoizing) for VPI property accesses on handles.
+
+
 -
   Version: 17.0.0
 
@@ -90,7 +150,7 @@
   Date: 2007-05-02
 
   Record: |
-    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.
+    This release adds support for the "Cadence NC-Sim":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
@@ -112,7 +172,7 @@
 
     h2. New features
 
-    * The "Cadence NC-Sim / NC-Verilog":http://www.cadence.com/products/functional_ver/nc-verilog/ (ncsim) simulator is now supported.
+    * The "Cadence NC-Sim":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

data/doc/intro.inc

@@ -10,23 +10,25 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
 
 <% 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.
+    * "What's new":history.html#<%= version.to_html_anchor %>
+      - release notes for version <%= version %>.
+    ** "History":history.html
+      - a record of all release notes.
+    ** <a type="application/rss+xml" href="<%= RSS_URL %>"><img src="images/feed-icon-28x28.png" alt="RSS feed for release announcements" style="float: right"/></a> "RSS feed":<%= RSS_URL %>
+      - keep track of new releases at your leisure.
     * "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 %>
+    * "Motivation":http://ruby-vpi.rubyforge.org/papers/masters_thesis.html#tth_sEc5.2
+      - why was Ruby-VPI developed?
     * "User manual":manual.html
-      - complete documentation for users. _Start here!_
+      - complete documentation for users.
     ** "Tutorial":manual.html#usage.tutorial
       - learn how to use Ruby-VPI quickly.
     * "Reference":../ref/
@@ -56,7 +58,7 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
   <% 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!
+    * Compiled _just once_ during "installation":manual.html#setup.inst and used forever!
   <% end %>
 
   <% paragraph "Agile" do %>
@@ -67,7 +69,7 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
 
     * 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.
+    ** The "automated test generator":manual.html#usage.tools.generate helps you accomodate design changes with _minimal_ effort.
     ** There is absolutely _no compiling_!
   <% end %>
 
@@ -95,12 +97,12 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
      - 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.
+    * "Cadence NC-Sim":http://www.cadence.com/products/functional_ver/nc-verilog/
+     - any version that supports the <tt>+loadvpi</tt> option is _mostly_ acceptable because you *will not* be able to "force values onto wires":manual.html#problem.ncsim.vpiForceFlag.
     * "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.
+    * "Icarus Verilog":http://www.geda.seul.org/tools/icarus/index.html
+      - version 0.8 is _mostly_ acceptable because you *will not* be able to "access child handles through method calls":manual.html#Accessing_a_handle_s_relatives. 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 %>
@@ -108,8 +110,10 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
       - 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.
+    * "SWIG":http://www.swig.org/download.html
+      - version 1.3.29 or newer is necessary.
+    * "Ruby":http://www.ruby-lang.org/en/downloads/
+      - 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.ruby-lang.org/en/downloads/.
   <% end %>
 
   <% paragraph "Libraries" do %>
@@ -170,7 +174,7 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
 
 
 <% section "License", "intro.license" do %>
-  <%=h File.read('../LICENSE') %>
+  <%= h(File.read('../LICENSE')).gsub(/^Copyright.*$/, '\&<br/>') %>
 <% end %>
 
 

data/doc/manual.doc

@@ -19,7 +19,7 @@
   <% paragraph "Legal notice" do %>
     This manual is distributed under <%= xref "intro.license", "the same license as Ruby-VPI" %>.
 
-    The admonition graphics used in this manual are Copyright 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org and are distributed under "these terms":./images/tango/LICENSE.
+    The admonition graphics used in this manual are Copyright 2005, 2006 "Tango Desktop Project":http://tango.freedesktop.org/Tango_Desktop_Project and are distributed under "these terms":./images/tango/LICENSE.
   <% end %>
 <% end %>
 
@@ -72,11 +72,11 @@
     $ gem env gemdir
     /usr/lib/ruby/gems/1.8
 
-    $ ls -d /usr/lib/ruby/gems/1.8/gems/ruby-vpi*
+    $ ls -d `gem env gemdir`/gems/ruby-vpi*
     /usr/lib/ruby/gems/1.8/gems/ruby-vpi-7.0.0/
     </pre>
 
-    <% note "Tuning for maximum performance" do %>
+    <% tip "Tuning for maximum performance" do %>
       You can tune your installation of Ruby-VPI for maximum performance by adding your C compiler's optimization flag to the @CFLAGS@ environment variable _before_ you run the <pre>gem install -y ruby-vpi</pre> command. For example, if your C compiler is GCC, then you can set @CFLAGS@ to <tt>-O9</tt> for maximum optimization.
     <% end %>
 
@@ -170,7 +170,7 @@
       <% section "@vprintf@ is @printf@" do %>
         The @vpi_vprintf@ and @vpi_mcd_vprintf@ VPI functions are aliased to @vpi_printf@ and @vpi_mcd_printf@ respectively because:
 
-        * Ruby represents "variable argument lists as arrays":http://www.rubycentral.com/book/tut_methods.html#UA instead of defining a special datatype, such as @va_list@, for them.
+        * Ruby represents "variable argument lists as arrays":http://phrogz.net/ProgrammingRuby/tut_methods.html#variablelengthargumentlists instead of defining a special datatype, such as @va_list@, for them.
 
         * Some C compilers have trouble with pointers to the @va_list@ type. For these compilers, the third line of source code shown below causes a "type mismatch" error.
 
@@ -479,7 +479,7 @@
   <% end %>
 
   <% section "Sample tests", "usage.examples" do %>
-    The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
+    The <tt>samp</tt> directory ("browse it online":<%= codeURL %>/samp/) contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
   <% end %>
 
   <% section "Tutorial", "usage.tutorial" do %>
@@ -581,7 +581,6 @@
       Before we continue,
       # Replace the contents of the file named <tt>RSpec/counter_spec.rb</tt> with the source code shown in <%= xref "fig:RSpec/counter_spec.rb" %>.
       # Replace the contents of the file named <tt>xUnit/counter_spec.rb</tt> with the source code shown in <%= xref "fig:xUnit/counter_spec.rb" %>.
-      # Replace the contents of the files named <tt>RSpec/counter_design.rb</tt> and <tt>xUnit/counter_design.rb</tt> with the following code. <code><%= File.read '../samp/counter/RSpec/counter_design.rb' %></code>
     <% end %>
 
 
@@ -711,6 +710,8 @@
   This chapter presents known problems and possible solutions.
 
   <% section "Icarus Verilog", "problem.ivl" do %>
+    The following sections describe problems that occur when Icarus Verilog is used with Ruby-VPI.
+
     <% section "Give full paths to Verilog objects", "problems.ivl.vpi_handle_by_name.absolute-paths" do %>
       In version 0.8 and snapshot 20061009 of Icarus Verilog, the @vpi_handle_by_name@ function requires an _absolute_ path (including the name of the bench which instantiates the design) to a Verilog object. In addition, @vpi_handle_by_name@ always returns @nil@ when its second parameter is specified.
 
@@ -755,10 +756,23 @@
         </code>
       <% end %>
     <% end %>
+
+    <% section "Vpi::reset", "problems.ivl.vpi_reset" do %>
+      In version 0.8 of Icarus Verilog, the @vpi_control(vpiReset)@ VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.
+    <% end %>
   <% end %>
 
-  <% section "Vpi::reset", "problems.ivl.vpi_reset" do %>
-    In version 0.8 of Icarus Verilog, the @vpi_control(vpiReset)@ VPI function causes an assertion to fail inside the simulator. As a result, the simulation terminates and a core dump is produced.
+  <% section "Cadence NC-Sim", "problem.ncsim" do %>
+    The following sections describe problems that occur when Cadence NC-Sim  (version 05.83-s003) is used with Ruby-VPI.
+
+    <% section "Cannot force values onto handles", "problem.ncsim.vpiForceFlag" do %>
+      When you write to a handle's value using @vpi_put_value()@ with the @VpiForceFlag@ propagation parameter, it does not have any effect.  As a result, the "register_file" sample test fails when you run it with NC-Sim.
+
+      This might be a bug in NC-Sim itself: even though I specified the "+access+rwc" command-line option for NC-Sim, I'm thinking that the force/release capability is not really enabled. However, it's more likely that there's a bug in the "register_file" sample test.
+
+      If you happen to know the solution, please tell me either on the project forums or via e-mail (see the LICENSE file for my e-mail address). Thanks.
+    <% end %>
+
   <% end %>
 <% end %>
 
@@ -792,7 +806,7 @@
   <% section "RSpec", "glossary.RSpec" do %>
     The <%= xref "glossary.BDD", "BDD" %> framework for Ruby.
 
-    See the "RSpec website":http://rspec.rubyforge.org and "tutorial":http://rspec.rubyforge.org/tutorials/index.html for more information.
+    See the "RSpec website":http://rspec.rubyforge.org and "tutorial":http://rspec.rubyforge.org/documentation/index.html for more information.
   <% end %>
 
   <% section "Test driven development", "glossary.TDD" do %>