README.html

<h1>About HDLRuby</h1>
<p>HDLRuby is a library for describing and simulating digital electronic
systems.</p>
<p><strong>Note</strong>:</p>
<p>If you want to learn how to describe a circuit with HDLRuby, please jump to the following section:</p>
<ul>
<li><p><a href="#hdlruby-programming-guide">HDLRuby Programming Guide</a></p>
<ul>
<li><p><a href="#introduction">Introduction</a></p>
</li>
<li><p><a href="#how-hdlruby-works">How HDLRuby Works</a></p>
</li>
<li><p><a href="#naming-rules">Naming rules</a></p>
</li>
<li><p><a href="#systems-and-signals">Systems and Signals</a></p>
</li>
<li><p><a href="#events">Events</a></p>
</li>
<li><p><a href="#statements">Statements</a></p>
</li>
<li><p><a href="#types">Types</a></p>
</li>
<li><p><a href="#expressions">Expressions</a></p>
</li>
<li><p><a href="#functions">Functions</a></p>
</li>
<li><p><a href="#software-code">Software code</a></p>
</li>
<li><p><a href="#time">Time</a></p>
</li>
<li><p><a href="#high-level-programming-features">High-Level Programming Features</a></p>
</li>
<li><p><a href="#extending-hdlruby">Extending HDLRuby</a></p>
</li>
</ul>
</li>
</ul>
<p>Many of HDLRuby's features are available through its standard libraries.
We strongly recommend consulting the corresponding section:</p>
<ul>
<li><p><a href="#standard-libraries">Standard Libraries</a></p>
<ul>
<li><p><a href="#clocks">Clocks</a></p>
</li>
<li><p><a href="#decoder">Decoder</a></p>
</li>
<li><p><a href="#fsm">FSM</a></p>
</li>
<li><p><a href="#parallel-enumerators">Parallel Enumerators</a></p>
</li>
<li><p><a href="#sequencer-software-like-hardware-coding">Sequencer (Software-like Hardware Coding)</a></p>
</li>
<li><p><a href="#fixed-point">Fixed-Point</a></p>
</li>
</ul>
</li>
</ul>
<p>Samples are also available: <a href="#sample-hdlruby-descriptions">Sample HDLRuby descriptions</a></p>
<p>Finally, HDLRuby can also process Verilog HDL files: <a href="#converting-verilog-hdl-to-hdlruby">Converting Verilog HDL to HDLRuby</a>.</p>
<p>If you are new to HDLRuby, we recommend starting with the following
tutorial even if you have a hardware background:</p>
<ul>
<li><a href="https://github.com/civol/HDLRuby/blob/master/tuto/tutorial_sw.md">HDLRuby Tutorial for Software People</a> [md]</li>
</ul>
<p>If you would prefer an HTML version, you can generate it by running the
following command. This will create a <code>tuto</code> folder containing all the
necessary files. Then, simply open <code>tuto/tutorial_sw.html</code>:</p>
<pre><code>hdrcc --get-tuto
</code></pre>
<p><strong>What's New</strong></p>
<p>For HDKRuby version 3.9.2:</p>
<ul>
<li>Added the <code>hbreak</code> command for exiting parallel enumerator loops.</li>
</ul>
<p>For HDLRuby version 3.9.0/3.9.1:</p>
<ul>
<li><p>Added the parallel enumerators to the software sequencers.</p>
</li>
<li><p>Added experimental TensorFlow code generation from the software sequencers.</p>
</li>
<li><p>Added the possibility to declare vectors of instances.</p>
</li>
<li><p>Added the possibility to fix the data type for the accumulation with the hinject and sinject enumerators.</p>
</li>
<li><p>Fixed various bugs.</p>
</li>
<li><p>Made an overhaul of the documentation.</p>
</li>
</ul>
<p>For HDLRuby version 3.8.3:</p>
<ul>
<li><p>Fixed various bugs including some in interactive mode.</p>
</li>
<li><p>Updated the documentation:</p>
<ul>
<li><p>Rewrote the beginning of the <a href="#hdlruby-programming-guide">HDLRuby Programming Guide</a>.</p>
</li>
<li><p>Updated the documentation for interactive mode.</p>
</li>
<li><p>Updated the <a href="#high-level-programming-features">High-Level Programming Features</a> chapter.</p>
</li>
</ul>
</li>
</ul>
<p>For HDLRuby version 3.8.0:</p>
<ul>
<li><p>Added parallel enumerators (e.g., heach), allowing Ruby-like iteration for describing parallel hardware.</p>
</li>
<li><p>Added genererive programming using standard HDLRuby constructs (e.g., hif) -- there is no need to use Ruby code directly any more.</p>
</li>
<li><p>Fixed compile bugs for windows.</p>
</li>
</ul>
<p>For HDLRuby version 3.7.9:</p>
<ul>
<li><p>Added Python code generation from software sequencers.</p>
</li>
<li><p>Added <a href="#parallel-enumerators">Parallel Enumerators</a>.</p>
</li>
</ul>
<p>For HDLRuby versions 3.7.7/3.7.8:</p>
<ul>
<li>Various fixes related to software sequencers.</li>
</ul>
<p>For HDLRuby version 3.7.6:</p>
<ul>
<li><p>Added initial value support for signals in software sequencers.</p>
</li>
<li><p>Fixed <code>hprint</code> in software sequencers.</p>
</li>
</ul>
<p>For HDLRuby versions 3.7.4/3.7.5:</p>
<ul>
<li>Various bug fixes.</li>
</ul>
<p>For HDLRuby version 3.7.3:</p>
<ul>
<li>Enabled use of software sequencers within HDLRuby's <code>program</code> construct, including use of program ports as if they were input or output signals.</li>
</ul>
<p>For HDLRuby version 3.7.2:</p>
<ul>
<li><p>Added the <code>text</code> command for software sequencers.</p>
</li>
<li><p>Added the <code>value_text</code> method to software sequencers signal, generating Ruby/C code with correct typing.</p>
</li>
<li><p>Added the <code>alive?</code> and <code>reset!</code> commands for HDLRuby sequencers.</p>
</li>
<li><p>Added the <code>require_ruby</code> method for loading Ruby (i.e., non-HDLRuby) libraries.</p>
</li>
</ul>
<p>For HDLRuby version 3.7.x:</p>
<ul>
<li>Added the possibility to run <a href="#sequencers-as-software-code">Sequencers in Software</a>. (WIP)
This enables significantly faster simulation and allows reusing the same code for both hardware and software design.</li>
</ul>
<p>For HDLRuby version 3.6.x:</p>
<ul>
<li><p>Added a new GUI board element allowing assignment of expressions to signals during simulation.</p>
</li>
<li><p>Added a new slider element for the GUI board (from 3.6.1).</p>
</li>
</ul>
<p>For HDLRuby version 3.5.0:</p>
<ul>
<li><p>Added direct support for Verilog HDL files as input to 'hdrcc'.</p>
</li>
<li><p>Added the ability to generate a graphical representation of the RTL code in SVG format using the '--svg' option for 'hdrcc'.</p>
</li>
</ul>
<p>For HDLRuby version 3.4.0:</p>
<ul>
<li><p>Improved synchronization between the browser-based graphical interface and the HDLRuby simulator.</p>
</li>
<li><p>Added a Verilog HDL parsing library for Ruby (to be released separately once stabilized).</p>
</li>
<li><p>Added a library for generating HDLRuby code from a Verilog HDL AST (produced by the parsing library).</p>
</li>
<li><p>Added <a href="#converting-verilog-hdl-to-hdlruby">v2hdr</a>, a standalone tool for converting Verilog HDL files to HDLRuby (experimental).</p>
</li>
<li><p>Added a HDLRuby command for <a href="#converting-verilog-hdl-to-hdlruby">loading a Verilog HDL file from a HDLRuby description</a>.</p>
</li>
</ul>
<p>For HDLRuby version 3.3.0:</p>
<ul>
<li><p>Redesigned the description of software components using the program construct.
The <code>Code</code> objects are now deprecated.</p>
</li>
<li><p>Added HW/SW co-simulation capability for Ruby and compiled C-compatible
software programs.</p>
</li>
<li><p>Added a browser-based graphical interface simulating a development board that interacts with the HDLRuby simulator.</p>
</li>
<li><p>Updated the documentation and tutorial accordingly, and fixed several typos.</p>
</li>
</ul>
<p>For HDLRuby version 3.2.0:</p>
<ul>
<li><p>Added components for declaring BRAM and BRAM-based stacks to enable efficient memory allocation in FPGAs.</p>
</li>
<li><p>Performed internal code overhaul in preparation for version 4.0.0.</p>
</li>
<li><p>Multiple bug fixes.</p>
</li>
</ul>
<p>For HDLRuby version 3.1.0:</p>
<ul>
<li><p>Added <a href="#sequencer-specific-functions">functions for sequencers</a>, including support for recursion.</p>
</li>
<li><p>Replaced the <code>function</code> keyword with <code>hdef</code> for consistency with sequencer functions (<code>sdef</code>).</p>
</li>
<li><p>Added the <code>steps</code> command for waiting multiple steps in a sequencer.</p>
</li>
<li><p>Improved Verilog HDL code generation to better preserve original signal names.</p>
</li>
<li><p>Several bug fixes for the sequencers.</p>
</li>
</ul>
<p>For HDLRuby version 3.0.0:</p>
<ul>
<li><p>Intruduced this changelog section.</p>
</li>
<li><p>Added <a href="#sequencer-software-like-hardware-coding">Sequencers</a> for software-like hardware design.</p>
</li>
<li><p>Added a <a href="tuto/tutorial_sw.md">tutorial</a> for software developers.</p>
</li>
<li><p>The stable <a href="#standard-libraries">Standard Libraries</a> are now loaded by
default.</p>
</li>
</ul>
<p><strong>Install</strong>:</p>
<p>The recommended method of installation is via RubyGems:</p>
<pre><code>gem install HDLRuby
</code></pre>
<p>Developers who wish to contribute to HDLRuby can install it from source using GitHub:</p>
<pre><code>git clone https://github.com/civol/HDLRuby.git
</code></pre>
<p><strong>Warning</strong>:</p>
<ul>
<li><p>HDLRuby is still under active development, and the API may change before a stable release.</p>
</li>
<li><p>It is highly recommended that users have a basic understanding of both the Ruby programming language and hardware description languages before using HDLRuby.</p>
</li>
</ul>
<h1>Compiling HDLRuby Descriptions</h1>
<h2>Using the HDLRuby Compiler</h2>
<p>'hdrcc' is the HDLRuby compiler. It takes an HDLRuby file as input, checks it, and can generate one of several outputs: Verilog HDL, VHDL, or a YAML low-level hardware component description. It can also simulate the input design.</p>
<p><strong>Usage</strong>:</p>
<pre><code>hdrcc [options] &lt;input file&gt; &lt;output/working directory&gt;
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>options</code> is a list of options (see below)</p>
</li>
<li><p><code>&lt;input file&gt;</code> is the input HDLRuby file to compile (mandatory)</p>
</li>
<li><p><code>&lt;output/working directory&gt;</code> is the directory where output and temporary files will be stored</p>
</li>
</ul>
<p>|  Options         |          |
|:------------------|:-----------------------------------------------------|
| <code>-I, --interactive</code> | Run in interactive mode                            |
| <code>-y, --yaml</code>      | Output in YAML format                                |
| <code>-v, --verilog</code>   | Output in Verilog HDL format                         |
| <code>-V, --vhdl</code>      | Output in VHDL format                                |
| <code>-s, --syntax</code>    | Output the Ruby syntax tree                          |
| <code>-C, --clang</code>     | Output the C code of the standalone simulator        |
| <code>-S, --sim</code>       | Perform the simulation with the default engine       |
| <code>--csim</code>          | Perform the simulation with the standalone engine    |
| <code>--rsim</code>          | Perform the simulation with the Ruby engine          |
| <code>--rcsim</code>         | Perform the simulation with the Hybrid engine        |
| <code>--vcd</code>           | Make the simulator generate a VCD (waveform) file               |
| <code>--svg</code>           | Output a graphical representation of the RTL (SVG format) |
| <code>-d, --directory</code> | Specify the base directory for loading the HDLRuby files |
| <code>-D, --debug</code>     | Set the HDLRuby debug mode |
| <code>-t, --top system</code>| Specify the top system describing the circuit to compile |
| <code>-p, --param x,y,z</code>     | Specify the generic parameters                 |
| <code>--get-samples</code>   | Copy the <code>hdr_samples</code> directory to the current directory, then exit |
| <code>--version</code>       | Show the version number, then exit                  |
| <code>-h, --help</code>      | Show the help message                                    |</p>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>If no top system is specified, it will be automatically inferred from the input file.</p>
</li>
<li><p>If no options are provided, the compiler will only check the input file for correctness.</p>
</li>
<li><p>If you're new to HDLRuby, or want to see working examples of new features, we strongly recommend downloading the sample files:</p>
<pre><code class="language-bash">hdrcc --get-samples
</code></pre>
<p>This will create a <code>hdr_samples</code> subdirectory in your current folder, containing various HDLRuby example files. For more details, see the <a href="#sample-hdlruby-descriptions">samples</a>.</p>
</li>
</ul>
<p><strong>Examples</strong>:</p>
<ul>
<li>Compile <code>adder.rb</code> and generate a low-level Verilog HDL description in the <code>adder</code> directory:</li>
</ul>
<pre><code class="language-bash">hdrcc -v adder.rb adder
</code></pre>
<ul>
<li>Compile the Verilog HDL file <code>adder8.v</code>, using <code>adder8</code> as the top module, and generate a graphical RTL diagram in the <code>view</code> directory:</li>
</ul>
<pre><code class="language-bash">hdrcc adder8.v -t adder8 --svg view
</code></pre>
<ul>
<li>Compile a parameterized system <code>multer</code> from <code>multer_gen.rb</code>, generating a 16x16-&gt;32-bit YAML hardware description into the <code>multer</code> directory:</li>
</ul>
<pre><code class="language-bash">hdrcc -V -t adder --param 16 adder_gen.rb adder
</code></pre>
<ul>
<li>Compile system <code>multer</code> with inputs and output bit width is generic from <code>multer_gen.rb</code> input file to a 16x16-&gt;32-bit circuit whose low-level YAML description into directory <code>multer</code>:</li>
</ul>
<pre><code class="language-bash">hdrcc -y -t multer -p 16,16,32 multer_gen.rb multer
</code></pre>
<ul>
<li>Simulate the circuit described in <code>counter_bench.rb</code> using the default simulation engine, outputting files to the <code>counter</code> directory:</li>
</ul>
<pre><code class="language-bash">hdrcc -S counter_bench.rb counter
</code></pre>
<p>Note: The default simulation engine is set to the fastest available engine (currently, the hybrid engine).</p>
<ul>
<li>Run in interactive mode.</li>
</ul>
<pre><code class="language-bash">hdrcc -I
</code></pre>
<ul>
<li>Run in interactive mode using pry as UI.</li>
</ul>
<pre><code class="language-bash">hdrcc -I pry
</code></pre>
<h2>Using HDLRuby in Interactive Mode</h2>
<p>When run in interactive mode, the HDLRuby framework launches a REPL (Read-Eval-Print Loop) environment and creates a working directory named HDLRubyWorkspace. By default, the REPL is irb, but it can also be set to pry.</p>
<p>Within the interactive prompt, you can write HDLRuby code just as you would in a standard HDLRuby source file. In addition, a set of special commands is available to compile, inspect, and simulate your design interactively:</p>
<h4>Available Commands</h4>
<ul>
<li>Compile an HDLRuby module (with optional parameters):</li>
</ul>
<pre><code class="language-ruby">hdr_make(&lt;module&gt;[,&lt;parameters])
</code></pre>
<ul>
<li>Display the internal representation (IR) of the compiled module in YAML format:</li>
</ul>
<pre><code class="language-ruby">hdr_yaml
</code></pre>
<ul>
<li>Reconstruct and display the HDLRuby source description of the compiled module:</li>
</ul>
<pre><code class="language-ruby">hdr_hdr
</code></pre>
<ul>
<li>Generate and save Verilog HDL output to the <code>HDLRubyWorkspace</code> directory:</li>
</ul>
<pre><code class="language-ruby">hdr_verilog
</code></pre>
<ul>
<li>Generate and save VHDL output to the HDLRubyWorkspace directory:</li>
</ul>
<pre><code class="language-ruby">hdr_vhdl
</code></pre>
<ul>
<li>Simulate the compiled module:</li>
</ul>
<pre><code class="language-ruby">hdr_sim
</code></pre>
<ul>
<li>Simulate the compiled module and save the VCD trace (waveform output) to  the directory <code>HDLRubyWorkspace</code>:</li>
</ul>
<pre><code>hdr_sim_vcd
</code></pre>
<ul>
<li>Simulate the compiled module in mute mode:</li>
</ul>
<pre><code>hdr_sim_mute
</code></pre>
<h2>HDLRuby files.</h2>
<p>Since HDLRuby is built on top of the Ruby language, it is standard convention to name HDLRuby files with the <code>.rb</code> extension.</p>
<p>For the same reason, including external HDLRuby files is done using the Ruby <code>methods require</code> or <code>require_relative</code>, which behave the same way as in standard Ruby. However, these methods can only be used to include HDLRuby description files, not plain Ruby files.</p>
<p>To include standard Ruby code (e.g., helper libraries or tools), you must use the methods <code>require_ruby</code> or <code>require_relative_ruby</code>.</p>
<h1>HDLRuby programming guide</h1>
<p>HDLRuby is designed to bring the flexibility and expressiveness of the Ruby language to hardware description, while ensuring that the resulting designs remain synthesizable. The abstractions provided by HDLRuby are meant to aid in describing hardwareÑbut they do not alter the underlying execution model, which is RTL (Register Transfer Level) by construction.</p>
<p>Another key feature of HDLRuby is its native support for all features of the Ruby language.</p>
<p><strong>Notes</strong>:</p>
<ul>
<li>It is possible to extend HDLRuby to support hardware descriptions at a higher level of abstraction than RTL. See <a href="#extending-hdlruby">Extending HDLRuby</a> for more details.</li>
<li>Throughout this guide, HDLRuby constructs are often compared to their Verilog HDL or VHDL equivalents to aid understanding.</li>
</ul>
<h2>Introduction</h2>
<p>This introduction gives a glimpse of what HDLRuby makes possible.</p>
<p>At first glance, HDLRuby resembles other hardware description languages such as Verilog HDL or VHDL. For example, the following code describes a simple D flip-flop:</p>
<pre><code class="language-ruby">system :dff do
   bit.input :clk, :rst, :d
   bit.output :q

   par(clk.posedge) do
      q &lt;= d &amp; ~rst
   end
end
</code></pre>
<p>In this example, <code>system</code> is the keyword used to define a hardware component, similar to the <code>module</code> construct in Verilog HDL. Signals are declared using a <code>&lt;type&gt;.&lt;direction&gt;</code> format, where <code>type</code> is the data type (e.g., <code>bit</code>) and direction indicates the signal's role (<code>input</code>, <code>output</code>, <code>inout</code>, or <code>inner</code>). Processes, like Verilog's <code>always</code> blocks, are described using the <code>par</code> keyword for non-blocking assignments and <code>seq</code> for blocking assignments.</p>
<p>Here is a second example: an 8-bit adder.</p>
<pre><code class="language-ruby">system :adder8 do
   bit[7..0].input :x, :y
   bit[7..0].output :z
   bit.output :cout

   [cout,z] &lt;= x.as(bit[8..0]) + y
end
</code></pre>
<p>This example demonstrates how to declare vector types. The signals <code>x</code>, <code>y</code>, and <code>z</code> are 8-bit unsigned vectors. If signed values are needed, you would use <code>signed</code> instead of <code>bit</code>.</p>
<p>Line 6 illustrates a connection (similar to the <code>assign</code> statement in Verilog HDL), where <code>cout</code> and <code>z</code> are concatenated and connected to the result of an addition. Note that <code>x</code> is explicitly cast to a 9-bit value to preserve the carry-out. In HDLRuby, unlike Verilog HDL, operand types are strictly preserved. This means that adding two 8-bit values yields an 8-bit result unless explicitly extended. The goal is to avoid the type-related ambiguities found in Verilog, while keeping syntax lighter than VHDL.</p>
<p>Conditional statements, common in RTL languages, are also supported in HDLRuby. However, unlike in Verilog or VHDL, HDLRuby conditionals can appear anywhere in a system body—not just within processes.</p>
<p>These include:</p>
<ul>
<li><p><code>hif</code> / <code>helsif</code> / <code>helse</code> for <code>if</code>-like conditionals</p>
</li>
<li><p><code>hcase</code> / <code>hwhen</code> / <code>helse</code> for <code>case</code>-like conditionals</p>
</li>
<li><p><code>mux</code>, an expression-level construct for multiplexers, which supports multiple inputs, unlike the ?: ternary operator in Verilog, which only handles two</p>
</li>
</ul>
<p><strong>Note</strong>:  These statements are also called &quot;parallel conditionals&quot; in HDLRuby, to contrast with the ones used in the <code>sequencer</code> constructs (see <a href="#sequencer-software-like-Hardware-coding">Sequencer</a>).</p>
<p>For example, we can upgrade the 8-bit adder to an adder-subtractor:</p>
<pre><code class="language-ruby">system :adder_suber8 do
   bit.input :addbsub
   bit[7..0].input :x, :y
   bit[7..0].output :z
   bit.output :cout

   hif(addbsub) { [cout,z] &lt;= x.as(bit[8..0]) + ~y + 1 }
   helse        { [cout,z] &lt;= x.as(bit[8..0]) + y }
end
</code></pre>
<p>The conditional logic above can also be written more compactly using the <code>mux</code> expression:</p>
<pre><code class="language-ruby">  [cout,z] &lt;= x.as(bit[8..0]) + mux(addbsub, y, ~y + 1)
</code></pre>
<hr>
<p>Once a module has been described, it can be instantiated. For example, a single instance of the <code>dff</code> module named <code>dff0</code> can be declared as follows:</p>
<pre><code class="language-ruby">dff :dff0
</code></pre>
<p>The ports of the instance can be accessed like regular signals. For example, <code>dff0.d</code> refers to the d input of the flip-flop.</p>
<p>You can also connect the ports of an instance at the time of declaration. The example above can be extended as follows:</p>
<pre><code class="language-ruby">system :counter2 do
   bit.input :clk, :rst
   bit.output :q

   dff(:dff0).(clk: clk, rst: rst, d: ~dff0.q)
   dff(:dff1).(~dff0.q, rst, ~dff1.q, q)
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>dff0</code> uses named connections for its ports (e.g., <code>clk: clk</code>).</p>
</li>
<li><p><code>dff1</code> uses positional connections, in the order the ports were declared in the module.</p>
</li>
</ul>
<p>It is also possible to connect only a subset of the ports at instantiation time, and to reconnect or override ports later in the code.</p>
<hr>
<p>To simulate a circuit, you must write a test bench using <code>timed</code> constructs, which describe how signals evolve over time.</p>
<p>Here is an example that simulates the D flip-flop <code>dff</code> using a 20 ns clock, and toggles the input <code>d</code> every two clock cycles for ten iterations:</p>
<pre><code class="language-ruby">system :dff_bench do
   
   dff :dff0

   timed do
      dff0.clk &lt;= 0
      dff0.rst &lt;= 1
      !10.ns
      dff0.clk &lt;= 1
      !10.ns
      dff0.clk &lt;= 0
      dff0.rst &lt;= 0
      dff0.d   &lt;= 1
      !10.ns
      repeat(10) do
         repeat(4) { !10.ns ; dff0.clk &lt;= ~dff0.clk }
         dff0.d   &lt;= ~dff0.d
      end
   end
