ruby-vpi 7.3.0 → 8.0.0

data/HEADER

@@ -9,8 +9,9 @@ Ruby-VPI is a "Ruby interface":http://ruby-lang.org to "Verilog VPI":http://ieee
 h2. Features
 
 * Prototype and verify designs _quickly_ using "BDD(behavior-driven development)":http://behaviour-driven.org/, "TDD(test-driven development)":http://www.agiledata.org/essays/tdd.html, and more.
-* Specifications are executable _and_ human-readable. (See this <a href="./doc/usage.tutorial.html#fig..counter_rspecTest_spec.rb">example specification</a> and its <a href="./doc/usage.tutorial.html#fig..test-proto.rspec">boss-friendly output</a>.)
 * Reuse the _same_ specification to verify both prototype and design.
+* Specifications are executable _and_ human-readable. (See this <a href="./doc/usage.tutorial.html#fig..counter_rspecTest_spec.rb">example specification</a> and its <a href="./doc/usage.tutorial.html#fig..test-proto.rspec">boss-friendly output</a>.)
+
 
 * Utilize Ruby's power and elegance. ("Why choose Ruby?":http://www.ruby-doc.org/whyruby)
 ** Built-in support for unlimited length integers, regular expressions, networking, multi-threading, system calls, _ad infinium_!
@@ -38,7 +39,16 @@ h2. Features
 </span>
 </dt>
 <dd>
-<p>Complete documentation for users. Start here!</p>
+<p>Complete documentation for users. _Start here!_</p>
+</dd>
+
+<dt>
+<span class="term">
+<a href="./ref/" target="_top">Reference</a>
+</span>
+</dt>
+<dd>
+<p>API reference documentation for Ruby libraries and C extension.</p>
 </dd>
 
 <dt>
@@ -53,9 +63,10 @@ Access project facilities, hosted generously by <a href="http://rubyforge.org" t
 RubyForge</a>.
 </p>
 </dd>
+
 <dt>
 <span class="term">
-<a href="http://rubyforge.org/projects/ruby-vpi" target="_top">
+<a href="http://rubyforge.org/tracker/?group_id=1339" target="_top">
 Tracker</a>
 </span>
 </dt>
@@ -63,6 +74,7 @@ Tracker</a>
 <p>
 Report problems, contribute patches, and more.</p>
 </dd>
+
 <dt>
 <span class="term">
 <a href="http://rubyforge.org/frs/?group_id=1339" target="_top">
@@ -73,9 +85,10 @@ Releases</a>
 <p>
 Download the newest releases.</p>
 </dd>
+
 <dt>
 <span class="term">
-<a href="http://rubyforge.org/scm/?group_id=1339" target="_top">
+<a href="http://ruby-vpi.rubyforge.org/src/ruby-vpi" target="_top">
 Sources</a>
 </span>
 </dt>
@@ -83,6 +96,7 @@ Sources</a>
 <p>
 Browse or access the source code repository.</p>
 </dd>
+
 <dt>
 <span class="term">
 <a href="http://rubyforge.org/forum/?group_id=1339" target="_top">
@@ -93,6 +107,7 @@ Forums</a>
 <p>
 Ask for help, give feedback, or discuss.</p>
 </dd>
+
 </dl>
 </div>
 </div>

data/HISTORY

@@ -12,11 +12,44 @@ We _strictly_ follow the RubyGems project's "rational versioning policy":http://
 fn1. C. Gross, "Explaining Open Source Version Numbers", [Online document], 2005 Nov 28, [cited 2006 Aug 27], Available HTTP: "http://ablog.apress.com/?p=738":http://ablog.apress.com/?p=738
 
 
