Traceability Report

Traceability Report Overview

Even a relatively small model can generate hundreds of lines of HDL code. The HDL Coder™ software provides the traceability report section to help you navigate more easily between the generated code and your source model. When you enable traceability, HDL Coder creates and displays an HTML code generation report. You can generate reports from the Configuration Parameters dialog box or the command line. A typical traceability report looks something like this:

The traceability report has several subsections:

The Traceability Report lists Traceable Simulink Blocks / Stateflow Objects / MATLAB Functions, providing a complete mapping between model elements and code. The Eliminated / Virtual Blocks section of the report accounts for blocks that are untraceable.
The Generated Source Files table contains hyperlinks that let you view generated HDL code in a MATLAB^® web browser window. This view of the code includes hyperlinks that let you view the blocks or subsystems from which the code was generated. You can click the names of source code files generated from your model to view their contents in a MATLAB web browser window. The report supports two types of linkage between the model and generated code:
- Code-to-model hyperlinks within the displayed source code let you view the blocks or subsystems from which the code was generated. Click the hyperlinks to view the relevant blocks or subsystems in a Simulink^® model window.
- Model-to-code linkage lets you view the generated code for any block in the model. To highlight a block's generated code in the HTML report, right-click the block and select HDL Code > Navigate to Code.

Note: If your model includes blocks that have requirements comments, you can also render the comments as hyperlinked comments within the HTML code generation report. See Requirements Comments and Hyperlinks for more information.

In the following sections, the mcombo example model illustrates stages in the workflow for generating code generation reports from the Configuration Parameters dialog box and from the command line.

To open the model, enter:

mcombo

The root-level mcombo model appears as follows:

HDL Coder supports report generation for models, subsystems, blocks, Stateflow^® charts, and MATLAB Function blocks. This example uses the combo subsystem, shown in the following figure. The combo subsystem includes a Stateflow chart, a MATLAB Function block, and a subsystem.

Generating a Traceability Report from Configuration Parameters

To generate a HDL Coder code generation report from the Configuration Parameters dialog box:

Verify that the model is open.
Open the Configuration Parameters dialog box and navigate to the HDL Code Generation pane.
To enable report generation, select Generate traceability report.
If your model includes blocks that have requirements comments, you can also select Include requirements in block comments in the HDL Code Generation > Global Settings > Coding style pane to render the comments as hyperlinked comments in the HTML code generation report. See Requirements Comments and Hyperlinks for more information.
Verify that Generate HDL for specifies the correct DUT for HDL code generation. You can generate reports for the root-level model or for subsystems, blocks, Stateflow charts, or MATLAB Function blocks.
Click Apply.
Click Generate to initiate code and report generation.
When you select Generate traceability report, HDL Coder generates HTML report files as part of the code generation process. Report file generation is the final phase of that process. As code generation proceeds, the coder displays progress messages. The process completes with messages similar to the following:
```
### Generating HTML files for traceability in slprj\hdl\mcombo\html directory ...

### HDL Code Generation Complete.
```
When code generation is complete, the HTML report appears in a new window:

To view the different report sections or view the generated code files, click the hyperlinks in the Contents pane of the report window.

Tip HDL Coder writes the code generation report files to a folder in the hdlsrc\html\ folder of the build folder. The top-level HTML report file is named system_codegen_rpt.html, where system is the name of the model, subsystem, or other component selected for code generation. However, because the coder automatically opens this file after report generation, you do not need to access the HTML files directly. Instead, navigate the report using the links in the top-level window.

For more information on using the report you generate for tracing, see:

Generating a Traceability Report from the Command Line

To generate a HDL Coder code generation report from the command line:

Open your model by entering:
```
open_system('model_name');
```
Specify the desired device under test (DUT) for code generation by entering:
```
gcb = 'path_to_DUT';
```
You can generate reports for the root-level model or for subsystems, blocks, Stateflow charts, or MATLAB Function blocks. If you do not specify a subsystem, block, Stateflow chart, or MATLAB Function block, HDL Coder generates a report for the top-level model.
Enable the makehdl property Traceability by entering:
```
makehdl(gcb,'Traceability','on');
```
When you enable traceability, HDL Coder generates HTML report files as part of the code generation process. Report file generation is the final phase of that process. As code generation proceeds, the coder displays progress messages. The process completes with messages similar to the following:
```
### Generating HTML files for traceability in slprj\hdl\mcombo\html directory ...

### HDL Code Generation Complete.
```
When code generation is complete, the HTML report appears in a new window:

To view the different report sections or view the generated code files, click the hyperlinks in the Contents pane of the report window.

For more information on using the report you generate for tracing, see:

Keeping the Report Current

If you generate a code generation report for a model, and subsequently make changes to the model, the report might become invalid.

To keep your code generation report current, you should regenerate HDL code and the report after modifying the source model.

If you close and then reopen a model without making changes, the report remains valid.

Tracing from Code to Model

To trace from generated code to your model:

Generate code and open an HTML report for the desired DUT (see Generating a Traceability Report from Configuration Parameters or Generating a Traceability Report from the Command Line).
In the left pane of the HTML report window, click the desired file name in the Generated Source Files table to view a source code file.
The following figure shows a view of the source file Gain_Subsystem.vhd.
In the HTML report window, click a link to highlight the corresponding source block.
For example, in the HTML report shown in the previous figure, you could click the hyperlink for the Gain block (highlighted) to view that block in the model. Clicking the hyperlink locates and displays the corresponding block in the Simulink model window.

Tracing from Model to Code

Model-to-code traceability lets you select a component at any level of the model, and view the code references to that component in the HTML code generation report. You can select the following objects for tracing:

Subsystem
Simulink block
MATLAB Function block
Stateflow chart, or the following elements of a Stateflow chart:
- State
- Transition
- Truth table
- MATLAB function inside a chart

To trace a model component:

Generate code and open an HTML report for the desired DUT (see Generating a Traceability Report from Configuration Parameters or Generating a Traceability Report from the Command Line).
In the model window, right-click the component and select HDL Code > Navigate to Code.
Selecting Navigate to Code activates the HTML code generation report.
The following figure shows the result of tracing the Stateflow chart within the combo subsystem.

In the right pane of the report, the highlighted tag <S3>/Chart indicates the beginning of the code generated code for the chart.
In the left pane of the report, the total number of highlighted lines of code (in this case, 1) appears next to the source file name combo.vhd.
The left pane of the report also contains Previous and Next buttons. These buttons help you navigate through multiple instances of code generated for a selected component. In this example, there is only one instance, so the buttons are disabled.

Mapping Model Elements to Code Using the Traceability Report

The Traceability Report section of the report provides a complete mapping between model elements and code. The Traceability Report summarizes:

Eliminated / virtual blocks: accounts for blocks that are untraceable because they are not included in generated code
Traceable model elements, including:
- Traceable Simulink blocks
- Traceable Stateflow objects
- Traceable MATLAB functions

The following figure shows the beginning of a traceability report generated for the combo subsystem of the mcombo model.