HDLRuby 3.6.2 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c4b4aec90e44d8229a4f13990112c3599b7104e3a867cf87741b2d1e4ff246
-  data.tar.gz: 10c6957977c1df45cae0f270dd27db75824a92e51dc508b5ffa600ce4654f1a0
+  metadata.gz: '096e1c8ad3a0b6627819a744569d9ef159a40201ed13b36f11203f4ba751ee84'
+  data.tar.gz: c0d06d1991d5e8f4f691b56402cd00230f8f46f87a1fbbce235ccd27b6921140
 SHA512:
-  metadata.gz: 56b18d61f3945edaaff50244ecb8ae69fa5c29058942c456ca377eb54da83bb64677004dae4047a8f2aae9b4dd2fa57972c8cf6f0fc497bfe9785c447466cfaa
-  data.tar.gz: 81e58ca1a9ae1b6ba038c5a43c857ebff9e93dd2627befe89706c0200389a5ee18e1d77261e21d13f291b547dc4cf5be2e9024d75d524e2d54d26c37f7943679
+  metadata.gz: b13fed12851411946a251af87cb00053a1f65ef118b5ade71c017ed3642aec055c8c60943d9873422100e389a87dd404f98b16e1a55d90cb2529a2d137405b37
+  data.tar.gz: fb7231f1cda8cef8afdfa13077952ecc3a71d281e12d83379df0bf64ffd1623266f2e59b218fd2e08be607225eaff0f901346cf892f1ad80f640401f45ff1f1b

data/README.md

@@ -17,6 +17,12 @@ hdrcc --get-tuto
 
 __What's new__
 
+For HDLRuby version 3.7.0:
+
+* Added the possibility to run sequencers in software (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 [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,188 @@ __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 with functional equivalance to 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, refered by the variable `my_seq`, which increments 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 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.
+
+```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}"
+```
+
+#### 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 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.
+
+
+#### 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:
+
+```ruby
+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:
+
+
+```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, 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`:
+
+```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 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.
+
+```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.
+
+
+#### 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.()
+```
+
 
 ## Fixed-point (fixpoint): `std/fixpoint.rb`
 <a name="fixpoint"></a>

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

@@ -0,0 +1,59 @@
+# 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 }
+  d <= 0
+  i <= 0
+  # swhile(c<10000000) do
+  10000000.stimes do
+    c <= a + b + d
+    d <= c + 1
+    ar[i%4] <= i
+    i <= i + 1
+    sync
+  end
+  a[4] <= 1
+  b[7..5] <= 5
+  res0 <= ar[0]
+end
+
+puts "prog0 source code: #{prog0.source}\n"
+
+prog1 = sequencer do
+  sloop do
+    res1 <= ar[1]
+    sync
+  end
+end
+
+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,74 @@
+# 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
+      c <= a + b + d
+      d <= c + 1
+      ar[i%4] <= i
+      i <= i + 1
+    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|