Define Custom Parameters and Callback Functions for Custom Reference Design

When you define your custom reference design, you can optionally use the properties in the hdlcoder.ReferenceDesign object to define custom parameters and callback functions.

Define Custom Parameters and Register Callback Function Handle

This MATLAB^® code shows how to define custom parameters and register the function handle of the custom callback functions in the reference design definition function.

function hRD = plugin_rd()
% Reference design definition

% Construct reference design object
hRD = hdlcoder.ReferenceDesign('SynthesisTool', 'Xilinx Vivado');
hRD.ReferenceDesignName = 'My Reference Design';
hRD.BoardName = 'ZedBoard';

% Tool information
hRD.SupportedToolVersion = {'2020.2'};

%% Add custom design files
% ...
% ...

%% Add optional custom parameters by using addParameter property.
% Specify custom 'DUT path' and 'Channel Mapping' parameters. 
% The parameters get populated in the 'Set Target Reference Design' 
% task of the HDL Workflow Advisor.
hRD.addParameter( ...
    'ParameterID',   'DutPath', ...
    'DisplayName',   'Dut Path', ...
    'DefaultValue',  'Rx', ...
    'ParameterType',  hdlcoder.ParameterType.Dropdown, ...
    'Choice',       {'Rx', 'Tx'});
hRD.addParameter( ...
    'ParameterID',   'ChannelMapping', ...
    'DisplayName',   'Channel Mapping', ...
    'DefaultValue',  '1');

%% Enable AXI manager IP insertion for the JTAG connection. The IP
% insertion setting is visible in the 'Set Target Reference Design'
% task of the HDL Workflow Advisor. By default, the
% AddMATLABAXIManagerParameter property is set to 'true'.
hRD.AddMATLABAXIManagerParameter = 'true';
hRD.MATLABAXIManagerDefaultValue = 'JTAG';

%% Enable AXI manager IP insertion for the Ethernet connection. The IP
% insertion setting is visible in the 'Set Target Reference Design'
% task of the HDL Workflow Advisor. By default, the Ethernet option 
% for the AXI manager IP insertion setting is available for the 
% Artix-7 35T Arty, Kintex-7 KC705, and Virtex-7 VC707 boards. 
% Enable this option for other Xilinx boards that have the Ethernet 
% physical layer (PHY) by adding the Ethernet media access 
% controller (MAC) Hub IP in the plugin_board file before launching 
% the HDL Workflow Advisor. To add the Ethernet MAC Hub IP, use 
% the addEthernetMACInterface method.
hRD.AddMATLABAXIManagerParameter = 'true';
hRD.MATLABAXIManagerDefaultValue = 'Ethernet';

%% Add custom callback functions. These are optional.
% With the callback functions, you can enable custom 
% validations, customize the project creation, software 
% interface model generation, and the bistream build.
% Register the function handle of these callback functions.

% Specify an optional callback for 'Set Target Reference Design' 
% task in Workflow Advisor. Use property name 
% 'PostTargetReferenceDesignFcn'.
hRD.PostTargetReferenceDesignFcn = ...
    @my_reference_design.callback_PostTargetReferenceDesign;

% Specify an optional callback for 'Set Target Interface' task in Workflow Advisor.
% Use the property name 'PostTargetInterfaceFcn'.
hRD.PostTargetInterfaceFcn     = ... 
    @my_reference_design.callback_PostTargetInterface;

% Specify an optional callback for 'Create Project' task
% Use the property name 'PostCreateProjectFcn' for the ref design object.
hRD.PostCreateProjectFcn       = ... 
    @my_reference_design.callback_PostCreateProject;

% Specify an optional callback for 'Generate Software Interface Model' task
% Use the property name 'PostSWInterfaceFcn' for the ref design object.
hRD.PostSWInterfaceFcn         = ...
    @my_reference_design.callback_PostSWInterface;

% Specify an optional callback for 'Build FPGA Bitstream' task
% Use the property name 'PostBuildBitstreamFcn' for the ref design object.
hRD.PostBuildBitstreamFcn      = ...
    @my_reference_design.callback_PostBuildBitstream;

% Specify an optional callback for 'Program Target Device'
% task to use a custom programming method.
hRD.CallbackCustomProgrammingMethod = ...
    @my_reference_design.callback_CustomProgrammingMethod;

%% Add interfaces
% ...
% ...

Define Custom Parameters

With the addParameter method of the hdlcoder.ReferenceDesign class, you can define custom parameters. In the preceding example code, the reference design defines two custom parameters, DUT Path and Channel Mapping. To learn more about the addParameter method, see addParameter.

Specify Insertion of AXI Manager IP

By default, HDL Coder™ adds the Insert AXI Manager (HDL Verifier required) parameter to all reference designs. When you set this parameter to JTAG, the code generator inserts the JTAG AXI Manager IP into your reference design. When you set this parameter to Ethernet, the code generator inserts the UDP AXI Manager IP into your reference design.

Note

By default, the Ethernet option is available for only the Artix^®-7 35T Arty, Kintex^®-7 KC705, and Virtex^®-7 VC707 boards. To enable this option for other Xilinx^® boards that have the Ethernet physical layer (PHY), manually add the Ethernet media access controller (MAC) Hub IP in the plugin_board file using the addEthernetMACInterface method before you launch the HDL Workflow Advisor tool.

