rvvm 0.9.2 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfe48fe0908436378978c1f713512eef964526caa955f0c20d6c63b866d5bcac
-  data.tar.gz: 6d197fb0b236b3a8bde5c058db531593e551b97a6c8b71429c7aa302061d5d68
+  metadata.gz: 23fecb22e1dceb684c808440d5d88e14e288e3001287a50435acfa57baedad5c
+  data.tar.gz: 88b6836f137f99529ba872045ab934cc618fcf71420e674117a0856b225dce63
 SHA512:
-  metadata.gz: ec6fe8c155ffa528e13b0c443e8361b648fb5ab94e3230e6257fad0c10a16fa338e53cbda53b57b83186902fcb9aa03c486609e73a04fc4d8b51a5ab86542fa9
-  data.tar.gz: bd555309f858e5bb274b03cdd929bbbbbac26042e634e9812a8f974c524d82a603cd735bfc9d4e01a2dd468d9245eab7534be4ce749833e84e7918929369bb8f
+  metadata.gz: 3197267e3a5f1f713167837ed16ff1410d7aea0429e031c60a78cd3f85b4aea88b200c0bcbe5bd2174de75182119fff227d08bc79eaff720c73654d2f095e6ae
+  data.tar.gz: 36f3c3f230eb785626b16f8b6200bd0277fe7635eec3982f6ef1fe2bf0ee7346fa531b7ee740cd987f8428c5cda7c2d73bc25370b0ef19ea014797b1fca4cdd9

data/CHANGELOG.md

@@ -47,16 +47,70 @@
 
 1. Test list parsing and batch simulation
 2. Unit tests
-3. CLI log graphics
+3. CLI log graphic
 
 ## [0.9.1] - 2024-09-16
 
-### Fixes
+### Fixes:
 
-1. Fixed rvvm exacutable being excluded by gemspec
+1. Fixed `rvvm` exacutable being excluded by gemspec
 
 ## [0.9.2] - 2024-09-16
 
-### Fixes
+### Fixes:
+
+1. `rvvm` executable still missing after 0.9.1 update
+
+### TBI:
+
+1. Test list parsing and batch simulation
+2. Tests
+3. CLI log graphic
+4. Project config load failure handling/error message when parsing invalid json
+5. Template file generation in pwd
+6. Elaboration and simulation custom waveform trace dump file
+
+## [0.9.3] - 2024-09-16
+
+### Added:
+
+1. Test list parsing and batch simulation
+2. Tests
+3. Updated gitlab pipeline
+4. `sandbox` script to play with during development
+5. Code documentation
+
+### Fixed:
+
+1. Hash key conversion to symbols when parsing config json
+
+### TBI:
+
+1. CLI log graphic
+2. Project config load failure handling/error message when parsing invalid json
+3. Template file generation in pwd
+4. Elaboration and simulation custom waveform trace dump file
+5. Project template files regeneration/restoration to default
+6. Rescue on script crash due to creating a project dir that already exists
+
+## [0.9.4] - 2024-09-17
+
+### Added:
+
+1. More tests
+2. Cleaned up code documentation
+3. JSON::ParserError handling when loading an invalid config json
+4. Promt to overwrite an existing directory while creating project
+5. Project creation error handling
+
+### Fixed:
+
+1. Script crash due to loading invalid json config
+2. Script crash due to creating a project dir that already exists
+
+### TBI:
 
-1. rvvm executable still missing after 0.9.1 update
+1. CLI log graphic
+2. Template file generation in pwd
+3. Elaboration and simulation custom waveform trace dump file
+4. Project template files regeneration/restoration to default

data/bin/sandbox

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# just a sandbox to play with ruby during development
+
+require "json"
+
+json = %(
+{
+  "sizmaj": "bit"
+  "akafuka" : {
+    "siz": 1,
+    "maj": 2,
+    "bit": 3
+  }
+}
+)
+
+def json_parse(data)
+  parsed = JSON.parse(data)
+  puts parsed
+rescue JSON::ParserError => e
+  puts "Invalid JSON!\nError #{e.message}"
+end
+
+json_parse(json)

data/lib/rvvm/templates.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Module containing template hashes for rvvm.
 module Templates
   @templates = {}
 
@@ -49,7 +50,7 @@ module Templates
     "verbosity": "LOW",
     "defTest": " ",
     "batch": 0,
-    "testList": " ",
+    "testlist": [" "],
     "args": " "
   }
 })
@@ -245,6 +246,11 @@ endpackage
 )
   }
 
+  # Loads template hashes.
+  #
+  # @return [Hash] template hashes
+  #
+  # @since 0.8.0
   def self.load
     @templates
   end

