Quick Start Code Replacement Library Development - Simulink

This example shows how to develop a code replacement library that includes an entry for generating replacement code for the math function sin. You use the Code Replacement Tool.

Prerequisites

To complete this example, install the following software:

• MATLAB®

• MATLAB Coder™

• Simulink®

• Simulink Coder™

• Embedded Coder®

• Compiler

For instructions on installing MathWorks® products, see the MATLAB installation documentation. If you have installed MATLAB and want to see what other MathWorks products are installed, in the Command Window, enter ver.

For a list of supported compilers, see https://www.mathworks.com/support/compilers/current_release/.

Open the Code Replacement Tool

1. Start a MATLAB session.

2. Create or navigate (cd) to an empty folder.

3. At the command prompt, enter the crtool command. The Code Replacement Tool window opens.

Create Code Replacement Table

1. In the Code Replacement Tool window, select File > New table

2. In the right pane, name the table crl_table_sinfcn and click Apply. When you save the table, the tool saves it with the file name crl_table_sinfcn.m.

Create Table Entry

Create a table entry that maps a sin function with double input and double output to a custom implementation function.

1. In the left pane, select table crl_table_sinfcn. Then, select File > New entry > Function. The entry appears in the middle pane, initially without a name.

2. In the middle pane, select the new entry.

3. In the right pane, on the Mapping Information tab, from the Function menu, select sin.

4. Leave Algorithm set to Unspecified, and leave parameters in the Conceptual function group set to default values.

5. In the Replacement function group, name the replacement function sin_dbl.

6. Leave the remaining parameters in the Replacement function group set to default values.

7. Click Apply. The tool updates the Function signature preview to reflect the specified replacement function name.

8. Scroll to the bottom of the Mapping Information tab and click Validate entry. The tool validates your entry.

The following figure shows the completed mapping information.

Specify Build Information for Replacement Code

1. On the Build Information tab, for the Implementation header file parameter, enter sin_dbl.h.

2. Leave the remaining parameters set to default values.

3. Click Apply.

4. Optionally, you can revalidate the entry. Return to the Mapping Information tab and click Validate entry.

Create Another Table Entry

Create an entry that maps a sin function with single input and double output to a custom implementation function named sin_sgl. Create the entry by copying and pasting the sin_dbl entry.

1. In the middle pane, select the sin_dbl entry.

2. Select Edit > Copy.

3. Select Edit > Paste.

4. On the Mapping Information tab, in the Conceptual function section, set the data type of input argument u1 to single.

5. In the Replacement function section, name the function sin_sgl. Set the data type of input argument u1 to single.

6. Click Apply. Note the changes that appear for the Function signature preview.

7. On the Build Information tab, for the Implementation header file parameter, enter sin_sgl.h. Leave the remaining parameters set to default values and click Apply.

Validate the Code Replacement Table

1. Select Actions > Validate table.

2. If the tool reports errors, fix them, and rerun the validation. Repeat fixing and validating errors until the tool does not report errors. The following figure shows a validation report.

Save the Code Replacement Table

Save the code replacement table to a MATLAB file in your working folder. Select File > Save table. By default, the tool uses the table name to name the file. For this example, the tool saves the table in the file crl_table_sinfcn.m.

Review the Code Replacement Table Definition

Consider reviewing the MATLAB code for your code replacement table definition. After using the tool to create an initial version of a table definition file, you can update, enhance, or copy the file in a text editor.

To review it, in MATLAB or another text editor, open the file crl_table_sinfcn.m.

Generate a Registration File

Before you can use your code replacement table, you must register it as part of a code replacement library. Use the Code Replacement Tool to generate a registration file.

1. In the Code Replacement Tool, select File > Generate registration file.

2. In the Generate registration file dialog box, edit the dialog box fields to match the following figure, and click OK.

3. In the Select location to save the registration file dialog box, specify a location for the registration file. The location must be on the MATLAB path or in the current working folder. Save the file. The tool saves the file as rtwTargetInfo.m.

Register the Code Replacement Table

At the command prompt, enter:

RTW.TargetRegistry.getInstance('reset');

Review and Test Code Replacements

Apply your code replacement library. Verify that the code generator makes code replacements that you expect.

1. Check for errors. At the command line, invoke the table definition file. For example:

tbl = crl_table_sinfcn

tbl =

TflTable with properties:

               Version: '1.0'
       ReservedSymbols: []
   StringResolutionMap: []
            AllEntries: [2x1 RTW.TflCFunctionEntry]
           EnableTrace: 1|

If an error exists in the definition file, the invocation triggers a message. Fix the error and try again.

2. Use the Code Replacement Viewer to check your code replacement entries. For example:

crviewer('Sin Function Example')

In the viewer, select entries in your table and verify that the content is what you expect. The viewer can help you detect issues such as:

• Incorrect argument order.

• Conceptual argument names that do not match what the code generator expects.

• Incorrect priority settings.

3. Identify existing model or create a model that includes a Trigonometric block that is set to the sin function. For example:

4. Open the model and configure it for code generation with an Embedded Coder (ERT-based) target.

5. See whether your library is listed as an available option for the Code Generation > Interface > Code replacement libraries model configuration parameter. If it is, select it.

If it is not listed, open the registration file, rtwTargetInfo.m. See whether you entered the correct code replacement table name when you created the file. If you hover the cursor over the selected library, a tool tip appears. This tip contains information derived from your code replacement library registration file, such as the library description and the list of tables it contains.

6. To find parameters quickly, in the Configuration Parameters dialog box Search field, type the parameter name. Configure the code generation report for code replacement analysis by selecting the following parameters:

• Create code generation report

• Open report automatically

• Code-to-model

• Model-to-code

• Summarize which blocks triggered code replacements

• Include comments

• Simulink block comments

• Simulink block descriptions

7. Configure the model to generate code only. Before you build an executable program, confirm that the code generator is replacing code as expected.

8. Generate code for the model.

9. Review code replacement results in the Code Replacement Report section of the code generation report.

The report indicates that the code generator found a match and applied the replacement code for the function sin_dbl.

10. Review the code replacements. In the model window, right-click the Trigonometric Function block. Select C/C++ Code > Navigate to C/C++ Code. The code generation report opens and highlights the code replacement in my_sin_func.c. In this case, the code generator replaced sin with sin_dbl.

More About

• Code You Can Replace From Simulink Models

• Develop a Code Replacement Library

• What Is Code Replacement Customization?

Related Topics

• Code You Can Replace From Simulink Models
• Develop a Code Replacement Library
• What Is Code Replacement Customization?