How to create an AXI4 Custom IP from scratch

Hi !

In this post we will create a custom IP with the following requirements :

- The IP will be placed in a new custom IP library
- The IP will be generated from scratch using the Vivado's wizzard
- The IP will have a slave AXI lite interface
- The IP has 4 internal registers accessible (read / write) by the processor
- The IP drives a LED with the following commands:

- The LED is set ON
- The LED is set OFF
- The LED is set blinking

- The blinking period is set using a generic parameter accessible from the Block Design GUI

As this post is quite long, here are the main sections of this post for a quick jump :

• Step 1 : Create the IP manager folder (Our library)
• Step 2 : Create our custom IP using the wizzard
• Step 3 : Edit the generated IP source files
• Step 4 : Finalize our IP in the IP editor

Good to know :

Creating custom IPs is a sub process of the Vivado tool. Vivado will provide everything to handle those IPs, even thow you can always do things manually when you know what you're doing !

The first thing to know is that Vivado provides a dedicated task to handle IP: the IP manager. This will create a dedicated Vivado project from where you can manipulate the IP library, in which your custom IPs / Interfaces can be added, removed, modified.

Then, when IPs are created, you can modify them in the IP manager or directly edit them when you use them in the block design editor, which is pretty convenient !

Finally, a custom IP is fully configurable and it is possible to easilly create the IP you've been looking for !

Step 1 : Create the IP manager folder (Our library)

Stage 1

Ok, first let's create a new project for the IP manager where we will store our library.

Launch Vivado and in the start up Tasks menu select Manage IP.

You can then either open an existing IP Manager project or create a new one.

Select New IP Location.

Then click next on the pop up screen that gives some explanations.

Stage 2

The next screen of the wizzard will let you configure the IP manager project.

First you have to select the device for which you want to create the IP.

