HDLRuby 3.7.0 → 3.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '096e1c8ad3a0b6627819a744569d9ef159a40201ed13b36f11203f4ba751ee84'
-  data.tar.gz: c0d06d1991d5e8f4f691b56402cd00230f8f46f87a1fbbce235ccd27b6921140
+  metadata.gz: 9c6e130a54f880c57186b29328c125d603604f4da1f25a5c4f890549a9847782
+  data.tar.gz: 19256d21296a7662f6241c27b41a969c0bb411c64084d8e48e740950c84867ac
 SHA512:
-  metadata.gz: b13fed12851411946a251af87cb00053a1f65ef118b5ade71c017ed3642aec055c8c60943d9873422100e389a87dd404f98b16e1a55d90cb2529a2d137405b37
-  data.tar.gz: fb7231f1cda8cef8afdfa13077952ecc3a71d281e12d83379df0bf64ffd1623266f2e59b218fd2e08be607225eaff0f901346cf892f1ad80f640401f45ff1f1b
+  metadata.gz: c6069997b2fbeb1acf6a4202e72fa6558060283de21d2ed2ea6a8ef72032f7c54166788346e03b4b4ba79d3c8cf0565edd3bee945b4c736907210b35b97d8331
+  data.tar.gz: be5e84ac24bd4df32e1a6a83fe37a294c9f17475de7c12bb8a40e96d944fb63f2e94556ea9cb6b954d82e81ff03fa44e9550dcd6cba349dc7d7b263e3808dece

data/README.md

@@ -17,9 +17,19 @@ hdrcc --get-tuto
 
 __What's new__
 
-For HDLRuby version 3.7.0:
+For HDLRuby version 3.7.2:
 
-* Added the possibility to run sequencers in software (WIP).
+* 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)
 This allows both much faster simulation and the use of the same code for both hardware and software design.
 
 
@@ -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
 
@@ -3221,7 +3241,7 @@ end
 ## Sequencer (software-like hardware coding):: `std/sequencer.rb`
 <a name="sequencer"></a>
 
