Customize Match and Replacement Process

During the build process, the code generator uses match criteria to identify functions and operators for which application-specific implementations replace default implementations. The build process uses replacement function signatures to call the replacement functions in the generated code. If the default match criteria or replacement function signatures do not meet your needs, you can add extra logic to the code replacement process by creating custom code replacement table entries. For example:

You want to replace an operator with a particular fixed-point implementation function only when fraction lengths are within a particular range.
When a match occurs, you want to modify your replacement function signature based on compile-time information, such as passing fraction-length values into the function.

With custom entries, you can specify additional match criteria that the base class does not provide. The base class provides a match based on:

Argument number
Argument name
Signedness
Word size
Slope (if not specified with wildcards)
Bias (if not specified with wildcards)
Math modes, such as saturation and rounding
Operator or function key

You can also use custom entries to modify the replacement function signature to meet application needs. You can:

Add additional arguments.
Set constant input argument values.
You can inject a constant value, such as an input scaling value, as an additional argument to the replacement function.

You can create custom code replacement entries for:

Functions — See Customize Code Match and Replacement for Functions.
Fixed-point operations — See Customize Code Match and Replacement for Fixed-Point Operations.
Matrix operations — See Customize Code Match and Replacement for Matrix Operations.

To create a custom code replacement entry:

Create a custom code replacement entry class, derived from RTW.TflCFunctionEntryML (for function replacement) or RTW.TflCOperationEntryML (for operator replacement).
In your derived class, implement a do_match method with a fixed preset signature as a MATLAB® function. In your do_match method, create a copy of an existing code replacement entry type and provide customizations on the copy.
Create code replacement entries that instantiate the custom entry class.
Register a library containing the code replacement table that includes your entries.

During code generation, the code replacement match process tries to match function or operator call sites with the base class of your derived entry class. If the process finds a match, the software calls your do_match method to execute your additional match logic (if any) and your replacement function customizations (if any).

Customize Code Replacement by Using the Code Replacement Tool

This example shows how to create a custom entry class and custom code replacement entry by using the Code Replacement Tool.

Open the tool. At the command line, enter crtool.

Create a table. In the toolstrip, select New > Table. In the right pane, name the table crl_table_custom. Click Apply.

Create a custom entry class. In the toolstrip, select Customize Code Replacement > Create. In the Create Custom Entry Class dialog box, specify these fields:

Namespace - CrlCustomEntry
Custom class name - CrlCustomFunctionEntry
Base entry type - RTW.TflCFunctionEntryML
Location - Specify the current folder.

Click OK. The tool creates the class file CrlCustomFunctionEntry.m in the namespace CrlCustomEntry. The class contains a do_match function that you use to define the custom entry information.

classdef CrlCustomFunctionEntry < RTW.TflCFunctionEntryML

    methods

        function ent = do_match(hThis, ...
                                hCSO, ... %#ok
                                targetBitPerChar, ... %#ok
                                targetBitPerShort, ... %#ok
                                targetBitPerInt, ... %#ok
                                targetBitPerLong ) %#ok
            % DO_MATCH - Create a custom match function. The base class
            % checks the types of the arguments prior to calling this
            % method. This will check additional data and perhaps modify
            % the implementation function.
            %

            ent = []; % default the return to empty indicating the match failed.

            %%------------------------------------------------------------
            %------------INSERT YOUR CODE HERE---------------------------







            %--------------------------------------------------------------

        end
    end
end

In the INSERT YOUR CODE HERE section, add code that creates a copy of a code replacement entry and specifies the customizations of that copy. For example, add this code and remove the comment blocks in the first and last lines.

%{
% Only use this sin function if the target int size is 32 bits
if targetBitPerInt == 32
    % Want to modify the default implementation. Need to create a copy first.
    % Want to create a regular CFunction Entry since we do not want to keep
    % adding an implementation arg on every query.
    ent = RTW.TflCFunctionEntry(hThis);
    
    % In this case, the implementation function takes flag
    % indicating degrees vs radians
    
    % The additional argument could be created either in the code replacement 
    % definition file or as follows:
    ent.createAndAddImplementationArg('RTW.TflArgNumericConstant', ...
        'Name','u2','Type','int32','Value',1);
end 
%}

This code specifies that the code replacement entry triggers replacement only if the integer size of the target is 32 bits. After adding the uncommented code to the do_match method, save the class.

classdef CrlCustomFunctionEntry < RTW.TflCFunctionEntryML

    methods

        function ent = do_match(hThis, ...
                                hCSO, ... %#ok
                                targetBitPerChar, ... %#ok
                                targetBitPerShort, ... %#ok
                                targetBitPerInt, ... %#ok
                                targetBitPerLong ) %#ok
            % DO_MATCH - Create a custom match function. The base class
            % checks the types of the arguments prior to calling this
            % method. This will check additional data and perhaps modify
            % the implementation function.
            %

            ent = []; % default the return to empty indicating the match failed.

            %%------------------------------------------------------------
            %------------INSERT YOUR CODE HERE---------------------------
            % Only use this sin function if the target int size is 32 bits    
            if targetBitPerInt == 32
                % Want to modify the default implementation. Need to create a copy first.
                % Want to create a regular CFunction Entry since we do not want to keep
                % adding an implementation arg on every query.
                ent = RTW.TflCFunctionEntry(hThis);
    
                % In this case, the implementation function takes flag
                % indicating degrees vs radians
    
                % The additional argument could be created either in the code replacement 
                % definition file or as follows:
                ent.createAndAddImplementationArg('RTW.TflArgNumericConstant', ...
                    'Name','u2','Type','int32','Value',1);
            end 
            %--------------------------------------------------------------

        end
    end
end

Create a code replacement entry by using the custom entry class. In the Code Replacement tool, select New > Custom Entry > CrlCustomEntry.CrlCustomFunctionEntry Entry. The list of available custom entries shows the custom entry classes that are available.

The new custom entry appears in the center pane. In the right pane, configure the entry by specifying information on the Mapping Information and Build Information tabs. For example, from the Function list, select sin. Specify the replacement function Name as my_sin_32. For this example, leave the other parameters and arguments with the default values.

Validate and save the table. Click Validate entry. Save the table by clicking Save.

Register the 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 out these fields:

Registry name - Custom Entries CRL
Table list - crl_table_custom.m
Base CRL - None
Target HW device - *
Description - Example code replacement library

Click OK. Refresh your current MATLAB session by using the command sl_refresh_customizations. Now the code replacement library is available for you to select in the model configuration parameters.

Customize Match and Replacement Process

Customize Code Replacement by Using the Code Replacement Tool

See Also

Topics