ruby-vpi 20.0.0 → 21.0.0

data/ext/user.h

@@ -0,0 +1,23 @@
+/*
+  Copyright 2008 Suraj N. Kurapati
+  See the file named LICENSE for details.
+*/
+
+#ifndef USER_H
+#define USER_H
+
+    #include "verilog.h"
+
+    /// should be called in vlog_startup_routines
+    void RubyVPI_user_init();
+
+    /// should be called at end of simulation
+    void RubyVPI_user_fini();
+
+    ///
+    /// VPI callback handler that resumes the user
+    /// code and waits until it becomes paused again.
+    ///
+    PLI_INT32 RubyVPI_user_resume(p_cb_data aCallback);
+
+#endif

data/ext/util.h

@@ -0,0 +1,55 @@
+/*
+  Copyright 2006 Suraj N. Kurapati
+  See the file named LICENSE for details.
+*/
+///\file Utility functions.
+
+#ifndef UTIL_H
+#define UTIL_H
+
+    #include "verilog.h"
+
+    /// An alias for vpi_printf().
+    ///
+    /// @param	...	Arguments to vpi_printf()
+    ///
+    #define RubyVPI_util_write vpi_printf
+
+    /// Marks the given message as being emitted from Ruby-VPI and prints it.
+    ///
+    /// @param	...	Arguments to vpi_printf()
+    ///
+    #define RubyVPI_util_print(...) \
+        RubyVPI_util_write("[%s:%d] Ruby-VPI: ", __FILE__, __LINE__); \
+        RubyVPI_util_write(__VA_ARGS__);
+
+    /// Marks the given message as being emitted from Ruby-VPI
+    /// and prints it while ending the message with a new line.
+    ///
+    /// @param	...	Arguments to RubyVPI_util_write()
+    ///
+    #define RubyVPI_util_puts(...) \
+        RubyVPI_util_print(__VA_ARGS__); \
+        RubyVPI_util_write("\n");
+
+    /// Marks the given message as being being an
+    /// error message from Ruby-VPI and prints it
+    /// while ending the message with a new line
+    /// and then stopping the simulation.
+    ///
+    /// @param	...	Arguments to RubyVPI_util_write()
+    ///
+    #define RubyVPI_util_error(...) \
+        RubyVPI_util_puts("error: " __VA_ARGS__); \
+        vpi_control(vpiStop);
+
+    /// A wrapper for RubyVPI_util_puts() which marks
+    /// the given message as being debugging output.
+    ///
+    #ifdef DEBUG
+        #define RubyVPI_util_debug RubyVPI_util_puts
+    #else
+        #define RubyVPI_util_debug(...)
+    #endif
+
+#endif

data/ext/verilog.h

@@ -2,61 +2,14 @@
   Copyright 2006 Suraj N. Kurapati
   See the file named LICENSE for details.
 */
-/**\file
-  A proxy for all Verilog headers of interest to us.
-*/
+///\file A proxy for all Verilog headers of interest to us.
 
 #ifndef VERILOG_H
 #define VERILOG_H
 
-  /*
-    Use our verbatim copy of the official IEEE Std. 1364-2005 header file, which
-    was obtained from this URL:
-    <http://www.boydtechinc.com/ptf/archive/ptf_2005/0737.html>
-  */
-  #include "vpi_user.h"
-
-  /*
-    Adjust for the peculiarities of the Verilog simulator being used.
-  */
-  #ifdef SYNOPSYS_VCS
-    #define VERILOG_LENIENT
-  #endif
-
-  /*
-    Do we want to enforce strict compliance with IEEE Std. 1364-2001? If so,
-    Ruby-VPI might not work with Synopsys VCS, but that's not our fault. ;-)
-  */
-  #define verilog_tf_funcPtr_strict(aPtrName) \
-    PLI_INT32 (*aPtrName)(PLI_BYTE8*)
-
-  #ifdef VERILOG_LENIENT
-    #define verilog_tf_funcPtr(aPtrName) \
-      void (*aPtrName)(void)
-
-    #define verilog_tf_funcSig(aFuncName) \
-      void aFuncName(void)
-
-    #define verilog_tf_funcReturn(aReturnVal) \
-      ;
-  #else
-    #define verilog_tf_funcPtr verilog_tf_funcPtr_strict
-
-    #define verilog_tf_funcSig(aFuncName) \
-      PLI_INT32 aFuncName(PLI_BYTE8* aCallbackData)
-
-    #define verilog_tf_funcReturn(aReturnVal) \
-      return aReturnVal
-  #endif
-
-
-  #define verilog_cb_funcPtr(aPtrName) \
-    PLI_INT32 (*aPtrName)(p_cb_data)
-
-  #define verilog_cb_funcSig(aFuncName) \
-    PLI_INT32 aFuncName(p_cb_data aCallbackData)
-
-  #define verilog_cb_funcReturn(aReturnVal) \
-    return aReturnVal
+    // Use our verbatim copy of the official IEEE Std 1364-2005
+    // header file, which was obtained from this URL:
+    // http://www.boydtechinc.com/ptf/archive/ptf_2005/0737.html
+    #include "vpi_user.h"
 
 #endif

