verilog_gen 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6704b1a822e219b49e5f613a69d19a068810b62
-  data.tar.gz: 717d1f7e1ed314da94394d46ae698253c6c955e3
+  metadata.gz: b1e2281d2daf631007d3ed1204c712bbdf24f6d8
+  data.tar.gz: 4a858282aaacc79cd2309f05b3d97083ad301438
 SHA512:
-  metadata.gz: 081b28ce4d838b57a8cf8cce2d3bd13646a0a596f94b2612e6d616585ca9dcbd7fd8d11fbe54768b0d82c5ed116e5ba43b1f243e3de139178beeb6b68eea48e9
-  data.tar.gz: 43a1dd83ad58d83fe6e65f476d29ac13721f1c5d918cbdf80e36e082c2e7011e65e2b1786050e0d0b5fb7173d8eed6733033e67d7b9af096b57dbb44450a6c4a
+  metadata.gz: df11fbfda6ee4d390b7c5698c95cf619d0a778ee5dfd6d8c11a02cc128f1bb464b6a5636ec99968df0001fe2d455aed2b7b6bbf97cd6176a174f9fba83af5309
+  data.tar.gz: 5c5369b66f49fa986a16977770387c9cc7fd6a02a0b82d225afb9ce0cda8076e5cc70652a103bcd4bf5caa84c835e77f07ca4546c0071f52b65aa6c1e04b43b9

data/Gemfile

@@ -1,6 +1,10 @@
 source 'https://rubygems.org'
 
 ruby '2.0.0'
+group :development do
+  gem 'yard'
+end
+
 group :test do
   gem 'rspec'
   gem 'cucumber'

data/README.md

@@ -1,6 +1,27 @@
 # VerilogGen
 
-TODO: Write a gem description
+Allows the user to declaratively create a verilog design. Using this tool
+the user can create a logical model of the design. running the script will
+render the logical view of the design. 
+Then for creating different views of the design (corresponding to different
+chips, technologies, ...etc) the user inherits from the logical model. It 
+manipulates the logical instance hierarchy by adding/deleting/swapping the 
+modules. It then calls the 'vgen' script which creates the ports of the 
+modules due to the change.
+
+To render it the script uses a default erb template. It is possible for the
+user to use a custom template to insert custom system verilog logic.
+
+Create a class HdlModule that corresponds to a verilog module. The class
+HdlModule knows the ports and the instances of the design. The script vgen
+can create the ports of the design by using the following  default rule.
+A. if there are multiple outputs then it is a primary output whose width
+   is the sum of all the busses.
+B. If there is one output then it is an internal wire.
+C. If there is 0 output then it is an primary input. The width of the port
+   is the largest width of the input pin.
+   If the user actually wanted the inputs to form a sub bus then user
+   would connect the ports to the pin manually.
 
 ## Installation
 

data/Rakefile

@@ -1 +1,21 @@
 require "bundler/gem_tasks"
+require "cucumber/rake/task"
+require "rspec/core/rake_task"
+require 'yard'
+
+# Generate documentation
+YARD::Rake::YardocTask.new
+
+# Passing vscan tests. 
+# Ignore all work in progress (wip) and those under debug (jsd)
+Cucumber::Rake::Task.new('vscan_test') do |task|
+  task.cucumber_opts = ["-r features", "features/vscan", " --tags ~@wip"]
+end
+
+# Run the vscan tests which are not yet implemented.
+Cucumber::Rake::Task.new('vscan_wip') do |task|
+  task.cucumber_opts = ["-r features", "features/vscan", " --tags @wip"]
+end
+
+# Run the rspec tests.
+RSpec::Core::RakeTask.new(:spec)

