ruby-vpi 19.0.0 → 20.0.0

data/LICENSE

@@ -1,21 +1,20 @@
 Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>
 Copyright 1999 Kazuhiro HIWADA <HIWADA at KUEE dot KYOTO-U dot AC dot JP>
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
 
-1. All copies and substantial portions of the Software, whether modified or
-   unmodified, (the "Derivatives") and their corresponding machine-readable
-   source code (the "Code") must include the above copyright notice and this
-   permission notice.
+* All copies and substantial portions of the Software (the "Derivatives")
+  and their corresponding machine-readable source code (the "Code") must
+  include the above copyright notice and this permission notice.
 
-2. The Derivatives, upon distribution, must be accompanied by the Code or, if
-   the Code is obtainable for no more than the cost of distribution plus a
-   nominal fee, by information on how to obtain the Code.
+* Upon distribution, the Derivatives must be accompanied either by the Code
+  or--provided that the Code is obtainable for no more than the cost of
+  distribution plus a nominal fee--by information on how to obtain the Code.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS

data/README

@@ -1 +1 @@
-Please see ./index.html or ./doc/readme.html in your web browser.
+Please see ./doc/guide.html in your web browser.

data/Rakefile

@@ -13,24 +13,15 @@ require 'tempfile'
 require 'rbconfig'
 
 PROJECT_LIBS = File.join(File.dirname(__FILE__), 'lib')
+DYNAMIC_DOCS = 'ruby-vpi-dynamic.rb'
 
 $:.unshift PROJECT_LIBS
 require 'ruby-vpi'
 require 'ruby-vpi/rake'
+require 'ruby-vpi/util'
 
 task :default => :build
 
-
-# load project information
-  include RubyVPI
-  PROJECT_SSH_URL  = "snk@rubyforge.org:/var/www/gforge-projects/#{PROJECT_ID}"
-
-  load 'doc/history.rb'
-  head = @history.first
-  PROJECT_VERSION  = head['Version']
-  PROJECT_BIRTHDAY = head['Date']
-
-
 # utility
 
   # Returns a temporary, unique path ready for
@@ -41,16 +32,10 @@ task :default => :build
     path
   end
 
-  # uploads the given sources to the given destination URL
-  def upload aDestUrl, *aSources
-    sh 'rsync', '-avz', '--delete', aSources, aDestUrl
-  end
-
   # propogate cleaning tasks recursively to lower levels
   %w[clean clobber].each do |t|
     task t do
-      files = FileList['**/Rakefile'].exclude('_darcs')
-      files.shift # avoid infinite loop on _this_ file
+      files = FileList['**/Rakefile'].exclude('_darcs') - %w[Rakefile]
 
       # allows propogation to lower levels when gem not installed
       ENV['RUBYLIB'] = PROJECT_LIBS
@@ -63,9 +48,7 @@ task :default => :build
     end
   end
 
-
 # extension
-
   desc "Builds object files for all simulators."
   task :build
 
@@ -75,20 +58,20 @@ task :default => :build
   ccFlags = ENV['CFLAGS']
   ldFlags = ENV['LDFLAGS']
 
-  SIMULATORS.each_pair do |id, sim|
-    taskName = "build_#{id}"
+  RubyVPI::SIMULATORS.each do |sim|
+    taskName = "build_#{sim.id}"
 
     desc "Builds object files for #{sim.name}."
     task taskName => ['obj', 'ext'] do
-      src = PROJECT_ID + '.' + Config::CONFIG['DLEXT']
-      dst = File.expand_path(File.join('obj', "#{id}.so"))
+      src = RubyVPI::Project[:name] + '.' + Config::CONFIG['DLEXT']
+      dst = File.expand_path(File.join('obj', "#{sim.id}.so"))
 
       unless File.exist? dst
         cd 'ext' do
           ENV['CFLAGS']  = [ccFlags, sim.compiler_args].compact.join(' ')
           ENV['LDFLAGS'] = [ldFlags, sim.linker_args].compact.join(' ')
 
-          sh "rake SIMULATOR=#{id}"
+          sh "rake SIMULATOR=#{sim.id}"
           mv src, dst
           sh 'rake clean'
         end
@@ -98,41 +81,88 @@ task :default => :build
     task :build => taskName
   end
 
-
 # documentation
