diff --git a/docs/library/jesd204/index.rst b/docs/library/jesd204/index.rst index 08c40c43832..a0bb2c81745 100644 --- a/docs/library/jesd204/index.rst +++ b/docs/library/jesd204/index.rst @@ -10,6 +10,7 @@ JESD204 Interface Framework JESD204B/C Link Receive Peripheral ADC JESD204B/C Transport Peripheral DAC JESD204B/C Transport Peripheral + Xilinx FPGAs Transceivers Wizard The JESD204, JESD204A, JESD204B and the JESD204C data converter serial interface standard was created through the JEDEC committee to standardize and reduce the diff --git a/docs/library/jesd204/xgt_wizard/index.rst b/docs/library/jesd204/xgt_wizard/index.rst new file mode 100644 index 00000000000..3898a0cdecf --- /dev/null +++ b/docs/library/jesd204/xgt_wizard/index.rst @@ -0,0 +1,404 @@ +.. _xgt_wizard: + +Xilinx FPGAs Transceivers Wizard +================================================================================ + +The 7 Series and Ultrascale FPGAs Transceivers Wizard can be used to configure +the transceivers inside the :ref:`util_adxcvr ` core. In general +in all reference designs the gigabit transceivers are configured to the highest +supported line rate of the device. If the user wants to use their system with a +different line rate, she needs to reconfigure the transceivers. This can be done +by software, which does the reconfiguration through the DRP interface of the +transceivers. Due the complexity of the transceivers, it can happen that the +user needs to do addition settings in HDL using the Wizard. The following wiki +provides a short guide on how to use the wizard to generate a transceiver +configuration for a JESD204B interface. + +.. note:: + + To learn more about the 7 Series FPGAs transceivers and the Wizard, please + read the :xilinx:`UG476 ` + and :xilinx:`PG168 `. + To learn more about the Ultrascale and Ultrascale+ FPGAs transceivers and + the Wizard, please read the + :xilinx:`UG476 `, + :xilinx:`UG576 `, + :xilinx:`UG578 ` + and :xilinx:`PG168 `. + +Required features by the JESD204B +-------------------------------------------------------------------------------- + +The following features are required for a JESD204B interface: + +- QPLL and CPLL for clock generation +- 8B/10B encoding and decoding +- TX and RX buffer to solve rate and phase differences between XCLK (PMA parallel clock) and USRCLK (device clock) +- RX Equalization and CDR +- RX Byte and Word alignment +- Tx configurable driver +- Polarity control + +There are 2 flows for generating transceivers using the wizard +------------------------------------------------------------------------------- + +The first one is using the GT wizard manually as explained below: +:ref:`Using_the_GUI_of_the_Wizard ` , +and a second one that uses a script to generate one or more configurations: +:ref:`Using_the_generator_script ` . +Please keep in mind that the script is capable of generating only configurations +where the TX ad RX lane rates are even. For more customization, you can use the +script to generate the configurations, then edit them manually as u please. + +If you used the script method, there is another script that parses the generated +configurations and generates a list containing only the parameters that are +different from the default, the ones that you will have to change/add in your +system_bd.tcl: Parsing_script. This script does not work at the moment for the +configurations that are not generated by the script. + +.. _xgt_wizard_gui_of_the_wizard: + +Using the GUI of the Wizard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +7 Series FPGAs Transceiver Wizard +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +To start the wizard in the Vivado, a project should be loaded with a 7 Series +FPGA which has gigabit transceivers. In the **Project Manager** select IP +catalog and search after the keyword **wizard**, then select the **7 Series +FPGAs Transceivers Wizard** IP. + +You can define a custom name for your component and leave it on default. The +tools should recognize your transceiver type (**GT Type**) automatically, if +not, you may have to double check if you have the right FPGA device selected +for your project. You also need to select **Include Shared Logic in core** at +the Shared Logic section in order to have both COMMON and CHANNEL instances in +the generated code. + +Line Rate and RefClk Selection +******************************************************************************** + +First, you need to select **JESD204** as targeted **protocol** and specify your +**line rate** and **reference clock**. A valid reference clock depends on your +line rate. Make sure that you're using a valid reference clock form the drop-down +list. Also you should set the used **PLLs** for **TX** and **RX**. If your line +rate is equal for both directions, you can use the same PLL. Be aware that each +PLL's VCO has a different frequency range where the circuit can function +correctly. If your targeted line rate is too high or too low, you may be +restricted to use just one of the two PLLs. All other settings can be left on +their default value in this tab. + +Encoding and Clocking +******************************************************************************** + +If you selected **JESD204** to be the used protocol, you don't have to change +anything here. The JESD204B interface is using 8B/10B encoding/decoding, and +the internal data width will be 40 bits. In all the reference designs the DRP +frequency is connected to the system clock (100 MHz). In the **Synchronization +and Clocking** section, both TX and RX should have an **enabled buffer**. For +the TXOUTCLK and RXOUTCLK source selection, you can leave the options unchecked, +as both clocks are already using PLLREFCLK as their source. + +Other tabs +******************************************************************************** + +The setting from the tabs **PCIe, SATA, PRBS** and **CB and CC Sequence** can +be left to their default values. + +Generated files +******************************************************************************** + +Location of the **COMMON** instance: + - /.gen/sources_1/ip//_common.v +Location of the **CHANNEL** instance: + - /.gen/sources_1/ip//_gt.v + +.. shell:: bash + + /hdl/projects + $less daq2_zc706.gen/sources_1/ip/gtwizard_0/gtwizard_0_common.v + $less daq2_zc706.gen/sources_1/ip/gtwizard_0/gtwizard_0_gt.v + +These instances should be compared with the COMMON and CHANNEL instances used in +:git-hdl:`util_adxcvr_xcm.v ` and +:git-hdl:`util_adxcvr_xch.v `. + +Ultrascale FPGAs Transceiver Wizard +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The overall workflow with the Ultrascale FPGAs Transceiver Wizard is similar to +the 7 Series one, it just has a different GUI. To open up the wizard in the +**Project Manager** select **IP Catalog** and search after the keyword **wizard**, +then select the **Ultrascale FPGAs Transceivers Wizard**. You can define a +custom name for your component and leave it on default. The tools should +recognize your transceiver type automatically, if not, you may have to double +check if you have the right FPGA device selected for your project. To apply the +general JESD204B setting, select the **GTH-JESD204 preset**. In the first tab, +called **Basic** you can find all the necessary settings. Select the targeted +**line rate, PLL** and **reference clock**. The tool will tell you what PLL and +reference clock can be used with a specific line rate. Note that the current +version of the util_adxcvr core does not support **QPLL Fractional-N option**. + +To have both COMMON and CHANNEL instances inside the generated core, in the +**Structural Options** tab the **Include transceiver COMMON in the Core** +option must be selected. + +Generated files +******************************************************************************** + +To find the actual instance attributes, two different files should be examined. +A generic one, which contains the actual software macro instance, and a wrapper, +which instanciates the previous file and sets the required attributes. + +Location of the **COMMON** instance: + - /.gen/sources_1/ip//synth/gtwizard_ultrascale_v1_7_gthe4_common.v +Location of the **COMMON** wrapper: + - /.gen/sources_1/ip//synth/_gthe4_common_wrapper.v +Location of the **CHANNEL** instance: + - /.gen/sources_1/ip//synth/gtwizard_ultrascale_v1_7_gthe4_channel.v +Location of the **CHANNEL** instance: + - /.gen/sources_1/ip//synth/_gthe4_channel_wrapper.v + +.. shell:: bash + + /hdl/projects + $less daq2_zcu102.gen/sources_1/ip/gth_jesd204/synth/gtwizard_ultrascale_v1_7_gthe4_common.v + $less daq2_zcu102.gen/sources_1/ip/gth_jesd204/synth/gth_jesd204_gthe4_common_wrapper.v + $less daq2_zcu102.gen/sources_1/ip/gth_jesd204/synth/gtwizard_ultrascale_v1_7_gthe4_channel.v + $less daq2_zcu102.gen/sources_1/ip/gth_jesd204/synth/gth_jesd204_gthe4_channel_wrapper.v + +.. note:: + + The example above is for the project :git-hdl:`DAQ2 with ZCU102 ` + and with a component name "gth_jesd204". + +These generated attributes values should be compared with the values used with +the COMMON and CHANNEL instances in +:git-hdl:`util_adxcvr_xcm.v ` +and :git-hdl:`util_adxcvr_xch.v ` . + +.. _xgt_wizard_generator_script: + +Using the generator script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + If you are using Windows, please use the ad_gth_generator command followed + by the parsing script call, since the get_diff_params only works for linux + systems + +Open the TCL console inside your Vivado project. Source gtwizard_generator.tcl + +.. code-block:: tcl + + source ../../scripts/gtwizard_generator.tcl + +Generating configuration +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Here you have 2 options. + +ad_gth_generator +******************************************************************************** + +**Recommended method for generating multiple configurations** + +This function only generates the IPs, but you can edit them using GT wizard +afterwards. After sourcing the script, you can just run the following command +ad_gth_generator with the desired parameters. + +.. code-block:: tcl + + ad_gth_generator { 9.8304 } QPLL1 { 245.76 } + +The first parameter represents the lane rate that will be set to both RX and TX. +The second one can be CPLL, QPLL, QPLL0, QPLL1, depending on the transceiver of +the board. The third one is the reference clock. If left empty, then it will be +filled with all the viable values for the lane rate given. This feature does +not work at the moment for GTXE2 transceivers. + +.. code-block:: tcl + + ad_gth_generator {9.8304} QPLL0 {} + +Both the first and the third parameters are actually lists, so you can use that +to generate multiple configurations. Keep in mind that the script will generate +IPs with all the combinations between the lane rate and reference clock. + +.. code-block:: tcl + + ad_gth_generator {9.8304 4.9152} QPLL0 {245.76 122.88} false + +This call makes 4 instances of transceivers. Now you can double click on the +.xci from the sources window to further customize the IP, including +configurations where RX and TX have different rates. After you are all set, +run the Parsing_script to get the list of parameters that need to be changed +into the project. + +get_diff_params +******************************************************************************** + +**Recommended method for generating a single configuration** + +This function generates the IP and calls the parsing script. + +.. note:: + + This method works only with configurations where TX and RX have the same + lane rate + +Call the get_diff_params method with the desired parameters. + +.. code-block:: tcl + + get_diff_params 15.4 QPLL0 385 + +The first parameter represents the lane rate that will be set to both RX and +TX. The second one can be CPLL, QPLL0, QPLL1. The third one is the reference +clock. If left empty, then it will be filled with all the viable values for +the lane rate given. + +.. code-block:: tcl + + get_diff_params {9.8304} QPLL0 {} false + +The fourth parameter is optional. If you set it to false, the script will +remove from the project and delete from disk the generated IPs after the +list of parameters is done, so you don't have to do that manually. + +Both the first and the third parameters are actually lists, so you can use +that to generate multiple configurations. Keep in mind that the script will +generate IPs with all the combinations between the lane rate and reference +clock. + +.. code-block:: tcl + + get_diff_params {9.8304 4.9152} QPLL0 {245.76 122.88} false + +This call makes 4 instances of transceivers, and also deletes them after +generating the list because of the 4th parameter is set to false. + +Parsing script +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +If you used the get_diff_params method from the script to generate the IP, +there is no need to call it again. + +If you used the ad_gth_generator method from the script, you will have to call +the parsing script from the shell, as explained below. + +If you edited the IP in any way after generating it, make sure to generate +output products for the transceiver before going forward. + +Navigate to .gen/sources_1/ip in the terminal. From there, call +the gtwiz_parser.pl script, specifying the GT type as in the example. + +.. code-block:: tcl + + ../../../../../scripts/gtwiz_parser.pl GTHE4 + +If you run the script wile having multiple configurations, it will include the +unique parameters for each IP, plus the gt_global list that contains the +common parameters within generated configurations that are different from the +default values. Now, you should find the files at .gen/sources_1/ip +Make sure to overwrite the list from system_bd with the one in _cfng.txt. + +.. warning:: + + Please note that if you used the GUI method to instantiate the wizard, the + paring script will not work + +Output products +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Output products can be found at this location: .gen/sources_1/ip + +Most of the output files make sense in the context of parsing multiple +configurations at once. If this is not the case, and you just used it to +generate a single configuration, then the only file you need is _cfng.txt. + +If you had multiple configurations, all the output files should give you some +valuable information. + +GT_Type_cfng.txt +******************************************************************************** + +This file contains 2 lists. The first one is a list of parameters that are +unique for the desired configuration/configurations, different from the default +values, and these parameters should be written into the system_bd file for your +project. The next list called “gt_global” is a list of parameters that are +common between the multiple generated configurations. These are also only the +ones different from the default ones. This list should be empty if you have +only one configuration generated. + +GT_Type_var_dist.txt +******************************************************************************** + +Here you will find a list with the distribution of each DRP attribute in +relation to the lane rates of your instances. + +.. code-block:: + + $VAR1 = 'RX_CLK25_DIV'; + $VAR2 = { + '8' => [ + 'GTHE4_QPLL0_9_8304_196' + ], + '10' => [ + 'GTHE4_QPLL0_9_8304_245' + ] + }; + $VAR3 = 'QPLL0_FBDIV'; + $VAR4 = { + '50' => [ + 'GTHE4_QPLL0_9_8304_196' + ], + '40' => [ + 'GTHE4_QPLL0_9_8304_245' + ] + }; + $VAR5 = 'TX_CLK25_DIV'; + $VAR6 = { + '8' => [ + 'GTHE4_QPLL0_9_8304_196' + ], + '10' => [ + 'GTHE4_QPLL0_9_8304_245' + ] + }; + +GT_Type_vco_dist.txt +******************************************************************************** + +Here you will find a list with the distribution of each DRP attribute in +relation to the VCO frequency of your instances. If this list is empty, that +means that the attributes are the same for the used VCOs (Probably all the +instances have the same VCO) This should look similar to “GT_Type_var_dist.txt” + +table_common.csv +******************************************************************************** + +This is a table containing 3 columns: The first one is the name of the parameter. +The second one is the default value for that parameter, and it is that value +found in the util_adxcvr file. The third column is called gt_global, and it +contains the value that all the configurations have in common, but is different +from the default. If there is an empty cell in this column, it means that there +is used the default value. + +table_unique.csv +******************************************************************************** + +This table contains the unique parameters for each individual configurations. +The values found here are the ones that differ among your generated +configurations. + +.. note:: + + If you encounter errors using the script, please make sure that you have the + .gen/sources_1/ip and .srcs/sources_1/ip folders + clear from other previous gtwizard IP instances. Also, the script uses git + to update the default util_adxcvr files, and it will probably not work if + you are in detached HEAD state, or any state that could generate git + conflicts with it. \ No newline at end of file diff --git a/docs/library/xilinx/util_adxcvr/index.rst b/docs/library/xilinx/util_adxcvr/index.rst index abe83200edb..2f93540e850 100644 --- a/docs/library/xilinx/util_adxcvr/index.rst +++ b/docs/library/xilinx/util_adxcvr/index.rst @@ -253,7 +253,7 @@ Design Guidelines -------------------------------------------------------------------------------- .. note:: - Please refer to :dokuwiki:`AMD Xilinx FPGAs Transceivers Wizard ` + Please refer to :ref:`Xilinx FPGAs Transceivers Wizard ` to generate the optimal parameters needed to configure the transceivers for your project. diff --git a/projects/scripts/gtwizard_generator.tcl b/projects/scripts/gtwizard_generator.tcl index 11a1d982715..50d6695691f 100644 --- a/projects/scripts/gtwizard_generator.tcl +++ b/projects/scripts/gtwizard_generator.tcl @@ -437,7 +437,7 @@ proc ad_gth_generator { {lane_rate_l {}} {pll_type {}} {ref_clk_l {}} } { ## This output should then overwrite the existing instance in the system_bd.tcl. ## The output products can be found at .gen/sources_1/ip (*_cfng.txt) ## It must be called inside a Ultrascale or Ultrascale+ project. -## Wiki documentation: wiki.analog.com/resources/fpga/docs/xgt_wizard +## GitHub documentation: https://analogdevicesinc.github.io/hdl/library/jesd204/xgt_wizard/index.html ## ############################################################################### proc get_diff_params { {lane_rate_l {}} {pll_type {}} {ref_clk_l {}} {keep_ip "true"} } {