ruby-vpi 16.0.1 → 17.0.0

data/LICENSE

@@ -1,23 +1,23 @@
-Copyright (c) 2006-2007 Suraj N. Kurapati
+Copyright 2006 Suraj N. Kurapati <snk@gna.org>
 
-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:
 
-All copies and portions of the Software (together the "Derivatives") and
-their corresponding machine-readable source code (the "Code") must include the
-above copyright notice and this permission notice.  The Code must reflect all
-modifications made to the Derivatives.  The Derivatives must be distributed
-either with the Code or, if the Code is obtainable for no more than the cost
-of distribution plus a nominal fee, with information on how to obtain the Code.
+1. All modified and unmodified 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. Upon distribution, the Derivatives must be accompanied either 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.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
-THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

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

data/Rakefile

@@ -2,11 +2,9 @@
 # CFLAGS:: Arguments to the compiler.
 # LDFLAGS:: Arguments to the linker.
 #--
-# Copyright 2006-2007 Suraj N. Kurapati
+# Copyright 2006 Suraj N. Kurapati
 # See the file named LICENSE for details.
 
-CFLAGS, LDFLAGS = ENV['CFLAGS'], ENV['LDFLAGS']
-
 require 'rake/clean'
 require 'rake/rdoctask'
 require 'rake/gempackagetask'
@@ -24,21 +22,22 @@ task :default => :build
 
 
 # load project information
-  include RubyVpi::Config
-  PROJECT_SSH_URL = "snk@rubyforge.org:/var/www/gforge-projects/#{PROJECT_ID}"
+  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']
+  head             = @history.first
+  PROJECT_VERSION  = head['Version']
   PROJECT_BIRTHDAY = head['Date']
 
 
 # utility
 
-  # Returns a temporary, unique path ready for use. No file exists at the
-  # returned path.
+  # Returns a temporary, unique path ready for
+  # use. No file exists at the returned path.
   def generate_temp_path
-    rm_f path = Tempfile.new($$).path
+    path = Tempfile.new($$).path
+    rm_f path
     path
   end
 
@@ -48,7 +47,7 @@ task :default => :build
   end
 
   # propogate cleaning tasks recursively to lower levels
-  [:clean, :clobber].each do |t|
+  %w[clean clobber].each do |t|
     task t do
       files = FileList['**/Rakefile'].exclude('_darcs')
       files.shift # avoid infinite loop on _this_ file
@@ -58,7 +57,7 @@ task :default => :build
 
       files.each do |f|
         cd File.dirname(f) do
-          sh 'rake', t.to_s
+          sh 'rake', t
         end
       end
     end
@@ -73,6 +72,9 @@ task :default => :build
   directory 'obj'
   CLOBBER.include 'obj'
 
+  ccFlags = ENV['CFLAGS']
+  ldFlags = ENV['LDFLAGS']
+
   SIMULATORS.each_pair do |id, sim|
     taskName = "build_#{id}"
 
@@ -83,8 +85,8 @@ task :default => :build
 
       unless File.exist? dst
         cd 'ext' do
-          ENV['CFLAGS'] = "#{CFLAGS} #{sim.compiler_args}"
-          ENV['LDFLAGS'] = "#{LDFLAGS} #{sim.linker_args}"
+          ENV['CFLAGS']  = "#{ccFlags} #{sim.compiler_args}"
+          ENV['LDFLAGS'] = "#{ldFlags} #{sim.linker_args}"
 
           sh 'rake'
           mv src, dst
@@ -120,7 +122,7 @@ task :default => :build
   desc 'Generate reference for Ruby.'
   Rake::RDocTask.new 'ref/ruby' do |t|
     t.rdoc_dir = t.name
-    t.title = "#{PROJECT_NAME}: #{PROJECT_SUMMARY}"
+    t.title    = "#{PROJECT_NAME}: #{PROJECT_SUMMARY}"
     t.options.concat %w(--charset utf-8 --line-numbers)
     t.rdoc_files.include '{bin,lib/**}/*.rb'
   end
@@ -200,25 +202,26 @@ task :default => :build
   end
 
   spec = Gem::Specification.new do |s|
-    s.name = s.rubyforge_project = PROJECT_ID
-    s.summary = PROJECT_SUMMARY
-    s.description = PROJECT_DETAIL
-    s.homepage = PROJECT_URL
-    s.version = PROJECT_VERSION
-
-    s.add_dependency 'rake', '>= 0.7.0'
-    s.add_dependency 'rspec', '>= 0.7.0'
-    s.add_dependency 'rcov', '>= 0.7.0'
-    s.add_dependency 'xx' # needed by rcov
+    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.add_dependency 'rake',       '>= 0.7.0'
+    s.add_dependency 'rspec',      '>= 1.0.0'
+    s.add_dependency 'rcov',       '>= 0.7.0'
+    s.add_dependency 'xx'           # needed by rcov
     s.add_dependency 'ruby-debug', '>= 0.5.2'
 
     s.requirements << "POSIX threads library"
     s.requirements << "C language compiler"
 