+  desc "Build the documentation."
+  task :doc
 
-  desc 'Generate user documentation.'
-  task :doc do |t|
-    cd t.name do
-      sh 'rake'
-    end
+  # the user guide
+  file 'doc/guide.html' => 'doc/guide.erb' do |t|
+    sh "gerbil html #{t.prerequisites} > #{t.name}"
   end
+  task :doc => 'doc/guide.html'
+  CLOBBER.include 'doc/guide.html'
 
+# API reference
+  directory 'doc/api'
+  CLOBBER.include 'doc/api'
 
-  directory 'ref'
-  CLOBBER.include 'ref'
+  desc "Build API reference."
+  task :ref => ['doc/api/ruby', 'doc/api/c']
 
-  desc 'Generate reference documentation.'
-  file 'ref' => ['ref/c', 'ref/ruby']
+  file DYNAMIC_DOCS => 'ext/vpi_user.h' do |t|
+    File.open t.name, 'w' do |f|
+      f.puts "# This module encapsulates all functionality provided by the C-language Application Programming Interface (API) of the Verilog Procedural Interface (VPI).  See the ext/vpi_user.h file for details."
+      f.puts "module VPI"
+        body = File.read(t.prerequisites[0])
 
+        # constants
+        body.scan %r{^#define\s+(vpi\S+)\s+(\S+)\s+/\*+(.*?)\*+/} do |var, val, info|
+          const = var.to_ruby_const_name
+          f.puts '# ' << info
+          f.puts "#{const}=#{val}"
 
-  directory 'ref/ruby'
-  CLOBBER.include 'ref/ruby'
+          f.puts "# Returns the #{const} constant: #{info}"
+          f.puts "def self.#{var}; end"
+        end
 
-  desc 'Generate reference for Ruby.'
-  Rake::RDocTask.new 'ref/ruby' do |t|
-    t.rdoc_dir = t.name
-    t.title    = "#{PROJECT_NAME}: #{PROJECT_SUMMARY}"
-    t.options.concat %w(--charset utf-8 --line-numbers)
-    t.rdoc_files.include '{bin,lib/**}/*.rb'
+        # functions
+        body.scan /^XXTERN\s+(\S+\s+\*?)(\S+)\s+PROTO_PARAMS\(\((.*?)\)\);/m do |type, func, args|
+          meth = func.gsub(/\W/, '')
+          args = args.gsub(/[\r\n]/, ' ')
+
+          [
+            [ /PLI_BYTE8(\s*)\*(\s*data)/ , 'Object\1\2'  ],
+            [ /PLI_BYTE8(\s*)\*?/         , 'String\1'    ],
+            [ /PLI_U?INT32(\s*)\*/        , 'Array\1'     ],
+            [ /PLI_U?INT32/               , 'Integer'     ],
+            [ /\b[ps]_/                   , 'VPI::S_'     ],
+            [ 'vpiHandle'                 , 'VPI::Handle' ],
+            [ /va_list\s+\w+/             , '...'         ],
+            [ /\bvoid(\s*)\*/             , 'Object\1'    ],
+            [ 'void'                      , 'nil'         ],
+          ].each do |(a, b)|
+            args.gsub! a, b
+            type.gsub! a, b
+          end
+
+          f.puts "# #{func}(#{args}) returns #{type}"
+          f.puts "def self.#{meth}; end"
+        end
+
+        # VPI::Handle methods
+        f.puts "class Handle"
+          require 'lib/ruby-vpi/core/edge-methods.rb'
+          RubyVPI::EdgeClass::DETECTION_METHODS.each do |m|
+            f.puts "# #{m.info}"
+            f.puts "def #{m.name}; end"
+          end
+        f.puts "end"
+      f.puts "end"
+    end
   end
+  CLOBBER.include DYNAMIC_DOCS
 
+  Rake::RDocTask.new 'doc/api/ruby' do |t|
+    Rake::Task['doc/api'].invoke
+    t.rdoc_dir = t.name
 
-  directory 'ref/c'
-  CLOBBER.include 'ref/c'
+    Rake::Task[DYNAMIC_DOCS].invoke
+    t.rdoc_files.include 'bin/{ruby-vpi,*.rb}', 'lib/**/*.rb', DYNAMIC_DOCS
+  end
 
-  desc 'Generate reference for C.'
-  file 'ref/c' do |t|
+
+  desc 'Build API reference for C.'
+  file 'doc/api/c' => 'doc/api' do |t|
     # doxygen outputs to this temporary destination
     tempDest = 'ext/html'
 
@@ -140,67 +170,25 @@ task :default => :build
       sh "doxygen"
     end
 
-    mv FileList[tempDest + '/*'].to_a, t.name
-    rmdir tempDest
-  end
-
-
-# distribution
-
-  desc 'Publish documentation to website.'
-  task :web => ['ref/web', 'doc/web']
-
-  desc "Publish reference documentation."
-  task 'ref/web' => 'ref' do |t|
-    upload PROJECT_SSH_URL, *t.prerequisites
-  end
-
-  desc "Publish user documentation."
-  task 'doc/web' => 'doc' do |t|
-    upload PROJECT_SSH_URL, *t.prerequisites
-  end
-
-  desc 'Connect to website FTP.'
-  task :ftp do
-    sh 'lftp', "sftp://#{PROJECT_SSH_URL}"
-  end
-
-  desc 'Generate release announcement.'
-  task :ann => 'doc/history.rb' do |t|
-    require t.prerequisites[0]
-
-    $: << File.join(File.dirname(__FILE__), 'doc', 'lib')
-    require 'doc_proxy'
-
-    text = [
-      PROJECT_DETAIL,
-      "* See #{PROJECT_URL} for details.",
-      "---",
-      @history.first
-    ].join "\n\n"
-
-    IO.popen('w3m -T text/html -dump -cols 60', 'w+') do |pipe|
-      pipe.write text.to_html
-      pipe.close_write
-      puts pipe.read
-    end
+    mv tempDest, t.name
   end
 
-
 # packaging
-
-  desc "Generate release packages."
-  task :release => [:ref, :doc] do
-    sh 'rake package'
-  end
-
   spec = Gem::Specification.new do |s|
-    s.name              = PROJECT_ID
-    s.rubyforge_project = PROJECT_ID
-    s.summary           = PROJECT_SUMMARY
-    s.description       = PROJECT_DETAIL
-    s.homepage          = PROJECT_URL
-    s.version           = PROJECT_VERSION
+    s.name              = RubyVPI::Project[:name].downcase
+    s.version           = RubyVPI::Project[:version]
+    s.summary           = "Ruby interface to IEEE 1364-2005 Verilog VPI"
+    s.description       = "Ruby-VPI is a #{s.summary} and a platform for unit testing, rapid prototyping, and systems integration of Verilog modules through Ruby. It lets you create complex Verilog test benches easily and wholly in Ruby."
+    s.homepage          = RubyVPI::Project[:website]
+    s.rubyforge_project = s.name
+
+    s.files       = FileList['**/*'].exclude('_darcs', DYNAMIC_DOCS)
+    s.autorequire = s.name
+    s.extensions << 'gem_extconf.rb'
+    s.executables = s.name
+
+    s.requirements << "POSIX threads library"
+    s.requirements << "C language compiler"
 
     s.add_dependency 'rake',       '>= 0.7.0'
     s.add_dependency 'rspec',      '>= 1.0.0'
@@ -208,23 +196,13 @@ task :default => :build
     s.add_dependency 'xx'           # needed by rcov
     s.add_dependency 'ruby-debug', '>= 0.5.2'
     s.add_dependency 'ruby-prof'
-
-    s.requirements << "POSIX threads library"
-    s.requirements << "C language compiler"
-
-    s.files       = FileList['**/*'].exclude('_darcs')
-    s.autorequire = PROJECT_ID
-    s.extensions << 'gem_extconf.rb'
-    s.executables = PROJECT_ID
   end
 
   Rake::GemPackageTask.new(spec) do |pkg|
     pkg.need_tar = true
   end
 
-
 # installation
-
   desc "Configures the gem during installation."
   task :gem_config_inst do |t|
     # make documentation available to gem_server
@@ -236,8 +214,18 @@ task :default => :build
     ln_s gemDir, File.join(docDir, 'rdoc')
   end
 
+# releasing
+  desc 'Build release packages.'
+  task :dist => [:clobber, :doc, :ref] do
+    system 'rake package'
+  end
 
-# testing
+# utility
+  desc 'Upload to project website.'
+  task :upload => [:doc, :ref] do
+    sh "rsync -av doc/ ~/www/lib/#{spec.name}"
+    sh "rsync -av doc/api/ ~/www/lib/#{spec.name}/api/ --delete"
+  end
 
   desc "Ensure that examples work with $SIMULATOR"
   task :test => :build do
@@ -247,8 +235,6 @@ task :default => :build
     sim = ENV['SIMULATOR'] || 'cver'
 
     FileList['examples/**/*.rake'].each do |runner|
-      cd File.dirname(runner) do
-        sh 'rake', '-f', File.basename(runner), sim
-      end
+      sh 'rake', '-f', runner, sim
     end
   end

data/TODO

@@ -0,0 +1,77 @@
+Pending tasks
+=============
+
+* add support for multiple Ruby prototypes so that you can do integration
+  testing and ESL stuff
+
+* add shortcuts for reading & writing VPI delay values
+
+* add support for GHDL simulator (and thereby VHDL!) because it supports VPI
+
+* add instructions for using *ruby-debug* with a graphical debugging tool or IDE
+  like RadRails
+
+* write section about code coverage and prototyping in manual
+
+* write unit tests for the non-VPI libraries like integer.rb and float.rb
+
+
+Finished tasks
+==============
+
+* add support for ESL prototyping (like SystemC)
+
+* decouple code generation with $RUBYLIB and erb
+
+* change should_be to should_equal in examples
+
+* add support for GPL Cver in the test runner template
+
+* build ruby-vpi once to generate all .so files
+
+  * test runner should not rebuild ruby-vpi every time
+
+* distribute as a GEM, binary, and source
+
+  * use RUBYLIB to bypass rubygems site installation for local testing.
+    otherwise have to build & install gem _every_ time!
+
+  * move stuff from lib/ into lib/ruby-vpi/
+
+* integrate RCov for code-coverage statistics
+
+* method_missing for Design class
+
+* define handled methods in Vpi::method_missing for faster response
+
+  * this has been verified as bottleneck from profiling data
+
+* make RCov correctly profile the code and report useful coverage metrics...
+
+* add support for VPI callbacks which execute Ruby blocks
+
+* write section about code coverage and prototyping in manual
+
+* clean up the teriminology section... unnecessary
+
+
+Obsolete tasks
+==============
+
+* smarter test generation, which adjusts to user modifications in previously
+  generated output
+
+  Just use a smart merging tool like *kdiff3*.
+
+* interactive console IRB wrapper for spec (just like Breakpoints in Rails)
+
+  Use the *ruby-debug* library with "*debugger* command for
+  breakpoints":http://www.datanoise.com/articles/category/ruby-debug instead!
+
+* need to dump signal values when expectation fails in rSpec
+
+  You can use the interactive debugger instead.
+
+* maybe a waveform dump will also help
+
+  After reading some RTL verification books, this is not necessarily true.

data/bin/convert.rb

@@ -1,4 +1,4 @@
-# Converts Verilog source code into Ruby.
+# Converts Verilog `defines, constants, ranges, etc. into Ruby syntax.
 # * The standard input stream is read if no input files are specified.
 # * Output is written to the standard output stream.
 

data/bin/generate/design.rb

@@ -1,15 +1,16 @@
 <% clock = aModuleInfo.clock_port.name rescue "YOUR_CLOCK_SIGNAL_HERE" %>
 # Simulates the design under test for one clock cycle.
-def cycle!
+def DUT.cycle!
   <%= clock %>.high!
   advance_time
+
   <%= clock %>.low!
   advance_time
 end
 
 <% reset = aModuleInfo.reset_port.name rescue "YOUR_RESET_SIGNAL_HERE" %>
 # Brings the design under test into a blank state.
-def reset!
+def DUT.reset!
   <%= reset %>.high!
   cycle!
   <%= reset %>.low!

data/bin/generate/loader.rb

@@ -0,0 +1 @@
+RubyVPI.load_test(<%= aModuleInfo.name.inspect %>, <%= aOutputInfo.designPath.inspect %>, <%= aOutputInfo.protoPath.inspect %>, <%= aOutputInfo.specPath.inspect %>)

data/bin/generate/proto.rb

@@ -1,18 +1,20 @@
-always do
-  wait until <%= aModuleInfo.clock_port.name rescue "YOUR_CLOCK_SIGNAL_HERE" %>.posedge?
+if RubyVPI::USE_PROTOTYPE
+  always do
+    wait until DUT.<%= aModuleInfo.clock_port.name rescue "YOUR_CLOCK_SIGNAL_HERE" %>.posedge?
 
-  # discard old outputs
-  <% aModuleInfo.output_ports.each do |port| %>
-    <%= port.name %>.x!
-  <% end %>
+    # discard old outputs
+    <% aModuleInfo.output_ports.each do |port| %>
+      DUT.<%= port.name %>.x!
+    <% end %>
 
-  # process new inputs
-  <% aModuleInfo.input_ports.each do |port| %>
-    # some_interesting_process( <%= port.name %> )
-  <% end %>
+    # process new inputs
+    <% aModuleInfo.input_ports.each do |port| %>
+      # some_interesting_process( DUT.<%= port.name %> )
+    <% end %>
 
-  # produce new outputs
-  <% aModuleInfo.output_ports.each do |port| %>
-    # <%= port.name %> = some interesting output
-  <% end %>
+    # produce new outputs
+    <% aModuleInfo.output_ports.each do |port| %>
+      # DUT.<%= port.name %> = some interesting output
+    <% end %>
+  end
 end

data/bin/generate/runner.rake

@@ -1,3 +1,8 @@
+# Path to a Ruby script that will be invoked before the Verilog
+# simulation begins.  This script shall then load the appropriate
+# tests to exercise the desired designs in the Verilog simulation.
+TEST_LOADER = <%= aOutputInfo.loaderPath.inspect %>
+
 # Array of paths and shell globs (see the Dir.glob method's documentation for
 # details) to source files and directories that contain source files.  These
 # source files will be loaded by the simulator before the simulation begins.
@@ -13,9 +18,9 @@ SIMULATOR_SOURCES = FileList[
 #   :cver => %w[these are also separate arguments],
 #
 SIMULATOR_ARGUMENTS = {
-<% RubyVPI::SIMULATORS.each_pair do |id, sim| %>
+<% RubyVPI::SIMULATORS.each do |sim| %>
   # <%= sim.name %>
-  :<%= id %> => "",
+  :<%= sim.id %> => "<%= aModuleInfo.name if sim.id == :vsim %>",
 
 <% end %>
 }
@@ -29,5 +34,5 @@ task :setup do
 end
 
 # This command loads the Ruby-VPI runner template,
-# which runs the simulator using the above parameters.
+# which starts the simulator with the above parameters.
 require 'ruby-vpi/runner'

data/bin/generate/spec.rb

@@ -1,45 +1,43 @@
-<% dut = aOutputInfo.designClassName %>
-
 <% case aOutputInfo.specFormat %>
 <% when :xUnit %>
 require 'test/unit'
 
-class <%= aOutputInfo.specClassName %> < Test::Unit::TestCase
+class A_<%= aModuleInfo.name %>_when_reset < Test::Unit::TestCase
   def setup
-    <%= dut %>.reset!
+    DUT.reset!
   end
 <% aModuleInfo.ports.each do |port| %>
 
   def test_<%= port.name %>
-    # assert <%= dut %>.<%= port.name %> ..., "<%= port.name %> should ..."
+    # assert DUT.<%= port.name %> ..., "<%= port.name %> should ..."
   end
 <% end %>
 end
 <% when :tSpec %>
 require 'test/spec'
 
-context "A resetted <%= dut %>" do
+context "A #{DUT.name}, when reset" do
   setup do
-    <%= dut %>.reset!
+    DUT.reset!
   end
 
   specify "should ..." do
-    # <%= dut %>.should ...
+    # DUT.should ...
   end
 end
 <% when :rSpec %>
 require 'spec'
 
-describe <%= dut %>, " when resetted" do
+describe "A #{DUT.name}, when reset" do
   before do
-    <%= dut %>.reset!
+    DUT.reset!
   end
 
   it "should ..." do
-    # <%= dut %>.should ...
+    # DUT.should ...
   end
 end
 <% else %>
-<%= dut %>.reset!
-# raise "should ..." unless <%= dut %> ...
+DUT.reset!
+# raise "should ..." unless DUT ...
 <% end %>