Get Started with IP Core Generation from MATLAB Function

Open Live Script

This example shows how to use the MATLAB® HDL Workflow Advisor to generate a customized IP core that blinks LEDs on an FPGA board. This example deploys the generated IP core on the ZedBoard hardware, but you can use any Xilinx® Zynq® platform or Xilinx FPGA with a MicroBlaze processor.

Introduction

You can use MATLAB to design, simulate, and verify your application, perform what-if scenarios with algorithms, and optimize parameters. You can then prepare your application design for hardware and software implementation on your FPGA board and decide which elements are performed by the programmable logic and which elements run on the processor.

In this example, you can:

Set up your Zynq hardware and tools.
Review your design for hardware and software implementation.
Convert your MATLAB algorithm to HDL code using HDL Coder.
Generate an HDL IP core by using the MATLAB HDL Workflow Advisor.
Deploy the IP core to Zynq hardware.
Prototype the Zynq hardware using included MATLAB scripts.

Additionally, you can use this IP core in other designs or projects to enhance and build upon its functionality.

Prerequisites

Install Xilinx Vivado®. For a list of supported versions, see HDL Language Support and Supported Third-Party Tools and Hardware.
Set the path to the installed synthesis tool for the target device by using the hdlsetuptoolpath function. In the MATLAB Command Window, use this command, making sure to replace the path with your installation path.

hdlsetuptoolpath('ToolName','Xilinx Vivado','ToolPath','C:\Xilinx\Vivado\2020.2\bin\vivado.bat');

Set up the ZedBoard. Refer to the "Set up Zynq Hardware and Tools" section in Get Started with IP Core Generation from Simulink Model for more information.
In this example, you implement the mlhdlc_ip_core_led_blinking function on the ZedBoard. Open and save a local copy of the function:

open mlhdlc_ip_core_led_blinking.m

Open and save a local copy of the MATLAB test bench.

open mlhdlc_ip_core_led_blinking_tb.m

Review and Partition Design for Hardware and Software Implementation

To generate and deploy an IP core from a MATLAB algorithm, you need three components:

A MATLAB function that runs on the hardware.
A MATLAB test bench that exercises the function design in MATLAB.
MATLAB scripts that prototype the deployed MATLAB function on the hardware. Prototyping using MATLAB is optional, but provides an additional means of IP core verification.

To effectively implement your design, you must:

Distinguish between the parts of the algorithm that are suitable for programmable logic and the parts that are suitable for the ARM processor.
Group the algorithm parts for the programmable logic into a MATLAB function.
Use the MATLAB function as the boundary for your hardware-software partition.
Use HDL Coder to implement the MATLAB code in this function on programmable logic.

Open the mlhdlc_ip_core_led_blinking function to examine how it is partitioned.

open mlhdlc_ip_core_led_blinking.m

This function models a counter that blinks LEDs on an FPGA board. It has two inputs, Blink_frequency and Blink_direction, which determine the LED blink frequency and direction. The output, LED, connects to the LED hardware found on the board and the output, Read_back is set to the count value and can be read back to the processor.

Open the mlhdlc_ip_core_led_blinking_tb test bench to examine how it exercises the function design.

open mlhdlc_ip_core_led_blinking_tb.m

The test bench provides a range of input conditions to the mlhdlc_ip_core_led_blinking function.

Open the included MATLAB scripts matlab_hdlcoder_led_blinking_interface.m and matlab_hdlcoder_led_blinking_setup.m.

open matlab_hdlcoder_led_blinking_interface.m
open matlab_hdlcoder_led_blinking_setup.m

These scripts set up and interface with the generated and deployed IP core by writing to the AXI accessible registers.

Create MATLAB HDL Coder Project

Create an HDL Coder project by entering this command in the MATLAB Command Window.

coder -hdlcoder -new blinkingLEDmatlab

For a more comprehensive tutorial on creating and populating MATLAB HDL Coder projects, see Get Started with MATLAB to HDL Workflow.

Alternatively, in the Apps tab, click HDL Coder. In the HDL Code Generation pane:

Set the MATLAB Function to the locally saved MATLAB function, mlhdlc_ip_core_led_blinking.
Set the MATLAB Test Bench to the locally saved MATLAB test bench, mlhdlc_ip_core_led_blinking_tb.
In the MATLAB Function section, click Autodefine types to define the input types automatically.
Click Workflow Advisor.

Using the Workflow Advisor, perform a fixed-point conversion:

