Verify Code Replacement Library

Step 4 of 5 in Develop a Code Replacement Library

Verify your code replacement library by examining its structure, replacement, and performance. Use the Code Replacement Viewer (crviewer) to verify the structure of your library. Use the code replacement report to verify the replacements made with your library in generated code. Use crviewer again to verify the performance of your library during code generation by examining the replacement hit and miss logs.

Verify Library Structure

Use the Code Replacement Viewer (crviewer) to open and view the structure of your code replacement library by examining its tables and table entries.

From the MATLAB^® command window, open your code replacement library using the crviewer with the command:
```
crviewer('library')
```
The viewer opens your code replacement library and shows its code replacement tables in the left pane. Verify that your library lists the required tables in the relative order.
Open and view the entries for each code replacement table. In the crtool, click each table listed in the left pane to view its entries in the middle pane.
If you are not using the crviewer, you can open each table directly from the MATLAB command prompt with the command:
```
crviewer(table)
```
For each table in your library, verify that it lists the required entries in the relative order. Verify that the conceptual representation and implementation representation are correct for each entry in the table.

Verify Library Replacement

Use the Code Replacements Report to verify that when the code generator uses your code replacement library it creates replacements as expected in the generated code. For each instance of replacement, the Code Replacements Report provides a mapping from the functions used from the selected code replacement library to the lines in the MATLAB code that triggered the replacement Use this mapping to verify code replacement by tracing between the report and the code in either direction (from report to code or code to report).

To generate the Code Replacements Report:

Configure your code generation project to use your code replacement library.
Configure your project to generate the Code Generation Report. The Code Replacements Report is a section within this report. In the code generation settings, in the Debugging pane, select:
- Always create a report
- Code replacements
- Automatically launch a report if one is generated
Configure the generated code to include comments. In the code generation settings, in the Code Appearance pane, select:
- Include comments
- Either or both of MATLAB source code as comments and MATLAB source code comment line numbers.
Generate the code. When the code generates, click View Report. On the bottom pane, click Code Replacements.
Verify that code replacements occur as expected. In the Code Replacements Report, click each code line link to see the source that triggered replacement.

Verify Library Performance

Verify the performance of your code replacement library by examining the hits and misses that occurred during code generation using your library. During code generation, when the code generator finds a match for code replacement from your code replacement library, it logs the hit in a hit cache. When it does not find a code replacement match, it logs the failed attempt in the miss cache. Each time that you generate code, the code generator overwrites its previous hit and miss cache logs.

To review trace information from the hit and miss cache data, use the Code Replacement Viewer (crviewer). From the hit cache, you can identify when code replacement occurred, and from the miss cache, you can troubleshoot when code replacement did not take place. The miss cache trace information provides you information about the reason for the miss, a link to the relevant source location for the miss, and the call site object of the miss. For more information, see Troubleshoot Code Replacement Misses.

Review Code Replacements

After you review the content of your code replacement library and tables, generate code and a code generation report. Verify that the code generator replaces code as you expect.

The Code Replacements Report details the code replacement library functions that the code generator uses for code replacements. The report provides a mapping between each replacement instance and the line of MATLAB code that triggered the replacement. The Code Replacements report is not available for generated MEX functions.

The following example illustrates two complementary approaches for reviewing code replacements:

Check the Code Replacements Report section of the code generation report for expected replacements.
Trace code replacements.

Identify the MATLAB function where you anticipate that a function or operator replacement occurs. This example uses this function:
```
function [y1, y2] = addsub_two_int16(u1, u2)

y1 = int16(u1 + u2);
y2 = int16(u1 - u2);
```
Identify or create code or a script to exercise the function. For example, consider test file addsub_to_int16_test.m, which includes the following code:
```
disp('Input')
u1 = int16(10)
u2 = int16(10)

[y1, y2] = addsub_two_int16(u1, u2);

disp('Output')
disp('y1 =')
disp(y1);
disp('y2 =')
disp(y2);
```
Open the MATLAB Coder™ app.
On the Select Source Files page, add your function to the project. For this example, add function addsub_two_int16. Click Next.
On the Define Input Types page, use the test file addsub_to_int16_test to automatically define the input types. Click Next.
On the Check for Run-Time Issues page, specify the test file addsub_to_int16_test. The app runs the test file, replacing calls to addsub_to_int16_test with calls to a MEX version of addsub_to_int16_test. Click Next.
To open the Generate dialog box, on the Generate Code page, click the Generate arrow .
Set Build type to generate source code. Before you build an executable, you want to review your code replacements in the generated code.
In the Generate dialog box, click More Settings.
Configure the code generator to use your code replacement library. On the Custom Code tab, set the Code replacement library parameter to the name of your library. For this example, set the library to Addition & Subtraction Examples.
Configure the code generation report to include the Code Replacements Report. On the Debugging tab, select:
- Always create a code generation report
- Code replacements
- Automatically launch a report if one is generated
To generate code and a report, set Build type to Source Code. Then, click Generate.
Open the Code Replacements Report section of the code generation report.
That report lists the replacement functions that the code generator used. The report provides a mapping between each replacement instance and the MATLAB code that triggered the replacement.
Review the report:
- Check whether expected function and operator code replacements occurred.
- In the replacements sections, click each code link to see the source that triggered the reported code replacement.

If a function or operator is not replaced as expected, the code generator used a higher-priority (lower-priority value) match or did not find a match.

To analyze and troubleshoot code replacement misses, use the trace information that the Code Replacement Viewer provides.