data/bin/hdl_equal

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+# Compare the equality of 2 hdl module classes.
+# The 2 classes are in separate files.
+
+require 'pp'
+
+if ARGV.size != 2
+  puts "error: you must specify 2 ruby hdl modules to compare."
+  exit 1
+end
+
+$LOAD_PATH.unshift File.expand_path("../../lib")
+$LOAD_PATH.unshift File.expand_path("../lib")
+
+require_relative "../lib/verilog_gen"
+
+# Evaluate the class in 2 separate namespaces
+# @return [Array] List of all derived class of hdl modules
+def create_hdl_classes(ns, filename)
+  content = File.open(filename).read 
+  eval """
+  module #{ns}
+    require 'verilog_gen' 
+    # Hook to detect a subclass
+    class VerilogGen::HdlModule
+      @instances = []
+      def self.inherited(new_subclass)
+        @instances << new_subclass
+      end
+      def self.get
+        @instances
+      end
+    end
+    #{content}
+  end
+  """, binding, __FILE__, __LINE__
+  return VerilogGen::HdlModule.get
+end
+
+module Lhs; end
+module Rhs; end
+
+lhs = create_hdl_classes(Lhs, ARGV[0])
+rhs = create_hdl_classes(Rhs, ARGV[1])
+
+if lhs.size == 0
+  puts "No Hdl Module detected in source file:#{ARGV[0]}"
+  exit 1
+end
+
+if rhs.size == 0
+  puts "No Hdl Module detected in source file:#{ARGV[1]}"
+  exit 1
+end
+
+if lhs.size != rhs.size 
+  puts "Number of entries #{lhs.size} on #{ARGV[0]} do not match
+                          #{rhs.size} entries in #{ARGV[1]}"
+  exit 1
+end
+
+lhs.each_index do |i|
+  if lhs[i].ports  == rhs[i].ports \
+    && lhs[i].child_instances == rhs[i].child_instances \
+    && lhs[i].module_name == rhs[i].module_name \
+    && lhs[i].proxy == rhs[i].proxy \
+    && lhs[i].file_name == rhs[i].file_name \
+    && lhs[i].parameters == rhs[i].parameters
+    exit 0 
+  else
+    puts "Mismatched ports" unless lhs[i].ports == rhs[i].ports    
+    puts "Mismatched child" unless lhs[i].child_instances == rhs[i].child_instances
+    puts "Mismatched mdule_name" unless lhs[i].module_name == rhs[i].module_name
+    puts "Mismatched proxy " unless lhs[i].proxy == rhs[i].proxy
+    puts "Mismatched file_name. Expect=#{lhs[i].file_name}, \
+      Got=#{rhs[i].file_name}" unless lhs[i].file_name == rhs[i].file_name
+    puts "Mismatched parameters:#{lhs[i].parameters}:#{rhs[i].parameters}" \
+          unless lhs[i].parameters == rhs[i].parameters
+    exit 1
+  end
+end

data/bin/vgen

@@ -1,2 +1,58 @@
 #!/usr/bin/env ruby
-puts "Verilog Rtl Generator"
+require 'pp'
+require 'optparse'
+require 'fileutils'
+
+# FIXME: Required till we install the gem
+$LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib")
+
+# By default load the build directory
+$LOAD_PATH.unshift("#{FileUtils.pwd}/build")
+
+require 'verilog_gen'
+
+options = {}
+option_parser = OptionParser.new do |opts|
+  executable_name = File.basename($PROGRAM_NAME)
+  opts.banner = "Verilog RTL Generator
+
+    Usage: #{executable_name} [options] ruby_build_script
+  "
+  opts.on("-t top", "--top", "top level class name") do |top|
+    options[:top_class_name] =  top
+  end
+  opts.on("-o outdir", "--outdir", "output directory name") do |outdir|
+    options[:output_dirname] = outdir
+    FileUtils.mkdir_p outdir
+  end
+end
+
+option_parser.parse!
+unless options.key?(:top_class_name)
+  puts "error: you must supply the top level class name."
+  exit 1
+end
+
+options[:output_dirname] = "." unless options.key?(:output_dirname)
+
+if ARGV.empty?
+  puts "error: you must supply the ruby build script."
+  exit 1
+else
+  eval(File.open(ARGV[0]).read)
+  klass = Object.const_get(options[:top_class_name])
+  
+  # Connect the ports and pins
+  VerilogGen.hookup klass
+
+  # Write out all the subclasses of hdl modules.
+  VerilogGen::HdlModule.get_subclasses.each do |sub_class|
+    unless sub_class.proxy
+      output_file = "#{options[:output_dirname]}/#{sub_class.module_name}.v"
+      File.open(output_file, 'w') do |fh|
+        fh.write(sub_class.render)
+      end
+    end
+  end
+end
+

data/bin/vscan

