Customize Reference Design Dynamically Based on Reference Design Parameters

When you define your own custom reference design, you can dynamically customize the reference design by using the CustomizeReferenceDesignFcn method of the hdlcoder.ReferenceDesign class.

Why Customize the Reference Design

By customizing the reference design parameters, instead of maintaining separate reference designs that have different interface choices, data widths, or I/O plugins, create one reference design that has different interface choices or data widths as parameters. You can then use the CustomizeReferenceDesignFcn method to reference the callback function that has different choices for interfaces or data widths.

For example, instead of creating separate reference designs that have different data widths for the interfaces, you can parameterize the data width and then create a reference design parameter. When you run the IP Core Generation workflow, you can use the parameter to select the data width that you want to use. Similarly, instead of using multiple reference designs, you can create one reference design that has only AXI4-Stream Master or only AXI4-Stream Slave or both AXI4-Stream Master and AXI4-Stream Slave interfaces.

How Reference Design Customization Works

To define the callback function:

In the plugin_rd file, define the reference design parameters you want to customize by using the addParameter method.
Create a MATLAB^® file that defines the callback function. You can use any arbitrary name for the callback function.
Save the callback function in the same folder as the plugin_rd.m file.
Register the function handle of the callback function in the reference design definition plugin_rd file by using the CustomizeReferenceDesignFcn method.

To use the different reference design customizations:

Open the HDL Workflow Advisor. In the Set Target Device and Synthesis Tool task, select IP Core Generation as the Target workflow and then select the target board for which you created your own custom reference design as the Target platform.
In the Set Target Reference Design task, when you select the custom reference design that you want to customize for the target board, HDL Coder™ populates the reference design parameters. Depending on the parameter choices such as the interface types you specify, the callback function is evaluated. Run this task.
Select the Set Target Interface task. Depending on the parameter you selected in the previous step, the target interface selection is populated in the Target platform interface table.

Customizable Reference Design Parameters

In the callback function, you can customize these reference design parameters. Do not specify these parameters in the plugin_rd file.

Block design Tcl file

% ...

% if ~isempty(ParamValue)
    hRD.addCustomVivadoDesign( ...
            'CustomBlockDesignTcl', 'system_top.tcl', ...
            'VivadoBoardPart',      'xilinx.com:zc706:part0:1.0'};

% ...

Reference design interfaces and reference design interface properties

For example, you can parameterize the data width of the AXI4-Stream Master Channel. In this case, use the addAXI4StreamInterface method in the callback function instead of the plugin_rd file.

% ...

% Add AXI4-Stream interface by parameterizing data width
DataWidth = hRD.getParamValue(paramValue)
                 
if ~isempty(DataWidth)
   hRD.addAXI4StreamInterface( 
    'MasterChannelEnable',     'true', ...
    'SlaveChannelEnable',      'true', ...
    'MasterChannelConnection', 'ByPass_0.AXI4_Stream_Slave', ...
    'SlaveChannelConnection',  'ByPass_0.AXI4_Stream_Master', ...
    'MasterChannelDataWidth',   DataWidth, ...
    'SlaveChannelDataWidth',    DataWidth);
end

% ...

IP repositories

In the callback function, you must specify the block design Tcl file when you add IP repositories.

% ...

%% Add IP Repository
hRD.addIPRepository(...
    'IPListFunction', 'mathworks.hdlcoder.vivado.hdlcoder_video_iplist',
		 'NotExistMessage', 'IP repository not found');

%% Add custom design files
hRD.addCustomVivadoDesign( ...
    'CustomBlockDesignTcl', 'system_top.tcl', ...
    'VivadoBoardPart',      'em.avnet.com:zed:part0:1.0');


% ...

Note

You cannot modify the reference design name, board name, and supported tool versions in the callback function. These parameters are used in the Set Target Device and Synthesis Tool task before the callback function is evaluated when the target reference design is selected in the Set Target Reference Design task.

Example: Create Master Only or Slave Only or Both Slave and Master Reference Designs

Instead of using multiple reference designs, you can create one reference design that has only AXI4-Stream Master or only AXI4-Stream Slave or both AXI4-Stream Master and AXI4-Stream Slave interfaces. This example shows how you can customize the AXI4-Stream interface channels you want to use when targeting your own reference design for the Xilinx Zynq ZC706 evaluation kit.

