HDLRuby 3.3.4 → 3.5.0

data/tuto/tutorial_sw.md

@@ -10,7 +10,7 @@ In this tutorial, you will learn the basics about the description of digital cir
 
  4. [How to add parallelism to your algorithms.](#4-how-to-add-parallelism-to-your-algorithms)
 
-Then, the following section will introduce advanced concepts about hardware design and HDLruby:
+Then, the following section will introduce advanced concepts about hardware design and HDLRuby:
 
  5. [Toward lower level hardware design: the processes.](#5-toward-lower-level-hardware-design-the-processes)
 
@@ -20,6 +20,8 @@ Then, the following section will introduce advanced concepts about hardware desi
 
  8. [How to interact with the simulator.](#8-how-to-interact-with-the-simulator)
 
+ 9. [What about using Verilog HDL instead?](#9-what-about-using-Verilog-hdl-instead)
+
 Within these topics, you will also have an explanation of how the following high-level concepts can be used in HDLRuby:
 
  * Object-oriented programming
@@ -46,7 +48,7 @@ To use HDLRuby the following software is required:
 
 The following software is also recommended:
 
- * A wave viewer supporting *vcd* files (e.g., [GTKWave](https://gtkwave.sourceforge.net/).)
+ * A wave viewer supporting *vcd* files (e.g., [GTKWave](https://gtkwave.sourceforge.net/), or, [HTMLWave](https://civol.github.io/htmlwave/htmlwave.html))
 
 ## 1. What is HDLRuby and how to use its framework
 
@@ -129,10 +131,10 @@ Up to now, we said that HDLRuby is a language, it is in truth a complete framewo
 Basically, `hdrcc` is used as follows:
 
 ```bash
-hdrcc <options> <input file> <output directory>
+hdrcc <options> <input file> <output/working directory>
 ```
 
-Where `options` specifies the action to be performed, `input file` specifies the input HDLRuby file, and `output directory` specifies the directory where the command results will be saved. As a general rule, when an input file is specified, an output directory must also be specified.
+Where `options` specifies the action to be performed, `input file` specifies the input HDLRuby file, and `output/working directory` specifies the directory where the command results will be saved. As a general rule, when an input file is specified, an output directory must also be specified.
 
 Several actions are possible using `hdrcc`, the main ones being the following:
 
@@ -142,6 +144,11 @@ Several actions are possible using `hdrcc`, the main ones being the following:
  hdrcc --sim <input file> <output directory>
  ```
 
+ * Generate a graphical representation of the RTL code in SVG format:
+
+ ```bash
+ hdrcc --svg <input file> <output directory>
+
  * Generate the equivalent Verilog HDL code:  
 
  ```bash
@@ -156,6 +163,28 @@ __Note__: VHDL generation is also possible using the following command.
  hdrcc --vhdl <input file> <output directory>
  ```
 
+While being able to convert HDLRuby to Verilog HDL may usually be enough to design a cricuits, it may also sometimes be useful to be able to do the reverse: converting a Verilog HDL file to HDLRuby.
+To do this, you can use the following command:
+
+```bash
+v2hdr <input Verilog HDL file> <output HDLRuby file>
+```
+
+For example, assuming that you have a Verilog ddHDL named 'adder.v' describing and adder circuit, you can convert it to HDLRuby as follows:
+
+```bash
+v2hdr adder.v adder.rb
+```
+
+It is also possible to directly use a Verilog file as input to 'hdrcc', but its top module must be specified. For example, to directly simulate the previous 'adder.v', and assuming its top module is 'adder' you can do as follows:
+
+```bash
+hdrcc --sim -t adder adder.v adder
+```
+
+__Note__: for the command above, it is assumed that 'adder.v' contains a simulation benchmark.
+
+
 And that's it! For details about all the actions that can be performed, how to write an input file, and what kind of output can be produced, let us see the remaining of the tutorial.
 
 
@@ -3776,7 +3805,62 @@ A more complete example can be found among the HDLRuby samples: `with_board.rb`,
 </p>
 
 
-## 9. What next?
+## 9. What about using Verilog HDL instead?
+
+I won’t claim how good HDLRuby is, but it’s clear that Verilog HDL (/ SystemVerilog) and VHDL are currently the leading languages in hardware design, and it would be unrealistic to expect this to change anytime soon. This means that for HDLRuby to offer any real benefit, the framework must be able to support one or both of these languages in some way. This is no easy task, but as a starting point, we now provide a tool for converting Verilog HDL files into HDLRuby files.
+For that please use the following command:
+
+```bash
+v2hdr <input Verilog HDL file> <output HDLRuby file>
+```
+
+For example, assuming that you have a Verilog ddHDL named 'adder.v' describing and adder circuit, you can convert it to HDLRuby as follows:
+
+```bash
+v2hdr adder.v adder.v.rb
+```
+
+
+Another possibility is to directly load the Verilog HDL file from a HDLRuby description using the command `require_verilog`.
+For example, assuming `adder.v` contains the following code:
+
+```verilog
+module adder(x,y,z);
+  input[7:0] x,y;
+  output[7:0] z;
+  
+  assign z = x + y;
+endmodule
+```
+
+It can be loaded the be instantiated like any other module in HDLRuby as follows:
+
+```ruby
+require_verilog "adder.v"
+
+system :my_IC do
+   [8].inner :a, :b, :c
+
+   adder(:my_adder).(a,b,c)
+
+   ...
+end
+```
+
+
+__Notes__:
+
+* Verilog HDL accepts signal and module names in any letter case, while HDLRuby reserves identifiers starting with a capital letter for constants. To avoid conflicts, Verilog HDL names that begin with a capital letter are prefixed with an underscore (`_`) in HDLRuby. For example, if the Verilog HDL module name in the previous example were `ADDER`, it would be renamed to `_ADDER` in HDLRuby. Instantiating such a module would be done as follows:
+
+  ```ruby
+  _ADDER(:my_add).(a,b,c)
+  ```
+
+* With the current version of HDLRuby, the Verilog HDL files are first converted to HDLRuby before being loaded using the standalone `v2hdr` tool.
+
+
+
+## 10. What next?
 
 There are still many aspects of HDLRuby that have not been addressed in this tutorial. For example, finite state machines (FSM) and decoders are crucial hardware components that you should learn about, and HDLRuby provides specific constructs for easier design. So from now on, please consult the main documentation of HDLRuby, and have a look at the code samples provided in the HDLRuby distribution. They can be copied to your working directory using the following command:
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: HDLRuby
 version: !ruby/object:Gem::Version
-  version: 3.3.4
+  version: 3.5.0
 platform: ruby
 authors:
 - Lovic Gauthier
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-11 00:00:00.000000000 Z
+date: 2024-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -60,6 +59,7 @@ email:
 - lovic@ariake-nct.ac.jp
 executables:
 - hdrcc
+- v2hdr
 extensions:
 - ext/hruby_sim/extconf.rb
 extra_rdoc_files:
@@ -77,6 +77,7 @@ files:
 - bin/console
 - bin/setup
 - exe/hdrcc
+- exe/v2hdr
 - ext/hruby_sim/Makefile_csim
 - ext/hruby_sim/extconf.rb
 - ext/hruby_sim/hruby_rcsim_build.c
@@ -102,6 +103,7 @@ files:
 - lib/HDLRuby/hdr_samples/WithMultiChannelExpVerilog/with_multi_channels_qu_222.v
 - lib/HDLRuby/hdr_samples/WithMultiChannelExpVerilog/with_multi_channels_rg_23.v
 - lib/HDLRuby/hdr_samples/adder.rb
+- lib/HDLRuby/hdr_samples/adder8.v
 - lib/HDLRuby/hdr_samples/adder_assign_error.rb
 - lib/HDLRuby/hdr_samples/adder_bench.rb
 - lib/HDLRuby/hdr_samples/adder_gen.rb
@@ -128,6 +130,7 @@ files:
 - lib/HDLRuby/hdr_samples/dff_properties.rb
 - lib/HDLRuby/hdr_samples/dff_unit.rb
 - lib/HDLRuby/hdr_samples/enum_as_param.rb
+- lib/HDLRuby/hdr_samples/hard_to_route.rb
 - lib/HDLRuby/hdr_samples/huge_rom.rb
 - lib/HDLRuby/hdr_samples/if_bench.rb
 - lib/HDLRuby/hdr_samples/include.rb
@@ -185,6 +188,7 @@ files:
 - lib/HDLRuby/hdr_samples/system_open.rb
 - lib/HDLRuby/hdr_samples/tuple.rb
 - lib/HDLRuby/hdr_samples/type_minmax_bench.rb
+- lib/HDLRuby/hdr_samples/verilog_parser_bench.rb
 - lib/HDLRuby/hdr_samples/with_board.rb
 - lib/HDLRuby/hdr_samples/with_board_sequencer.rb
 - lib/HDLRuby/hdr_samples/with_bram.rb
@@ -206,6 +210,7 @@ files:
 - lib/HDLRuby/hdr_samples/with_fixpoint_adv.rb
 - lib/HDLRuby/hdr_samples/with_fsm.rb
 - lib/HDLRuby/hdr_samples/with_function_generator.rb
+- lib/HDLRuby/hdr_samples/with_generic_in_generic.rb
 - lib/HDLRuby/hdr_samples/with_handshake.rb
 - lib/HDLRuby/hdr_samples/with_init.rb
 - lib/HDLRuby/hdr_samples/with_instance.rb
@@ -227,6 +232,9 @@ files:
 - lib/HDLRuby/hdr_samples/with_reduce.rb
 - lib/HDLRuby/hdr_samples/with_ref_array.rb
 - lib/HDLRuby/hdr_samples/with_ref_expr.rb
+- lib/HDLRuby/hdr_samples/with_seq_case.rb
+- lib/HDLRuby/hdr_samples/with_seq_if.rb
+- lib/HDLRuby/hdr_samples/with_seq_if_succ.rb
 - lib/HDLRuby/hdr_samples/with_sequencer.rb
 - lib/HDLRuby/hdr_samples/with_sequencer_channel.rb
 - lib/HDLRuby/hdr_samples/with_sequencer_deep.rb
@@ -240,6 +248,7 @@ files:
 - lib/HDLRuby/hdr_samples/with_to_a.rb
 - lib/HDLRuby/hdr_samples/with_to_array.rb
 - lib/HDLRuby/hdr_samples/with_values.rb
+- lib/HDLRuby/hdr_samples/with_verilog.rb
 - lib/HDLRuby/hdrcc.rb
 - lib/HDLRuby/hdrlib.rb
 - lib/HDLRuby/high_samples/_adder_fault.rb
@@ -343,6 +352,7 @@ files:
 - lib/HDLRuby/hruby_values.rb
 - lib/HDLRuby/hruby_verilog.rb
 - lib/HDLRuby/hruby_verilog_name.rb
+- lib/HDLRuby/hruby_viz.rb
 - lib/HDLRuby/low_samples/adder.yaml
 - lib/HDLRuby/low_samples/after.yaml
 - lib/HDLRuby/low_samples/before.yaml
@@ -415,10 +425,13 @@ files:
 - lib/HDLRuby/test_hruby_high_low.rb
 - lib/HDLRuby/test_hruby_low.rb
 - lib/HDLRuby/ui/hruby_board.rb
+- lib/HDLRuby/v2hdr.rb
 - lib/HDLRuby/v_samples/adder.v
 - lib/HDLRuby/v_samples/dff.v
 - lib/HDLRuby/v_samples/ram.v
 - lib/HDLRuby/v_samples/rom.v
+- lib/HDLRuby/verilog_hruby.rb
+- lib/HDLRuby/verilog_parser.rb
 - lib/HDLRuby/version.rb
 - lib/c/Rakefile
 - lib/c/cHDL.h
@@ -460,7 +473,6 @@ homepage: https://github.com/civol/HDLRuby
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -476,8 +488,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.0
 specification_version: 4
 summary: HDLRuby is a library for describing and simulating digital electronic systems.
 test_files: []