ruby-vpi 15.0.2 → 16.0.0

data/lib/ruby-vpi/vpi.rb

@@ -1,24 +1,8 @@
-# A utility layer which transforms the VPI interface into one that is more suitable for Ruby.
-
-=begin
-  Copyright 2006 Suraj N. Kurapati
-
-  This file is part of Ruby-VPI.
-
-  Ruby-VPI is free software; you can redistribute it and/or
-  modify it under the terms of the GNU General Public License
-  as published by the Free Software Foundation; either version 2
-  of the License, or (at your option) any later version.
-
-  Ruby-VPI is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with Ruby-VPI; if not, write to the Free Software Foundation,
-  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
-=end
+# A utility layer which transforms the VPI interface into one that is more
+# suitable for Ruby.
+#--
+# Copyright 2006-2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
 
 module Vpi
   # Number of bits in PLI_INT32.
@@ -31,487 +15,547 @@ module Vpi
   INTEGER_MASK = INTEGER_LIMIT - 1
 
 
-  ## handles
-
-  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
+  # handles
+
+    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 unknown (x).
-    def x?
-      self.hexStrVal =~ /x/i
-    end
+      # Tests if the logic value of this handle is unknown (x).
+      def x?
+        self.hexStrVal =~ /x/i
+      end
 
-    # Sets the logic value of this handle to unknown (x).
-    def x!
-      self.hexStrVal = 'x'
-    end
+      # Sets the logic value of this handle to unknown (x).
+      def x!
+        self.hexStrVal = 'x'
+      end
 
-    # Tests if the logic value of this handle is high impedance (z).
-    def z?
-      self.hexStrVal =~ /z/i
-    end
+      # Tests if the logic value of this handle is high impedance (z).
+      def z?
+        self.hexStrVal =~ /z/i
+      end
 
-    # Sets the logic value of this handle to high impedance (z).
-    def z!
-      self.hexStrVal = 'z'
-    end
+      # Sets the logic value of this handle to high impedance (z).
+      def z!
+        self.hexStrVal = 'z'
+      end
 
-    # Tests if the logic value of this handle is currently at a positive edge.
-    def posedge?
-      old = @lastVal
-      new = @lastVal = self.intVal
+      # Tests if the logic value of this handle is currently at a positive edge.
+      def posedge?
+        old = @lastVal
+        new = @lastVal = self.intVal
 
-      old == 0 && new == 1
-    end
+        old == 0 && new == 1
+      end
 
-    # Tests if the logic value of this handle is currently at a negative edge.
-    def negedge?
-      old = @lastVal
-      new = @lastVal = self.intVal
+      # Tests if the logic value of this handle is currently at a negative edge.
+      def negedge?
+        old = @lastVal
+        new = @lastVal = self.intVal
 
-      old == 1 && new == 0
-    end
+        old == 1 && new == 0
+      end
 
-    # 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
+      # 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
 
-      vpi_get_value self, val
-      val
-    end
+        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 the Verilog simulator will attempt to determine the correct format.
-    def get_value aFormat = VpiObjTypeVal
-      val = get_value_wrapper(resolve_prop_type(aFormat))
+      # 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(resolve_prop_type(aFormat))
 
-      case val.format
-        when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
-          val.value.str
+        case val.format
+          when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
+            val.value.str
 
-        when VpiScalarVal
-          val.value.scalar
+          when VpiScalarVal
+            val.value.scalar
 
-        when VpiIntVal
-          get_value_wrapper(VpiHexStrVal).value.str.to_i(16)
+          when VpiIntVal
+            get_value_wrapper(VpiHexStrVal).value.str.to_i(16)
 
-        when VpiRealVal
-          val.value.real
+          when VpiRealVal
+            val.value.real
 
-        when VpiTimeVal
-          val.value.time
+          when VpiTimeVal
+            val.value.time
 
-        when VpiVectorVal
-          val.value.vector
+          when VpiVectorVal
+            val.value.vector
 
-        when VpiStrengthVal
-          val.value.strength
+          when VpiStrengthVal
+            val.value.strength
 