Either you know the exact reference of you device (if you're working on a custom board for example) and you will choose the part reference in the Parts tab. Or either you are working with a dev board and you can use the pre defined settings for your board in the Boards tab.

First selelect the Boards tab.

Then in our case we select the Minized configuration.

And finally click Ok.

So back to the IP Manager settings screen.

You can select the HDL language you want, the HDL simulator you will use and the simulator's language.

In our case we will use the proposed defaults (VHDL, Vivado Simulator, Mixed).

Last thing, you have to select the folder for your library.

This folder will store the IP Manager project folder, our custom IPs folder and our custom interface folder.

I decide to call this folder my_test_ip_lib.

Finish with Select.

Ok, everything is set up, just click Finish.

Stage 3

Ok, the IP manager project is created and it opens.

You can see on the right side of the window the IP catalog proposed by Vivado, classified by categories.

IPs are stored in the Cores tab, but there is also the Interfaces tab where you can create your signals Interface.

This mandatory to simplify the graphical edition of Block Designs using IP boxes that contain many signals on their entity.

Step 2 : Create our custom IP using the wizzard

Stage 1

To create our custom IP go to the Tools menu, then select Create and Package New IP.

Stage 2

The Create and Package New IP Wizzard is launched.

Read the provided explanations.

Click Next.

In our case we want to create an AXI4 IP from scratch.

So select the Create a new AXI4 Peripheral section.

Click Next.

Stage 3

In this screen we will configure our IP.

First provide the name of the IP.

Version starts automatically at 1.0, leave this.

The display name is automatically built by the wizzard, leave it this way.

Description, you can provide what you want !

And most important, the location where the IP's folder will be stored.
Provide the path to the IP library's folder we've created in the previous steps : my_test_ip_lib.

Click Next.

This screen is very important !

This is where you will add all the main resources of your IP.

But remember, this wizzard will generate an example template, you can modify everything manually afterward !

By default we get an AXI4 Interface as requested. So we need to configure this interface :

- The interface's name. The S00_AXI is Xilinx's naming so keep it. S is for Slave and 00 for the interface index.
I always add the direction, here the interface is an input of the IP.
- The AXI4 type (Stream, Lite or Memory Map). Our IP will be controlled by a processor so a Lite interface is fine.
- The interface mode is slave. The processor is the master, it generates read/write cycles to the IP.
- The Data width of the busses, here 32 bits.
- The wizzard will generate a template with 4 registers.

Then click Next.

The next screen is the IP creation summary.

Review the information.

Select the action Add IP to the repository.

And click Finish.

Stage 4

And there it is !!!

Our IP appears in the IP catalog.

It shows that it is not in the Viado's Repository but in the User Repository.

As our IP has an AXI interface it is sorted in the AXI Peripherals section.

Stage 5

If we take a look inside the Library we've created.

Vivado created a default repository, but we will keep ours ! (Just to let you see that you can handle IPs as you want !!)

So just keep :

- managed_ip_project : which is the IP manager project's folder
- led_test_ip_1.0 : which is our custom IP's folder

Stage 6

Let's take a closer look to our IP's folder's content.

my_test_ip_lib  : Library's folder

    led_test_ip_1.0 : Custom IP structure folder

        bd : Folder containing the GUI definition in the Block Design editor

        drivers : Software drivers' folder

            led_test_ip_v1_0 : The driver auto generated by the wizzard for our IP

        example_designs : Design examples auto generated by the wizzard for our IP

        hdl : IP's sources folder

        xgui : tcl procedures for IP customization from GUI modifications

        component.xml : IP's definition file

Step 3 : Edit the generated IP source files

Stage 1

Let's take a look to the generated source files of our IP.

led_test_ip_v1_0.vhd : This is the top level of the IP. It instanciates the led_test_ip_v1_0_S00_AXI_IN.vhd module.

led_test_ip_v1_0_S00_AXI_IN.vhd : This is a template for an AXI4 Lite Slave interface.

It could be very interesting for you to have a look at this file to see how Xilinx implemented it !

Stage 2

Let's analyze the IP's top level file (led_test_ip_v1_0.vhd)

Here we have the entity. Basically, the wizzard provided the AXI4 Lite slave interface elements.

I added the G_BLINK_PERIOD generic parameter that will let us control statically from the BD's GUI the blinking period.

I also added to led_out output that will drive the LED on the board.

Some Constants and Signals declarations.

Then the wizzard made the AXI4 Lite interface module's instanciation.

I added the led_mode control register that will let us drive the LED behavior and which is generated in the AXI4 Lite module.

Last section, I added custom code.

First, a free running counter that is controlled by the G_BLINK_PERIOD generic parameter.

Second, the output stage that generates the LED behavior depending on the led_mode control register.

Stage 3

Let's analyze the IP's AXI4 Lite interface (led_test_ip_v1_0_S00_AXI_IN.vhd)

As this file is auto generated and quite long, I will let you read the file if you want an example of how generate this kind of interface.

I will just show you my modification of this file to generate the led_mode register.

Step 4 : Finalize our IP in the IP editor

Stage 1

If I open the IP Manager tool on my library's repository I can see my IP in the IP Catalog, in the User Repository section and in the AXI Peripheral category.

Then, select the IP, right click on it and launch Edit in the IP Packager tool.

Check that the editing project is located in the IP manager location, click Ok.

If the project already exists because you made previous editions, click click Ok to overwrite.

There you are, your IP is opened in the IP Packager tool !

Let's see how to finalize the IP's edition process.

Stage 2

Identification Section

In this section fields have been automatically filled.

The tool is happy, Identification section has a green tag.

You can update fields if you want, I keep them as they are.

Stage 3

Compatibility Section

This is where you specifiy the Xilinx devices familly that are compatible with your IP.

As we've designed the IP in a Vivado project set for our Minized board, the familly is the Minized's device familly, the Zynq.

You can add famillies using the Add cross, and you can set the Life cycle upon the tests you've made for your IP on each Device familly.

Everything is fine for the tool, we've got the green tag !

Stage 4

File Groups Section

This section lists all the source files that are needed to use the IP in different situations.

- The VHDL Synthesis section lists the source needed for implementation
- The VHDL Simulation section lists the source needed for RTL simulation
- The Software Driver section lists all the driver's template files
- The UI Layout section is a Tcl file to control GUI layout and customization of the IP
- The Block Diagram section list the tcl control file for IP GUI use in the Block Design editor.

For now we will leave it as it is, again we've got the green tag for this section !

You could add others elements to be packaged with the IP by using the Add cross.

Stage 5

Customization Parameters Section

This section is detected as modified because I modified the generated VHDL files !

The edit tag is shown for the section and the Merge changes from Customization Parameters Wizard action warning has pop up.

This is because I added the G_BLINK_PERIOD generic parameter in the source of the IP's top level.

To update this section, just click on the Merge changes from Customization Parameters Wizard hyperlink to launch the synchronization.

This action updates the entire IP in the IP packager tool, all the edit tags sections are updated !

In this section our G_BLINK_PERIOD generic parameter is detected, but it is for now identified as Hidden. This means it won't appear in the IP's GUI.

Just give it a check by viewing the Customization GUI. The G_BLINK_PERIOD generic parameter is still identified as hidden and does not appear in the preview sections.

So let's modify how our IP will look like in the GUI !

First of all, go back to the Customization Parameters section.

Ok, Double click on the G_BLINK_PERIOD generic parameter, this will open the parameter editor.

First, click on Visible in the Customization GUI, of course, we'll need to modify it on IP use in the BD !!

The tool provides a default Display name, usally I put the same string as the parameter's VHDL name. So change it to G_BLINK_PERIOD.

As this parameter has to be provided in 100Mhz clock cycle number unit, the user shall know it, just say it in the Tooltip. I used "Unit is 100Mhz clock cycle number". The tooltip will display when your mouse cursor passes over the parameter in the GUI.

The tool provided the right long type and proposed that the parameter is Editable in the GUI, fine !

Now click the Specify Range box to access the definition. Select Range of integer, and set the minimum to 10_000_000d for 10Hz and maximum to 100_000_000d for 1Hz.

And set the default value to 100_000_000.

Click Ok.

Just do the same for the 4 other parameters. As we don't need them in our application, just set them as NOT Visible in customization GUI.

Last step, in the Customization GUI section, just move the G_BLINK_PERIOD parameter in the Page 0 section, which let it appear on the right side window !

And there you go, our IP's GUI looks like this.

Stage 6

Ports and Interfaces Section

In this section we will find all the inputs/outputs defined in the IP's top level entity.

But the most important thing is that if your entity provides signals with names corresponding to a defined interface, the tool will automatically identify it and replace it with the interface view of the bunch of signals, thus reducing GUI's complexity !!!!

For our IP there are 3 standard interfaces :

- The AXI Lite Slave Interface
- The AXI reset in interface
- The AXI clock in interface

Stage 7

Addressing and Memory section

This section displays the memory mapping of the IP when the IP provides memory mapped interfaces.

You can specify the base address offset and the address range that will be decoded by the IP (Number of address bits in the implemented address decoder).

As all the provided parameters are generic parameters, they will be replaced by the values you will provide in the address editor in the Block Design editor when you use your IP.

Stage 8

As we used the Customization GUI section earlier, we will jump to the

Review and Package section

This is the final section !

You can read the summary and finally click Re-Package IP to generate your IP.

If you are re-Packaging an existing IP, just click to accept overwriting the existing project.

Then the IP packager tool closes and you're back in the IP catalog !

Post Conclusion

Waou ! This post was quite long, but IP customization can do many many things, so it is quite long to cover everything about it !

Now we have :

- Created a Custom IP Library.
- Used the wizzard to create an IP template structure.
- Customized the source code of the IP for our needs.
- Generated our custom IP in the custom IP Library