data/lib/rvvm/utils.rb

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
+# Utils module providing utilities and helper methods to rvvm.
+#
+# Mainly used to generate files and templates.
+#
+# @since 0.1.0
 module Utils
-  def self.interpret(string, hash)
+  # Interpolates string.
+  #
+  # Replaces named keys `${example_key}` with provided values based on a hash.
+  #
+  # @param string [String] string to be interpolated
+  # @param hash [Hash] Hash to provide values to replace instead of the named keys
+  #
+  # @return [string] interpolated string
+  #
+  # @since 0.1.0
+  def self.interpolate(string, hash)
     string.gsub(/\$\{([^}]+)\}/) do |match|
       hash[Regexp.last_match(1).to_sym] || match
     end
   end
 
+  # Generates a file with a provided content.
+  #
+  # @param path [String] path of the file to be generated
+  # @param content [String] content of the file to be generated
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.gen_file(path, content)
     File.open(path, "w") do |file|
       file.write(content)
@@ -15,16 +38,36 @@ module Utils
     puts "\nFailed to create a file!\nError #{e.message}"
   end
 
+  # Generates a file based on a template.
+  #
+  # @param template [Hash] hash with the template content
+  # @param name [String] name of the file to be generated
+  # @param config [Hash] template config hash for content interpolation
+  # @param path [String] path of the template file to be generated (excluding file name)
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.gen_template(template, name = nil, config = nil, path = nil)
     temp_config = config || template[:config]
-    content = interpret(template[:content], temp_config)
+    content = interpolate(template[:content], temp_config)
     filename = name || template[:file][:name]
     filepath = path || template[:file][:path]
 
-    puts "Generating: #{filepath}/#{filename}"
+    puts "      Generating: #{filepath}/#{filename}"
     gen_file("#{filepath}/#{filename}", content)
   end
 
+  # Recursively searches provided directory for a file.
+  #
+  # @param filename [String] name of the file to look for
+  # @param path [String] path to start search on
+  #
+  # @return [String] path of the first occurence of the file
+  # or
+  # @return [nil] if file not found
+  #
+  # @since 0.8.0
   def self.find_file_dir(filename, path)
     Dir.foreach(path) do |file|
       next if file == "."
@@ -42,6 +85,11 @@ module Utils
     nil
   end
 
+  # Extracts git username using git config system call.
+  #
+  # @return [String] git username
+  #
+  # @since 0.9.0
   def self.git_userame
     username = nil
     IO.popen("git config --get user.name") do |handle|
@@ -52,6 +100,15 @@ module Utils
     username
   end
 
+  # Checks if hash contains keys provided from an array.
+  #
+  # @param hash [Hash] hash to analyze
+  # @param arra [Array] array of keys to look for in the hash
+  #
+  # @return [Bolean] true if all provided keys from a hash return nil
+  # @return [Boolean] false if a provided key is found in the hash
+  #
+  # @since 0.9.0
   def self.all_nil?(hash, array)
     array.each do |key|
       return false if hash[key]

data/lib/rvvm/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Module holding current rvvm version.
 module Rvvm
-  VERSION = "0.9.2"
+  # Current rvvm module version.
+  VERSION = "0.9.4"
 end

data/lib/rvvm.rb

@@ -8,13 +8,28 @@ require "optparse"
 require "fileutils"
 require "json"
 
+# Top level module of the rvvm cli meta tool.
+#
+# Handles argument parsing, project creation, template file
+# generation and all interaction with Xilinx Vivado tools.
+#
+# Argument parsing runs on `require`, rest is run using run
+#
+# @example
+#   require "rvvm"
+#
+#   Rvvm.run
+#
+# @since 0.1.0
 module Rvvm
   class Error < StandardError; end
 
+  # Module instance variables to hold tempaltes and project config
   @templates = Templates.load
   @config_path = nil
   @config = nil
 
+  # Instance variables to hold parsed args and required arg symbol list
   @args = {}
   @required_args = %i[
     version
@@ -34,6 +49,8 @@ module Rvvm
     covreport
   ]
 
+  # Script argument parsing block.
+  # Runs on loading the module using require.
   OptionParser.new do |args|
     args.on("-h", "--help", "Shows this help") do
       puts "\nRVvM - Ruby Vivado Manager\n\n"
@@ -44,16 +61,11 @@ module Rvvm
       @current_time = Time.now
       @formatted_time = @current_time.strftime("%Y-%m-%d %H:%M:%S")
 
-
       req_args = String.new
       @required_args.each do |arg|
         req_args << "--#{arg} "
       end
       puts "\nRequired args (at least one): #{req_args}\n\n"