-        else
-          raise "unknown S_vpi_value.format: #{val.format}"
+          else
+            raise "unknown S_vpi_value.format: #{val.format}"
+        end
       end
-    end
 
-    # 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 =
-        if aFormat
-          resolve_prop_type(aFormat)
-        else
-          get_value_wrapper(VpiObjTypeVal).format
-        end
+      # 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 =
+          if aFormat
+            resolve_prop_type(aFormat)
+          else
+            get_value_wrapper(VpiObjTypeVal).format
+          end
 
-      newVal = S_vpi_value.new
-      newVal.format = aFormat
+        newVal = S_vpi_value.new
+        newVal.format = aFormat
 
-      case aFormat
-        when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
-          newVal.value.str = aValue.to_s
+        case aFormat
+          when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
+            newVal.value.str = aValue.to_s
 
-        when VpiScalarVal
-          newVal.value.scalar = aValue
+          when VpiScalarVal
+            newVal.value.scalar = aValue
 
-        when VpiIntVal
-          newVal.format = VpiHexStrVal
-          newVal.value.str = aValue.to_i.to_s(16)
+          when VpiIntVal
+            newVal.format = VpiHexStrVal
+            newVal.value.str = aValue.to_i.to_s(16)
 
-        when VpiRealVal
-          newVal.value.real = aValue.to_f
+          when VpiRealVal
+            newVal.value.real = aValue.to_f
 
-        when VpiTimeVal
-          newVal.value.time = aValue
+          when VpiTimeVal
+            newVal.value.time = aValue
 
-        when VpiVectorVal
-          newVal.value.vector = aValue
+          when VpiVectorVal
+            newVal.value.vector = aValue
 
-        when VpiStrengthVal
-          newVal.value.strength = aValue
+          when VpiStrengthVal
+            newVal.value.strength = aValue
 
-        else
-          raise "unknown S_vpi_value.format: #{newVal.format}"
-      end
+          else
+            raise "unknown S_vpi_value.format: #{newVal.format}"
+        end
 
-      vpi_put_value self, newVal, aTime, aDelay
+        vpi_put_value self, newVal, aTime, aDelay
 
-      # ensure that value was written correctly
-        readenVal = get_value(aFormat)
+        # ensure that value was written correctly
+          readenVal = get_value(aFormat)
 
-        writtenCorrectly =
-          case aFormat
-            when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal
-              if aValue =~ /[xz]/i  # TODO: verify 'z' behavior
-                readenVal =~ /[xz]/i
-              else
+          writtenCorrectly =
+            case aFormat
+              when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal
+                if aValue =~ /[xz]/i  # TODO: verify 'z' behavior
+                  readenVal =~ /[xz]/i
+                else
+                  readenVal == aValue.to_s
+                end
+
+              when VpiStringVal
                 readenVal == aValue.to_s
-              end
 
-            when VpiStringVal
-              readenVal == aValue.to_s
+              when VpiIntVal
+                # allow for register overflow when limit reached
+                readenVal == (aValue.to_i % (2 ** self.vpiSize))
 
-            when VpiIntVal
-              # allow for register overflow when limit reached
-              readenVal == (aValue.to_i % (2 ** self.vpiSize))
+              when VpiRealVal
+                readenVal == aValue.to_f
 
-            when VpiRealVal
-              readenVal == aValue.to_f
+              else
+                true
+            end
 
-            else
-              true
+          unless writtenCorrectly
+            raise "value written (#{aValue.inspect}) does not match value read (#{readenVal.inspect}) from handle #{self}"
           end
 
-        unless writtenCorrectly
-          raise "value written (#{aValue.inspect}) does not match value read (#{readenVal.inspect}) from handle #{self}"
-        end
-
-      aValue
-    end
+        aValue
+      end
 
-    # Returns an array of child handles of the given types (name or integer constant).
-    def [] *aTypes
-      handles = []
+      # Returns an array of child handles of the given types (name or integer
+      # constant).
+      def [] *aTypes
+        handles = []
 