-    s.files = FileList['**/*'].exclude('_darcs')
+    s.files       = FileList['**/*'].exclude('_darcs')
     s.autorequire = PROJECT_ID
     s.extensions << 'gem_extconf.rb'
-    s.executables = FileList['bin/*.rb'].map {|f| File.basename f}
+    s.executables = PROJECT_ID
   end
 
   Rake::GemPackageTask.new(spec) do |pkg|
@@ -231,9 +234,9 @@ task :default => :build
   desc "Configures the gem during installation."
   task :gem_config_inst do |t|
     # make documentation available to gem_server
-      gemDir = File.dirname(__FILE__)
+      gemDir  = File.dirname(__FILE__)
       gemName = File.basename(gemDir)
-      docDir = File.join('..', '..', 'doc', gemName)
+      docDir  = File.join('..', '..', 'doc', gemName)
 
       mkdir_p docDir
       ln_s gemDir, File.join(docDir, 'rdoc')
@@ -247,9 +250,9 @@ task :default => :build
     # ensures that current sources are tested instead of the installed gem
     ENV['RUBYLIB'] = PROJECT_LIBS
 
-    FileList['samp/*/'].each do |s|
-      cd s do
-        sh 'rake', ENV['SIMULATOR'] || 'cver'
+    FileList['samp/**/*.rake'].each do |runner|
+      cd File.dirname(runner) do
+        sh 'rake', '-f', File.basename(runner), ENV['SIMULATOR'] || 'cver'
       end
     end
   end

data/bin/convert.rb

@@ -0,0 +1,28 @@
+# Converts Verilog source code into Ruby.
+# * The standard input stream is read if no input files are specified.
+# * Output is written to the standard output stream.
+
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+
+# parse command-line options
+  require 'optparse'
+
+  opts = OptionParser.new
+  opts.banner = "Usage: ruby-vpi convert [options] [files]"
+
+  opts.on '-h', '--help', 'show this help message' do
+    require 'ruby-vpi/rdoc'
+    RDoc.usage_from_file __FILE__
+
+    puts opts
+    exit
+  end
+
+  opts.parse! ARGV
+
+require 'ruby-vpi/verilog_parser'
+puts ARGF.read.verilog_to_ruby

data/bin/generate/design.rb

@@ -0,0 +1,16 @@
+<% clock = aModuleInfo.clock_port.name rescue "YOUR_CLOCK_SIGNAL_HERE" %>
+# Simulates the design under test for one clock cycle.
+def 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!
+  <%= reset %>.high!
+  cycle!
+  <%= reset %>.low!
+end

data/bin/generate/proto.rb

@@ -0,0 +1,13 @@
+# Ruby prototype of the design under test's Verilog implementation.
+def feign!
+  if <%= aModuleInfo.clock_port.name rescue "YOUR_CLOCK_SIGNAL_HERE" %>.posedge?
+    # discard old outputs
+    <% aModuleInfo.output_ports.each do |port| %>
+      <%= port.name %>.x!
+    <% end %>
+
+    # process new inputs
+
+    # produce new outputs
+  end
+end

data/bin/generate/runner.rake

@@ -0,0 +1,33 @@
+# 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.
+SIMULATOR_SOURCES = FileList[
+  '<%= aModuleInfo.name %>.v',
+]
+
+# Command-line arguments for the simulator.  These arguments can be
+# specified as a string or an array of strings, as demonstrated below:
+#
+#   :cver => "this is a single string argument",
+#   :cver => ["these", "are", "separate", "arguments"],
+#   :cver => %w[these are also separate arguments],
+#
+SIMULATOR_ARGUMENTS = {
+<% RubyVPI::SIMULATORS.each_pair do |id, sim| %>
+  # <%= sim.name %>
+  :<%= id %> => "",
+
+<% end %>
+}
+
+# This task is invoked before the simulator runs.  It
+# can be used to make preprations, such as converting
+# Verilog header files into Ruby, for the simulation.
+task :setup do
+  # To learn how to write Rake tasks, please see:
+  # http://docs.rubyrake.org/read/chapter/4#page16
+end
+
+# This command loads the Ruby-VPI runner template,
+# which runs the simulator using the above parameters.
+require 'ruby-vpi/runner'

data/bin/generate/spec.rb

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

data/bin/generate.rb

