fpga_interchange: minor fixes and comments addition

Signed-off-by: Alessandro Comodi <acomodi@antmicro.com>

3 files changed, 57 insertions, 22 deletions

diff --git a/fpga_interchange/examples/chipdb.cmake b/fpga_interchange/examples/chipdb.cmake
index aa81bbe8..e0cf2c13 100644
--- a/fpga_interchange/examples/chipdb.cmake
+++ b/fpga_interchange/examples/chipdb.cmake
@@ -12,6 +12,12 @@ function(create_rapidwright_device_db)
     # If output_target is specified, the output_target_name variable
     # is set to the generated output_device_file target.
     #
+    # Arguments:
+    #   - device: common device name of a set of parts. E.g. xc7a35tcsg324-1 and xc7a35tcpg236-1
+    #             share the same xc7a35t device prefix
+    #   - part: one among the parts available for a given device
+    #   - output_target: variable name that will hold the output device target for the parent scope
+    #
     # Targets generated:
     #   - rapidwright-<device>-device
 
@@ -68,6 +74,16 @@ function(create_patched_device_db)
     # If output_target is specified, the variable named as the output_target
     # parameter value is set to the generated output_device_file target.
     #
+    # Arguments:
+    #   - device: common device name of a set of parts. E.g. xc7a35tcsg324-1 and xc7a35tcpg236-1
+    #             share the same xc7a35t device prefix.
+    #   - patch_name: name of the patch which determines the target name
+    #   - patch_path: patch_path argument for the fpga_interchange.patch call
+    #   - patch_format: patch_format argument for the fpga_interchange.patch call
+    #   - patch_data: path to the patch_data required for the fpga_interchange.patch call
+    #   - input_device: target for the device that needs to be patched
+    #   - output_target: variable name that will hold the output device target for the parent scope
+    #
     # Targets generated:
     #   - <patch_name>-<device>-device
 
@@ -132,7 +148,11 @@ function(generate_xc7_device_db)
     #   - constraints patch
     #   - luts patch
     #
-    # The final device target is output in the device_target variable to use in the parent scope
+    # Arguments:
+    #   - device: common device name of a set of parts. E.g. xc7a35tcsg324-1 and xc7a35tcpg236-1
+    #             share the same xc7a35t device prefix
+    #   - part: one among the parts available for a given device
+    #   - device_target: variable name that will hold the output device target for the parent scope
 
     set(options)
     set(oneValueArgs device part device_target)
@@ -191,7 +211,7 @@ function(generate_chipdb)
     #    part <part>
     #    device_target <device target>
     #    bel_bucket_seeds <bel bucket seeds>
-    #    package <package>
+    #    test_package <test_package>
     # )
     # ~~~
     #
@@ -202,6 +222,16 @@ function(generate_chipdb)
     #
     # The package argument is only used to run the architecture check target.
     #
+    # Arguments:
+    #   - family: nextpnr architecture family (e.g. fpga_interchange)
+    #   - device: common device name of a set of parts. E.g. xc7a35tcsg324-1 and xc7a35tcpg236-1
+    #             share the same xc7a35t device prefix
+    #   - part: one among the parts available for a given device
+    #   - device_target: target for the device from which the chipdb is generated
+    #   - bel_bucket_seeds: path to the bel bucket seeds YAML file
+    #   - test_package: package among the ones available for the device. This is used for architecture
+    #                   testing only
+    #
     # Targets generated:
     #   - chipdb-${device}-bba
     #   - chipdb-${device}-bin
@@ -211,7 +241,7 @@ function(generate_chipdb)
     # as the binary chipdb
 
     set(options)
-    set(oneValueArgs family device part device_target bel_bucket_seeds package)
+    set(oneValueArgs family device part device_target bel_bucket_seeds test_package)
     set(multiValueArgs)
 
     cmake_parse_arguments(
@@ -227,7 +257,7 @@ function(generate_chipdb)
     set(part ${generate_chipdb_part})
     set(device_target ${generate_chipdb_device_target})
     set(bel_bucket_seeds ${generate_chipdb_bel_bucket_seeds})
-    set(package ${generate_chipdb_package})
+    set(test_package ${generate_chipdb_test_package})
 
     get_target_property(device_loc ${device_target} LOCATION)
     set(chipdb_bba ${CMAKE_CURRENT_BINARY_DIR}/chipdb.bba)
@@ -272,24 +302,12 @@ function(generate_chipdb)
     )
 
     # Generate architecture check target
