HDLRuby 3.7.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '096e1c8ad3a0b6627819a744569d9ef159a40201ed13b36f11203f4ba751ee84'
-  data.tar.gz: c0d06d1991d5e8f4f691b56402cd00230f8f46f87a1fbbce235ccd27b6921140
+  metadata.gz: 01c5cc3826577779dad647fb9c8811d4bec3445bc19ca873f1015990aa689e68
+  data.tar.gz: 84985eda69036fe35175cc5255786c53839d7611a98170d2d1d131b3d4c0ec1d
 SHA512:
-  metadata.gz: b13fed12851411946a251af87cb00053a1f65ef118b5ade71c017ed3642aec055c8c60943d9873422100e389a87dd404f98b16e1a55d90cb2529a2d137405b37
-  data.tar.gz: fb7231f1cda8cef8afdfa13077952ecc3a71d281e12d83379df0bf64ffd1623266f2e59b218fd2e08be607225eaff0f901346cf892f1ad80f640401f45ff1f1b
+  metadata.gz: 45fbf8ad20c226c543770c85e3b41fd3dabf9fb337830c518544f67b86afd417240e3309575993e58a13de17233b8a197b08e9ca3a7ba7eb9a6e505900b41251
+  data.tar.gz: 8728928e73e6ccd092c5741be652d8f0730c7cf07f04ddbb4af64615b8472df2db50dfa6d0ad4c310c09270f61cc6d3e760fe6d4a87850ca97156ef64e2518ed

data/README.md

@@ -17,9 +17,9 @@ hdrcc --get-tuto
 
 __What's new__
 
-For HDLRuby version 3.7.0:
+For HDLRuby version 3.7.x:
 
-* Added the possibility to run sequencers in software (WIP).
+* 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.
 
 
@@ -3221,7 +3221,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:
 
@@ -3725,7 +3725,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 +3733,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 +3752,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 +3781,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 +3804,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 +3817,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 +3834,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 +3850,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 +3867,6 @@ sequencer(nil,start1) do
    swhile(count1<100) { count1 <= count1 + 1 }
 end
 ```
-   
 
 #### Synchronizing Sequencers for Pseudo-Parallel Execution
 
@@ -3889,6 +3898,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 +3917,18 @@ sequencer do
 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

@@ -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

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