X_MODULE_SPEC Attribute - 2022.2 English

How to Insert X_MODULE_SPEC Attribute

To reference an IP or BD module into another BD as RTL module reference, you must first create a Shim RTL file.

1. Create a new Shim RTL file (Example: Shim.v containing the Shim module) from an IP or a BD instantiation template, or from a generated BD wrapper.
   Important: If using a BD wrapper be sure to configure it to be "managed by user" to avoid future BD generations overwriting your work. Make sure the BD output products are generated before using the ::ipx::package_module_spec tcl commands below.
   Figure 1. RTL Module with BD
   
   
   
2. Use the ipx::package_module_spec command as mentioned below to create the default X_MODULE_SPEC attribute for a wrapped module. IP or BD modules must be generated before running ipx::package_module_spec or else the tool will fail with an error.

   ipx::package_module_spec -create -module_name <BD_name> -output_file module_spec.json

   With reference to the example in the previous figure, the command would be

   ipx::package_module_spec -create -module_name lower_bd -output_file module_spec.json

3. Optionally you can edit module specification in the JSON file. Validate switch would validate the module specification w.r.t. the target 'Shim' module.

   ipx::package_module_spec -validate -module_name Shim -input_file module_spec.json

4. Convert the module specification from JSON to RTL format.

   JSON-to-Verilog: ipx::package_module_spec -convert -module_name <BD_name> -language verilog -input_file module_spec.json -output_file module_spec.v
   
   JSON-to-VHDL: ipx::package_module_spec -convert -module_name <BD_name> -language vhdl    -input_file module_spec.json -output_file module_spec.vhd

   With reference to the example in the previous figure, the command would be:

   ipx::package_module_spec -convert -module_name Shim -language vhdl -input_file module_spec.json
   
   ipx::package_module_spec -convert -module_name Shim -language verilog -input_file module_spec.json

