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:
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 |
|
|
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
|
Create Project | PostCreateProjectFcn | Specify custom settings when HDL Coder creates the project. For an example, see
|
Generate Software Interface | PostSWInterfaceFcn | Change the generated software interface model. For
an example, see |
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 |
Program Target Device | CallbackCustomProgrammingMethod | Specify a custom FPGA programming method. For an
example, see |
Define Custom Callback Functions
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.
Make sure that the callback function has the documented input and output arguments.
Verify that the functions are accessible from the MATLAB path.
Register the function handle of the callback functions in the reference design definition function.
Follow the naming conventions for the callback property names.
To learn more about these callback functions, see hdlcoder.ReferenceDesign
.
See Also
hdlcoder.Board
| hdlcoder.ReferenceDesign
Related Examples
- Register a Custom Board
- Register a Custom Reference Design
- Define Custom Board and Reference Design for Zynq Workflow
- Define Custom Board and Reference Design for Intel SoC Workflow