@@ -0,0 +1,177 @@
+# Generates Ruby-VPI tests from Verilog 2001 and Verilog 95 module declarations.
+#
+# * The standard input stream is read if no input files are specified.
+#
+# = Progress indicators
+#
+# module:: A Verilog module has been identified.
+#
+# create:: A file is being created because it does not exist.
+#
+# skip:: A file is being skipped because it is already up to date.
+#
+# update::  A file will be updated because it is out of date.  A text
+#           merging tool (see MERGER) will be launched to transfer
+#           content from the old file (*.old) and the new file (*.new)
+#           to the out of date file.  If a text merging tool is not
+#           specified, then you will have to do the merging by hand.
+#
+#
+# = Environment variables
+#
+# MERGER::  A command that invokes a text merging tool with three
+#           arguments: (1) old file, (2) new file, (3) output file.
+#           The tool's output should be written to the output file.
+
+#--
+# Copyright 2006-2007 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+$: << File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'ruby-vpi' # for project info
+require 'ruby-vpi/verilog_parser'
+require 'fileutils'
+require 'digest/md5'
+
+
+# Notify the user about some action being performed.
+def notify *args # :nodoc:
+  printf "%8s  %s\n", *args
+end
+
+# Writes the given contents to the file at the given path. If the given path
+# already exists, then a backup is created before invoking the merging tool.
+def write_file aPath, aContent # :nodoc:
+  if File.exist? aPath
+    oldDigest = Digest::MD5.digest(File.read(aPath))
+    newDigest = Digest::MD5.digest(aContent)
+
+    if oldDigest == newDigest
+      notify :skip, aPath
+    else
+      notify :update, aPath
+      cur, old, new = aPath, "#{aPath}.old", "#{aPath}.new"
+
+      FileUtils.cp cur, old, :preserve => true
+      File.open(new, 'w') {|f| f << aContent}
+
+      if m = ENV['MERGER']
+        system "#{m} #{old.inspect} #{new.inspect} #{cur.inspect}"
+      end
+    end
+  else
+    notify :create, aPath
+    File.open(aPath, 'w') {|f| f << aContent}
+  end
+end
+
+
+require 'ruby-vpi/erb'
+
+# Template used for generating output.
+class Template < ERB # :nodoc:
+  TEMPLATE_PATH = __FILE__.sub(/\.rb$/, '')
+
+  def initialize aName
+    super File.read(File.join(TEMPLATE_PATH, aName))
+  end
+end
+
+
+# Holds information about the output destinations of a parsed Verilog module.
+class OutputInfo # :nodoc:
+  RUBY_EXT      = '.rb'
+  VERILOG_EXT   = '.v'
+  RUNNER_EXT    = '.rake'
+
+  DESIGN_SUFFIX = '_design'
+  SPEC_SUFFIX   = '_spec'
+  RUNNER_SUFFIX = '_runner'
+  PROTO_SUFFIX  = '_proto'
+
+  SPEC_FORMATS = [:rSpec, :tSpec, :xUnit, :generic]
+
+  attr_reader :designPath,  :designName,  :designClassName,
+              :specPath,    :specName,    :specClassName,    :specFormat,
+              :runnerPath,  :runnerName,
+              :protoPath,   :protoName
+
+  def initialize aModuleName, aSpecFormat
+    raise ArgumentError unless SPEC_FORMATS.include? aSpecFormat
+    @specFormat       = aSpecFormat
+
+    @designName       = aModuleName + DESIGN_SUFFIX
+    @designPath       = @designName + RUBY_EXT
+
+    @protoName        = aModuleName + PROTO_SUFFIX
+    @protoPath        = @protoName  + RUBY_EXT
+
+    @specName         = aModuleName + SPEC_SUFFIX
+    @specPath         = @specName   + RUBY_EXT
+
+    @designClassName  = aModuleName.to_ruby_const_name
+    @specClassName    = @specName.to_ruby_const_name
+
+    @runnerName       = aModuleName + RUNNER_SUFFIX
+    @runnerPath       = @runnerName + RUNNER_EXT
+  end
+end
+
+
+# obtain templates for output generation
+  DESIGN_TEMPLATE = Template.new('design.rb')
+  PROTO_TEMPLATE  = Template.new('proto.rb')
+  SPEC_TEMPLATE   = Template.new('spec.rb')
+  RUNNER_TEMPLATE = Template.new('runner.rake')
+
+
+# parse command-line options
+  require 'optparse'
+
+  optSpecFmt  = :generic
+  optTestName = 'test'
+
+  opts        = OptionParser.new
+  opts.banner = "Usage: ruby-vpi generate [options] [files]"
+
+  opts.on '-h', '--help', 'show this help message' do
+            require 'ruby-vpi/rdoc'
+            RDoc.usage_from_file __FILE__
+
+            puts opts
+            exit
+          end
+
+  opts.on '--xUnit',
+          'use xUnit (Test::Unit) specification format' do
+            optSpecFmt = :xUnit
+          end
+
+  opts.on '--rSpec',
+          'use rSpec specification format' do
+            optSpecFmt = :rSpec
+          end
+
+  opts.on '--tSpec',
+          'use test/spec specification format' do
+            optSpecFmt = :tSpec
+          end
+
+  opts.parse! ARGV
+
+
+v = VerilogParser.new(ARGF.read)
+v.modules.each do |m|
+  puts
+  notify :module, m.name
+
+  o = OutputInfo.new(m.name, optSpecFmt)
+  aParseInfo, aModuleInfo, aOutputInfo = v.freeze, m.freeze, o.freeze
+
+  write_file o.runnerPath, RUNNER_TEMPLATE.result(binding)
+  write_file o.designPath, DESIGN_TEMPLATE.result(binding)
+  write_file o.protoPath, PROTO_TEMPLATE.result(binding)
+  write_file o.specPath, SPEC_TEMPLATE.result(binding)
+  write_file 'Rakefile', "require 'ruby-vpi/runner_proxy'"
+end