data/lib/ruby-vpi.rb

@@ -6,8 +6,8 @@
 module RubyVPI
   Project = {
     :name    => 'ruby-vpi',
-    :version => '20.0.0',
-    :release => '2008-01-27',
+    :version => '21.0.0',
+    :release => '2008-06-08',
     :website => "http://ruby-vpi.rubyforge.org",
     :home    => File.expand_path(File.join(File.dirname(__FILE__), '..'))
   }
@@ -49,6 +49,7 @@ module RubyVPI
   #                       object in the Verilog simulation
   #
   def RubyVPI.load_test aDesignHandleOrPath, *aTestFilePaths
+    # access the design under test
     design =
       if aDesignHandleOrPath.is_a? VPI::Handle
         aDesignHandleOrPath
@@ -58,11 +59,18 @@ module RubyVPI
 
     raise ArgumentError, "cannot access the design under test: #{aDesignHandleOrPath.inspect}" unless design
 
+    # create a sandbox
     sandbox = Module.new
     sandbox.const_set :DUT, design
+    sandboxBinding = sandbox.module_eval('binding')
 
+    # load files into sandbox
     aTestFilePaths.flatten.compact.uniq.each do |path|
-      sandbox.module_eval(File.read(path), path)
+      if HAVE_RUBY_19X
+        eval File.read(path), sandboxBinding, path
+      else
+        sandbox.module_eval File.read(path), path
+      end
     end
 
     sandbox

data/lib/ruby-vpi/boot/loader.rb

@@ -0,0 +1,162 @@
+# Boot loader for the Ruby side of the Ruby-VPI cosimulation.
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+begin
+  # copy Ruby output into simulator's log file
+    [STDOUT, STDERR].each do |stream|
+      class << stream #:nodoc:
+        alias __write__ write
+
+        def write aString
+          s = aString.to_s
+
+          VPI.vpi_printf(s)
+          return s.length
+        end
+      end
+    end
+
+  # XXX: in the C extension, we use rb_require() to run this
+  #      boot loader.  when that finishes, any at_exit handlers
+  #      are NOT automatically invoked (since rb_require() does
+  #      not internally run ruby_finalize()).  so this is a
+  #      workaround to simulate at_exit invocation, which is
+  #      used by RSpec and Test::Unit to execute the unit test
+  module Kernel
+    alias __RubyVPI__orig_at_exit at_exit
+
+    @@__RubyVPI__exit_handlers = []
+
+    def at_exit &aBlock # :nodoc:
+      @@__RubyVPI__exit_handlers.unshift aBlock if aBlock
+    end
+
+    # runs all fake at_exit handlers
+    def __RubyVPI__simulate_exit # :nodoc:
+      if defined? @@__RubyVPI__exit_handlers
+        @@__RubyVPI__exit_handlers.each do |handler|
+          begin
+            handler.call
+          rescue SystemExit
+            # ignore
+          end
+        end
+      end
+    end
+
+    module_function :__RubyVPI__simulate_exit
+  end
+
+  module RubyVPI
+    USE_SIMULATOR = ENV['RUBYVPI_SIMULATOR'].to_sym
+    USE_DEBUGGER  = ENV['DEBUGGER'].to_i  == 1
+    USE_COVERAGE  = ENV['COVERAGE'].to_i  == 1
+    USE_PROTOTYPE = ENV['PROTOTYPE'].to_i == 1
+    USE_PROFILER  = ENV['PROFILER'].to_i  == 1
+    HAVE_RUBY_19X = RUBY_VERSION =~ /^1\.9\./
+    HAVE_RUBY_18X = RUBY_VERSION =~ /^1\.8\./
+  end
+
+  require 'rubygems'
+  require 'ruby-vpi'
+  require 'ruby-vpi/core'
+
+  # set up code coverage analysis
+    if RubyVPI::USE_COVERAGE
+      require 'ruby-vpi/rcov'
+
+      outFile = "coverage.txt"
+      RubyVPI::Coverage.attach do |analysis|
+        begin
+          File.open(outFile, 'w') do |f|
+            STDOUT.flush
+            $stdout = f
+
+            analysis.dump_coverage_info [
+              Rcov::TextReport.new,
+              Rcov::FullTextReport.new(:textmode => :counts),
+            ]
+          end
+        ensure
+          $stdout = STDOUT
+        end
+      end
+
+      RubyVPI::Coverage.start
+      RubyVPI.say "coverage analysis is enabled; results stored in #{outFile}"
+    end
+
+  # set up the interactive debugger
+    if RubyVPI::USE_DEBUGGER
+      require 'ruby-debug'
+
+      Debugger.start
+      Debugger.post_mortem
+
+      RubyVPI.say 'interactive debugger is enabled'
+    end
+
+    # suppress undefined method errors when debugger is not enabled
+      unless Kernel.respond_to? :debugger
+        Kernel.class_eval do
+          # Starts an interactive debugging session.
+          def debugger
+          end
+        end
+      end
+
+  # set up the profiler
+    if RubyVPI::USE_PROFILER
+      require 'ruby-prof'
+
+      outFile = "profile.txt"
+      at_exit do
+        result = RubyProf.stop
+        printer = RubyProf::GraphPrinter.new(result)
+
+        File.open(outFile, 'w') do |out|
+          printer.print(out)
+        end
+      end
+
+      RubyProf.start
+      RubyVPI.say "performance analysis is enabled; results stored in #{outFile}"
+    end
+
+  # set up the prototyping environment
+    if RubyVPI::USE_PROTOTYPE
+      VPI.module_eval do
+        def vpi_register_cb *args #:nodoc:
+          warn "vpi_register_cb: callbacks are ignored when prototype is enabled"
+        end
+      end
+
+      RubyVPI.say 'prototype is enabled'
+    end
+
+  # make VPI functions available globally
+    class Object
+      include VPI
+    end
+
+  # load the user-defined test loader
+    RubyVPI::Scheduler.start
+    require ENV['RUBYVPI_TEST_LOADER']
+
+  # simulate at_exit handler invocation
+    Kernel.__RubyVPI__simulate_exit
+
+    # restore original at_exit handler
+    module Kernel
+      alias at_exit __RubyVPI__orig_at_exit
+      undef __RubyVPI__simulate_exit
+    end
+
+  RubyVPI.detach
+
+rescue Exception => e
+  # mimic how Ruby internally prints exceptions
+  STDERR.puts "#{e.class}: #{e.message}", e.backtrace.map {|s| "\tfrom #{s}" }
+end

