HDLRuby 3.3.4 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160a8c6607e6dd20282a50fa26e0d472e055992ebce5f7cdf62d39e8c6bf7db5
-  data.tar.gz: 2c44f4edc3e4fdd76d64c2cb349f7083a255b68b1a18c6f41bef77c6d82138ab
+  metadata.gz: d4aecd7d8db226fd84031bd58762b442e4882a405a0898b8e87e3118c1ade8be
+  data.tar.gz: 9808966d1decc2aae4c9c9b0423b0ab2fbb0543d44dd635b98789f1f07aaabcf
 SHA512:
-  metadata.gz: 234d4901bc7ae389c1e0893ad19a7a2aff93c2bc2851066a80ce07b778787a1fa25950af60dd30d32d7e77a8804f0ef4dbc2c43bdf2f026f7b725cd15a943c84
-  data.tar.gz: 774369895db9a9f30b7a85061aba5190d3e45f962f6ca28e2cee7fe77d7c02c049570dd6e2a0f730640f687bc8069f19e433ea6d4bb2f79b6cb7875a6ef423a4
+  metadata.gz: bebd8de17a2e35c7c926fe44feb6ad04cce0fa4558d7a96376125da7a2ec55bc0815a24b6f26936e6dc6ca99781867fd8737a2cf8a3a6c6430c8fdef53bd38fc
+  data.tar.gz: 6ca378209e06714804526c8bff40845ccd7663ee4cff033044727035e16ff1ef86bc021342944b633d10cf7a599da4faff739b14b90b0ac5efdb329303e5c4f9

data/HDLRuby.gemspec

@@ -8,6 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = HDLRuby::VERSION
   spec.authors       = ["Lovic Gauthier"]
   spec.email         = ["lovic@ariake-nct.ac.jp"]
+  spec.platform      = "ruby"
 
   spec.summary       = %q{HDLRuby is a library for describing and simulating digital electronic systems.}
   spec.description   = %q{HDLRuby is a library for describing and simulating digital electronic systems. With this library it will possible to describe synthesizable hardware using all the features of the Ruby language, e.g., object orientation, duck typing, closure. This library is also usable through irb for interactive design and simulation.}

data/README.md

@@ -17,6 +17,26 @@ hdrcc --get-tuto
 
 __What's new__
 
