ruby-vpi 11.0.0 → 11.1.0

data/history.part.html

@@ -18,6 +18,78 @@ We <em>strictly</em> follow the RubyGems project&#8217;s <a href="http://www.rub
 	<p id="fn1"><sup>1</sup> C. Gross, &#8220;Explaining Open Source Version Numbers&#8221;, [Online document], 2005 Nov 28, [cited 2006 Aug 27], Available <span class="caps">HTTP</span>: <a href="http://ablog.apress.com/?p=738">http://ablog.apress.com/?p=738</a></p>
 
 
+	<h1>Version 11.1.0 (2006-11-08)</h1>
+
+
+	<h2>Summary</h2>
+
+
+	<p>This release fixes a bug in generated benches, improves the <a href="./ref/ruby/classes/Vpi/Handle.html">the <code>Vpi::Handle</code> class</a>, and improves performance by roughly 20%.</p>
+
+
+	<h2>Acknowledgment</h2>
+
+
+	<p>Thanks to Matt Fischler for finding the bug in generated benches (see below).</p>
+
+
+	<h2>Notice</h2>
+
+
+	<ul>
+	<li>A bug in generated Verilog and Ruby benches, which caused this error <pre>ruby: no such file to load -- ruby-vpi (LoadError)</pre> has been fixed.
+	<ul>
+	<li>Please regenerate your tests to apply this bug fix to your tests.</li>
+	</ul></li>
+	</ul>
+
+
+	<h2>Detail</h2>
+
+
+	<ul>
+	<li>The class <code>SWIG::TYPE_p_unsigned_int</code> has been aliased as <code>Vpi::Handle</code> for easier access.</li>
+	</ul>
+
+
+	<ul>
+	<li><code>Vpi::Handle#to_s</code> and <code>Vpi::Handle#inspect</code> now produce more informative output. For example, what used to appear as <pre>#&lt;SWIG::TYPE_p_unsigned_int:0x2aaab6574fa0&gt;</pre> now appears as <pre>#&lt;Vpi::Handle vpiModule fullName=counter_rspec_bench, size=-1, file=counter_rspec_bench.v, lineNo=2&gt;</pre> in this release.
+	<ul>
+	<li>You can also provide a list of <span class="caps">VPI</span> property/type names or integer constants to those methods to see additional information in the output.</li>
+	</ul></li>
+	</ul>
+
+
+	<ul>
+	<li><code>Vpi::Handle</code> now implements all methods from <code>Enumerable</code>, such as <code>map</code>, <code>each</code>, <code>select</code>, and so on. However, unlike their counterparts in <code>Enumerable</code>, these methods also accept a list of <span class="caps">VPI</span> property/type names or integer constants. Thus, you are now able to write <code>handle.select(:reg, :net) {|h| h.size &gt; 5}</code> to obtain a list of child handles to registers and nets whose capacity is greater than 5 bits.</li>
+	</ul>
+
+
+	<ul>
+	<li>The <code>Vpi::Handle#[]</code>, <code>Vpi::Handle#get_value</code>, and <code>Vpi::Handle#put_value</code> methods now accept names of <span class="caps">VPI</span> types/properties as well as their integer constants. Thus, you are now able to write <code>handle[:reg, :net]</code> to obtain a list of handles to all child registers and nets.</li>
+	</ul>
+
+
+	<ul>
+	<li><code>Vpi::Handle#method_missing</code> has been refactored to cache queries. There is now, approximately, 20% improvement in performance.</li>
+	</ul>
+
+
+	<ul>
+	<li><code>Vpi::Handle#method_missing</code> has been fixed to accept operations with multiple underscores. For example, before this release, you could not write <code>handle.find_all_reg {|r| r.name =~ /foo/}</code> because the &#8220;find_all_reg&#8221; method would be interpreted as the operation &#8220;find&#8221; and the <span class="caps">VPI</span> property &#8220;all_reg&#8221;.</li>
+	</ul>
+
+
+	<ul>
+	<li>The <code>IntegerGenerator</code> class, in the pipelined <span class="caps">ALU</span> example, has been fixed so that multiple instances do not interfere with the generation of each other&#8217;s prime integers.</li>
+	</ul>
+
+
+	<ul>
+	<li>Due to a bug in the <code>Rakefile</code>, the reference documentation was not included in the previous few releases. This has been fixed.</li>
+	</ul>
+
+
 	<h1>Version 11.0.0 (2006-11-05)</h1>
 
 
