ruby-vpi 18.0.2 → 19.0.0

data/lib/ruby-vpi/core/callback.rb

@@ -0,0 +1,142 @@
+# Simulation callbacks.
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+require 'singleton'
+
+module RubyVPI
+  class CallbackClass #:nodoc:
+    include Singleton
+
+    def initialize
+      @id2handler = {}
+      @id2receipt = {}
+      @lock = Mutex.new
+    end
+
+    def attach aData, &aHandler
+      raise ArgumentError, "block must be given" unless block_given?
+      id = aHandler.object_id.to_s
+
+      # register the callback with Verilog
+      aData.user_data = id
+      aData.cb_rtn    = VPI::Vlog_relay_ruby
+      receipt         = VPI::__callback__vpi_register_cb(aData)
+
+      @lock.synchronize do
+        @id2handler[id] = aHandler
+        @id2receipt[id] = receipt
+      end
+
+      receipt
+    end
+
+    def detach aData
+      id = aData.user_data.to_s
+      receipt = @lock.synchronize{ @id2receipt[id] }
+
+      if receipt
+        VPI::__callback__vpi_remove_cb(receipt)
+
+        @lock.synchronize do
+          @id2handler.delete id
+          @id2receipt.delete id
+        end
+      end
+    end
+
+    # Transfers control to the simulator, which will return control
+    # during the given time slot after the given number of time steps.
+    def relay_verilog aTimeSlot, aNumSteps
+      # schedule wake-up callback from verilog
+      time            = VPI::S_vpi_time.new
+      time.integer    = aNumSteps
+      time.type       = VPI::VpiSimTime
+
+      value           = VPI::S_vpi_value.new
+      value.format    = VPI::VpiSuppressVal
+
+      alarm           = VPI::S_cb_data.new
+      alarm.reason    = aTimeSlot
+      alarm.cb_rtn    = VPI::Vlog_relay_ruby
+      alarm.obj       = nil
+      alarm.time      = time
+      alarm.value     = value
+      alarm.index     = 0
+      alarm.user_data = nil
+
+      VPI.vpi_free_object(VPI::__callback__vpi_register_cb(alarm))
+
+      # transfer control to verilog
+      loop do
+        VPI::__extension__relay_verilog
+
+        if reason = VPI::__extension__relay_ruby_reason # might be nil
+          id = reason.user_data.to_s
+
+          handler = @lock.synchronize do
+            @id2handler[id]
+          end
+
+          if handler
+            handler.call reason
+          else
+            break
+          end
+        end
+      end
+    end
+  end
+
+  Callback = CallbackClass.instance
+end
+
+module VPI
+  class Handle
+    # Registers a callback that is invoked
+    # whenever the value of this object changes.
+    def cbValueChange aOptions = {}, &aHandler
+      raise ArgumentError unless block_given?
+
+      aOptions[:time]  ||= S_vpi_time.new(:type => VpiSuppressTime)
+      aOptions[:value] ||= S_vpi_value.new(:format => VpiSuppressVal)
+
+      alarm = S_cb_data.new(
+        :reason => CbValueChange,
+        :obj    => self,
+        :time   => aOptions[:time],
+        :value  => aOptions[:value],
+        :index  => 0
+      )
+
+      vpi_register_cb alarm, &aHandler
+    end
+  end
+
+
+  alias_method :__callback__vpi_register_cb, :vpi_register_cb
+  module_function :__callback__vpi_register_cb
+
+  # This is a Ruby version of the vpi_register_cb C function.  It is
+  # identical to the C function, except for the following differences:
+  #
+  # * This method accepts a block (callback handler)
+  #   which is executed whenever the callback occurs.
+  #
+  # * This method overwrites the +cb_rtn+ and +user_data+
+  #   fields of the given +S_cb_data+ object.
+  #
+  def vpi_register_cb aData, &aHandler # :yields: VPI::S_cb_data
+    raise ArgumentError, "block must be given" unless block_given?
+    RubyVPI::Callback.attach(aData, &aHandler)
+  end
+
+
+  alias_method :__callback__vpi_remove_cb, :vpi_remove_cb
+  module_function :__callback__vpi_remove_cb
+
+  def vpi_remove_cb aData # :nodoc:
+    RubyVPI::Callback.detach(aData)
+  end
+end

data/lib/ruby-vpi/core/edge.rb