+h1. Version 8.0.0 (2006-10-13)
+
+h2. Summary
+
+This release renames some identifiers for consistency, updates the documentation, and improves integration with RubyGems.
+
+h2. Notice
+
+* The @RubyVPI@ module has been renamed to @RubyVpi@.
+
+* The @PROTO@ environment variable has been renamed to @PROTOTYPE@.
+** In addition to using @unset@, you can now disable simulation of the prototype by assigning an empty value to this variable.
+
+h2. Details
+
+* We now use "Darcs":http://darcs.net for revision control, instead of Subversion. The source repository can now be accessed at "http://ruby-vpi.rubyforge.org/src/ruby-vpi":http://ruby-vpi.rubyforge.org/src/ruby-vpi.
+
+* The source code is now distributed in tar.gz and zip form, in addition to gem.
+
+* Some identifiers have been renamed for better consistency.
+
+* The user manual now resides directly within the @doc/@ directory.
+** The integration of documentation in @gem_server@ has been improved.
+
+* The glossary and tutorial in the user manual have been revised.
+
+
 h1. Version 7.3.0 (2006-09-30)
 
 h2. Summary
 
-This release fixes a bug in generated Verilog benches and adds parsed constants to generated Verilog benches and Ruby designs.
+This release fixes a bug in generated Verilog benches, includes parsed constants in generated tests, and adds new methods to handles.
+
+h2. Notice
+
+* Handles now have two new methods:
+** @handle.x?@ -- checks if the logic value is "don't care"
+** @handle.z?@ -- checks if the logic value is high impedance
 
 h2. Details
 

data/MEMO

@@ -13,8 +13,6 @@ h1. Pending tasks
 * GHDL simulator supports VPI
 ** need way to invoke VPI tasks from VHDL, like @$ruby_init();@
 
-* smarter test generation, which adjusts to user modifications in previously generated output
-
 
 h1. Finished tasks
 
@@ -40,3 +38,5 @@ h1. Obsolete tasks
 
 * file bug report for Icarus 0.8 (l0_dcache)
 ** try new icarus snapshot
+
+* smarter test generation, which adjusts to user modifications in previously generated output -- just use a smart merging tool like *kdiff3*

data/README

@@ -1,9 +1,22 @@
 h1. Getting started
 
-* See the "user manual":./doc/xhtml to begin using Ruby-VPI.
+* See the "user manual":./doc to begin using Ruby-VPI.
 
 * See the "release history":./history.html to see what is new in this release.
 
 * See API documentation for the "C extension":./ref/c or "Ruby-VPI libraries":./ref/ruby.
 
 * Visit the "project website":http://ruby-vpi.rubyforge.org for additional resources.
+
+
+h1. Compiling from source
+
+In addition to the "normal requirements":./doc/usage.requirements.html, you need the following software to compile from source:
+
+* "DocBook-XML":http://www.docbook.org/
+** xsltproc
+** xmlto
+* "RedCloth":http://rubyforge.org/projects/redcloth/
+* "SWIG":http://www.swig.org/
+
+Once you have satisfied these requirements, you can run @rake release@ to build the release packages. Also, see the output of @rake -T@ for more build options.

data/Rakefile

@@ -20,6 +20,7 @@
 
 require 'rake/clean'
 require 'rake/rdoctask'
+require 'rake/gempackagetask'
 
 require 'tempfile'
 require 'rbconfig'
@@ -35,6 +36,9 @@ PROJECT_SUMMARY = "Ruby interface to Verilog VPI."
 PROJECT_DETAIL = "#{PROJECT_NAME} is a #{PROJECT_SUMMARY}. It lets you create complex Verilog test benches easily and wholly in Ruby."
 PROJECT_SSH_URL = "snk@rubyforge.org:/var/www/gforge-projects/#{PROJECT_ID}"
 
+File.read('HISTORY') =~ /Version\s+([\d\.]+)\s*\((.*?)\)/
+PROJECT_VERSION = $1
+PROJECT_BIRTHDAY = $2
 
 
 # Returns a temporary, unique path ready for use. No file exists at the returned path.
@@ -43,23 +47,9 @@ def generate_temp_path
   path
 end
 