end
</code></pre>
<p>In this code:</p>
<ul>
<li><p><code>!&lt;time&gt;.&lt;unit&gt;</code> pauses execution for the specified physical time. Units can range from picoseconds (<code>ps</code>) to seconds (<code>s</code>).</p>
</li>
<li><p><code>repeat(n)</code> repeats the block <code>n</code> times.</p>
</li>
<li><p><code>~dff0.clk</code> inverts the clock value.</p>
</li>
</ul>
<p>This test bench models both the reset behavior and a clock-driven sequence, demonstrating how to simulate sequential logic in HDLRuby.</p>
<hr>
<p>The <code>dff</code> example shown earlier is quite similar to what you would write in other HDLs. However, HDLRuby offers several features to increase productivity and reduce boilerplate in hardware descriptions. Below are a few of these conveniences.</p>
<p>First, HDLRuby supports syntactic sugar that allows for more concise code. For example, the following version of the <code>dff</code> module is functionally identical to the earlier version:</p>
<pre><code class="language-ruby">system :dff do
   input :clk, :rst, :d
   output :q

   (q &lt;= d &amp; ~rst).at(clk.posedge)
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p>The <code>bit</code> type is omitted for signal declarations (it is the default type).</p>
</li>
<li><p>Since the process contains only a single statement, it is expressed more compactly using the <code>at</code> method.</p>
</li>
</ul>
<p>Similarly, the <code>adder8</code> module can be written more concisely:</p>
<pre><code class="language-ruby">system :adder8 do
   [8].input :x, :y
   [8].output :z
   output :cout

   [cout,z] &lt;= x.as(bit[9]) + y
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p>The vector range <code>[7..0]</code> is abbreviated to <code>[8]</code>, which implies an 8-bit width.</p>
</li>
<li><p>The <code>bit</code> type is omitted for signal declarations (again, because it is the default).</p>
</li>
<li><p><strong>Note</strong>: when casting a signal or using it in expressions where type precision matters, the bit type must still be explicitly specified, as seen in <code>bit[9]</code>.</p>
</li>
</ul>
<hr>
<p>Second, HDLRuby also provides high-level constructs that make it easier to describe complex structures and behaviors in hardware.</p>
<p>For example, the <code>sequencer</code> construct allows to describe finite state
machines using software code-like statements, including conditionals,
loops and function calls. For example the following module describes a
simple 8-bit serializing circuit that emmits bit every 10 clock cycle.</p>
<pre><code class="language-ruby">system :serial do
  [8].input :din
  input :clk, :rst, :req
  output :ack, :bout

  [8].inner :buf

  bout &lt;= buf[0]

  sequencer(clk,rst) do
    sloop do
      ack &lt;= 0 ; buf &lt;= 0
      swhile(~req)
      buf &lt;= din ; ack &lt;= 1
      8.stimes do
        buf &lt;= buf &gt;&gt; 1
        9.stimes
      end
    end
  end
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>sequencer(clk, rst)</code> creates a clocked finite-state machine initialized on reset <code>(rst = 1)</code>.</p>
</li>
<li><p><code>sloop</code> is an infinite loop.</p>
</li>
<li><p><code>swhile(condition)</code> loops until the condition becomes false; if it has no body, it waits passively.</p>
</li>
<li><p><code>stimes(n)</code> is a shorthand for looping a block <code>n</code> times.</p>
</li>
<li><p>Each control-flow step in a sequencer (even inside loops) corresponds to one clock cycle, making timing behavior explicit and predictable.</p>
</li>
</ul>
<p>This example uses <code>buf</code> to hold the 8-bit input and shift it right each cycle to serialize it bit by bit onto the <code>bout</code> output.</p>
<p>Other HDLRuby high-level contructs includes:</p>
<ul>
<li><p>Iterators (both parallel and sequential)</p>
</li>
<li><p>Decoders</p>
</li>
<li><p>Fixed-point arithmetic</p>
</li>
<li><p>And more...</p>
</li>
</ul>
<p>These high-level abstractions are built on synthesizable foundations, and help keep hardware descriptions clear, maintainable, and concise, especially for complex control logic.</p>
<hr>
<p>Third, HDLRuby supports generic parameters that can be used flexibly to define reusable hardware modules. These parameters can represent sizes, types, or any other construct needed to generalize a design.</p>
<p>For instance, the following example defines a simple, fixed-size 8-bit register:</p>
<pre><code class="language-ruby">system :reg8 do
   input :clk, :rst
   [8].input :d
   [8].output :q

   (q &lt;= d &amp; [~rst]*8).at(clk.posedge)
end
</code></pre>
<p>To make this register size configurable, you can introduce a parameter. In this version, <code>n</code> defines the bit width of the register:</p>
<pre><code class="language-ruby">system :regn do |n|
   input :clk, :rst
   [n].input :d
   [n].output :q

   (q &lt;= d &amp; [~rst]*n).at(clk.posedge)
end
</code></pre>
<p>Going further, you can define a fully generic register by parameterizing not just the size, but the data type itself (e.g., signed, fixed-point, structs, etc.):</p>
<pre><code class="language-ruby">system :reg do |typ|
   input :clk, :rst
   typ.input :d
   typ.output :q

   (q &lt;= d &amp; [~rst]*typ.width).at(clk.posedge)
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>typ</code> is used as a type object (e.g., <code>bit[8]</code>, <code>signed[16]</code>, etc.).</p>
</li>
<li><p><code>typ.width</code> returns the number of bits associated with the type, allowing the reset mask (<code>[~rst] * typ.width</code>) to scale automatically.</p>
</li>
</ul>
<hr>
<p>Fourth, HDLRuby allows you to extend modules and instances after their declaration. This makes it easy to add new features without duplicating code.</p>
<p>Let us say you want to extend an existing <code>dff</code> module to include an inverted output (<code>qb</code>). There are three ways to do this:</p>
<ol>
<li>Inheriting from a Module.</li>
</ol>
<p>You can define a new system that inherits from the existing <code>dff</code>:</p>
<pre><code class="language-ruby">system :dff_full, dff do
   output :qb
   qb &lt;= ~q
end
</code></pre>
<p>This creates a new module <code>dff_full</code> that includes all the functionality of <code>dff</code>, with the additional inverted output.</p>
<ol start="2">
<li>Reopening a Module.</li>
</ol>
<p>You can modify the original <code>dff</code> module after its declaration using the open method:</p>
<pre><code class="language-ruby">dff.open do
   output :qb
   qb &lt;= ~q
end
</code></pre>
<p>This approach modifies <code>dff</code> itself, and the added behavior (<code>qb &lt;= ~q</code>) will apply to all future instances of <code>dff</code>.</p>
<ol start="3">
<li>Reopening a Specific Instance.</li>
</ol>
<p>You can also modify a single instance of a module without affecting the others:</p>
<pre><code class="language-ruby"># Declare dff0 as an instance of dff
dff :dff0

# Modify it
dff0.open do
   output :qb
   qb &lt;= ~q
end
</code></pre>
<p>In this case, only <code>dff0</code> will have the qb inverted output. Other instances of <code>dff</code> remain unchanged.</p>
<p>In summary, HDLRuby supports:</p>
<ul>
<li><p>Inheritance: for creating extended modules from existing ones</p>
</li>
<li><p>Module reopening: to modify a module after declaration</p>
</li>
<li><p>Instance reopening: to customize individual instances</p>
</li>
</ul>
<hr>
<p>Fifth, HDLRuby allows you to instantiate components in groups, similar to how signals are grouped in arrays. This enables scalable and readable hardware descriptions using familiar Ruby-style iteration.</p>
<pre><code class="language-ruby">system :shifter do |n|
   input :clk, :rst
   input :i0
   output :o0, :o0b

   dff_full :dffr

   dffr.clk &lt;= clk

   # Instantiating n D-FF
   dff_full[n,:dffIs]

   # Connect the clock and the reset.
   dffIs.heach { |ff| ff.clk &lt;= clk ; ff.rst &lt;= rst }

   # Interconnect them as a shift register
   dffIs[0..-1].heach_cons(2) { |ff0,ff1| ff1.d &lt;= ff0.q }

   # Connects the input and output of the circuit
   dffIs[0].d &lt;= i0
   o0 &lt;= dffIs[-1].q
   o0b &lt;= dffIs[-1].qb
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>dff_full[n, :dffIs]</code> creates an array of <code>n</code> instances named <code>dffIs</code>.</p>
</li>
<li><p><code>heach</code> iterates over each instance in parallel.</p>
</li>
<li><p><code>heach_cons(2)</code> creates overlapping pairs (like a sliding window) to wire the flip-flops together.</p>
</li>
</ul>
<p>If you don¿t need a specific subcomponent like <code>dff_full</code>, you can describe the shift register more concisely using a bit vector:</p>
<pre><code class="language-ruby">system :shifter do |n|
   input :clk, :rst
   input :i0
   output :o0
   [n].inner :sh
   
   par (clk.posedge) do
      hif(rst) { sh &lt;= 0 }
      helse { sh &lt;= ((sh &lt;&lt; 1)|i0) }
   end
   
   o0 &lt;= sh[n-1]
end
</code></pre>
<p>This version:</p>
<ul>
<li><p>Uses a single <code>n</code>-bit inner register (<code>sh</code>) to store the shift state.</p>
</li>
<li><p>Updates the register each clock cycle, inserting <code>i0</code> at the least significant bit.</p>
</li>
<li><p>Outputs the most significant bit (<code>sh[n-1]</code>).</p>
</li>
</ul>
<hr>
<p>HDLRuby supports many more advanced features that enable concise, flexible, and reusable hardware descriptions. The following examples showcase how you can use generic parameters, functional abstractions, and custom types in practice.</p>
<p>Suppose you want to build a circuit that computes a sum of products between several inputs and constant coefficients. For example, with four signed 16-bit inputs and coefficients 3, 4, 5, 6, a basic HDLRuby implementation looks like this:</p>
<pre><code class="language-ruby">system :sumprod_16_3456 do
   signed[16].input :i0, :i1, :i2, :i3
   signed[16].output :o
   
   o &lt;= i0*3 + i1*4 + i2*5 + i3*6
end
</code></pre>
<p>This works, but lacks flexibility. Changing the bit width or coefficients requires rewriting the entire module. It also becomes error-prone with large coefficient sets.</p>
<p>A better approach is to create a generic system:</p>
<pre><code class="language-ruby">system :sumprod do |typ,coefs|
   typ[-coefs.size].input :ins
   typ.output :o
   
   o &lt;= coefs.hzip(ins).hreduce(0) do |sum,(i,c)|
      sum + i*c
   end
end
</code></pre>
<p>In this version:</p>
<ul>
<li><p><code>typ</code> defines the data type (e.g., <code>signed[32]</code>)</p>
</li>
<li><p><code>coefs</code> is an array of constant coefficients</p>
</li>
<li><p><code>ins</code> is an array of inputs with size <code>coefs.size</code></p>
</li>
<li><p><code>[-coefs.size]</code> is shorthand for declaring an array indexed in the forward direction (<code>[0..coefs.size - 1]</code>)</p>
</li>
<li><p><code>hzip</code> pairs each input with its coefficient (like Ruby¿s <code>zip</code>)</p>
</li>
<li><p><code>hreduce</code> accumulates the products into a final sum (like Ruby¿s <code>reduce</code>)</p>
</li>
</ul>
<p>This version supports any number of coefficients and any data type.
Example instantiation (with 16 coefficients):</p>
<pre><code class="language-ruby">sumprod(signed[32], 
        [3,78,43,246, 3,67,1,8,
         47,82,99,13, 5,77,2,4]).(:my_circuit)  
</code></pre>
<p><strong>Note</strong>: when passing generic arguments, the instance name (:my_circuit) goes after the parameters, in parentheses.</p>
<p>While the description <code>sumprod</code> is already usable in a wide range of
cases you may want to use specialized operations (e.g., saturated arithmetic) instead of standard <code>+</code> and <code>*</code>. You can do this by replacing operators with functions:</p>
<pre><code class="language-ruby">system :sumprod_func do |typ,coefs|
   typ[-coefs.size].input :ins
   typ.output :o
   
   o &lt;= coefs.hzip(ins).hreduce(0) do |sum,(c,i)|
      add(sum, mult(i,c))
   end
end
</code></pre>
<p>Now you define your custom <code>add</code> and <code>mult</code> functions. For example, an addition with saturation at 1000:</p>
<pre><code class="language-ruby">hdef :add do |x,y|
   inner :res
   seq do
      res &lt;= x + y
      hif(res &gt; 1000) { res &lt;= 1000 }
   end
   res
end
</code></pre>
<p>With HDLRuby functions, the value returned is the result of the last statement, here <code>res</code>.</p>
<p>To avoid hardcoding saturation values, functions can accept extra arguments:</p>
<pre><code class="language-ruby">hdef :add do |max, x, y|
   inner :res
   seq do
      res &lt;= x + y
      hif(res &gt; max) { res &lt;= max }
   end
   res
end
</code></pre>
<p>You would then call it like:</p>
<pre><code class="language-ruby">add(1000,sum,mult(...))
</code></pre>
<p>However, this becomes cumbersome if your functions take inconsistent argument counts. A better approach is to pass code (lambdas or procs) as parameters:</p>
<pre><code class="language-ruby">system :sumprod_proc do |add,mult,typ,coefs|
   typ[coefs.size].input :ins
   typ.output :o
   
   o &lt;= coefs.hzip(ins).hreduce(0) do |sum,(c,i)|
      add.(sum, mult.(i*c))
   end
end
</code></pre>
<p><strong>Note</strong>: When calling a proc in HDLRuby, use <code>.()</code> instead of regular parentheses.</p>
<p>Example usage:</p>
<pre><code class="language-ruby">sumprod_proc( 
        proc { |x,y| add_sat(1000,x,y) },
        proc { |x,y| mult_sat(1000,x,y) },
        signed[64], 
        [3,78,43,246, 3,67,1,8,
         47,82,99,13, 5,77,2,4]).(:my_circuit)
</code></pre>
<p>This lets you reconfigure the arithmetic logic without changing the core circuit.</p>
<p>As second possible approach, HDLRuby also allows you to define custom data types with redefined operators:</p>
<pre><code>signed[16].typedef(:sat16_1000)

sat16_1000.define_operator(:+) do |x,y|
   tmp = x + y
   mux(tmp &gt; 1000,tmp,1000)
end
</code></pre>
<p>In the code above:</p>
<ul>
<li><p>The first line defines the new type <code>sat16_1000</code> to be
16-bit signed,</p>
</li>
<li><p>The <code>define_operator</code> method overloads (redefines) the <code>+</code> operator
for this type.</p>
</li>
</ul>
<p>Then use your original <code>sumprod</code> with this type:</p>
<pre><code class="language-ruby">sumprod(sat16_1000, 
        [3,78,43,246, 3,67,1,8,
        47,82,99,13, 5,77,2,4]).(:my_circuit)
</code></pre>
<p>You can also define generic types with parameters:</p>
<pre><code class="language-ruby">typedef :sat do |width, max|
   signed[width]
end

sat.define_operator(:+) do |width,max, x,y|
   tmp = x + y
   mux(tmp &gt; max, tmp, max)
end
</code></pre>
<p>Now you can instantiate saturated arithmetic with custom precision and bounds:</p>
<pre><code class="language-ruby">sumprod(sat(16,1000), 
        [3,78,43,246, 3,67,1,8,
         47,82,99,13, 5,77,2,4]).(:my_circuit)
</code></pre>
<p><strong>Note</strong>: Any parameters used in a type definition must also be listed when overloading operators.</p>
<h2>How HDLRuby works</h2>
<p>Unlike high-level HDLs such as SystemVerilog, VHDL, or SystemC, HDLRuby descriptions are not direct descriptions of hardware. Instead, they are Ruby programs that generate hardware descriptions.</p>
<p>In traditional HDLs, executing the code (e.g., in a simulator) simulates the behavior of the described circuit. In contrast, executing HDLRuby code produces a low-level hardware description, which can then be synthesized or simulated like any standard HDL.</p>
<p>This separation between:</p>
<ul>
<li><p>the user-facing description (written in HDLRuby), and</p>
</li>
<li><p>the internal hardware representation (handled by <code>HDLRuby::Low</code>)</p>
</li>
</ul>
<p>allows HDLRuby to incorporate advanced programming features¿such as iterators, generics, and metaprogramming -- without affecting the synthesizability of the resulting hardware description.</p>
<hr>
<p>In HDLRuby, each construct does not directly describe hardware. Instead, it generates a hardware description. For example, consider the following line:</p>
<pre><code class="language-ruby">   a &lt;= b
</code></pre>
<p>This expression creates a connection from signal <code>b</code> to signal <code>a</code>. When this line is executed (remember, HDLRuby code runs as Ruby code), it generates an instance of <code>HDLRuby::Low::Connection</code> -- the internal object representing that hardware connection.</p>
<p>Its execution will produce the actual hardware description of this connection as an object of the <code>HDLRuby::Low library</code> in this case, an instance of the <code>HDLRuby::Low::Connection</code> class. Concretely, an HDLRuby system is described by a Ruby block, and the instantiation of this system is performed by executing this block. The actual synthesizable description of this hardware is the execution result of this instantiation.</p>
<p>More generally:</p>
<ul>
<li><p>an HDLRuby module (<code>system</code>) is defined using a Ruby block.</p>
</li>
<li><p>When the module is instantiated, the block is executed.</p>
</li>
<li><p>The result of that execution is a complete, synthesizable hardware description in the internal <code>HDLRuby::Low</code> format.</p>
</li>
</ul>
<p>This architecture -- where Ruby is used to dynamically generate HDL constructs -- makes HDLRuby extremely flexible and expressive, while still producing valid, low-level HDL for synthesis or simulation</p>
<p>From here, we will begin to explore HDLRuby’s core constructs in more detail.</p>
<h2>Naming Rules</h2>
<p>Several constructs in HDLRuby -- such as modules and signals -- are identified by names. These names must be specified using Ruby symbols that begin with a lowercase letter.</p>
<p>For example:</p>
<ul>
<li><p><code>:hello</code> -&gt; valid</p>
</li>
<li><p><code>:Hello</code> -&gt; invalid (starts with an uppercase letter)</p>
</li>
</ul>
<p>Once declared, the construct is referred to by the name without the colon (<code>:</code>). That is, a construct declared as <code>:hello</code> will later be referenced simply as <code>hello</code>.</p>
<h2>Systems and Signals</h2>
<p>In HDLRuby, a <em>system</em> represents a digital module, similar to a module in Verilog HDL. A system includes:</p>
<ul>
<li><p>An interface (comprising <code>input</code>, <code>output</code>, and <code>inout</code> signals),</p>
</li>
<li><p>as well as structural and behavioral descriptions of the circuit.</p>
</li>
</ul>
<p>A signal represents a piece of state within a system. Each signal has:</p>
<ul>
<li><p>a data type, and</p>
</li>
<li><p>a value that can change over time.</p>
</li>
</ul>
<p>HDLRuby signals abstract both wires and registers:</p>
<ul>
<li><p>If a signal's value is explicitly assigned at all times, it behaves like a wire.</p>
</li>
<li><p>If the value is updated conditionally or based on clocked logic, it behaves like a register.</p>
</li>
</ul>
<h3>Declaring an Empty System</h3>
<p>A system is declared using the <code>system</code> keyword. It must be given a name (as a Ruby symbol or string) and a block that defines its contents.</p>
<p>For example, the following code declares an empty system named <code>box</code>:</p>
<pre><code class="language-ruby">system(:box) {}
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>Since this is Ruby code, the block can also be written using <code>do...end</code> syntax. In that case, parentheses around the name are optional:</p>
<pre><code class="language-ruby">system :box do
end
</code></pre>
</li>
<li><p>Although HDLRuby internally stores names as Ruby symbols, you can also use strings. For example, the following is equally valid:</p>
<pre><code class="language-ruby">system(&quot;box&quot;) {}
</code></pre>
</li>
</ul>
<h3>Declaring a system with an interface</h3>
<p>A system's interface defines how it communicates with the outside world. It consists of <code>input</code>, <code>output</code>, and <code>inout</code> signals, each of a specified data type.</p>
<p>While interface declarations can appear anywhere in the system body, it is recommended to place them at the beginning for clarity.</p>
<p>Interface signals are declared using the following pattern:</p>
<pre><code class="language-ruby">&lt;data type&gt;.&lt;direction&gt; :name1, :name2, ...
</code></pre>
<p>For example, to declare a 1-bit input signal named <code>clk</code>:</p>
<pre><code class="language-ruby">bit.input :clk
</code></pre>
<p>Since <code>bit</code> is the default data type in HDLRuby, it can be omitted:</p>
<pre><code class="language-ruby">input :clk
</code></pre>
<p>Here is a more complete example: the following defines a simple memory module. It has:</p>
<ul>
<li><p>a 1-bit clock input (<code>clk</code>)</p>
</li>
<li><p>a 1-bit read/write control input (<code>rwb</code>, where 1 = read, 0 = write)</p>
</li>
<li><p>a 16-bit address input (<code>addr</code>)</p>
</li>
<li><p>an 8-bit bidirectional data bus (<code>data</code>)</p>
</li>
</ul>
<pre><code class="language-ruby">system :mem8_16 do
    input :clk, :rwb
    [15..0].input :addr
    [7..0].inout :data

    bit[7..0][2**16].inner :content
    
    par(clk.posedge) do
        hif(rwb) { data &lt;= content[addr] }
        helse    { content[addr] &lt;= data }
    end
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p>The memory content is declared as an array of <code>2**16</code> 8-bit words.</p>
</li>
<li><p>On each rising edge of <code>clk</code>, the module either reads from or writes to memory depending on the value of <code>rwb</code>.</p>
</li>
</ul>
<h3>Structural description in a system</h3>
<p>In HDLRuby, structural descriptions define how subsystems (i.e., instances of other systems) are instantiated and interconnected.</p>
<p>To instantiate a system, use the following syntax:</p>
<pre><code class="language-ruby">&lt;system name&gt; :&lt;instance name&gt;
</code></pre>
<p>For example, to instantiate the <code>mem8_16</code> system:</p>
<pre><code class="language-ruby">mem8_16 :mem8_16I
</code></pre>
<p>You can also declare multiple instances at once:</p>
<pre><code class="language-ruby">mem8_16 [:mem8_16I0, :mem8_16I1]
</code></pre>
<p>Or create an array of instances:</p>
<pre><code class="language-ruby">mem8_16[5,:mem8_18Is] # Creates an array of 5 instances named mem8_16Is
</code></pre>
<p>To interconnect subsystems, you'll often need internal signals. These are declared using the inner direction:</p>
<pre><code class="language-ruby">inner :w1
[1..0].inner :w2
</code></pre>
<p>If a signal is constant (i.e., its value never changes), use constant instead of inner.</p>
<p>When signals are declared, use the assignment operator &lt;= to define connections:</p>
<pre><code class="language-ruby">&lt;destination&gt; &lt;= &lt;source&gt;
</code></pre>
<p>For example:</p>
<pre><code class="language-ruby">ready &lt;= w1         # Connects internal w1 to ready
w2[0] &lt;= clk        # Assigns clk to the first bit of w2
w2[1] &lt;= clk &amp; rst  # Assigns AND of clk and rst to w2[1]
</code></pre>
<p>You can also refer to the ports of an instance using the dot operator:</p>
<pre><code class="language-ruby">&lt;instance name&gt;.&lt;signal name&gt;
</code></pre>
<p>For example:</p>
<pre><code class="language-ruby">mem8_16I.clk &lt;= clk
</code></pre>
<p>Alternatively, you can connect multiple ports at once using the call operator <code>.()</code> with named arguments:</p>
<pre><code class="language-ruby">mem8_16I.(clk: clk, rwb: rwb)
</code></pre>
<p>This also allows partial connections (e.g., leaving out addr or data).
But you can also list the connections in order of port decleration:</p>
<pre><code>mem8_16I.(clk, rwb, addr, data)
</code></pre>
<p>You can even connect ports inline at instantiation:</p>
<pre><code class="language-ruby">mem8_16(:mem8_16I).(clk: clk, rwb: rwb)
</code></pre>
<p>The following system uses two 8-bit memory modules (mem8_16) to construct a 16-bit wide memory by splitting the data bus:</p>
<pre><code class="language-ruby">system :mem16_16 do
   input :clk, :rwb
   [15..0].input :addr
   [15..0].inout :data

   mem8_16(:memL).(clk: clk, rwb: rwb, addr: addr, data: data[7..0])
   mem8_16(:memH).(clk: clk, rwb: rwb, addr: addr, data: data[15..8])
end
</code></pre>
<p>The same can be written using the dot operator and individual assignments:</p>
<pre><code class="language-ruby">system :mem16_16 do
   input :clk, :rwb
   [15..0].input :addr
   [15..0].inout :data

   mem8_16 [:memL, :memH]

   memL.clk  &lt;= clk
   memL.rwb  &lt;= rwb
   memL.addr &lt;= addr
   memL.data &lt;= data[7..0]

   memH.clk  &lt;= clk
   memH.rwb  &lt;= rwb
   memH.addr &lt;= addr
   memH.data &lt;= data[15..8]
end
</code></pre>
<h3>Initialization of signals</h3>
<p>In HDLRuby, output, inner, and constant signals can be initialized at the time of declaration using the following syntax:</p>
<pre><code class="language-ruby">&lt;signal name&gt;: &lt;intial value&gt;
</code></pre>
<p>For example, the following declares a 1-bit inner signal named sig initialized to 0:</p>
<pre><code class="language-ruby">inner sig: 0
</code></pre>
<p>The following, declares and initialize an 8-word, 8-bit ROM (read-only memory):</p>
<pre><code class="language-ruby">bit[8][-8] rom: [ _h00,_h01,_h02,_h03,_h04,_h05,_h06,_h07 ]
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>The notation <code>_hXY</code> represents an explicit 8-bit hexadecimal value where <code>X</code> and <code>Y</code> are hex digits (e.g., <code>_h0A</code> is an 8-bit 10).</p>
</li>
<li><p>By default:</p>
<ul>
<li><p>Ruby integers (e.g., <code>42</code>) are treated as 64-bit HDLRuby values.</p>
</li>
<li><p>HDLRuby literals prefixed with <code>_</code> (e.g., <code>_b1010</code>, <code>_h0F</code>) have a bit-width corresponding to their representation.</p>
</li>
</ul>
</li>
<li><p>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.</p>
</li>
</ul>
<h3>Scope in a system</h3>
<h4>General scopes</h4>
<p>HDLRuby uses scopes to control the visibility of signals and instances. Understanding scopes helps avoid naming conflicts and improves modularity and readability. As general rule:</p>
<ul>
<li><p>Interface signals (<code>input</code>, <code>output</code>, <code>inout</code>) are globally accessible from anywhere within the system where they are declared.</p>
</li>
<li><p>Inner signals (<code>inner</code>) and instances are local to the scope in which they are declared and cannot be accessed outside of it.</p>
</li>
</ul>
<p>A scope is a region of code where declared objects (signals, instances, etc.) are visible. Each system has its own top-level scope, and scopes can be nested.</p>
<p>For example, the following system has only a top-level scope:</p>
<pre><code class="language-ruby">system :div2 do
   input :clk
   output :q
   
   inner :d, :qb
   d &lt;= qb
   
   dff_full(:dffI).(clk: clk, d: d, q: q, qb: qb)
   
