ruby-vpi 7.0.0

data/bin/generate_test.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/ruby -w
+#
+# == Synopsis
+# Generates Ruby-VPI tests from Verilog 2001 module declarations. A generated test is composed of the following parts.
+#
+# Runner:: Written in Rake, this file builds and runs the test bench.
+#
+# Bench:: Written in Verilog and Ruby, these files define the testing environment.
+#
+# Design:: Written in Ruby, this file provides an interface to the Verilog module under test.
+#
+# Prototype:: Written in Ruby, this file defines a prototype of the design under test.
+#
+# Specification:: Written in Ruby, this file verifies the design.
+#
+# The reason for dividing a single test into these parts is mainly to decouple the design from the specification. This allows humans to focus on writing the specification while the remainder is automatically generated by this tool.
+#
+# For example, when the interface of a Verilog module changes, you would simply re-run this tool to incorporate those changes into the test without diverting your focus from the specification.
+#
+# == Notes
+# * If no input files are specified, then the standard input stream will be read instead.
+# * The first signal parameter in a module's declaration is assumed to be the clocking signal.
+# * Existing output files will be backed-up before being over-written. A backed-up file has a tilde (~) appended to its name.
+
+=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'
+
+# Writes the given contents to the file at the given path. If the given path already exists, then a backup is created before proceeding.
+def write_file aPath, aContent
+  # create a backup
+    if File.exist? aPath
+      backupPath = aPath.dup
+
+      while File.exist? backupPath
+        backupPath << '~'
+      end
+
+      FileUtils.cp aPath, backupPath, :preserve => true
+    end
+
+  File.open(aPath, 'w') {|f| f << aContent}
+end
+
+
+
+require 'ruby-vpi/erb'
+
+# Template used for generating output.
+class Template < ERB
+  TEMPLATE_PATH = __FILE__.sub %r{\.rb$}, '_tpl'
+
+  def initialize aName
+    super File.read(File.join(TEMPLATE_PATH, aName))
+  end
+end
+
+
+
+# Holds information about a parsed Verilog module.
+class ModuleInfo
+  attr_reader :name, :portNames, :paramNames, :portDecls, :paramDecls, :inputPortNames
+
+  def initialize aDecl
+    aDecl =~ %r{module\s+(\w+)\s*(\#\((.*?)\))?\s*\((.*?)\)\s*;}m
+    @name, paramDecl, portDecl = $1, $3 || '', $4
+
+    # parse configuration parameters
+      paramDecl.gsub! %r{\bparameter\b}, ''
+      paramDecl.strip!
+
+      @paramDecls = paramDecl.split(/,/)
+
+      @paramNames = paramDecls.inject([]) do |acc, decl|
+        acc << decl.scan(%r{\w+}).first
+      end
+
+    # parse signal parameters
+      portDecl.gsub! %r{\breg\b}, ''
+      portDecl.strip!
+
+      @portDecls = portDecl.split(/,/)
+
+      @inputPortNames = []
+
+      @portNames = portDecls.inject([]) do |acc, decl|
+        name = decl.scan(%r{\w+}).last
+        @inputPortNames << name if decl =~ /\binput\b/
+
+        acc << name
+      end
+  end
+
+  # Parses and returns Verilog 2001 module declarations from the given input.
+  def self.parse_declarations aInput
+    input = aInput.dup
+
+    # remove single-line comments
+      input.gsub! %r{//.*$}, ''
+
+    # remove multi-line comments
+      input.gsub! %r{/\*.*?\*/}m, ''
+
+    input.scan %r{module.*?;}m
+  end
+end
+
+
+
+# Holds information about the output destinations of a parsed Verilog module.
+class OutputInfo
+  RUBY_EXT = '.rb'
+  VERILOG_EXT = '.v'
+  RUNNER_EXT = '.rake'
+
+  RUNNER_TMPL_REL_PATH = 'tpl/runner.rake'
+
+  SPEC_FORMATS = [:RSpec, :UnitTest, :Generic]
+
+  attr_reader :verilogBenchName, :verilogBenchPath, :rubyBenchName, :rubyBenchPath, :designName, :designClassName, :designPath, :specName, :specClassName, :specFormat, :specPath, :rubyVpiPath, :runnerName, :runnerPath, :protoName, :protoPath, :protoClassName
+
+  attr_reader :testName, :suffix, :benchSuffix, :designSuffix, :specSuffix, :runnerSuffix, :protoSuffix
+
+  def initialize aModuleName, aSpecFormat, aTestName, aRubyVpiPath
+    raise ArgumentError unless SPEC_FORMATS.include? aSpecFormat
+    @specFormat = aSpecFormat
+    @testName = aTestName
+
+    @suffix = '_' + @testName
+    @benchSuffix = @suffix + '_bench'
+    @designSuffix = @suffix + '_design'
+    @specSuffix = @suffix + '_spec'
+    @runnerSuffix = @suffix + '_runner'
+    @protoSuffix = @suffix + '_proto'
+
+    @rubyVpiPath = aRubyVpiPath
+
+    @verilogBenchName = aModuleName + @benchSuffix
+    @verilogBenchPath = @verilogBenchName + VERILOG_EXT
+
+    @rubyBenchName = aModuleName + @benchSuffix
+    @rubyBenchPath = @rubyBenchName + RUBY_EXT
+
+    @designName = aModuleName + @designSuffix
+    @designPath = @designName + RUBY_EXT
+
+    @protoName = aModuleName + @protoSuffix
+    @protoPath = @protoName + RUBY_EXT
+
+    @specName = aModuleName + @specSuffix
+    @specPath = @specName + RUBY_EXT
+
+    @designClassName = aModuleName.capitalize
+    @protoClassName = @designClassName + 'Proto'
+    @specClassName = @specName.capitalize
+
+    @runnerName = aModuleName + @runnerSuffix
+    @runnerPath = @runnerName + RUNNER_EXT
+  end
+end
+
+
+
+if File.basename($0) == File.basename(__FILE__)
+  # obtain templates for output generation
+    VERILOG_BENCH_TEMPLATE = Template.new('bench.v')
+    RUBY_BENCH_TEMPLATE = Template.new('bench.rb')
+    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: #{File.basename __FILE__} [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 '-u', '--unit', 'use Test::Unit specification format' do |val|
+      optSpecFmt = :UnitTest if val
+    end
+
+    opts.on '-r', '--rspec', 'use RSpec specification format' do |val|
+      optSpecFmt = :RSpec if val
+    end
+
+    opts.on '-n', '--name NAME', 'attach NAME indentifier to generated test' do |val|
+      optTestName = val
+    end
+
+    opts.parse! ARGV
+
+  puts "Using name `#{optTestName}' for generated test."
+  puts "Using #{optSpecFmt} specification format."
+
+
+  ModuleInfo.parse_declarations(ARGF.read).each do |moduleDecl|
+    puts
+
+    m = ModuleInfo.new(moduleDecl).freeze
+    puts "Parsed module: #{m.name}"
+
+    o = OutputInfo.new(m.name, optSpecFmt, optTestName, File.dirname(File.dirname(__FILE__))).freeze
+
+    # generate output
+      aModuleInfo, aOutputInfo = m, o
+
+      write_file o.runnerPath, RUNNER_TEMPLATE.result(binding)
+      puts "- Generated runner:           #{o.runnerPath}"
+
+      write_file o.verilogBenchPath, VERILOG_BENCH_TEMPLATE.result(binding)
+      puts "- Generated bench:            #{o.verilogBenchPath}"
+
+      write_file o.rubyBenchPath, RUBY_BENCH_TEMPLATE.result(binding)
+      puts "- Generated bench:            #{o.rubyBenchPath}"
+
+      write_file o.designPath, DESIGN_TEMPLATE.result(binding)
+      puts "- Generated design:           #{o.designPath}"
+
+      write_file o.protoPath, PROTO_TEMPLATE.result(binding)
+      puts "- Generated prototype:        #{o.protoPath}"
+
+      write_file o.specPath, SPEC_TEMPLATE.result(binding)
+      puts "- Generated specification:    #{o.specPath}"
+  end
+end

data/bin/generate_test_tpl/bench.rb

@@ -0,0 +1,31 @@
+## This is the Ruby side of the bench.
+
+require 'ruby-vpi'
+<%
+  case aOutputInfo.specFormat
+    when :UnitTest
+%>
+require 'test/unit'
+<%
+    when :RSpec
+%>
+require 'ruby-vpi/rspec'
+<%
+  end
+%>
+
+RubyVPI.init_bench '<%= aModuleInfo.name + aOutputInfo.suffix %>', :<%= aOutputInfo.protoClassName %>
+
+# service the $ruby_relay callback
+<%
+  case aOutputInfo.specFormat
+    when :UnitTest, :RSpec
+%>
+  # The <%= aOutputInfo.specFormat %> library will take control henceforth.
+<%
+  else
+%>
+  <%= aOutputInfo.specClassName + '.new' %>
+<%
+  end
+%>

data/bin/generate_test_tpl/bench.v

@@ -0,0 +1,54 @@
+<%
+  # Returns a comma-separated string of parameter declarations in Verilog module instantiation format.
+  def make_inst_param_decl(paramNames)
+    paramNames.inject([]) {|acc, param| acc << ".#{param}(#{param})"}.join(', ')
+  end
+
+  clockSignal = aModuleInfo.portNames.first
+%>
+/* This is the Verilog side of the bench. */
+
+module <%= aOutputInfo.verilogBenchName %>;
+
+  // instantiate the design under test
+<% aModuleInfo.paramDecls.each do |decl| %>
+    parameter <%= decl %>;
+<% end %>
+
+<%
+  aModuleInfo.portDecls.each do |decl|
+    { 'input' => 'reg', 'output' => 'wire' }.each_pair do |key, val|
+      decl.sub! %r{\b#{key}\b(.*?)$}, "#{val}\\1;"
+    end
+%>
+    <%= decl.strip %>
+<%
+  end
+%>
+
+    <%= aModuleInfo.name %><%
+      instConfigDecl = make_inst_param_decl(aModuleInfo.paramNames)
+
+      unless instConfigDecl.empty?
+    %>#(<%= instConfigDecl %>)<%
+      end
+
+    %><%= aOutputInfo.verilogBenchName + aOutputInfo.designSuffix %>(<%= make_inst_param_decl(aModuleInfo.portNames) %>);
+
+  // connect to the Ruby side of this bench
+    initial begin
+      <%= clockSignal %> = 0;
+      $ruby_init("ruby", "-w", "-rubygems", "<%= aOutputInfo.rubyBenchPath %>"<%=
+        %{, "-f", "s"} if aOutputInfo.specFormat == :RSpec
+      %>);
+    end
+
+    always begin
+      #5 <%= clockSignal %> = ~<%= clockSignal %>;
+    end
+
+    always @(posedge <%= clockSignal %>) begin
+      #1 $ruby_relay;
+    end
+
+endmodule

data/bin/generate_test_tpl/design.rb

@@ -0,0 +1,26 @@
+# An interface to the design under test.
+class <%= aOutputInfo.designClassName %>
+  include Vpi
+
+<% aModuleInfo.paramDecls.each do |decl| %>
+  <%= decl.strip.capitalize %>
+<% end %>
+
+  attr_reader <%=
+    aModuleInfo.portNames.inject([]) do |acc, port|
+      acc << ":#{port}"
+    end.join(', ')
+  %>
+
+  def initialize
+<% aModuleInfo.portNames.each do |port| %>
+    @<%= port %> = vpi_handle_by_name("<%= aOutputInfo.verilogBenchName %>.<%= port %>", nil)
+<% end %>
+  end
+
+  def reset!
+<% aModuleInfo.inputPortNames[1..-1].each do |port| %>
+    @<%= port %>.hexStrVal = 'x'
+<% end %>
+  end
+end

data/bin/generate_test_tpl/proto.rb

@@ -0,0 +1,8 @@
+# A prototype of the design under test.
+class <%= aOutputInfo.protoClassName %> < <%= aOutputInfo.designClassName %>
+  def simulate!
+    # read inputs
+    # simulate design's behavior
+    # produce outputs
+  end
+end

data/bin/generate_test_tpl/runner.rake

@@ -0,0 +1,28 @@
+## This file builds and runs the test.
+
+# These are source files that are to be simulated.
+SIMULATOR_SOURCES = [
+  '<%= aOutputInfo.verilogBenchPath %>',
+  '<%= aModuleInfo.name %>.v',
+]
+
+# This specifies the "top module" that is to be simulated.
+SIMULATOR_TARGET = '<%= aOutputInfo.verilogBenchName %>'
+
+# These are command-line arguments for the simulator.
+# They can be specified as a string or an array of strings.
+SIMULATOR_ARGS = {
+  # GPL Cver
+  :cver => '',
+
+  # Icarus Verilog
+  :ivl => '',
+
+  # Synopsys VCS
+  :vcs => '',
+
+  # Mentor Modelsim
+  :vsim => '',
+}
+
+require 'ruby-vpi/runner'

data/bin/generate_test_tpl/spec.rb

@@ -0,0 +1,46 @@
+## This specification verifies the design under test.
+
+<%
+  case aOutputInfo.specFormat
+    when :UnitTest
+%>
+class <%= aOutputInfo.specClassName %> < Test::Unit::TestCase
+  include Vpi
+
+  def setup
+    @design = <%= aOutputInfo.designClassName %>.new
+  end
+<% aModuleInfo.portNames.each do |param| %>
+
+  def test_<%= param %>
+  end
+<% end %>
+end
+<%
+   when :RSpec
+%>
+include Vpi
+
+context "A new <%= aOutputInfo.designClassName %>" do
+  setup do
+    @design = <%= aOutputInfo.designClassName %>.new
+    @design.reset!
+  end
+
+  specify "should ..." do
+    # @design.should ...
+  end
+end
+<%
+  else
+%>
+class <%= aOutputInfo.specClassName %>
+  include Vpi
+
+  def initialize
+    @design = <%= aOutputInfo.designClassName %>.new
+  end
+end
+<%
+  end
+%>

data/bin/header_to_ruby.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/ruby -w
+#
+# == Synopsis
+# Transforms Verilog header files into Ruby syntax.
+
+=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
+
+class String
+  # Converts this Verilog header content into Ruby syntax.
+  def to_ruby
+    content = self.dup
+
+    # remove single-line comments
+      content.gsub! %r{//(.*)$}, '#\1'
+
+    # remove multi-line comments
+      content.gsub! %r{/\*.*?\*/}m, "\n=begin\n\\0\n=end\n"
+
+    # remove preprocessor directives
+      content.gsub! %r{`include}, '#\0'
+      content.gsub! %r{`define\s+(\w+)\s+(.+)}, '\1 = \2'
+      content.gsub! %r{`+}, ''
+
+    # change numbers
+      content.gsub! %r{\d*\'([dohb]\w+)}, '0\1'
+
+    # change ranges
+      content.gsub! %r{(\S)\s*:\s*(\S)}, '\1..\2'
+
+    content
+  end
+end
+
+if File.basename($0) == File.basename(__FILE__)
+  # parse command-line options
+    require 'optparse'
+
+    opts = OptionParser.new
+    opts.banner = "Usage: #{File.basename __FILE__} [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
+
+  puts ARGF.read.to_ruby
+end

data/doc/Rakefile

@@ -0,0 +1,55 @@
+=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 'rake/clean'
+
+FORMATS = {
+  # task name => [xsltproc flag, needs resources?]
+  'html' => ['xhtml', true],
+  'text' => ['txt', false],
+}
+
+task :default => FORMATS.keys
+
+FORMATS.each_pair do |fmtName, (fmtFlag, needsResources)|
+  desc "Generate documentation in #{fmtName} format."
+  file fmtFlag => ['src/manual.xml', 'src/manual.xsl'] do |t|
+    sh %{xmlto #{fmtFlag} -o #{fmtFlag} -m #{t.prerequisites[1]} #{t.prerequisites[0]}}
+  end
+
+  CLOBBER.include fmtFlag
+
+  task fmtName => fmtFlag
+
+  # copy additional resources to output directory
+    if needsResources
+      FileList['src/*/'].each do |path|
+        dst = File.join(fmtFlag, File.basename(path))
+
+        file dst => [path, fmtFlag] do
+          cp_r path, dst
+        end
+
+        CLEAN.include dst
+
+        task fmtName => dst
+      end
+    end
+end