@@ -0,0 +1,128 @@
+# Value change / edge detection for handles.
+#--
+# Copyright 2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+require 'singleton'
+
+module RubyVPI
+  class EdgeClass #:nodoc:
+    include Singleton
+
+    def initialize
+      @handles = []
+      @lock = Mutex.new
+    end
+
+    # Begins monitoring the given handle for value change.
+    def monitor aHandle
+      # ignore handles that cannot hold a meaningful value
+      type = VPI::vpi_get_str(VpiType, aHandle)
+      return if type =~ /Bit|Array|Module|Parameter/
+
+      @lock.synchronize do
+        unless @handles.include? aHandle
+          @handles << aHandle
+          refresh_handle aHandle
+        end
+      end
+    end
+
+    # Refreshes the cached value of all monitored handles.
+    def refresh_cache
+      @lock.synchronize do
+        @handles.each do |h|
+          refresh_handle h
+        end
+      end
+    end
+
+    # Remember the current value as the "previous" value.
+    def refresh_handle aHandle
+      aHandle.instance_eval do
+        @__edge__prev_val = get_value(VpiHexStrVal)
+      end
+    end
+  end
+
+  Edge = EdgeClass.instance
+end
+
+module VPI
+  class Handle
+    # create methods for detecting all possible value changes
+    vals  = %w[0 1 x z]
+    edges = vals.map {|a| vals.map {|b| a + b}}.flatten
+
+    edges.each do |edge|
+      meth = "change_#{edge}?"
+      old, new = edge.split(//)
+
+      old_int  = old =~ /[01]/
+      new_int  = new =~ /[01]/
+
+      old_read = old_int ? 'int' : 'hex'
+      new_read = new_int ? 'VpiIntVal' : 'VpiHexStrVal'
+
+      old_test = old_int ? "== #{old}" : "=~ /#{old}/i"
+      new_test = new_int ? "== #{new}" : "=~ /#{new}/i"
+
+      class_eval %{
+        def #{meth}
+          old = __edge__prev_val_#{old_read}
+          new = get_value(#{new_read})
+
+          old #{old_test} and new #{new_test}
+        end
+      }
+    end
+
+    alias posedge? change_01?
+    alias negedge? change_10?
+
+    # Tests if either a positive or negative edge has occurred.
+    def edge?
+      posedge? or negedge?
+    end
+
+    # Tests if the logic value of this handle has
+    # changed since the last simulation time step.
+    def change?
+      old = __edge__prev_val_hex
+      new = get_value(VpiHexStrVal)
+
+      old != new
+    end
+
+
+    private
+
+    # Returns the previous value as a hex string.
+    def __edge__prev_val_hex #:nodoc:
+      @__edge__prev_val.to_s
+    end
+
+    # Returns the previous value as an integer.
+    def __edge__prev_val_int #:nodoc:
+      __edge__prev_val_hex.to_i(16)
+    end
+  end
+
+  %w[
+    vpi_handle_by_name
+    vpi_handle_by_index
+    vpi_handle
+    vpi_scan
+  ].each do |src|
+    dst = "__value_change__#{src}"
+    alias_method dst, src
+
+    define_method src do |*args|
+      if result = __send__(dst, *args)
+        RubyVPI::Edge.monitor(result)
+      end
+
+      result
+    end
+  end
+end

data/lib/ruby-vpi/core/handle.rb

@@ -0,0 +1,421 @@
+# Interface to VPI handles.
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+module VPI
+  Handle = SWIG::TYPE_p_unsigned_int
+
+  # A handle is 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
+
+    # Tests if the logic value of this handle is unknown (x).
+    def x?
+      get_value(VpiHexStrVal) =~ /x/i
+    end
+
+    # Sets the logic value of this handle to unknown (x).
+    def x!
+      put_value('x', VpiHexStrVal)
+    end
+
+    alias unknown? x?
+    alias unknown! x!
+
+    alias dont_care? x?
+    alias dont_care! x!
+
+    # Tests if the logic value of this handle is high impedance (z).
+    def z?
+      get_value(VpiHexStrVal) =~ /z/i
+    end
+
+    # Sets the logic value of this handle to high impedance (z).
+    def z!
+      put_value('z', VpiHexStrVal)
+    end
+
+    alias hi_z? z?
+    alias hi_z! z!
+
+    alias high_z? z?
+    alias high_z! z!
+
+    alias high_impedance? z?
+    alias high_impedance! z!
+
+    alias tri_state? z?
+    alias tri_state! z!
+
+    alias floating? z?
+    alias floating! z!
+
+    # Tests if the logic value of this handle is at "logic high" level.
+    def high?
+      get_value(VpiIntVal) != 0
+    end
+
+    # Sets the logic value of this handle to "logic high" level.
+    def high!
+      put_value(1, VpiIntVal)
+    end
+
+    alias one? high?
+    alias one! high!
+
+    # Tests if the logic value of this handle is at "logic low" level.
+    def low?
+      get_value(VpiHexStrVal) =~ /^0+$/
+    end
+
+    # Sets the logic value of this handle to "logic low" level.
+    def low!
+      put_value(0, VpiIntVal)
+    end
+
+    alias zero? low?
+    alias zero! low!
+
+
+    # Inspects the given VPI property names, in
+    # addition to those common to all handles.
+    def inspect *aPropNames
+      aPropNames.unshift :name, :fullName, :size, :file, :lineNo, :hexStrVal
+
+      aPropNames.map! do |name|
+        "#{name}=#{__send__(name).inspect}"
+      end
+
+      "#<VPI::Handle #{vpi_get_str(VpiType, self)} #{aPropNames.join(', ')}>"
+    end
+
+    alias to_s inspect
+
+
+    #---------------------------------------------------------------------------
+    # reading & writing values
+    #---------------------------------------------------------------------------
+
+    # Reads the value using the given format (name or
+    # integer constant) and returns a +S_vpi_value+ object.
+    def get_value_wrapper aFormat
+      fmt = resolve_prop_type(aFormat)
+      val = S_vpi_value.new(:format => fmt)
+      vpi_get_value(self, val)
+      val
+    end
+
+    # Reads the value using the given format (name or integer constant) and
+    # returns it.  If a format is not given, then it is assumed to be VpiIntVal.
+    def get_value aFormat = VpiIntVal
+      fmt = resolve_prop_type(aFormat)
+      @size ||= vpi_get(VpiSize, self)
+
+      if fmt == VpiIntVal and @size > INTEGER_BITS
+        fmt = VpiHexStrVal
+        val = get_value_wrapper(fmt)
+        val.read(fmt).to_i(16)
+      else
+        val = get_value_wrapper(fmt)
+        val.read(fmt)
+      end
+    end
+
+    # Writes the given value using the given format (name or integer
+    # constant), time, and delay, and then returns the written 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
+      if vpi_get(VpiType, self) == VpiNet
+        aDelay = VpiForceFlag
+
+        if driver = self[VpiDriver].find {|d| vpi_get(VpiType, d) != VpiForce}
+          warn "forcing value #{aValue.inspect} onto wire #{self} that is already driven by #{driver.inspect}"
+        end
+      end
+
+      aFormat =
+        if aFormat
+          resolve_prop_type(aFormat)
+        else
+          S_vpi_value.detect_format(aValue) ||
+          get_value_wrapper(VpiObjTypeVal).format # let the simulator detect
+        end
+
+      if aFormat == VpiIntVal
+        @size ||= vpi_get(VpiSize, self)
+
+        unless @size < INTEGER_BITS
+          aFormat = VpiHexStrVal
+          aValue  = aValue.to_i.to_s(16)
+        end
+      end
+
+      aTime ||= S_vpi_time.new(:type => VpiSimTime, :integer => 0)
+
+      wrapper = S_vpi_value.new(:format => aFormat)
+      result  = wrapper.write(aValue, aFormat)
+
+      vpi_put_value(self, wrapper, aTime, aDelay)
+
+      result
+    end
+
+    # Forces the given value (see arguments for #put_value) onto this handle.
+    def force_value *args
+      args[3] = VpiForceFlag
+      put_value(*args)
+    end
+
+    # Releases a previously forced value on this handle.
+    def release_value
+      # this doesn't really change the value, it only removes the force flag
+      put_value(0, VpiIntVal, nil, VpiReleaseFlag)
+    end
+
+    # Tests if there is currently a value forced onto this handle.
+    def force?
+      self[VpiDriver].any? {|d| vpi_get(VpiType, d) == VpiForce}
+    end
+
+
+    #---------------------------------------------------------------------------
+    # accessing related handles / traversing the hierarchy
+    #---------------------------------------------------------------------------
+
+    # Returns an array of child handles of the
+    # given types (name or integer constant).
+    def [] *aTypes
+      handles = []
+
+      aTypes.each do |arg|
+        t = resolve_prop_type(arg)
+
+        if itr = vpi_iterate(t, self)
+          while h = vpi_scan(itr)
+            handles << h
+          end
+        end
+      end
+
+      handles
+    end
+
+    # inherit Enumerable methods, such as #each, #map, #select, etc.
+    Enumerable.instance_methods.push('each').each do |meth|
+      # using a string because define_method
+      # does not accept a block until Ruby 1.9
+      class_eval %{
+        def #{meth}(*args, &block)
+          if ary = self[*args]
+            ary.#{meth}(&block)
+          end
+        end
+      }, __FILE__, __LINE__
+    end
+
+    # bypass Enumerable's #to_a method, which relies on #each
+    alias to_a []
+
+    # Sort by absolute VPI path.
+    def <=> other
+      get_value(VpiFullName) <=> other.get_value(VpiFullName)
+    end
+
+
+    #---------------------------------------------------------------------------
+    # accessing VPI properties
+    #---------------------------------------------------------------------------
+
+    @@propCache = Hash.new {|h, k| h[k] = Property.new(k)}
+
+    undef type # used to access VpiType
+
+    # Provides access to this handle's (1) child handles
+    # and (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
+      # cache the result for future accesses, in order
+      # to cut down number of calls to method_missing()
+      eigen_class = (class << self; self; end)
+
+      if child = vpi_handle_by_name(aMeth.to_s, self)
+        eigen_class.class_eval do
+          define_method aMeth do
+            child
+          end
+        end
+
+        child
+      else
+        # XXX: using a string because define_method() does
+        #      not support a block argument until Ruby 1.9
+        eigen_class.class_eval %{
+          def #{aMeth}(*a, &b)
+            @@propCache[#{aMeth.inspect}].execute(self, *a, &b)
+          end
+        }, __FILE__, __LINE__
+
+        __send__(aMeth, *aArgs, &aBlockArg)
+      end
+    end
+
+    private
+
+    class Property # :nodoc:
+      attr_reader :name, :type, :accessor, :operation
+
+      def initialize aMethName
+        @methName = aMethName.to_s
+
+        # parse property information from the given method name
+          tokens = @methName.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.to_ruby_const_name
+          @name.insert 0, 'Vpi' unless @name =~ /^[Vv]pi/
+
+          begin
+            @type = VPI.const_get(@name)
+          rescue NameError
+            raise ArgumentError, "#{@name.inspect} is not a valid VPI property"
+          end
+
+        @accessor = if @accessor
+          @accessor.to_sym
+        else
+          # infer accessor from VPI property @name
+          if isQuery
+            :b
+          else
+            case @name
+            when /Time$/
+              :d
+
+            when /Val$/
+              :l
+
+            when /Type$/, /Direction$/, /Index$/, /Size$/, /Strength\d?$/, /Polarity$/, /Edge$/, /Offset$/, /Mode$/, /LineNo$/
+              :i
+
+            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
+
+      def execute aHandle, *aArgs, &aBlockArg
+        if @operation
+          aHandle.__send__(@operation, @type, *aArgs, &aBlockArg)
+        else
+          case @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 @isAssign
+              value = aArgs.shift
+              aHandle.put_value(value, @type, *aArgs)
+            else
+              aHandle.get_value(@type)
+            end
+
+          when :i # integer values
+            if @isAssign
+              raise NotImplementedError
+            else
+              vpi_get(@type, aHandle)
+            end
+
+          when :b # boolean values
+            if @isAssign
+              raise NotImplementedError
+            else
+              value = vpi_get(@type, aHandle)
+              value && (value != 0) # zero is false in C
+            end
+
+          when :s # string values
+            if @isAssign
+              raise NotImplementedError
+            else
+              vpi_get_str(@type, aHandle)
+            end
+
+          when :h # handle values
+            if @isAssign
+              raise NotImplementedError
+            else
+              vpi_handle(@type, aHandle)
+            end
+
+          when :a # array of child handles
+            if @isAssign
+              raise NotImplementedError
+            else
+              aHandle[@type]
+            end
+
+          else
+            raise NoMethodError, "cannot access VPI property #{@name.inspect} for handle #{aHandle.inspect} through method #{@methName.inspect} with arguments #{aArgs.inspect}"
+          end
+        end
+      end
+    end
+
+    # resolve type names into type constants
+    def resolve_prop_type aNameOrType
+      if aNameOrType.respond_to? :to_int and not aNameOrType.is_a? Symbol
+        aNameOrType.to_int
+      else
+        @@propCache[aNameOrType.to_sym].type
+      end
+    end
+  end
+end