ruby-vpi 7.0.0

data/lib/ruby-vpi/erb.rb

@@ -0,0 +1,41 @@
+=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
+
+require 'erb'
+
+# A version of ERB whose embedding tags behave like those of PHP. That is, only <%= ... %> tags produce output, whereas <% ... %> tags do *not* produce any output.
+class ERB
+  alias original_initialize initialize
+
+  def initialize aInput, *aArgs
+    # ensure that only <%= ... %> tags generate output
+      input = aInput.gsub %r{<%=.*?%>}m do |s|
+        if ($' =~ /\r?\n/) == 0
+          s << $&
+        else
+          s
+        end
+      end
+
+      aArgs[1] = '>'
+
+    original_initialize input, *aArgs
+  end
+end

data/lib/ruby-vpi/rake.rb

@@ -0,0 +1,35 @@
+=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
+
+require 'fileutils'
+
+module FileUtils
+  alias old_sh sh
+
+  # An improved sh() that also accepts arrays as arguments.
+  def sh *aArgs, &aBlock
+    old_sh *collect_args(aArgs).reject {|i| i.to_s.empty?}, &aBlock
+  end
+
+  # Collects the given arguments into a single, sparse array.
+  def collect_args *aArgs
+    aArgs.flatten.compact
+  end
+end

data/lib/ruby-vpi/rdoc.rb

@@ -0,0 +1,51 @@
+=begin
+  Copyright 2006 Suraj N. Kurapati
+  Copyright 2004 Dave Thomas
+
+  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
+
+require 'rdoc/usage'
+
+module RDoc
+  # Display usage information from RDoc comments in the given file.
+  def RDoc.usage_from_file input_file, *args
+    comment = File.open(input_file) do |file|
+      find_comment(file)
+    end
+
+    comment = comment.gsub(/^\s*#/, '')
+
+    markup = SM::SimpleMarkup.new
+    flow_convertor = SM::ToFlow.new
+
+    flow = markup.convert(comment, flow_convertor)
+
+    format = "plain"
+
+    unless args.empty?
+      flow = extract_sections(flow, args)
+    end
+
+    options = RI::Options.instance
+    if args = ENV["RI"]
+      options.parse(args.split)
+    end
+    formatter = options.formatter.new(options, "")
+    formatter.display_flow(flow)
+  end
+end

data/lib/ruby-vpi/rspec.rb

@@ -0,0 +1,32 @@
+# Bootstraps the RSpec library from within Ruby.
+
+=begin
+  Copyright 2006 Suraj N. Kurapati
+  Copyright 2006 RSpec project
+
+  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
+
+require 'rubygems'
+require_gem 'rspec', '>= 0.5.4'
+require 'spec'
+
+# prevent RSpec termination when no arguments are provided
+  ARGV.unshift ''
+
+$context_runner = ::Spec::Runner::OptionParser.create_context_runner(ARGV, false, STDERR, STDOUT)
+at_exit {$context_runner.run false}

data/lib/ruby-vpi/runner.rb

@@ -0,0 +1,22 @@
+=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
+
+require 'ruby-vpi'
+RubyVPI.load_runner_template

data/lib/ruby-vpi/vpi_util.rb

@@ -0,0 +1,310 @@
+# 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
+
+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
+    include Vpi
+
+    # Reads the value using the given format 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
+
+    # 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.
+    def get_value aFormat = VpiObjTypeVal
+      val = get_value_wrapper(aFormat)
+
+      case val.format
+        when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
+          val.value.str
+
+        when VpiScalarVal
+          val.value.scalar
+
+        when VpiIntVal
+          get_value_wrapper(VpiHexStrVal).value.str.to_i(16)
+
+        when VpiRealVal
+          val.value.real
+
+        when VpiTimeVal
+          val.value.time
+
+        when VpiVectorVal
+          val.value.vector
+
+        when VpiStrengthVal
+          val.value.strength
+
+        else
+          raise "unknown S_vpi_value.format: #{val.format}"
+      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.
+    def put_value aValue, aFormat = nil, aTime = nil, aDelay = VpiNoDelay
+      aFormat ||= get_value_wrapper(VpiObjTypeVal).format
+
+      newVal = S_vpi_value.new
+      newVal.format = aFormat
+
+      case aFormat
+        when VpiBinStrVal, VpiOctStrVal, VpiDecStrVal, VpiHexStrVal, VpiStringVal
+          newVal.value.str = aValue.to_s
+
+        when VpiScalarVal
+          newVal.value.scalar = aValue
+
+        when VpiIntVal
+          newVal.format = VpiHexStrVal
+          newVal.value.str = aValue.to_i.to_s(16)
+
+        when VpiRealVal
+          newVal.value.real = aValue.to_f
+
+        when VpiTimeVal
+          newVal.value.time = aValue
+
+        when VpiVectorVal
+          newVal.value.vector = aValue
+
+        when VpiStrengthVal
+          newVal.value.strength = aValue
+
+        else
+          raise "unknown S_vpi_value.format: #{newVal.format}"
+      end
+
+      vpi_put_value self, newVal, aTime, aDelay
+
+      # 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
+                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 VpiRealVal
+              readenVal == aValue.to_f
+
+            else
+              true
+          end
+
+        unless writtenCorrectly
+          raise "value written (#{aValue.inspect}) does not match value read (#{readenVal.inspect}) from handle #{self}"
+        end
+
+      aValue
+    end
+
+    HINT_REGEXP = %r{_([a-z])$}
+    ASSIGN_REGEXP = %r{=$}
+    QUERY_REGEXP = %r{\?$}
+    PREFIX_REGEXP = %r{^(.*?)_}
+
+    # Enables read and write access to VPI properties of this handle.
+    def method_missing aMsg, *aArgs, &aBlockArg
+      methName = aMsg.to_s
+
+      # determine if property is being written
+        if isAssign = methName =~ ASSIGN_REGEXP
+          methName.sub! ASSIGN_REGEXP, ''
+        end
+
+      # determine if property is being queried
+        if isQuery = methName =~ QUERY_REGEXP
+          methName.sub! QUERY_REGEXP, ''
+        end
+
+      # parse Accessor parameter
+        if accessor = methName[HINT_REGEXP, 1]
+          methName.sub! HINT_REGEXP, ''
+        end
+
+      # parse Operation parameter
+        if operation = methName[PREFIX_REGEXP, 1]
+          methName.sub! PREFIX_REGEXP, ''
+        end
+
+      # resolve Property parameter into a valid VPI property
+        propName = methName[0, 1].upcase << methName[1..-1]
+        propName.insert(0, 'Vpi') unless methName =~ /^vpi/
+
+        puts '', Kernel.caller.join("\n"), '', "operation: #{operation}", "meth: #{aMsg}", "args: #{aArgs.inspect}", "name: #{methName}", "prop: #{propName}", "assign: #{isAssign}", "query: #{isQuery}" if $DEBUG
+
+        begin
+          prop = Vpi.const_get(propName)
+        rescue NameError
+          raise ArgumentError, "invalid VPI property `#{propName}'"
+        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
+
+            break
+          end
+        end
+
+      raise NoMethodError, "unable to access VPI property `#{propName}' through method `#{aMsg}' with arguments `#{aArgs.inspect}' for handle #{self}"
+    end
+
+    # Returns an array of handles of the given type.
+    def [] aType
+      handles = []
+
+      if itr = vpi_iterate(aType, self)
+        while h = vpi_scan(itr)
+          handles << h
+        end
+      end
+
+      handles
+    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)
+    end
+  end
+end

data/lib/ruby-vpi.rb

@@ -0,0 +1,58 @@
+=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
+
+# Provides configuration information of the Ruby-VPI project.
+module RubyVPI
+  LIBRARY_PATH = File.dirname(__FILE__)
+  PATH = File.dirname(LIBRARY_PATH)
+  TEMPLATE_PATH = File.join(PATH, 'tpl')
+  OBJECT_PATH = File.join(PATH, 'obj')
+
+  # Loads the test runner template.
+  def self.load_runner_template
+    load File.join(TEMPLATE_PATH, 'runner.rake')
+  end
+
+  # Initializes the current bench using the given parameters.
+  def self.init_bench aTestPrefix, aProtoClassId
+    Vpi::relay_verilog	# service the $ruby_init() callback
+
+    require 'ruby-vpi/vpi_util'
+
+    # load the design under test
+      require "#{aTestPrefix}_design.rb"
+
+      if ENV['PROTO']
+        require "#{aTestPrefix}_proto.rb"
+
+        proto = Kernel.const_get(aProtoClassId).new
+
+        Vpi.class_eval do
+          define_method :relay_verilog do
+            proto.simulate!
+          end
+        end
+
+        puts "#{aTestPrefix}: verifying prototype instead of design"
+      end
+
+    require "#{aTestPrefix}_spec.rb"
+  end
+end

data/memo.html

@@ -0,0 +1,86 @@
+<h1>Notes</h1>
+
+
+	<ul>
+	<li>When within Rake, rubygems is automatically available for use. no need to require() it again</li>
+	</ul>
+
+
+	<h1>Pending tasks</h1>
+
+
+	<ul>
+	<li>integrate RCov for coverage statistics</li>
+	</ul>
+
+
+	<ul>
+	<li>define handled methods in Vpi::method_missing for faster response
+	<ul>
+	<li>this has been verified as bottleneck from profiling data</li>
+	</ul></li>
+	</ul>
+
+
+	<ul>
+	<li>file bug report for Icarus 0.8 (l0_dcache)
+	<ul>
+	<li>try new icarus snapshot</li>
+	</ul></li>
+	</ul>
+
+
+	<ul>
+	<li><span class="caps">GHDL</span> simulator supports <span class="caps">VPI</span>
+	<ul>
+	<li>need way to invoke <span class="caps">VPI</span> tasks from <span class="caps">VHDL</span>, like <code>$ruby_init();</code></li>
+	</ul></li>
+	</ul>
+
+
+	<ul>
+	<li>smarter test generation, which adjusts to user modifications in previously generated output</li>
+	</ul>
+
+
+	<h1>Finished tasks</h1>
+
+
+	<ul>
+	<li>add support for <span class="caps">ESL</span> prototyping (like SystemC)</li>
+	</ul>
+
+
+	<ul>
+	<li>decouple code generation with $RUBYLIB and erb</li>
+	</ul>
+
+
+	<ul>
+	<li>change should_be to should_equal in examples</li>
+	</ul>
+
+
+	<ul>
+	<li>add support for <span class="caps">GPL</span> Cver in the test runner template</li>
+	</ul>
+
+
+	<ul>
+	<li>build ruby-vpi once to generate all <strong>.so files
+	<ul>
+	<li>test runner should not rebuild ruby-vpi every time</li>
+	</ul></li>
+	</ul>
+
+
+	<ul>
+	<li>distribute as a <span class="caps">GEM</span>, binary, and source
+	<ul>
+	<li>use <span class="caps">RUBYLIB</span> to bypass rubygems site installation for local testing. otherwise have to build &#38; install gem <em>every</em> time!</li>
+		<li>put lib/</strong> into lib/ruby-vpi/*</li>
+	</ul></li>
+	</ul>
+
+
+	<h1>Obsolete tasks</h1>

data/readme.html

@@ -0,0 +1,19 @@
+<h1>Welcome to Ruby-VPI</h1>
+
+
+	<p>Ruby-VPI is a Ruby interface to Verilog <span class="caps">VPI</span>. It lets you create complex Verilog test benches easily and wholly in Ruby.</p>
+
+
+	<ul>
+	<li>See the <a href="./doc/">user manual</a> to begin using Ruby-VPI.</li>
+	</ul>
+
+
+	<ul>
+	<li>See the <a href="./history.html">release history</a> to see what is new in this release.</li>
+	</ul>
+
+
+	<ul>
+	<li>Visit the <a href="http://ruby-vpi.rubyforge.org">project website</a> for additional resources.</li>
+	</ul>