data/bin/ruby-vpi

@@ -0,0 +1,56 @@
+# This is a front-end for tools provided by Ruby-VPI.
+#
+# Usage:
+#   ruby-vpi                                    Show this help message
+#   ruby-vpi TOOL --help                        Show help message for TOOL
+#   ruby-vpi TOOL arguments...                  Run TOOL with some arguments
+
+#--
+# Copyright 2006 Suraj N. Kurapati
+# See the file named LICENSE for details.
+
+TOOL_DIR = File.dirname(__FILE__)
+TOOL_EXT = '.rb'
+
+$: << File.join(TOOL_DIR, '..', 'lib')
+
+
+def show_help_info
+  require 'ruby-vpi/rdoc'
+  RDoc.usage_from_file __FILE__
+
+  # show a list of available tools
+    puts "Tools:"
+
+    Dir[File.join(TOOL_DIR, "*#{TOOL_EXT}")].each do |file|
+      tool = File.basename file, TOOL_EXT
+      printf "  %-10s %s", tool, File.new(file).readline.sub(/^#\s*/, '')
+    end
+
+    puts
+
+  # show a list of available simulators
+    require 'ruby-vpi'
+    puts "Simulators:"
+
+    RubyVPI::SIMULATORS.each_pair do |id, sim|
+      printf "  %-10s %s\n", id, sim.name
+    end
+end
+
+
+unless ARGV.empty?
+  tool = ARGV.shift
+  glob = File.join(TOOL_DIR, tool + '*' + TOOL_EXT)
+  file = Dir[glob].first
+
+  begin
+    load file
+  rescue LoadError
+    show_help_info
+    puts '', '#' * 76
+    raise "Invalid tool: #{tool.inspect}"
+  end
+else
+  show_help_info
+end

data/doc/Rakefile

@@ -8,18 +8,31 @@ require 'rake/clean'
 
 $: << File.join(File.dirname(__FILE__), '..', 'lib')
 require 'ruby-vpi'
-include RubyVpi::Config
+include RubyVPI
+
 HISTORY_URL = WEBSITE_URL + "/history.html"
 RSS_URL = WEBSITE_URL + '/rss.xml'
 RSS_INFO = "RSS feed for this project."
 
 require 'ruby-vpi/erb'
+include ERB::Util
 
 
 $: << File.join(File.dirname(__FILE__), 'lib')
 require 'doc_proxy'
 
 
+def resolve_includes aFilePath
+  input = File.read(aFilePath)
+
+  input.gsub! %r{<doc_proxy_include *(.*?)>} do
+    resolve_includes($1)
+  end
+
+  input
+end
+
+
 FileList['*.doc'].each do |src|
   prefix = File.basename(src, File.extname(src))
   helper = prefix + '.rb'
@@ -28,7 +41,7 @@ FileList['*.doc'].each do |src|
 
   desc "Process file #{src.inspect}."
   file dst => [src, 'common.tpl', *deps] do |t|
-    String.reset_anchors
+    puts src
 
     content = DocProxy.new.instance_eval do
       # default output configuration
@@ -41,10 +54,14 @@ FileList['*.doc'].each do |src|
         end
 
       # evaluate the documentation file
-        template = ERB.new(File.read(src))
+        input = resolve_includes(src)
+        File.open('input', 'w') {|f| f << input} if $DEBUG
+
+        template = ERB.new(input)
         content = template.result(binding)
         toc, content = post_process(content)
 
+
       # fit result into common HTML format
         template = ERB.new(File.read(t.prerequisites[1]))
         template.result(binding)
@@ -52,7 +69,6 @@ FileList['*.doc'].each do |src|
 
     File.open(dst, 'w') do |f|
       f << content
-      puts f.path
     end
   end