data/lib/ruby-vpi/boot/relay.rb

@@ -0,0 +1,47 @@
+# Defines methods for transferring control between Ruby and Verilog.
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+begin
+  module RubyVPI
+    require 'thread'
+
+    @@userRun = Queue.new
+    @@hostRun = Queue.new
+
+    # Allows the simulator to resume this Ruby code.
+    def resume aCallback
+      @@userRun.enq aCallback
+      attach
+    end
+
+    module_function :resume
+
+    # Pauses this Ruby code and waits for the simulator to resume it.
+    def pause
+      detach
+      @@userRun.deq
+    end
+
+    module_function :pause
+
+    # Unblocks the simulator, which is waiting for this Ruby code to pause.
+    def detach
+      @@hostRun.enq nil
+    end
+
+    module_function :detach
+
+    # Allows the simulator to wait for this Ruby code to pause.
+    def attach
+      @@hostRun.deq
+    end
+
+    module_function :attach
+  end
+
+rescue Exception => e
+  # mimic how Ruby internally prints exceptions
+  STDERR.puts "#{e.class}: #{e.message}", e.backtrace.map {|s| "\tfrom #{s}" }
+end

data/lib/ruby-vpi/core.rb

@@ -25,14 +25,6 @@ module VPI
   INTEGER_MASK  = INTEGER_LIMIT - 1
 end
 
-module RubyVPI
-  USE_SIMULATOR = ENV['RUBYVPI_SIMULATOR'].to_sym
-  USE_DEBUGGER  = ENV['DEBUGGER'].to_i  == 1
-  USE_COVERAGE  = ENV['COVERAGE'].to_i  == 1
-  USE_PROTOTYPE = ENV['PROTOTYPE'].to_i == 1
-  USE_PROFILER  = ENV['PROFILER'].to_i   == 1
-end
-
 require 'thread'
 require 'ruby-vpi/core/struct'
 require 'ruby-vpi/core/handle'

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

@@ -21,8 +21,8 @@ module RubyVPI
 
       # register the callback with Verilog
       aData.user_data = id
-      aData.cb_rtn    = VPI::Vlog_relay_ruby
-      receipt         = VPI::__callback__vpi_register_cb(aData)
+      aData.cb_rtn    = VPI::RubyVPI_user_resume
+      receipt         = VPI.__callback__vpi_register_cb(aData)
 
       @lock.synchronize do
         @id2handler[id] = aHandler
@@ -37,7 +37,7 @@ module RubyVPI
       receipt = @lock.synchronize{ @id2receipt[id] }
 
       if receipt
-        VPI::__callback__vpi_remove_cb(receipt)
+        VPI.__callback__vpi_remove_cb(receipt)
 
         @lock.synchronize do
           @id2handler.delete id
@@ -50,42 +50,35 @@ module RubyVPI
     # 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
+        time            = VPI::S_vpi_time.new
+        time.integer    = aNumSteps
+        time.type       = VPI::VpiSimTime
 
-      value           = VPI::S_vpi_value.new
-      value.format    = VPI::VpiSuppressVal
+        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
+        alarm           = VPI::S_cb_data.new
+        alarm.reason    = aTimeSlot
+        alarm.cb_rtn    = VPI::RubyVPI_user_resume
+        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))
+        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
+        while ring = RubyVPI.pause
+          id = ring.user_data.to_s
+          handler = @lock.synchronize { @id2handler[id] }
 
           if handler
-            handler.call reason
+            handler.call ring
           else
             break
           end
         end
-      end
     end
   end