HDLRuby 3.9.0 → 3.9.3

data/README.md

@@ -9,48 +9,48 @@ If you want to learn how to describe a circuit with HDLRuby, please jump to the
 
 * [HDLRuby Programming Guide](#hdlruby-programming-guide)
 
- - [Introduction](#introduction)
+  * [Introduction](#introduction)
 
- - [How HDLRuby Works](#how-hdlruby-works)
+  * [How HDLRuby Works](#how-hdlruby-works)
 
- - [Naming rules](#naming-rules)
+  * [Naming rules](#naming-rules)
 
- - [Systems and Signals](#systems-and-signals)
+  * [Systems and Signals](#systems-and-signals)
 
- - [Events](#events)
+  * [Events](#events)
 
- - [Statements](#statements)
+  * [Statements](#statements)
 
- - [Types](#types)
+  * [Types](#types)
 
- - [Expressions](#expressions)
+  * [Expressions](#expressions)
 
- - [Functions](#functions)
+  * [Functions](#functions)
 
- - [Software code](#software-code)
+  * [Software code](#software-code)
 
- - [Time](#time)
+  * [Time](#time)
 
- - [High-Level Programming Features](#high-level-programming-features)
+  * [High-Level Programming Features](#high-level-programming-features)
 
- - [Extending HDLRuby](#extending-hdlruby)
+  * [Extending HDLRuby](#extending-hdlruby)
 
 Many of HDLRuby's features are available through its standard libraries.
 We strongly recommend consulting the corresponding section:
 
 * [Standard Libraries](#standard-libraries)
 
- - [Clocks](#clocks)
+  * [Clocks](#clocks)
 
- - [Decoder](#decoder)
+  * [Decoder](#decoder)
 
- - [FSM](#fsm)
+  * [FSM](#fsm)
 
- - [Parallel Enumerators](#parallel-enumerator)
+  * [Parallel Enumerators](#parallel-enumerators)
 
- - [Sequencer (Software-like Hardware Coding)](#sequencer-software-like-hardware coding)
+  * [Sequencer (Software-like Hardware Coding)](#sequencer-software-like-hardware-coding)
 
- - [Fixed-Point](#fixed-point)
+  * [Fixed-Point](#fixed-point)
 
 Samples are also available: [Sample HDLRuby descriptions](#sample-hdlruby-descriptions)
 
@@ -71,7 +71,11 @@ hdrcc --get-tuto
 
 __What's New__
 
-For HDLRuby version 3.9.0:
+For HDKRuby version 3.9.2:
+
+* Added the `hbreak` command for exiting parallel enumerator loops.
+
+For HDLRuby version 3.9.0/3.9.1:
 
 * Added the parallel enumerators to the software sequencers.
 
@@ -92,11 +96,11 @@ For HDLRuby version 3.8.3:
 
 * Updated the documentation: 
 
-  - Rewrote the beginning of the [HDLRuby Programming Guide](#hdlruby-programming-guide).
+  * Rewrote the beginning of the [HDLRuby Programming Guide](#hdlruby-programming-guide).
 
-  - Updated the documentation for interactive mode.
+  * Updated the documentation for interactive mode.
 
-  - Updated the [High-Level Programming Features](#high-level-programming-features) chapter.
+  * Updated the [High-Level Programming Features](#high-level-programming-features) chapter.
 
 For HDLRuby version 3.8.0:
 
@@ -111,7 +115,7 @@ For HDLRuby version 3.7.9:
 
 * Added Python code generation from software sequencers.
 
-* Added [Parallel Enumerators](#parallel-enumerators-stdhruby_enumrb). 
+* Added [Parallel Enumerators](#parallel-enumerators). 
 
 For HDLRuby versions 3.7.7/3.7.8:
 
@@ -170,7 +174,7 @@ For HDLRuby version 3.4.0:
 
 * Added [v2hdr](#converting-verilog-hdl-to-hdlruby), a standalone tool for converting Verilog HDL files to HDLRuby (experimental).
 
-* Added a HDLRuby command for [loading a Verilog HDL file from a HDLRuby description](#loading-verilog-hdl-from-hdlruby).
+* Added a HDLRuby command for [loading a Verilog HDL file from a HDLRuby description](#converting-verilog-hdl-to-hdlruby).
 
 
 For HDLRuby version 3.3.0:
@@ -197,7 +201,7 @@ For HDLRuby version 3.2.0:
 
 For HDLRuby version 3.1.0:
 
-* Added [Functions for sequencers](#sequencer-specific-function-std-sequencer_func-rb), including support for recursion.
+* Added [functions for sequencers](#sequencer-specific-functions), including support for recursion.
 
 * Replaced the `function` keyword with `hdef` for consistency with sequencer functions (`sdef`).
 
@@ -211,7 +215,7 @@ For HDLRuby version 3.0.0:
 
 * Intruduced this changelog section.
 
-* Added [Sequencers](#sequencer-software-like-hardware-coding-stdsequencerrb) for software-like hardware design.
+* Added [Sequencers](#sequencer-software-like-hardware-coding) for software-like hardware design.
 
 * Added a [tutorial](tuto/tutorial_sw.md) for software developers.
 
@@ -235,8 +239,9 @@ git clone https://github.com/civol/HDLRuby.git
 
 __Warning__: 
 
- - HDLRuby is still under active development, and the API may change before a stable release.
- - It is highly recommended that users have a basic understanding of both the Ruby programming language and hardware description languages before using HDLRuby.
+* HDLRuby is still under active development, and the API may change before a stable release.
+
+* It is highly recommended that users have a basic understanding of both the Ruby programming language and hardware description languages before using HDLRuby.
 
 
 # Compiling HDLRuby Descriptions
@@ -419,8 +424,8 @@ Another key feature of HDLRuby is its native support for all features of the Rub
 
 __Notes__:
 
-- It is possible to extend HDLRuby to support hardware descriptions at a higher level of abstraction than RTL. See [Extending HDLRuby](#extending-hdlruby) for more details.
-- Throughout this guide, HDLRuby constructs are often compared to their Verilog HDL or VHDL equivalents to aid understanding.
+* It is possible to extend HDLRuby to support hardware descriptions at a higher level of abstraction than RTL. See [Extending HDLRuby](#extending-hdlruby) for more details.
+* Throughout this guide, HDLRuby constructs are often compared to their Verilog HDL or VHDL equivalents to aid understanding.
 
 ## Introduction
 
@@ -467,7 +472,7 @@ These include:
 
 * `mux`, an expression-level construct for multiplexers, which supports multiple inputs, unlike the ?: ternary operator in Verilog, which only handles two
 
-__Note__:  These statements are also called "parallel conditionals" in HDLRuby, to contrast with the ones used in the `sequencer` constructs (see [Sequencer](##sequencer-software-like-Hardware-coding)).
+__Note__:  These statements are also called "parallel conditionals" in HDLRuby, to contrast with the ones used in the `sequencer` constructs (see [Sequencer](#sequencer-software-like-Hardware-coding)).
 
 For example, we can upgrade the 8-bit adder to an adder-subtractor:
 
@@ -714,45 +719,48 @@ Fourth, HDLRuby allows you to extend modules and instances after their declarati
 
 Let us say you want to extend an existing `dff` module to include an inverted output (`qb`). There are three ways to do this:
 
- 1. Inheriting from a Module.
-    You can define a new system that inherits from the existing `dff`:
+1. Inheriting from a Module.
 
-   ```ruby
-   system :dff_full, dff do
-      output :qb
-      qb <= ~q
-   end
-   ```
+  You can define a new system that inherits from the existing `dff`:
 
-    This creates a new module `dff_full` that includes all the functionality of `dff`, with the additional inverted output.
+  ```ruby
+  system :dff_full, dff do
+     output :qb
+     qb <= ~q
+  end
+  ```
 
-  2. Reopening a Module.
-     You can modify the original `dff` module after its declaration using the open method:
+  This creates a new module `dff_full` that includes all the functionality of `dff`, with the additional inverted output.
 
-   ```ruby
-   dff.open do
-      output :qb
-      qb <= ~q
-   end
-   ```
+2. Reopening a Module.
 
-     This approach modifies `dff` itself, and the added behavior (`qb <= ~q`) will apply to all future instances of `dff`.
+  You can modify the original `dff` module after its declaration using the open method:
 
-  3. Reopening a Specific Instance.
-     You can also modify a single instance of a module without affecting the others:
+  ```ruby
+  dff.open do
+     output :qb
+     qb <= ~q
+  end
+  ```
 
-   ```ruby
-   # Declare dff0 as an instance of dff
-   dff :dff0
-   
-   # Modify it
-   dff0.open do
-      output :qb
-      qb <= ~q
-   end
-   ```
+  This approach modifies `dff` itself, and the added behavior (`qb <= ~q`) will apply to all future instances of `dff`.
+
+ 3. Reopening a Specific Instance.
 
-     In this case, only `dff0` will have the qb inverted output. Other instances of `dff` remain unchanged.
+  You can also modify a single instance of a module without affecting the others:
+
+  ```ruby
+  # Declare dff0 as an instance of dff
+  dff :dff0
+  
+  # Modify it
+  dff0.open do
+     output :qb
+     qb <= ~q
+  end
+  ```
+
+  In this case, only `dff0` will have the qb inverted output. Other instances of `dff` remain unchanged.
 
 In summary, HDLRuby supports:
 
@@ -1095,19 +1103,19 @@ system(:box) {}
 
 __Notes__:
 
- - Since this is Ruby code, the block can also be written using `do...end` syntax. In that case, parentheses around the name are optional:
+* Since this is Ruby code, the block can also be written using `do...end` syntax. In that case, parentheses around the name are optional:
  
 
-```ruby
-system :box do
-end
-```
+  ```ruby
+  system :box do
+  end
+  ```
 
- - Although HDLRuby internally stores names as Ruby symbols, you can also use strings. For example, the following is equally valid:
+* Although HDLRuby internally stores names as Ruby symbols, you can also use strings. For example, the following is equally valid:
 
-```ruby
-system("box") {}
-```
+  ```ruby
+  system("box") {}
+  ```
 
 ### Declaring a system with an interface
 
@@ -1307,9 +1315,9 @@ __Notes__:
 
 * By default:
    
-   - Ruby integers (e.g., `42`) are treated as 64-bit HDLRuby values.
+  * Ruby integers (e.g., `42`) are treated as 64-bit HDLRuby values.
 
-   - HDLRuby literals prefixed with `_` (e.g., `_b1010`, `_h0F`) have a bit-width corresponding to their representation.
+  * HDLRuby literals prefixed with `_` (e.g., `_b1010`, `_h0F`) have a bit-width corresponding to their representation.
 
 * When initializing ROM or arrays of values, make sure that the bit-width of the values matches the declared type -- otherwise, misalignments or synthesis issues may occur.
 
@@ -1582,17 +1590,17 @@ end
 
 __Notes__:
 
-  - `helse seq` ensures that the block of the hardware `else` is in blocking assignment mode.
+* `helse seq` ensures that the block of the hardware `else` is in blocking assignment mode.
 
-  - `hif(rst)` could also have been set to blocking assignment mode as follows:
-    
-    ```ruby
-       hif rst, seq do
-          reg <= 0
-       end
-    ```
+* `hif(rst)` could also have been set to blocking assignment mode as follows:
+   
+   ```ruby
+      hif rst, seq do
+         reg <= 0
+      end
+   ```
 
-  - non-blocking mode can be set the same way using `par`.
+* Non-blocking mode can be set the same way using `par`.
 
 
 ### Extra Features for the Description of Processes
@@ -2469,21 +2477,21 @@ In this declaration:
 
 * `programming_language` is a symbol indicating the language used for the software. Currently supported options are:
 
-  - `:ruby` -- for programs written in Ruby.
+  * `:ruby` -- for programs written in Ruby.
 
-  - `:c` --  for programs written in C. (In fact, any language that can be compiled into a shared library linkable with C is supported.)
+  * `:c` --  for programs written in C. (In fact, any language that can be compiled into a shared library linkable with C is supported.)
 
 * `function_name` is the name of the software function that is executed when an activation event occurs. Only one such function can be specified per program, but multiple programs can be declared within the same module.
 
 * `location of the software files and description of its interface` may include the following declarations:
 
-  - `actport <list of events>` -- Declares the events that activate the program (i.e., trigger execution of the program’s start function).
+  * `actport <list of events>` -- Declares the events that activate the program (i.e., trigger execution of the program’s start function).
 
-  - `inport <port_name: signal>` -- Declares input ports that can be read by the software.
+  * `inport <port_name: signal>` -- Declares input ports that can be read by the software.
 
-  - `outport <port_name: signal>` -- Declares output ports that the software can write to.
+  * `outport <port_name: signal>` -- Declares output ports that the software can write to.
 
-  - `code <list_of_filenames>` -- Specifies the software source file(s).
+  * `code <list_of_filenames>` -- Specifies the software source file(s).
 
 __Example:__
 
@@ -2508,9 +2516,9 @@ end
 
 __Notes:__ 
 
- * The bit width of an input or output port matches that of the signal it is connected to. From the software perspective, however, all port values are converted to the C type `long long`.
+* The bit width of an input or output port matches that of the signal it is connected to. From the software perspective, however, all port values are converted to the C type `long long`.
 
- * If the language is Ruby, the `code` section can use a Ruby `Proc` objecct in place of a file name.
+* If the language is Ruby, the `code` section can use a Ruby `Proc` objecct in place of a file name.
 
 
 
@@ -3369,9 +3377,9 @@ __Warnings__:
 
 * In the example above, the semantics of some_arrow change depending on the context in which it is called:
 
-  - Within a module: interpreted as a static connection.
+  * Within a module: interpreted as a static connection.
 
-  - Within a process: interpreted as a behavioral assignment.
+  * Within a process: interpreted as a behavioral assignment.
 
 * Using Ruby methods to describe hardware can lead to fragile or incorrect code if not used carefully. For example, consider the following:1
 
@@ -3398,21 +3406,21 @@ __Warnings__:
 
   In this case:
 
-  - `sys0` works correctly. 
+  * `sys0` works correctly. 
 
-  - `sys1` raises an error due to redeclaration of `in0`.
+  * `sys1` raises an error due to redeclaration of `in0`.
 
-  - `sys2` raises an error because `input` declarations are not allowed inside a process.
+  * `sys2` raises an error because `input` declarations are not allowed inside a process.
 
 __Using Ruby Method Features__
 
 Ruby methods in HDLRuby support all standard Ruby features, including:
 
- * Variadic arguments (`*args`)
+* Variadic arguments (`*args`)
 
- * Named (keyword) arguments
+* Named (keyword) arguments
 
- * Block arguments (`&block`)
+* Block arguments (`&block`)
 
 For example, the following method connects a single driver signal to multiple targets:
 
@@ -3804,11 +3812,11 @@ The available state kinds are:
 
 * `reset`: The state entered when the FSM is reset.
 
-  - If name is `:sync`, the reset is forced to be synchronous.
+  * If name is `:sync`, the reset is forced to be synchronous.
 
-  - If name is `:async`, the reset is forced to be asynchronous.
+  * If name is `:async`, the reset is forced to be asynchronous.
 
-  - If name is omitted, the mode defaults to that of the FSM.
+  * If name is omitted, the mode defaults to that of the FSM.
 
 * `state`: A regular state that follows the FSM’s default mode.
 
@@ -3977,6 +3985,10 @@ Parallel enumerators provide several control methods:
 
 * `+`: Concatenates two enumerators.
 
+Additionaly, it is possible to exit an enumeration loop using the following command:
+
+* `hbreak`: Exits the current enumeration loop.
+
 __Hardware Implementations of Enumerable Methods__
 
 Using parallel enumerators, HDLRuby provides hardware implementations of many Ruby Enumerable methods. These are available for any enumerable object and can be used inside or outside processes.
@@ -4149,7 +4161,7 @@ __Using Enumerators in Sequences__
 
 Within sequencer blocks, HDLRuby provides enumerator methods similar to Ruby’s `each`. These include:
 
-* `<object>.seach`: `object` can be any Ruby enumerable or HDLRuby signal. If a block is given, it behaves like sfor; otherwise, it returns an HDLRuby enumerator (see [enumerator](#hdlruby-enumerators-and-enumerable-objects-stdsequencerrb) for details).
+* `<object>.seach`: `object` can be any Ruby enumerable or HDLRuby signal. If a block is given, it behaves like sfor; otherwise, it returns an HDLRuby enumerator (see [enumerator](#hdlruby-enumerators-and-enumerable-objects) for details).
 
 * `<object>.stimes`: Can be used on integers and is equivalent to calling seach on the range `0..object-1`.
 
@@ -4894,9 +4906,9 @@ When a `sync` command is encountered during execution:
 
 * The paused sequencer can later be resumed by either:
 
-  - Calling it again using the call operator (`my_seq.()`), or
+  * Calling it again using the call operator (`my_seq.()`), or
 
-  - Setting its associated start signal to `1`.
+  * Setting its associated start signal to `1`.
 
 __Example: Pausing and Resuming a Sequencer__
 

data/ext/hruby_sim/hruby_rcsim_build.c

@@ -760,6 +760,8 @@ VALUE rcsim_make_unary(VALUE mod, VALUE type, VALUE operator, VALUE child) {
     switch(sym_to_char(operator)) {
         case (unsigned char)'~':         unary->oper = not_value; break;
         case (unsigned char)('-'+'@'*2): unary->oper = neg_value; break;
+        case (unsigned char)'|':   unary->oper = reduce_or_value; break;
+        case (unsigned char)'&':  unary->oper = reduce_and_value; break;
         default: perror("Invalid operator for unary.");
     }
     value_to_rcsim(ExpressionS,child,unary->child);

data/ext/hruby_sim/hruby_sim.h

@@ -252,6 +252,12 @@ extern Value not_value(Value src, Value dst);
  *  @return dst */
 extern Value reduce_or_value(Value src, Value dst);
 
+/** Compute the and of the bits a a value.
+ *  @param src the source value
+ *  @param dst the destination value
+ *  @return dst */
+extern Value reduce_and_value(Value src, Value dst);
+
 /** Computes the AND of two values.
  *  @param src0 the first source value of the and
  *  @param src1 the second source value of the and

data/ext/hruby_sim/hruby_sim_calc.c

@@ -1348,6 +1348,44 @@ Value reduce_or_value_bitstring(Value src, Value dst) {
     return dst;
 }
 
+/** Compute the and of the bits a bitstring value.
+ *  @param src the source value
+ *  @param dst the destination value
+ *  @return dst */
+Value reduce_and_value_bitstring(Value src, Value dst) {
+    /* Compute the width of the result in bits. */
+    unsigned long long width = type_width(src->type);
+
+    /* Update the destination capacity if required. */
+    resize_value(dst,width);
+    /* Set the type and size of the destination from the type of the source.*/
+    dst->type = src->type;
+    dst->numeric = 0;
+
+    /* Get access to the source and destination data. */
+    char* src_data = src->data_str;
+    char* dst_data = dst->data_str;
+
+    /* Performs the reduce or. */
+    unsigned long long count;
+    char res = 0;
+    for(count = 0; count < width; ++count) {
+        /* Performs the reduce and. */
+        char d = src_data[count] - '0'; /* Get and convert to bit. */
+        if ((d == (d&1)) && (res != 'x'-'0')) { /* d is defined. */
+            res &= d;
+        } else {
+            /* res is undefined. */
+            res = 'x' - '0';
+        }
+        /* Apart for the first bit, there are only 0, still we are in
+         * the loop, set it. */
+        dst_data[count] = '0';
+    }
+    dst_data[0] = res + '0';
+    /* Return the destination. */
+    return dst;
+}
 
 /** Computes the and of two bitstring values.
  *  @param src0 the first source value of the and
@@ -2280,6 +2318,21 @@ Value reduce_or_value_numeric(Value src, Value dst) {
     return dst;
 }
 
+/** Compute the and of the bits a numeric value.
+ *  @param src the source value
+ *  @param dst the destination value
+ *  @return dst */
+Value reduce_and_value_numeric(Value src, Value dst) {
+    /* Sets state of the destination using the first source. */
+    dst->type = src->type;
+    dst->numeric = 1;
+
+    /* Perform the reduce and. */
+    unsigned long long mask = ~(-1LL << type_width(src->type));
+    dst->data_int = fix_numeric_type(dst->type, (~src->data_int & mask) == 0);
+    return dst;
+}
+
 
 /** Computes the AND of two numeric values.
  *  @param src0 the first source value of the addition
@@ -3061,6 +3114,20 @@ Value reduce_or_value(Value src, Value dst) {
     }
 }
 
+/** Compute the and of the bits a value.
+ *  @param src the source value
+ *  @param dst the destination value
+ *  @return dst */
+Value reduce_and_value(Value src, Value dst) {
+    if (src->numeric) {
+        /* The source is numeric. */
+        return reduce_and_value_numeric(src,dst);
+    } else {
+        /* The source cannot be numeric, compute bitsitrings. */
+        return reduce_and_value_bitstring(src,dst);
+    }
+}
+
 
 /** Computes the AND of two general values. 
  *  @param src0 the first source value of the addition