[Yosyslib]: add README to the yosyslib directory

Signed-off-by: Seyed Alireza Damghani <[email protected]>

Author: sdamghan

vtr_flow/misc/yosyslib/README.md

@@ -0,0 +1,34 @@
+# Yosys+VTR library files
+This directory includes required Verilog models to run the VTR flow using Yosys as its front-end.
+The approach of utilizing Yosys as the VTR synthesizer is mainly driven by what Eddie Hung proposed
+for the [`VTR-to-Bitstream`](http://eddiehung.github.io/vtb.html) (VTB), based upon VTR 7. Although 
+some files, such as [`yosys_models.v`](./yosys_models.v) and [`multiply.v`](./multiply.v), are directly
+copied from the VTB project, the other files have been subjected to a few changes due to significant 
+alterations from VTR 7 to the current version of VTR. Furthermore, Hung's approach was specifically 
+proposed for Xilinx Vertix-6 architecture. As a result, we have applied relevant changes to the remainder
+of Yosys library files to make them compatible with the current VTR version and support routine architectures
+used in the VTR regression tests.
+
+## What is new compared to the VTB files?
+Changes applied to the VTB files are outlined as follows:
+ 1. Replacing Vertix-6 adder black-box (`xadder`) with the conventional adder used in the current version of VTR.
+ 2. If required, performing a recursive depth splitting for memory hard blocks, i.e., `single_port_ram` and `dual_port_ram`, to make them adaptable with the VTR flow configurations.
+ 3. Converting asynchronous DFFs with enable signals (ADFFE) to synchronous form using [`adffe2dffe.v`](./../../../ODIN_II/techlib/adffe2dff.v).
+ 4. Adding `dffunmap` to transform complex DFF sub-circuits, such as SDFFE (DFF with synchronous reset and enable), to their soft logic implementation, i.e., the combination of multiplexers and latches.
+ 5. Removing the ABC commands from the Yosys synthesis script and letting the VTR flow's ABC stage performs the technology mapping. (NOTE: the LUT size is considered the one defined in the architecture file as the same as the regular VTR flow)
+
+## How to add new changes?
+The Yosys synthesis commands, including the generic synthesis and additional VTR specific configurations, are provided
+in [`synthesis.ys`](./synthesis.ys). To make changes in the overall Yosys synthesis flow, the [`synthesis.ys`](./synthesis.ys)
+script is perhaps the first file developers may require to change.
+
+Moreover, the [`yosys_models.v`](./yosys_models.v) file includes the required definitions for Yosys to how it should infer implicit
+memories and instantiate arithmetic operations, such as addition, subtraction, and multiplication. Therefore, to alter these 
+behaviours or add more regulations such as how Yosys should behave when facing other arithmetic operations, for example modulo and division,
+the [`yosys_models.v`](./yosys_models.v) Verilog file is required to be modified.
+
+Except for [`single_port_ram.v`](./single_port_ram.v) and [`dual_port_ram.v`](./dual_port_ram.v) Verilog files that perform the depth splitting
+process, the other files are defined as black-box, i.e., their declarations are required while no definition is needed. To add new black-box
+components, developers should first provide the corresponding Verilog files similar to the [`adder.v`](./adder.v). Then, a new  `read_verilog -lib TTT/NEW_BB.v`
+command should be added to the Yosys synthesis script. If there is an implicit inference of the new black-box component, the [`yosys_models.v`](./yosys_models.v)
+Verilog file must also be modified, as mentioned earlier.

vtr_flow/misc/yosyslib/adder.v

@@ -1,3 +1,9 @@
+/********************************************************
+# Description: definition of the hard adder black-box	#
+#														#
+# Author: Seyed Alireza Damghani ([email protected])  #
+********************************************************/
+
 (* blackbox *)
 module adder(a, b, cin, cout, sumout);
 	input a, b, cin;

vtr_flow/misc/yosyslib/dpram_rename.v

@@ -1,3 +1,13 @@
+/******************************************************************
+# Description: Renaming depth-split dualPortRam to dual_port_ram  #
+#			   to be recognized by VTR flow CAD tools. This file  #
+#			   is executed by the Yosys synthesis flow once the   #
+#			   dual_port_ram.v is executed.		  	  			  #
+#																  #
+# Author: Seyed Alireza Damghani ([email protected])   		  #
+******************************************************************/
+
+
 `timescale 1ps/1ps
 
 `define MEM_MAXADDR PPP

vtr_flow/misc/yosyslib/dual_port_ram.v

@@ -1,3 +1,10 @@
+/****************************************************************
+# Description: Performing a recursive depth splitting for 		#
+#			   dual_port_ram memory hard blocks					#
+#																#
+# Author: Seyed Alireza Damghani ([email protected])   		#
+****************************************************************/
+
 `timescale 1ps/1ps
 
 `define MEM_MAXADDR PPP

vtr_flow/misc/yosyslib/multiply.v

@@ -1,3 +1,10 @@
+/****************************************************************
+# Description: definition of the hard multiplier black-box		#
+#																#
+# Author: Eddie Hung											#
+# VTR-to-Bitstream: "http://eddiehung.github.io/vtb.html"	#
+****************************************************************/
+
 (* blackbox *)
 module multiply(a, b, out);
 	parameter A_WIDTH = 36;

vtr_flow/misc/yosyslib/single_port_ram.v

@@ -1,3 +1,10 @@
+/****************************************************************
+# Description: Performing a recursive depth splitting for 		#
+#			   single_port_ram memory hard blocks				#
+#																#
+# Author: Seyed Alireza Damghani ([email protected])   		#
+****************************************************************/
+
 `timescale 1ps/1ps
 
 `define MEM_MAXADDR PPP

vtr_flow/misc/yosyslib/spram_rename.v

@@ -1,3 +1,12 @@
+/*********************************************************************
+# Description: Renaming depth-split singlePortRam to single_port_ram #
+#			   to be recognized by VTR flow CAD tools. This file  	 #
+#			   is executed by the Yosys synthesis flow once the      #
+#			   single_port_ram.v is executed.		  	  			 #
+#																  	 #
+# Author: Seyed Alireza Damghani ([email protected])   		 	 #
+*********************************************************************/
+
 `timescale 1ps/1ps
 
 `define MEM_MAXADDR PPP

vtr_flow/misc/synthesis.ys renamed to vtr_flow/misc/yosyslib/synthesis.ys

@@ -9,6 +9,9 @@
 # it adaptable with the current VTR flow have been made.		#
 #																#
 # [1] http://eddiehung.github.io/vtb.html						#
+#																#
+# Author: Eddie Hung											#
+# Co-author: Seyed Alireza Damghani	([email protected])  		#
 #################################################################
 
 # XXX (input circuit) is replaced with filename by the run_vtr_flow script

vtr_flow/misc/yosyslib/yosys_models.v

@@ -1,3 +1,18 @@
+/********************************************************************************************
+# Description: this file includes the required definitions for Yosys to how it should		#
+#			   infer implicit memories and instantiate arithmetic operations, such as 		#
+#			   addition, subtraction, and multiplication. In this file, implicit memory 	#
+#			   boundary and required splitting process, arithmetic operation depth/width    # 
+#			   splitting, and error handling for possible invalid situations are specified.	#
+# 																							#
+# NOTE: PPP, AAA, and MMM will be replaced with the configuration specifications via the 	#
+#		run_vtr_flow.py script file while the VTR flow is executing.						#
+# 																							#
+# Author: Eddie Hung																		#
+# VTR-to-Bitstream: "http://eddiehung.github.io/vtb.html"								#
+********************************************************************************************/
+
+
 `define MEM_MINWIDTH 1
 `define MEM_MAXADDR PPP
 `define MEM_MAXDATA 36

vtr_flow/scripts/python_libs/vtr/paths.py

@@ -18,8 +18,8 @@
 
 # YOSYS paths
 yosys_exe_path = root_path / "libs" / "EXTERNAL" / "libyosys" / "yosys"
-yosys_script_path = vtr_flow_path / "misc" / "synthesis.ys"
 yosys_lib_path = vtr_flow_path / "misc" / "yosyslib"
+yosys_script_path = yosys_lib_path / "synthesis.ys"
 
 # ABC paths
 abc_path = root_path / "abc"