-      # puts "\nRequired args (at least one):"
-      # @required_args.each do |arg|
-      #   puts "\t--#{arg}"
-      # end
       exit(0)
     end
     args.on("-v", "--version", "Displays RVvM gem version") do
@@ -66,7 +78,6 @@ module Rvvm
     args.on("--pkg NAME", "Creates a SystemVerilog package template (default path: <prj dir>/design/pkg)")
     args.on("--itf NAME", "Creates a SystemVerilog interface template (default path: <prj dir>/design/itf)")
     args.on("--svfile NAME", "Creates a generic SystemVerilog file template (default path: <prj dir>/design/src)")
-    # args.on("--here", "Speciies pwd as a path when creating a file template")
     args.on("--path PATH", "Specifies a path relative to <prj dir> when creating a file template")
     args.on("-c", "--comp", "Compile SystemVerilog sources")
     args.on("-e", "--elab", "Elaborates project")
@@ -97,22 +108,31 @@ module Rvvm
     args.on("--debug", "Script debug")
   end.parse!(into: @args)
 
-  def self.pass_config(config)
-    @config = config
-  end
-
+  # Simple argument check.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.check_args
     if @args[:all]
       @args[:comp] = 1
       @args[:elab] = 1
       @args[:run] = 1
     end
+
+    # Check if a required arg is provided
     if Utils.all_nil?(@args, @required_args)
       puts "\nNo required options provided!\nFor more info use -h or --help\n"
-      exit
+      exit(1)
     end
   end
 
+  # Argument collision handling and additional settings for
+  # batch simulation and dpi compilation.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.handle_args
     @args[:dpi] = 1 if @args[:all] && @config[:dpi][:dpilib] == 1
 
@@ -127,6 +147,16 @@ module Rvvm
     end
   end
 
+  # Shell command with debug printout.
+  #
+  # If --debug arg provided instead of calling `system`
+  # prints the input command.
+  #
+  # @param command [String] command to be called/printed
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.execute(command)
     if @args[:debug]
       puts command
@@ -135,9 +165,28 @@ module Rvvm
     end
   end
 
+  # Creates a new RVvM project template in pwd with a given name.
+  #
+  # @param name [String] project name
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.create_new_project(name)
     puts "\nRVvM: Generating new project: #{name} ...\n"
 
+    if File.exist?(name)
+      print "      Directory #{name} already exists. Do you want to overwrite it? [y/n] "
+      input = gets.chomp
+      puts " "
+
+      if input == "y"
+        FileUtils.rm_rf(name)
+      else
+        exit(0)
+      end
+    end
+
     FileUtils.mkdir(name)
     Dir.chdir(name)
 
@@ -187,15 +236,25 @@ module Rvvm
     temp_conf[:PRJNAME] = name.upcase
     Utils.gen_template(@templates[:tbtop], "#{name}_tb_top.sv", temp_conf)
 
+    puts " "
     system("git init")
     system("git add .")
     system('git commit -am "Initial commit"')
 
-    puts "\nRVvM: New project generated. ^^"
+    puts "\nRVvM: New project generated. ^^\n\n"
 
     exit(0)
+  rescue StandardError => e
+    puts "RVvM: Failed to create project...\n #{e.message}\n"
+    exit(1)
   end
 
+  # Loads and parses rvvmconf.json config file from
+  # an RVvM project rvvm directory.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.load_config
     puts "\nRVvM: Loading RVvM project config..."
 
@@ -210,14 +269,27 @@ module Rvvm
 
     @config = JSON.parse(json_file) if json_file
     @config = @config.transform_values do |v|
-      v.transform_keys(&:to_sym)
+      v.is_a?(Hash) ? v.transform_keys(&:to_sym) : v
     end.transform_keys(&:to_sym)
+  rescue JSON::ParserError => e
+    puts "     Invalid config json!\n\n#{e.message}"
+    exit(1)
   end
 
+  # Navigates to project top (rvvm directory of the RVvM project).
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.prj_top
     Dir.chdir(@config_path)
   end
 
+  # Compiles project SystemVerilog sources using xvlog.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.compile
     cmd_args = @config[:compilation][:args]
     logname = @args[:complog] || File.join([@config[:project][:logDir], @config[:compilation][:logDir], @config[:compilation][:log]])
@@ -229,6 +301,12 @@ module Rvvm
     execute(cmd)
   end
 
+  # Compiles C/C++ sources into a shared library to use during
+  # elaboration and simulation using DPI-C.
+  #
+  # @return [void]
+  #
+  # @Since 0.9.0
   def self.dpi_c
     cmd_args = @config[:dpi][:args]
     dpilist = @args[:dpilist] || @config[:dpi][:list]
