HDLRuby 3.7.1 → 3.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01c5cc3826577779dad647fb9c8811d4bec3445bc19ca873f1015990aa689e68
-  data.tar.gz: 84985eda69036fe35175cc5255786c53839d7611a98170d2d1d131b3d4c0ec1d
+  metadata.gz: 9c6e130a54f880c57186b29328c125d603604f4da1f25a5c4f890549a9847782
+  data.tar.gz: 19256d21296a7662f6241c27b41a969c0bb411c64084d8e48e740950c84867ac
 SHA512:
-  metadata.gz: 45fbf8ad20c226c543770c85e3b41fd3dabf9fb337830c518544f67b86afd417240e3309575993e58a13de17233b8a197b08e9ca3a7ba7eb9a6e505900b41251
-  data.tar.gz: 8728928e73e6ccd092c5741be652d8f0730c7cf07f04ddbb4af64615b8472df2db50dfa6d0ad4c310c09270f61cc6d3e760fe6d4a87850ca97156ef64e2518ed
+  metadata.gz: c6069997b2fbeb1acf6a4202e72fa6558060283de21d2ed2ea6a8ef72032f7c54166788346e03b4b4ba79d3c8cf0565edd3bee945b4c736907210b35b97d8331
+  data.tar.gz: be5e84ac24bd4df32e1a6a83fe37a294c9f17475de7c12bb8a40e96d944fb63f2e94556ea9cb6b954d82e81ff03fa44e9550dcd6cba349dc7d7b263e3808dece

data/README.md

@@ -17,6 +17,16 @@ hdrcc --get-tuto
 
 __What's new__
 