-# uploads the given sources without their SVN meta-data to the given destination URL
-def upload_without_svn aDestUrl, *aSources
-  tmpDir = generate_temp_path
-  mkdir tmpDir
-
-  tmpSources = aSources.map do |src|
-    cp_r src, tmpDir, :preserve => true
-    File.join(tmpDir, File.basename(src))
-  end
-
-  # remove SVN meta-data from sources
-    sh "find #{tmpDir} -name .svn | xargs rm -rf"
-
-  # upload sources
-    sh 'scp', '-Cr', *(tmpSources + [aDestUrl])
-
-  rm_rf tmpDir
+# uploads the given sources to the given destination URL
+def upload aDestUrl, *aSources
+  sh 'scp', '-Cr', aSources, aDestUrl
 end
 
 
@@ -67,7 +57,8 @@ end
 task :default => :build
 
 task :clobber do |t|
-  files = FileList['**/Rakefile'].reject {|f| File.expand_path(f) == __FILE__}
+  files = FileList['**/Rakefile'].exclude('_darcs')
+  files.shift # avoid infinite loop on _this_ file
 
   files.each do |f|
     cd File.dirname(f) do
@@ -208,21 +199,21 @@ end
 
 
 desc 'Publish documentation to website.'
-task :web => [:web_dist, :web_ref, :web_doc]
+task :web => [:web_info, :web_ref, :web_doc]
 
 desc "Publish distribution info."
-task :web_dist => ['style.css', *distDocs] do |t|
-  upload_without_svn PROJECT_SSH_URL, *t.prerequisites
+task :web_info => ['style.css', *distDocs] do |t|
+  upload PROJECT_SSH_URL, *t.prerequisites
 end
 
 desc "Publish reference documentation."
 task :web_ref => 'ref' do |t|
-  upload_without_svn PROJECT_SSH_URL, *t.prerequisites
+  upload PROJECT_SSH_URL, *t.prerequisites
 end
 
 desc "Publish user documentation."
 task :web_doc => :doc do |t|
-  upload_without_svn "#{PROJECT_SSH_URL}/doc/", *FileList['doc/xhtml/*']
+  upload PROJECT_SSH_URL, *t.prerequisites
 end
 
 desc 'Connect to website FTP.'
@@ -232,56 +223,38 @@ end
 
 
 desc "Generate release packages."
-task :pkg => ['HISTORY', 'gem_extconf.rb'] do |t|
-  # determine release version
-    File.read(t.prerequisites[0]) =~ /Version\s+([\d\.]+)/
-    releaseVersion = $1
-    puts "release version is: #{releaseVersion}"
-
-  mkdir tmpDir = generate_temp_path
-  cp_r '.', tmpDir
-
-  cd tmpDir do
-    # clean up
-      sh "svn st | awk '/^\\?/ {print $2}' | xargs rm -rf"
-      sh "svn up"
-      sh "find -name .svn | xargs rm -rf"
-
-    sh "rake dist"
-
-    # make gem package
-      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 = releaseVersion
-
-        s.add_dependency 'rspec', '>= 0.5.4'
-        s.add_dependency 'rake', '>= 0.7.0'
-        s.add_dependency 'rcov', '>= 0.7.0'
-
-        s.requirements << "POSIX threads library"
-        s.requirements << "C language compiler"
-
-        s.files = FileList['**/*']
-        s.autorequire = PROJECT_ID
-        s.executables = FileList['bin/*'].select {|f| File.executable?( f ) && File.file?( f )}.map {|f| File.basename f}
-        s.extensions << t.prerequisites[1]
-      end
+task :release => [:clobber, :dist] do
+  sh 'rake package'
+end
 
-      Gem::manage_gems
-      Gem::Builder.new(spec).build
+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
 
-      mv *(FileList['*.gem'] << File.dirname(__FILE__))
-  end
+  s.add_dependency 'rspec', '>= 0.5.4'
+  s.add_dependency 'rake', '>= 0.7.0'
+  s.add_dependency 'rcov', '>= 0.7.0'
+
+  s.requirements << "POSIX threads library"
+  s.requirements << "C language compiler"
+
+  s.files = FileList['**/*'].exclude('_darcs')
+  s.autorequire = PROJECT_ID
+  s.executables = FileList['bin/*'].select {|f| File.executable?( f ) && File.file?( f )}.map {|f| File.basename f}
+  s.extensions << 'gem_extconf.rb'
+end
 
-  rm_r tmpDir
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
 end
 
 
 desc "Configures the gem during installation."