</code></pre>
<p>In this example, signals <code>d</code> and <code>qb</code> and the instance <code>dffI</code> are accessible only within system <code>div2</code>.</p>
<p>You can define additional inner scopes using the <code>sub</code> keyword:</p>
<pre><code class="language-ruby">sub do
   # Local declarations and code
end
</code></pre>
<p>This is useful for organizing code or isolating declarations. Objects declared inside a sub block are not accessible outside of it.</p>
<p>For example, the following system includes a one-level nested scope:</p>
<pre><code class="language-ruby">system :sys do
   ...
   sub
      inner :sig
      # sig is accessible here
   end
   # sig is not accessible here
end
</code></pre>
<p>And the following system includes two-level nested scopes:</p>
<pre><code class="language-ruby">system :sys do
   ...
   sub
      inner :sig0
      # sig0 is accessible here
      sub
         inner :sig1
         # sig0 and sig1 are accessible here
      end
      # sig1 is not accessible here
   end
   # Neither sig0 nor sig1 are accessible here
end
</code></pre>
<p>There rules for name collisions are the following:</p>
<ul>
<li><p>Within the same scope, you cannot declare two signals or instances with the same name.</p>
</li>
<li><p>However, inner scopes may reuse names already declared in outer scopes. In such cases, the innermost declaration takes precedence.</p>
</li>
</ul>
<h4>Named scopes</h4>
<p>You can assign a name to a scope:</p>
<pre><code class="language-ruby">sub :&lt;name&gt; do
   ...
end
</code></pre>
<p>Signals and instances declared within a named scope can be accessed from outside using dot notation: <code>&lt;scope_name&gt;.&lt;object_name&gt;</code></p>
<p>For example:</p>
<pre><code class="language-ruby">sub :scop do
   inner :sig
   ...
end
...
# Access sig from outside its scope.
scop.sig &lt;= ...
</code></pre>
<h3>Behavioral description in a system.</h3>
<p>In HDLRuby, behavioral descriptions is done using processes which are declared using either:</p>
<ul>
<li><p><code>par</code> for non-blocking execution (like Verilog <code>always</code> with <code>&lt;=</code>)</p>
</li>
<li><p><code>seq</code> for blocking execution (like Verilog <code>always</code> with <code>=</code>)</p>
</li>
</ul>
<p>A process consists of:</p>
<ul>
<li><p>a sensitivity list (i.e., a list of events that trigger it)</p>
</li>
<li><p>a block of statements</p>
</li>
</ul>
<p>The general syntax is as follows:</p>
<pre><code class="language-ruby">par &lt;list of events&gt; do
   &lt;statements&gt;
end

seq &lt;list of events&gt; do
   &lt;statements&gt;
end
</code></pre>
<p>Each process is activated when any event in its sensitivity list occurs. An event corresponds to a change in a signal, such as:</p>
<ul>
<li><p><code>posedge</code> -- rising edge</p>
</li>
<li><p><code>negedge</code> -- falling edge</p>
</li>
<li><p><code>anyedge</code> -- any edge (can be ommitted)</p>
</li>
</ul>
<p>For example:</p>
<pre><code class="language-ruby">par(clk.posedge) do
   # This block runs on every rising edge of clk
   ...
end
</code></pre>
<p>The sensitivity list is evaluated at runtime, and processes are executed once per activation.
See <a href="#events">Events</a> for more details.</p>
<p>Statements include assingments, conditionals and blocks.
You can also declare inner signals within these statements; they will be local to the current process.
Statements are described in more detail in section <a href="#statements">statements</a>. In this section, we focus on assignment statements and block statements.</p>
<p>An assignment statement is declared using the arrow operator <code>&lt;=</code> as follows:</p>
<pre><code class="language-ruby">&lt;destination&gt; &lt;= &lt;source&gt;
</code></pre>
<p>The <code>destination</code> must be a reference to a signal, and the <code>source</code> can be any expression.
An assignment has the same structure as a connection. However, its execution model is different: while a connection is continuously executed, an assignment is only executed during the execution of its block.</p>
<p>A block comprises a list of statements and is used to add hierarchy to a process.
Blocks can use either blocking or non-blocking assignments.
By default, a top-level block is created when declaring a process, and it inherits its execution mode. For example, in the following code, the top block uses blocking assignments:</p>
<pre><code class="language-ruby">system :with_blocking_process do
   seq do
      &lt;list of statements&gt;
   end
end
</code></pre>
<p>It is possible to declare new blocks within an existing block.
To declare a sub-block with the same execution mode as its parent, use the keyword <code>sub</code>. For example, the following code declares a sub-block within a seq block, inheriting the same execution mode:</p>
<pre><code class="language-ruby">system :with_blocking_process do
   seq do
      &lt;list of statements&gt;
      sub do
         &lt;list of statements&gt;
      end
   end
end
</code></pre>
<p>A sub-block can also use a different execution mode by explicitly using <code>seq</code> (for blocking assignments) or <code>par</code> (for non-blocking execution).
For example, the following code declares a <code>par</code> sub-block inside a <code>seq</code> block:</p>
<pre><code class="language-ruby">system :with_par_in_seq_process do
   seq do
      &lt;list of statements&gt;
      par do
         &lt;list of statements&gt;
      end
   end
end
</code></pre>
<p>Sub-blocks have their own scope, so it is possible to declare signals without name collisions.
For example, the following code declares three different inner signals, all named <code>sig</code>:</p>
<pre><code class="language-ruby">...
par(&lt;sensibility list&gt;) do
   inner :sig
   ...
   sub do
      inner :sig
      ...
      sub do
         inner :sig
         ...
      end
   end
   ...
end
</code></pre>
<p>To summarize this section, here is a behavioral description of a 16-bit shift register with asynchronous reset (<code>hif</code> and <code>helse</code> are keywords used for specifying hardware <code>if</code> and <code>else</code> control statements).</p>
<pre><code class="language-ruby">system :shift16 do
   input :clk, :rst, :din
   output :dout

   [15..0].inner :reg

   dout &lt;= reg[15] # The output is the last bit of the register.

   par(clk.posedge) do
      hif(rst) { reg &lt;= 0 }
      helse do
         reg[0] &lt;= din
         reg[15..1] &lt;= reg[14..0]
      end
   end
end
</code></pre>
<p>In the example above, the order of assignment statements does not matter.
However, this is not the case in the following example, which implements the same register using a <code>seq</code> block.</p>
<p>In this second example, placing the statement <code>reg[0] &lt;= din</code> last would result in incorrect shift register behavior:</p>
<pre><code class="language-ruby">system :shift16 do
   input :clk, :rst, :din
   output :dout

   [15..0].inner :reg

   dout &lt;= reg[15] # The output is the last bit of the register.

   par(clk.posedge) do
      hif(rst) { reg &lt;= 0 }
      helse seq do
         reg[0] &lt;= din
         reg &lt;= reg[14..0]
      end
   end
end
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p><code>helse seq</code> ensures that the block of the hardware <code>else</code> is in blocking assignment mode.</p>
</li>
<li><p><code>hif(rst)</code> could also have been set to blocking assignment mode as follows:</p>
<pre><code class="language-ruby">   hif rst, seq do
      reg &lt;= 0
   end
</code></pre>
</li>
<li><p>Non-blocking mode can be set the same way using <code>par</code>.</p>
</li>
</ul>
<h3>Extra Features for the Description of Processes</h3>
<h4>Single-Statement Processes</h4>
<p>It often happens that a process contains only one statement.  In such cases, the description can be shortened using the <code>at</code> operator as follows:</p>
<pre><code class="language-ruby">( statement ).at(&lt;list of events&gt;)
</code></pre>
<p>For example, the following two code samples are equivalent:</p>
<pre><code class="language-ruby">par(clk.posedge) do
   a &lt;= b+1
end
</code></pre>
<pre><code class="language-ruby">( a &lt;= b+1 ).at(clk.posedge)
</code></pre>
<p>For the sake of consistency, this operator can also be applied to block statements, as shown below. However, this usage is likely less readable than the standard process declaration:</p>
<pre><code class="language-ruby">( seq do
     a &lt;= b+1
     c &lt;= d+2
  end ).at(clk.posedge)
</code></pre>
<h4>Insertion of Statements at the Beginning of a Block</h4>
<p>By default, statements in a block are added in the order in which they appear in the code. However, it is also possible to insert statements at the beginning of the current block using the <code>unshift</code> command, as follows:</p>
<pre><code class="language-ruby">unshift do
   &lt;list of statements&gt;
end
</code></pre>
<p>For example, the following code inserts two statements at the beginning of the current block:</p>
<pre><code class="language-ruby">par do
   x &lt;= y + z
   unshift do
      a &lt;= b - c
      u &lt;= v &amp; w
    end
end
</code></pre>
<p>The code above will result in the following block:</p>
<pre><code class="language-ruby">par do
   a &lt;= b - c
   u &lt;= v &amp; w
   x &lt;= y + z
end
</code></pre>
<p><strong>Note</strong>: While this feature has little practical use for simple circuit descriptions, it can be useful in advanced generic component descriptions.</p>
<!-- ### Reconfiguration

In HDLRuby, dynamically reconfigurable devices are modeled by instances having more than one system. Adding systems to an instance is done as follows:

```ruby
<instance>.choice(<list of named systems>)
```

For example, assuming systems `sys0`, `sys1`, and `sys2` have been previously declared a device named `dev012` able to be reconfigured to one of these three systems would be declared as follows (the connections of the instance, omitted in the example, can be done as usual):

```ruby
sys0 :dev012 # dev012 is at first a standard instance of sys0
dev012.choice(conf1: sys1, conf2: sys2) # Now dev012 is reconfigurable
```

After the code above, instance `dev012` can be dynamically reconfigured to `sys0`, `sys1`, and `sys2` with respective names `dev012`, `conf1`, and `conf2`.

__Note:__
The name of the initial system in the reconfigurations is set to be the name of the instance.

A reconfigurable instance can then be reconfigured using the command `configure` as follows:

```ruby
<instance>.configure(<name or index>)
```

In the code above, the argument of `configure` can either be the name of the configuration as previously declared with `choice`, or its index in order of declaration. For example in the following code, instance `dev012` is reconfigured to system `sys1`, then system `sys0` the system `sys2`:

```ruby
dev012.configure(:conf1)
!1000.ns
dev012.configure(:dev012)
!1000.ns
dev012.configure(2)
```

These reconfiguration commands are treated as regular RTL statements in HDLRuby and are supported by the simulator. However, in the current version of the HDLRuby, these statements are ignored when generating Verilog HDL or VHDL code.
-->
<h2>Events</h2>
<p>Each process of a system is associated with a list of events, called a sensitivity list, that specifies when the process is to be executed. An event is associated with a signal and represents the instant when the signal reaches a given state.</p>
<p>There are three kinds of events:</p>
<ul>
<li><p><strong>Positive edge events</strong>, which occur when a signal transitions from 0 to 1.</p>
</li>
<li><p><strong>Negative edge events</strong>, which occur when a signal transitions from 1 to 0.</p>
</li>
<li><p><strong>Change events</strong>, which occur whenever the signal changes, regardless of direction.</p>
</li>
</ul>
<p>Events are declared directly from the signals, using the <code>posedge</code> operator for a positive edge, the <code>negedge</code> operator for a negative edge, and the <code>anyedge</code> operator for any change. For example, the following code declares 3 processes activated respectively on the positive edge, the negative edge, and any change of the <code>clk</code> signal:</p>
<pre><code class="language-ruby">inner :clk

par(clk.posedge) do
...
end

par(clk.negedge) do
...
end

par(clk.anyedge) do
...
end
</code></pre>
<p><strong>Note:</strong> The <code>anyedge</code> keyword can be omitted.</p>
<h2>Statements</h2>
<p>Statements are the basic elements of a behavioral description. They are regrouped in blocks that specify their execution mode (non-blocking or blocking assignments).
There are four kinds of statements: the assignment statement which computes expressions and sends the result to the target signals, the control statement which changes the execution flow of the process, the block statement (described earlier), and the inner signal declaration.</p>
<p>Statements are the fundamental elements of a behavioral description. They are grouped into blocks that specify their execution mode—either non-blocking or blocking assignments.</p>
<p>There are four types of statements:</p>
<ul>
<li><p><strong>Assignment statements</strong>, which compute expressions and assign the results to target signals.</p>
</li>
<li><p><strong>Control statements</strong>, which alter the execution flow of a process.</p>
</li>
<li><p><strong>Block statements</strong>, which group multiple statements and were described earlier.</p>
</li>
<li><p><strong>Inner signal declarations</strong>, which define signals local to a process or block.</p>
</li>
</ul>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>A fifth type of statement, called a <em>time statement</em>, will be discussed in the <a href="#time">Time</a> section.</p>
</li>
<li><p>Unlike in other HDLs such as Verilog or VHDL, statements in this language are not restricted to processes.</p>
</li>
</ul>
<h3>Assignment Statement</h3>
<p>An assignment statement is written using the arrow operator <code>&lt;=</code> within a process. Its right-hand side is the expression to be computed, and its left-hand side is a reference to the target signals (or parts of signals) -- i.e., the signals (or signal slices) that will receive the result of the computation.</p>
<p>For example, the following code assigns the value <code>3</code> to the signal <code>s0</code>, and assigns the sum of signals <code>i0</code> and <code>i1</code> to the first four bits of signal s1:</p>
<pre><code class="language-ruby">s0 &lt;= 3
s1[3..0] &lt;= i0 + i1
</code></pre>
<p>The behavior of an assignment statement depends on the execution mode of the enclosing block:</p>
<ul>
<li><p>If the mode is non-blocking, the target signals are updated after all statements in the current block have been processed.</p>
</li>
<li><p>If the mode is blocking, the target signals are updated immediately after the expression on the right-hand side is evaluated.</p>
</li>
</ul>
<h3>Control Statements</h3>
<p>There are two types of control statements in HDLRuby: the hardware if (<code>hif</code>) and the hardware case (<code>hcase</code>).</p>
<h4>hif</h4>
<p>The <code>hif</code> construct consists of a condition and a block that is executed if -- and only if -- the condition is true. It is declared as follows, where the condition can be any expression:</p>
<pre><code class="language-ruby">hif &lt;condition&gt; do
   &lt;block contents&gt;
end
</code></pre>
<h4>hcase</h4>
<p>The <code>hcase</code> construct consists of an expression and a list of value-block pairs. A block is executed when its corresponding value matches the value of the <code>hcase</code> expression. It is declared as follows:</p>
<pre><code class="language-ruby">hcase &lt;expression&gt;
hwhen &lt;value 0&gt; do
   &lt;block contents 0&gt;
end
hwhen &lt;value 1&gt; do
   &lt;block contents 1&gt;
end
...
</code></pre>
<h4>helse</h4>
<p>You can add a block that is executed when the condition of an <code>hif</code> is not met, or when no case in an hcase matches, using the <code>helse</code> keyword:</p>
<pre><code class="language-ruby">&lt;hif or hcase construct&gt;
helse do
   &lt;block contents&gt;
end
</code></pre>
<h4>helsif</h4>
<p>In addition to <code>helse</code>, you can define additional conditions in an <code>hif</code> using the <code>helsif</code> keyword:</p>
<pre><code class="language-ruby">hif &lt;condition 0&gt; do
   &lt;block contents 0&gt;
end
helsif &lt;condition 1&gt; do
   &lt;block contents 1&gt;
end
...
</code></pre>
<h4>About loops</h4>
<p>Outside of sequencer, HDLRuby -- like other HDLs -- does not support runtime looping constructs. It is important not to confuse constructs like Verilog's generate, which are not actual loops but rather generative code structures. Similarly, HDLRuby supports generative loops through parallel enumerators. See the <a href="#parallel-enumerators">Parallel Enumerators</a> section for more information.</p>
<h2>Types</h2>
<p>Each signal and expression in HDLRuby is associated with a data type that defines the kind of value it can represent. In HDLRuby, data types represent bit vectors, along with the way they should be interpreted -- i.e., as bit strings, unsigned values, signed values, or hierarchical structures.</p>
<h3>Type Construction</h3>
<p>There are five basic types, <code>bit</code>, <code>signed</code>, <code>unsigned</code>, <code>integer</code>, and <code>float</code> that represent respectively single bit logical values, single-bit unsigned values, single-bit signed values, Ruby integer values, and Ruby floating-point values (double precision). The first three types are HW and support four-valued logic, whereas the two last ones are SW (but are compatible with HW) and only support Boolean logic. Ruby integers can represent any element of <strong>Z</strong> (the mathematical integers) and have for that purpose a variable bit-width.</p>
<p>There are five basic types in HDLRuby: <code>bit</code>, <code>signed</code>, <code>unsigned</code>, <code>integer</code>, and <code>float</code>. These represent, respectively:</p>
<ul>
<li><p>Single-bit logical values (<code>bit</code>)</p>
</li>
<li><p>Single-bit unsigned values (<code>unsigned</code>), equivalent to <code>bit</code></p>
</li>
<li><p>Single-bit signed values (<code>signed</code>)</p>
</li>
<li><p>Ruby integer values (<code>integer</code>)</p>
</li>
<li><p>Ruby floating-point values in double precision (<code>float</code>), not supported for simulation or synthesis yet</p>
</li>
</ul>
<p>The first three types are hardware types and support four-valued logic (<code>0</code>, <code>1</code>, <code>Z</code>, and <code>X</code>), while the last two are software types. Although software types are compatible with hardware types, they support only Boolean logic.</p>
<p>Additional types can be constructed using a combination of the following two type operators:</p>
<p><strong>The vector operator</strong> <code>[]</code></p>
<p>This operator is used to build types that represent vectors of elements, either of a single type or a tuple of multiple types.</p>
<ul>
<li><p>A uniform vector (all elements of the same type) is declared as:</p>
<pre><code class="language-ruby">&lt;type&gt;[&lt;range&gt;]
</code></pre>
<p>The <code>range</code> specifies the index of the most and least significant bits. A range such as <code>n..0</code> can also be written as <code>n+1</code>. For example, the following two declarations are equivalent:</p>
<pre><code class="language-ruby">bit[7..0]
bit[8]
</code></pre>
</li>
<li><p>A tuple (vector of different types) is declared using square brackets with a list of types:</p>
<pre><code class="language-ruby">[&lt;type 0&gt;, &lt;type 1&gt;, ... ]
</code></pre>
<p>For example, the following defines a tuple containing an 8-bit logical value, a 16-bit signed value, and a 16-bit unsigned value:</p>
<pre><code class="language-ruby">[ bit[8], signed[16], unsigned[16] ]
</code></pre>
</li>
</ul>
<p><strong>The structure operator</strong> <code>{}</code></p>
<p>This operator defines hierarchical types made up of named subtypes. It is used as follows:</p>
<pre><code class="language-ruby">{ &lt;name 0&gt;: &lt;type 0&gt;, &lt;name 1&gt;: &lt;type 1&gt;, ... }
</code></pre>
<p>For instance, the following defines a structure with two fields: an 8-bit <code>header</code> and a 24-bit <code>data</code>:</p>
<pre><code class="language-ruby">{ header: bit[7..0], data: bit[23..0] }
</code></pre>
<h3>Type definition</h3>
<p>You can assign names to type constructs using the <code>typedef</code> method:</p>
<pre><code class="language-ruby">&lt;type construct&gt;.typedef :&lt;name&gt;
</code></pre>
<p>For example, the following code defines <code>char</code> as a signed 8-bit type:</p>
<pre><code class="language-ruby">signed[7..0].typedef :char
</code></pre>
<p>After this, <code>char</code> can be used like any other type. For instance, the following declares an input signal <code>sig</code> of type <code>char</code>:</p>
<pre><code class="language-ruby">char.input :sig
</code></pre>
<p>Alternatively, a new type can be defined using a block:</p>
<pre><code class="language-ruby">typedef :&lt;type name&gt; do
   &lt;code&gt;
end
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>type name</code> is the name of the type</p>
</li>
<li><p><code>code</code> is a description of the content of the type</p>
</li>
</ul>
<p>For example, the <code>char</code> type could also be defined as:</p>
<pre><code class="language-ruby">typedef :char do
   signed[7..0]
end 
</code></pre>
<h3>Type compatibility and conversion</h3>
<p>All HDLRuby types are ultimately based on bit vectors, where each bit can hold one of four values: <code>0</code>, <code>1</code>, <code>Z</code>, or <code>X</code>. Bit vectors are unsigned by default, but can be explicitly set to signed.</p>
<p>When performing operations involving signals of different bit-vector types, the shorter signal is automatically extended to match the length of the longer one, preserving its sign if it is signed.</p>
<p>Even though all types in HDLRuby are ultimately bit vectors, complex types can be defined. When such types are used in computational expressions or assignments, they are implicitly converted to unsigned bit vectors of equivalent size.</p>
<h2>Expressions</h2>
<p>Expressions are constructs that represent values associated with types.
They include <a href="#immediate-values">immediate values</a>, <a href="#references">reference to signals</a> and operations involving other expressions using <a href="#expression-operators">expression operators</a>.</p>
<h3>Immediate values</h3>
<p>mmediate values in HDLRuby can represent vectors of type <code>bit</code>, <code>unsigned</code>, or <code>signed</code>, as well as <code>integer</code> or <code>float</code> numbers. They are prefixed with an underscore (<code>_</code>) and include a header indicating the vector type and the numeric base, followed by the actual number.</p>
<p>By default, the bit width is inferred from the length of the numeral, but it can also be explicitly specified in the header. Underscores (<code>_</code>) can be inserted anywhere within the number to improve readability—they are ignored by the parser.</p>
<p><strong>Vector type specifiers</strong></p>
<ul>
<li><p><code>b</code>: <code>bit</code> type (can be omitted)</p>
</li>
<li><p><code>u</code>: <code>unsigned</code> type (equivalent to <code>b</code>; provided to avoid confusion with the binary base specifier)</p>
</li>
<li><p><code>s</code>: <code>signed</code> type (the last digit is sign-extended if required for binary, octal, or hexadecimal bases, but not for decimal)</p>
</li>
</ul>
<p><strong>Base specifiers</strong></p>
<ul>
<li><p><code>b</code>: binary</p>
</li>
<li><p><code>o</code>: octal</p>
</li>
<li><p><code>d</code>: decimal</p>
</li>
<li><p><code>h</code>: hexadecimal</p>
</li>
</ul>
<p><strong>Examples</strong></p>
<p>All the following immediate values represent the value <code>100</code>, using different bases and types, all encoded as 8-bit values:</p>
<pre><code class="language-ruby">_bb01100100
_b8b110_0100
_u8d100
_s8d100
_uh64
_s8o144
</code></pre>
<p>You may omit either the type specifier (default: <code>bit</code>) or the base specifier (default: binary). For example, all of the following also represent 8-bit unsigned values equal to <code>100</code>:</p>
<pre><code class="language-ruby">_b01100100
_h64
_o144
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>The form <code>_01100100</code> was previously treated as equivalent to <code>_b01100100</code>, but due to compatibility issues with recent versions of Ruby, it is now deprecated.</p>
</li>
<li><p>You may also use Ruby-style immediate values. Their bit width will be automatically adjusted to match the data type of the expression in which they are used. Note, however, that this adjustment may change the value. For example, in the following code, sig is assigned the value <code>4</code> (not <code>100</code>):</p>
<pre><code class="language-ruby">[3..0].inner :sig
sig &lt;= 100
</code></pre>
</li>
</ul>
<h3>References</h3>
<p>References are expressions used to designate signals or a part of signals.</p>
<p>The simplest reference is the name of a signal. It refers to the signal with that name in the current scope. For example, in the following code, the inner signal <code>sig0</code> is declared, and the name <code>sig0</code> then becomes a reference to that signal:</p>
<pre><code class="language-ruby"># Declaration of signal sig0.
inner :sig0

# Access to signal sig0 using a name reference.
sig0 &lt;= 0
</code></pre>
<p>To refer to a signal in another system, or to a sub-signal within a hierarchical signal, use the dot (<code>.</code>) operator:</p>
<pre><code class="language-ruby">&lt;parent name&gt;.&lt;signal name&gt;
</code></pre>
<p>For instance, in the following code, the input signal <code>d</code> of system instance <code>dff0</code> is connected to the <code>sub0</code> field of the hierarchical signal <code>sig</code>:</p>
<pre><code class="language-ruby">system :dff do
   input :clk, :rst, :d
   output :q

   par(clk.posedge) { q &lt;= d &amp; ~rst }
end

system :my_system do
   input :clk, :rst
   { sub0: bit, sub1: bit}.inner :sig
   
   dff(:dff0).(clk: clk, rst: rst)
   dff0.d &lt;= sig.sub0
   ...