By using the AXI manager IP, you can easily access the AXI registers in the generated DUT IP core on a hardware board from MATLAB or Simulink^® through the JTAG or Ethernet connection. See also Set Up for AXI Manager (HDL Verifier).

To use this capability, you must have the HDL Verifier™ hardware support packages installed and downloaded. See Download FPGA Board Support Package (HDL Verifier).

The code generator adjusts the AXI4 Slave ID Width to accommodate the AXI manager IP connection. After you generate the HDL IP core and create the reference design project, you can open the Vivado^® block design to see the AXI manager IP inserted in the reference design.

In the previous example code, the reference design defines the AddMATLABAXIManagerParameter and MATLABAXIManagerDefaultValue properties of the hdlcoder.ReferenceDesign class. These properties control the default behavior of the Insert AXI Manager (HDL Verifier required) setting in the Set Target Reference Design task of the HDL Workflow Advisor. If you do not specify any of these properties in the hdlcoder.ReferenceDesign class, the Insert AXI Manager (HDL Verifier required) parameter is visible in the Set Target Reference Design task and the value is set to off. This example code illustrates the default behavior.

This property controls visibility of the Insert AXI Manager (HDL Verifier required) parameter in the Set Target Reference Design task of the HDL Workflow Advisor. By default, the property value is 'true', which means that the parameter is visible in the task. To disable the parameter, set this value to 'false'.

hRD.AddMATLABAXIManagerParameter = 'true';

This property controls the value of the Insert AXI Manager (HDL Verifier required) parameter in the Set Target Reference Design task. By default, the property value is 'off', which means that the parameter is visible in the task and the value is off. To enable automatic insertion of AXI manager IP in the reference design, set this value to 'JTAG' or 'Ethernet'. In that case, you must set the AddMATLABAXIManagerParameter to 'true'.

hRD.MATLABAXIManagerDefaultValue = 'off';

For examples, see:

• Using JTAG MATLAB as AXI Master to control the HDL Coder IP Core

• Access DUT Registers on Xilinx Pure FPGA Board Using IP Core Generation Workflow

Run IP Core Generation Workflow

When you open the HDL Workflow Advisor, HDL Coder populates the Set Target Reference Design task with the reference design name, tool version, custom parameters that you specified, and the Insert AXI Manager (HDL Verifier required) option set to JTAG.

HDL Coder then passes these parameter values to the callback functions in the input structure.

If your synthesis tool is Xilinx Vivado, HDL Coder sets the reference design parameter values to variables. The variables are then input to the block design Tcl file. This code snippet is an example from the reference design project creation Tcl file.

update_ip_catalog
set DutPath {Rx}
set ChannelMapping {1}
source vivado_custom_block_design.tcl

The code shows how HDL Coder sets the reference design parameters before sourcing the custom block design Tcl file.

Register Callback Function Handles

In the reference design definition, you can register the function handle to reference the custom callback functions. You then can:

• Enable custom validations.

• Customize the reference design dynamically.

• Customize the reference design project creation settings.

• Change the generated software interface model.

• Customize the FPGA bitstream build process.

• Specify custom FPGA programming method.

With the hdlcoder.ReferenceDesign class, you can define callback property names. The callback properties have a naming convention. The callback functions can have any name. In the HDL Workflow Advisor, you can define callback functions to customize these tasks.

Workflow Advisor Task	Callback Property Name	Functionality
Set Target Reference Design	CustomizeReferenceDesignFcn PostTargetReferenceDesignFcn	CustomizeReferenceDesignFcn enables customization of the reference design dynamically. By using this callback function, you can customize the block design Tcl file, reference design interfaces, reference design interface properties, and IP repositories in your reference design. See Customize Reference Design Dynamically Based on Reference Design Parameters. PostTargetReferenceDesignFcn enables custom validations. For an example that shows how you can validate that the Reset type is Synchronous, see PostTargetReferenceDesignFcn.
Set Target Interface	PostTargetInterfaceFcn	Enable custom validations. For an example that shows how you can validate not choosing a certain interface for a certain custom parameter setting, see PostTargetInterfaceFcn.
Create Project	PostCreateProjectFcn	Specify custom settings when HDL Coder creates the project. For an example, see PostCreateProjectFcn.
Generate Software Interface	PostSWInterfaceFcn	Change the generated software interface model. For an example, see PostSWInterfaceFcn.
Build FPGA Bitstream	PostBuildBitstreamFcn	Specify custom settings when you build the FPGA bitstream. When you use this function, the build process cannot be run externally. You must run the build process within the HDL Workflow Advisor by clearing the Run build process externally check box in the Build FPGA Bitstream task. For an example, see PostBuildBitstreamFcn.
Program Target Device	CallbackCustomProgrammingMethod	Specify a custom FPGA programming method. For an example, see CallbackCustomProgrammingMethod.

Define Custom Callback Functions

1. For each of the callback function that you want HDL Coder to execute after running a task, create a file that defines a MATLAB function with any name.

2. Make sure that the callback function has the documented input and output arguments.

3. Verify that the functions are accessible from the MATLAB path.

4. Register the function handle of the callback functions in the reference design definition function.

5. Follow the naming conventions for the callback property names.

To learn more about these callback functions, see hdlcoder.ReferenceDesign.