5. Copy the edited X_MODULE_SPEC attribute (i.e. the contents of module_spec.v) into the Shim.v file. Paste above the Shim module in Verilog or within the Shim ENTITY for VHDL. The following is X_MODULE SPEC in Verilog:

   `timescale 1 ps / 1 ps
   
   (* X_MODULE_SPEC = "{\
     'schema': 'xilinx.com:schema:json_module:1.0',\
     'boundary': {\
       'interfaces': {\
         'ddr4_dimm1_sma_clk': {\
           'vlnv': 'xilinx.com:interface:diff_clock:1.0',\
           'abstraction_type': 'xilinx.com:interface:diff_clock_rtl:1.0',\
           'mode': 'slave',\
           'parameters': {\
             'CAN_DEBUG': [ { 'value': 'false' } ],\
             'FREQ_HZ': [ { 'value': '200000000' } ],\
             'BUSIF.BOARD_INTERFACE': [ { 'value': 'ddr4_dimm1_sma_clk' } ]\
           },\
           'port_maps': {\
             'CLK_N': [ { 'physical_name': 'ddr4_dimm1_sma_clk_clk_n' } ],\
             'CLK_P': [ { 'physical_name': 'ddr4_dimm1_sma_clk_clk_p' } ]\
           }\
         },\
         'CLK.CLK_100MHZ': {\
           'vlnv': 'xilinx.com:signal:clock:1.0',\
           'abstraction_type': 'xilinx.com:signal:clock_rtl:1.0',\
           'mode': 'slave',\
           'parameters': {\
             'FREQ_HZ': [ { 'value': '100000000' } ],\
             'FREQ_TOLERANCE_HZ': [ { 'value': '0' } ],\
             'PHASE': [ { 'value': '0.0' } ]\
           },\
           'port_maps': {\
             'CLK': [ { 'physical_name': 'clk_100MHz' } ]\
           }\
         }\
       }\
     }\
   }" *)
   
   
   module Shim
      (clk_100MHz,
       ddr4_dimm1_sma_clk_clk_n,
       ddr4_dimm1_sma_clk_clk_p);
     input clk_100MHz;
     input ddr4_dimm1_sma_clk_clk_n;
     input ddr4_dimm1_sma_clk_clk_p;
   
     wire clk_100MHz;
     wire ddr4_dimm1_sma_clk_clk_n;
     wire ddr4_dimm1_sma_clk_clk_p;
   
     lower_bd lower_bd_i
          (.clk_100MHz(clk_100MHz),
           .ddr4_dimm1_sma_clk_clk_n(ddr4_dimm1_sma_clk_clk_n),
           .ddr4_dimm1_sma_clk_clk_p(ddr4_dimm1_sma_clk_clk_p));
   Endmodule
   

   This is the X_MODULE SPEC in VHDL:

   library IEEE;
   use IEEE.STD_LOGIC_1164.ALL;
   library UNISIM;
   use UNISIM.VCOMPONENTS.ALL;
   entity Shim is
     port (
       clk_100MHz : in STD_LOGIC;
       ddr4_dimm1_sma_clk_clk_n : in STD_LOGIC;
       ddr4_dimm1_sma_clk_clk_p : in STD_LOGIC
     );
     
     ATTRIBUTE X_MODULE_SPEC : STRING;
   ATTRIBUTE X_MODULE_SPEC OF Shim : ENTITY IS "{" & 
   "  'schema': 'xilinx.com:schema:json_module:1.0'," & 
   "  'boundary': {" & 
   "    'interfaces': {" & 
   "      'ddr4_dimm1_sma_clk': {" & 
   "        'vlnv': 'xilinx.com:interface:diff_clock:1.0'," & 
   "        'abstraction_type': 'xilinx.com:interface:diff_clock_rtl:1.0'," & 
   "        'mode': 'slave'," & 
   "        'parameters': {" & 
   "          'CAN_DEBUG': [ { 'value': 'false' } ]," & 
   "          'FREQ_HZ': [ { 'value': '200000000' } ]," & 
   "          'BUSIF.BOARD_INTERFACE': [ { 'value': 'ddr4_dimm1_sma_clk' } ]" & 
   "        }," & 
   "        'port_maps': {" & 
   "          'CLK_N': [ { 'physical_name': 'ddr4_dimm1_sma_clk_clk_n' } ]," & 
   "          'CLK_P': [ { 'physical_name': 'ddr4_dimm1_sma_clk_clk_p' } ]" & 
   "        }" & 
   "      }," & 
   "      'CLK.CLK_100MHZ': {" & 
   "        'vlnv': 'xilinx.com:signal:clock:1.0'," & 
   "        'abstraction_type': 'xilinx.com:signal:clock_rtl:1.0'," & 
   "        'mode': 'slave'," & 
   "        'parameters': {" & 
   "          'FREQ_HZ': [ { 'value': '100000000' } ]," & 
   "          'FREQ_TOLERANCE_HZ': [ { 'value': '0' } ]," & 
   "          'PHASE': [ { 'value': '0.0' } ]" & 
   "        }," & 
   "        'port_maps': {" & 
   "          'CLK': [ { 'physical_name': 'clk_100MHz' } ]" & 
   "        }" & 
   "      }" & 
   "    }" & 
   "  }" & 
   "}";
   end Shim;
   
   architecture STRUCTURE of Shim is
     component lower_bd is
     port (
       ddr4_dimm1_sma_clk_clk_n : in STD_LOGIC;
       ddr4_dimm1_sma_clk_clk_p : in STD_LOGIC;
       clk_100MHz : in STD_LOGIC
     );
     end component lower_bd;
   begin
   lower_bd_i: component lower_bd
        port map (
         clk_100MHz => clk_100MHz,
         ddr4_dimm1_sma_clk_clk_n => ddr4_dimm1_sma_clk_clk_n,
         ddr4_dimm1_sma_clk_clk_p => ddr4_dimm1_sma_clk_clk_p
       );
   end STRUCTURE;
   

6. Add the RTL module Shim.v to the BD design as a module reference. See the following figure with the example, create_bd_cell -type module -reference Shim Shim_0.
   Figure 2. Adding RTL Module with BD to another BD
7. Edit, validate, and generate the BD design as needed.

Limitations of the X_MODULE_SPEC

• X_MODULE_SPEC operates on a single module at a time. If there are multiple BD/XCI in a module, the X_module spec has to be generated individually, then manually merged into the module reference RTL.
• The reference RTL ports have to match with the BD/XCI inside.