end
</code></pre>
<h3>Expression operators</h3>
<p>The following table summarizes the operators available in HDLRuby. More details are provided in the subsequent sections for each group of operators.</p>
<p><strong>Assignment Operators (left-most operator of a statement):</strong></p>
<p>|       symbol       | description               |
| :---          | :---                             |
| <code>&lt;=</code>          | Connection (outside a process)   |
| <code>&lt;=</code>          | Assingment (inside a process)    |</p>
<p><strong>Arithmetic Operators:</strong></p>
<p>|       symbol       | description               |
| :---          | :---                          |
| <code>+</code>           | Addition                      |
| <code>-</code>           | Subtraction                   |
| <code>*</code>           | Multiplication                |
| <code>/</code>           | Division                      |
| <code>%</code>           | Modulo                        |
| <code>**</code>          | Power                         |
| <code>+@</code>          | Unary plus (identity)         |
| <code>-@</code>          | Negation                      |</p>
<p><strong>Comparison Operators:</strong></p>
<p>|       symbol       | description               |
| :---          | :---                          |
| <code>==</code>          | Equality                      |
| <code>!=</code>          | Inequality                    |
| <code>&gt;</code>           | Greater than                  |
| <code>&lt;</code>           | Less than                     |
| <code>&gt;=</code>          | Greater than or equal         |
| <code>&lt;=</code>          | Less than or equal            |</p>
<p><strong>Logic and Shift Operators:</strong></p>
<p>|       symbol       | description               |
| :---          | :---                          |
| <code>&amp;</code>           | Bitwise/logical AND           |
| <code>|</code>           | Bitwise/logical OR            |
| <code>~</code>           | Bitwise/logical NOT           |
| <code>mux</code>         | Multiplex                     |
| <code>&lt;&lt;</code>/<code>ls</code>     | Left shift                    |
| <code>&gt;&gt;</code>/<code>rs</code>     | Right shift                   |
| <code>lr</code>          | Left rotate                   |
| <code>rr</code>          | Right rotate                  |</p>
<p><strong>Conversion Operators:</strong></p>
<p>|       symbol       | description               |
| :---          | :---                          |
| <code>to_bit</code>      | Cast to bit vector            |
| <code>to_unsigned</code> | Cast to unsigned vector       |
| <code>to_signed</code>   | Cast to signed vector         |
| <code>to_big</code>      | cast to big-endian            |
| <code>to_little</code>   | cast to little endian         |
| <code>reverse</code>     | Reverse the bit order         |
| <code>ljust</code>       | Increase width from the left, preserving the sign  |
| <code>rjust</code>       | increase width from the right, preserving the sign |
| <code>zext</code>        | zero extension (converts to unsigned if signed)    |
| <code>sext</code>        | sign extension (converts to sign if unsigned)      |</p>
<p><strong>Selection/Concatenation Operators:</strong></p>
<p>|       symbol       | description               |
| :---          | :---                          |
| <code>[]</code>          | sub-vector selection          |
| <code>@[]</code>         | concatenation operator        |
| <code>.</code>           | field selection               |</p>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>Operator precedence in HDLRuby follows Ruby’s operator precedence rules.</p>
</li>
<li><p>Ruby does not allow overriding of the <code>&amp;&amp;</code>, <code>||</code>, or <code>?:</code> (ternary) operators, so they are not available in HDLRuby.</p>
<ul>
<li><p>Instead of the <code>?:</code> operator, HDLRuby provides the more general mux (multiplexer) operator.</p>
</li>
<li><p>HDLRuby does not provide replacements for <code>&amp;&amp;</code> and <code>||</code>; see the <a href="#logic-and-shift-operators">Logic and Shift Operators</a> section for an explanation.</p>
</li>
</ul>
</li>
</ul>
<h4>Assignment Operators</h4>
<p>Assignment operators can be used with any type. In HDLRuby, both connection and assignment operations are represented by the <code>&lt;=</code> symbol.</p>
<p><strong>Note</strong>: The first <code>&lt;=</code> in a statement is always interpreted as an assignment operator. Any subsequent occurrences of <code>&lt;=</code> in the same statement are interpreted as the standard less than or equal to comparison operator.</p>
<h4>Arithmetic Operators</h4>
<p>Arithmetic operators automatically convert operands to vectors of <code>bit</code>, <code>unsigned</code> or <code>signed</code> values, or to <code>integer</code>, or <code>float</code> values.  The binary arithmetic operators are <code>+</code>, <code>-</code>, <code>*</code>, <code>%</code>. The unary arithmetic operators are <code>+</code> (indentity) and <code>-</code> (negation). All behave the same way as their Ruby equivalents.</p>
<h4>Comparison operators</h4>
<p>Comparison operators return a result of either true or false. In HDLRuby, true is represented by the bit value <code>1</code>, and false by the bit value <code>0</code>.</p>
<p>Supported operators include: <code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>, and <code>&gt;=</code>. These have the same meaning as in Ruby.</p>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>The <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code> and <code>&gt;=</code> operators automatically converts operands to one of the following types: vectors of <code>bit</code>, <code>unsigned</code> or <code>signed</code>, or <code>integer</code> or <code>float</code>.</p>
</li>
<li><p>When comparing values of other types, they are interpreted as <code>unsigned</code> bit vectors, unless they are explicitly <code>signed</code> or <code>float</code>.</p>
</li>
</ul>
<h4>Logic and Shift Operators</h4>
<p><strong>Logic Operators:</strong></p>
<p>In HDLRuby, all logic operators are bitwise. To perform Boolean logic operations, operands must be single-bit values. The bitwise logic operators are:</p>
<ul>
<li><p>Binary: <code>&amp;</code>, <code>|</code>, <code>^</code></p>
</li>
<li><p>Unary: <code>~</code></p>
</li>
</ul>
<p>These behave the same way as their Ruby counterparts.</p>
<p><strong>Note</strong>: There are no Boolean (<code>&amp;&amp;</code>, <code>||</code>) operators in HDLRuby for two reasons:</p>
<ol>
<li><p>Ruby does not support operator overloading for Boolean operators.</p>
</li>
<li><p>In Ruby, any value other than <code>false</code> or <code>nil</code> is considered true -- an assumption valid for software, but not for hardware, where values are often bit vectors. Therefore, Boolean logic is supported only through bitwise operators on single-bit values.</p>
</li>
</ol>
<p><strong>Shift Operators:</strong></p>
<p>The shift operators are <code>&lt;&lt;</code> (left shift) and <code>&gt;&gt;</code> (right shift).
These preserve the sign for <code>signed</code> types and do not change bit width. Their behavior matches that of Ruby.</p>
<p>The rotation operators are <code>rl</code> (left rotate) and <code>rr</code> (right rotate).
Like shifts, they preserve sign and bit width. Since Ruby lacks rotation operators, these are implemented as methods and used as follows:</p>
<pre><code class="language-ruby">&lt;expression&gt;.rl(&lt;other expression&gt;)
&lt;expression&gt;.rr(&lt;other expression&gt;)
</code></pre>
<p>For example, to rotate the bits of signal <code>sig</code> to the left by 3 positions:</p>
<pre><code class="language-ruby">sig.rl(3)
</code></pre>
<p>More complex shifts and rotations can also be implemented using selection and concatenation. See the <a href="#concatenation-and-selection-operators">Concatenation and selection operators</a> for details.</p>
<h4>Conversion operators</h4>
<p>The conversion operators are used to change the type of an expression.</p>
<ul>
<li><p><strong>Type puns</strong>, which change the interpretation of a value without modifying its raw bit content.</p>
</li>
<li><p><strong>Type casts</strong>, which modify both the type and the underlying bit representation.</p>
</li>
</ul>
<p><strong>Type Puns:</strong></p>
<p>The type pun operators include <code>to_bit</code>, <code>to_unsigned</code>, and <code>to_signed</code>. These convert an expression of any type into a vector of <code>bit</code>, <code>unsigned</code>, or <code>signed</code> elements, respectively, without altering the raw value.</p>
<p>For example, the following code converts a hierarchical signal into an 8-bit signed vector:</p>
<pre><code class="language-ruby">[ up: signed[3..0], down: unsigned[3..0] ].inner :sig
sig.to_bit &lt;= _b01010011
</code></pre>
<p><strong>Type Casts:</strong></p>
<p>Type cast operators change both the type and the bit representation of a value. They are used to change the bit width of vectors of type bit, signed, or unsigned.</p>
<p>The type cast operators include:</p>
<ul>
<li><p><code>ljust</code></p>
</li>
<li><p><code>rjust</code></p>
</li>
<li><p><code>zext</code></p>
</li>
<li><p><code>sext</code></p>
</li>
</ul>
<p>Each performs a specific form of bit-width extension:</p>
<ul>
<li><p><code>ljust</code> and <code>rjust</code>: these operators increase the width of a bit vector by adding bits on the left (<code>ljust</code>) or right (<code>rjust</code>) side. They take two arguments: the target width and the bit value (<code>0</code> or <code>1</code>) to be added.</p>
<p>Example: Extending <code>sig0</code> to 12 bits by adding <code>1</code>s on the right:</p>
<pre><code class="language-ruby">[7..0].inner :sig0
[11..0].inner :sig1
sig0 &lt;= 25
sig1 &lt;= sig0.ljust(12,1)
</code></pre>
</li>
<li><p><code>zext</code>: this operator performs zero extension by adding <code>0</code>s to the most significant side, based on the endianness of the value. It takes a single argument: the desired bit width.</p>
<p>Example: Extending <code>sig0</code> to 12 bits by adding <code>0</code>s on the left:</p>
<pre><code class="language-ruby">signed[7..0].inner :sig0
[11..0].inner :sig1
sig0 &lt;= -120
sig1 &lt;= sig0.zext(12)
</code></pre>
</li>
<li><p><code>sext</code>: this operator performs sign extension by duplicating the most significant bit of the original value. The extension side depends on the endianness. It also takes the target bit width as an argument.</p>
<p>Example: Extending <code>sig0</code> to 12 bits by duplicating the MSB on the right:</p>
<pre><code class="language-ruby">signed[0..7].inner :sig0
[0..11].inner :sig1
sig0 &lt;= -120
sig1 &lt;= sig0.sext(12)
</code></pre>
</li>
</ul>
<h4>Concatenation and selection operators</h4>
<p>Concatenation and selection in HDLRuby are performed using the <code>[]</code> operator. Its behavior depends on the argument it receives:</p>
<p><strong>Concatenation:</strong></p>
<p>When the <code>[]</code> operator takes multiple expressions as arguments, it concatenates them.</p>
<p>For example, the following code concatenates <code>sig0</code> and <code>sig1</code> into <code>sig2</code>:</p>
<pre><code class="language-ruby">[3..0].inner :sig0
[7..0].inner :sig1
[11..0].inner :sig2
sig0 &lt;= 5
sig1 &lt;= 6
sig2 &lt;= [sig0, sig1]
</code></pre>
<p><strong>Selection:</strong></p>
<p>When applied to an expression with a range as the argument, it selects the corresponding slice of bits.</p>
<p>If only a single bit is to be selected, a single index can be used instead.</p>
<p>For example, the following code selects bits 3 down to 1 from <code>sig0</code>, and bit 4 from <code>sig1</code>:</p>
<pre><code class="language-ruby">[7..0].inner :sig0
[7..0].inner :sig1
[3..0].inner :sig2
bit.inner    :sig3
sig0 &lt;= 5
sig1 &lt;= 6
sig2 &lt;= sig0[3..1]
sig3 &lt;= sig1[4]
</code></pre>
<h4>Implicit conversions</h4>
<p>When there is no ambiguity, HDLRuby automatically inserts conversion operators when two types are not directly compatible. The following rules apply:</p>
<ol>
<li><p>The bit width is adjusted to match that of the larger operand.</p>
</li>
<li><p>If one operand is signed, the computation is performed as signed; otherwise, it is unsigned.</p>
</li>
</ol>
<h2>Functions</h2>
<h3>HDLRuby Functions</h3>
<p>Like Verilog HDL, HDLRuby provides function constructs for reusing code. Functions in HDLRuby are declared as follows:</p>
<pre><code class="language-ruby">hdef :&lt;function_name&gt; do |&lt;arguments&gt;|
&lt;code&gt;
end
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>function_name</code> is the name of the function.</p>
</li>
<li><p><code>arguments</code> is the list of function parameters.</p>
</li>
<li><p><code>code</code> is the body of the function.</p>
</li>
</ul>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>Functions have their scope, so any declaration within a function is local. It is also forbidden to declare interface signals (<code>input</code>, <code>output</code>, or <code>inout</code>) within a function.</p>
</li>
<li><p>Like Ruby <code>Proc</code> objects, the last statement in a function is treated as its return value. For example, the following function returns <code>1</code> (and takes no arguments):</p>
<pre><code class="language-ruby">function :one { 1 }
</code></pre>
</li>
<li><p>Functions can accept any type of object as an argument, including variadic arguments and code blocks. For example, the following function applies a block of code passed via <code>&amp;code</code> to each argument passed via <code>*args</code>:</p>
<pre><code class="language-ruby">function :apply do |*args, &amp;code|
   args.each { |arg| code.call(args) }
end
</code></pre>
<p>This function can be used to connect a signal to multiple others. For example, the following connects sig to <code>x</code>, <code>y</code>, and <code>z</code>:</p>
<pre><code class="language-ruby"> apply(x,y,z) { |v| v &lt;= sig }
</code></pre>
</li>
</ul>
<p>You can invoke a function anywhere in your code using its name and passing arguments in parentheses:</p>
<pre><code class="language-ruby">&lt;function name&gt;(&lt;list of values&gt;)
</code></pre>
<h3>Ruby functions</h3>
<p>While HDLRuby functions are useful for reusing code, they cannot interact with the context in which they are called. For example, they cannot add interface signals or modify control structures such as <code>hif</code>. For these kinds of high-level, generic operations, you can use standard Ruby functions, which are declared as follows:</p>
<pre><code class="language-ruby">def &lt;function_name&gt;(&lt;arguments&gt;)
   &lt;code&gt;
end
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>function_name</code> is the name of the function.</p>
</li>
<li><p><code>arguments</code> is the list of function parameters.</p>
</li>
<li><p><code>code</code> is the body of the function.</p>
</li>
</ul>
<p>Ruby functions are invoked in the same way as HDLRuby functions, but they behave differently: their code is inlined directly into the location where they are called.</p>
<p>In addition:</p>
<ul>
<li>Ruby functions do not have their own scope, so any inner signals or instances declared within them are added to the enclosing object or scope where they are invoked.</li>
</ul>
<p>For example, the following function adds an input signal <code>in0</code> to any system in which it is used:</p>
<pre><code class="language-ruby">def add_in0
   input :in0
end
</code></pre>
<p>This function can be used as follows:</p>
<pre><code class="language-ruby">system :sys do
   ...
   add_in0
   ...
end
</code></pre>
<p>As another example, the following Ruby function appends a <code>helse</code> clause of with a reset assignment to a control structure like <code>hif</code> or <code>hcase</code>:</p>
<pre><code class="language-ruby">def too_bad
   helse { rst &lt;= 1 }
end
</code></pre>
<p>This function can be used as follows:</p>
<pre><code class="language-ruby">system :sys do
   ...
   par do
      hif(sig == 1) do
         ...
      end
      too_bad
   end
end
</code></pre>
<p><strong>Caution:</strong></p>
<p>Ruby functions behave similarly to C macros: they offer flexibility by modifying the code in which they are invoked, but they can also introduce unexpected behavior and hard-to-debug issues if used improperly.
As a rule, <strong>Ruby functions should be avoided unless you are building a generic library for HDLRuby</strong>.</p>
<h2>Software Code</h2>
<p>HDLRuby allows the description of hardware-software components using the program construct, which encapsulates software code and provides an interface for communication with the hardware. This interface consists of three types of components:</p>
<ul>
<li><p><strong>Activation events</strong>: 1-bit signals that trigger the execution of a specific software function when they transition from <code>0</code> to <code>1</code> (for positive events) or from <code>1</code> to <code>0</code> (for negative events).</p>
</li>
<li><p><strong>Read ports</strong>: Bit-vector signals that can be read from within a software function.</p>
</li>
<li><p><strong>Write ports</strong>: Bit-vector signals that can be written from within a software function.</p>
</li>
</ul>
<p><strong>Note:</strong> A single signal can be used simultaneously as both a read and a write port in multiple contexts. However, from the software perspective, it will appear as two separate ports—one for reading and one for writing.</p>
<h3>Declaring a Software Component</h3>
<p>A software component is declared similarly to a hardware process, within a system block. The syntax is as follows:</p>
<pre><code class="language-ruby">program(&lt;programming_language&gt;, &lt;function_name&gt;) do
   # location of the software files and description of its interface
end
</code></pre>
<p>In this declaration:</p>
<ul>
<li><p><code>programming_language</code> is a symbol indicating the language used for the software. Currently supported options are:</p>
<ul>
<li><p><code>:ruby</code> -- for programs written in Ruby.</p>
</li>
<li><p><code>:c</code> --  for programs written in C. (In fact, any language that can be compiled into a shared library linkable with C is supported.)</p>
</li>
</ul>
</li>
<li><p><code>function_name</code> 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.</p>
</li>
<li><p><code>location of the software files and description of its interface</code> may include the following declarations:</p>
<ul>
<li><p><code>actport &lt;list of events&gt;</code> -- Declares the events that activate the program (i.e., trigger execution of the program’s start function).</p>
</li>
<li><p><code>inport &lt;port_name: signal&gt;</code> -- Declares input ports that can be read by the software.</p>
</li>
<li><p><code>outport &lt;port_name: signal&gt;</code> -- Declares output ports that the software can write to.</p>
</li>
<li><p><code>code &lt;list_of_filenames&gt;</code> -- Specifies the software source file(s).</p>
</li>
</ul>
</li>
</ul>
<p><strong>Example:</strong></p>
<p>The following example declares a program in Ruby with a start function named <code>echo</code>. The program is triggered on the positive edge of signal <code>req</code>, reads from signal <code>count</code> through port <code>inP</code>, and writes to signal <code>val</code> through port <code>outP</code>. The software code is located in the file <code>echo.rb</code>:</p>
<pre><code class="language-ruby">system :my_system do
   inner :req
   [8].inner :count, :val
 
   ...

   program(:ruby,'echo') do
      actport req.posedge
      inport  inP:  count
      outport outP: val
      code &quot;echo.rb&quot;
   end
end
</code></pre>
<p><strong>Notes:</strong></p>
<ul>
<li><p>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 <code>long long</code>.</p>
</li>
<li><p>If the language is Ruby, the <code>code</code> section can use a Ruby <code>Proc</code> objecct in place of a file name.</p>
</li>
</ul>
<h3>About the Software Code Used in HDLRuby Programs</h3>
<h4>Location and Format of the Files</h4>
<p>The filenames specified in the <code>code</code> declaration must indicate paths relative to the directory where the HDLRuby tools are run.</p>
<p>In the earlier example, this means that the <code>echo.rb</code> file must be located in the same directory as the HDLRuby description. If the source file were placed in a <code>ruby/</code> subdirectory instead, the declaration would be:</p>
<pre><code class="language-ruby">   code &quot;ruby/echo.rb&quot;
</code></pre>
<p>For Ruby programs, you may declare multiple source files, and plain Ruby code can be used as-is without any compilation.</p>
<p>For C programs, however, the code must first be compiled, and the code declaration must refer to the resulting compiled file (not the source). For instance, if the echo function were implemented in C, the declaration would be:</p>
<pre><code class="language-ruby">   program(:c, :echo) do
      actport req.posedge
      inport  inP:  count
      outport outP: val
      code &quot;echo&quot;
   end
</code></pre>
<p>To make this work, you must compile the C code into a file named echo.</p>
<p><strong>Note</strong>: The file extension is intentionally omitted so that the system can automatically detect the appropriate format (e.g., .so for a shared library on Linux).</p>
<h4>The hardware Interface</h4>
<p>From the software point of view, the hardware interface consists only of a list of ports that can either be read or written. However, the implementation of this interface depends on the language.</p>
<h5>For Ruby</h5>
<p>In Ruby, the hardware interface is accessed by requiring the rubyHDL library. This library provides the RubyHDL module, which exposes the program's ports as module-level accessors.</p>
<p>For example, the following Ruby function reads from the <code>inP</code> port and writes the result to the <code>outP</code> port:</p>
<pre><code class="language-ruby">require 'rubyHDL'

def echo
   val = RubyHDL.inP
   RubyHDL.outP = val
end
</code></pre>
<p><strong>Note:</strong> As long as a port has been declared in the HDLRuby description of the program, it will automatically be accessible in the software via the <code>RubyHDL</code> module. No additional declarations or configuration are required.</p>
<h5>For C</h5>
<p>In C (and other C-compatible compiled languages), the interface is accessed by including the <code>cHDL.h</code> header file. This file must be generated using the following command:</p>
<pre><code class="language-bash">hdrcc --ch &lt;destination_project&gt;
</code></pre>
<p>Here, <code>destination_project</code> is the folder where the C source code is located.</p>
<p>The generated header provides the following interface functions:</p>
<ul>
<li><p><code>void* c_get_port(const char* name)</code>: Returns a pointer to the port with the specified name.</p>
</li>
<li><p><code>int c_read_port(void* port)</code>: Reads the value from the given port pointer.</p>
</li>
<li><p><code>int c_write_port(void* port, int val)</code>: Writes the value <code>val</code> to the specified port pointer.</p>
</li>
</ul>
<p>Here is an example program that reads from port <code>inP</code> and writes the result to port <code>outP</code>:</p>
<pre><code class="language-c">#include &quot;cHDL.h&quot;

void echo() {
   void* inP = c_get_port(&quot;inP&quot;);
   void* outP = c_get_port(&quot;outP&quot;);
   int val;
   
   val = c_read_port(inP);
   c_write_port(outP,val);
}
</code></pre>
<p><strong>Notes:</strong></p>
<ul>
<li><p>The hdrcc command not only generates the C header (cHDL.h) but also creates additional files to assist in compiling the C source code. See <a href="#compiling-the-c-code">compile for simulation</a> for details.</p>
</li>
<li><p><strong>Important for Windows:</strong> Functions used as HDLRuby entry points must be declared with the <code>__declspec(dllexport)</code> prefix. If this is missing, the simulation will not work properly. For example, the echo function on Windows must be declared as:</p>
<pre><code class="language-c">#include &quot;cHDL.h&quot;

__declspec(dllexport) void echo() {
   void* inP = c_get_port(&quot;inP&quot;);
   void* outP = c_get_port(&quot;outP&quot;);
   int val;
   
   val = c_read_port(inP);
   c_write_port(outP,val);
}
</code></pre>
</li>
</ul>
<h4>Hardware-software co-simulation</h4>
<p>As long as your programs a correctly described and the software files provided (and compiled in the case of C), the hardware-software co-simulation will be automatically performed when executing the HDLRuby simulator.</p>
<h5>Compiling the C code</h5>
<p>While Ruby programs can be used directly, C programs must be compiled into a shared library before they can be simulated.</p>
<p>To do this, you must generate the necessary files -- most importantly, the hardware interface header <code>cHDL.h</code>. This is done using the following HDLRuby command:</p>
<pre><code class="language-bash">hdrcc --ch &lt;destination_project&gt;
</code></pre>
<p>Here, <code>&lt;destination_project&gt;</code> refers to both the directory where the C code resides and the name of the resulting shared library.</p>
<p>For example, to prepare a project located in the <code>echo</code> directory, you would run:</p>
<pre><code class="language-bash">hdrcc --ch echo
</code></pre>
<p>This command will create a directory named echo containing the cHDL.h file and supporting files.</p>
<p>Next:</p>
<ol>
<li><p>Place your C source files (e.g., <code>echo.c</code>) into the <code>echo</code> directory.</p>
</li>
<li><p>Change into that directory and compile the C code.</p>
</li>
</ol>
<p>If you prefer to compile manually (e.g., without relying on Ruby tools), you can use a standard command like the following (on Linux):</p>
<pre><code class="language-bash">gcc -shared -fPIC -undefined dynamic_lookup  -o c_program.so echo.c
</code></pre>
<p>This compiles a single-file project into a shared object file suitable for simulation.</p>
<p>Alternatively, if you want a simpler and more portable option, you can use Ruby's <code>rake-compiler</code>. First install it:</p>
<pre><code class="language-bash">gem install rake-compiler
</code></pre>
<p>Then, from within the <code>echo</code> directory, run:</p>
<pre><code class="language-bash">rake compile
</code></pre>
<p>The <code>rake</code> tool will automatically handle the compilation process across different platforms.</p>
<h4>Hardware Generation</h4>
<p>At its current stage, HDLRuby generates only the hardware portion of a design. For example, when generating Verilog, any <code>program</code> constructs are ignored. It is the user's responsibility to provide additional infrastructure to implement the hardware-software interface.</p>
<p>This limitation exists because such interfaces are target-specific, and often rely on licensed IP or proprietary components that cannot be integrated directly into HDLRuby.</p>
<p>However, this is not as restrictive as it may seem: you can still write <code>program</code> constructs that wrap access to such hardware interfaces, enabling you to reuse your HDLRuby and software code directly in your target system.</p>
<p>For an example, see the tutorial section: <a href="tuto/tutorial_sw.md#7-6-hardware-software-co-synthesis">7.6. hardware-software co-synthesis</a>.</p>
<h3>Extended co-simulation</h3>
<p>Since HDLRuby programs can support any compiled software, they can be used to execute arbitrary applications -- not just software targeting the main system CPU. For example, peripheral devices such as a keyboard or monitor can be modeled using HDLRuby programs. This approach is illustrated in the HDLRuby sample <code>with_program_ruby_cpu.rb</code>.</p>
<h3>Development board simulation graphical interface</h3>
<p>HDLRuby provides a web-based graphical user interface (GUI) for simulating hardware-software systems. This GUI acts as an extension of the co-design platform and is declared within a module using the <code>board</code> construct:</p>
<pre><code class="language-ruby">board(:&lt;board_name&gt;,&lt;server_port&gt;) do
  actport &lt;event&gt;
  &lt;GUI description&gt;