-task :config_gem_install => 'readme.html' do |t|
+task :gem_config_inst => 'readme.html' do |t|
   # make documentation available to gem_server
     gemDir = File.dirname(__FILE__)
     gemName = File.basename(gemDir)

data/bin/generate_test.rb

@@ -1,25 +1,7 @@
 #!/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.
+# Generates Ruby-VPI tests from Verilog 2001 module declarations.
+# * If no input files are specified, then the standard input stream is assumed to be the input.
+# * The first input signal 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
@@ -119,7 +101,7 @@ class OutputInfo
     @specPath = @specName + RUBY_EXT
 
     @designClassName = aModuleName.to_ruby_const_name
-    @protoClassName = @designClassName + 'Proto'
+    @protoClassName = @designClassName + 'Prototype'
     @specClassName = @specName.to_ruby_const_name
 
     @runnerName = aModuleName + @runnerSuffix
@@ -170,7 +152,7 @@ if File.basename($0) == File.basename(__FILE__)
 
     opts.parse! ARGV
 
-  puts "Using name `#{optTestName}' for generated test."
+  puts "Using name #{optTestName.inspect} for generated test."
   puts "Using #{optSpecFmt} specification format."
 
 

data/bin/generate_test_tpl/bench.rb

@@ -14,7 +14,7 @@ require 'ruby-vpi/rspec'
   end
 %>
 
-RubyVPI.init_bench '<%= aModuleInfo.name + aOutputInfo.suffix %>', :<%= aOutputInfo.protoClassName %>
+RubyVpi.init_bench '<%= aModuleInfo.name + aOutputInfo.suffix %>', :<%= aOutputInfo.protoClassName %>
 
 # service the $ruby_relay callback
 <%

data/bin/generate_test_tpl/bench.v

@@ -26,10 +26,10 @@ module <%= aOutputInfo.verilogBenchName %>;
       instConfigDecl = make_inst_param_decl(aModuleInfo.parameters)
 
       unless instConfigDecl.empty?
-    %>#(<%= instConfigDecl %>)<%
+      %>#(<%= instConfigDecl %>)<%
       end
 
-    %><%= aOutputInfo.verilogBenchName %>_design(<%= make_inst_param_decl(aModuleInfo.ports) %>);
+    %> <%= aOutputInfo.verilogBenchName %>_design(<%= make_inst_param_decl(aModuleInfo.ports) %>);
 
   // connect to the Ruby side of this bench
     initial begin

data/bin/generate_test_tpl/proto.rb

@@ -1,8 +1,13 @@
 # A prototype of the design under test.
 class <%= aOutputInfo.protoClassName %> < <%= aOutputInfo.designClassName %>
   def simulate!
-    # read inputs
-    # simulate design's behavior
-    # produce outputs
+    # discard old outputs
+<% aModuleInfo.ports.reject { |p| p.input? }.each do |port| %>
+      @<%= port.name %>.hexStrVal = 'x'
+<% end %>
+
+    # process new inputs
+
+    # produce new outputs
   end
 end

data/bin/header_to_ruby.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/ruby -w
-#
-# == Synopsis
-# Transforms Verilog header files into Ruby syntax.
+# Transforms Verilog header files into Ruby.
+# * If no input files are specified, then the standard input stream is assumed to be the input.
+# * The resulting output is emitted to the standard output stream.
 
 =begin
   Copyright 2006 Suraj N. Kurapati

data/doc/Rakefile

@@ -21,35 +21,18 @@
 require 'rake/clean'
 
 FORMATS = {
-  # task name => [xsltproc flag, needs resources?]
-  'html' => ['xhtml', true],
-  'text' => ['txt', false],
+  # format => xsltproc flag
+  'html' => 'xhtml',
+  'text' => 'txt',
 }
 
 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]}}
+FORMATS.each_pair do |fmt, flag|
+  desc "Generate documentation in #{fmt} format."
+  task fmt => ['src/manual.xml', 'src/manual.xsl'] do |t|
+    sh %{xmlto #{flag} -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
+
+CLOBBER.include '*.html', '*.txt'