Replace Addition and Subtraction Operator Code

This example shows how to develop a code replacement library to optimize the performance of addition and subtraction operators by providing information on how to define code replacement for a addition operator. To develop a code replacement library use either the interactive or programmatic approach. When you replace an addition or subtraction operator, your library function algorithm must match the algorithm type of the operator that you want to replace. For more information, see Addition and Subtraction Algorithm Types for Code Replacement.

Interactively Develop a Code Replacement Library

Open the Code Replacement Tool (crtool), from the MATLAB command line with the following command:
```
>>crtool
```
Create a table.
1. From the toolstrip of the Code Replacement tool, click New > Table.
2. In the right pane, name the table crl_table_addition. Click Apply.
Create an entry. Click New > Entry > Math Operation Entry.
Create entry parameters. In the Function drop-down list, select Addition. Algorithm information appears in the crtool. For this example, set the parameter to Cast before operation.
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, with the Data Type of uint8 and the Argument Type of Scalar, the input arguments, u1 and u2 with the Data Type of uint16 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 for the replacement function as u8_add_cbo_u16_u16.
Specify the Integer saturation mode as Saturate on Overflow.
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 the fields are filled in as shown. Click Apply, then click Validate entry. On the toolstrip, click Save and save the table.
Register a code replacement library. Registration creates a library composed of the tables that you specify. Click Generate Registration File. In the Generate registration file dialog box, fill in these fields:
- Registry name — CRL for addition operator replacement
- Table list — crl_table_addition
- Base CRL — None
- Target HW device — *
- Description — Example code replacement library
Click OK. To use your code replacement library, refresh your current MATLAB session with the command:
```
>>sl_refresh_customizations
```
Verify the code replacement library. From 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 hTflTable = make_cbo_add_crl_table
% Create a function to call the code replacement library table 

%% Create a table object
hTflTable = 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.TflCOperationEntry.

function hTflTable = make_cbo_add_crl_table
% Create a function to call the code replacement library table 

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

%% Create an entry
hEntry = RTW.TflCOperationEntry;

Create entry parameters. Because this examples replaces a function, create entry parameters by calling the function setTflCOperationEntryParameters.

function hTflTable = make_cbo_add_crl_table
% Create a function to call the code replacement library table 

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

%% Create an entry
hEntry = RTW.TflCOperationEntry;


%% Create entry parameters
hEntry.setTflCOperationEntryParameters(...
                   'Key',                      'RTW_OP_ADD', ...
                   'EntryInfoAlgorithm',       'RTW_CAST_BEFORE_OP', ...
                   'ImplementationName',       'u8_add_cao_u16_u16');

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 getTflArgFromString.

function hTflTable = make_cbo_add_crl_table
% Create a function to call the code replacement library table 

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

%% Create an entry
hEntry = RTW.TflCOperationEntry;


%% Create entry parameters
hEntry.setTflCOperationEntryParameters(...
                   'Key',                      'RTW_OP_ADD', ...
                   'EntryInfoAlgorithm',       'RTW_CAST_BEFORE_OP', ...
                   'ImplementationName',       'u8_add_cao_u16_u16');

%% Create the conceptual representation
arg = getTflArgFromString(hTflTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEntry, arg);

arg = getTflArgFromString(hTflTable, 'u1', 'uint16');
addConceptualArg(hEntry, arg );

arg = getTflArgFromString(hTflTable, 'u2', 'uint16');
addConceptualArg(hEntry, arg );

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 hTflTable = make_cbo_add_crl_table()
% Create a function to call the code replacement library table 

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

%% Create an entry
hEntry = RTW.TflCOperationEntry;


%% Create entry parameters
hEntry.setTflCOperationEntryParameters(...
                   'Key',                      'RTW_OP_ADD', ...
                   'EntryInfoAlgorithm',       'RTW_CAST_BEFORE_OP', ...
                   'ImplementationName',       'u8_add_cao_u16_u16');

%% Create the conceptual representation
arg = getTflArgFromString(hTflTable, 'y1', 'uint8');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEntry, arg);

arg = getTflArgFromString(hTflTable, 'u1', 'uint16');
addConceptualArg(hEntry, arg );

arg = getTflArgFromString(hTflTable, 'u2', 'uint16');
addConceptualArg(hEntry, arg );

%% Create the Implementation Representation
copyConceptualArgsToImplementation(hEntry);

%% Add the entry to the table
addEntry(hTflTable, hEntry);

Specify build information. In the entry parameters, specify files (header, source, object) that the code generator needs 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. From the command line, validate the code replacement library table by calling it:
```
>> hTable = make_cbo_add_crl_table
```

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) with 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 addition subtraction operator replacement';
this(1).TableList = {'make_cbo_add_crl_table.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 with the command:

>>sl_refresh_customizations

Verify the code replacement library. From 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 Using Addition and Subtraction Operator Code Replacement Library

Open Script

In this section, you generate code using the code replacement library that you created in the first two sections of this example. The generated code contains the implementation function signature that modifies an addition operator. For this example, the addition operator contains the Cast before operation parameter. This example does not provide an implementation function. You should write the implementation function that contains the optimization that you want to see in the generated code.

Example Model

Open the model crl_AddSubfunction for configuring the code replacement library.

crl_AddSubfunction

copyfile AddSubFnRtwTargetInfo.txt rtwTargetInfo.m

The input ports are of data type uint16 and the output port is of data type uint8. For the Add block, the Accumulator data type is set to uint8. Based on these data types, the addition is a cast-before-operation algorithm.

To create a code replacement table and register the file, run the MATLAB customization file. For this example, the customization file has already been executed. To register the library, run the sl_refresh_customizations function.

sl_refresh_customizations;

Enable Code Replacement Library

Open the Configuration Parameters dialog box.
On the Interface pane, set Code Replacement Library. Click Select and add CRL for Addition and Subtraction operator replacement to the Selected code replacement libraries - prioritized list pane. Alternatively, use the command-line API to enable the code replacement:

set_param('crl_AddSubfunction', 'CodeReplacementLibrary', 'CRL for Addition and Subtraction operator replacement');

Generate code from the model:

evalc('slbuild(''crl_AddSubfunction'')');

View the generated code. Here is a portion of crl_AddSubfunction.c.

cfile = fullfile('crl_AddSubfunction_ert_rtw','crl_AddSubfunction.c');
coder.example.extractLines(cfile,'/* Model step function ','/* Model initialize function',1, 1);

/* Model step function */
void crl_AddSubfunction_step(void)
{
  /* Outport: '<Root>/Out1' incorporates:
   *  Inport: '<Root>/In1'
   *  Inport: '<Root>/In2'
   *  Sum: '<Root>/Add8'
   */
  crl_AddSubfunction_Y.Out1 = u8_add_cbo_u16_u16(crl_AddSubfunction_U.In1,
    crl_AddSubfunction_U.In2);
}

The + operator can be replaced with your custom implementation.

Close the model.

delete ./rtwTargetInfo.m
bdclose('crl_AddSubfunction');