HDLRuby 3.7.1 → 3.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01c5cc3826577779dad647fb9c8811d4bec3445bc19ca873f1015990aa689e68
-  data.tar.gz: 84985eda69036fe35175cc5255786c53839d7611a98170d2d1d131b3d4c0ec1d
+  metadata.gz: 78d08a6a222a4f33398c1d92e8b1f7d9462597b22ea2c48306318fb3e3e9c82d
+  data.tar.gz: 4a52c34a1355369260b0c162df38b7714ad1cedf4ed56ab7bc023eb01d2b7e40
 SHA512:
-  metadata.gz: 45fbf8ad20c226c543770c85e3b41fd3dabf9fb337830c518544f67b86afd417240e3309575993e58a13de17233b8a197b08e9ca3a7ba7eb9a6e505900b41251
-  data.tar.gz: 8728928e73e6ccd092c5741be652d8f0730c7cf07f04ddbb4af64615b8472df2db50dfa6d0ad4c310c09270f61cc6d3e760fe6d4a87850ca97156ef64e2518ed
+  metadata.gz: d35ac48b9832cd591a03be9db90574021ccf2ee73a784fd3b608487f8addff48295f7043ee2c0a31aeccec0cba00866828da94b63aa6f319e61c9ac812be64bb
+  data.tar.gz: ddd87fe50aedb38521627cbaf5c6467c7ea59146d10c2e62f1069de2ae90859013d20e312b1b40fdc36a94d04cc02278aeaafa59227c3d71f340544e31f03067

data/README.md

@@ -17,6 +17,20 @@ hdrcc --get-tuto
 
 __What's new__
 