-      aTypes.each do |t|
-        t = resolve_prop_type(t)
+        aTypes.each do |t|
+          t = resolve_prop_type(t)
 
-        if itr = vpi_iterate(t, self)
-          while h = vpi_scan(itr)
-            handles << h
+          if itr = vpi_iterate(t, self)
+            while h = vpi_scan(itr)
+              handles << h
+            end
           end
         end
-      end
-
-      handles
-    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)}"
+        handles
       end
 
-      "#<Vpi::Handle #{vpiType_s} #{aPropNames.join(', ')}>"
-    end
+      # Inspects the given VPI property names, in addition to those common to
+      # all handles.
+      def inspect *aPropNames
+        aPropNames.unshift :fullName, :size, :file, :lineNo
 
-    alias to_s inspect
+        aPropNames.map! do |name|
+          "#{name}=#{self.send(name.to_sym)}"
+        end
 
+        "#<Vpi::Handle #{vpiType_s} #{aPropNames.join(', ')}>"
+      end
 
-    ## properties
+      alias to_s inspect
 
-    @@propCache = Hash.new {|h, k| h[k] = Property.resolve(k)}
+      # Registers a callback that is invoked whenever the value of this object
+      # changes.
+      def cbValueChange aOptions = {}, &aHandler
+        raise ArgumentError unless block_given?
 
-    # 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
+        aOptions[:time]  ||= S_vpi_time.new(:type => VpiSuppressTime)
+        aOptions[:value] ||= S_vpi_value.new(:format => VpiSuppressVal)
 
-        child
+        alarm = S_cb_data.new(
+          :reason => CbValueChange,
+          :obj    => self,
+          :time   => aOptions[:time],
+          :value  => aOptions[:value],
+          :index  => 0
+        )
 
-      else
-        prop = @@propCache[aMeth]
+        vpi_register_cb alarm, &aHandler
+      end
 
-        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)
+      @@propCache = Hash.new {|h, k| h[k] = Property.resolve(k)}
+
+      # 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
+        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
 
-            when :i	# integer values
-              vpi_get(prop.type, self) unless prop.assignment
+          child
 
-            when :b # boolean values
-              unless prop.assignment
-                value = vpi_get(prop, self)
-                value && (value != 0)	# zero is false in C
-              end
+        else
+          prop = @@propCache[aMeth]
 
-            when :s	# string values
-              vpi_get_str(prop.type, self) unless prop.assignment
+          if prop.operation
+            self.send(prop.operation, prop.type, *aArgs, &aBlockArg)
 
-            when :h	# handle values
-              vpi_handle(prop.type, self) unless prop.assignment
+          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
+
+              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}"
+              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
-    end
 
-    Property = Struct.new :type, :name, :operation, :accessor, :assignment
+      Property = Struct.new :type, :name, :operation, :accessor, :assignment
 
-    # Resolves the given shorthand name into a description of its VPI property.
-    def Property.resolve aName # :nodoc:
-      # parse the given property name
-        tokens = aName.to_s.split(/_/)
+      # Resolves the given shorthand name into a description of its VPI
+      # property.
+      def Property.resolve aName # :nodoc:
+        # parse the given property name
+          tokens = aName.to_s.split(/_/)
 
 
-        tokens.last.sub!(/[\?!=]$/, '')
+          tokens.last.sub!(/[\?!=]$/, '')
 
-        addendum = $&
-        isAssign = $& == '='
-        isQuery = $& == '?'
+          addendum = $&
+          isAssign = $& == '='
+          isQuery = $& == '?'
 
 
-        tokens.last =~ /^[a-z]$/ && tokens.pop
-        accessor = $&
+          tokens.last =~ /^[a-z]$/ && tokens.pop
+          accessor = $&
 
-        name = tokens.pop
+          name = tokens.pop
 
-        operation =
-          unless tokens.empty?
-            tokens.join('_') << (addendum || '')
-          end
+          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/
+        # 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
-          type = Vpi.const_get(name)
-        rescue NameError
-          raise ArgumentError, "#{name.inspect} is not a valid VPI property"
-        end
+          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
+        accessor =
+          if accessor
+            accessor.to_sym
 
