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 JTAG AXI Manager IP Insertion. The IP
% insertion setting is visible in the 'Set Target Reference Design'
% task of the HDL Workflow Advisor. By default, the
% AddJTAGMATLABasAXIMasterParameter property is set to 'true'.
hRD.AddJTAGMATLABasAXIMasterParameter = 'true';
hRD.JTAGMATLABasAXIMasterDefaultValue = 'on';


%% 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 JTAG AXI Manager IP

By default, HDL Coder™ adds a parameter Insert JTAG AXI Manager (HDL Verifier required) to all reference designs. When you set this parameter to on, the code generator automatically inserts the JTAG AXI Manager IP into your reference design. By using the JTAG AXI Manager IP, you can easily access the AXI registers in the generated DUT IP core on an FPGA board from MATLAB through the JTAG 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 JTAG AXI Manager IP inserted in the reference design.

In the previous example code, the reference design defines the AddJTAGMATLABasAXIMasterParameter and JTAGMATLABasAXIMasterDefaultValue properties of the hdlcoder.ReferenceDesign class. These properties control the default behavior of the Insert JTAG 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 JTAG AXI Manager (HDL Verifier required) parameter is displayed in the Set Target Reference Design task and the value is set to off. This example code illustrates the default behavior.

%% Default behavior of Insert JTAG AXI Manager option

% This parameter controls visibility of the option in 
% 'Set Target Reference Design Task' of HDL Workflow Advisor
% By default, the parameter value is set to 'true',
% which means that the option is displayed in the UI. If
% you do not want the parameter to be displayed, set this
% value to 'false'.
hRD.AddJTAGMATLABasAXIMasterParameter = 'true';

% This parameter controls the value of the option in the
% the 'Set Target Reference Design Task' task. By default,
% the value is 'off', which means that the parameter is
% displayed in the task and the value is off. To enable
% automatic insertion of JTAG AXI Manager IP in the reference
% design, set this value to 'on'. In that case, the 
% AddJTAGMATLABasAXIMasterParameter must be set to 'true'.
hRD.JTAGMATLABasAXIMasterDefaultValue = '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 JTAG AXI Manager (HDL Verifier required) option set to on.

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.