This code shows the reference design parameter and interface choices for the reference design my_reference_design specified by using the addParameter method in the plugin_rd file. The CustomizeReferenceDesignFcn method references a callback function that has the name customcallback_axistreamchannel.

function hRD = plugin_rd()
% Reference design definition

%   Copyright 2017-2019 The MathWorks, Inc.

% Construct reference design object
hRD = hdlcoder.ReferenceDesign('SynthesisTool', 'Xilinx Vivado');

hRD.ReferenceDesignName = 'Vivado Custom Reference Design';
hRD.BoardName = 'Xilinx Zynq ZC706 evaluation kit';

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

% ...
% ...

% Parameter For  calling AXI4 Master 
interface from Callback function
hRD.addParameter ...
('ParameterID'    ,  'stream_channel', ...
 'DisplayName'    ,  'Stream Channel', ...
 'DefaultValue'   ,  'Both Master and Slave',...
 'ParameterType'  ,   hdlcoder.ParameterType.Dropdown, ...
 'Choice'         ,   {'Both Master and Slave','Master Only','Slave Only'});

% Reference the callback function.
hRD.CustomizeReferenceDesignFcn = @my_reference_design.customcallback_axistreamchannel;

% ...

When you create the callback function, pass the infoStruct argument to the function. The argument contains the reference design and board information in a structure format. This code shows the callback function customcallback_axistreamchannel that has the AXI4-Stream Master or Slave Channels or both channels specified by using the addAXI4StreamInterface method.

% Control AXI Master or Slave channel selection by using callback function

function customcallback_axistreamchannel(infoStruct)
%% Reference design callback run at the end of the task Set Target Reference Design
%
% infoStruct: information in structure format
% infoStruct.ReferenceDesignObject: current reference design registration object
% infoStruct.BoardObject: current board registration object
% infoStruct.ParameterStruct: custom parameters of the current reference design, in struct format
% infoStruct.HDLModelDutPath: the block path to the HDL DUT subsystem
% infoStruct.ReferenceDesignToolVersion: Reference design Tool Version set in 1.2 Task

paramStruct = infoStruct.ParameterStruct;

if ~isempty(paramStruct)
    paramIDCell = fieldnames(paramStruct);
    paramValue = '';
    for ii = 1:length(paramIDCell)
        paramID = paramIDCell(ii);
        if strcmp(paramID,'Both Master and Slave')
            paramValue = paramStruct.paramID;
            break;
        elseif strcmp(paramID,'Master Only')
            paramValue = paramStruct.paramID;
            break;
        elseif strcmp(paramID,'Slave Only')
            paramValue = paramStruct.paramID;
            break;
        end
    end
end
interface_type = str2double(paramValue);

if ~isempty(interface_type)

    if strcmp(interface_type, 'Both Master and Slave')

        % add custom vivado design
        hRD.addCustomVivadoDesign( ...
            'CustomBlockDesignTcl', 'system_top.tcl', ...
            'VivadoBoardPart',      'xilinx.com:zc706:part0:1.0');

        hRD.addAXI4StreamInterface( ...
            'MasterChannelEnable',      'true', ...
            'SlaveChannelEnable',       'true', ...
            'MasterChannelConnection',  'axi_dma_s2mm/S_AXIS_S2MM', ...
            'SlaveChannelConnection',   'axi_dma_mm2s/M_AXIS_MM2S', ...
            'MasterChannelDataWidth',   32, ...
            'SlaveChannelDataWidth',    32);

    elseif strcmp(interface_type, 'Master Only')

        % add custom vivado design
        hRD.addCustomVivadoDesign( ...
            'CustomBlockDesignTcl', 'system_top.tcl', ...
            'VivadoBoardPart',      'xilinx.com:zc706:part0:1.0');

        hRD.addAXI4StreamInterface( ...
            'MasterChannelEnable',      true, ...
            'MasterChannelConnection',  'axi_dma_s2mm/S_AXIS_S2MM', ...
            'MasterChannelDataWidth',   32);


    % ...

Save the callback function in the same folder as the plugin_rd file.

When you run the IP Core Generation workflow with Xilinx Zynq ZC706 evaluation kit as the Target platform, you see the parameter Stream Channel displayed in the Set Target Reference Design task.

You can specify the reference design type you want to use and then run the workflow to specify the target platform interfaces and then generate the HDL IP core and then integrate the IP core into the reference design.

Related Examples

More About

Board and Reference Design Registration System