+For HDLRuby version 3.7.3:
+
+* Added the possibility to use software sequencers inside HDLRuby's program construct, and use within them program ports like they were input or output signals.
+
+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 +269,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 +755,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 +943,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 +3279,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 +3964,48 @@ 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
+```
+
+#### Using Software Sequencer Inside a HDLRuby program.
+
+HDLRuby supports hardware/software co-design through the `program` [construct](#declaring-a-software-component). Since software sequencers are software components, they can be used within this construct when the selected language is Ruby. They can also be used with the C language, but in that case, the corresponding C code must first be generated.
+
+For Ruby, software sequencer signals can be automatically connected to the ports of the program construct by declaring them as input signals for `inport` and output signals for `outport`. For example, the following code describes a software sequencer that echoes the value from the input port `inP` to the output port `outP` (`sig0` and `sig1` are signals from the upper RTL design).
+
+```ruby
+program(:ruby) do
+  actport clk.posedge
+  inport inP: sig0
+  outport outP: sig1
+  code do
+    input :inP
+    output :outP
+    sequencer do
+      outP <= inP
+    end
+  end
+end
+```
+
 
 
 ## Fixed-point (fixpoint): `std/fixpoint.rb`

data/ext/hruby_sim/hruby_rcsim_build.c

@@ -1682,7 +1682,7 @@ VALUE rcsim_transmit_fixnum_to_signal(VALUE mod, VALUE signalV, VALUE valR) {
     /* Get the C signal from the Ruby value. */
     SignalI signal;
     value_to_rcsim(SignalIS,signalV,signal);
-    /* Compute the simualtion value from valR. */
+    /* Compute the simulation value from valR. */
     Value value = get_value();
     value->type = signal->type;
     value->numeric = 1;
@@ -1699,7 +1699,7 @@ VALUE rcsim_transmit_fixnum_to_signal_seq(VALUE mod, VALUE signalV, VALUE valR)
     /* Get the C signal from the Ruby value. */
     SignalI signal;
     value_to_rcsim(SignalIS,signalV,signal);
-    /* Compute the simualtion value from valR. */
+    /* Compute the simulation value from valR. */
     Value value = get_value();
     value->type = signal->type;
     value->numeric = 1;
@@ -1711,6 +1711,49 @@ VALUE rcsim_transmit_fixnum_to_signal_seq(VALUE mod, VALUE signalV, VALUE valR)
 }
 
 
+/** Reads an elements of a C signal array at an index and returns
+ *  the result as a Ruby fixnum.
+ *  Sets 0 if the value contains x or z bits. */
+VALUE rcsim_read_index_fixnum(VALUE mod, VALUE signalV, VALUE idxV) {
+    Value value = get_value();
+    /* Get the C signal from the Ruby value. */
+    SignalI signal;
+    value_to_rcsim(SignalIS,signalV,signal);
+    /* Get its base type.*/
+    Type base = get_type_vector(get_type_bit(),signal->type->base);
+    /* Get the index. */
+    unsigned long long idx = FIX2LONG(idxV);
+    /* Access the value. */
+    read_range(signal->c_value,idx,idx,base,value);
+    /* Get the value from the signal. */
+    return LONG2FIX(value2integer(value));
+}
+
+/** Transmit a Ruby fixnum inside a C signal array at an index in 
+ *  a blocking fashion.
+ * NOTE: the simulator events are updated. */
+VALUE rcsim_write_index_fixnum_seq(VALUE mod, VALUE signalV, VALUE idxV, VALUE valR) {
+    /* Get the C signal from the Ruby value. */
+    SignalI signal;
+    value_to_rcsim(SignalIS,signalV,signal);
+    // /* Get its base type.*/
+    // Type base = get_type_vector(get_type_bit(),signal->type->base);
+    /* Get the index. */
+    unsigned long long idx = FIX2LONG(idxV);
+    /* Compute the simulation value from valR. */
+    Value value = get_value();
+    value->type = signal->type;
+    value->numeric = 1;
+    value->data_int = FIX2LONG(valR);
+    /* Transmit it. */
+    transmit_to_signal_range_num_seq(value, signal, idx,idx);
+    /* End, return the transmitted expression. */
+    return valR;
+}
+
+
+
+
 // /** Execute a behavior. */
 // VALUE rcsim_execute_behavior(VALUE mod, VALUE behaviorV) {
 //     /* Get the behavior. */
@@ -1900,6 +1943,8 @@ void Init_hruby_sim() {
     /* The Ruby software interface. */
     rb_define_singleton_method(mod,"rcsim_get_signal_fixnum",rcsim_get_signal_fixnum,1);
     rb_define_singleton_method(mod,"rcsim_transmit_fixnum_to_signal_seq",rcsim_transmit_fixnum_to_signal_seq,2);
+    rb_define_singleton_method(mod,"rcsim_read_index_fixnum",rcsim_read_index_fixnum,2);
+    rb_define_singleton_method(mod,"rcsim_write_index_fixnum_seq",rcsim_write_index_fixnum_seq,3);
     // rb_define_singleton_method(mod,"rcsim_execute_behavior",rcsim_execute_behavior,1);
 
 }

data/ext/hruby_sim/hruby_sim.h

@@ -901,6 +901,14 @@ extern void transmit_to_signal_seq(Value value, SignalI signal);
  *         value to. */
 extern void transmit_to_signal_range_seq(Value value, RefRangeS ref);
 
+/** Transmit a value to a range within a signal in case of sequential
+ *  execution model.
+ *  @param value the value to transmit
+ *  @param ref the reference to the range in the signal to transmit the
+ *         value to. */
+extern void transmit_to_signal_range_num_seq(Value value, SignalI signal,
+        unsigned long long first, unsigned long long last);
+
 /** Creates an event.
  *  @param edge the edge of the event
  *  @param signal the signal of the event */

data/ext/hruby_sim/hruby_sim_calc.c

@@ -2449,7 +2449,7 @@ static int same_content_value_range_numeric(Value value0,
 Value read_range_numeric(Value value,
         unsigned long long first, unsigned long long last,
         Type base, Value dst) {
-    /* printf("read_range_numeric with value=%llx and first=%llu and last=%llu\n",value->data_int,first,last); */
+    // printf("read_range_numeric with value=%llx and first=%llu and last=%llu\n",value->data_int,first,last); 
     /* Ensure first is the smaller. */
     if (first > last) {
         long long tmp = last;
@@ -2465,7 +2465,7 @@ Value read_range_numeric(Value value,
     first *= bw;
     last  *= bw;
     length *= bw;
-    /* printf("first=%lld last=%lld bw=%llu length=%lld\n",first,last,bw,length); */
+    // printf("first=%lld last=%lld bw=%llu length=%lld\n",first,last,bw,length); */
 
     /* Set the type and size of the destination from the type of the source.*/
     dst->type = make_type_vector(get_type_bit(),length);
@@ -3427,6 +3427,7 @@ unsigned long long value2integer(Value value) {
 Value read_range(Value value,
         unsigned long long first, unsigned long long last, 
         Type base, Value dst) {
+    // printf("Read range with first=%d, last=%d\n",first,last);
     /* Is the value numeric? */
     if (value->numeric) {
         /* Yes, do a numeric range read. */

data/ext/hruby_sim/hruby_sim_core.c

@@ -735,18 +735,35 @@ void transmit_to_signal_seq(Value value, SignalI signal) {
  *  @param value the value to transmit
  *  @param ref the reference to the range in the signal to transmit the
  *         value to. */
+void transmit_to_signal_range_num_seq(Value value, SignalI signal,
+        unsigned long long first, unsigned long long last) {
+    // printf("Tansmit to signal range seq: %s(%p) [%llu,%llu]\n",signal->name,signal,first,last);
+    /* The base type is stored here to avoid allocating a new type each time.
+     * It have an arbitrary base size a single element. */
+    static TypeS baseT = { 1, 1 };
+    baseT.base = signal->f_value->type->base;
+    // printf("Tansmit to signal range: %s(%p) [%lld:%lld]\n",signal->name,signal,first,last);
+    /* Can transmit, copy the content. */
+    if (signal->fading)
+        signal->f_value = write_range(value,first,last,&baseT,
+                signal->f_value);
+    else
+        signal->f_value = write_range_no_z(value,first,last,&baseT,
+                signal->f_value);
+    /* And touch the signal. */
+    touch_signal_seq(signal);
+}
+
+/** Transmit a value to a range given with by first and last values, within a signal in case of sequential
+ *  execution model.
+ *  @param value the value to transmit
+ *  @param ref the reference to the range in the signal to transmit the
+ *         value to. */
 void transmit_to_signal_range_seq(Value value, RefRangeS ref) {
     SignalI signal = ref.signal;
     unsigned long long first = ref.first;
     unsigned long long last = ref.last;
     // printf("Tansmit to signal range seq: %s(%p) [%llu,%llu]\n",signal->name,signal,first,last);
-    // /* Can transmit, copy the content. */
-    // if (signal->fading)
-    //     // write_range(value,first,last,signal->f_value->type,signal->f_value);
-    //     write_range(value,first,last,ref.type,signal->f_value);
-    // else
-    //     // write_range_no_z(value,first,last,signal->f_value->type,signal->f_value);
-    //     write_range_no_z(value,first,last,ref.type,signal->f_value);
     /* The base type is stored here to avoid allocating a new type each time.
      * It have an arbitrary base size a single element. */
     static TypeS baseT = { 1, 1 };

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/hdr_samples/ruby_program/with_sw_hruby_function.rb

@@ -0,0 +1,31 @@
+require 'HDLRuby/std/sequencer_sw'
+
+include RubyHDL::High
+using RubyHDL::High
+
+# Sequencer for testing arithmetic computations.
+
+sdef(:truc) do |m,n|
+  sreturn(n+m*2)
+end
+
+signed[32].inner :x,:y, :result
+signed[32].inner :clk
+
+my_seq = sequencer(clk) do
+  x <= 0
+  y <= 0
+  100.stimes do
+    x <= x + 1
+    10.times do
+      y <= truc(x,y)
+    end
+  end
+  result <= y
+end
+
+puts "code=" + my_seq.source
+
+my_seq.()
+
+puts "result=#{result}"

data/lib/HDLRuby/hdr_samples/with_program_ruby_array.rb

@@ -0,0 +1,48 @@
+
+# A benchmark for testing the use of Ruby software code with array ports.
+system :with_ruby_prog do
+  inner :clk
+  bit[8][-8].inner ar: [ _h00, _h01, _h04, _h09, _h10, _h19, _h24, _h31 ]
+
+  program(:ruby,:show) do
+    actport clk.posedge
+    arrayport arP: ar
+    code(proc do
+      def show
+        8.times do |i|
+          val = RubyHDL.arP[i]
+          puts "# ar[#{i}]=#{val}"
+          RubyHDL.arP[i] = i+i
+        end
+      end
+    end)
+  end
+
+
+  timed do
+    clk <= 0
+    hprint("ar[0]=",ar[0],"\n")
+    hprint("ar[1]=",ar[1],"\n")
+    hprint("ar[2]=",ar[2],"\n")
+    hprint("ar[3]=",ar[3],"\n")
+    hprint("ar[4]=",ar[4],"\n")
+    hprint("ar[5]=",ar[5],"\n")
+    hprint("ar[6]=",ar[6],"\n")
+    hprint("ar[7]=",ar[7],"\n")
+    !10.ns
+    repeat(8) do
+      clk <= ~clk
+      !10.ns
+    end
+    !10.ns
+    hprint("ar[0]=",ar[0],"\n")
+    hprint("ar[1]=",ar[1],"\n")
+    hprint("ar[2]=",ar[2],"\n")
+    hprint("ar[3]=",ar[3],"\n")
+    hprint("ar[4]=",ar[4],"\n")
+    hprint("ar[5]=",ar[5],"\n")
+    hprint("ar[6]=",ar[6],"\n")
+    hprint("ar[7]=",ar[7],"\n")
+    !10.ns
+  end
+end

data/lib/HDLRuby/hdr_samples/with_program_ruby_sequencer.rb

@@ -0,0 +1,49 @@
+
+# A benchmark for testing the use of Ruby software code including a
+# sequencer.
+#
+system :with_ruby_prog_seq do
+    inner :clk
+    [8].inner :count, :echo
+
+    program(:ruby,:echo) do
+        actport clk.posedge
+        inport  inP: count
+        outport outP: echo
+        code(proc do
+          activate_sequencer_sw(binding)
+
+          $my_seq = nil
+
+          def echo
+            unless $my_seq then
+              [32].input :inP
+              [32].output :outP
+              $my_seq = sequencer do
+                sloop do
+                  outP <= inP
+                  sync
+                end
+              end
+            end
+            $my_seq.()
+          end
+        end)
+    end
+
+
+    timed do
+        clk <= 0
+        count <= 0
+        !10.ns
+        repeat(10) do
+            clk <= 1
+            hprint("echo=",echo,"\n")
+            !10.ns
+            count <= count + 1
+            clk <= 0
+            !10.ns
+        end
+
+    end
+end

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!
@@ -2579,6 +2584,8 @@ module HDLRuby::High
             self.each_inport  { |p| progL.add_inport(p[0],p[1].to_low) }
             # Add the output signals references.
             self.each_outport { |p| progL.add_outport(p[0],p[1].to_low) }
+            # Add the array signals references.
+            self.each_arrayport { |p| progL.add_arrayport(p[0],p[1].to_low) }
             # Return the resulting program.
             return progL
         end
@@ -2602,6 +2609,11 @@ module HDLRuby::High
         def outport(ports = {})
           ports.each { |k,v| self.add_outport(k,v) }
         end
+
+        # Adds new array ports.
+        def arrayport(ports = {})
+          ports.each { |k,v| self.add_arrayport(k,v) }
+        end
     end
 
 
@@ -5495,6 +5507,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
 
@@ -5540,4 +5562,20 @@ def self.configure_high
     def self.booting?
         false
     end
+
+
 end
+
+
+
+
+# Activate the software sequencer for Ruby code embedded in HDLRuby
+def activate_sequencer_sw(binding_context)
+  eval <<~RUBY, binding_context
+    alias require_ruby require
+    require_ruby 'HDLRuby/std/sequencer_sw'
+    include RubyHDL::High
+    using RubyHDL::High
+  RUBY
+end
+

data/lib/HDLRuby/hruby_low.rb

@@ -3019,6 +3019,7 @@ module HDLRuby::Low
             @codes    = [] # The code files.
             @inports  = {} # The input ports.
             @outports = {} # The output ports.
+            @arrayports ={}# The array ports.
         end
 
         # Add a new activation port.
@@ -3063,6 +3064,20 @@ module HDLRuby::Low
             @outports[name] = sig
         end
 
+        # Add a new array port.
+        def add_arrayport(name, sig)
+            # Ensure name is a symbol.
+            unless name.is_a?(Symbol) then
+                name = name.to_s.to_sym
+            end
+            # Ensure sig is a signal.
+            unless sig.is_a?(SignalI) then
+                raise AnyError, "Invalid class for a signal: #{sig.class}"
+            end
+            # Add the new port.
+            @arrayports[name] = sig
+        end
+
 
         # Iterates over each activation event.
         #
@@ -3104,6 +3119,16 @@ module HDLRuby::Low
             @outports.each(&ruby_block)
         end
 
+        # Iterate over each array port.
+        #
+        # Returns an enumerator if no ruby block is given.
+        def each_arrayport(&ruby_block)
+            # No block? Return an enumerator.
+            return to_enum(:each_arrayport) unless ruby_block
+            # A block is given, apply it.
+            @arrayports.each(&ruby_block)
+        end
+
     end
 
 

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
@@ -572,6 +572,10 @@ module HDLRuby::High
                 self.each_outport do |sym, sig|
                     RubyHDL.outport(sym,sig.rcsignalI)
                 end
+                # Add the array ports.
+                self.each_arrayport do |sym, sig|
+                    RubyHDL.arrayport(sym,sig.rcsignalI)
+                end
             elsif self.language == :c then
                 # Loads the code file: only the last one remains.
                 self.each_code do |code|
@@ -601,6 +605,10 @@ module HDLRuby::High
                 self.each_outport do |sym, sig|
                     RCSim::CPorts[sym] = sig.rcsignalI
                 end
+                # Add the array ports.
+                self.each_arrayport do |sym, sig|
+                    RCSim::CPorts[sym] = sig.rcsignalI
+                end
             end
 
 

data/lib/HDLRuby/std/sequencer.rb

@@ -315,6 +315,21 @@ module HDLRuby::High::Std
             expr.seach.with_index(&ruby_block)
         end
 
+        # Does nothing: just for compatibility with the software
+        # implementation of sequencers.
+        def sync
+        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)