HDLRuby 3.6.2 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c4b4aec90e44d8229a4f13990112c3599b7104e3a867cf87741b2d1e4ff246
-  data.tar.gz: 10c6957977c1df45cae0f270dd27db75824a92e51dc508b5ffa600ce4654f1a0
+  metadata.gz: 01c5cc3826577779dad647fb9c8811d4bec3445bc19ca873f1015990aa689e68
+  data.tar.gz: 84985eda69036fe35175cc5255786c53839d7611a98170d2d1d131b3d4c0ec1d
 SHA512:
-  metadata.gz: 56b18d61f3945edaaff50244ecb8ae69fa5c29058942c456ca377eb54da83bb64677004dae4047a8f2aae9b4dd2fa57972c8cf6f0fc497bfe9785c447466cfaa
-  data.tar.gz: 81e58ca1a9ae1b6ba038c5a43c857ebff9e93dd2627befe89706c0200389a5ee18e1d77261e21d13f291b547dc4cf5be2e9024d75d524e2d54d26c37f7943679
+  metadata.gz: 45fbf8ad20c226c543770c85e3b41fd3dabf9fb337830c518544f67b86afd417240e3309575993e58a13de17233b8a197b08e9ca3a7ba7eb9a6e505900b41251
+  data.tar.gz: 8728928e73e6ccd092c5741be652d8f0730c7cf07f04ddbb4af64615b8472df2db50dfa6d0ad4c310c09270f61cc6d3e760fe6d4a87850ca97156ef64e2518ed

data/README.md

@@ -17,6 +17,12 @@ hdrcc --get-tuto
 
 __What's new__
 
+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.
+
+
 For HDLRuby version 3.6.x:
 
  * Added a new element for the GUI board that allows to assign an expression to a signal on the fly while simulating.
@@ -3215,7 +3221,7 @@ end
 ## Sequencer (software-like hardware coding):: `std/sequencer.rb`
 <a name="sequencer"></a>
 
-This library provides a new set of 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.
+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:
 
@@ -3715,6 +3721,214 @@ __Notes__:
 
     With the code above, the only restriction is that the signal `stack_overflow` is declared before the function `fact` is called.
 