@@ -138,7 +210,7 @@ end</pre> notation.
 
 
 	<ul>
-	<li>Revised the stylesheet to make disjoint sections readily distinguishable from eachother, through generous spacing and minor coloring.</li>
+	<li>Revised the stylesheet to make disjoint sections readily distinguishable from each other, through generous spacing and minor coloring.</li>
 	</ul>
 
 

data/lib/ruby-vpi.rb

@@ -19,13 +19,13 @@
 =end
 
 module RubyVpi
-  # Initializes the current bench by loading:
+  # Initializes the bench by loading:
   # 1. the design.rb file
-  # 2. the proto.rb file (if prototyping is enabled)
+  # 2. the proto.rb file if prototyping is enabled
   # 3. the spec.rb file
   #
-  # aDesignId:: The name of the Ruby interface to the design under test.
-  # aSpecFormat:: The format of the specification.
+  # aDesignId:: The name of the Ruby design object.
+  # aSpecFormat:: The format being used by the specification.
   def RubyVpi.init_bench aDesignId, aSpecFormat
     if caller.find {|s| s =~ /^(.*?)_bench.rb:/}
       testName = $1
@@ -90,7 +90,7 @@ module RubyVpi
       require "#{testName}_spec.rb"
   end
 
-  # Provides information about the Ruby-VPI project's configuration.
+  # Provides information about this project's configuration.
   module Config
     PROJECT_ID = 'ruby-vpi'
     PROJECT_NAME = 'Ruby-VPI'

data/lib/ruby-vpi/verilog_parser.rb

@@ -101,7 +101,7 @@ class VerilogParser
 end
 
 class String
-  # Converts this string containing Verilog code into loadable Ruby code.
+  # Converts this string containing Verilog code into syntactically correct Ruby code.
   def verilog_to_ruby
     content = self.dup
 

data/lib/ruby-vpi/vpi.rb

@@ -20,47 +20,35 @@
   Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 =end
 
-module SWIG
-=begin rdoc
-  This class represents an object inside a Verilog simulation. Such an object is known as a _handle_ in Verilog jargon. See *vpiHandle* in IEEE Std. 1364-2005 for details.
-
-  = Reading and writing values
-  There are several ways to read and write a handle's value, depending on its representation.
-
-  == Using +S_vpi_value+ objects
-  You can read and write values using +S_vpi_value+ objects through the following methods.
-  * #get_value_wrapper
-  * Vpi::vpi_get_value
-  * Vpi::vpi_put_value
-
-  == Using values and formats
-  You can read and write values, while specifying their format, through the following methods.
-  * value = handle.#get_value(format)
-  * handle.#put_value(value, format)
-
-  == Using values directly
-  You can read and write values directly, while implicitly specifying their format, through several shortcut methods. The names of these methods can be determined by (1) taking the name of a VPI value format listed in the *VALUE_FORMAT_NAMES* array, (2) removing the "Vpi" prefix, and (3) converting the first character into lower-case.
-
-  For example, the shortcut methods for reading and writing values using the <tt><b>Vpi</b><em>I</em>ntVal</tt> format are:
-  * intVal
-  * intVal=
-
-  The methods shown above can be used like so:
-  * value = handle.#intVal
-  * handle.#intVal = value
-
-  == Examples of all approaches
-  To read a handle's value as an integer:
-  * handle.#get_value(VpiIntVal)
-  * handle.intVal
-
-  To write a handle's value as an integer:
-  * handle.#put_value(15, VpiIntVal)
-  * handle.intVal = 15
-=end
-  class TYPE_p_unsigned_int
+module Vpi
+  Handle = SWIG::TYPE_p_unsigned_int
+
+  # An object inside a Verilog simulation (see *vpiHandle* in IEEE Std. 1364-2005).
+  # * VPI types and properties listed in ext/vpi_user.h can be specified by their names (strings or symbols) or integer constants.
+  #   * example names:
+  #     * "intVal"
+  #     * :intVal
+  #     * "vpiIntVal"
+  #     * :vpiIntVal
+  #     * "VpiIntVal"
+  #     * :VpiIntVal
+  #   * example constants:
+  #     * VpiIntVal
+  #     * VpiModule
+  #     * VpiReg
+  class Handle
     include Vpi
 
