Creating a new IP

Here is a quick start guide about creating a new IP. You can start from these files and modify them as you need. Here is the code for a fan control IP: library/axi_fan_control. In this tutorial, we will make a led control IP, using AXI. In this case, <module_name> will be replaced in code with axi_led_control for Xilinx and axi_led_control_intel for Intel.

Verilog File

Lets say you want to make a new IP with the name <module_name>. You must edit the verilog file so that it has the same name (e.g. axi_led_control.v). After that, feel free to write the verilog code for your purpose. You can also use other instances of modules, but be sure to include them after, in the tcl file, under the <other_components> list.

Register Map

The register map is defined in a docs/regmap/adi_regmap_*.txt file and follows a special syntax.

One file can have more than one register map, and they are bounded by the header:

TITLE
[USING <regmap_to_inherit>]
<title> (<ip_name>)
<unique_id>
ENDTITLE

Example:

TITLE
SPI Engine (axi_spi_engine)
AXI_SPI_ENGINE
ENDTITLE

The USING line is only present if the register map imports other register map for look-up.

The register and fields are defined with the following syntax:

REG
0x00000000
[WHERE n IS ...]
<name>
<description>
ENDREG

FIELD
[31:0] 0x00000000
[WHERE n IS ...]
<description>
<access>
ENDFIELD

For example:

REG
0x00000001
VERSION
Version of the peripheral.
Follows semantic versioning. Current version 1.00.71.
ENDREG

FIELD
[31:16] 0x00000001
VERSION_MAJOR
RO
ENDFIELD

FIELD
[15:8] 0x00000001
VERSION_MINOR
RO
ENDFIELD

FIELD
[7:0] 0x00000071
VERSION_PATCH
RO
ENDFIELD

The WHERE line is only present if using ranged register/fields.

Noticed that the description can be multi-line and can also include Sphinx syntax, parsed during build The file content is always 90-columns wide. A field default value shall be a parameter, by escaping it with “double” single quotes '', e.g.

FIELD
[31:0] ''ID''
PERIPHERAL_ID
RO
Value of the ID configuration parameter.
In case of multiple instances, each instance will have a unique ID.
ENDFIELD

Examples:

Importing with Using Method

If using the USING method for look-up, registers and fields are imported with the following syntax:

REG
<reg_to_import>
ENDREG

FIELD
<field_to_import>
ENDFIELD

For example:

REG
CNTRL_1
ENDREG

FIELD
SDR_DDR_N
SYMB_8_16B
ENDFIELD

Some considerations:

  • Imported registers shall have non-imported fields, for example, when importing a register that is reserved for custom implementation.

  • Imported fields must be inside a imported register, since the field name is not unique.

  • Multiple fields can be imported from a single FIELD group.

Ranged Registers and Fields

Registers and fields can use a special n variable and the WHERE method to define an incrementing/repeating register/field. The syntax is WHERE n IS FROM <lower> TO <UPPER>, for example, for registers:

REG
0x0102 + 0x16*n
WHERE n IS FROM 0 TO 15
CHAN_CNTRLn_3
DAC Channel Control & Status (channel - 0)
ENDREG

and for fields:

FIELD
[n]
WHERE n IS FROM 0 TO 31
ES_RESETn
RW
Controls the EYESCANRESET pin of the GTH/GTY transceivers for lane n.
ENDFIELD

Xilinx

TCL File

The tcl file should be named <module_name_ip>.tcl (ex: axi_led_control_ip.tcl). Here you should keep the two lines that source our scripts :

source ../scripts/adi_env.tcl
source $ad_hdl_dir/library/scripts/adi_ip_xilinx.tcl

Then take a look at the commands

adi_ip_create <module_name>
adi_ip_files <module_name> [list <other_components>]

These commands create the IP and add the dependencies for it. By <other_components> we refer to the modules we were talking about above, that must be included in the tcl file. Also, <other_components> must include the verilog file for the IP itself, named <module_name>.v.

If your new IP uses AXI Lite for register control, then the next command is

adi_ip_properties <module_name>

