ruby-vpi 18.0.2 → 19.0.0

data/doc/history.inc

@@ -1,4 +1,101 @@
-<% section "Version 18.0.2 (2007-08-03)", "18.0.2" do %>This release fixes a bug in error reporting.
+<% section "Version 19.0.0 (2007-08-27)", "19.0.0" do %>This release restores support for Cadence NC-Sim, breaks support for Mentor Modelsim, adds support for concurrent processes which simplify implementing Ruby prototypess, and offers numerous other improvements.
+
+*Mentor Modelsim users, take note*: this release does not work very well with Mentor Modelsim, so do not upgrade until compatibility is restored in a future release. In the mean time, consider using this release with another simulator, such as "GPL Cver":http://www.pragmatic-c.com/gpl-cver/.
+
+
+h2. Thanks
+
+* Calvin Wong "requested the concurrent processes feature":http://rubyforge.org/pipermail/ruby-vpi-discuss/2007-August/000046.html, helped test it, and provided useful feedback.
+
+
+h2. Caution
+
+* Prototypes no longer have a @feign!@ method.  Instead, they emulate the behavior of the real Verilog DUT using the new "concurrency model":manual.html#usage.concurrency.
+
+* All "initial" blocks in Verilog code are now evaluated _before_ the specification begins executing. This allows you to set the initial value of registers in Verilog before the specification interacts with them.
+
+* The @Vpi@ module has been renamed to @VPI@ for consistency with the project name.
+
+* The @VPI::simulation_time@ method has been renamed to @VPI::current_time@.
+
+* The @VPI::Handle.value_forced?@ method has been renamed to @VPI::Handle.force?@
+
+* The <tt>samp/</tt> directory has been renamed to <tt>examples/</tt>.
+
+* Code coverage analysis results are now produced only in plain-text format.
+
+
+h2. Repairs
+
+* You can now access VPI constants using their original uncapitalized names.  For example, you can now write "vpiIntVal" instead of having to write "VpiIntVal".  However, note that the capitalized names are still supported, so you are not required to change your code.
+
+* Value change / edge detection for VPI handles was previously incorrect:  if you called the @VPI::Handle.posedge?@ function twice in the same time step, it would give you two different answers.
+
+* The problem of not being able to write values to nets in Cadence NC-Sim has been fixed.
+
+
+h2. Additions
+
+* Added support for "concurrent processes":manual.html#usage.concurrency, which make Ruby prototypes appear more like Verilog code and also give the ability to write parallel tests.
+
+* Added support for performance profiling using the "ruby-prof":http://ruby-prof.rubyforge.org project. The profiler can be enabled by setting the @PROFILER@ environment variable to "1" before running a Ruby-VPI test.
+
+* Added new method aliases to @VPI::Handle@ for value detection. The complete list of aliases is now:
+** Tests if the logic value of this handle is unknown (x).
+*** x?
+*** unknown?
+*** dont_care?
+** Sets the logic value of this handle to unknown (x).
+*** x!
+*** unknown!
+*** dont_care!
+** Tests if the logic value of this handle is high impedance (z).
+*** z?
+*** hi_z?
+*** high_z?
+*** high_impedance?
+*** tri_state?
+*** floating?
+** Sets the logic value of this handle to high impedance (z).
+*** z!
+*** hi_z!
+*** high_z!
+*** high_impedance!
+*** tri_state!
+*** floating!
+** Tests if the logic value of this handle is at "logic high" level.
+*** high?
+*** one?
+** Sets the logic value of this handle to "logic high" level.
+*** high!
+*** one!
+** Tests if the logic value of this handle is at "logic low" level.
+*** low?
+*** zero?
+** Sets the logic value of this handle to "logic low" level.
+*** low!
+*** zero!
+
+* Added new methods to @VPI::Handle@ for value change / edge detection:
+** edge? - detects positive and negative edges
+** change? - detects any kind of value change
+** change_00? - detects a value change from 0 to 0
+** change_01? - detects a value change from 0 to 1
+** change_0x? - detects a value change from 0 to unknown
+** change_0z? - detects a value change from 0 to high-Z
+** change_10? - detects a value change from 1 to 0
+** change_11? - detects a value change from 1 to 1
+** change_1x? - detects a value change from 1 to unknown
+** change_1z? - detects a value change from 1 to high-Z
+** change_x0? - detects a value change from unknown to 0
+** change_x1? - detects a value change from unknown to 1
+** change_xx? - detects a value change from unknown to unknown
+** change_xz? - detects a value change from unknown to high-Z
+** change_z0? - detects a value change from high-Z to 0
+** change_z1? - detects a value change from high-Z to 1
+** change_zx? - detects a value change from high-Z to unknown
+** change_zz? - detects a value change from high-Z to high-Z
+<% end %><% section "Version 18.0.2 (2007-08-03)", "18.0.2" do %>This release fixes a bug in error reporting.
 
 
 h2. Repairs

