X_MODULE_SPEC Attribute - 2023.2 English

Vivado Design Suite User Guide: Designing IP Subsystems Using IP Integrator (UG994)

Document ID
UG994
Release Date
2023-10-18
Version
2023.2 English

The existing X_INTERFACE_INFO and X_INTERFACE_PARAMETER HDL attributes can be replaced with a single X_MODULE_SPEC attribute . The X_MODULE SPEC is more user friendly in that it contains boundary information like port to interface mappings, and content information like CPUs inside IP STR/STC paths, parameters, elf file, etc.

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.