Wiki

This version (15 Apr 2024 08:46) was approved by Andrei Grozav.

Add HDL IP guide

Before starting this guide you should be familiar with https://wiki.analog.com/resources/fpga/docs/build.

ADI IPs can be found in hdl/library.

Generic file content of an library(IP) folder:

  • .v - Verilog files
  • .hv - Verilog header files
  • .sv - System Verilog files
  • .vhd - VHDL files
  • .sdc - constraint files (Intel tools)
  • .xdc - constraint files (Xilinx tools)
  • .ttcl - dynamic constraint files (Xilinx tools)
  • bd/bd.tcl - IP block definition files (Xilinx tools)
  • <ip_name>_ip.tcl - IP definition TCL files (Xilinx tools)
  • <ip_name>_hw.tcl - IP definition TCL files (Intel IPs)

Basic ip definition, tcl steps:

  1. Source ADI scripts(encapsulate vendor tool commands).
  2. Point the HDL files including constraint files.
  3. Define IP parameters and interfaces

In the following examples my_ip will be used as generic name.

When creating a new IP, a directory must be added in hdl/library folder, like my_ip.

Add IP for Xilinx tools

Source ADI scripts

Set the environment (hdl directory location).

source ../scripts/adi_env.tcl

Source ADI processes for IP creation.

source $ad_hdl_dir/library/scripts/adi_ip_xilinx.tcl
In this script is defined the required tool version, according to ADI release. Do not ignore the warnings regarding the used tool version. For more info see: Releases

Define the IP

adi_ip_create my_ip # defines the ip name, in our case  my_ip

Point to the HDL files

adi_ip_files my_ip[list ...]

Creates a fileset with the files used by my_ip. The name list is separated by “ ”(space). As an example:

adi_ip_files my_ip [list \
  "$ad_hdl_dir/library/common/ad_rst.v" \ # examples of adding some files used in my_ip
  "$ad_hdl_dir/library/common/ad_addsub.v" \
  "$ad_hdl_dir/library/xilinx/common/ad_rst_constr.xdc" \
  "my_ip.v" \
  "my_ip_function.v" \
  "my_ip_interfaces.v" \
  "my_ip_constrains.xdc" ]

For an actual IP implementation example seeaxi_ad9361

Define IP parameters and interfaces

adi_ip_properties my_ip
 
set_property driver_value 0 [ipx::get_ports *clk* -of_objects [ipx::current_core]]
set_property driver_value 0 [ipx::get_ports *frame* -of_objects [ipx::current_core]]
set_property driver_value 0 [ipx::get_ports *data* -of_objects [ipx::current_core]]
set_property driver_value 0 [ipx::get_ports *sync* -of_objects [ipx::current_core]]

Constraints

The constraints go in the .xdc and .ttcl files.

As an example for the .xdc, if the IP works with two clock domains and there is a FF sync stage implemented for a signal

always @(posedge clk_1) begin
  s_toggle_reg <= control_event;
end
 
always @(posedge clk_2) begin
  s_toggle_m1_reg <= s_toggle_reg;
  s_toggle_m2_reg <= s_toggle_m1_reg;
end

the following constraint will apply:

set_property ASYNC_REG TRUE [get_cells -hier -filter {name =~ *s_toggle*}] 
 
set_false_path -from [get_cells -hier -filter {name =~ *s_toggle_reg && IS_SEQUENTIAL}] \
               -to [get_cells -hier -filter {name =~ *s_toggle_m1_reg && IS_SEQUENTIAL}] 

Adding constraints dependent on the build arguments(parameters). These types of constraints are useful when working with an IP that gives the option for multiple interface selection and/or having synchronous or asynchronous clock domains.

adi_ip_ttcl my_ip ttcl_path/sctipt.ttcl
TTCL is “embedded TCL”. Basically TTCL returns a text file that has static and dynamic content, generate by TCL.

ttcl examples:

IP block design

The IP block design(db.tcl) is used when having an IP that contains logic dependent on block design parameters, such as clocks/interfaces connected to the IP, or on the FPGA part(resources).

The bd.tcl is based around the following hook processes:

  1. init
  2. propagate
  3. postpropagate

For more information regarding this processes see Xilinx IP packaging documentation.

The ADI IPs work with two types of bd.tcl, static and auto generated/removed during the build/clean process. The static bd files are for IPs that are dependent on clocks/interfaces. The bd files generated at build time are generic and are used for IPs dependent on the FPGA resources. The purpose of the autogenerated db.tcl is to determine the FPGA characteristics and set IP parameters according to those characteristics.

How is the bd/bd.tcl autogenerated/removed?

adi_init_bd_tcl

The above command will generate the “bd/bd.tcl file”. The file will contain the init, propagate and postpropagate processes, for parameters detected in the IP(top module) and also are predefined in auto_set_param_list.

The above command will also generate a file called temporary_case_dependencies.mk. This is a Makefile that contains the bd folder and itself as a cleaning “target”. Meaning when doing a make clean the bd folder and temporary_case_dependencies.mk will be erased.

How are the bd.tcl integrated/used?

Adding the bd files the the IP fileset.

adi_ip_bd my_ip "bd/bd.tcl"

Although the parameters(some) are defined in the bd files, this does not mean the work is done. The same parameters must be defined for the IP, type, range(if required), value and their presence in the GUI, format and location.

adi_add_auto_fpga_spec_params

One of the last steps is to let the tool create all the GUI files for the IP from the previous definitions.

ipx::create_xgui_files [ipx::current_core]

A good example of a static bd.tcl is the axi_clkgen IP, It is dependent on the FPGA resources and the clocks connected to it. And an example for a autogenerated bd, could be axi_ad9361.

Save IP

Finally to complete the IP creation one must call the save_core process.

ipx::save_core [ipx::current_core]

Add IP for Altera tools (work in progress)

The Intel tools search for IP files containing “_hw.tcl into their name.

package require qsys
package require quartus::device
source ../scripts/adi_env.tcl
source ../scripts/adi_ip_intel.tcl
ad_ip_create my_ip {my_ip custom logic} my_elaboration
set_module_property VALIDATION_CALLBACK info_param_validate
set_module_property COMPOSITION_CALLBACK p_avl_adxcvr
ad_ip_files my_ip [list ...]
ad_ip_parameter PARAMETER2 INTEGER 0
ad_ip_parameter PARAMETER2 INTEGER 0
adi_add_auto_fpga_spec_params

Creating interfaces

ad_ip_intf_s_axi s_axi_aclk s_axi_aresetn
ad_interface signal sync_in input 1
ad_interface signal sync_out output 1

Comparing to it's target scripts and files, this document might be outdated between ADI releases or some features present in the documentation may not be implemented in older ADI releases.

resources/fpga/docs/hdl/add_hdl_ip.txt · Last modified: 11 Feb 2021 11:15 by Andrei Grozav