data/doc/history.yaml

@@ -1,3 +1,108 @@
+-
+  Version: 19.0.0
+
+  Date: 2007-08-27
+
+  Record: |
+    This release restores support for Cadence NC-Sim, breaks support for Mentor Modelsim, adds support for concurrent processes which simplify implementing Ruby prototypess, and offers numerous other improvements.
+
+    *Mentor Modelsim users, take note*: this release does not work very well with Mentor Modelsim, so do not upgrade until compatibility is restored in a future release. In the mean time, consider using this release with another simulator, such as "GPL Cver":http://www.pragmatic-c.com/gpl-cver/.
+
+
+    h2. Thanks
+
+    * Calvin Wong "requested the concurrent processes feature":http://rubyforge.org/pipermail/ruby-vpi-discuss/2007-August/000046.html, helped test it, and provided useful feedback.
+
+
+    h2. Caution
+
+    * Prototypes no longer have a @feign!@ method.  Instead, they emulate the behavior of the real Verilog DUT using the new "concurrency model":manual.html#usage.concurrency.
+
+    * All "initial" blocks in Verilog code are now evaluated _before_ the specification begins executing. This allows you to set the initial value of registers in Verilog before the specification interacts with them.
+
+    * The @Vpi@ module has been renamed to @VPI@ for consistency with the project name.
+
+    * The @VPI::simulation_time@ method has been renamed to @VPI::current_time@.
+
+    * The @VPI::Handle.value_forced?@ method has been renamed to @VPI::Handle.force?@
+
+    * The <tt>samp/</tt> directory has been renamed to <tt>examples/</tt>.
+
+    * Code coverage analysis results are now produced only in plain-text format.
+
+
+    h2. Repairs
+
+    * You can now access VPI constants using their original uncapitalized names.  For example, you can now write "vpiIntVal" instead of having to write "VpiIntVal".  However, note that the capitalized names are still supported, so you are not required to change your code.
+
+    * Value change / edge detection for VPI handles was previously incorrect:  if you called the @VPI::Handle.posedge?@ function twice in the same time step, it would give you two different answers.
+
+    * The problem of not being able to write values to nets in Cadence NC-Sim has been fixed.
+
+
+    h2. Additions
+
+    * Added support for "concurrent processes":manual.html#usage.concurrency, which make Ruby prototypes appear more like Verilog code and also give the ability to write parallel tests.
+
+    * Added support for performance profiling using the "ruby-prof":http://ruby-prof.rubyforge.org project. The profiler can be enabled by setting the @PROFILER@ environment variable to "1" before running a Ruby-VPI test.
+
+    * Added new method aliases to @VPI::Handle@ for value detection. The complete list of aliases is now:
+    ** Tests if the logic value of this handle is unknown (x).
+    *** x?
+    *** unknown?
+    *** dont_care?
+    ** Sets the logic value of this handle to unknown (x).
+    *** x!
+    *** unknown!
+    *** dont_care!
+    ** Tests if the logic value of this handle is high impedance (z).
+    *** z?
+    *** hi_z?
+    *** high_z?
+    *** high_impedance?
+    *** tri_state?
+    *** floating?
+    ** Sets the logic value of this handle to high impedance (z).
+    *** z!
+    *** hi_z!
+    *** high_z!
+    *** high_impedance!
+    *** tri_state!
+    *** floating!
+    ** Tests if the logic value of this handle is at "logic high" level.
+    *** high?
+    *** one?
+    ** Sets the logic value of this handle to "logic high" level.
+    *** high!
+    *** one!
+    ** Tests if the logic value of this handle is at "logic low" level.
+    *** low?
+    *** zero?
+    ** Sets the logic value of this handle to "logic low" level.
+    *** low!
+    *** zero!
+
+    * Added new methods to @VPI::Handle@ for value change / edge detection:
+    ** edge? - detects positive and negative edges
+    ** change? - detects any kind of value change
+    ** change_00? - detects a value change from 0 to 0
+    ** change_01? - detects a value change from 0 to 1
+    ** change_0x? - detects a value change from 0 to unknown
+    ** change_0z? - detects a value change from 0 to high-Z
+    ** change_10? - detects a value change from 1 to 0
+    ** change_11? - detects a value change from 1 to 1
+    ** change_1x? - detects a value change from 1 to unknown
+    ** change_1z? - detects a value change from 1 to high-Z
+    ** change_x0? - detects a value change from unknown to 0
+    ** change_x1? - detects a value change from unknown to 1
+    ** change_xx? - detects a value change from unknown to unknown
+    ** change_xz? - detects a value change from unknown to high-Z
+    ** change_z0? - detects a value change from high-Z to 0
+    ** change_z1? - detects a value change from high-Z to 1
+    ** change_zx? - detects a value change from high-Z to unknown
+    ** change_zz? - detects a value change from high-Z to high-Z
+
+
 -
   Version: 18.0.2
 