It is used to initialize properties like memory and so on. If the IP does not use AXI, then you should use

adi_ip_properties_lite <module_name>

At the end of the file don’t forget to save the IP by using this command

ipx::save_core [ipx::currentcore]

If you need more help, here is an example of an IP called axi_led_control. You can open it side by side with the tcl file from the original axi_fan_control and apply the same logic to make your changes.

# ip

source ../scripts/adi_env.tcl
source $ad_hdl_dir/library/scripts/adi_ip_xilinx.tcl

adi_ip_create axi_led_control
adi_ip_files axi_led_control [list \
  "$ad_hdl_dir/library/common/up_axi.v" \
  "axi_led_control.v"]

adi_ip_properties axi_led_control
set cc [ipx::current_core]

ipx::save_core $cc

Makefile

In this file you will also have to change/add paths to every file in <other_components> list, using GENERIC_DEPS. Make sure to also change LIBRARY_NAME and XILINX_DEPS to match the name for the new IP.

If you need more help, here is an example of an IP called axi_led_control. You can open it side by side with the Makefile from the original axi_fan_control and apply the same logic to make your changes.

LIBRARY_NAME := axi_led_control

GENERIC_DEPS += ../common/up_axi.v
GENERIC_DEPS += axi_led_control.v

XILINX_DEPS += axi_led_control_ip.tcl

include ../scripts/library.mk

Now you can run the famous make in command line from the IP directory. After that, <module_name> will be accessible within vivado for future integrations.

Intel

TCL File

The tcl file should be named <module_name_hw>.tcl (ex: axi_led_control_intel_hw.tcl) These first 4 lines of code you should keep:

package require qsys 14.0
package require quartus::device

source ../scripts/adi_env.tcl
source ../scripts/adi_ip_intel.tcl

After that, the next line creates the new IP:

ad_ip_create <module_name> {entity_name}.

The module_name is the name of the IP you are creating, but entity_name will be the one visible inside Quartus IP Catalogue.

Next, you must add the other components used for creating the IP. For this, we will use the ad_ip_files command:

ad_ip_files <module_name> [list <other_components>]

The <other_components> list is referring to any other verilog file imported or used. It must also include the verilog file for the IP itself (<module_name>.v).

Now let’s add an instance of AXI:

ad_ip_intf_s_axi s_axi_aclk s_axi_aresetn 10

This command instantiates an interface using axi. The parameters refer to the ports of the interface, while the number refers to the width of the data bus.

There should be added an interface for every port of the IP. In this example, there is only one port left: led_on. This port is also external, so that’s what conduit is there for.

add_interface led_on_if conduit end
add_interface_port led_on_if led_on data Output 1

The last line is related to the port in the verilog file. In this case, led_on. The other parameters refer to <signal_type> <direction> <width_expression>.

In Quartus there is no need to save the core or run make afterwards. It is smart enough to search for _hw.tcl in the library directory. Although, you might need to add the path to the new IP in the IP Catalogue.

If you want to see the whole file, here is an example named axi_led_control_intel.

package require qsys 14.0
package require quartus::device

source ../scripts/adi_env.tcl
source ../scripts/adi_ip_intel.tcl

ad_ip_create axi_led_control_intel {AXI LED CONTROL}

ad_ip_files axi_led_control_intel [list \
  $ad_hdl_dir/library/common/up_axi.v \
  axi_led_control_intel.v]

#axi4 subordinate
ad_ip_intf_s_axi s_axi_aclk s_axi_aresetn 10

#output led
add_interface led_on_if conduit end
add_interface_port led_on_if led_on data Output 1

Makefile

You don’t need to run make for the IP to be visible in the Catalogue. Yet, here is the Makefile for the example mentioned before:

LIBRARY_NAME := axi_led_control_intel

GENERIC_DEPS += ../common/up_axi.v
GENERIC_DEPS += axi_led_control_intel.v


INTEL_DEPS += axi_led_control_intel_hw.tcl


include ../scripts/library.mk

This example was made starting from the axi_ad9361 IP found in our repo, under the library directory: ibrary/axi_ad9361.