end
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>board_name</code> is the name of the board.</p>
</li>
<li><p><code>server_port</code> is the port number used to access the GUI (default: 8000).</p>
</li>
<li><p><code>event</code> is the signal event (e.g., a clock's rising edge) that synchronizes the GUI with the simulator.</p>
</li>
</ul>
<p><strong>GUI Elements:</strong></p>
<p>The GUI description consists of a list of visual or hidden elements. Active elements must be named and linked to HDLRuby signals using the format:</p>
<pre><code class="language-ruby">&lt;element&gt; &lt;element_name&gt;: &lt;HDLRuby_signal&gt;
</code></pre>
<p>Supported elements include:</p>
<ul>
<li><p><code>sw</code>: A set of slide switches (bit-width matches the signal).</p>
</li>
<li><p><code>bt</code>: A set of push buttons (bit-width matches the signal).</p>
</li>
<li><p><code>slider</code>: A horizontal slider for numeric input.</p>
</li>
<li><p><code>text</code>: A text input field. The value is interpreted as a Ruby expression. All display objects (e.g., <code>leds</code>) can be referenced as variables.</p>
</li>
<li><p><code>hook</code>: Attaches a signal without displaying it. Useful for referencing in <code>text</code> fields.</p>
</li>
<li><p><code>led</code>: A set of LEDs (bit-width matches the signal).</p>
</li>
<li><p><code>hexa</code>: A hexadecimal display. The width adjusts to the signal's range.</p>
</li>
<li><p><code>digit</code>: A decimal display. Width is based on the signal's numeric range.</p>
</li>
<li><p><code>scope</code>: An oscilloscope-like display. Vertical axis reflects signal values; horizontal axis shows GUI synchronization steps.</p>
</li>
<li><p><code>row</code>: Inserts a new line in the GUI layout.</p>
</li>
</ul>
<p><strong>Example: Adder Interface with GUI:</strong></p>
<p>The following example creates a GUI for an adder system with 8-bit input signals <code>x</code> and <code>y</code>, and an output signal <code>z</code> displayed using LEDs, a numeric display, and an oscilloscope:</p>
<pre><code class="language-ruby">system :adder_with_gui do
  [8].inner :x, :y, :z
  
  z &lt;= x + y

  inner :gui_sync
  
  board(:adder_gui) do
    actport gui_sync.posedge
    sw x: x
    sw y: y
    row
    led z_led: z
    digit z_digit: z
    row
    scope z_scope: z
  end

  timed do
    clk &lt;= 0
    repeat(10000) do
      !10.ns
      clk &lt;= ~clk
    end
  end
end
</code></pre>
<p>This code defines a GUI with:</p>
<ul>
<li><p>Two sets of slide switches for inputs <code>x</code> and <code>y</code> (first row),</p>
</li>
<li><p>A set of LEDs and a decimal display for output <code>z</code> (second row),</p>
</li>
<li><p>An oscilloscope displaying the evolution of <code>z</code> over time (third row).</p>
</li>
</ul>
<p><strong>Running the Simulation:</strong></p>
<p>You can simulate this design as you would any HDLRuby system. The following command runs the simulation and generates a VCD waveform file:</p>
<pre><code class="language-bash">hdrcc --sim --vcd my_adder.rb my_adder
</code></pre>
<p>When this command is executed, the simulator will wait for a web browser to connect before starting. To launch the GUI, open a browser and navigate to:</p>
<pre><code>http://localhost:8000
</code></pre>
<p>Once connected, the simulation will begin, and you can interact with the design through the GUI.</p>
<h2>Time</h2>
<h3>Time Values</h3>
<p>In HDLRuby, time values can be created using the following time suffix operators:</p>
<ul>
<li><p><code>s</code> for seconds.</p>
</li>
<li><p><code>ms</code> for milliseconds.</p>
</li>
<li><p><code>us</code> for microseconds.</p>
</li>
<li><p><code>ns</code> for nanoseconds.</p>
</li>
<li><p><code>ps</code> for picoseconds.</p>
</li>
</ul>
<p>For example, all of the following expressions represent one second:</p>
<pre><code class="language-ruby">1.s
1000.ms
1000000.us
1000000000.ns
1000000000000.ps
</code></pre>
<h3>Time Processs and Time Statements</h3>
<p>Like other HDLs, HDLRuby provides specific statements to model the passage of time. These statements are not synthesizable and are intended for simulation only, such as modeling a hardware component’s environment.</p>
<p>To improve clarity and avoid confusion, time-based statements are only allowed in explicitly non-synthesizable processes declared using the <code>timed</code> keyword:</p>
<pre><code class="language-ruby">timed do
   &lt;statements&gt;
end
</code></pre>
<p>A time process has no sensitivity list but can include any statements allowed in a standard process, plus time-specific statements.</p>
<p>There are two such time statements:</p>
<ul>
<li><p><code>wait</code> statement: this statement blocks the execution of the process for the specified amount of time. For example:</p>
<pre><code class="language-ruby">   wait(10.ns)
</code></pre>
<p>This can also be abbreviated using the <code>!</code> operator:</p>
<pre><code class="language-ruby">   !10.ns
</code></pre>
</li>
<li><p><code>repeat</code> statement: This statement repeats a block of code for a specified number of iterations. For example, the following toggles the <code>clk</code> signal every 10 nanoseconds, repeating 10 times:</p>
<pre><code class="language-ruby">   repeat(10) do 
      !10.ns
      clk &lt;= ~clk
   end
</code></pre>
</li>
</ul>
<p><strong>Note:</strong> These time statements are not synthesizable and can only be used within <code>timed</code> processes.</p>
<h3>Non-Blocking and Blocking Execution</h3>
<p>Time processes use blocking assignments by default, but both blocking and non-blocking assignment blocks can be used inside them.</p>
<p>The execution semantic is:</p>
<ul>
<li><p>Blocking assignment blocks are executed sequentially.</p>
</li>
<li><p>Non-blocking assignment blocks are executed in a semi-parallel manner, based on the following rules:</p>
<ol>
<li><p>Statements are grouped in sequence until a time statement is encountered.</p>
</li>
<li><p>The grouped blocks are executed in parallel.</p>
</li>
<li><p>The time statement is executed.</p>
</li>
<li><p>Execution resumes with the next group of statements.</p>
</li>
</ol>
</li>
</ul>
<h2>High-Level Programming Features</h2>
<h3>Generating Hardware RTL Code in HDLRuby</h3>
<p>Since HDLRuby is built on top of Ruby, you can freely use standard Ruby constructs (such as classes, methods, and modules) without any compatibility issues. Additionally, this Ruby code does not interfere with the synthesizability of the resulting hardware design. In fact, Ruby logic can be used to generate HDLRuby constructs at compile time.</p>
<p>However, pure Ruby code does not interact with the HDLRuby name stack, and its misuse may lead to unintended states during compilation. Unless you're intentionally extending HDLRuby itself, it is recommended to avoid low-level Ruby generation logic for general-purpose hardware generation.</p>
<p>Instead, you should prefer HDLRuby’s high-level hardware generation features, which are safer and clearer—similar to Verilog’s <code>generate</code> construct. These include:</p>
<ul>
<li><p>Generic programming (explained in the next section)</p>
</li>
<li><p>Parallel statements like <code>hif</code> or <code>hcase</code></p>
</li>
<li><p>Parallel enumerators (see <a href="#parallel-enumerators">Parallel Enumerators</a>)</p>
</li>
</ul>
<p>These constructs can be used anywhere in the code without restriction and are generally sufficient for most hardware generation needs.</p>
<p><strong>Example: Conditional Hardware Generation</strong></p>
<p>The <code>hif</code> and <code>hcase</code> statements can be used to generate conditional logic. For instance, the following code generates either a clocked process or a continuous one depending on the value of the <code>clocked</code> flag:</p>
<pre><code>hif(clocked) do
   par(clk.posedge) { ... }
helse
   par { ... }
end
</code></pre>
<h3>Generic Programming</h3>
<h4>Declaring</h4>
<h5>Declaring Generic Modules</h5>
<p>Modules can be declared with generic parameters using the following syntax:</p>
<pre><code class="language-ruby">system :&lt;system_name&gt; do |&lt;list_of_generic_parameters&gt;|
   ...
end
</code></pre>
<p>For example, the following code defines an empty module with two generic parameters named <code>a</code> and <code>b</code>:</p>
<pre><code class="language-ruby">system(:nothing) { |a,b| }
</code></pre>
<p>Generic parameters in HDLRuby can be anything: values, data types, signals, modules, Ruby variables, and more.</p>
<p><strong>Example: Using Generics for Type, Range, and Module</strong></p>
<p>The following example demonstrates a module with:</p>
<ul>
<li><p><code>t</code>: a generic type used for an input signal</p>
</li>
<li><p><code>w</code>: a bit range used for an output signal</p>
</li>
<li><p><code>s</code>: a generic module used to create an instance</p>
</li>
</ul>
<pre><code class="language-ruby">system :something do |t,w,s|
   t.input :isig
   [w].output :osig

   s :sI.(i: isig, o: osig)
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>t.input :isig</code> declares an input of type <code>t</code></p>
</li>
<li><p><code>[w].output :osig</code> declares an output with bit-width or range <code>w</code></p>
</li>
<li><p><code>s :sI.(...)</code> instantiates module <code>s</code> and connects its ports</p>
</li>
</ul>
<p><strong>Variadic Generic Parameters</strong></p>
<p>You can declare a module with a variable number of generic parameters using Ruby’s splat operator (<code>*</code>). The parameters are collected into an array.</p>
<pre><code class="language-ruby">system(:variadic) { |*args| }
</code></pre>
<p>Here, <code>args</code> is an array containing any number of arguments.</p>
<h5>Declaring generic types</h5>
<p>Data types can be declared with generic parameters as follows:</p>
<pre><code class="language-ruby">typedef :&lt;type_name&gt; do |&lt;list_of_generic_parameters&gt;|
   ...
end
</code></pre>
<p>For example, the following code defines a bit-vector type with a generic bit width parameter <code>width</code>:</p>
<pre><code class="language-ruby">type(:bitvec) { |width| bit[width] }
</code></pre>
<p>As with modules, the generic parameters of types can be any kind of object. It is also possible to use variadic arguments.</p>
<h4>Specializing</h4>
<h5>Specializing Generic Modules</h5>
<p>A generic module is specialized by invoking its name and passing values for its generic arguments, as shown below:</p>
<pre><code class="language-ruby">&lt;module_name&gt;(&lt;generic_argument_values_list&gt;)
</code></pre>
<p>If fewer values are provided than the number of generic arguments, the module is partially specialized. However, only a fully specialized module can be instantiated.</p>
<p>A specialized module can also be used for inheritance. For example, assuming the module <code>sys</code> has two generic arguments, it can be specialized and used to build the module <code>subsys</code> as follows:</p>
<pre><code class="language-ruby">system :subsys, sys(1,2) do
   ...
end
</code></pre>
<p>This kind of inheritance can only be performed with fully specialized modules. For partially specialized modules, include must be used instead. For example, if <code>sys</code> is specialized with only one value, it can be used in the generic module <code>subsys_gen</code> as follows:</p>
<pre><code class="language-ruby">system :subsys_gen do |param|
   include sys(1,param)
   ...
end
</code></pre>
<p><strong>Note:</strong> In the example above, the generic parameter <code>param</code> of <code>subsys_gen</code> is used to specialize the module <code>sys</code>.</p>
<h5>Specializing Generic Types</h5>
<p>A generic type is specialized by invoking its name and passing values corresponding to the generic arguments, as follows:</p>
<pre><code class="language-ruby">&lt;type_name&gt;(&lt;generic_argument_values_list&gt;)
</code></pre>
<p>If fewer values are provided than the number of generic arguments, the type is partially specialized. However, only a fully specialized type can be used for declaring signals.</p>
<!--
##### Use of Signals as Generic Parameters

Signals passed as generic arguments to modules can be used to create generic connections within the module instance. To do this, the generic argument must be declared as an `input`, `output`, or `inout` port in the body of the module, as shown below:

```ruby
system :<system_name> do |sig|
   sig.input :my_sig
   ...
end
```

In the example above, `sig` is a generic argument assumed to be a signal. The second line declares the port to which `sig` will be connected when the module is instantiated. After this declaration, the port `my_sig` can be used like any other port in the module.

```ruby
system_name(some_sig) :<instance_name>
```

Here, `some_sig` is a signal available in the current context. This instantiation automatically connects `some_sig` to the instance.
-->
<h3>Inheritance</h3>
<h4>Basics</h4>
<p>In HDLRuby, a module can inherit from one or more parent modules using the <code>include</code> command, as shown:</p>
<pre><code class="language-ruby">   include &lt;list_of_modules&gt;
</code></pre>
<p>This <code>include</code> can be placed anywhere within the body of a module. However, the inherited content will only be accessible after the <code>include</code> statement is executed.</p>
<p>For example, the following code first defines a simple D flip-flop (<code>dff</code>) and then uses it to define a flip-flop with an additional inverted output (<code>qb</code>):</p>
<pre><code class="language-ruby">system :dff do
   input :clk, :rst, :d
   output :q

   par(clk.posedge) { q &lt;= d &amp; ~rst }
end

system :dff_full do
    output :qb

    include dff

    qb &lt;= ~q
end
</code></pre>
<p>It is also possible to declare inheritance in a more object-oriented style by listing the parent modules immediately after the module name, as follows:</p>
<pre><code class="language-ruby">system :&lt;new_module_name&gt;, &lt;list_of_parent_modules&gt; do
   # Additional module code
end
</code></pre>
<p>For example, the following code provides an alternative way to define <code>dff_full</code>:</p>
<pre><code class="language-ruby">system :dff_full, dff do
   output :qb

   qb &lt;= ~q
end
</code></pre>
<p><strong>Note</strong>: From an implementation perspective, HDLRuby modules behave more like Ruby mixins than traditional class-based inheritance. Internally, modules are treated as sets of methods used to access constructs such as signals and instances.</p>
<h4>About Inner Signals and Module Instances</h4>
<p>By default, inner signals and instances defined in a parent module are not accessible in child modules. To expose them, use the <code>export</code> keyword:</p>
<pre><code class="language-ruby">   export &lt;symbol_0&gt;, &lt;symbol_1&gt;, ...
</code></pre>
<p>For example, the following code exports signals <code>clk</code> and <code>rst</code>, and the instance <code>dff0</code> from the module <code>exporter</code>, making them accessible in its child module <code>importer</code>:</p>
<pre><code class="language-ruby">system :exporter do
   input :d
   inner :clk, :rst

   dff(:dff0).(clk: clk, rst: rst, d: d)

   export :clk, :rst, :dff0 
end

system :importer, exporter do
   input :clk0, :rst0
   output :q

   clk &lt;= clk0
   rst &lt;= rst0
   dff0.q &lt;= q
end
</code></pre>
<p><strong>Notes</strong> <code>export</code> accepts symbols or strings representing the names of the components to export -- not references to them.</p>
<p>For example, the following code is invalid:</p>
<pre><code class="language-ruby">system :exporter do
   input :d
   inner :clk, :rst

   dff(:dff0).(clk: clk, rst: rst, d: d)

   export clk, rst, dff0 
end
</code></pre>
<h4>Conflicts when Inheriting</h4>
<p>Signals and instances cannot be overridden, including those inherited from parent modules. For example, the following code is invalid because the signal <code>rst</code> is already defined in <code>dff</code>:</p>
<pre><code class="language-ruby">   system :dff_bad, dff do
      input :rst
   end
</code></pre>
<h4>Shadowed signals and instances</h4>
<p>In HDLRuby, it is possible to declare a signal or instance in a child module with the same name as one from an included module. When this happens, the construct from the parent module becomes shadowed -- it still exists but is no longer directly accessible, even if exported.</p>
<p>To access a shadowed signal or instance, you must reinterpret the current module as the parent using the <code>as</code> operator:</p>
<pre><code class="language-ruby">   as(&lt;parent_module)
</code></pre>
<p>For example, in the code below, the signal <code>db</code> defined in <code>dff_shadow</code> shadows the one from <code>dff_db</code>. The original <code>db</code> can still be accessed using the as operator:</p>
<pre><code class="language-ruby">system :dff_db do
   input :clk,:rst,:d
   inner :db
   output :q

   db &lt;= ~d
   (q &lt;= d &amp; ~rst).at(clk.posedge)
end

system :dff_shadow, dff_db do
   output :qb, :db

   db &lt;= ~d
   qb &lt;= as(dff_db).db
end
</code></pre>
<h3>Opening a Module</h3>
<p>HDLRuby allows you to continue the definition of a module after it has already been declared by using the <code>open</code> method, as shown below:</p>
<pre><code class="language-ruby">&lt;module&gt;.open do
   # Additional description for the module
end
</code></pre>
<p>For example, the module <code>dff</code>, which describes a D flip-flop, can be extended to include an inverted output as follows:</p>
<pre><code class="language-ruby">dff.open do
   output :qb

   qb &lt;= ~q
end
</code></pre>
<h3>Opening an Instance</h3>
<p>When a modification is required for a specific instance, it may be preferable to modify only that instance rather than creating a new module derived from the original. To do this, you can open the instance for modification using the following syntax:</p>
<pre><code class="language-ruby">&lt;instance_name&gt;.open do
   # Additional description for the instance
end
</code></pre>
<p>For example, an instance of the previously defined <code>dff</code> module can be extended to include an inverted output as follows:</p>
<pre><code class="language-ruby">system :some_system do
   ...
   dff :dff0
   dff0.open do
      output :qb
      qb &lt;= ~q
   end
   ...
end
</code></pre>
<h3>Overloading Operators</h3>
<p>Operators can be overloaded for specific types. This allows, for example, seamless support for fixed-point computations without requiring explicit adjustment of the decimal point position.</p>
<p>An operator is redefined as follows:</p>
<pre><code class="language-ruby">&lt;type&gt;.define_operator(:&lt;op&gt;) do |&lt;args&gt;|
   # Operation description
end
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>type</code> is the type from which the operator is overloaded.</p>
</li>
<li><p><code>op</code> is the operator being overloaded (e.g., <code>+</code>).</p>
</li>
<li><p><code>args</code> are the arguments of the operation.</p>
</li>
<li><p><code>operation description</code> is an HDLRuby expression defining the new behavior of the operator.</p>
</li>
</ul>
<p><strong>Example: Fixed-Point Type</strong></p>
<p>Suppose <code>fix32</code> is a 32-bit fixed-point type with the decimal point at bit 16, defined as follows:</p>
<pre><code class="language-ruby">signed[31..0].typedef(:fix32)
</code></pre>
<p>You can overload the multiplication operator to maintain correct decimal alignment as follows:</p>
<pre><code class="language-ruby">fix32.define_operator(:*) do |left,right|
   (left.as(signed[31..0]) * right) &gt;&gt; 16
end
</code></pre>
<p><strong>Note:</strong> In the example above, <code>left</code> is explicitly cast to a plain signed bit-vector to prevent infinite recursive calls to the overloaded * operator.</p>
<p><strong>Overloading with Generic Types</strong></p>
<p>Operators can also be overloaded for generic types. In this case, the generic parameters must be included in the block parameters of the overloaded operator.</p>
<p>For example, consider a generic fixed-point type where the decimal point is set at half the bit width:</p>
<pre><code class="language-ruby">typedef(:fixed) do |width|
   signed[(width-1)..0]
end
</code></pre>
<p>You can overload the multiplication operator for this type as follows:</p>
<pre><code class="language-ruby">fixed.define_operator do |width,left,right|
   (left.as(signed[(width-1)..0]) * right) &gt;&gt; width/2
end
</code></pre>
<h3>Predicate and Access Methods</h3>
<p>HDLRuby provides several predicate and access methods to retrieve information about the current state of the hardware description.</p>
<p>| predicate name | predicate type | predicate meaning                          |
| :---           | :---           | :---                                       |
| <code>is_block?</code>    | bit            | Returns 1 if currently inside a block.           |
| <code>is_par?</code>      | bit            | Returns 1 if the current block is non-blocking.|
| <code>is_seq?</code>      | bit            | Returns 1 if the current block is blocking.|
| <code>is_clocked?</code>  | bit            | Returns 1 if the current process is clocked (i.e., triggered by a single rising or falling edge of a signal). |
| <code>cur_block</code>    | block          | Returns the current block.         |
| <code>cur_behavior</code> | process        | Returns the current process (behavior). |
| <code>cur_systemT</code>  | system         | Returns the current module (system).  |
| <code>top_block  </code>  | block          | Returns the top block of the current process. |
| <code>parent</code>       | any            | Returns the parent construct. |</p>
<p><strong>Enumerators</strong></p>
<p>HDLRuby also provides enumerators for accessing internal elements of the current construct in its current state:</p>
<p>| enumerator name   | accessed elements                    |
| :---              | :---                                 |
| <code>each_input</code>      | Iterates over the input signals of the current system.  |
| <code>each_output</code>     | Iterates over the output signals of the current system. |
| <code>each_inout</code>      | Iterates over the inout signals of the current system.  |
| <code>each_behavior</code>   | Iterates over the processes (behaviors) of the current system.      |
| <code>each_event</code>      | Iterates over the events of the current process.       |
| <code>each_block</code>      | Iterates over the blocks of the current process.       |
| <code>each_statement</code>  | Iterates over the statements in the current block.     |
| <code>each_inner</code>      | Iterates over the inner signals of the current block (or of the system if not inside a block). |</p>
<h3>Defining and Executing Ruby Methods within HDLRuby Constructs</h3>
<p>As with any Ruby program, it is possible to define and execute methods anywhere in HDLRuby using standard Ruby syntax. When a method is defined, it is attached to the enclosing HDLRuby construct. For example:</p>
<ul>
<li><p>If a method is defined within a module declaration, it can only be used inside that module.</p>
</li>
<li><p>If a method is defined outside of any construct, it can be used throughout the HDLRuby description.</p>
</li>
</ul>
<p>A method can include HDLRuby code, in which case the resulting hardware description is appended to the current construct. For example, the following code connects <code>sig0</code> to Psig1<code>within the module</code>sys0<code>, and assigns </code>sig0<code>to</code>sig1<code>within the process of</code>sys1`:</p>
<pre><code class="language-ruby">def some_arrow
   sig1 &lt;= sig0
end

system :sys0 do
   input :sig0
   output :sig1

   some_arrow
end

system :sys1 do
   input :sig0, :clk
   output :sig1

   par(clk.posedge) do
      some_arrow
   end
end
</code></pre>
<p><strong>Warnings</strong>:</p>
<ul>
<li><p>In the example above, the semantics of some_arrow change depending on the context in which it is called:</p>
<ul>
<li><p>Within a module: interpreted as a static connection.</p>
</li>
<li><p>Within a process: interpreted as a behavioral assignment.</p>
</li>
</ul>
</li>
<li><p>Using Ruby methods to describe hardware can lead to fragile or incorrect code if not used carefully. For example, consider the following:1</p>
<pre><code class="language-ruby">def in_decl
   input :in0
end

system :sys0 do
   in_decl
end

system :sys1 do
   input :in0
   in_decl
end

system :sys2 do
   par do
      in_decl
   end
end
</code></pre>
<p>In this case:</p>
<ul>
<li><p><code>sys0</code> works correctly.</p>
</li>
<li><p><code>sys1</code> raises an error due to redeclaration of <code>in0</code>.</p>
</li>
<li><p><code>sys2</code> raises an error because <code>input</code> declarations are not allowed inside a process.</p>
</li>
</ul>
</li>
</ul>
<p><strong>Using Ruby Method Features</strong></p>
<p>Ruby methods in HDLRuby support all standard Ruby features, including:</p>
<ul>
<li><p>Variadic arguments (<code>*args</code>)</p>
</li>
<li><p>Named (keyword) arguments</p>
</li>
<li><p>Block arguments (<code>&amp;block</code>)</p>
</li>
</ul>
<p>For example, the following method connects a single driver signal to multiple targets:</p>
<pre><code class="language-ruby">def mconnect(driver, *signals)
   signals.each do |signal|
      signal &lt;= driver
   end
end

system :sys0 do
   input :i0
   input :o0, :o1, :o2, :o3

   mconnect(i0,o0,o1,o2,o3)
end
</code></pre>
<!--
__Higher-Order Hardware Behavior with Blocks__

While caution is needed, properly designed methods can greatly enhance code reuse and clarity. For example, the following method executes a block of hardware description after a specified number of clock cycles:

```ruby
def after(cycles, rst, &code)
   sub do
      inner :count
      hif rst == 1 do
         count <= 0
      end
      helse do
         hif count < cycles do
            count <= count + 1
         end
         helse do
            instance_eval(&code)
         end
      end
   end
end
```

Explanation:

* `sub` ensures that the signal `count` is locally scoped and avoids name collisions.

* `instance_eval(&code)` executes the given block in the current context, preserving signal and instance visibility.

Using the after method, the following example turns an LED on after 1,000,000 clock cycles:

```ruby
system :led_after do
   output :led
   input :clk, :rst

   par(clk.posedge) do
      (led <= 0).hif(rst)
      after(100000,rst) { led <= 1 }
   end
end
```

__Note__: 

 * Ruby closures apply in HDLRuby. The block passed to after can use local signals and instances.

 * Signals declared within the method will not clash with existing ones in the calling context.

-->
<h2>Extending HDLRuby</h2>
<p>Like any Ruby-based framework, HDLRuby constructs can be dynamically extended. While modifying their internal structure is generally discouraged, it is possible -- and sometimes useful -- to add methods to existing classes for customization and extension.</p>
<h3>Extending HDLRuby Constructs Globally</h3>
<p>A global extension refers to the traditional Ruby technique of <em>monkey patching</em>, where new methods are added to an existing class. For example, you can add a method that returns the number of interface signals (inputs, outputs, and inouts) of a module instance as follows:</p>
<pre><code class="language-ruby">class SystemI
   def interface_size
      return each_input.size + each_output.size + each_inout.size
   end
end
</code></pre>
<p>Once defined, the <code>interface_size</code> method can be used on any module instance:</p>
<pre><code class="language-ruby">   &lt;module_instance&gt;.interface_size
</code></pre>
<p>The following table shows the HDLRuby class associated with each core construct:</p>
<p>| construct                   | class          |
| :---                        | :---           |
| Data type                   | <code>Type</code>         |
| Module (system)             | <code>SystemT</code>      |
| Scope                       | <code>Scope</code>        |
| Module instance             | <code>SystemI</code>      |
| Signal                      | <code>Signal</code>       |
| Connection                  | <code>Connection</code>   |
| Process (<code>par</code>, <code>seq</code>)      | <code>Behavior</code>     |
| Time process (<code>timed</code>)      | <code>TimeBehavior</code> |
| Event                       | <code>Event</code>        |
| Block (<code>par</code>, <code>seq</code>, <code>sub</code>) | <code>Block</code>        |
| Assignment                  | <code>Transmit</code>     |
| Conditional (<code>hif</code>)         | If             |
| Case (<code>hcase</code>)              | Case           |
| Program  (<code>program</code>)        | Program        |</p>
<h3>Extending HDLRuby Constructs Locally</h3>
<p>A local extension of an HDLRuby construct means that only the targeted construct is modified, while all other constructs of the same type remain unaffected. This is accomplished in Ruby by accessing the construct's <em>eigenclass</em> using the <code>singleton_class</code> method and then modifying it via <code>class_eval</code>.</p>
<p><strong>Local Extension of a Specific Module</strong></p>
<p>In the following example, only the module <code>dff</code> is extended with the <code>interface_size</code> method:</p>
<pre><code class="language-ruby">dff.singleton_class.class_eval do
   def interface_size
      return each_input.size + each_output.size + each_inout.size
   end
end
</code></pre>
<p>After this extension, only <code>dff</code> responds to <code>interface_size</code>; other modules remain unchanged.</p>
<p><strong>Local Extension of a Specific Instance</strong></p>
<p>Similarly, you can extend a single instance of a module. In this example, only the instance <code>dff0</code> gains the <code>interface_size</code> method:</p>
<pre><code class="language-ruby">dff :dff0

dff0.singleton_class.class_eval do
   def interface_size
      return each_input.size + each_output.size + each_inout.size
   end
end
</code></pre>
<p>Other instances of the same module will not be affected.</p>
<p><strong>Local Extension of All Instances of a Module</strong></p>
<p>To extend all instances of a particular module, use the <code>singleton_instance</code> method instead of <code>singleton_class</code>. For example:</p>
<pre><code class="language-ruby">dff.singleton_instance.class_eval do
   def interface_size
      return each_input.size + each_output.size + each_inout.size
   end
end
</code></pre>
<p>Now, any instance of the <code>dff</code> module will respond to the <code>interface_size</code> method.</p>
<h3>Modifying the Generation Behavior</h3>
<p>The primary purpose of supporting global and local extensions for HDLRuby constructs is to allow users to customize and control the hardware generation process. This is especially useful when implementing synthesis algorithms tailored to specific types of modules.</p>
<p>For example, suppose you want to implement a generation algorithm for a category of modules. You can define an abstract module -- one without hardware content -- that holds the generation logic:</p>
<pre><code class="language-ruby">system(:my_base) {}

my_base.singleton_instance.class_eval do
   def my_generation
      &lt;some code&gt;
   end
end
</code></pre>
<p>When the module <code>my_base</code> is used as a parent (i.e., included in another module), the child module inherits the <code>my_generation</code> method. For example:</p>
<pre><code class="language-ruby">system :some_system, my_base do
   # Some system description
end
</code></pre>
<p><strong>Generation Invocation</strong></p>
<p>To use the custom generation logic before converting to a low-level hardware description, you would typically write:</p>
<pre><code class="language-ruby">some_system :instance0
instance0.my_generation
low = instance0.to_low
</code></pre>
<p>However, this manual invocation can be avoided by overriding the <code>to_low</code> method to automatically include the generation step:</p>
<pre><code class="language-ruby">system(:my_base) {}

my_base.singleton_instance.class_eval do
   def my_generation
      &lt;some code&gt;
   end

   alias :_to_low :to_low
   def to_low
      my_generation
      _to_low
   end
end
</code></pre>
<p>With this modification, calling <code>to_low</code> on any instance of a module that inherits from my_base will automatically execute my_generation beforehand:</p>
<pre><code class="language-ruby">some_system :instance0
low = instance0.to_low  # Automatically runs my_generation
</code></pre>
<h1>Standard Libraries</h1>
<p>The standard libraries are included in the <code>Std</code> Ruby module.
They can be loaded as follows, where <code>library_name</code> is the name of the library:</p>
<pre><code class="language-ruby">require 'std/&lt;library_name&gt;' 
</code></pre>
<p>After loading a library, you must include the <code>Std</code> Ruby module as follows:</p>
<pre><code class="language-ruby">include HDLRuby::High::Std
</code></pre>
<blockquote>
<p>However, <code>hdrcc</code> loads the stable components of the standard library by default, so you do not need to require or include anything additional to use them.</p>
</blockquote>
<p>As of the current version, the stable components are:</p>
<ul>
<li><p><code>std/clocks.rb</code></p>
</li>
<li><p><code>std/fixpoint.rb</code></p>
</li>
<li><p><code>std/decoder.rb</code></p>
</li>
<li><p><code>std/fsm.rb</code></p>
</li>
<li><p><code>std/sequencer.rb</code></p>
</li>
<li><p><code>std/sequencer_sync.rb</code></p>
</li>
<li><p><code>std/hruby_enum.rb</code></p>
</li>
</ul>
<h2>Clocks</h2>
<p>The <code>clocks</code> library provides utilities to simplify clock synchronization handling.</p>
<p>It allows you to multiply an event by an integer. The result is a new event whose frequency is divided by the integer multiplier.</p>
<p>For example, the following code describes a D flip-flop that captures data every three clock cycles:</p>
<pre><code class="language-ruby">system :dff_slow do
   input :clk, :rst
   input :d
   output :q

   ( q &lt;= d &amp; ~rst ).at(clk.posedge * 3)
end
</code></pre>
<p><strong>Note</strong>: This library automatically generates the RTL code required to implement the frequency division circuitry.</p>
<!--
## Counters
<a name="counters"></a>

This library provides two new constructs for implementing synthesizable wait statements.

The first construct is the `after` statement that activates a block after a given number of clock cycles is passed. Its syntax is the following:

```ruby
after(<number>,<clock>,<reset>)
```

Where:

* `<number>` is the number of cycles to wait.

* `<clock>` is the clock to use, this argument can be omitted.

* `<reset>` is the signal used to reset the counter used for waiting, this argument can be omitted.

This statement can be used inside a clocked process where the clock event of the process is used for the counter unless specified otherwise. 

The second construct is the `before` statement that activates a block until a given number of clock cycles is passed. Its syntax and usage are identical to the `after` statement.
-->
<h2>Decoder</h2>
<p>The decoder library provides a new set of control statements for easily describing instruction decoders.</p>
<p>A decoder can be declared anywhere within a module definition using the <code>decoder</code> keyword, as shown below:</p>
<pre><code class="language-ruby">decoder(&lt;signal&gt;) &lt;block&gt;
</code></pre>
<p>Here, <code>signal</code> is the signal to decode, and <code>block</code> is a procedure block (i.e., a Ruby proc) that defines the decoding behavior. This block can contain any code normally allowed in a standard process, and it also supports the special <code>entry</code> statement.</p>
<p>The <code>entry</code> statement defines a bit-pattern to match and the corresponding action to perform when the signal matches that pattern. Its syntax is:</p>
<pre><code class="language-ruby">entry(&lt;pattern&gt;) &lt;block&gt;
</code></pre>
<ul>
<li><p><code>pattern</code> is a string that defines the bit pattern to match.</p>
</li>
<li><p><code>block</code> is a procedure block (HDLRuby code) specifying the actions to execute when the pattern matches.</p>
</li>
</ul>
<p>The pattern string can include:</p>
<ul>
<li><p><code>0</code> and <code>1</code> characters to match fixed bit values.</p>
</li>
<li><p>Alphabetical characters to define named fields within the pattern.</p>
</li>
</ul>
<p>These named fields can be used as variables in the action block. If the same letter appears multiple times in the pattern, the corresponding bits are concatenated to form a multi-bit signal.</p>
<p>For example, the following code defines a decoder for the signal ir with two entries:</p>
<ul>
<li><p>The first entry sums fields <code>x</code> and <code>y</code> and assigns the result to signal <code>s</code>.</p>
</li>
<li><p>The second entry sums fields <code>x</code>, <code>y</code>, and <code>z</code> and assigns the result to <code>s</code>.</p>
</li>
</ul>
<pre><code class="language-ruby">decoder(ir) do
   entry(&quot;000xx0yy&quot;) { s &lt;= x + y }
   entry(&quot;10zxxzyy&quot;) { s &lt;= x + y + z }
end
</code></pre>
<p>Note that field bits do not need to be contiguous. For example, field <code>z</code> in the second entry spans non-adjacent bits.</p>
<h2>FSM</h2>
<p>The fsm library provides a set of control statements for easily describing finite state machines (FSMs).</p>
<p>An FSM can be declared anywhere in a module, provided it is outside any process, using the <code>fsm</code> keyword:</p>
<pre><code class="language-ruby">fsm(&lt;event&gt;,&lt;reset&gt;,&lt;mode&gt;) &lt;block&gt;
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>event</code> is the event (e.g., rising or falling edge of a signal) that triggers state transitions.</p>
</li>
<li><p><code>reset</code> is the reset signal.</p>
</li>
<li><p><code>mode</code> is the default execution mode of the FSM, either <code>:sync</code> (synchronous/Moore) or <code>:async</code> (asynchronous/Mealy).</p>
</li>
<li><p><code>block</code> is a procedure block that defines the FSM's states and transitions.</p>
</li>
</ul>
<p><strong>Defining States</strong></p>
<p>FSM states are declared with the following syntax:</p>
<pre><code class="language-ruby">&lt;kind&gt;(&lt;name&gt;) &lt;block&gt;
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>kind</code> is the type of state (reset, state, sync, or async).</p>
</li>
<li><p><code>name</code> is he state name (as a symbol).</p>
</li>
<li><p><code>block</code> is the actions to execute when the FSM is in that state.</p>
</li>
</ul>
<p>The available state kinds are:</p>
<ul>
<li><p><code>reset</code>: The state entered when the FSM is reset.</p>
<ul>
<li><p>If name is <code>:sync</code>, the reset is forced to be synchronous.</p>
</li>
<li><p>If name is <code>:async</code>, the reset is forced to be asynchronous.</p>
</li>
<li><p>If name is omitted, the mode defaults to that of the FSM.</p>
</li>
</ul>
</li>
<li><p><code>state</code>: A regular state that follows the FSM’s default mode.</p>
</li>
<li><p><code>sync</code>: A state that is always synchronous, regardless of the FSM mode.</p>
</li>
<li><p><code>async</code>: A state that is always asynchronous, regardless of the FSM mode.</p>
</li>
</ul>
<p><strong>Default Actions</strong></p>
<p>You can define actions that run in every state using the <code>default</code> statement:</p>
<pre><code class="language-ruby">default &lt;block&gt;
</code></pre>
<p>This block will execute alongside the states' block.</p>
<p><strong>State Transitions</strong></p>
<p>By default, state transitions follow the order in which the states are declared. When the last state is reached, the next transition loops back to the first state -- unless otherwise specified.</p>
<p>To define specific transitions, use the <code>goto</code> statement at the end of a state's action block:</p>
<pre><code class="language-ruby">goto(&lt;condition&gt;,&lt;names&gt;)
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>condition</code>: A signal whose value is used as an index.</p>
</li>
<li><p><code>names</code>: A list of target states. The condition’s value selects one of them by index.</p>
</li>
</ul>
<p>For example:</p>
<pre><code class="language-ruby">goto(cond,:st_a,:st_b,:st_c)
</code></pre>
<p>This means:</p>
<ul>
<li><p>If <code>cond == 0</code>, transition to <code>st_a</code></p>
</li>
<li><p>If <code>cond == 1</code>, transition to <code>st_b</code></p>
</li>
<li><p>If <code>cond == 2</code>, transition to <code>st_c</code></p>
</li>
<li><p>Otherwise, this <code>goto</code> is ignored</p>
</li>
</ul>
<p>Multiple <code>goto</code> statements can be used in the same block. If more than one is taken, the last matching one takes precedence.</p>
<p>If no <code>goto</code> is taken, the FSM continues with the next declared state.</p>
<p>For example, the following code describes an FSM describing a circuit that checks if two buttons (<code>but_a</code> and <code>but_b</code>) are pressed and released in sequence for activating an output signal (<code>ok</code>):</p>
<p><strong>Example</strong></p>
<p>The following example defines an FSM that detects a sequence of button presses (<code>but_a</code> followed by <code>but_b</code>) and sets the output ok accordingly:</p>
<pre><code class="language-ruby">fsm(clk.posedge,rst,:sync) do
   default { ok &lt;= 0 }
   reset do
      goto(but_a, :reset, but_a_on)
   end
   state(:but_a_on) do
      goto(but_a, :but_a_off, :but_a_on)
   end
   state(:but_a_off) do
      goto(but_b, :but_a_off, :but_b_on)
   end
   state(:but_b_on) do
      goto(but_b, :but_b_off, :but_b_on)
   end
   state(:but_b_off) do
      ok &lt;= 1
      goto(:but_b_off)
   end
end
</code></pre>
<p><strong>About Goto Behavior</strong></p>
<p><code>goto</code> statements are global within a state. Their position in the block does not affect execution order. For example, both of the following result in an unconditional transition to <code>:st_a</code>:</p>
<pre><code class="language-ruby">   state(:st_0) do
      goto(:st_a)
   end
   state(:st_1) do
      hif(cond) { goto(:st_a) }
   end
</code></pre>
<p>However, to make the transition conditional, write:</p>
<pre><code class="language-ruby">   state(:st_1) do
      goto(cond,:st_a)
   end
</code></pre>
<p><strong>Static FSM Mode</strong></p>
<p>While <code>goto</code> simplifies FSM design in most cases, sometimes finer control is needed. You can configure the FSM in <code>:static</code> mode, where transitions are explicitly defined using <code>next_state</code> statements.</p>
<p>To enable static mode, use <code>:static</code> as the FSM's execution mode:</p>
<pre><code class="language-ruby">fsm(clk.posedge,rst,:static)
   state(:st_0) do
      next_state(:st_1)
   state(:st_1) do
      hif(cond) { next_state(:st_1) }
      helse { next_state(:st_0) }
   end
end
</code></pre>
<p>In this mode, each state explicitly defines its next state(s), allowing precise transition logic.</p>
<h2>Parallel Enumerators</h2>
<p>HDLRuby parallel enumerators are objects used to generate hardware processes that operate on series of signals in parallel.</p>
<p>They are created using the <code>heach</code> method on parallel enumerable objects.</p>
<p><strong>Parallel Enumerable Objects</strong></p>
<p>Parallel enumerable objects include:</p>
<ul>
<li><p>Arrays of signals</p>
</li>
<li><p>Ranges</p>
</li>
<li><p>Expressions (enumerating on each bit)</p>
</li>
</ul>
<p>You can generate a parallel enumerable object from an integer value using one of the following methods:</p>
<ul>
<li><p><code>&lt;integer&gt;.htimes</code>: Equivalent to the range <code>0..&lt;integer-1&gt;</code>.</p>
</li>
<li><p><code>&lt;integer&gt;.supto(&lt;last&gt;)</code>: Equivalent to the range <code>&lt;integer&gt;..&lt;last&gt;</code>.</p>
</li>
<li><p><code>&lt;integer&gt;.sdownto(&lt;last&gt;)</code>: Equivalent to the range <code>&lt;last&gt;..&lt;integer&gt;</code>.</p>
</li>
</ul>
<p><strong>Parallel Enumerator Control Methods</strong></p>
<p>Parallel enumerators provide several control methods:</p>
<ul>
<li><p><code>hsize</code>: Returns the number of elements accessible by the enumerator.</p>
</li>
<li><p><code>htype</code>: Returns the type of the elements accessed.</p>
</li>
<li><p><code>heach</code>: Returns the enumerator itself. If a block is given, it performs the iteration.</p>
</li>
<li><p><code>heach_with_index</code>: Iterates over each element and its index. Returns an enumerator or performs iteration if a block is given.</p>
</li>
<li><p><code>heach_with_object(&lt;obj&gt;)</code>: Iterates over each element with a custom object. Returns an enumerator or performs iteration if a block is given.</p>
</li>
<li><p><code>with_index</code>: Identical to <code>seach_with_index</code>.</p>
</li>
<li><p><code>with_object(&lt;obj&gt;)</code>: Identical to <code>seach_with_object</code>.</p>
</li>
<li><p><code>clone</code>: Creates a new enumerator over the same elements.</p>
</li>
<li><p><code>+</code>: Concatenates two enumerators.</p>
</li>
</ul>
<p>Additionaly, it is possible to exit an enumeration loop using the following command:</p>
<ul>
<li><code>hbreak</code>: Exits the current enumeration loop.</li>
</ul>
<p><strong>Hardware Implementations of Enumerable Methods</strong></p>
<p>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.</p>
<p>Each method name corresponds to its Ruby counterpart, prefixed with an <code>h</code> (for &quot;hardware&quot;). For example, <code>hall?</code> is the hardware implementation of Ruby's <code>all?</code>.</p>
<ul>
<li><p><code>hall?</code>: Hardware implementation of <code>all?</code>. Returns a 1-bit signal (<code>0</code> = false, <code>1</code> = true).</p>
</li>
<li><p><code>hany?</code>: Hardware implementation of <code>any?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>hchain</code>: Hardware implementation of <code>chain</code>.</p>
</li>
<li><p><code>hmap</code>: Hardware implementation of <code>map</code>. Returns a vector signal of the computed results.</p>
</li>
</ul>
 <!-- * `hcompact`: Hardware implementation of `compact`. However, since there is no nil value in HW, use 0 instead for compacting. Returns a vector signal containing the compaction result. -->
<ul>
<li><code>hcount</code>: Hardware implementation of <code>count</code>. Returns a signal whose bit width matches the size of the enumerator containing the count result.</li>
</ul>
<!-- * `hcycle`: Hardware implementation of `cycle`. -->
<ul>
<li><p><code>hfind</code>: Hardware implementation of <code>find</code>. Returns the found element or <code>0</code> if not found.</p>
</li>
<li><p><code>hdrop</code>: Hardware implementation of <code>drop</code>. Returns a vector signal of the remaining elements.</p>
</li>
</ul>
<!-- * `hdrop_while`: Hardware implementation of `drop_while`. Returns a vector signal containing the remaining elements. -->
<ul>
<li><p><code>heach_cons</code>: Hardware implementation of <code>each_cons</code>.</p>
</li>
<li><p><code>heach_slice</code>: Hardware implementation of <code>each_slice</code>.</p>
</li>
<li><p><code>heach_with_index</code>: Hardware implementation of <code>each_with_index</code>.</p>
</li>
<li><p><code>heach_with_object</code>: Hardware implementation of <code>each_with_object</code>.</p>
</li>
<li><p><code>hto_a</code>: Hardware implementation of <code>to_a</code>. Returns a vector signal of all enumerated elements.</p>
</li>
</ul>
<!-- * `hselect`: Hardware implementation of `select`. Returns a vector signal containing the selected elements. -->
<ul>
<li><p><code>hfind_index</code>: Hardware implementation of<code>find_index</code>. Returns the index of the found element or <code>-1</code> if not found.</p>
</li>
<li><p><code>hfirst</code>: Hardware implementation of <code>first</code>. Returns a vector signal of the first elements.</p>
</li>
<li><p><code>hinclude?</code>: Hardware implementation of <code>include?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>hinject</code>: Hardware implementation of <code>inject</code>. Returns a signal containing the accumulated result. The data type of the result can be passed as initialization argument.</p>
</li>
<li><p><code>hmax</code>: Hardware implementation of <code>max</code>. Returns a vector signal of the maximum values.</p>
<p><em>Note:</em> Only one maximum value is supported at the moment.</p>
</li>
<li><p><code>hmax_by</code>: Hardware implementation of <code>max_by</code>. Returns a vector signal of the maximum values.</p>
<p><em>Note:</em> Only one maximum value is supported at the moment.</p>
</li>
<li><p><code>hmin</code>: Hardware implementation of <code>min</code>. Returns a vector signal of the minimum values.</p>
<p><em>Note:</em> Only one minimum value is supported at the moment.</p>
</li>
<li><p><code>hmin_by</code>: Hardware implementation of<code>min_by</code>. Returns a vector signal of the minimum values.</p>
<p><em>Note:</em> Only one minimum value is supported at the moment.</p>
</li>
<li><p><code>hminmax</code>: Hardware implementation of <code>minmax</code>. Returns a 2-element vector signal with the minimum and maximum values.</p>
</li>
<li><p><code>hminmax_by</code>: Hardware implementation of the Ruby <code>minmax_by</code> method. Returns a 2-element vector signal with the minimum and maximum values.</p>
</li>
<li><p><code>hnone?</code>: Hardware implementation of <code>none?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>hone?</code>: Hardware implementation of <code>one?</code>. Returns a 1-bit signal.</p>
</li>
</ul>
<!-- * `hreject`: Hardware implementation of `reject`. Returns a vector signal containing the remaining elements. -->
<ul>
<li><p><code>hreverse_each</code>: Hardware implementation of <code>reverse_each</code>.</p>
<p><em>Note:</em> To be used inside a <code>seq</code> process.</p>
</li>
<li><p><code>hsort</code>: Hardware implementation of <code>sort</code>. Returns a vector of sorted elements.</p>
<p><em>Note</em>: When the number of elements is not a power of 2, you must provide the maximum (or minimum for descending sort) value as an argument.</p>
</li>
<li><p><code>hsort_by</code>: Hardware implementation of <code>sort_by</code>. Returns a vector signal containing the sorted elements.</p>
<p><em>Note</em>: When the number of elements is not a power of 2, you must provide the maximum (or minimum for descending sort) value as an argument.</p>
</li>
<li><p><code>hsum</code>: Hardware implementation of <code>sum</code>. Returns a signal with the total sum.</p>
</li>
<li><p><code>htake</code>: Hardware implementation of <code>take</code>. Returns a vector of the selected elements.</p>
</li>
</ul>
<!-- * `htake_while`: Hardware implementation of `take_while`. Returns a vector signal containing the taken elements. -->
<!-- * `huniq`: Hardware implementation of `uniq`. Returns a vector signal containing the selected elements. -->
<h2>Sequencer (Software-like Hardware Coding)</h2>
<p>This library provides a set of software-like control statements for describing the behavior of a circuit.
Behind the scenes, these constructs generate a finite state machine (FSM), where states are inferred from control points in the description.</p>
<p>Although sequencers are intended for hardware design, they are software-compatible and can efficiently execute as software programs. For more information, see the section on <a href="#sequencers-as-software-code">software sequencers</a>.</p>
<p><strong>Declaring a Sequencer</strong></p>
<p>A sequencer can be declared anywhere in a system, as long as it is outside of a process, using the <code>sequencer</code> keyword:</p>
<pre><code class="language-ruby">sequencer(&lt;clock&gt;,&lt;start&gt;) &lt;block&gt;
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>clock</code> is the signal (or event, such as <code>posedge</code> or <code>negedge</code>) that advances the sequencer.</p>
</li>
<li><p><code>start</code> is the signal (or event) that starts the sequencer.</p>
</li>
<li><p><code>block</code> is the sequence of operations to perform.</p>
</li>
</ul>
<p><strong>Sequencer Constructs</strong></p>
<p>The sequence block behaves like a <code>seq</code> block but includes the following software-like control statements:</p>
<ul>
<li><p><code>step</code>: Waits until the next event (as defined by the sequencer’s <code>event</code>).</p>
</li>
<li><p><code>steps(&lt;num&gt;)</code>: Repeats <code>step</code> for <code>num</code> cycles. <code>num</code> can be any expression.</p>
</li>
<li><p><code>sif(&lt;condition&gt;) &lt;block&gt;</code>: Executes <code>block</code> if condition is true (not <code>0</code>).</p>
</li>
<li><p><code>selsif(&lt;condition&gt;) &lt;block&gt;</code>: Executes block if all previous <code>sif</code>/<code>selsif</code> conditions were false (<code>0</code>) and this one is true (not <code>0</code>).</p>
</li>
<li><p><code>selse &lt;block&gt;</code>: Executes <code>block</code> if none of the previous conditions were met.</p>
</li>
<li><p><code>swait(&lt;condition&gt;)</code>: Waits until <code>condition</code> becomes true (not <code>0</code>).</p>
</li>
<li><p><code>swhile(&lt;condition&gt;) &lt;block&gt;</code>: Repeats <code>block</code> while condition is true (not <code>0</code>).</p>
</li>
<li><p><code>sfor(&lt;enumerable&gt;) &lt;block&gt;</code>: Iterates over each element of an enumerable object or signal.</p>
</li>
<li><p><code>sbreak</code>: Exits the current loop.</p>
</li>
<li><p><code>scontinue</code>: Skips to the next iteration.</p>
</li>
<li><p><code>sterminate</code>: Ends the sequencer’s execution.</p>
</li>
</ul>
<p><strong>Controlling Sequencers Externally</strong></p>
<p>Two methods can be used to control a sequencer from outside:</p>
<ul>
<li><p><code>alive?</code>: Returns <code>1</code> if the sequencer is still running; <code>0</code> otherwise.</p>
</li>
<li><p><code>reset!</code>: Resets the sequencer to its initial state.</p>
</li>
</ul>
<p>To use these methods, assign the sequencer to a reference variable:</p>
<pre><code class="language-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
</code></pre>
<p><strong>Using Enumerators in Sequences</strong></p>
<p>Within sequencer blocks, HDLRuby provides enumerator methods similar to Ruby’s <code>each</code>. These include:</p>
<ul>
<li><p><code>&lt;object&gt;.seach</code>: <code>object</code> can be any Ruby enumerable or HDLRuby signal. If a block is given, it behaves like sfor; otherwise, it returns an HDLRuby enumerator (see <a href="#hdlruby-enumerators-and-enumerable-objects">enumerator</a> for details).</p>
</li>
<li><p><code>&lt;object&gt;.stimes</code>: Can be used on integers and is equivalent to calling seach on the range <code>0..object-1</code>.</p>
</li>
<li><p><code>&lt;object&gt;.supto(&lt;last&gt;)</code>: Can be used on integers and is equivalent to calling <code>seach</code> on the range<code>object..last</code>.</p>
</li>
<li><p><code>&lt;object&gt;.sdownto(&lt;last&gt;)</code>: Can be used on an integer and is equivalent to calling <code>seach</code> on the range <code>object..last</code> in reverse order.</p>
</li>
</ul>
<p>Objects that support these methods are called <em>enumerable objects</em>. These include HDLRuby signals, HDLRuby enumerators, and all Ruby enumerable types (e.g., ranges, arrays).</p>
<p><strong>Examples</strong></p>
<p>Below are a few examples of sequencers synchronized on the positive edge of <code>clk</code>, starting when <code>start</code> becomes <code>1</code>.</p>
<p><em>Example 1: Fibonacci Sequence</em></p>
<p>his sequencer computes the Fibonacci sequence up to 100, producing a new term in the signal <code>v</code> on each clock cycle:</p>
<pre><code class="language-ruby">require 'std/sequencer.rb'
include HDLRuby::High::Std

system :a_circuit do
   inner :clk, :start
   [16].inner :a, :b
   
   sequencer(clk.posedge,start) do
      a &lt;= 0
      b &lt;= 1
      swhile(v &lt; 100) do
         b &lt;= a + b
         a &lt;= b - a
      end
   end
end
</code></pre>
<p><em>Example 2: Squaring Integers</em></p>
<p>This sequencer computes the square of integers from 10 to 100, producing one result per cycle in signal <code>a</code>:</p>
<pre><code class="language-ruby">inner :clk, :start
[16].inner :a

sequencer(clk.posedge,start) do
   10.supto(100) { |i| a &lt;= i*i }
end
</code></pre>
<p><em>Example 3: Reversing a String in Memory</em></p>
<p>This sequencer reverses the contents of memory <code>mem</code>. The final result will be &quot;!dlrow olleH&quot;:</p>
<pre><code class="language-ruby">inner :clk, :start
bit[8][-12].inner mem: &quot;Hello world!&quot;

sequencer(clk.posedge,start) do
   mem.size.stimes do |i|
      [8].inner :tmp
      tmp       &lt;= mem[i]
      mem[i]    &lt;= mem[-i-1]
      mem[-i-1] &lt;= tmp
   end
end
</code></pre>
<p><em>Example 4: Summing Elements with Early Termination</em></p>
<p>This sequencer computes the sum of the elements in memory <code>mem</code>, stopping if the sum exceeds 16:</p>
<pre><code class="language-ruby">inner :clk, :start
bit[8][-8].inner mem: [ _h02, _h04, _h06, _h08, _h0A, _h0C, _h0E ]
bit[8] :sum

sequencer(clk.posedge,start) do
   sum &lt;= 0
   sfor(mem) do |elem|
      sum &lt;= sum + elem
      sif(sum &gt; 16) { sterminate }
   end
end
</code></pre>
<h3>HDLRuby Sequential Enumerators and Enumerable Objects</h3>
<p>HDLRuby sequential enumerators are objects used to perform iterations within sequencers. They are created using the <code>seach</code> method on enumerable objects, as presented in the previous section.</p>
<p>Enumerators can be controlled using the following methods:</p>
<ul>
<li><p><code>size</code>: Returns the number of elements the enumerator can access.</p>
</li>
<li><p><code>type</code>: Returns the type of elements accessed by the enumerator.</p>
</li>
<li><p><code>seach</code>: Returns the current enumerator. If a block is given, it performs the iteration instead of returning an enumerator.</p>
</li>
<li><p><code>seach_with_index</code>: Returns an enumerator over the elements of the current enumerator, paired with their index positions. If a block is given, it performs the iteration instead.</p>
</li>
<li><p><code>seach_with_object(&lt;obj&gt;)</code>: Returns an enumerator over the elements of the current enumerator, each paired with the given object <code>obj</code> (any object, HDLRuby or otherwise). If a block is given, it performs the iteration instead.</p>
</li>
<li><p><code>with_index</code>: Identical to <code>seach_with_index</code>.</p>
</li>
<li><p><code>with_object(&lt;obj&gt;)</code>: Identical to <code>seach_with_object</code>.</p>
</li>
<li><p><code>clone</code>: Creates a new enumerator over the same elements.</p>
</li>
<li><p><code>speek</code>: Returns the current element pointed to by the enumerator without advancing it.</p>
</li>
<li><p><code>snext</code>: Returns the current element pointed to by the enumerator and then advances to the next one.</p>
</li>
<li><p><code>srewind</code>: Restarts the enumeration from the beginning.</p>
</li>
<li><p><code>+</code>: Concatenates two enumerators.</p>
</li>
</ul>
<p>You can also define a custom enumerator using the following syntax:</p>
<pre><code class="language-ruby">&lt;enum&gt; = senumerator(&lt;typ&gt;,&lt;size&gt;) &lt;block&gt;
</code></pre>
<p>Where:</p>
<ul>
<li><p><code>enum</code> is a Ruby variable referring to the enumerator,</p>
</li>
<li><p><code>typ</code> is the data type of the elements,</p>
</li>
<li><p><code>block</code> is the code block that defines how to access each element by index.</p>
</li>
</ul>
<p>For example, an enumerator over a memory can be defined as follows:</p>
<pre><code class="language-ruby">    bit[8][-8].inner mem: [ _h01, _h02, _h03, _h04, _h30, _h30, _h30, _h30 ]
    [3].inner :addr
    [8].inner :data

    data &lt;= mem[addr]

    mem_enum = senumerator(bit[8],8) do |i|
        addr &lt;= i
        step
        data
    end
</code></pre>
<p>In the code above, <code>mem_enum</code> is a variable referring to the enumerator that accesses memory <code>mem</code>. The access assumes that one clock cycle must pass after setting the address before the data becomes available. Therefore, a step command is used in the block before returning data.</p>
<p><strong>Enumeration Algorithms</strong></p>
<p>Based on the enumerator functionality, several algorithms have been implemented in HDLRuby using sequential enumerators. These algorithms mirror the behavior of Ruby's Enumerable methods and are compatible with all HDLRuby enumerable objects. Each algorithm is implemented in hardware for HDLRuby sequencers and is accessible via the corresponding Ruby method, prefixed with the letter <code>s</code>.</p>
<p>Here are the available methods in detail:</p>
<ul>
<li><p><code>sall?</code>: Sequencer implementation of <code>all?</code>. Returns a 1-bit signal (<code>0</code> for false, <code>1</code> for true).</p>
</li>
<li><p><code>sany?</code>: Sequencer implementation of <code>any?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>schain</code>: Sequencer implementation of <code>chain</code>.</p>
</li>
<li><p><code>smap</code>: Sequencer implementation of <code>map</code>. When used with a block, returns a vector signal containing each computation result.</p>
</li>
<li><p><code>scompact</code>: Sequencer implementation of<code>compact</code>. Since there is no <code>nil</code> in HDLRuby, the value <code>0</code> is used instead. Returns a vector signal containing the compacted result.</p>
</li>
<li><p><code>scount</code>: Sequencer implementation of<code>count</code>. Returns a signal whose bit width matches the enumerator’s size, representing the count result.</p>
</li>
<li><p><code>scycle</code>: Sequencer implementation of <code>cycle</code>.</p>
</li>
<li><p><code>sfind</code>: Sequencer implementation of <code>find</code>. Returns a signal containing the found element, or 0 if not found.</p>
</li>
<li><p><code>sdrop</code>: Sequencer implementation of<code>drop</code>. Returns a vector signal containing the remaining elements.</p>
</li>
<li><p><code>sdrop_while</code>: Sequencer implementation of <code>drop_while</code>. Returns a vector signal containing the remaining elements.</p>
</li>
<li><p><code>seach_cons</code>: Sequencer implementation of <code>each_cons</code>.</p>
</li>
<li><p><code>seach_slice</code>: Sequencer implementation of <code>each_slice</code>.</p>
</li>
<li><p><code>seach_with_index</code>: Sequencer implementation of <code>each_with_index</code>.</p>
</li>
<li><p><code>seach_with_object</code>: Sequencer implementation of <code>each_with_object</code>.</p>
</li>
<li><p><code>sto_a</code>: Sequencer implementation of <code>to_a</code>. Returns a vector signal containing all the elements of the enumerator.</p>
</li>
<li><p><code>sselect</code>: Sequencer implementation of <code>select</code>. Returns a vector signal containing the selected elements.</p>
</li>
<li><p><code>sfind_index</code>: Sequencer implementation of<code>find_index</code>. Returns the index of the found element or -1 if not.</p>
</li>
<li><p><code>sfirst</code>: Sequencer implementation of <code>first</code>. Returns a vector signal containing the first elements.</p>
</li>
<li><p><code>sinclude?</code>: Sequencer implementation of <code>include?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>sinject</code>: Sequencer implementation of <code>inject</code>. Returns a signal of the same type as the enumerator’s elements, containing the result.</p>
</li>
<li><p><code>smax</code>: Sequencer implementation of <code>max</code>. Returns a vector signal containing the found maximum value(s).</p>
</li>
<li><p><code>smax_by</code>: Sequencer implementation of <code>max_by</code>. Returns a vector signal containing the found maximum value(s).</p>
</li>
<li><p><code>smin</code>: Sequencer implementation of <code>min</code>. Returns a vector signal containing the found minimum value(s).</p>
</li>
<li><p><code>smin_by</code>: Sequencer implementation of <code>min_by</code>. Returns a vector signal containing the found minimum value(s).</p>
</li>
<li><p><code>sminmax</code>: Sequencer implementation of <code>minmax</code>. Returns a 2-element vector signal containing the resulting minimum and maximum values.</p>
</li>
<li><p><code>sminmax_by</code>: Sequencer implementation of <code>minmax_by</code>. Returns a 2-element vector signal containing the resulting minimum and maximum values.</p>
</li>
<li><p><code>snone?</code>: Sequencer implementation of <code>none?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>sone?</code>: Sequencer implementation of <code>one?</code>. Returns a 1-bit signal.</p>
</li>
<li><p><code>sreject</code>: Sequencer implementation of <code>reject</code>. Returns a vector signal containing the remaining elements.</p>
</li>
<li><p><code>sreverse_each</code>: Sequencer implementation of <code>reverse_each</code>.</p>
</li>
<li><p><code>ssort</code>: Sequencer implementation of <code>sort</code>. Returns a vector signal containing the sorted elements.</p>
</li>
<li><p><code>ssort_by</code>: Sequencer implementation of <code>sort_by</code>. Returns a vector signal containing the sorted elements.</p>
</li>
<li><p><code>ssum</code>: Sequencer implementation of <code>sum</code>. Returns a signal of the same type as the enumerator’s elements, containing the sum result.</p>
</li>
<li><p><code>stake</code>: Sequencer implementation of <code>take</code>. Returns a vector signal containing the taken elements.</p>
</li>
<li><p><code>stake_while</code>: Sequencer implementation of <code>take_while</code>. Returns a vector signal containing the taken elements.</p>
</li>
<li><p><code>suniq</code>: Sequencer implementation of <code>uniq</code>. Returns a vector signal containing the selected elements.</p>
</li>
</ul>
<h3>Shared Signals, Arbiters, and Monitors</h3>
<h4>Shared Signals</h4>
<p>s with any other process, multiple sequencers cannot write to the same signal. Doing so would cause race conditions, which can physically damage the device if permitted. In standard RTL design, this issue is typically handled using three-state buses, multiplexers, and arbiters.</p>
<p>However, HDLRuby sequencers introduce a special kind of signal called a <em>shared signal</em>, which abstracts away these implementation details and prevents race conditions.</p>
<p>Shared signals are declared similarly to regular signals, based on their type. The syntax is:</p>
<pre><code class="language-ruby">&lt;type&gt;.shared &lt;list of names&gt;
</code></pre>
<p>They can also be initialized with default values as follows:</p>
<pre><code class="language-ruby">&lt;type&gt;.shared &lt;list of names with initialization&gt;
</code></pre>
<p>For example, the following code declares two 8-bit shared signals <code>x</code> and <code>y</code>, and two signed 16-bit shared signals <code>u</code> and <code>v</code>, both initialized to 0:</p>
<pre><code class="language-ruby">[8].shared :x, :y
signed[8].shared u: 0, v: 0
</code></pre>
<p>A shared signal can be read from and written to by any sequencer, from anywhere in the subsequent code within the current scope. However, shared signals cannot be written to outside of a sequencer.</p>
<p>Valid example:</p>
<pre><code class="language-ruby">input :clk, :start
[8].inner :val0, :val1
[8].shared :x, :y

val0 &lt;= x+y
par(clk.posedge) { val1 &lt;= x+y }

sequencer(clk.posedge,start) do
   10.stimes { |i| x &lt;= i }
end

sequencer(clk.posedge,start) do
   5.stimes { |i| x &lt;= i*2 ; y &lt;= i*2 }
end
</code></pre>
<p>Invalid example:</p>
<pre><code class="language-ruby">[8].shared w: 0

par(clk.posedge) { w &lt;= w + 1 }
</code></pre>
<p>By default, a shared signal acknowledges writes from the first sequencer that attempts to write to it (in order of declaration). All other writes are ignored. In the valid example above, the value of <code>x</code> is always set by the first sequencer, producing values from 0 to 9, changing once per clock cycle. The signal <code>y</code>, however, is only written by the second sequencer and thus reflects its values.</p>
<p>This default behavior avoids race conditions but offers limited flexibility. To gain better control, you can explicitly select which sequencer is allowed to write to a shared signal. This is done using the <code>select</code> sub-signal of the shared signal:</p>
<pre><code class="language-ruby">&lt;shared signal&gt;.select &lt;= &lt;index&gt;
</code></pre>
<p>The selection index starts at 0 for the first sequencer writing to the signal, 1 for the second, and so on.</p>
<p>For example, to allow the second sequencer to write to x, you can add the following line after declaring <code>x</code>:</p>
<pre><code class="language-ruby">   x.select &lt;= 1
</code></pre>
<p>This selection can also be changed dynamically at runtime. For instance, to alternate the writer every clock cycle:</p>
<pre><code class="language-ruby">   par(clk.posedge) { x.select &lt;= x.select + 1 }
</code></pre>
<p><strong>Note</strong>: The <code>select</code> sub-signal is a standard RTL signal and is subject to the same rules and limitations as any other non-shared signal. It is not itself a shared signal.</p>
<h4>Arbiters</h4>
<p>In most cases, it's not the signals themselves that we want to share, but rather the resources they control. For example, in a CPU, it's the ALU that is shared as a whole -- not each of its inputs separately. To support such scenarios and simplify the handling of shared signals, HDLRuby provides arbiter components.</p>
<p>An arbiter is instantiated like a standard module. The syntax is as follows, where <code>name</code> is the name of the arbiter instance:</p>
<pre><code class="language-ruby">arbiter(:&lt;name&gt;).(&lt;list_of_shared_signal&gt;)
</code></pre>
<p>When instantiated, the arbiter takes control of the <code>select</code> sub-signals of the specified shared signals. As a result, you can no longer manually set the <code>select</code> values for those signals. In exchange, the arbiter allows sequencers to request or release write access to the shared signals.</p>
<p>To request access, a sequencer assigns the value 1 to the arbiter. To release access, it assigns 0. If a sequencer attempts to write to a shared signal under arbitration without first requesting access, the write will be ignored.</p>
<p><strong>Example</strong></p>
<p>The following example defines an arbiter named <code>ctrl_xy</code> that manages access to shared signals <code>x</code> and <code>y</code>, along with two sequencers that request and release access to them:</p>
<pre><code class="language-ruby">input :clk, :start
[8].shared x, y
arbiter(:ctrl_xy).(x,y)

sequencer(clk.posedge,start) do
   ctrl_xy &lt;= 1
   x &lt;= 0 ; y &lt;= 0
   5.stime do |i|
      x &lt;= x + 1
      y &lt;= y + 2
   end
   ctrl_xy &lt;= 0
end

sequencer(clk.posedge,start) do
   ctrl_xy &lt;= 1
   x &lt;= 2; y &lt;= 1
   10.stime do |i|
      x &lt;= x + 2
      y &lt;= y + 1
   end
   ctrl_xy &lt;= 0
end
</code></pre>
<p>In this example, both sequencers request access before writing to the shared signals and release it afterward.</p>
<p><strong>Note</strong>: Requesting access does not guarantee that access will be granted. If access is not granted, write operations will be ignored.</p>
<p>By default, the arbiter grants access based on the order of sequencer declaration. That is, if multiple sequencers request access simultaneously, the one declared first in the code has priority.</p>
<p>In the example above, the first sequencer is granted write access to <code>x</code> and <code>y</code> and holds it for five cycles. Once it releases access, the second sequencer gains control and begins writing. The second sequencer runs its first five iterations without affecting the shared signals—only the last five are effective.</p>
<p>To avoid wasting cycles in such situations, a sequencer can check whether it currently holds write access by using the arbiter’s <code>acquired</code> sub-signal. This signal is 1 if the sequencer has been granted access and 0 otherwise. For example, the following line will increment <code>x</code> only when access is granted:</p>
<pre><code class="language-ruby">hif(ctrl_xy.acquired) { x &lt;= x + 1 }
</code></pre>
<p><strong>Changing Arbiter Policy</strong></p>
<p>You can change the arbiter's access-granting policy using the <code>policy</code> method. One option is to provide a priority list -- a vector of sequencer indices in order of decreasing priority (i.e., the first entry has the highest priority). Sequencers are numbered in the order they are declared and use the arbiter.</p>
<p>For example, to give the second sequencer priority over the first in the earlier example, you could write:</p>
<pre><code class="language-ruby">ctrl_xy.policy([1,0])
</code></pre>
<p>You can also define more complex arbitration logic by passing a block to <code>policy</code>. This block receives a vector (<code>acq</code>) indicating which sequencers are currently requesting access (each bit set to 1 means a request is active), and returns the index of the sequencer to be granted access.</p>
<p>Here’s an example that alternates the priority at each access:</p>
<pre><code class="language-ruby">inner priority_xy: 0
inner grant_xy
ctrl_xy.policy do |acq|
   hcase(acq)
   hwhen(_b01) do
      grant_xy &lt;= 0
      priority_xy &lt;= ~priority_xy
   end
   hwhen(_b10) do
      grant_xy &lt;= 1
      priority_xy &lt;= ~priority_xy
   end
   hwhen(_b11) do
      grant_xy &lt;= priority_xy
      priority_xy &lt;= ~priority_xy
   end
   grant_xy
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>acq</code> is a bit vector where bit 0 corresponds to sequencer 0, bit 1 to sequencer 1, etc.</p>
</li>
<li><p>he policy toggles <code>priority_xy</code> after each access, thereby switching priority between sequencers.</p>
</li>
</ul>
<h4>Monitors</h4>
<p>Arbiters are especially useful when sequencers accessing the same resource do not overlap in time or do not need to synchronize with each other. However, when synchronization is required -- meaning a sequencer must wait until it has exclusive access before proceeding -- <em>a monitor</em> is more appropriate.</p>
<p>Monitors are instantiated in the same way as arbiters:</p>
<pre><code class="language-ruby">monitor(:&lt;name&gt;).(&lt;list_of_shared_signals&gt;)
</code></pre>
<p>Like arbiters, monitors manage shared signals and support the same write-access granting policies. However, unlike arbiters, monitors block the execution of a sequencer that requests access until the access is granted. This guarantees that a sequencer’s operations on shared signals are performed without interruption or interference from other sequencers.</p>
<p><strong>Example</strong></p>
<p>Let’s revisit the previous arbiter-based example. If we replace the arbiter with a monitor:</p>
<pre><code class="language-ruby">monitor(:ctrl_xy).(x,y)
</code></pre>
<p>Then the second sequencer will be paused until it is granted access to shared signals <code>x</code> and <code>y</code>. This ensures that all iterations of its loop are performed as intended, without being skipped or ignored.</p>
<p>Since monitors block execution, they implicitly insert a <code>step</code>. To make this behavior explicit and clear, acquiring access to a monitor is done using the <code>lock</code> method (instead of assigning 1), and releasing access is done using the <code>unlock</code> method (instead of assigning 0).</p>
<p>Here is the rewritten version of the previous example using a monitor:</p>
<pre><code class="language-ruby">input :clk, :start
[8].shared x, y
monitor(:ctrl_xy).(x,y)

sequencer(clk.posedge,start) do
   ctrl_xy.lock
   x &lt;= 0 ; y &lt;= 0
   5.stime do |i|
      x &lt;= x + 1
      y &lt;= y + 2
   end
   ctrl_xy.unlock
end

sequencer(clk.posedge,start) do
   ctrl_xy.lock
   x &lt;= 2; y &lt;= 1
   10.stime do |i|
      x &lt;= x + 2
      y &lt;= y + 1
   end
   ctrl_xy.unlock
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p>Each sequencer waits to acquire exclusive access before proceeding.</p>
</li>
<li><p>The monitor guarantees mutual exclusion, ensuring no interleaved writes occur.</p>
</li>
<li><p>The <code>lock</code> and <code>unlock</code> methods clearly define the critical section.</p>
</li>
</ul>
<h3>Sequencer-Specific Functions</h3>
<p>HDLRuby functions defined with <code>hdef</code> can be used within sequencers like any other HDLRuby construct. However, just like process constructs such as <code>hif</code>, the body of an <code>hdef</code> function cannot include any sequencer-specific constructs.</p>
<p>To define functions that do support sequencer-specific constructs, use <code>sdef</code> instead of <code>hdef</code>. The syntax is:</p>
<pre><code class="language-ruby">   sdef :&lt;function_name&gt; do |&lt;arguments&gt;|
   # Sequencer code
   end
</code></pre>
<p>Functions defined with <code>sdef</code> can be declared anywhere in an HDLRuby description but can only be called from within a sequencer.</p>
<p><strong>Recursion Support</strong></p>
<p>Since <code>sdef</code> is intended to support software-like control structures, it also supports recursion. For example, a recursive factorial function can be defined as follows:</p>
<pre><code class="language-ruby">sdef(:fact) do |n|
    sif(n &gt; 1) { sreturn(n*fact(n-1)) }
    selse      { sreturn(1) }
end
</code></pre>
<p>As shown above, the <code>sreturn</code> construct is used to return a value from within the body of an <code>sdef</code> function.</p>
<p>When recursion is used, HDLRuby automatically allocates a stack to store the return state and the function arguments. The stack size is heuristically determined based on the maximum bit width of the function arguments at the time of the recursive call.</p>
<p>For example, if the argument <code>n</code> in the fact function is 16 bits, the stack will support up to 16 recursive calls.</p>
<p>If this heuristic is insufficient, you can manually set the stack size by providing a second argument to <code>sdef</code>:</p>
<pre><code class="language-ruby">sdef(:fact,32) do |n|
    sif(n &gt; 1) { sreturn(n*fact(n-1)) }
    selse      { sreturn(1) }
end
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>Each recursive function call takes one sequencer cycle, and each return takes two cycles.</p>
</li>
<li><p>Tail-call optimization is currently not supported.</p>
</li>
<li><p>If the number of recursive calls exceeds the available stack size (i.e., a stack overflow occurs), the current recursion is terminated, and the sequencer continues execution normally.</p>
</li>
<li><p>To handle stack overflows explicitly, you can attach a handler process using a proc block as a third argument to <code>sdef</code>:</p>
<pre><code class="language-ruby">   sdef(:&lt;name&gt;,&lt;depth&gt;, proc &lt;block&gt;) do
      &lt;function code&gt;
   end
</code></pre>
<p><strong>Important:</strong> The overflow handler block cannot contain sequencer-specific constructs.</p>
<p>For example, the factorial function can be modified to set a <code>stack_overflow</code> signal in case of overflow:</p>
<pre><code class="language-ruby">sdef(:fact,32, proc { stack_overflow &lt;= 1 }) do |n|
    sif(n &gt; 1) { sreturn(n*fact(n-1)) }
    selse      { sreturn(1) }
end
</code></pre>
<p>In the code above, the signal <code>stack_overflow</code> must be declared before calling the fact function.</p>
</li>
</ul>
<h3>Sequencers as Software Code</h3>
<h4>Introduction to Sequencer as Software Code</h4>
<p>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:</p>
<pre><code class="language-ruby">require 'HDLRuby/std/sequencer_sw'
include RubyHDL::High
using RubyHDL::High
</code></pre>
<p>After this, signals and sequencers can be described exactly as in HDLRuby. However, unlike in hardware simulation, sequencer objects are not executed immediately -- they must be assigned to a variable for later execution.</p>
<p>For example, the following Ruby code defines a sequencer (referenced by the variable <code>my_seq</code>) that increments the signal <code>counter</code> up to 1000:</p>
<pre><code class="language-ruby">require 'HDLRuby/std/sequencer_sw'
include RubyHDL::High
using RubyHDL::High

[32].inner :counter

my_seq = sequencer do
   counter &lt;= 0
   1000.stimes do
      counter &lt;= counter + 1
   end
end
</code></pre>
<p>You may notice that no clock or start signal is provided to the sequencer. This is because, in software execution, everything runs sequentially -- no clock or control signals are needed. Instead, you start the sequencer by calling it directly using the function call syntax:</p>
<pre><code class="language-ruby">my_seq.()
</code></pre>
<p>To check whether the sequencer executed correctly, you can read signal values outside the sequencer using the <code>value</code> method. For instance, the code below initializes <code>counter</code> to 0, runs the sequencer, and then prints the final value:</p>
<pre><code class="language-ruby">require 'HDLRuby/std/sequencer_sw'
include RubyHDL::High
using RubyHDL::High

[32].inner :counter

counter.value = 0

my_seq = sequencer do
   counter &lt;= 0
   1000.stimes do
      counter &lt;= counter + 1
   end
end

my_seq.()

puts &quot;counter=#{counter.value}&quot;
</code></pre>
<p><strong>Note</strong>: When printing the value of a signal, the <code>value</code> method can be omitted, as signals are implicitly converted to their current value. For example, the last line above can also be written as:</p>
<pre><code class="language-ruby">puts &quot;counter=#{counter}&quot;
</code></pre>
<p>Internally, the HDLRuby code of a sequencer is translated to Ruby before execution. This generated Ruby code can be accessed using the <code>source</code> method. You can save it to a file for standalone execution, as shown below:</p>
<pre><code class="language-ruby">File.open(&quot;sequencer_in_ruby.rb&quot;,&quot;w&quot;) do |f|
   f &lt;&lt; my_seq.source
end
</code></pre>
<p>You can also generate C or Python code from the sequencer using the <code>to_c</code> and <code>to_python</code> methods, respectively. The following commands create equivalent C and Python files from <code>my_seq</code>:</p>
<pre><code class="language-ruby">File.open(&quot;sequencer_in_c.c&quot;,&quot;w&quot; do |f|
   f &lt;&lt; my_seq.to_c
end

File.open(&quot;sequencer_in_python.py&quot;,&quot;w&quot; do |f|
   f &lt;&lt; my_seq.to_python
end
</code></pre>
<p><strong>Notes:</strong></p>
<ul>
<li><p>Currently, synchronization commands (presented in section <a href="#synchronizing-sequencers-for-pseudo-parallel-execution">Synchronizing Sequencers for Pseudo-Parallel Execution</a> are not yet supported in the C and Python backends.</p>
</li>
<li><p>The Ruby code for sequencers is compatible with mruby, making it suitable for execution on embedded systems.</p>
</li>
<li><p>You can also generate experimental TensorFlow code using the <code>to_tf</code> method.</p>
</li>
</ul>
<h4>Why Would I Want to Execute a Sequencer in Software, and What are the Limitations?</h4>
<p>There are two main reasons for executing sequencers in software:</p>
<ol>
<li><strong>High-speed simulation</strong></li>
</ol>
<p>Software-executed sequencers run approximately 10 times faster than those simulated using the HDLRuby simulator.</p>
<ol start="2">
<li><strong>Seamless transition from software to hardware</strong></li>
</ol>
<p>In early design stages, it is often unclear whether a given component will ultimately be implemented in software or hardware. Using the same code for both provides:</p>
<ul>
<li><p>Reliability -- guaranteed functional equivalence between software and hardware.</p>
</li>
<li><p>Reduced design time -- no need to rewrite or duplicate code.</p>
</li>
</ul>
<hr>
<p>While software-based sequencers are functionally equivalent to their hardware counterparts, they differ fundamentally in how they handle time and parallelism:</p>
<ul>
<li><p>In hardware, sequencers are implemented as finite state machines that respond to a clock and run in parallel with the rest of the circuit.</p>
</li>
<li><p>In software, sequencers are implemented as fibers that execute sequentially.</p>
</li>
</ul>
<p>This distinction means that software sequencers may not be suitable for designs that rely heavily on timing or parallelism, such as communication protocols.</p>
<p>However, there are ways to introduce hardware-like timing and concurrency, which are described in the following sections.</p>
<h4>Adding a Clock to a Software Sequencer.</h4>
<p>As mentioned earlier, software execution does not involve a hardware clock. However, you can simulate a clock during the execution of a software sequencer to estimate its performance as if it were implemented in hardware.</p>
<p>This is done by passing a signal as an argument to the sequencer. That signal will be incremented at each simulated clock cycle:</p>
<pre><code class="language-ruby">sequencer(&lt;clock_counting_signal&gt;) do
  ...
end
</code></pre>
<p>After execution, the total number of estimated clock cycles is stored in the clock count signal. For example, the following code displays <code>1000 clocks</code>, which represents the number of cycles the sequencer would take if implemented in hardware:</p>
<pre><code class="language-ruby">[32].inner :clk_count
clk_count.value = 0

sequencer(clk_count) do
   1000.stimes
end.()

puts &quot;#{clk_count} clocks&quot;
</code></pre>
<p><strong>Note</strong>: In the example above, the sequencer is not stored in a variable because it is executed immediately upon definition.</p>
<h4>Adding a Signal to Control the Execution of a Software Sequencer.</h4>
<p>In addition to a clock counter signal, you can pass a start signal to control when a software sequencer begins execution—just like in hardware implementations.</p>
<p>To do this, pass the start signal as the second argument to the <code>sequencer</code> function. For example, in the code below, the sequencer begins executing when the start <code>signal</code> is set to <code>1</code>:</p>
<pre><code class="language-ruby">[32].inner :clk_count
[1].inner :start
clk_count.value = 0

sequencer(clk_count,start) do
   1000.stimes
end

start.value = 1

puts &quot;#{clk_count} clocks&quot;
</code></pre>
<p>In this mode, you don’t need to store the sequencer in a Ruby variable. Execution begins just like in hardware, and the sequencer can also be triggered from another sequencer.</p>
<p><strong>Controlling One Sequencer from Another</strong></p>
<p>The example below shows two sequencers, where the first sequencer controls the start of the second by setting the <code>start1</code> signal to <code>1</code>:</p>
<pre><code class="language-ruby">[1].inner :start0, :start1
[8].inner :count0, :count1

sequencer(nil,start0) do
   count0 &lt;= 0
   swhile(count0&lt;100) { count0 &lt;= count0 + 1 }
   start1 &lt;= 1
end

sequencer(nil,start1) do
   count1 &lt;= 0
   swhile(count1&lt;100) { count1 &lt;= count1 + 1 }
end
</code></pre>
<h4>Synchronizing Sequencers for Pseudo-Parallel Execution</h4>
<p>In software, sequencers normally run to completion before any other code is executed. However, you can simulate parallel execution by using the <code>sync</code> command. While <code>sync</code> has no hardware equivalent, it can be used in software to pause and resume sequencers in a controlled, cooperative manner.</p>
<p>When a <code>sync</code> command is encountered during execution:</p>
<ul>
<li><p>The sequencer is paused.</p>
</li>
<li><p>Control is returned to the code following the sequencer's start.</p>
</li>
<li><p>The paused sequencer can later be resumed by either:</p>
<ul>
<li><p>Calling it again using the call operator (<code>my_seq.()</code>), or</p>
</li>
<li><p>Setting its associated start signal to <code>1</code>.</p>
</li>
</ul>
</li>
</ul>
<p><strong>Example: Pausing and Resuming a Sequencer</strong></p>
<p>In the following example, the sequencer runs until <code>count</code> reaches 20, then pauses. After resuming, it continues up to 40:</p>
<pre><code class="language-ruby">
[32].inner :count

my_seq = sequencer do
   count &lt;= 0
   20.stimes
      count &lt;= count + 1
   sync
   20.stimes
      count &lt;= count + 1
   end
end

my_seq.()
puts &quot;stop at count=#{count}&quot;
my_seq.()
puts &quot;end at count=#{count}&quot;
</code></pre>
<p><strong>Cycle-Accurate Synchronization</strong></p>
<p>To simulate cycle-accurate synchronization, you could insert a <code>sync</code> call at each estimated clock cycle. However, this comes with a performance cost. Depending on the Ruby interpreter and system configuration, heavy use of <code>sync</code> may cause software execution to become slower than the HDLRuby hardware simulator.</p>
<p><strong>Recommendation:</strong> Use <code>sync</code> only when necessary for modeling concurrency or interleaving. For cycle-accurate simulation, prefer using HDLRuby's hardware simulation mode.</p>
<p><strong>Checking If a Sequencer Is Still Running</strong></p>
<p>To check whether a sequencer is still active or paused (e.g., waiting at a <code>sync</code>), use the <code>alive?</code> method. For example, the following loop resumes the sequencer until it finishes:</p>
<pre><code class="language-ruby">my_seq.() while(my_seq.alive?)
</code></pre>
<h4>Executing ruby code within a software sequencer.</h4>
<p>When running a sequencer in software, HDLRuby provides an additional command called <code>ruby</code>, which allows execution of plain Ruby code inside a sequencer block.</p>
<p>For example, the following code prints <code>Hello</code> ten times using Ruby's <code>puts</code> method:</p>
<pre><code class="language-ruby">sequencer do
   stimes.10 do
      ruby { puts &quot;Hello&quot; }
   end
end.()
</code></pre>
<p>Alternatively, you can generate Ruby code dynamically using the <code>text</code> or <code>expression</code> commands:</p>
<ul>
<li><p><code>text</code> inserts a Ruby statement.</p>
</li>
<li><p><code>expression</code> inserts a Ruby expression.</p>
</li>
</ul>
<p>Both functions format their arguments similarly to the C <code>printf</code> function.</p>
<p>For example, the following code prints <code>Hello 0</code> through <code>Hello 9</code> when executed:</p>
<pre><code>sequencer do
   stimes.10 do |i|
      text(&quot;puts \&quot;Hello %d\&quot;&quot;,i)
   end
end.()
</code></pre>
<p><strong>Choosing Between ruby, text, and expression</strong></p>
<ul>
<li><p><code>ruby</code> is safer, as errors are checked at compile time, but it is slower and incompatible with separate code generation (e.g., for C or Python).</p>
</li>
<li><p><code>text</code> and <code>expression</code> allow faster execution and code export, but offer less safety, as errors are only detected at run time.</p>
</li>
</ul>
<p><strong>Accessing Signal Values in text and expression Generated Code</strong></p>
<p>Since the string passed to <code>text</code> and <code>expression</code> is inserted as-is into the generated Ruby (or C) code, you cannot directly embed signal values into it. To include signal values safely and correctly, use:</p>
<ul>
<li><p><code>to_ruby</code>, <code>to_c</code>, or <code>to_python</code> to get the raw value in the corresponding language.</p>
</li>
<li><p><code>value_text</code> for a hardware-accurate representation (handling overflow/underflow).</p>
</li>
</ul>
<pre><code class="language-ruby">sequencer do
   text(&quot;puts #{sig0.to_ruby}&quot;)
   text(&quot;puts #{sig1.value_text}&quot;)
end
</code></pre>
<h4>Using Software Sequencer Inside a HDLRuby program.</h4>
<p>HDLRuby supports hardware/software co-design through the <code>program</code> <a href="#declaring-a-software-component">construct</a>. Since software sequencers are software components, they can be used within this construct when the selected language is Ruby.</p>
<p>To enable software sequencer functionality in Ruby, you must insert the following command at the beginning of the code block:</p>
<pre><code class="language-ruby">activate_sequencer_sw(binding)
</code></pre>
<p>Software sequencers can also be used with the C language, but in that case, the corresponding C code must be explicitly generated beforehand using the <code>to_c</code> method.</p>
<p><strong>Connecting Signals to Program Ports</strong></p>
<p>When writing Ruby software within a <code>program</code>, the signals used by the software sequencer can be automatically connected to the RTL-level ports by declaring them as:</p>
<ul>
<li><p><code>inport</code> for input signals, and</p>
</li>
<li><p><code>outport</code> for output signals.</p>
</li>
</ul>
<p>The following example describes a software sequencer that copies the value from the input port <code>inP</code> to the output port <code>outP</code>. The signals <code>sig0</code> and <code>sig1</code> come from the surrounding RTL design.</p>
<pre><code class="language-ruby">program(:ruby) do
  actport clk.posedge
  inport inP: sig0
  outport outP: sig1
  code do
    activate_sequencer_sw(binding)
    input :inP
    output :outP
    sequencer do
      outP &lt;= inP
    end
  end
end
</code></pre>
<p>In this example:</p>
<ul>
<li><p><code>actport</code> specifies that the Ruby code is triggered on the positive edge of the clock signal.</p>
</li>
<li><p>The <code>input</code> and <code>output</code> declarations inside the code block mirror the port names, making them accessible within the sequencer.</p>
</li>
<li><p><code>activate_sequencer_sw(binding)</code> initializes the environment for using HDLRuby software sequencers.</p>
</li>
</ul>
<h2>Fixed-Point</h2>
<p>This library provides a set of fixed-point data types for use in HDLRuby designs. These types can represent:</p>
<ul>
<li><p>Bit (or unsigned) values.</p>
</li>
<li><p>Signed values.</p>
</li>
</ul>
<p>They are declared using the following syntax:</p>
<pre><code class="language-ruby">bit[&lt;integer_part_range&gt;,&lt;fractional_part_range&gt;]
unsigned[&lt;integer_part_range&gt;,&lt;fractional_part_range&gt;]
signed[&lt;integer_part_range&gt;,&lt;fractional_part_range&gt;]
</code></pre>
<p>For example, the following code declares a signed fixed-point signal named <code>sig</code> with 4 bits for the integer part and 4 bits for the fractional part:</p>
<pre><code class="language-ruby">bit[4,4].inner :sig
</code></pre>
<p>When performing arithmetic operations on fixed-point types, HDLRuby automatically adjusts the decimal point position to maintain correct precision in the result.</p>
<p><strong>Converting Literals to Fixed-Point</strong></p>
<p>A method is also provided to convert numeric literals (such as integers or floats) to fixed-point format:</p>
<pre><code class="language-ruby">&lt;litteral&gt;.to_fix(&lt;number_of_bits_after_the_decimal_point&gt;)
</code></pre>
<p>For example, the following code converts the floating-point number 3.178 to a fixed-point representation with 16 fractional bits:</p>
<pre><code>3.178.to_fix(16)
</code></pre>
<!--

## Channel
<a name="channel"></a>

This library provides a unified interface to complex communication protocols through a new kind of component called the channels that abstract the details of communication protocols. The channels can be used similarly to the ports of a system and are used through a unified interface so that changing the kind of channel, i.e., the communication protocol, does not require any modification of the code.

### Using a channel

A channel is used similarly to a pipe: it has an input where data can be written and an output where data can be read. The ordering of the data and the synchronization depend on the internals of the channel, e.g., a channel can be FIFO or LIFO. The interaction with the channel is done using the following methods:

* `write(<args>) <block>`: write to the channel and execute `block` when `write` completes. `args` is a list of arguments required for performing the write that depends on the channel.

* `read(<args>) <block>`: read the channel and execute `block` when the read completes. `args` is a list of arguments required for performing the write that depends on the channel.


For example, a system sending successive 8-bit values through a channel can be described as follows:

```ruby
system :producer8 do |channel|
    # Inputs of the producer: clock and reset.
    input :clk, :rst
    # Inner 8-bit counter for generating values.
    [8].inner :counter

    # The value production process
    par(clk.posedge) do
        hif(rst) { counter <= 0 }
        helse do
            channel.write(counter) { counter <= counter + 1 }
        end
    end
end
```

__Note__: In the code above, the channel is passed as a generic argument of the system.

The access points to a channel can also be handled individually by declaring ports using the following methods:
 
* `input <name>`: declares a port for reading from the channel and associates them to `name` if any

* `output <name>`: declares a port for writing to the channel and associates them to `name` if any

* `inout <name>`: declares a port for reading and writing to the channel and associates them to `name` if any

Such a port can then be accessed using the same `read` and `write` method of a channel, the difference being that they can also be configured for new access procedures using the `wrap` method:

* `wrap(<args>) <code>`: creates a new port whose read or write procedure has the elements of `<args>` and the ones produced by `<code>` assigned to the arguments of the read or write procedure.

For example, assuming `mem` is a channel whose read and write access have as argument the target address and data signals, the following code creates a port for always accessing at address 0:

```ruby
  addr0 = channel.input.wrap(0) 
```

### Channel branches

Some channels may include several branches, they are accessed by name using the following method:
 
* `branch(<name>)`: gets branch named `name` from the channel. This name can be any ruby object (e.g., a number) but it will be converted internally to a ruby symbol.

A branch is a full-fledged channel and is used identically. For instance, the following code gets access to branch number 0 of channel `ch`, gets its inputs port, reads it, and put the result in signal `val` on the rising edges of signal `clk`:

```ruby
br = ch.branch(0)
br.input
par(clk.posedge) { br.read(val) }
```

### Declaring a channel

A new channel is declared using the keyword `channel` as follows:

```ruby
channel <name> <block>
```

Where `name` is the name of the channel and `block` is a procedure block describing the channel. This block can contain any HDLRuby code, and is comparable to the content of a block describing a system with the difference that it does not have standard input, output, and inout ports are declared differently, and that it supports the following additional keywords:

* `reader_input <list of names>`: declares the input ports on the reader side. The list must give the names of the inner signals of the channel that can be read using the reader procedure.

* `reader_output <list of names>`: declares the output ports on the reader side. The list must give the names of the inner signals of the channel that can be written using the reader procedure.

* `reader_inout <list of names>`: declares the inout ports on the reader side. The list must give the names of the inner signals of the channel that can be written using the reader procedure.

* `writer_input <list of names>`: declares the input ports on the writer side. The list must give the names of the inner signals of the channel that can be read using the writer procedure.

* `writer_output <list of names>`: declares the output ports on the writer side. The list must give the names of the inner signals of the channel that can be written using the writer procedure.

* `writer_inout <list of names>`: declares the inout ports on the writer side. The list must give the names of the inner signals of the channel that can be written using the writer procedure.

* `accesser_input <list of names>`: declares the input ports on both the reader and writer sides. The list must give the names of the inner signals of the channel that can be read using the writer procedure.

* `accesser_output <list of names>`: declares the output ports on both the reader and writer sides. The list must give the names of the inner signals of the channel that can be written using the writer procedure.

* `accesser_inout <list of names>`: declares the inout ports on both the reader and writer sides. The list must give the names of the inner signals of the channel that can be written using the writer procedure.

* `reader <block>`: defines the reader's access procedure.
   This procedure is invoked by the method `read` of the channel (please refer to the previous example).
 The first argument of the block must be the following:
   - `blk`: the block to execute when the read completes.
 Other arguments can be freely defined and will be required by the `read` method.

* `writer < block>`: defines the writer's access procedure.
   This procedure is invoked by the method `write` of the channel (please refer to the previous example).
 The first argument of the block must be the following:
   - `blk`: the block to execute when the write completes.
 Other arguments can be freely defined and will be required by the `write` command.

* `brancher(name) <block>`: defines branch named +name+ described in `block`. The content of the block can be any content valid for a channel, with the additional possibility to access the internals of the upper channel.

For example, a channel implemented by a simple register of generic type `typ`, that can be set to 0 using the `reset` command can be described as follows:

```ruby
channel :regch do |typ|
   # The register.
   typ.inner :reg

   # The reader procedure can read reg
   reader_input :reg
   # The writer procedure can write reg
   writer_output :reg

   # Declares a reset
   command(:reset) { reg <= 0 }

   # Defines the reader procedure.
   reader do |blk,target|
      target <= reg
      blk.call if blk
   end

   # Defines the writer procedure.
   writer do |blk,target|
      reg <= target
      blk.call if blk
   end
end
```

__Notes__:

* The described channel assumes that the `write` method of the channel is invoked within a clocked process (otherwise, the register will become a latch).

* The described channel supports the `read` and `write` methods to be invoked with or without a block.


Like systems, a channel must be instantiated for being used, and the instantiation procedure is identical: 

```ruby
<channel name> :<instance name>
```

And in case there is a generic parameter, the instantiation procedure is as follows:

```ruby
<channel name>(:<instance name>).(<generic parameters>)
```

After a channel is instantiated, it must be linked to the circuits that will communicate through it. This is done when instantiating these circuits. If a circuit reads or writes on the channel, it will be instantiated as follows:

```ruby
<system name>(<channel instance>).(:<instance name>).(<circuit standard connections>)
```


__Notes__:

* It is possible for a circuit to access several channels. For that purpose, each channel must be passed as generic arguments, and their corresponding `reader_signals` and `writer_signals` are to be put in the order of declaration.

* It is also possible for a circuit to read and write on the same channel. For that purpose, the channel will be passed several times as generic arguments, and the corresponding `reader_signals` and `writer_signals` are to be put in the order of declaration.

The following code is an example instantiating the register channel presented above for connecting an instance of `producer8` and another circuit called `consumer8`:

```ruby
# System wrapping the producer and the consumer circuits.
system :producer_consumer8 do
   # The clock and reset of the circuits
   input :clk, :rst

   # Instance of the channel (using 8-bit data).
   regch([8]).(:regchI)

   # Reset the channel on positive edges of signal rst.
   regchI.reset.at(rst.posedge)

   # Instantiate the producer.
   producer8(regch).(:producerI).(clk,rst)

   # Instantiate the consumer.
   consumer8(regch).(:consumerI).(clk.rst)
end
```

__Note__: The code of the circuits, in the examples `producer8`, `consumer8`, and `producer_consummer8` is independent of the content of the channel. For example, the sample `with_channel.rb` (please see [samples](#sample-hdlruby-descriptions)) uses the same circuits with a channel implementing handshaking.

-->
<!---

## Pipeline
<a name="pipeline"></a>

This library provides a construct for an easy description of pipeline architectures.

-->
<h1>Sample HDLRuby descriptions</h1>
<p>Several samples HDLRuby descriptions are available in the following directory:</p>
<pre><code class="language-bash">path/to/HDLRuby/lib/HDLRuby/hdr_samples
</code></pre>
<p>If you installed HDLRuby as a gem, you can find the installation path by running:</p>
<pre><code class="language-bash">gem which HDLRuby
</code></pre>
<p>However, the recommended way to access the samples is to import them into your local directory using the following command:</p>
<pre><code class="language-bash">hdrcc --get-samples
</code></pre>
<p><strong>Naming Conventions for Sample Files</strong></p>
<p>The samples follow a naming convention:</p>
<ul>
<li><p><code>&lt;name&gt;.rb</code>:</p>
<p>A standard sample, requiring no parameters.</p>
</li>
<li><p><code>&lt;name&gt;_gen.rb</code>:</p>
<p>A sample that requires generic parameters for processing.</p>
</li>
<li><p><code>&lt;name&gt;_bench.rb</code>:</p>
<p>A sample that includes a simulation benchmark. These are the only samples that can be simulated using the hdrcc -S command.</p>
</li>
<li><p><code>with_&lt;name&gt;.rb</code>:</p>
<p>A sample that illustrates a specific feature of HDLRuby or one of its libraries. These usually include a benchmark.</p>
</li>
</ul>
<h1>Converting Verilog HDL to HDLRuby</h1>
<p>While the HDLRuby framework does not yet support Verilog HDL files as direct input, a standalone tool is provided to convert Verilog files to HDLRuby. To perform this conversion, use the following command:</p>
<pre><code class="language-bash">v2hdr &lt;input_Verilog_HDL_file&gt; &lt;output_HDLRuby_file&gt;
</code></pre>
<p>For example, assuming you have a Verilog HDL file named <code>adder.v</code> that describes an adder circuit, you can convert it to HDLRuby using:</p>
<pre><code class="language-bash">v2hdr adder.v adder.v.rb
</code></pre>
<p><strong>Alternative: Loading Verilog HDL Directly from HDLRuby</strong></p>
<p>Instead of manually converting a Verilog file, you can load it from a HDLRuby description using the <code>require_verilog</code> command.</p>
<p>Assuming <code>adder.v</code> contains the following Verilog code:</p>
<pre><code class="language-verilog">module adder(x,y,z);
  input[7:0] x,y;
  output[7:0] z;
  
  assign z = x + y;
endmodule
</code></pre>
<p>You can load and instantiate this module in HDLRuby just like any other system:</p>
<pre><code class="language-ruby">require_verilog &quot;adder.v&quot;

system :my_IC do
   [8].inner :a, :b, :c

   adder(:my_adder).(a,b,c)

   ...
end
</code></pre>
<p><strong>Notes</strong>:</p>
<ul>
<li><p>Verilog HDL allows signal and module names to start with uppercase letters. In HDLRuby, however, identifiers starting with a capital letter are reserved for constants. To avoid naming conflicts, Verilog names beginning with a capital letter are prefixed with an underscore (<code>_</code>) when imported into HDLRuby.</p>
<p>For example, if the Verilog module were named <code>ADDER</code>, it would be imported as <code>_ADDER</code> in HDLRuby, and instantiated like this:</p>
<pre><code class="language-ruby">_ADDER(:my_add).(a,b,c)
</code></pre>
</li>
<li><p>In the current version of HDLRuby, Verilog HDL files are converted to HDLRuby using the v2hdr tool before being loaded with <code>require_verilog</code>.</p>
</li>
</ul>
<h1>Contributing</h1>
<p>Bug reports and pull requests are welcome on GitHub at https://github.com/civol/HDLRuby.</p>
<h1>To do</h1>
<ul>
<li>Find and fix the (maybe) terrifying number of bugs.</li>
</ul>
<h1>License</h1>
<p>The gem is available as open-source under the terms of the <a href="http://opensource.org/licenses/MIT">MIT License</a>.</p>