-        else # infer accessor from VPI property name
-          if isQuery
-            :b
+          else # infer accessor from VPI property name
+            if isQuery
+              :b
 
-          else
-            case name
-              when /Time$/
-                :d
+            else
+              case name
+                when /Time$/
+                  :d
 
-              when /Val$/
-                :l
+                when /Val$/
+                  :l
 
-              when /Type$/, /Direction$/, /Index$/, /Size$/, /Strength\d?$/, /Polarity$/, /Edge$/, /Offset$/, /Mode$/, /LineNo$/
-                :i
+                when /Type$/, /Direction$/, /Index$/, /Size$/, /Strength\d?$/, /Polarity$/, /Edge$/, /Offset$/, /Mode$/, /LineNo$/
+                  :i
 
-              when /Is[A-Z]/, /ed$/
-                :b
+                when /Is[A-Z]/, /ed$/
+                  :b
 
-              when /Name$/, /File$/, /Decompile$/
-                :s
+                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
+                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
 
-      Property.new type, name, operation, accessor, isAssign
-    end
+        Property.new type, name, operation, accessor, isAssign
+      end
 
-    private
+      private
 
-    # resolve type names into type constants
-    def resolve_prop_type aNameOrType
-      if aNameOrType.is_a? Integer
-        aNameOrType
-      else
-        @@propCache[aNameOrType.to_sym].type
+      # 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
 
 
-  ## callbacks
+  # callbacks
 
-  Callback = Struct.new :handler, :token #:nodoc:
-  @@callbacks = {}
+    Callback = Struct.new :handler, :token #:nodoc:
+    @@callbacks = {}
 
-  alias vpi_register_cb_old vpi_register_cb
+    alias vpi_register_cb_old 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?
+    # 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?
 
-    key = aHandler.object_id.to_s
+      key = aHandler.object_id.to_s
 
-    # register the callback with Verilog
-      aData.user_data = key
-      aData.cb_rtn = Vlog_relay_ruby
-      token = vpi_register_cb_old(aData)
+      # register the callback with Verilog
+        aData.user_data = key
+        aData.cb_rtn = Vlog_relay_ruby
+        token = vpi_register_cb_old(aData)
 
-    @@callbacks[key] = Callback.new(aHandler, token)
-    token
-  end
+      @@callbacks[key] = Callback.new(aHandler, token)
+      token
+    end
 
-  alias vpi_remove_cb_old vpi_remove_cb
+    alias vpi_remove_cb_old vpi_remove_cb
 
-  def vpi_remove_cb aData # :nodoc:
-    key = aData.user_data
+    def vpi_remove_cb aData # :nodoc:
+      key = aData.user_data
 
-    if c = @@callbacks[key]
-      vpi_remove_cb_old c.token
-      @@callbacks.delete key
+      if c = @@callbacks[key]
+        vpi_remove_cb_old c.token
+        @@callbacks.delete key
+      end
     end
-  end
 
-  # Proxy for relay_verilog which supports callbacks.
-  # This method should NOT be invoked from callback handlers (see vpi_register_cb) and threads -- otherwise the situation will be like seven remote controls changing the channel on a single television set!
-  def relay_verilog_proxy # :nodoc:
-    loop do
-      relay_verilog
+    # Proxy for relay_verilog which supports callbacks.
+    # This method should NOT be invoked from callback handlers (see
+    # vpi_register_cb) and threads -- otherwise the situation will be like seven
+    # remote controls changing the channel on a single television set!
+    def relay_verilog_proxy # :nodoc:
+      loop do
+        relay_verilog
 
-      if reason = relay_ruby_reason # might be nil
-        dst = reason.user_data
+        if reason = relay_ruby_reason # might be nil
+          dst = reason.user_data
 
-        if c = @@callbacks[dst]
-          c.handler.call reason
-        else
-          break # main thread is receiver
+          if c = @@callbacks[dst]
+            c.handler.call reason
+          else
+            break # main thread is receiver
+          end
         end
       end
     end