-This library provides a new set of software-like control statements for describing the behavior of a circuit. Behind the curtain, these constructs build a finite state machine where states are deduced from the control points within the description. Eventhough sequencers are ment to describe hardware, they are software-compatible so that they can efficiently be executed as software programs as explain in section [software sequencers](#sequencers-as-software-code).
+This library provides a new set of software-like control statements for describing the behavior of a circuit. Behind the curtain, these constructs build a finite state machine where states are deduced from the control points within the description. Eventhough sequencers are ment to describe hardware, they are software-compatible so that they can efficiently be executed as software programs as explain in section about [software sequencers](#sequencers-as-software-code).
 
 A sequencer can be declared anywhere in a system provided it is outside a behavior using the `sequencer` keyword as follows:
 
@@ -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).
@@ -3725,7 +3768,7 @@ __Notes__:
 
 #### Introduction to Sequencer as Software Code
 
-Sequencers can be executed in software using a Ruby interpreter with functional equivalance to the hardware implementation. To achieve this, the following headers must be added to your Ruby source code:
+Sequencers can be executed in software using a Ruby interpreter while maintaining functional equivalence with the hardware implementation. To achieve this, the following headers must be added to your Ruby source code:
 
 ```ruby
 require 'HDLRuby/std/sequencer_sw'
@@ -3733,7 +3776,7 @@ include RubyHDL::High
 using RubyHDL::High
 ```
 
-After this, signals and sequencers can be described exactly like in HDLRuby. However, the resulting sequencer objects are not executed immediately and must be stored in a variable for further reference. For example the following Ruby code defines a sequencer, refered by the variable `my_seq`, which increments signal `counter` up to 1000:
+After this, signals and sequencers can be described exactly like in HDLRuby. However, the resulting sequencer objects are not executed immediately and must be stored in a variable for further reference. For example, the following Ruby code defines a sequencer, referred by the variable `my_seq`, which increments the signal `counter` up to 1000:
 
 ```ruby
 require 'HDLRuby/std/sequencer_sw'
@@ -3752,7 +3795,7 @@ end
 
 You may notice that no clock or start signal is provided to the sequencer. This is because, in software, execution is sequential, and no clock nor control signals are required. Instead, starting the execution of a sequencer is done using the call operators as follows: `my_seq.()`.
 
-To verify wether the sequencer executed correctly, you can access the values of signals outside the sequencer using the `value` method. For example, the following code, initialize `counter` to 0, and then display the counter value after executing the sequencer.
+To verify whether the sequencer executed correctly, you can access signal values outside the sequencer using the `value` method. For example, the following code initializes `counter` to 0 and then displays the counter value after executing the sequencer.
 
 ```ruby
 require 'HDLRuby/std/sequencer_sw'
@@ -3781,6 +3824,17 @@ __Note__: When displaying the value of a signal, the `.value` method can be omit
 puts "counter=#{counter}"
 ```
 
+Internally, the HDLRuby code of a sequencer is converted to Ruby before execution. This code can be accessed through the `source` command. It can then be saved into a file for separate execution for example, as follows:
+
+```ruby
+File.open("sequencer_in_ruby.rb","w") do |f|
+   f << my_seq.source
+end
+```
+
+__Note__: the ruby code for sequencers is compatible with mruby for execution on embedded systems.
+
+
 #### Why Would I Want to Execute a Sequencer in Software, and What are the Limitations?
 
 There are two main reasons for executing sequencers in software:
@@ -3793,12 +3847,12 @@ There are two main reasons for executing sequencers in software:
 
    * Reduced design time (no need for recoding).
 
-While software sequencer are functionaly equivalent to their hardware implementation, their handling of time and parallelism is fundamentally different. In hardware, sequencers are implemented as finite state machines that transition according to a clock and that run in parallel with the remain of the circuits. By contrast, in software, sequencers are implemented as functions executed in sequence. If parallel synchronization is important in your design, e.g., a communication protocol, software sequencers may not be useful. However, there are ways to add hardware timing and parallelism in the following sections.
+While software sequencer are functionally equivalent to their hardware implementations, their handling of time and parallelism is fundamentally different. In hardware, sequencers are implemented as finite state machines that transition according to a clock and that run in parallel with the remain of the circuits. By contrast, in software, sequencers are implemented as fibers executed sequentially. If parallel synchronization is important in your design  (e.g., a communication protocol), software sequencers may not be useful. However, there are ways to add hardware timing and parallelism as described in the following sections.
 
 
 #### Adding a Clock to a Software Sequencer.
 
-While there is no clock in software, it is possible to simulate one while executing a sequencer to estimate its performance when implemented in hardware. This is done by passing as argument a signal that will be increase at each estimated clock cycle as follows:
+As mentioned earlier, there is no clock in software. However, it is possible to simulate one while executing a sequencer to estimate its performance when implemented in hardware. This is done by passing as argument a signal that will be increase at each estimated clock cycle as follows:
 
 ```ruby
 sequencer(<clock counting signal>) do
@@ -3806,8 +3860,7 @@ sequencer(<clock counting signal>) do
 end
 ```
 
-After the executing of a sequencer with a clock, the estimate number of clock cycles required by the hardware implementation is stored into the clock signal. For example the following code will display `1000 clocks` which is the estimated number of executed clocks if the sequencer is implemented in hardware:
-
+After the execution of a sequencer with a clock, the estimated number of clock cycles required for the hardware implementation is stored into the clock signal. For example, the following code will display `1000 clocks`, which is the estimated number of executed clocks if the sequencer were implemented in hardware:
 
 ```ruby
 [32].inner :clk_count
@@ -3824,7 +3877,7 @@ __Note__: In the code above, the sequencer is not stored in a variable because i
 
 #### Adding a Signal to Control the Execution of a Software Sequencer.
 
-In addition to a clock counter signal, it is possible to add a signal that when written one will start the execution of a software sequencer, like it is the case for the hardware implementation. For that purpose this signal is to be passed as second argument of the sequencer. For example the following code, starts the execution of the sequencer using signal `start`:
+In addition to a clock counter signal, you can add a signal that, when set to 1, starts the execution of a software sequencer, just like in the hardware implementation. To achieve this, pass the signal as second argument of the sequencer. For example the following code, starts the execution of the sequencer using signal `start`:
 
 ```ruby
 [32].inner :clk_count
@@ -3840,7 +3893,7 @@ start.value = 1
 puts "#{clk_count} clocks"
 ```
 
-With this alternate way for executing a software sequencer, it is not necesary any longer to store it into a ruby variable, and it is possible to start the execution of a sequencer exactly like in hardware, and also from anther sequencer. For example, in the following code, the sequencer sequencer start is controlled by the first one.
+With this alternative execution method, storing the sequencer in a Ruby variable is no longer necessary. The execution can be started exactly as in hardware, and also from another sequencer. For example, in the following code, the execution of the second sequencer is controlled by the first one.
 
 ```ruby
 [1].inner :start0, :start1
@@ -3857,7 +3910,6 @@ sequencer(nil,start1) do
    swhile(count1<100) { count1 <= count1 + 1 }
 end
 ```
-   
 
 #### Synchronizing Sequencers for Pseudo-Parallel Execution
 
@@ -3889,6 +3941,11 @@ puts "end at count=#{count}"
 
 For full cycle-accurate synchronization, insert a sync command at each estimated cycle. However, sync has a significant performance cost, and depending on the Ruby interpreter and software configuration, excessive use may make execution slower than the HDLRuby hardware simulator. Hence it is recommended to use this command only when necessary, and use the HDLRuby hardware simulator for cycle-accurate synchronization.
 
+Finally, to determine whether a sequencer has completed execution or is paused at sync command, use the `alive?` method. For example, the following code will resume execution of sequencer `my_seq` until it completes:
+
+```ruby
+my_seq.() while(my_seq.alive?)
+```
 
 #### Executing ruby code within a software sequencer.
 
@@ -3903,6 +3960,27 @@ sequencer do
 end.()
 ```
 
+Another possibility is to put the code into a string using the command `text` as follows:
+
+```
+sequencer do
+   stimes.10 do
+      text('puts "Hello"')
+   end
+end.()
+```
+
+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`
 <a name="fixpoint"></a>

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

@@ -19,15 +19,19 @@ some_ruby_value = 1
 prog0 = sequencer(clk) do
   a <= 1
   b <= 2
-  c <= ruby { some_ruby_value }
+  # c <= ruby { some_ruby_value }
+  c <= ruby("some_ruby_value")
   d <= 0
   i <= 0
   # swhile(c<10000000) do
-  10000000.stimes do
+  # 10000000.stimes do
+  sfor(0..10000000) do |u|
     c <= a + b + d
     d <= c + 1
-    ar[i%4] <= i
-    i <= i + 1
+    # ar[i%4] <= i
+    ar[u%4] <= i
+    sif(i<1000) { i <= i + 1 }
+    selse { i <= 0 }
     sync
   end
   a[4] <= 1
@@ -35,7 +39,10 @@ prog0 = sequencer(clk) do
   res0 <= ar[0]
 end
 
-puts "prog0 source code: #{prog0.source}\n"
+puts "Generating file from prog0 source code..."
+File.open("with_sw_hruby_mruby.rb","w") do |f|
+  f << prog0.source
+end
 
 prog1 = sequencer do
   sloop do
@@ -44,6 +51,8 @@ prog1 = sequencer do
   end
 end
 
+puts "Executing concurrently prog0 and prog1..."
+
 while prog0.alive? do
   prog0.call
   prog1.call
@@ -54,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_hruby_test.rb

@@ -23,11 +23,14 @@ system :test_with_sw_ruby do
     i <= 0
     e <= 0
     # swhile(c<10000000) do
-    10000000.stimes do
+    # 10000000.stimes do
+    sfor(0..10000000) do |u|
       c <= a + b + d
       d <= c + 1
-      ar[i%4] <= i
-      i <= i + 1
+      # ar[i%4] <= i
+      ar[u%4] <= i
+      sif(i<1000) { i <= i + 1 }
+      selse { i <= 0 }
     end
     a[4] <= 1
     b[7..5] <= 5

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)