-    set(test_data_source ${CMAKE_CURRENT_SOURCE_DIR}/test_data.yaml)
-    set(test_data_binary ${CMAKE_CURRENT_BINARY_DIR}/test_data.yaml)
-    add_custom_command(
-        OUTPUT ${test_data_binary}
-        COMMAND
-            ${CMAKE_COMMAND} -E create_symlink
-            ${test_data_source}
-            ${test_data_binary}
-        DEPENDS
-            ${test_data_source}
-    )
-
     add_custom_target(
         chipdb-${device}-bin-check
         COMMAND
             nextpnr-fpga_interchange
                 --chipdb ${chipdb_bin}
-                --package ${package}
+                --package ${test_package}
                 --test
         DEPENDS
             ${chipdb_bin}
@@ -301,12 +319,14 @@ function(generate_chipdb)
         COMMAND
             nextpnr-fpga_interchange
                 --chipdb ${chipdb_bin}
-                --package ${package}
+                --package ${test_package}
                 --run ${PROJECT_SOURCE_DIR}/python/check_arch_api.py
         DEPENDS
             ${chipdb_bin}
             chipdb-${device}-bin
             ${test_data_binary}
+        WORKING_DIRECTORY
+            ${CMAKE_CURRENT_SOURCE_DIR}
     )
 
 add_dependencies(all-${family}-archcheck-tests chipdb-${device}-bin-check-test-data chipdb-${device}-bin-check)
diff --git a/fpga_interchange/examples/devices/xc7a35t/CMakeLists.txt b/fpga_interchange/examples/devices/xc7a35t/CMakeLists.txt
index 465ff66d..ce5d5d2d 100644
--- a/fpga_interchange/examples/devices/xc7a35t/CMakeLists.txt
+++ b/fpga_interchange/examples/devices/xc7a35t/CMakeLists.txt
@@ -1,14 +1,14 @@
 generate_xc7_device_db(
     device xc7a35t
     part xc7a35tcsg324-1
-    device_target target
+    device_target xc7a35t_target
 )
 
 generate_chipdb(
     family ${family}
     device xc7a35t
     part xc7a35tcsg324-1
-    device_target ${target}
+    device_target ${xc7a35t_target}
     bel_bucket_seeds ${PYTHON_INTERCHANGE_PATH}/test_data/series7_bel_buckets.yaml
-    package csg324
+    test_package csg324
 )
diff --git a/fpga_interchange/examples/tests.cmake b/fpga_interchange/examples/tests.cmake
index 194a3f21..7598d25c 100644
--- a/fpga_interchange/examples/tests.cmake
+++ b/fpga_interchange/examples/tests.cmake
@@ -7,13 +7,27 @@ function(add_interchange_test)
     #    package <package>
     #    tcl <tcl>
     #    xdc <xdc>
-    #    top <top name>
     #    sources <sources list>
+    #    [top <top name>]
     #    [techmap <techmap file>]
     # )
     #
     # Generates targets to run desired tests
     #
+    # Arguments:
+    #   - name: test name. This must be unique and no other tests with the same
+    #           name should exist
+    #   - family: nextpnr architecture family (e.g. fpga_interchange)
+    #   - device: common device name of a set of parts. E.g. xc7a35tcsg324-1 and xc7a35tcpg236-1
+    #             share the same xc7a35t device prefix
+    #   - package: package among the ones available for the device
+    #   - tcl: tcl script used for synthesis
+    #   - xdc: constraints file used in the physical netlist generation step
+    #   - sources: list of HDL sources
+    #   - top (optional): name of the top level module.
+    #                     If not provided, "top" is assigned as top level module
+    #   - techmap (optional): techmap file used during synthesis
+    #
     # Targets generated:
     #   - test-fpga_interchange-<name>-json     : synthesis output
     #   - test-fpga_interchange-<name>-netlist  : interchange logical netlist
@@ -121,6 +135,7 @@ function(add_interchange_test)
                 --package ${package}
         DEPENDS
             ${netlist}
+            ${xdc}
             ${chipdb_bin_target}
             ${chipdb_bin_loc}
     )