data/doc/intro.inc

@@ -102,7 +102,7 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
      - any version that supports the <tt>-pli</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 should be acceptable. However, version 05.83-s003 is _mostly_ acceptable because you *will not* be able to "force values onto wires":manual.html#problem.ncsim.vpiForceFlag.
+     - any version that supports the <tt>+loadvpi</tt> option should be acceptable.
 
     * "GPL Cver":http://www.pragmatic-c.com/gpl-cver/
      - version 2.11a or newer is acceptable.
@@ -135,6 +135,41 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
 <% 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:
+  ** @your_register.intVal = 2 ** 2048@
+  ** @your_register.put_value 2 ** 2048@
+
+  * Check if all nets in a module are at high impedance:
+  ** @your_module.all_net? { |your_net| your_net.z? }@
+  ** <code>
+  your_nets = your_module.net_a
+  your_nets.all? { |net| net.z? }
+  </code>
+
+  * See a register's path, width, and location (file & line number):
+  ** @puts your_register@
+  ** <code>
+  p :path  => your_register.fullName
+  p :width => your_register.size
+  p :file  => your_register.fileName
+  p :file  => your_register.lineNo
+  </code>
+
+  * Access the first five elements in a memory:
+  ** @your_memory.memoryWord_a.first(5)@
+  ** @your_memory.memoryWord_a[0..4]@
+  ** @your_memory.memoryWord_a[0, 5]@
+
+  * Clear a memory by filling it with zeroes:
+  ** @your_memory.each_memoryWord { |w| w.zero! }@
+  ** @your_memory.each_memoryWord { |w| w.intVal = 0 }@
+  ** @your_memory.each_memoryWord { |w| w.put_value 0 }@
+<% end %>
+
+
 <% section "Applications", "intro.applications" do %>
   Examples of tasks that can be performed with Ruby-VPI are:
 
@@ -158,39 +193,10 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
 <% 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@
-
-  * 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@
-
-  * Access the first five elements in a memory:
-
-  bq. @your_memory.memoryWord_a[0..4]@
-
-  * Clear a memory by filling it with zeroes:
-
-  bq. @your_memory.each_memoryWord {|w| w.intVal = 0}@
-<% end %>
-
-
-<% section "License", "intro.license" do %>
-  <%= h(File.read('../LICENSE')).gsub(/^Copyright.*$/, '\&<br/>') %>
-<% end %>
-
-
 <% section "Related works", "intro.related-works" do %>
-  * "JOVE":http://jove.sourceforge.net is a Java interface to VPI.
+  * "ANVIL":http://anvil.sourceforge.net is a C++ interface to VPI.
   * "Teal":http://teal.sourceforge.net is a C++ interface to VPI.
+  * "JOVE":http://jove.sourceforge.net is a Java 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.
@@ -202,3 +208,8 @@ Ruby-VPI is "open source software":http://en.wikipedia.org/wiki/Open_source_soft
     * "Verilog::Pli":http://www.veripool.com/verilog-pli.html is a Perl interface to PLI.
   <% end %>
 <% end %>
+
+
+<% section "License", "intro.license" do %>
+  <%= h(File.read('../LICENSE')).gsub(/^Copyright.*$/, '\&<br/>') %>
+<% end %>

data/doc/lib/doc_format.rb

@@ -48,8 +48,8 @@ class String
     end
 
 
-    ## fix annoyances in Textile conversion 
-    
+    ## fix annoyances in Textile conversion
+
     # redcloth wraps indented text within <pre> tags
     html.gsub! %r{(<pre>)\s*<code>(.*?)\s*</code>\s*(</pre>)}m, '\1\2\3'
     html.gsub! %r{(<pre>)\s*<pre>(.*?)</pre>\s*(</pre>)}m, '\1\2\3'