+### Sequencers as Software Code
+
+#### Introduction to Sequencer as Software 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'
+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, referred by the variable `my_seq`, which increments the signal `counter` up to 1000:
+
+```ruby
+require 'HDLRuby/std/sequencer_sw'
+include RubyHDL::High
+using RubyHDL::High
+
+[32].inner :counter
+
+my_seq = sequencer do
+   counter <= 0
+   1000.stimes do
+      counter <= counter + 1
+   end
+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 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'
+include RubyHDL::High
+using RubyHDL::High
+
+[32].inner :counter
+
+counter.value = 0
+
+my_seq = sequencer do
+   counter <= 0
+   1000.stimes do
+      counter <= counter + 1
+   end
+end
+
+my_seq.()
+
+puts "counter=#{counter.value}"
+```
+
+__Note__: When displaying the value of a signal, the `.value` method can be omitted. For example, in the code above, the final statement can also be written as:
+
+```ruby
+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:
+
+1. High-speed simulation: Sequencers executed in software run approximately 10 times faster than in the HDLRuby simulator.
+
+2. Seamless transition from software to hardware: During the early design stages, it may not be clear whether a given part will be implemented in software and hardware. Using the same code for both ensures:
+
+   * Reliability (guaranteed functional equivalence).
+
+   * Reduced design time (no need for recoding).
+
+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.
+
+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
+  ...
+end
+```
+
+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
+clk_count.value = 0
+
+sequencer(clk_count) do
+   1000.stimes
+end.()
+
+puts "#{clk_count} clocks"
+```
+
+__Note__: In the code above, the sequencer is not stored in a variable because it is executed immediately upon declaration.
+
+#### Adding a Signal to Control the Execution of a Software Sequencer.
+
+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
+[1].inner :start
+clk_count.value = 0
+
+sequencer(clk_count,start) do
+   1000.stimes
+end
+
+start.value = 1
+
+puts "#{clk_count} clocks"
+```
+
+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
+[8].inner :count0, :count1
+
+sequencer(nil,start0) do
+   count0 <= 0
+   swhile(count0<100) { count0 <= count0 + 1 }
+   start1 <= 1
+end
+
+sequencer(nil,start1) do
+   count1 <= 0
+   swhile(count1<100) { count1 <= count1 + 1 }
+end
+```
+
+#### Synchronizing Sequencers for Pseudo-Parallel Execution
+
+While software sequencers normally execute to completion before any other code runs, they can be interrupted using the `sync` command. This command does not correspond to anything in hardware but can be used to simulate parallel execution of multiple sequencers.
+
+When a `sync` command is encountered during execution, the sequencer is paused, and execution resumes with the code that follows the sequencer’s start. The paused sequencer can then be resumed using the call operator or by setting its start signal to 1.
+
+For example, in the following code, the sequencer starts execution, then prints "stop at count=20" before resuming execution, and finally prints "end at count=40":
+
+```ruby
+
+[32].inner :count
+
+my_seq = sequencer do
+   count <= 0
+   20.stimes
+      count <= count + 1
+   sync
+   20.stimes
+      count <= count + 1
+   end
+end
+
+my_seq.()
+puts "stop at count=#{count}"
+my_seq.()
+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.
+
+When executing a sequencer in software, an additional command, `ruby`, is available for running plain Ruby code. For example, the following displays "Hello" ten times using the puts method:
+
+
+```ruby
+sequencer do
+   stimes.10 do
+      ruby { puts "Hello" }
+   end
+end.()
+```
+
+Another possibility is to put the code into a string as follows:
+
+```
+sequencer do
+   stimes.10 do
+      ruby('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.
+
 
 ## Fixed-point (fixpoint): `std/fixpoint.rb`
 <a name="fixpoint"></a>

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

@@ -0,0 +1,68 @@
+# Ruby program for testing SW HDLRuby.
+
+require 'HDLRuby/std/sequencer_sw'
+
+include RubyHDL::High
+using RubyHDL::High
+
+[32].inner :clk
+clk.value = 0
+
+[32].inner :a,:b,:c,:i
+[32].inner :d
+bit[32][-4].inner :ar
+[32].inner :res0, :res1
+
+some_ruby_value = 1
+
+
+prog0 = sequencer(clk) do
+  a <= 1
+  b <= 2
+  # c <= ruby { some_ruby_value }
+  c <= ruby("some_ruby_value")
+  d <= 0
+  i <= 0
+  # swhile(c<10000000) do
+  # 10000000.stimes do
+  sfor(0..10000000) do |u|
+    c <= a + b + d
+    d <= c + 1
+    # ar[i%4] <= i
+    ar[u%4] <= i
+    sif(i<1000) { i <= i + 1 }
+    selse { i <= 0 }
+    sync
+  end
+  a[4] <= 1
+  b[7..5] <= 5
+  res0 <= ar[0]
+end
+
+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
+    res1 <= ar[1]
+    sync
+  end
+end
+
+puts "Executing concurrently prog0 and prog1..."
+
+while prog0.alive? do
+  prog0.call
+  prog1.call
+end
+
+puts "a=#{a}"
+puts "b=#{b}"
+puts "c=#{c}"
+puts "d=#{d}"
+puts "ar=#{ar}"
+puts "res0=#{res0}"
+puts "res1=#{res1}"
+puts "clk=#{clk}"

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

@@ -0,0 +1,77 @@
+# Ruby program for testing SW HDLRuby.
+
+# require 'HDLRuby/std/sequencer_sw'
+
+# include RubyHDL::High
+# using RubyHDL::High
+
+system :test_with_sw_ruby do
+
+  [32].inner :a,:b,:c,:i
+  [32].inner :d, :e
+  bit[32][-4].inner :ar
+  [32].inner :res0, :res1
+
+  inner :clk,:start
+
+
+  sequencer(clk,start) do
+    a <= 1
+    b <= 2
+    c <= 0
+    d <= 0
+    i <= 0
+    e <= 0
+    # swhile(c<10000000) do
+    # 10000000.stimes do
+    sfor(0..10000000) do |u|
+      c <= a + b + d
+      d <= c + 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
+    res0 <= ar[0]
+    e <= 1
+  end
+
+
+  sequencer(clk,start) do
+    sloop do
+      res1 <= ar[1]
+    end
+  end
+
+
+  timed do
+    clk <= 0
+    start <= 0
+    !10.ns
+    clk <= 1
+    !10.ns
+    clk <= 0
+    start <= 1
+    !10.ns
+    clk <= 1
+    !10.ns
+    clk <= 0
+    start <= 0
+    !10.ns
+    clk <= 1
+    !10.ns
+    repeat(100000000) do
+      clk <= ~clk
+      !10.ns
+      hif(e == 1) do
+        hprint("c=",c,"\n")
+        hprint("res0=",res0,"\n")
+        hprint("res1=",res1,"\n")
+        terminate
+      end
+    end
+  end
+
+end

data/lib/HDLRuby/hdr_samples/with_program_ruby.rb

@@ -8,7 +8,14 @@ system :with_ruby_prog do
         actport clk.posedge
         inport  inP: count
         outport outP: echo
-        code "ruby_program/echo.rb"
+        # code "ruby_program/echo.rb"
+        code(proc do
+          def echo
+            val = RubyHDL.inP
+            puts "Echoing: #{val}"
+            RubyHDL.outP = val    
+          end
+        end)
     end
 
 

data/lib/HDLRuby/hruby_high.rb

@@ -3067,7 +3067,7 @@ module HDLRuby::High
         end
 
         # Adds the unary operations generation.
-        [:"-@",:"@+",:"~", :abs,
+        [:"-@",:"+@",:"~", :abs,
          :boolean, :bit, :signed, :unsigned].each do |operator|
             meth = proc do
                 expr = self.to_expr

data/lib/HDLRuby/hruby_low.rb

@@ -3031,7 +3031,8 @@ module HDLRuby::Low
 
         # Add a new code file.
         def add_code(code)
-            @codes << code.to_s
+          #  @codes << code.to_s
+          @codes << (code.is_a?(Proc) ? code : code.to_s)
         end
 
         # Add a new input port.

data/lib/HDLRuby/hruby_rcsim.rb

@@ -558,7 +558,11 @@ module HDLRuby::High
             if self.language == :ruby then
                 # Loads the code files.
                 self.each_code do |code|
+                  if code.is_a?(Proc)
+                    TOPLEVEL_BINDING.eval(&code)
+                  else
                     Kernel.require("./"+code.to_s)
+                  end
                 end
                 # Add the input ports.
                 self.each_inport do |sym, sig|