@@ -0,0 +1,354 @@
+#!/usr/bin/perl
+## ----------------------------------------------------------------------
+## This script converts a verilog file into a ruby includable file which
+## contains the structure which defines the module definition of the given
+## verilog file.
+##
+##  Input:  Path to the verilog file
+##          Parameter override declarations in format PARAM1=value
+##          Class override declared using -class flag
+##  Output: File in same directory as verilog file named <module>.rb
+##          or <class_override>.rb if -class flag specified.
+##
+##  Examples:
+##     vscan subdir1/leaf.v
+##     vscan PARAM1=7 PARAM2=9 leaf.v
+##     vscan -class trunk leaf.v
+## ----------------------------------------------------------------------
+
+require 5.005;
+use FindBin qw($RealBin);
+use lib "$RealBin/blib/arch";
+use lib "$RealBin/blib/lib";
+use lib "$RealBin";
+use File::Basename;
+
+use Verilog::Netlist;
+use strict;
+
+my $VERSION = "0.4.0";
+my %PARAMETERS;
+my $class_override = "";
+my $verilog_file = "";
+
+while( @ARGV ) {
+    my $option = shift @ARGV;
+    if( $option =~ /=/ ) {
+        ## A parameter is potentially being overwritten
+        (my $parameter, my $value) = split( /=/, $option, 2 );
+        $PARAMETERS{$parameter} = $value;
+    }
+    elsif( $option eq "-class" ) {
+        die "error: you can't specify more than one class overide.\n" if( $class_override );
+        $class_override = shift @ARGV;
+    }
+    else {
+        die "error: too many command line arguments.\n" if( $verilog_file );
+        $verilog_file = $option;
+    }
+}
+die "error: you must supply a leaf verilog module.\n" unless( $verilog_file );
+die "error: file $verilog_file does not exist.\n" unless( -f $verilog_file );
+
+## And then process the Verilog file
+&Convert_Verilog_To_Ruby( $class_override, $verilog_file );
+exit(0);
+
+## --------------------------------------------------
+## Parse a verilog file and convert it into a ruby executable
+## that contains the structure which described the Verilog module's
+## declaration state
+sub Convert_Verilog_To_Ruby {
+    my $class_override = shift @_;
+    my $in_file = shift @_;
+
+    ## Prepare for reading in verilog netlists
+    my $netlist = new Verilog::Netlist();
+    $netlist->read_file( filename=>$in_file );
+
+    ## And print any startup text needed
+    &Print_Header($VERSION);
+
+    ## Set the class to the override value, and then fix it later if
+    ## it wans't overridden:
+    my $class = $class_override;
+
+    ## Process all module declarations in the Verilog file
+    foreach my $module ($netlist->modules_sorted) {
+
+        ## Add the module name and class
+        $class = $module->name unless( $class_override );
+
+        &Print_Module($in_file, $class, $module->name);
+
+        ## Add override parameters
+        &Print_Parameters($module);
+    
+        ## And information for each port
+        foreach my $port ($module->ports_sorted) {
+	    ## if an 'interface', the port->direction is "interface"
+	    (my $type, my $packed, my $unpacked) = &Parse_Port($port->data_type, $port->array, $module);
+	    &Print_Port($port->name, $port->direction, $type, $packed, $unpacked);
+        }
+        
+        ## Finish with any text required to end file creation
+        &Print_Trailer();
+    }
+
+    ## Process all interface declarations in the Verilog file
+    foreach my $interface ($netlist->interfaces_sorted) {
+
+	## Start printing the class information for the interface
+        $class = $interface->name unless( $class_override );
+	&Print_Interface($in_file, $class, $interface->name);
+
+        ## Add override parameters
+        &Print_Parameters($interface);
+    
+        ## And 'port' information for each interface
+        foreach my $port ($interface->ports_sorted) {
+	    (my $type, my $packed, my $unpacked) = &Parse_Port($port->data_type, $port->array, $interface);
+	    &Print_Port($port->name, $port->direction, $type, $packed, $unpacked);
+        }
+        
+        ## Finish with any text required to end file creation
+        &Print_Trailer();
+    }
+        
+    return;
+}
+
+## --------------------------------------------------
+## A function to parse a port to determine the type of the
+## port, the packed portion of a vector declaration and the
+## unpacked portion of an array declaration.
+sub Parse_Port {
+    my $packed_string = shift @_;
+    my $unpacked_string = shift @_;
+    my $module = shift @_;
+    my $type;
+    my $packed = "";
+    my $unpacked = "";
+
+    ## Remove Verilog comments if any
+    $packed_string =~ s/\/\/.*$//;
+
+    ## First determine the type
+    if( $packed_string =~ /^(.*?)\[/ ) {
+	$type = $1;
+	$type =~ s/\s+//g;
+    }
+    else {
+	## Remove white spaces
+	$packed_string =~ s/\s+//g;
+	$type = $packed_string;
+    }
+    $type = "wire" if( $type eq "" ); ## default to wire if not specified
+
+    if( $packed_string =~ /:/ ) {
+        ## reg, wire, logic, bit:
+	## vector containing parameters, mathematical functions, etc.
+	while( $packed_string =~ /\[/ ) {
+	    $packed_string =~ s/^(.*?)\[//; ## strip everything up to and including [
+	    (my $substr, $packed_string) = split( /\]/, $packed_string, 2 ); ## Get all to the left of first ]
+	    ## Break into the LHS and RHS (of the colon)
+	    (my $lhs, my $rhs) = split( /:/, $substr, 2 );
+	    ## Convert each side into a numerical value
+	    $lhs = &Resolve_Expression( $lhs, $module );
+	    $rhs = &Resolve_Expression( $rhs, $module );
+	    $packed .= "[$lhs:$rhs]";
+	}
+    } else {
+        ## reg, wire, logic, bit: single-bit
+    }
+
+    ## And then handle the unpacked (array) portion of the signal
+    ## Remove Verilog comments if any
+    $unpacked_string =~ s/\/\/.*$//;
+
+    while( $unpacked_string =~ /\[/ ) {
+	$unpacked_string =~ s/^(.*?)\[//; ## strip everything up to and including [
+	(my $substr, $unpacked_string) = split( /\]/, $unpacked_string, 2 ); ## Get all to the left of first ]
+	## Break into the LHS and RHS (of the colon)
+	(my $lhs, my $rhs) = split( /:/, $substr, 2 );
+	## Convert each side into a numerical value
+	$lhs = &Resolve_Expression( $lhs, $module );
+	$rhs = &Resolve_Expression( $rhs, $module );
+	$unpacked .= "[$lhs:$rhs]";
+    }
+
+    return( $type, $packed, $unpacked );
+}
+
+## --------------------------------------------------
+## Function to replace parameters in a string and then
+## evaluate the mathematical result of the string post
+## parameter replacement.
+sub Resolve_Expression {
+    my $string = shift @_;
+    my $module = shift @_;
+
+    ## Split the string on interesting Verilog supported mathematical operators
+    ##   (which are: **, *, +, -, /, %, (, ) ).  Note, $clog() is supported deeper
+    ##   in the code below.
+    my @ITEMS = split( /(\*+|\+|\-|\/|\%|\(|\))/, $string );
+    ## Then substitute parameters with values (i.e., if one of
+    ## the items returned by the 'split' above is a defined
+    ## parameter, replace it in the array with the parameters value:
+    for( my $i=0; $i<=$#ITEMS; ++$i ) {
+        ## Is there an override of item from the command line?
+        ## if so, replace with the override value instead
+        if( $PARAMETERS{$ITEMS[$i]} ) {
+            ## Use override value
+            $ITEMS[$i] = $PARAMETERS{$ITEMS[$i]};
+        }
+	elsif( $ITEMS[$i] eq "\$clog2" ) {
+	    ## Else, check if the item is a special Verilog function call:
+	    ## Replace verilog log-base-2 function call with local version
+	    $ITEMS[$i] = "&Log2";
+	}
+        else {
+            ## Else, check if there there is a net matching the text 'name' of the item?
+            my $net = $module->find_net($ITEMS[$i]);
+            ## If so, replace the item with the value of the net (parameter)
+	    if( $net ) {
+		## The value (for paremeters) might themselves be complex expressions
+		## that need to be evaluated, call this function recursively before
+		## proceeding:
+		$ITEMS[$i] = &Resolve_Expression( $net->value, $module );
+	    }
+        }
+	## Else, the item is either a number, mathematical operator, or something
+	## that is not supported.  Leave it unchanged.
+    }
+    ## Then evaluate the resultant string as a mathematical function.  This will return
+    ## a NULL value if the evaluation fails (due to unsupported stuff in expression):
+    ## Because this is a PERL EVAL, the &Log2 function call that was placed in the expression
+    ## will calculate using the Log2 subroutine located in this program.
+    my $result = eval( join( "", @ITEMS ) );
+    die "error: I/O declaration using undefined parameter.\n" unless( $result ne "" );
+
+    return($result);
+}
+
+## --------------------------------------------------
+## Ruby file header text
+sub Print_Header {
+    print "# vscan v${VERSION}\n";
+    print "\n";
+    return;
+}
+
+## --------------------------------------------------
+## Ruby file module name processing
+sub Print_Module {
+    my $src_file = shift @_;
+    my $class_name = shift @_;
+    my $module_name = shift @_;
+    print "# --------------------------------------------------\n";
+    ## Make sure class name is all lower case with first letter capitalized
+    $class_name =~ tr/A-Z/a-z/;
+    $class_name = ucfirst( $class_name );
+    my $file_name = basename($src_file);
+    print "class $class_name < VerilogGen::HdlModule\n";
+    print "  set_proxy true\n";
+    print "  set_file_name \"${file_name}\"\n";
+    print "  set_module_name \"${module_name}\"\n";
+
+    return;
+}
+
+## --------------------------------------------------
+## Ruby file module name processing
+sub Print_Interface {
+    my $src_file = shift @_;
+    my $class_name = shift @_;
+    my $interface_name = shift @_;
+    print "\n";
+    print "# --------------------------------------------------\n";
+    ## Make sure classs name is all lower case with first letter capitalized
+    $class_name =~ tr/A-Z/a-z/;
+    $class_name = ucfirst( $class_name );
+    print "class $class_name < VerilogGen::HdlInterface\n";
+    print "  set_proxy true\n";
+    print "  set_file_name \"${src_file}\"\n";
+    print "  set_interface_name \"${interface_name}\"\n";
+
+    return;
+}
+
+## --------------------------------------------------
+## Print out override parameters specified on the command line
+sub Print_Parameters {
+    my $object = shift @_;
+
+    foreach my $override (sort keys %PARAMETERS) {
+	my $net = $object->find_net($override);
+	if( $net ) {
+	    print "  set_parameter ${override}: " . $PARAMETERS{$override} . "\n" if( $net->decl_type eq "parameter" );
+	}
+    }
+
+    return;
+}
+
+## --------------------------------------------------
+## Ruby file port data type processing
+sub Print_Port {
+    my $port_name = shift @_;
+    my $port_dir = shift @_;
+    my $port_type = shift @_;
+    my $packed_string = shift @_;
+    my $unpacked_string = shift @_;
+
+    ## Convert the port direction into a proper string
+    $port_dir = "input" if( $port_dir eq "in" );
+    $port_dir = "output" if( $port_dir eq "out" );
+    ## if 'inout', already in correct format
+
+    if( $port_dir eq "interface" ) {
+	print "  add_interface \"${port_name}\", type: \"${port_type}\"\n";
+    }
+    else {
+	## Print out the line of interest
+	print "  add_port \"${port_name}\", direction: \"${port_dir}\", type: \"${port_type}\"";
+	
+	## Print out the packed side of the array and unpacked side of the array if they exist
+	print ", packed: \"${packed_string}\"" if( $packed_string );
+	print ", unpacked: \"${unpacked_string}\"" if( $unpacked_string );
+	
+	## Finish with carriage return
+	print "\n";
+    }
+
+    return;
+}
+
+## --------------------------------------------------
+## Ruby file trailer text
+sub Print_Trailer {
+    print "end\n";
+    print "\n";
+
+    return;
+}
+
+## --------------------------------------------------
+## Log2 function used for signal vector resolution.  In order to
+## match verilog, round up the answer
+sub Log2 {
+    my $operand = shift @_;
+    my $result = &RoundUp( log($operand)/log(2) );
+
+    return( $result );
+}
+
+## --------------------------------------------------
+## Helper function to round up a value
+sub RoundUp {
+    my $n = shift @_;
+    my $n_roundedup = ($n==int($n)) ? $n : int($n+1);
+
+    return( $n_roundedup );
+}
+