Memory Function Code Replacement
This example shows how to develop a code replacement library to optimize the
performance of memory functions by providing information on
how to define code replacement for a memcpy
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), from the MATLAB command line with the following command:
>>crtool
Create a table.
From the toolstrip of the Code Replacement tool, click New > Table.
In the right pane, name the table
crl_table_memcpy
. Click Apply.
Click New > Entry > Function Entry.
Create entry parameters. In the Function drop-down list, select
memcpy
.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 void and the Argument Type of Pointer, the input arguments,u1
andu2
with the Data Type of void and the Argument Type of Pointer andu3
with the Data Type of unsigned integer 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 a Name for the replacement function under Function prototype. For example, specify
memcpy_int
.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 memcpy replacement
Table list —
crl_table_memcpy
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.
Create a function to call your code replacement library table. The function should not have arguments and return a table object.
Create a table object by calling
RTW.TflTable
.
function hTable = crl_table_memcpy() % 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_memcpy() % Create a code replacement library table %% Create a table object hTable = RTW.TflTable; %% Create an entry hEntry = rtw.TflCFunctionEntry;
Create entry parameters. Because this examples replaces a function, create entry parameters by calling the function
setTflCFunctionEntryParameters
.function hTable = crl_table_memcpy() % Create a code replacement library table %% Create a table object hTable = RTW.TflTable; %% Create an entry hEntry = RTW.TflCFunctionEntry; %% Create entry parameters % Set SideEffects to 'true' for function returning void to prevent it from % being optimized away. hEntry.setTflCFunctionEntryParameters(... 'Key', 'memcpy', ... 'Priority', 90, ... 'ImplementationName', 'memcpy_int', ... 'ImplementationHeaderFile', 'memcpy_int.h',... 'SideEffects', true);
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 hTable = crl_table_memcpy() % Create a code replacement library table %% Create a table object hTable = RTW.TflTable; %% Create an entry hEntry = RTW.TflCFunctionEntry; %% Create entry parameters % Set SideEffects to 'true' for function returning void to prevent it from % being optimized away. hEntry.setTflCFunctionEntryParameters(... 'Key', 'memcpy', ... 'Priority', 90, ... 'ImplementationName', 'memcpy_int', ... 'ImplementationHeaderFile', 'memcpy_int.h',... 'SideEffects', true); %% Create conceptual arguments arg = getTflArgFromString(hTable, 'y1', 'void*'); arg.IOType = 'RTW_IO_OUTPUT'; addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u1', 'void*'); addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u2', 'void*'); addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u3', 'size_t'); 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 functionaddEntry
.function hTable = crl_table_memcpy() % Create a code replacement library table %% Create a table object hTable = RTW.TflTable; %% Create an entry hEntry = RTW.TflCFunctionEntry; %% Create entry parameters setTflCFunctionEntryParameters(hEntry, ... 'Key', 'memcpy', ... 'Priority', 90, ... 'ImplementationName', 'memcpy_int', ... 'ImplementationHeaderFile', 'memcpy_int.h',... 'SideEffects', true); %% Create conceptual arguments arg = getTflArgFromString(hTable, 'y1', 'void*'); arg.IOType = 'RTW_IO_OUTPUT'; addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u1', 'void*'); addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u2', 'void*'); addConceptualArg(hEntry, arg); arg = getTflArgFromString(hTable, 'u3', 'size_t'); addConceptualArg(hEntry, arg); %% 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 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 = crl_table_memcpy
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 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 memory function replacement'; this(1).TableList = {'crl_table_memcpy.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.