+    # inherit Enumerable methods, such as #each, #map, #select, etc.
+      Enumerable.instance_methods.each do |meth|
+        # using a string because define_method does not accept a block until Ruby 1.9
+        class_eval %{
+          def #{meth} *args, &block
+            self[*args].send(:#{meth}, &block)
+          end
+        }
+      end
+
     # Tests if the logic value of this handle is "don't care" (x).
     def x?
       self.hexStrVal =~ /x/i
@@ -71,7 +59,7 @@ module SWIG
       self.hexStrVal =~ /z/i
     end
 
-    # Reads the value using the given format and returns a +S_vpi_value+ object.
+    # Reads the value using the given format (integer constant) and returns a +S_vpi_value+ object.
     def get_value_wrapper aFormat
       val = S_vpi_value.new
       val.format = aFormat
@@ -80,9 +68,9 @@ module SWIG
       val
     end
 
-    # Reads the value using the given format and returns it. If a format is not given, then the Verilog simulator will attempt to determine the correct format.
+    # Reads the value using the given format (name or integer constant) and returns it. If a format is not given, then the Verilog simulator will attempt to determine the correct format.
     def get_value aFormat = VpiObjTypeVal
-      val = get_value_wrapper(aFormat)
+      val = get_value_wrapper(resolve_prop_type(aFormat))
 
       case val.format
         when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
@@ -111,9 +99,14 @@ module SWIG
       end
     end
 
-    # Writes the given value using the given format, time, and delay, and then returns the given value. If a format is not given, then the Verilog simulator will attempt to determine the correct format.
+    # Writes the given value using the given format (name or integer constant), time, and delay, and then returns the given value. If a format is not given, then the Verilog simulator will attempt to determine the correct format.
     def put_value aValue, aFormat = nil, aTime = nil, aDelay = VpiNoDelay
-      aFormat ||= get_value_wrapper(VpiObjTypeVal).format
+      aFormat =
+        if aFormat
+          resolve_prop_type(aFormat)
+        else
+          get_value_wrapper(VpiObjTypeVal).format
+        end
 
       newVal = S_vpi_value.new
       newVal.format = aFormat
@@ -180,153 +173,175 @@ module SWIG
       aValue
     end
 
-    HINT_REGEXP = %r{_([a-z])$}
-    ASSIGN_REGEXP = %r{=$}
-    QUERY_REGEXP = %r{\?$}
-    PREFIX_REGEXP = %r{^(.*?)_}
-
-    # Enables access to (1) child handles and (2) VPI properties of this handle. In the case that a child handle has the same name as a VPI property, the child handle will be accessed instead of the VPI property. However, you can still access the VPI property via #get_value and #put_value.
-    def method_missing aMsg, *aArgs, &aBlockArg
-      methName = aMsg.to_s
-
-      # give access to a child handle if possible
-        if child = vpi_handle_by_name(methName, self)
-          # cache the child for future accesses, in order to cut down number of calls to method_missing
-            (class << self; self; end).class_eval do
-              define_method aMsg do
-                child
-              end
-            end
+    # Returns an array of child handles of the given types (name or integer constant).
+    def [] *aTypes
+      handles = []
 
-          return child
-        end
+      aTypes.each do |t|
+        t = resolve_prop_type(t)
 
-      # determine if property is being written
-        if isAssign = methName =~ ASSIGN_REGEXP
-          methName.sub! ASSIGN_REGEXP, ''
+        if itr = vpi_iterate(t, self)
+          while h = vpi_scan(itr)
+            handles << h
+          end
         end
+      end
 
-      # determine if property is being queried
-        if isQuery = methName =~ QUERY_REGEXP
-          methName.sub! QUERY_REGEXP, ''
-        end
+      handles
+    end
 
-      # parse Accessor parameter
-        if accessor = methName[HINT_REGEXP, 1]
-          methName.sub! HINT_REGEXP, ''
-        end
+    # Inspects the given VPI property names, in addition to those common to all handles.
+    def inspect *aPropNames
+      aPropNames.unshift :fullName, :size, :file, :lineNo
+
+      aPropNames.map! do |name|
+        "#{name}=#{self.send(name.to_sym)}"
+      end
+
+      "#<Vpi::Handle #{vpiType_s} #{aPropNames.join(', ')}>"
+    end
+
+    alias to_s inspect
+
+
+    @@propCache = Hash.new {|h, k| h[k] = Property.resolve(k)}
+
+    # Provides access to this handle's
+    # 1. child handles
+    # 2. VPI properties
+    # through method calls. In the case that a child handle has the same name as a VPI property, the child handle will be accessed instead of the VPI property. However, you can still access the VPI property via #get_value and #put_value.
+    def method_missing aMeth, *aArgs, &aBlockArg
+      if child = vpi_handle_by_name(aMeth.to_s, self)
+        # cache the child for future accesses, in order to cut down number of calls to method_missing
+          (class << self; self; end).class_eval do
+            define_method aMeth do
+              child
+            end
+          end
+
+        child
+
+      else
+        prop = @@propCache[aMeth]
+
+        if prop.operation
+          self.send(prop.operation, prop.type, *aArgs, &aBlockArg)
+
+        else
+          case prop.accessor
+            when :d	# delay values
+              raise NotImplementedError, 'processing of delay values is not yet implemented.'
+              # TODO: vpi_put_delays
+              # TODO: vpi_get_delays
+
+            when :l	# logic values
+              if prop.assignment
+                value = aArgs.shift
+                put_value(value, prop.type, *aArgs)
+              else
+                get_value(prop.type)
+              end
 
-      # parse Operation parameter
-        if operation = methName[PREFIX_REGEXP, 1]
-          methName.sub! PREFIX_REGEXP, ''
+            when :i	# integer values
+              vpi_get(prop.type, self) unless prop.assignment
+
+            when :b # boolean values
+              unless prop.assignment
+                value = vpi_get(prop, self)
+                value && (value != 0)	# zero is false in C
+              end
+
+            when :s	# string values
+              vpi_get_str(prop.type, self) unless prop.assignment
+
+            when :h	# handle values
+              vpi_handle(prop.type, self) unless prop.assignment
+
+            else
+              raise NoMethodError, "unable to access VPI property #{prop.name.inspect} through method #{aMeth.inspect} with arguments #{aArgs.inspect} for handle #{self}"
+          end
         end
+      end
+    end
 
-      # resolve Property parameter into a valid VPI property
-        propName = methName[0, 1].upcase << methName[1..-1]
-        propName.insert(0, 'Vpi') unless methName =~ /^vpi/
+    Property = Struct.new :type, :name, :operation, :accessor, :assignment
 
-        puts '', Kernel.caller.join("\n"), '', "operation: #{operation}", "meth: #{aMsg}", "args: #{aArgs.inspect}", "name: #{methName}", "prop: #{propName}", "assign: #{isAssign}", "query: #{isQuery}" if $DEBUG
+    # Resolves the given shorthand name into a description of its VPI property.
+    def Property.resolve aName
+      # parse the given property name
+        tokens = aName.to_s.split(/_/)
+
+
+        tokens.last.sub!(/[\?!=]$/, '')
+
+        addendum = $&
+        isAssign = $& == '='
+        isQuery = $& == '?'
+
+
+        tokens.last =~ /^[a-z]$/ && tokens.pop
+        accessor = $&
+
+        name = tokens.pop
+
+        operation =
+          unless tokens.empty?
+            tokens.join('_') << (addendum || '')
+          end
+
+      # determine the VPI integer type for the property
+        name = name[0, 1].upcase << name[1..-1]
+        name.insert 0, 'Vpi' unless name =~ /^[Vv]pi/
 
         begin
-          prop = Vpi.const_get(propName)
+          type = Vpi.const_get(name)
         rescue NameError
-          raise ArgumentError, "invalid VPI property #{propName.inspect}"
+          raise ArgumentError, "#{name.inspect} is not a valid VPI property"
         end
 
-      # access the VPI property
-        if operation
-          return self.send(operation.to_sym, prop, *aArgs, &aBlockArg)
-        else
-          loop do
-            puts "looping, accessor: #{accessor}" if $DEBUG
-
-            case accessor
-              when 'd'	# delay values
-                if isAssign
-                  # TODO: vpi_put_delays
-                else
-                  # TODO: vpi_get_delays
-                end
-
-              when 'l'	# logic values
-                if isAssign
-                  value = aArgs.shift
-                  return put_value(value, prop, *aArgs)
-                else
-                  return get_value(prop)
-                end
-
-              when 'i'	# integer values
-                return vpi_get(prop, self) unless isAssign
-
-              when 'b'	# boolean values
-                unless isAssign
-                  value = vpi_get(prop, self)
-                  return value && (value != 0)	# zero is false in C
-                end
-
-              when 's'	# string values
-                return vpi_get_str(prop, self) unless isAssign
-
-              when 'h'	# handle values
-                return vpi_handle(prop, self) unless isAssign
-
-              else	# accessor not specified. guess its value from property name
-                if isQuery
-                  accessor = 'b'
-                  redo
-                end
-
-                case propName
-                  when /Time$/
-                    accessor = 'd'
-                    redo
-
-                  when /Val$/
-                    accessor = 'l'
-                    redo
-
-                  when /Type$/, /Direction$/, /Index$/, /Size$/, /Strength\d?$/, /Polarity$/, /Edge$/, /Offset$/, /Mode$/
-                    accessor = 'i'
-                    redo
-
-                  when /Is[A-Z]/, /ed$/
-                    accessor = 'b'
-                    redo
-
-                  when /Name$/, /File$/, /Decompile$/
-                    accessor = 's'
-                    redo
-
-                  when /Parent$/, /Inst$/, /Range$/, /Driver$/, /Net$/, /Load$/, /Conn$/, /Bit$/, /Word$/, /[LR]hs$/, /(In|Out)$/, /Term$/, /Argument$/, /Condition$/, /Use$/, /Operand$/, /Stmt$/, /Expr$/, /Scope$/, /Memory$/, /Delay$/
-                    accessor = 'h'
-                    redo
-                end
-            end
+      accessor =
+        if accessor
+          accessor.to_sym
 
-            break
-          end
-        end
+        else # infer accessor from VPI property name
+          if isQuery
+            :b
 
-      raise NoMethodError, "unable to access VPI property #{propName.inspect} through method #{aMsg.inspect} with arguments #{aArgs.inspect} for handle #{self}"
-    end
+          else
+            case name
+              when /Time$/
+                :d
 
-    # Returns an array of handles of the given type.
-    def [] aType
-      handles = []
+              when /Val$/
+                :l
+
+              when /Type$/, /Direction$/, /Index$/, /Size$/, /Strength\d?$/, /Polarity$/, /Edge$/, /Offset$/, /Mode$/, /LineNo$/
+                :i
 
-      if itr = vpi_iterate(aType, self)
-        while h = vpi_scan(itr)
-          handles << h
+              when /Is[A-Z]/, /ed$/
+                :b
+
+              when /Name$/, /File$/, /Decompile$/
+                :s
+
+              when /Parent$/, /Inst$/, /Range$/, /Driver$/, /Net$/, /Load$/, /Conn$/, /Bit$/, /Word$/, /[LR]hs$/, /(In|Out)$/, /Term$/, /Argument$/, /Condition$/, /Use$/, /Operand$/, /Stmt$/, /Expr$/, /Scope$/, /Memory$/, /Delay$/
+                :h
+            end
+          end
         end
-      end
 
-      handles
+      Property.new type, name, operation, accessor, isAssign
     end
 
-    # Iterates over all handles of the given type and executes the given block once for each handle.
-    def each aType, &aBlock	# :yields: handle
-      self[aType].each(&aBlock)
+    private
+
+    # resolve type names into type constants
+    def resolve_prop_type aNameOrType
+      if aNameOrType.is_a? Integer
+        aNameOrType
+      else
+        @@propCache[aNameOrType.to_sym].type
+      end
     end
   end
 end