@@ -239,6 +317,11 @@ module Rvvm
     execute(cmd)
   end
 
+  # Elaborates project into a testbench snapshot using xelab.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.elaborate
     cmd_args = @config[:elaboration][:args]
     cmd_args << " -sv_lib dpi" if @args[:dpi] || @args[:dpilib] || @config[:dpi][:dpilib] == 1
@@ -256,6 +339,11 @@ module Rvvm
     execute(cmd)
   end
 
+  # Runs UVM test simulation on an elaborated testbench snapshot using xrun.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.run_sim
     cmd_args = @config[:simulation][:args]
     if @args[:wave]
@@ -263,10 +351,12 @@ module Rvvm
     else
       cmd_args << "-R"
     end
-
+    
+    # Run simulaton on an array of tests.
+    # If in not running in batch mode testlist is an array with a single test
     test = @args[:test] || @config[:simulation][:defTest]
-    # TODO: parse test list
     testlist = [test]
+    testlist = @args[:testlist] || @config[:simulation][:testlist] if @args[:batch] || @config[:simulation][:batch] == 1
 
     tb = @args[:simtb] || @args[:tb] || @config[:elaboration][:tb]
 
@@ -276,7 +366,7 @@ module Rvvm
       puts "RVvM: Running test #{i + 1}/#{testlist.size}: #{simtest}"
 
       logname = File.join([@config[:project][:logDir], @config[:simulation][:logDir], @config[:simulation][:log]])
-      logname = Utils.interpret(logname, { testname: simtest })
+      logname = Utils.interpolate(logname, { testname: simtest })
 
       verb = "UVM_#{@args[:verb] || @config[:simulation][:verbosity]}"
 
@@ -285,6 +375,11 @@ module Rvvm
     end
   end
 
+  # Runs a pure SystemVerilog/Verilog simulation using xrun.
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.run_sv
     cmd_args = @config[:simulation][:args]
     tb = @args[:simtb] || @args[:tb] || @config[:elaboration][:tb]
@@ -295,7 +390,12 @@ module Rvvm
     cmd = "xsim #{tb} -log #{logname} #{cmd_args}"
     execute(cmd)
   end
-
+  
+  # Opens last generated waveform trace dump to inspect in Vivado GUI.
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.gui
     dump = @args[:wavefile] || "#{@config[:elaboration][:tb]}.wdb"
 
@@ -303,16 +403,34 @@ module Rvvm
     execute(cmd)
   end
 
+  # Generates UVM test functional coverage report using xcrg.
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.coverage
     cmd = "xcrg -report_format html -dir xsim.covdb"
     execute(cmd)
   end
 
+  # Opens last generated functional coverage report in a HTML dashboard.
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.cov_report
     Dir.chdir("xcrg_func_cov_report")
     execute("./dashboard.html")
   end
 
+  # Generates a SystemVerilog module/interface template.
+  #
+  # @param type [String] specifies modudle/itf
+  # @param name [String] specifies module/itf name
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.create_module(type, name)
     conf = @templates[:module][:conf]
     conf[:module] = name
@@ -330,6 +448,13 @@ module Rvvm
     exit(0)
   end
 
+  # Generates a SystemVerilog package template.
+  #
+  # @param name [String] specifies package name
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.create_pkg(name)
     conf = @templates[:package][:conf]
     conf[:package] = name
@@ -346,6 +471,13 @@ module Rvvm
     exit(0)
   end
 
+  # Generates a generic SystemVerilog template file.
+  #
+  # @param name [String] specifies template name
+  #
+  # @return [void]
+  #
+  # @since 0.9.0
   def self.create_svfile(name)
     conf = @templates[:svfile][:conf]
     conf[:NAME] = name.upcase
@@ -361,6 +493,11 @@ module Rvvm
     exit(0)
   end
 
+  # Runs rvvm calling its methods based on provided script args.
+  #
+  # @return [void]
+  #
+  # @since 0.8.0
   def self.run
     create_new_project(@args[:new]) if @args[:new]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rvvm
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.4
 platform: ruby
 authors:
 - mrbya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-16 00:00:00.000000000 Z
+date: 2024-09-17 00:00:00.000000000 Z
 dependencies: []
 description: RVvM is a Ruby based meta tool to manage/compile/elaborate and run simulations
   on SystemVerilog and UVM based projects using Xilinx Vivado xvlog, xelab, xrun,
@@ -26,6 +26,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/sandbox
 - exe/rvvm
 - lib/rvvm.rb
 - lib/rvvm/templates.rb