In the Fixed-Point Conversion task, click Advanced and ensure Safety margin for sim min/max (%) is 0.
In the bottom pane, in the Variables tab, in the Proposed Type column, set the proposed type of the freqCounter variable to unsigned 24-bit integer by entering numerictype(0, 24, 0).
Right-click the Fixed-Point Conversion task and select Run This Task.

For an overview on fixed-point conversion, see Floating-Point to Fixed-Point Conversion.

Define Code Generation Target

You can generate a shareable and reusable IP core using the MATLAB HDL Workflow Advisor. HDL Coder integration with the Xilinx Vivado IDE facilitates the incorporation of the generated IP core into the FPGA design.

For an overview of how to generate an IP core for a specific hardware platform, see Targeting FPGA & SoC Hardware Overview.

Perform IP Core Generation using the MATLAB HDL Workflow Advisor:

In the MATLAB HDL Workflow Advisor, click Select Code Generation Target.
Set Workflow to IP Core Generation.

Specify Platform

In order to integrate the generated IP core in a reference design, set Platform to a target platform:

Generic Xilinx Platform: This is a board-independent option that generates a generic Xilinx IP core. However, you must manually integrate the IP core into an existing Xilinx Vivado project.
Board-specific platforms: These options are specific to Xilinx boards and integrate the IP core into a predefined reference design. This integration uses the Xilinx Vivado with IP Integrator embedded system tool.

In this example, you target a ZedBoard platform. Set these parameters:

Set Platform to ZedBoard.
Set Synthesis tool to Xilinx Vivado.
Set Target Frequency (MHz) to 50.
Under IP core settings, set Reference design to Default system.

Configure Target Interfaces

Next, you use the Set Target Interface subtask to map each input and output in the MATLAB design function to one of the IP core target interfaces.

In this example, map inputs Blink_frequency and Blink_direction, along with the output Read_back to the AXI4-Lite interface. HDL Coder generates AXI accessible registers for them. Map the LED output to an external interface, LEDs General Purpose [0:7], which connects to the LED hardware on the ZedBoard.

In the bottom pane, in the Ports tab, in the Target Platform Interfaces column, set the target platform interface for the Blink_frequency, Blink_direction, and Read_back variables to the AXI4-Lite interface.
In the bottom pane, in the Ports tab, in the Target Platform Interfaces column, set the target platform interface for the LED variable to the LEDs General Purpose [0:7] external interface.
Right-click the Set Target Interface subtask and select Run to Selected Task.

To generate the IP core and IP core report, right-click the HDL Code Generation task and select Run this task.

Integrate Generated IP Core with Xilinx Vivado Environment

After generating the IP core, you integrate it with a reference design, then synthesize and download the bitstream to the FPGA within the MATLAB HDL Workflow Advisor.

1. Under the Embedded System Integration task, right-click the Create Project subtask and select Run This Task. A Xilinx Vivado project is generated that integrates the IP core in a predefined reference design by leveraging the IP Integrator embedded system tool. The dialog box includes a link to open the project in Vivado.

2. In the Build Embedded System subtask, select Run build process externally, then click Run. The Xilinx synthesis tool runs as a separate process outside of MATLAB. Wait for the synthesis tool to complete.

3. After generating the bitstream, right-click the Program Target Device subtask and select Run This Task to program the ZedBoard.

4. After programming the FPGA hardware, the LEDs start blinking on the ZedBoard.

Prototype and Verify IP Core on Hardware

To verify your generated IP core on the ZedBoard hardware, use the included handwritten MATLAB files, matlab_hdlcoder_led_blinking_interface.m and matlab_hdlcoder_led_blinking_setup.m. These files contain MATLAB commands that connect your hardware and interact with your IP core.

Open the interface and setup files and save local copies:

open matlab_hdlcoder_led_blinking_interface.m
open matlab_hdlcoder_led_blinking_setup.m

The matlab_hdlcoder_led_blinking_interface.m script establishes a connection to your FPGA hardware and uses the matlab_hdlcoder_led_blinking_setup function to enable data reading and writing by configuring the fpga hardware object with the mapped ports and interfaces from the Set Target Interface subtask.

You can reuse this function in your own scripts to replicate the same configuration. For example, in the matlab_hdlcoder_led_blinking_interface.m script uncomment and modify this line to change the LED blink frequency.

% writePort(testFPGA, "Blink_frequency_1", 0);

Run the modified script and observe the LED blink frequency changing on the hardware. Additionally, in the matlab_hdlcoder_led_blinking_interface.m script uncomment this line and run the script to observe the changes in the data_Read_back variable in the MATLAB workspace.

% data_Read_back = readPort(testFPGA, "Read_back");