+For HDLRuby version 3.7.2:
+
+* Added the `text` command for the sequencers in software.
+
+* Added the `value_text` method to sequencers in software's signal for generatign Ruby/C code for accessing a value with correct typing.
+
+* Added the `alive?` and `reset!` commands for HDLRuby sequencers.
+
+* Added the `require_ruby` method for loading Ruby (i.e., non-HDLRuby) libraries.
+
 For HDLRuby version 3.7.x:
 
 * Added the possibility to run [sequencers in software](#sequencers-as-software-code). (WIP)
@@ -255,7 +265,9 @@ hdr_vhdl
 hdr_sim
 ```
 
+## HDLRuby files.
 
+HDLRuby being built on top of the Ruby language, we choose as convension to name the HDLRuby file with the `.rb` extension. For the same reason, including external HDLRuby files is done using the `require` or `require_relative` methods, that are identical to their Ruby counterpart. Those method however can only be used for including HDLRuby description file and not Ruby ones, for the later, the method `require_ruby` and `require_relative_ruby` must be used instead.
 
 
 # HDLRuby programming guide
@@ -739,7 +751,7 @@ __Notes__:
 - Since this is Ruby code, the body can also be delimited by the `do` and `end` Ruby keywords (in which case the parentheses can be omitted) as follows:
 
 ```ruby
-system :box does
+system :box do
 end
 ```
 
@@ -927,9 +939,17 @@ inner sig: 0
 As another example, an 8-bit 8-word ROM could be declared and initialized as follows:
 
 ```ruby
-bit[8][-8] rom: [ 0,1,2,3,4,5,6,7 ]
+bit[8][-8] rom: [ _h00,_h01,_h02,_h03,_h04,_h05,_h06,_h07 ]
 ```
 
+__Note__: 
+
+ * The notation `_hXY` is used for indicating a 2-digit, `X` and `Y`, hexadecimal.
+
+ *  By default, Ruby integers (not preceded by the `_` prefix) are typed as 64-bit HDLRuby values, whereas HDLRuby explicit values (preceded by the `_ ` prefix) have a bit-width corresponding to their representation.
+
+ * When declaring the contents of a ROM, the bit-width of the elements must match that of the declared type; otherwise, misalignments may occur.
+
 
 ### Scope in a system
 
@@ -3255,6 +3275,29 @@ A sequence is a specific case of a `seq` block that includes the following softw
 
  - `sterminate`: ends the execution of the sequence.
 
+ - `alive?`: is 0 if the sequencer is still running and not 0 otherwise.
+   Can be used outside the sequencer.
+
+ - `reset!`: resets the sequencer to its start.
+   Can be used outside the sequencer.
+
+The two last commands can be used to control a sequencer outside of it. For that purpose, a reference must be assigned to the sequencer as follows, where `ref_sequencer` is a Ruby variable that will refer to the sequencer:
+
+```ruby
+ref_sequencer = sequencer(clk,start) do
+   < some sequencer code >
+end
+
+< somewhere else in the code. >
+
+   # Reset the sequencer if it ended its execution.
+   hif(ref_sequencer.alive? == 0) do
+      ref_sequencer.reset!
+   end
+```
+
+
+
 It is also possible to use enumerators (iterators) similar to the Ruby `each` using the following methods within sequences:
 
  - `<object>.seach`: `object` any enumerable Ruby object or any signal. If a block is given, it works like `sfor`, otherwise, it returns a HDLRuby enumerator (please see [enumerator](#hdlruby-enumerators-and-enumerable-objects-stdsequencerrb) for details about them).
@@ -3917,17 +3960,26 @@ sequencer do
 end.()
 ```
 
-Another possibility is to put the code into a string as follows:
+Another possibility is to put the code into a string using the command `text` as follows:
 
 ```
 sequencer do
    stimes.10 do
-      ruby('puts "Hello"')
+      text('puts "Hello"')
    end
 end.()
 ```
 
-Both method are functionally equivalent. However, the first is faster and safer but is incompatible with separated code generation, while the second allows separate code generation but is slower and less safe.
+Both method are functionally equivalent. However, the first is safer as potential errors are detected at the compile stage, but is incompatible with separated code generation and is slow, while the second allows separate code generation, if fast, but is less safe since it is only at the execution stage that the code is checked.
+
+__Note__: Since the string in text is grafted as is into the generated Ruby (or C) code, you cannot directly access the value of a signal. However, you can use to_ruby or to_c to access the underlying raw value, or use value_text to retrieve the value with proper type adjustment in case of overflow or underflow. For example, the following will display the raw value of signal sig0 and the hardware-accurate value of signal sig1:
+
+```ruby
+sequencer do
+   text("puts #{sig0.to_ruby}")
+   text("puts #{sig1.value_text}")
+end
+```
 
 
 ## Fixed-point (fixpoint): `std/fixpoint.rb`

data/lib/HDLRuby/hdr_samples/ruby_program/with_sw_hruby.rb

@@ -63,6 +63,7 @@ puts "b=#{b}"
 puts "c=#{c}"
 puts "d=#{d}"
 puts "ar=#{ar}"
+puts "ar[1]=#{ar.value[1]}"
 puts "res0=#{res0}"
 puts "res1=#{res1}"
 puts "clk=#{clk}"

data/lib/HDLRuby/hruby_high.rb

@@ -1466,6 +1466,11 @@ module HDLRuby::High
                     sys.no_parent!
                     systemT.scope.add_systemI(sys)
                 end
+                # Adds it programs.
+                included.scope.each_program do |program|
+                  program.no_parent!
+                  systemT.scope.add_program(program)
+                end
                 # Adds its code.
                 included.scope.each_code do |code|
                     code.no_parent!
@@ -5495,6 +5500,16 @@ module HDLRuby::High
 
 end
 
+# Require a Ruby file.
+def self.require_ruby(str)
+  require(str)
+end
+
+# Require a Ruby file from current path.
+def self.require_relative_ruby(str)
+  require_relative(str)
+end
+
 # Tell if already configured.
 $HDLRuby_configure = false
 

data/lib/HDLRuby/hruby_rcsim.rb

@@ -559,7 +559,7 @@ module HDLRuby::High
                 # Loads the code files.
                 self.each_code do |code|
                   if code.is_a?(Proc)
-                    TOPLEVEL_BINDING.eval(&code)
+                    Object.instance_eval(&code)
                   else
                     Kernel.require("./"+code.to_s)
                   end

data/lib/HDLRuby/std/sequencer.rb

@@ -315,6 +315,16 @@ module HDLRuby::High::Std
             expr.seach.with_index(&ruby_block)
         end
 
+        # Tell if the sequencer ends it execution.
+        def alive?
+          return @fsm.cur_state_sig != self.end_state_value
+        end
+
+        # Resets the sequencer.
+        def reset!
+          @fsm.next_state_sig <= self.start_state_value
+        end
+
 
         # Fills the top user with the content of block +blk+.
         def fill_top_user(blk)

data/lib/HDLRuby/std/sequencer_sw.rb

@@ -54,7 +54,7 @@ module RubyHDL::High
 
     # Generate inner signals with type +type+ and names from +names+ list.
     def make_inners(type,*names)
-      puts "make_inners with names=#{names.join(",")}"
+      # puts "make_inners with names=#{names.join(",")}"
       type = type.to_type
       last_sig = nil
       names.each do |name|
@@ -151,22 +151,44 @@ module RubyHDL::High
   # end
 
 
+  # RUBY_OPERATOR = {
+  #   # Unary operators.
+  #   :"-@" => "-(%s)", :"+@" => "+(%s)", :"~" => "~(%s)",
+  #   :abs => "(%s).abs",
+  #   :boolean => "%s", :bit => "%s", 
+  #   :signed => "%s", :unsigned => "(%s) & 0xFFFFFFFFFFFFFFFF",
+
+  #   # Binary operators.
+  #   :"+" => "(%s)+(%s)", :"-" => "(%s)-(%s)",  :"*" => "(%s)*(%s)",
+  #   :"/" => "(%s)/(%s)", :"%" => "(%s)%%(%s)", :"**" => "(%s)**(%s)",
+  #   :"&" => "(%s)&(%s)", :"|" => "(%s)|(%s)",  :"^" => "(%s)^(%s)",
+  #   :"<<" => "(%s)<<(%s)", :">>" => "(%s)>>(%s)",
+  #   :"==" => "(%s)==(%s)", :"!=" => "(%s)!=(%s)",
+  #   :"<" => "(%s)<(%s)", :">" => "(%s)>(%s)", 
+  #   :"<=" => "(%s)<=(%s)",:">=" => "(%s)>=(%s)"
+  # }
+
   # The translation of operators into Ruby code.
   RUBY_OPERATOR = {
     # Unary operators.
-    :"-@" => "-(%s)", :"+@" => "+(%s)", :"~" => "~(%s)",
-    :abs => "(%s).abs",
-    :boolean => "%s", :bit => "%s", 
-    :signed => "%s", :unsigned => "(%s) & 0xFFFFFFFFFFFFFFFF",
+    :"-@" => "-(%{l})", :"+@" => "+(%{l})", :"~" => "~(%{l})",
+    :abs => "(%{l}).abs",
+    :boolean => "%{l}", :bit => "%{l}", 
+    :signed => "%{l}", :unsigned => "(%{l}) & 0xFFFFFFFFFFFFFFFF",
 
     # Binary operators.
-    :"+" => "(%s)+(%s)", :"-" => "(%s)-(%s)",  :"*" => "(%s)*(%s)",
-    :"/" => "(%s)/(%s)", :"%" => "(%s)%%(%s)", :"**" => "(%s)**(%s)",
-    :"&" => "(%s)&(%s)", :"|" => "(%s)|(%s)",  :"^" => "(%s)^(%s)",
-    :"<<" => "(%s)<<(%s)", :">>" => "(%s)>>(%s)",
-    :"==" => "(%s)==(%s)", :"!=" => "(%s)!=(%s)",
-    :"<" => "(%s)<(%s)", :">" => "(%s)>(%s)", 
-    :"<=" => "(%s)<=(%s)",:">=" => "(%s)>=(%s)"
+    :"+" => "(%{l})+(%{r})", :"-" => "(%{l})-(%{r})", 
+    :"*" => "(%{l})*(%{r})", :"/" => "(%{l})/(%{r})", 
+    :"%" => "(%{l})%%(%{r})", :"**" => "(%{l})**(%{r})",
+    :"&" => "(%{l})&(%{r})", :"|" => "(%{l})|(%{r})", 
+    :"^" => "(%{l})^(%{r})",
+    :"<<" => "(%{l})<<(%{r})", :">>" => "(%{l})>>(%{r})",
+    :"==" => "(%{l}) & %{m}==(%{r}) & %{m}", 
+    :"!=" => "(%{l}) & %{m}!=(%{r}) %{m}",
+    :"<" => "(%{l}) & %{m}%{s} < (%{r}) & %{m}%{s}", 
+    :">" => "(%{l}) & %{m}%{s} > (%{r}) & %{m}%{s}", 
+    :"<=" => "(%{l}) & %{m}%{s} <=(%{r}) & %{m}%{s}",
+    :">=" => "(%{l}) & %{m}%{s} >=(%{r}) & %{m}%{s}"
   }
 
   # The translation of operators into C code.
@@ -985,12 +1007,30 @@ module RubyHDL::High
 
   # The signed bit type.
   Signed = define_type(:signed)
+  class << Signed
+    # Tells if the type signed.
+    def signed?
+      return true
+    end
+  end
 
   # The unsigned bit type.
   Unsigned = define_type(:unsigned)
+  class << Unsigned
+    # Tells if the type unsigned.
+    def unsigned?
+      return true
+    end
+  end
 
   # The float bit type
   Float = define_type(:float)
+  class << Float
+    # Tells if the type signed.
+    def signed?
+      return true
+    end
+  end
 
   # The string type
   StringT = define_type(:string)
@@ -1823,11 +1863,13 @@ module RubyHDL::High
       super(type)
       @operator = operator.to_sym
       @child = child.to_expr
+      @mask = (2 ** @type.width)-1
     end
 
     # Convert to Ruby code.
     def to_ruby
-      return RUBY_OPERATOR[@operator] % @child.to_ruby
+      # return RUBY_OPERATOR[@operator] % @child.to_ruby
+      return RUBY_OPERATOR[@operator] % { l: @child.to_ruby }
     end
 
     # Convert to C code.
@@ -1845,11 +1887,22 @@ module RubyHDL::High
       @operator = operator.to_sym
       @left = left.to_expr
       @right = right.to_expr
+      # Compute the mask for fixing the bit width.
+      @mask = (2 ** @type.width)-1
+      # Compute xor mask for handling the sign.
+      # Make it as a string so that no addition computation is required
+      # if no sign is required.
+      @sign_fix = ""
+      if type.signed? then
+        @sign_fix = " ^ #{2**(@type.width-1)}"
+      end
     end
 
     # Convert to Ruby code.
     def to_ruby
-      return RUBY_OPERATOR[@operator] % [ @left.to_ruby, @right.to_ruby ]
+      # return RUBY_OPERATOR[@operator] % [ @left.to_ruby, @right.to_ruby ]
+      return RUBY_OPERATOR[@operator] % 
+        { l: @left.to_ruby, r: @right.to_ruby, m: @mask, s: @sign_fix }
     end
 
     # Convert to C code.
@@ -3110,6 +3163,9 @@ module RubyHDL::High
     def initialize(type,name)
       @type = type.to_type
       @name = name.to_sym
+      # Compute the mask for adjusting the value to the type.
+      @mask = (2 ** @type.width)-1
+      @sign = 2 ** (@type.width-1)
     end
 
     # Tell if the signal is an array.
@@ -3132,7 +3188,31 @@ module RubyHDL::High
 
     # Gets the value of the signal.
     def value
-      return TOPLEVEL_BINDING.eval(self.to_ruby)
+      # return TOPLEVEL_BINDING.eval(self.to_ruby)
+      res = TOPLEVEL_BINDING.eval(self.to_ruby)
+      if res.is_a?(Integer) then
+        res = res & @mask
+        if @type.signed? then
+          if res & @sign != 0 then
+            return res - (@mask+1)
+          end
+        end
+      end
+      return res
+    end
+
+    # Generate a Ruby/C string code for accessing the value of the 
+    # signal with proper bit width and sign.
+    def value_text
+      unless self.array? then
+        if @type.signed? then
+          return "(#{self.to_ruby} & #{@sign} != 0 ? #{self.to_ruby} & #{@mask} - #{@mask+1} : #{self.to_ruby} & #{@mask})"
+        else
+          return "(#{self.to_ruby} & #{@mask})"
+        end
+      else
+        return self.to_ruby
+      end
     end
 
     # Sets the value of the signal.
@@ -3272,16 +3352,19 @@ module RubyHDL::High
     def sif(cond, &ruby_block)
       self << RubyHDL::High::Sif.new(@sequencer,cond,&ruby_block)
     end
+    alias_method :hif, :sif
 
     # Create a sequential elsif statement on +cond+.
     def selsif(cond, &ruby_block)
       self.last_statement.selsif(&ruby_block)
     end
+    alias_method :helsif, :selsif
 
     # Create a sequential else statement.
     def selse(&ruby_block)
       self.last_statement.selse(&ruby_block)
     end
+    alias_method :helse, :selse
 
     # Wait a given condition.
     def swait(cond)
@@ -3321,6 +3404,11 @@ module RubyHDL::High
     def ruby(str = nil, &ruby_block)
       self << RubyHDL::High::Ruby.new(str,&ruby_block)
     end
+
+    # Some arbitrary code whose text is to add direction.
+    def text(str)
+      self << str.to_s
+    end
   end
 
 
@@ -3411,7 +3499,7 @@ Fiber.new do
 end
 BUILD
       # puts "building code_txt=" + @source
-      @code = TOPLEVEL_BINDING.eval(@source)
+      self.reset!
     end
 
     # Get the Ruby code.
@@ -3462,6 +3550,11 @@ BUILDC
     end
     alias_method :call, :resume
 
+    # Resets the sequencer.
+    def reset!
+      @code = TOPLEVEL_BINDING.eval(@source)
+    end
+
     # Check is the sequencer can still be resumed.
     def alive?
       @code.alive?
@@ -3479,6 +3572,11 @@ BUILDC
     return SequencerT.new(clk,start,&ruby_block)
   end
 
+  # Create a 1-bit signal.
+  def inner(*names)
+    return [1].inner(*names)
+  end
+
   # Create a new function named +name+, built using block +ruby_block+.
   def sdef(name,&ruby_block)
     name = name.to_sym

data/lib/HDLRuby/version.rb

@@ -1,3 +1,3 @@
 module HDLRuby
-  VERSION = "3.7.1"
+  VERSION = "3.7.2"
 end

data/tuto/tutorial_sw.html

@@ -131,6 +131,12 @@ To do this, you can use the following command:</p>
 </code></pre>
 <p><strong>Note</strong>: for the command above, it is assumed that 'adder.v' contains a simulation benchmark.</p>
 <p>And that's it! For details about all the actions that can be performed, how to write an input file, and what kind of output can be produced, let us see the remaining of the tutorial.</p>
+<h3>1.4. About the HDLRuby files.</h3>
+<p>The HDLRuby files, that include HDLRuby description of circuits, are text files (the default encoding is UTF-8), is file name's extension is by convension <code>.rb</code>. It is possible to include other HDLRuby file within the current one using the <code>require</code> (for HDLRuby standard files) or <code>require_relative</code> (for local HDLRuby files) methods as follows:</p>
+<pre><code class="language-ruby">require &quot;filename&quot;
+require_relative &quot;path_to_another_filename&quot;
+</code></pre>
+<p>As it will be seen later, software Ruby code can also be used for generic descriptions of circuits. It is also possible to include Ruby code from different files using respectively <code>require_ruby</code> for standard libraries and gems, and <code>require_relative_ruby</code> for local files.</p>
 <h2>2. How to represent a circuit in HDLRuby</h2>
 <p>In this section we will see:</p>
 <ul>

data/tuto/tutorial_sw.md

@@ -187,6 +187,18 @@ __Note__: for the command above, it is assumed that 'adder.v' contains a simulat
 
 And that's it! For details about all the actions that can be performed, how to write an input file, and what kind of output can be produced, let us see the remaining of the tutorial.
 
+### 1.4. About the HDLRuby files.
+
+The HDLRuby files, that include HDLRuby description of circuits, are text files (the default encoding is UTF-8), is file name's extension is by convension `.rb`. It is possible to include other HDLRuby file within the current one using the `require` (for HDLRuby standard files) or `require_relative` (for local HDLRuby files) methods as follows:
+
+```ruby
+require "filename"
+require_relative "path_to_another_filename"
+```
+
+As it will be seen later, software Ruby code can also be used for generic descriptions of circuits. It is also possible to include Ruby code from different files using respectively `require_ruby` for standard libraries and gems, and `require_relative_ruby` for local files.
+
+
 
 ## 2. How to represent a circuit in HDLRuby
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: HDLRuby
 version: !ruby/object:Gem::Version
-  version: 3.7.1
+  version: 3.7.2
 platform: ruby
 authors:
 - Lovic Gauthier
 bindir: exe
 cert_chain: []
-date: 2025-03-16 00:00:00.000000000 Z
+date: 2025-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler