Buffer Index Calculation Code Replacement

This example shows how to develop a code replacement library to optimize the performance of the buffer index calculation for a Delay block. Optimize the buffer index calculation by defining a code replacement for the circular index calculation function. To develop a code replacement library, use either the interactive or programmatic approach. For more information, see Develop a Code Replacement Library.

Interactively Develop a Code Replacement Library

Open the Code Replacement Tool (crtool). At the MATLAB command line, enter:
```
>>crtool
```
Create a table.
1. From the crtool context menu, select File > New Table.
2. In the right pane, name the table crl_table_circularIndex. Click Apply.
Create an entry. From the crtool context menu, select File > New entry > Function.
Create entry parameters. In the Function drop-down list, select circularIndex.
Create the conceptual representation. The conceptual representation describes the signature of the function that you want to replace. In the Conceptual function subsection of the crtool, specify the return argument, y1, and the input arguments, u1, u2, and u3, that use the Data Type of int32 and the Argument Type of Scalar.
Create the implementation representation. The implementation representation describes the signature of the optimization function. For this example, to specify that the implementation arguments have the same order and properties as the conceptual arguments, select the Make conceptual and implementation argument types the same check box.
Specify the name of the replacement function. In the Replacement Function section, set Name to myCircularIndexFunc.
Specify build information. Click the Build Information tab to open the build requirements pane. Specify the files (source, header, object) that the code generator requires for code replacement. For this example, you do not need to specify build information.
Validate and save the table. Click the Mapping Information tab and verify that the fields are filled in as shown. Click Validate entry. In the crtool context menu, select File > Save table > Save.
Register a code replacement library. Registration creates a library composed of the tables that you specify. Select File > Generate registration file. In the Generate registration file dialog box, fill out these fields:
- Registry name — CRL for circular buffer index replacement
- Table list — crl_table_circularIndex
- Description — Example code replacement library
To use your code replacement library, refresh your current MATLAB session. At the command line, enter:
```
>>sl_refresh_customizations
```
Verify the code replacement library. At the MATLAB command line, open the library by using the Code Replacement Viewer and verify that the table and entry are correctly specified. For more information, see Verify Code Replacement Library. Configure your model to use the code replacement library, generate code, and verify that replacement occurs as expected. If unexpected behavior occurs, examine the hit and miss logs to troubleshoot the issues.

Programmatically Develop a Code Replacement Library

Open the programmatic interface from the MATLAB menu by selecting New > Function.
Create a table.
1. Create a function with the name of your code replacement library table that does not have arguments and returns a table object. You can use this function to call your code replacement library table.
2. Create a table object by calling RTW.TflTable.
```
function hTable = crl_table_circularIndex()
% Create a function to call the code replacement library table 

%% Create a table object
hTable = RTW.TflTable;
```

Create an entry. Because this example replaces a function, create a code replacement entry in your table by calling the entry function RTW.TflCFunctionEntry.

function hTable = crl_table_circularIndex()
% Create a code replacement library table 

%% Create a table object
hTable = RTW.TflTable;

%% Create an entry
hEntry = rtw.TflCFunctionEntry;

Create entry parameters. Because this example replaces a function, create entry parameters by calling the function setTflCFunctionEntryParameters.

function hTable = crl_table_circularIndex()
% Create a code replacement library table 

%% Create a table object
hTable = RTW.TflTable;

%% Create an entry 
hEntry = RTW.TflCFunctionEntry;

%% Create entry parameters
hEntry.setTflCFunctionEntryParameters(...
        'Key',                         'circularIndex', ...
        'Priority',                    30, ...
        'ImplementationName',          'myCircularIndexFunc');

Create the conceptual representation. The conceptual representation describes the signature of the function that you want to replace. To explicitly specify argument properties, call the function createAndAddConceptualArg.

function hTable = crl_table_circularIndex()
% Create a code replacement library table 

%% Create a table object
hTable = RTW.TflTable;

%% Create an entry 
hEntry = RTW.TflCFunctionEntry;

%% Create entry parameters
hEntry.setTflCFunctionEntryParameters(...
        'Key',                         'circularIndex', ...
        'Priority',                    30, ...
        'ImplementationName',          'myCircularIndexFunc');

%% Create the conceptual representation
hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'y1',...
        'IOType',                 'RTW_IO_OUTPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u1', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u2', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u3', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

Create the implementation representation. The implementation representation describes the signature of the optimization function. To specify that the implementation arguments have the same order and properties as the conceptual arguments, call the function copyConceptualArgsToImplementation. Add the complete entry to the table by calling the function addEntry.

function hTable = crl_table_circularIndex()
% Create a code replacement library table 

%% Create a table object
hTable = RTW.TflTable;

%% Create an entry 
hEntry = RTW.TflCFunctionEntry;

%% Create entry parameters
hEntry.setTflCFunctionEntryParameters(...
        'Key',                         'circularIndex', ...
        'Priority',                    30, ...
        'ImplementationName',          'myCircularIndexFunc');

%% Create the conceptual representation
hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'y1',...
        'IOType',                 'RTW_IO_OUTPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u1', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u2', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

hEntry.createAndAddConceptualArg(...
        'RTW.TflArgNumeric',      ...
        'Name',                   'u3', ...
        'IOType',                 'RTW_IO_INPUT',...
        'DataTypeMode',           'int32');

%% Create the Implementation Representation
copyConceptualArgsToImplementation(hEntry);

%% Add the entry to the table
hTable.addEntry(hEntry);

Specify build information. In the entry parameters, specify files (header, source, object) that the code generator requires for code replacement. For this example, build information is not required.
Validate and save the customization file. From the MATLAB menu, save this customization file by selecting File > Save. At the command line, validate the code replacement library table by calling it:
```
>> hTable = crl_table_circularIndex
```

Register the code replacement library. Registration creates a code replacement library by defining the library name, code replacement tables, and other information. Create a registration file (a new function file) by using these specifications:

function rtwTargetInfo(cm)
 
cm.registerTargetInfo(@loc_register_crl);
end
 
function this = loc_register_crl 
 
this(1) = RTW.TflRegistry; 
this(1).Name = 'CRL for circular index calculation replacement';
this(1).TableList = {'crl_table_circularIndex.m'}; % table created in this example
this(1).TargetHWDeviceType = {'*'};
this(1).Description = 'Example code replacement library';

end

To use your code replacement library, refresh your current MATLAB session. At the command line, enter:

>>sl_refresh_customizations

Verify the code replacement library. At the MATLAB command line, open the library by using the Code Replacement Viewer and verify that the table and entry are correctly specified. For more information, see Verify Code Replacement Library. Configure your model to use the code replacement library, generate code, and verify that replacement occurs as expected. If unexpected behavior occurs, examine the hit and miss logs to troubleshoot the issues.

Generate Code by Using Circular Index Code Replacement Library

Generate code by using the code replacement library that you previously created in this example. The code that calculates the circular index for a delay buffer is replaced with a call to a custom function in the generated code. This example does not provide an implementation function. Write your own implementation or use the target specific implementation.

Example Model

The example model contains a Delay block with these properties:

Delay length — Input port
Input processing — Columns as channels (frame-based)
Use circular buffer for state — On

Model containing delay block.

The Delay block receives a 32 by 2 data input signal and a scalar delay length input signal. To replace the buffer index calculation, for the Delay block, you must enable Use circular buffer for state enabled and use frame-based input processing. Frame-based input processing requires DSP System Toolbox™. For more information, see Sample- and Frame-Based Concepts (DSP System Toolbox).

Enable Code Replacement Library

Open the Configuration Parameters dialog box.
On the Interface pane, set Code Replacement Library by clicking Select. Add CRL for circular index calculation replacement to the Selected code replacement libraries - prioritized list pane. Alternatively, use the command-line API to enable the code replacement.
```
set_param('delayModel', 'CodeReplacementLibrary', 'CRL for circular index calculation');
```
Generate code from the model.

View the generated code. The portion of delayModel.c that calculates the buffer index uses the replacement function myCircularIndexFunc.

/* Update for Delay: '<Root>/Delay' incorporates:
 *  Inport: '<Root>/Input'
 */
currIdx = rtDW->CircBufIdx;
for (frameIdx = 0; frameIdx < 32; frameIdx++) {
  rtDW->Delay_DSTATE[currIdx] = rtInput[frameIdx];
  rtDW->Delay_DSTATE[currIdx + 200] = rtInput[frameIdx + 32];
  currIdx = myCircularIndexFunc(currIdx, 1, 200);
}

if (rtDW->CircBufIdx < 168) {
  rtDW->CircBufIdx += 32;
} else {
  rtDW->CircBufIdx -= 168;
}

/* End of Update for Delay: '<Root>/Delay' */