Merge branch 'master' into Seb_DrawDocumentation

Author: SebastianLievano

.gitignore

@@ -105,6 +105,11 @@ ODIN_II/usefull_tools/**/track_completed
 #
 Yosys
 
+#
+#ArchFPGA exec dir
+#
+ArchFPGA
+
 #
 #Python
 #

README.md

@@ -13,7 +13,7 @@ It then performs:
 to generate FPGA speed and area results.
 VTR includes a set of benchmark designs known to work with the design flow.
 
-VTR can also produce [FASM](https://symbiflow.readthedocs.io/en/latest/fasm/docs/specification.html) to program some commercial FPGAs (via [Symbiflow](https://symbiflow.github.io/))
+VTR can also produce [FASM](https://fasm.readthedocs.io/en/latest/) to program some commercial FPGAs (via [Symbiflow](https://chipsalliance.org/announcement/2022/02/18/chips-alliance-forms-f4pga-workgroup-to-accelerate-adoption-of-open-source-fpga-tooling/))
 
 | Placement (carry-chains highlighted) | Critical Path |
 | ------------------------------------ | ------------- |

doc/src/vpr/command_line_usage.rst

@@ -283,6 +283,12 @@ General Options
     .. warning:: Exercise extreme caution when turning this option off -- be sure you completely understand why the issue is being flagged, and why it is OK to treat as a warning instead of an error.
 
     **Default:** ``on``
+    
+.. option:: --terminate_if_timing_fails {on, off}
+
+    Controls whether VPR should terminate if timing is not met after routing. 
+    
+    **Default:** ``off``
 
 .. _filename_options:
 

doc/src/yosys+odin/dev_guide/contributing.rst

@@ -156,6 +156,10 @@ If no architecture is passed in, Odin-II will create the soft logic and use LUTs
 However, if an architecture is passed, Odin-II will map accordingly to the available hard blocks and LUTs.
 It uses a combination of soft logic and hard logic.
 
+.. note::
+
+	Please visit the Yosys's `Developers Guide <https://docs.verilogtorouting.org/en/latest/yosys/dev_guide/#working-with-complex-blocks-and-how-to-instantiate-them?>`_ for more information about how Yosys deals with the complex blocks defined in the VTR architecture file.
+
 With the integration of Yosys+Odin-II, the Odin-II partial mapping features such as hard/soft logic trade-offs become available for a Yosys elaborated circuit.
 For instance, using optimization command arguments, a user can force the partial mapper to infer at least a user-defined percentage of multipliers in soft logic.
 

doc/src/yosys/dev_guide.rst

@@ -28,8 +28,8 @@ Changes applied to the VTB files are outlined as follows:
 	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?
------------------------
+Working with Complex Blocks and How to Instantiate them?
+-------------------------------------------------------
 
 The Yosys synthesis commands, including the generic synthesis and additional VTR specific configurations, are provided
 in `synthesis.tcl <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/synthesis.tcl>`_. To make changes in the overall Yosys synthesis flow, the `synthesis.tcl <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/synthesis.tcl>`_
@@ -42,10 +42,31 @@ the `yosys_models.v <https://github.com/verilog-to-routing/vtr-verilog-to-routin
 
 Except for `single_port_ram.v <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/single_port_ram.v>`_ and `dual_port_ram.v <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/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 <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/adder.v>`_. Then, a new  `read_verilog -lib TTT/NEW_BB.v`
+components manually, developers should first provide the corresponding Verilog files similar to the `adder.v <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/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 <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/misc/yosyslib/yosys_models.v>`_
 Verilog file must also be modified, as mentioned earlier.
 
+It is worth noting that the VTR flow scripts for running Yosys standalone as the VTR frontend are designed to automatically provide the black box declaration of complex blocks defined in the architecture XML file for Yosys.
+Technically, by running the ``run_vtr_flow.py`` script with the Yosys frontend, the ``write_arch_bb`` routine, defined in the ``libarchfpga``, is executed initially to extract the information of complex blocks defined in the architecture file.
+Then, the routine generates a file, including the black box declaration of the complex blocks in the Verilog format.
+The output file is named ``arch_dsps.v`` by default, found in the project destination directory.
+
+Instantiation of complex blocks is similar to the explicit instantiation of VTR primitives in HDL format.
+The ``write_arch_bb`` generates a Verilog module with the same name as the complex block model.
+Module ports are also defined according to the port declaration provided in the architecture file.
+For instance, the HDL instantiation of the ``multiply_fp_clk`` complex block defined in the ``COFFE_22nm/k6FracN10LB_mem20K_complexDSP_customSB_22nm.xml`` architecture file is as follows:
+
+.. code-block:: verilog
+	...
+	multiply_fp_clk instance_name(
+		.b(i_b),		// input	[31:0]	b
+		.a(i_a), 		// input	[31:0]	a
+		.clk(i_clk), 	// input	[0:0]	clk
+		.out(i_out)		// output	[31:0]	out
+	);
+	...
+
+**Algorithm 1** - Custom Complex Blocks HDL Instantiation
 
 Yosys Synthesis Script File
 ---------------------------
@@ -135,4 +156,4 @@ Yosys Synthesis Script File
 	# ZZZ will be replaced by run_vtr_flow.pl
 	write_blif -true + vcc -false + gnd -undef + unconn -blackbox ZZZ
 
-**Algorithm 1** - The Yosys Tcl Script File
+**Algorithm 2** - The Yosys Tcl Script File

libs/EXTERNAL/libyosys/CMakeLists.txt

@@ -39,7 +39,10 @@ add_custom_target(yosys ALL DEPENDS ${LIB_FILE} ${BINARY_LIB_FILE})
 
 # create an library target out of the library compilation result
 add_library(libyosys SHARED IMPORTED GLOBAL)
-add_dependencies(libyosys yosys)
+
+# adding dependency to libarchfpga, as it is required
+# by VTR scripts for Yosys standalone frontend
+add_dependencies(libyosys yosys libarchfpga)
 
 # specify where the library is and where to find the headers
 set_target_properties(libyosys

libs/libarchfpga/CMakeLists.txt

@@ -2,13 +2,14 @@ cmake_minimum_required(VERSION 3.9)
 
 project("libarchfpga")
 
-file(GLOB_RECURSE EXEC_SOURCES src/main.cpp)
+file(GLOB_RECURSE READ_ARCH_EXEC_SRC src/main.cpp)
+file(GLOB_RECURSE WRITE_ARCH_BB_EXEC_SRC src/write_arch_bb.cpp)
 file(GLOB_RECURSE LIB_SOURCES src/*.cpp)
 file(GLOB_RECURSE LIB_HEADERS src/*.h)
 files_to_dirs(LIB_HEADERS LIB_INCLUDE_DIRS)
 
 #Remove test executable from library
-list(REMOVE_ITEM LIB_SOURCES ${EXEC_SOURCES})
+list(REMOVE_ITEM LIB_SOURCES ${READ_ARCH_EXEC_SRC} ${WRITE_ARCH_BB_EXEC_SRC})
 
 #Create the library
 add_library(libarchfpga STATIC
@@ -31,16 +32,40 @@ target_link_libraries(libarchfpga
 target_compile_definitions(libarchfpga PUBLIC ${INTERCHANGE_SCHEMA_HEADERS})
 
 #Create the test executable
-add_executable(read_arch ${EXEC_SOURCES})
+add_executable(read_arch ${READ_ARCH_EXEC_SRC})
+add_executable(write_arch_bb ${WRITE_ARCH_BB_EXEC_SRC})
 target_link_libraries(read_arch libarchfpga)
+target_link_libraries(write_arch_bb libarchfpga)
 
 #Supress IPO link warnings if IPO is enabled
 get_target_property(READ_ARCH_USES_IPO read_arch INTERPROCEDURAL_OPTIMIZATION)
+get_target_property(WRITE_ARCH_BB_USES_IPO write_arch_bb INTERPROCEDURAL_OPTIMIZATION)
 if (READ_ARCH_USES_IPO)
     set_property(TARGET read_arch APPEND PROPERTY LINK_FLAGS ${IPO_LINK_WARN_SUPRESS_FLAGS})
 endif()
+if (WRITE_ARCH_BB_USES_IPO)
+    set_property(TARGET write_arch_bb APPEND PROPERTY LINK_FLAGS ${IPO_LINK_WARN_SUPRESS_FLAGS})
+endif()
+
+install(TARGETS libarchfpga read_arch write_arch_bb DESTINATION bin)
 
-install(TARGETS libarchfpga read_arch DESTINATION bin)
+#
+# install executables in the VTR source root directory
+# to utilize them for scripts running VTR flow
+#
+set(ARCHFPGA_DIR ${VTR_SOURCE_DIR}/ArchFPGA)
+# making a new custom target out of libarchfpga to automatically perform
+# the house keeping for end users by deleting the ArchFPGA dir in the
+# VTR root dir if it exists and holds expired execs
+add_custom_target(archfpga-execs ALL 
+                    DEPENDS read_arch write_arch_bb
+                    COMMAND ${CMAKE_COMMAND} -E 
+                                            remove_directory ${ARCHFPGA_DIR}                     
+                    COMMAND ${CMAKE_COMMAND} -E 
+                                            make_directory ${ARCHFPGA_DIR}
+                    COMMAND ${CMAKE_COMMAND} -E 
+                                            copy_directory ${CMAKE_CURRENT_BINARY_DIR} ${ARCHFPGA_DIR}
+                    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
 
 # 
 # Unit Tests

libs/libarchfpga/src/main.cpp

@@ -12,14 +12,15 @@
 #include "vtr_error.h"
 #include "vtr_memory.h"
 
+#include "arch_util.h"
 #include "read_xml_arch_file.h"
 #include "echo_arch.h"
 
 void print_help();
 
 int main(int argc, char** argv) {
     try {
-        t_arch* arch = (t_arch*)vtr::calloc(1, sizeof(t_arch));
+        t_arch arch;
         std::vector<t_physical_tile_type> physical_tile_types;
         std::vector<t_logical_block_type> logical_block_types;
 
@@ -43,12 +44,17 @@ int main(int argc, char** argv) {
         printf("Reading in architecture\n");
 
         /* function declarations */
-        XmlReadArch(argv[1], atoi(argv[2]), arch, physical_tile_types, logical_block_types);
+        XmlReadArch(argv[1], atoi(argv[2]), &arch, physical_tile_types, logical_block_types);
 
         printf("Printing Results\n");
 
-        EchoArch(argv[3], physical_tile_types, logical_block_types, arch);
-        free(arch);
+        EchoArch(argv[3], physical_tile_types, logical_block_types, &arch);
+
+        // CLEAN UP
+        free_arch(&arch);
+        free_type_descriptors(physical_tile_types);
+        free_type_descriptors(logical_block_types);
+
     } catch (vtr::VtrError& vtr_error) {
         printf("Failed to process architecture %s: %s\n", argv[1], vtr_error.what());
         return 1;

libs/libarchfpga/src/write_arch_bb.cpp

@@ -0,0 +1,80 @@
+/**
+ * Reading an architecture and output the Verilog black box
+ * declaration of complex blocks in a file
+ *
+ * Date: July, 2022
+ * Author: Seyed Alireza Damghani
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <vector>
+
+#include "vtr_error.h"
+#include "vtr_memory.h"
+
+#include "arch_util.h"
+#include "read_xml_arch_file.h"
+#include "write_models_bb.h"
+
+void print_help();
+
+int main(int argc, char** argv) {
+    try {
+        t_arch arch;
+        std::vector<t_physical_tile_type> physical_tile_types;
+        std::vector<t_logical_block_type> logical_block_types;
+
+        if (argc - 1 != 2) {
+            printf("Error: Unexpected # of arguments.  Expected 2 found %d arguments\n",
+                   argc);
+            print_help();
+            return 1;
+        }
+
+        printf("-------------------------------------------------------------------------------------------------------\n");
+        printf("- Read architecture file and generate a Verilog file including the declaration of models as black boxes\n");
+        printf("-------------------------------------------------------------------------------------------------------\n\n");
+
+        printf(
+            "Inputs: \n"
+            "architecture %s\n"
+            "output file %s\n",
+            argv[1], argv[2]);
+        printf("Reading in architecture ...\n");
+
+        /* function declarations */
+        XmlReadArch(argv[1], false, &arch, physical_tile_types, logical_block_types);
+
+        printf("Printing Results ...\n");
+
+        WriteModels_bb(argv[1], argv[2], &arch);
+
+        // CLEAN UP
+        free_arch(&arch);
+        free_type_descriptors(physical_tile_types);
+        free_type_descriptors(logical_block_types);
+
+    } catch (vtr::VtrError& vtr_error) {
+        printf("Failed to process architecture %s: %s\n", argv[1], vtr_error.what());
+        return 1;
+    } catch (std::exception& error) {
+        printf("Failed to process architecture %s: %s\n", argv[1], error.what());
+        return 1;
+    }
+
+    printf("Done\n");
+
+    return 0;
+}
+
+void print_help() {
+    printf("\n-----------------------------------------------------------------------------------------------------------------------\n");
+    printf("write_arch_bb - Read a VPR architecture file and output a Verilog file including the declaration of models as black boxes\n");
+    printf("\n");
+    printf("Usage: write_arch_bb <arch_file.xml> <output_file>\n");
+    printf("\n");
+    printf("  ex: write_arch_bb k4_n10.xml dsp_bb.v\n");
+    printf("      Read timing-driven architecture k4_n10.xml and output the results to arch_data.out\n");
+    printf("\n-----------------------------------------------------------------------------------------------------------------------\n");
+}