-  end
-
 
-  ## simulation control
 
-  # Simulates the design under test according to RubyVpi.init_bench.
-  def simulate
-    # this is a dummy method!
-  end
+  # simulation control
 
-  # Advances the simulation by the given number of steps.
-  def advance_time aNumSteps = 1
-    # schedule wake-up callback from verilog
-      time = S_vpi_time.new
-      time.integer = aNumSteps
-      time.type = VpiSimTime
-
-      value = S_vpi_value.new
-      value.format = VpiSuppressVal
-
-      alarm = S_cb_data.new
-      alarm.reason = CbAfterDelay
-      alarm.cb_rtn = Vlog_relay_ruby
-      alarm.obj = nil
-      alarm.time = time
-      alarm.value = value
-      alarm.index = 0
-      alarm.user_data = nil
+    # Simulates the design under test according to RubyVpi.init_bench.
+    def simulate
+      # this is a dummy method! it is overwritten by RubyVpi.init_bench
+    end
 
-      vpi_free_object(vpi_register_cb_old(alarm))
+    # Advances the simulation by the given number of steps.
+    def advance_time aNumSteps = 1
+      # schedule wake-up callback from verilog
+        time = S_vpi_time.new
+        time.integer = aNumSteps
+        time.type = VpiSimTime
+
+        value = S_vpi_value.new
+        value.format = VpiSuppressVal
+
+        alarm = S_cb_data.new
+        alarm.reason = CbAfterDelay
+        alarm.cb_rtn = Vlog_relay_ruby
+        alarm.obj = nil
+        alarm.time = time
+        alarm.value = value
+        alarm.index = 0
+        alarm.user_data = nil
+
+        vpi_free_object(vpi_register_cb_old(alarm))
+
+      # relay to verilog
+        relay_verilog_proxy
+    end
 
-    # relay to verilog
-      relay_verilog_proxy
-  end
 
+  # utility
 
-  ## utility
+    # Returns the current simulation time as an integer.
+    def simulation_time
+      t = S_vpi_time.new
+      t.type = VpiSimTime
 
-  # Returns the current simulation time as an integer.
-  def simulation_time
-    t = S_vpi_time.new
-    t.type = VpiSimTime
+      vpi_get_time nil, t
+      t.to_i
+    end
 
-    vpi_get_time nil, t
-    t.to_i
-  end
+    class S_vpi_time
+      # Returns the high and low portions of this time as a single 64-bit
+      # integer.
+      def integer
+        (self.high << INTEGER_BITS) | self.low
+      end
 
+      # Sets the high and low portions of this time from the given 64-bit
+      # integer.
+      def integer= aValue
+        self.low = aValue & INTEGER_MASK
+        self.high = (aValue >> INTEGER_BITS) & INTEGER_MASK
+      end
 
-  class S_vpi_time
-    # Returns the high and low portions of this time as a single 64-bit integer.
-    def integer
-      (self.high << INTEGER_BITS) | self.low
+      alias to_i integer
+      alias to_f real
     end
 
-    # Sets the high and low portions of this time from the given 64-bit integer.
-    def integer= aValue
-      self.low = aValue & INTEGER_MASK
-      self.high = (aValue >> INTEGER_BITS) & INTEGER_MASK
-    end
+    class S_vpi_value
+      def to_i
+        value.integer
+      end
 
-    alias to_i integer
-    alias to_f real
-  end
+      def to_f
+        value.real
+      end
 
-  class S_vpi_value
-    def to_i
-      value.integer
+      def to_s
+        value.str
+      end
     end
 
-    def to_f
-      value.real
-    end
+    # make VPI structs more accessible by allowing their members to be
+    # initialized through the constructor
+      constants.grep(/^S_/).each do |s|
+        const_get(s).class_eval do
+          alias old_initialize initialize
 
-    def to_s
-      value.str
-    end
-  end
+          def initialize aMembers = {}
+            old_initialize
+
+            aMembers.each_pair do |k, v|
+              __send__ "#{k}=", v
+            end
+          end
+        end
+      end
 end