063-gtp-common-conf: fix naming of GTREFCLK features

- Also adds a README for the fuzzer

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

fuzzers/063-gtp-common-conf/README.md

@@ -0,0 +1,33 @@
+GTPE2\_COMMON Primitive Configuration fuzzer
+============================================
+
+This fuzzer is used to document the parameters corresponding to the GTPE2\_COMMON primitive.
+
+It uses pre-built JSON containing a dictionary of parameters, each one with four attributes:
+
+- Type: one of Binary, Integer, String, Boolean.
+- Values: all possible values that this parameter can assume. In case of `BIN` types, the values list contains only the maximum value reachable.
+- Digits: number of digits (or bits) required to use a parameter.
+- Encoding: This is present only for `INT` types of parameters. These reflect the actual encoding of the parameter value in the bit array.
+
+E.g.:
+
+```json
+{
+    "PLL0_REFCLK_DIV": {
+        "type": "INT",
+        "values": [1, 2],
+        "encoding": [16, 0],
+        "digits": 5
+    }
+}
+```
+
+In addition, there exist wires and PIPs that allow the connections of the `GTREFCLK` ports to clocks coming from the device fabric instead of the `IBUFDS_GTE2` primitive.
+
+In fact, if the clock comes from the device fabric, the physical `GTGREFCLK[01]` port is used instead of the `GTREFCLK[01]` one (even though the design's primitive port is always `GTREFCLK`).
+
+In the [User Guide (pg 27)](https://www.xilinx.com/support/documentation/user_guides/ug482_7Series_GTP_Transceivers.pdf), it is stated that the `GTGREFCLK[01]` port is used for "internal testing purposes".
+Using this port is highly discouraged to get the reference clock from the fabric, as the recommended way is to get the clock from an external source using the `IBUFDS_GTE2` primitive.
+
+Therefore, in addition to the parameters, `IN_USE` and `ZINV\INV` features, this fuzzer documents also the `GTREFCLK[01]_USED` and `BOTH_GTREFCLK[01]_USED` features.

fuzzers/063-gtp-common-conf/generate.py

@@ -91,7 +91,8 @@ def main():
             for param in ["PLL0LOCKDETCLK", "PLL1LOCKDETCLK", "DRPCLK"]:
                 segmk.add_site_tag(site, "ZINV_" + param, 1 ^ params[param])
 
-            for param in ["GTREFCLK0", "GTREFCLK1", "BOTH_GTREFCLK_USED"]:
+            for param in ["GTREFCLK0_USED", "GTREFCLK1_USED",
+                          "BOTH_GTREFCLK_USED"]:
                 segmk.add_site_tag(site, param, params[param])
 
     for params in params_list:

fuzzers/063-gtp-common-conf/top.py

@@ -165,7 +165,8 @@ IBUFDS_GTE2 #(
 
             verilog_ports = ""
 
-            for param in ["GTREFCLK0", "GTREFCLK1", "BOTH_GTREFCLK_USED"]:
+            for param in ["GTREFCLK0_USED", "GTREFCLK1_USED",
+                          "BOTH_GTREFCLK_USED"]:
                 params[param] = 0
 
             if tile_name in ibufds_out_wires:
@@ -179,7 +180,7 @@ IBUFDS_GTE2 #(
             .GTREFCLK{}({}),""".format(location, wire)
 
                     gtrefclk_ports_used += 1
-                    params["GTREFCLK{}".format(location)] = 1
+                    params["GTREFCLK{}_USED".format(location)] = 1
 
                 if gtrefclk_ports_used == 2:
                     params["BOTH_GTREFCLK_USED"] = 1