@@ -85,25 +85,31 @@ class String
   # Otherwise, the programming language is assumed to be ruby.
   def coderay
     gsub %r{<(code)(.*?)>(.*?)</\1>}m do
-      code = CGI.unescapeHTML $3
-      atts = $2
+      matches = $~
 
-      lang =
-        if $2 =~ /lang=('|")(.*?)\1/i
-          $2
-        else
-          :ruby
-        end
+      atts = matches[2]
+      lang = if atts =~ /lang=('|")(.*?)\1/i then $2 else :ruby end
+
+      # obtain the raw source code w/o extraneous indentation
+      code = CGI.unescapeHTML(matches[3]).rstrip
+
+      if matches.pre_match =~ /^[ \t]+$/
+        code.gsub! %r/^#{$&}/, ''
+      end
+
+      # convert the code into HTML
+      html = CodeRay.scan(code, lang).html(:css => :style)
+
+      # perform smart sizing (block vs. inline) of the code
+      trailingText = matches.post_match[/^.*$/].to_s.strip
 
       tag =
-        if code =~ /\n/
+        if code =~ /\n/ or trailingText.empty? or trailingText =~ %r{^</(p|div|body)}
           :pre
         else
           :code
         end
 
-      html = CodeRay.scan(code, lang).html(:css => :style)
-
       %{<#{tag} class="code"#{atts}>#{html}</#{tag}>}
     end
   end

data/doc/lib/doc_proxy.rb

@@ -64,7 +64,7 @@ class DocProxy < ErbProxy
                   end
                 }
 
-                <p class="title"><a href="##{node.tocAnchor}">#{type.to_s.capitalize} #{node.number}</a>. &nbsp; #{node.title.to_html}</p>
+                <p class="title"><a href="##{node.tocAnchor}" class="ref">#{type.to_s.capitalize} #{node.number}</a>. &nbsp; #{node.title.to_html}</p>
 
                 #{content.to_html}
               </div>
@@ -93,7 +93,7 @@ class DocProxy < ErbProxy
 
         <div id="#{node.anchor}" class="part">
           <h1 class="title">
-            Part <a href="##{node.tocAnchor}">#{node.number}</a>
+            Part <a href="##{node.tocAnchor}" class="ref">#{node.number}</a>
 
             <br/><br/>
 
@@ -112,7 +112,7 @@ class DocProxy < ErbProxy
 
         <div id="#{node.anchor}" class="chapter">
           <h1 class="title">
-            Chapter <a href="##{node.tocAnchor}">#{node.latexNumber}</a>
+            Chapter <a href="##{node.tocAnchor}" class="ref">#{node.latexNumber}</a>
 
             <br/><br/>
 
@@ -132,7 +132,7 @@ class DocProxy < ErbProxy
 
         <div id="#{node.anchor}" class="section">
           <h#{level} class="title">
-            <a href="##{node.tocAnchor}">#{node.latexNumber}</a>
+            <a href="##{node.tocAnchor}" class="ref">#{node.latexNumber}</a>
 
             &nbsp;
 
@@ -192,7 +192,7 @@ class DocProxy < ErbProxy
 
       if node
         words = [
-          %{<a href="##{node.anchor}">Reference #{node.number}</a>},
+          %{<a href="##{node.anchor}" class="ref">Reference #{node.number}</a>},
 
           # extra information about the citation (page #, etc.)
           *args.map {|s| s.to_html}
@@ -213,7 +213,7 @@ class DocProxy < ErbProxy
 
       if target
         title = aTitle || "#{target.type.to_s.capitalize} #{target.latexNumber || target.number}"
-        %{<a href="##{target.anchor}">#{title.to_html}</a>}
+        %{<a href="##{target.anchor}" class="ref">#{title.to_html}</a>}
       else
         warn "invalid xref to #{aTarget.inspect}"
         ''
@@ -520,7 +520,7 @@ class DocProxy < ErbProxy
 
 
         # generate hyperlink for traveling from TOC to heading
-        toc << %{<li><span class="hide">#{node.latexNumber} </span><a id="#{node.tocAnchor}" href="##{node.anchor}">#{node.title.to_html}</a></li>}
+        toc << %{<li>#{node.latexNumber} <a id="#{node.tocAnchor}" href="##{node.anchor}" class="ref">#{node.title.to_html}</a></li>}
       end
 
       if prevIndex.empty?