+For HDLRuby version 3.5.0:
+
+ * Added direct support for Verilog HDL files as input to 'hdrcc'.
+
+ * Added the ability to generate a graphical representation of the RTL code in SVG format using the '--svg' option for 'hdrcc'.
+
+
+For HDLRuby version 3.4.0:
+
+ * Improved synchronization of the browser-base graphical interface with the HDLRuby simulator.
+
+ * Added a Verilog HDL parsing library for Ruby. This library will be released separately once it is fully stabilized."
+
+ * Added a HDLRuby generating library from the a Verilog HDL AST provided by the above-mentioned library.
+
+ * Added a standalone tool for converting Verilog HDL files to HDLRuby called [v2hdr](#converting-verilog-hdl-to-hdlruby). This tool is still experimental though.
+
+ * Added a HDLRuby command for [loading a Verilog HDL file from a HDLRuby description](#loading-verilog-hdl-from-hdlruby).
+
+
 For HDLRuby version 3.3.0:
  
  * Remade the description of software components using the program construct.
@@ -93,14 +113,14 @@ __Warning__:
 __Usage__:
 
 ```
-hdrcc [options] <input file> <output directory>
+hdrcc [options] <input file> <output/working directory>
 ```
 
 Where:
 
  * `options` is a list of options
  * `<input file>` is the initial file to compile (mandatory)
- *  `<output directory>` is the directory where the generated files will be put
+ *  `<output/working directory>` is the directory where the output and temporary files will be put
 
 |  Options         |          |
 |:------------------|:-----------------------------------------------------|
@@ -115,6 +135,7 @@ Where:
 | `--rsim`          | Perform the simulation with the Ruby engine          |
 | `--rcsim`         | Perform the simulation with the Hybrid engine        |
 | `--vcd`           | Make the simulator generate a VCD file               |
+| `--svg`           | Output a graphical representation of the RTL (SVG format) |
 | `-d, --directory` | Specify the base directory for loading the HDLRuby files |
 | `-D, --debug`     | Set the HDLRuby debug mode |
 | `-t, --top system`| Specify the top system describing the circuit to compile |
@@ -138,16 +159,16 @@ __Notes__:
 
 __Examples__:
 
-* Compile system named `adder` from `adder.rb` input file and generate a low-level YAML description into directory `adder`:
+* Compile `adder.rb` input file and generate a low-level Verilog HDL description into the directory `adder`:
 
 ```bash
-hdrcc --yaml --top adder adder.rb adder
+hdrcc -v adder.rb adder
 ```
 
-* Compile `adder.rb` input file and generate a low-level Verilog HDL description into the directory `adder`:
+* Compile `adder8.v` input Verilog HDL file with `adder8` as top module, and generate a graphical representation of its RTL in the `view` directory:
 
 ```bash
-hdrcc -v adder.rb adder
+hdrcc adder8.v -t adder8 --svg view
 ```
   
 * Compile system `adder` whose bit width is generic from `adder_gen.rb` input file to a 16-bit circuit low-level VHDL description into directory `adder`:
@@ -3929,6 +3950,57 @@ The naming convention of the samples is the following:
 * `<name>_bench.rb`: sample including a simulation benchmark, these are the only samples that can be simulated using `hdrcc -S`. Please notice that such a sample cannot be converted to VHDL or Verilog HDL yet.
 * `with_<name>.rb`: sample illustrating a single aspect of HDLRuby or one of its libraries, usually includes a benchmark.
 
+# Converting Verilog HDL to HDLRuby
+
+While the HDLRuby framwork does not support Verilog HDL files as input yet, a standalone tool is provided for converting those files to HDLRuby. For that please use the following command:
+
+```bash
+v2hdr <input Verilog HDL file> <output HDLRuby file>
+```
+
+For example, assuming that you have a Verilog ddHDL named 'adder.v' describing and adder circuit, you can convert it to HDLRuby as follows:
+
+```bash
+v2hdr adder.v adder.v.rb
+```
+
+Another possibility is to directly load the Verilog HDL file from a HDLRuby description using the command `require_verilog`.
+For example, assuming `adder.v` contains the following code:
+
+```verilog
+module adder(x,y,z);
+  input[7:0] x,y;
+  output[7:0] z;
+  
+  assign z = x + y;
+endmodule
+```
+
+It can be loaded the be instantiated like any other module in HDLRuby as follows:
+
+```ruby
+require_verilog "adder.v"
+
+system :my_IC do
+   [8].inner :a, :b, :c
+
+   adder(:my_adder).(a,b,c)
+
+   ...
+end
+```
+
+
+__Notes__:
+
+* Verilog HDL accepts signal and module names in any letter case, while HDLRuby reserves identifiers starting with a capital letter for constants. To avoid conflicts, Verilog HDL names that begin with a capital letter are prefixed with an underscore (`_`) in HDLRuby. For example, if the Verilog HDL module name in the previous example were `ADDER`, it would be renamed to `_ADDER` in HDLRuby. Instantiating such a module would be done as follows:
+
+  ```ruby
+  _ADDER(:my_add).(a,b,c)
+  ```
+
+* With the current version of HDLRuby, the Verilog HDL files are first converted to HDLRuby before being loaded using the standalone `v2hdr` tool.
+
 
 # Contributing
 
@@ -3938,7 +4010,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/civol/
 # To do
 
  * Find and fix the (maybe) terrifying number of bugs.
- * Add a GUI (any volunteer to do it?).
 
 
 # License

data/exe/v2hdr

@@ -0,0 +1,3 @@
+#!/usr/bin/ruby
+
+require 'HDLRuby/v2hdr.rb'

data/ext/hruby_sim/hruby_rcsim_build.c

@@ -554,6 +554,7 @@ VALUE rcsim_make_timeWait(VALUE mod, VALUE unitV, VALUE delayV) {
     /* Adjust the delay depending on the unit. */
     const char* unit = rb_id2name(SYM2ID(unitV));
     switch(unit[0]) {
+        case 'f': delay /= 1000;          break;
         case 'p': /* Ok as is. */         break;
         case 'n': delay *= 1000;          break;
         case 'u': delay *= 1000000;       break;

data/lib/HDLRuby/hdr_samples/adder8.v

@@ -0,0 +1,6 @@
+module adder8(x,y,z);
+  input[7:0] x,y;
+  output[7:0] z;
+  
+  assign z = x + y;
+endmodule

data/lib/HDLRuby/hdr_samples/hard_to_route.rb

@@ -0,0 +1,30 @@
+# A benchmark for testing the router of SVG generation with hard to
+# handle patterns.
+# Note that the circuit is not synthesizable here, it is just for
+# testing difficult routing patterns, even if they are illegal in practice.
+
+system :adder do |typ|
+    typ.input :x, :y
+    typ.output :z
+
+    z <= x + y
+end
+
+
+system :hard_to_route do
+
+    [8].inner :x, :y, :z, :c
+
+    adder(bit[8]).(:adderI0).(x,y,z)
+    adder(bit[8]).(:adderI1).(x: x, y: y, z: z)
+
+    timed do
+        !10.ns
+        x <= 0
+        y <= 0
+        !10.ns
+        x <= 1
+        y <= 1
+        !10.ns
+    end
+end

data/lib/HDLRuby/hdr_samples/sw_encrypt_bench.rb

@@ -1,3 +1,5 @@
+raise "Deprecated code."
+
 # require "../hruby_low2c.rb"
 
 # An 8-bit register with C encrypting.

data/lib/HDLRuby/hdr_samples/sw_encrypt_cpu_bench.rb

@@ -1,3 +1,5 @@
+raise "Deprecated code."
+
 require 'HDLRuby/backend/allocator'
 require 'HDLRuby/hdr_samples/mei8'
 

data/lib/HDLRuby/hdr_samples/sw_encrypt_cpusim_bench.rb

@@ -1,3 +1,5 @@
+raise "Deprecated code."
+
 require 'HDLRuby/backend/allocator'
 
 ## A generic CPU description

data/lib/HDLRuby/hdr_samples/verilog_parser_bench.rb

@@ -0,0 +1,36 @@
+$LOAD_PATH << "#{__dir__}/../../"
+
+require "HDLRuby/verilog_hruby.rb"
+
+parser = VerilogTools::Parser.new
+
+ast = nil
+
+begin
+  ast = parser.run(filename: ARGV[0], compress: ARGV[1] == "--compress" )
+rescue => error
+  puts error
+  exit
+end
+
+puts "#################################"
+puts "##             AST             ##"
+puts "#################################"
+puts "\n"
+
+puts ast
+
+hdlruby = ""
+begin
+  hdlruby = ast.to_HDLRuby
+rescue => error
+  puts error
+  exit
+end
+
+puts "\n"
+puts "#################################"
+puts "##           HDLRuby           ##"
+puts "#################################"
+
+puts hdlruby

data/lib/HDLRuby/hdr_samples/with_generic_in_generic.rb

@@ -0,0 +1,31 @@
+# Samples for testing instantiation of generic system within generic system.
+
+
+system :inner_generic do |typeI, typeO|
+  typeI.input :din
+  typeO.output :dout
+
+  dout <= din * 2
+end
+
+
+system :outer_generic do |typeI, typeO|
+  typeI.input :din_
+  typeO.output :dout_
+
+  inner_generic(typeI,typeO).(:my_inner_generic).(din_,dout_)
+end
+
+
+system :test_generic_in_generic do
+  [8].inner :x, :y
+
+  outer_generic(bit[8],bit[16]).(:my_outer_generic).(x,y)
+
+  timed do
+    x <= 0
+    !10.ns
+    x <= 1
+    !10.ns
+  end
+end

data/lib/HDLRuby/hdr_samples/with_handshake.rb

@@ -1,3 +1,5 @@
+raise "Deprecated code."
+
 require 'std/handshakes.rb'
 
 include HDLRuby::High::Std

data/lib/HDLRuby/hdr_samples/with_memory.rb

@@ -1,3 +1,5 @@
+raise "Deprecated code."
+
 require 'std/memory.rb'
 
 include HDLRuby::High::Std

data/lib/HDLRuby/hdr_samples/with_nand_board.rb

@@ -11,7 +11,7 @@ system :nand_board do
     inner :clk
     # Description of the board.
     # It is updated at each rising edge of +clk+.
-    board(:nand,8080) do
+    board(:nand,http_port: 8080) do
         actport clk.posedge
         sw din0: din0
         sw din1: din1

data/lib/HDLRuby/hdr_samples/with_reconf.rb

@@ -1,3 +1,4 @@
+raise "Deprecated code."
 
 # Some system that can be used for reconfiguration.
 system :sys0 do

data/lib/HDLRuby/hdr_samples/with_seq_case.rb

@@ -0,0 +1,28 @@
+
+
+# A benchmark for testing case in seq blocks.
+system :with_seq_case_bench do
+    [2].inner :s
+    [8].inner :z
+
+    seq do
+       z <= 4
+       hcase(s)
+       hwhen(0) { z <= 0 }
+       hwhen(1) { z <= 1 }
+       hwhen(2) {        } # Intentionally left blank
+       helse    { z <= 3 }
+       z <= z+1
+    end
+
+    timed do
+        s <= 0
+        !10.ns
+        s <= 1
+        !10.ns
+        s <= 2
+        !10.ns
+        s <= 3
+        !10.ns
+    end
+end

data/lib/HDLRuby/hdr_samples/with_seq_if.rb

@@ -0,0 +1,25 @@
+
+
+# A benchmark for testing if in seq blocks.
+system :with_seq_if_bench do
+    [2].inner :s
+    [8].inner :z
+
+    seq do
+       hif(s==0)    { z <= 0 }
+       helsif(s==1) { z <= 1 }
+       helsif(s==2) { z <= 2 }
+       helse        { z <= 3 }
+    end
+
+    timed do
+        s <= 0
+        !10.ns
+        s <= 1
+        !10.ns
+        s <= 2
+        !10.ns
+        s <= 3
+        !10.ns
+    end
+end

data/lib/HDLRuby/hdr_samples/with_seq_if_succ.rb

@@ -0,0 +1,27 @@
+
+
+# A benchmark for testing if in seq blocks.
+system :with_seq_if_bench do
+    [2].inner :s
+    [8].inner :u, :v
+
+    seq do
+       hif(s==0)    { u <= 0; v <= 3 }
+       helsif(s==1) { u <= 1; v <= 2 }
+       helsif(s==2) { u <= 2; v <= 1 }
+       helse        { u <= 3; v <= 0 }
+       u <= u + 1
+       v <= v + 2
+    end
+
+    timed do
+        s <= 0
+        !10.ns
+        s <= 1
+        !10.ns
+        s <= 2
+        !10.ns
+        s <= 3
+        !10.ns
+    end
+end

data/lib/HDLRuby/hdr_samples/with_verilog.rb

@@ -0,0 +1,24 @@
+# Sample HDLRuby instantiating a Verilog HDL-described adder (adder8.v)
+
+require_verilog "adder8.v"
+
+system :verilog_bench do
+  [8].inner :a, :b, :c
+
+  # Instantiate the adder.
+  adder8(:my_adder8).(a,b,c)
+
+  # Testing it.
+  timed do
+    a <= 0
+    b <= 0
+    repeat(100) do
+      repeat(100) do
+        !10.ns
+        b <= b + 1
+      end
+      a <= a + 1
+    end
+    !10.ns
+  end
+end

data/lib/HDLRuby/hdrcc.rb

@@ -254,15 +254,15 @@ module HDLRuby
                 # No, look for it.
                 @top_system = get_top
                 # show? "@top_system=#{@top_system}"
-                unless @top_system then
-                    # Not found? Error.
-                    # Maybe it is a parse error, look for it.
-                    bind = TOPLEVEL_BINDING.clone
-                    eval("require 'HDLRuby'\n\nconfigure_high\n\n",bind)
-                    eval(@texts[0],bind,@top_file_name,1)
-                    # No parse error found.
-                    raise "Cannot find a top system." unless @top_system
-                end
+                # unless @top_system then
+                #     # Not found? Error.
+                #     # Maybe it is a parse error, look for it.
+                #     bind = TOPLEVEL_BINDING.clone
+                #     eval("require 'HDLRuby'\n\nconfigure_high\n\n",bind)
+                #     eval(@texts[0],bind,@top_file_name,1)
+                #     # No parse error found.
+                #     raise "Cannot find a top system." unless @top_system
+                # end
             end
             # Initialize the environment for processing the hdr file.
             bind = TOPLEVEL_BINDING.clone
@@ -272,16 +272,20 @@ module HDLRuby
             end
             # Process it.
             eval(@texts[0],bind,@top_file_name,1)
-            # Get the resulting instance
-            if @params.empty? then
+            # Get the resulting instance if any.
+            if @top_system then
+              if @params.empty? then
                 # There is no generic parameter
                 @top_instance = 
-                    eval("#{@top_system} :#{@top_name}\n#{@top_name}",bind)
-            else
+                  eval("#{@top_system} :#{@top_name}\n#{@top_name}",bind)
+              else
                 # There are generic parameters
                 @top_instance = 
-                    # eval("#{@top_system} :#{@top_name},#{@params.join(",")}\n#{@top_name}",bind)
-                    eval("#{@top_system}(#{@params.join(",")}).(:#{@top_name})\n#{@top_name}",bind)
+                  eval("#{@top_system}(#{@params.join(",")}).(:#{@top_name})\n#{@top_name}",bind)
+              end
+            else
+              # No top instance.
+              @top_instance = nil
             end
         end
     end
@@ -348,13 +352,15 @@ $options = {}
 $options[:std] = true
 # Parse the options
 $optparse = OptionParser.new do |opts|
-    opts.banner = "Usage: hdrcc.rb [options] <input file> [<output directory or file>]"
+    opts.banner = "Usage: hdrcc.rb [options] [<input file>] [<output/working directory>]"
 
     opts.separator ""
     opts.separator "Where:"
     opts.separator "* `options` is a list of options"
-    opts.separator "* `<input file>` is the initial file to compile (mandatory)"
-    opts.separator "* `<output file>` is the output file"
+    opts.separator "* `<input file>` is the initial file to compile."
+    opts.separator "  This input can either be HDLRuby (.rb) or Verilog HDL (.v),"
+    opts.separator "  however, for the latter the top module must be specified using --top"
+    opts.separator "* `<output/working directory>` is the directory where to put temporary and output files"
     opts.separator ""
     opts.separator "Options:"
 
@@ -456,6 +462,11 @@ $optparse = OptionParser.new do |opts|
         $options[:vhdl08] = true
         $gen = true
     end
+    opts.on("--svg","Output a graphical representation of the RTL (SVG format)") do |v|
+      $options[:svg] = v
+      $options[:multiple] = v
+      $gen = true
+    end
     opts.on("-s", "--syntax","Output the Ruby syntax tree") do |s|
         $options[:syntax] = s
     end
@@ -541,15 +552,15 @@ $optparse.parse!
 # show? "options=#{$options}"
 
 # Check the compatibility of the options
-if $options.count {|op| [:yaml,:hdr,:verilog,:vhdl].include?(op) } > 1 then
-    warn("Please choose either YAML, HDLRuby, Verilog HDL, or VHDL output.")
+if $options.count {|op| [:yaml,:hdr,:verilog,:vhdl,:svg].include?(op) } > 1 then
+    warn("Please choose either YAML, HDLRuby, Verilog HDL, VHDL, SVG (visualize) output.")
     puts $optparse.help()
 end
 
 # Get the the input and the output files.
 $input,$output = $*
-    # Get the top system name if name.
-    $top = $options[:top].to_s
+# Get the top system name if name.
+$top = $options[:top].to_s
 unless $top == "" || (/^[_[[:alpha:]]][_\w]*$/ =~ $top) then
     warn("Please provide a valid top system name.")
     exit
@@ -593,17 +604,42 @@ if $output then
             FileUtils.mkdir_p($output)
         end
     else
-        # Open the file.
-        $output = File.open($output,"w")
+        # Now, nothing to do: specified output files are not to be
+        # handled by hdrcc directly with handles output directories only.
+        # 
+        # # Open the file if it is one, otherwise use a string.
+        # if File.file?($output) then
+        #     $output = File.open($output,"w")
+        # else
+        #     $output = StringIO.new
+        # end
     end
 else
     if $options[:multiple] then
-        raise "Need a target directory in multiple files generation mode."
+        # raise "Need a target directory in multiple files generation mode."
+        warn("Need a output/working directory.")
+        warn($optparse.banner)
+        exit
     end
     $output = $stdout
 end
 
-# Load and process the hdr files.
+# Process non-HDLRuby files.
+if $input.end_with?(".v") then
+  if $top.empty? then
+    warn("The top module must be specified using \"--top <top module>\".")
+    exit
+  end
+  # Processing a Verilog HDL file, embed it into regular HDLRuby
+  # Generate a temporary HDLRuby file to process it.
+  rinput = $output+"/"+$input.chomp(".v")+".rb"
+  File.open(rinput,"w") do |f|
+    f << "require_verilog '#{$input}'\n"
+  end
+  $input = rinput
+end
+
+# Load and process the HDLRuby files.
 $options[:directory] ||= "./"
 $loader = HDRLoad.new($top,$input,$options[:directory].to_s,*$params)
 $loader.read_all
@@ -637,7 +673,13 @@ end
 # Get the top systemT.
 HDLRuby.show "#{Time.now}#{show_mem}"
 # Ruby simulation uses the HDLRuby::High tree, other the HDLRuby::Lowais used 
-$top_system = ($options[:rsim] || $options[:rcsim]) ? $top_instance.systemT : $top_instance.to_low.systemT
+if $top_instance then
+  $top_system = ($options[:rsim] || $options[:rcsim]) ? $top_instance.systemT : $top_instance.to_low.systemT
+else
+  # No top system, end here.
+  HDLRuby.show "##### End here since not top system #####"
+  exit
+end
 $top_intance = nil # Free as much memory as possible.
 HDLRuby.show "##### Top system built #####"
 HDLRuby.show "#{Time.now}#{show_mem}"
@@ -1025,6 +1067,21 @@ elsif $options[:vhdl] then
             $output << systemT.to_vhdl
         end
     end
+elsif $options[:svg] then
+    # Requires the viz library.
+    require "HDLRuby/hruby_viz.rb"
+    # Generate the viz structure.
+    viz = $top_system.to_viz
+    # Do the place and route.
+    viz.place_and_route_deep
+    viz.scale = 30.0
+    # Get the base name of the input file, it will be used for
+    # generating the main name of the multiple result files.
+    $basename = File.basename($input,File.extname($input))
+    $basename = $output + "/" + $basename
+    $name = $basename + ".svg"
+    # Generate the svg file.
+    File.open($name,"w") { |file| file.write(viz.to_svg) }
 end
 
 HDLRuby.show "##### Code generated #####"

data/lib/HDLRuby/hruby_bstr.rb

@@ -70,7 +70,7 @@ module HDLRuby
                 # Content is not a numeric nor a BitString.
                 @content = []
                 # Ensure it is a string.
-                val = val.to_s.downcase
+                val = val.to_s.chomp.downcase
                 val.each_byte.reverse_each do |c|
                     case c
                     when 48  # "0"
@@ -82,7 +82,7 @@ module HDLRuby
                     when 122 # "z"
                         @content << 2
                     else
-                        raise "Invalid bit: #{b.chr}"
+                      raise "Invalid bit '#{c.chr}' in #{val}"
                     end
                 end
             end