Navigate Between Simulink Model and HDL Code by Using Traceability

Even a relatively small model can generate hundreds of lines of HDL code. To identify the mapping between your source model and the generated HDL code more easily, use the traceability support in HDL Coder™.

How Traceability Works

When you enable traceability support and generate HDL code for your model, the code generator creates and displays an HTML code generation report.

By default, the code generator uses the line-level style to generate a traceability report. The report generated by using this style contains hyperlinks for each line of HDL code to navigate between code and model. You can customize the traceability style to generate a comment-based report. This style contains hyperlinked comments above a block of code that correspond to a searchable tag for a certain block in your model. To learn more about the two traceability styles, see Traceability style.

You can generate reports for the root-level model or for subsystems, blocks, Stateflow^® charts, or MATLAB Function blocks. By default, HDL Coder generates a report for the top-level model.

After you generate the report, you can navigate from:

• Model to code: Select a certain block in your model and navigate to corresponding lines of HDL code in the report.

• Code to model: Select a line of code in the report and navigate to Simulink^® blocks corresponding to that line of code.

HDL Coder provides this two-way navigation or bidirectional traceability. With traceability support, you can:

• Verify that the generated code is as you expect. You can identify which model elements correspond to a line of code, and track code from different model elements that you have or have not reviewed.

• Verify whether the generated code meets the design requirements. You can assign the requirements to model elements and include the requirements as hyperlinks in the traceability report.

Generate Traceability Report

You can generate the report in the Configuration Parameters dialog box or at the command-line.

1. Enable generation of the traceability report.

   • In the Apps tab, select HDL Coder. The HDL Code tab appears. Select Settings > Report Options, and then select Generate traceability report.

   • At the command line, use hdlset_param to set the Traceability property on the model.

   To learn more about this parameter, see Generate traceability report.

2. Specify the traceability style. To generate a line-level traceability report, leave this setting as the default. To generate a comment-based traceability report:

   • On the HDL Code Generation > Report pane, specify the Traceability style.

   • At the command line, use hdlset_param to specify the TraceabilityStyle property on the model.

   To learn more about this parameter, see Traceability style.

3. Generate HDL code and the traceability report. Either select the DUT Subsystem and click Generate HDL Code on the Simulink Toolstrip, or run makehdl on the DUT Subsystem at the command line.

When HDL code generation is complete, the HTML code generation report appears in a new window.

Report Location

By default, HDL Coder writes the code generation report files to a folder in the hdlsrc\html\ folder of the build folder. If you close the report, you can navigate to this folder to reopen the report.

Before generating code, you can customize the target folder that stores the HDL code and the report files.

• In the Configuration Parameters dialog box, specify the target folder by using the Target setting.

• At the command line, use the TargetDirectory property.

To learn how to specify this parameter, see Code Generation Folder.

To keep your traceability report up to date, regenerate the HDL code and report after modifying the source model.

View the Traceability Report

In the HTML code generation report window, select the Traceability Report section. In the left pane of the report, click the names of Generated Source Files to view their contents in a MATLAB^® web browser window.

This figure shows a typical traceability report.

The traceability report has several subsections that indicate the blocks or subsystems from which the code was generated:

• The Eliminated / Virtual Blocks section accounts for blocks that are untraceable because they are not included in the generated HDL code.

• The Traceable Simulink Blocks / Stateflow Objects / MATLAB Functions section provides a complete mapping between model elements and code.

If you assigned block requirements, you can see the requirements as hyperlinked comments in the traceability report. For more information, see Include requirements in block comments.

Traceability by Using Code View

By default, after you enable generation of the traceability report and generate HDL code for your model, the Code view displays the generated code to the right of your model. You can use the Code view to trace generated HDL code to your model and your model to the generated HDL code.

To manually open the Code view, open the HDL Coder app. On the Simulink toolstrip, click the View Code button. Select the file that you want to display by using the drop-down list at the top of the Code view. You can dock or undock the Code view from the editor and minimize or expand the Code view using the down arrow in the upper right corner of the Code view. You can also use rich text capabilities, such as code folding and hiding comments.

This figure shows the Code view opened from the View Code button on the Simulink toolstrip in HDL Coder app.

Code-to-Model Navigation

To navigate from the HDL code to the model, follow either of these workflows:

Use the Code view:

1. Navigate to the Code view by clicking the automatically generated Code view panel on the right or by clicking the View Code button on the Simulink toolstrip in the HDL Coder app.

2. In the Code view, click the line number hyperlink or code comment link to highlight the block that the code line traces to. You can trace lines of code to the model elements from which they were generated.

This figure shows how the generated HDL code on line 238 in symmetric_fir.vhd in the Code view maps to the block highlighted in blue in the model when the Traceability style is specified as Line Level.

This figure shows how the comment <S1>/m3 generated in HDL code on line 253 in symmetric_fir.vhd in the Code view maps to the block highlighted in blue in the model when the Traceability style is specified as Comment Based.

Use the Code Generation Report:

1. In the traceability report, on the Code Location column, click any hyperlink.

   The code generator highlights that line of HDL code in the generated source file.

2. Select the link corresponding to that line of code in the source file.

   The code generator opens a separate window that displays the highlighted Simulink block corresponding to that line of code.

This figure shows how to navigate from the HDL code to the model by using the traceability report when you specify Line Level as the Traceability style.

In the traceability report, you see that HDL Coder generates line-level hyperlinks to the HDL code in the Code Location column. Click the link to highlight that line of code in the HDL source file, and then click the hyperlink for that line of code in the source file to highlight the corresponding block in your model.

This figure shows how to navigate from the HDL code to the model using the traceability report when you specify Comment Based as the Traceability style.

In the traceability report, when you select a hyperlink in the Code Location column, you see that HDL Coder highlights a hyperlinked comment <S2>/a1 in the HDL code. When you click the hyperlinked comment in the HDL source file, the code generator highlights the corresponding block a1 in your model.

Model-to-Code Navigation

Use model-to-code traceability to select a component at any level of the model and view the code references to that component in the traceability report. For tracing, you can select these objects:

• Subsystem

• Simulink block

• MATLAB Function block

• Stateflow chart, or these elements of a Stateflow chart:

  • State

  • Transition

  • Truth table

  • MATLAB function inside a chart

You can navigate from a certain block in the model to the HDL code generated for that block by using any of these approaches.

• Click that block in the model. The Code view highlights the code for the block and scrolls to the highlighted code lines.

  This figure shows an example of how a block highlighted in the model maps to the corresponding highlighted HDL code in the script symmetric_fir.vhd when the Traceability style is specified as Line Level.

  

  This figure shows an example of how a block highlighted in the model maps to the corresponding highlighted comment in the HDL code in the script symmetric_fir.vhd when the Traceability style is specified as Comment Based.

  

• Select that block and click Navigate to Code on the HDL Code tab.

• Right-click that block in your Simulink model and select HDL Code > Navigate to Code.

This figure shows the model-to-code navigation for both line-level and comment-based traceability style.

If you use Line Level as the Traceability style and navigate from the model to the HDL code, the traceability report highlights all lines of HDL code corresponding to that block.

If you use Comment Based as the Traceability style and navigate from the model to the HDL code, the traceability report highlights the traceable block comment in the HDL code.

Traceability Report Limitations

• If a block name in your model contains a single quote ('), code-to-model and model-to-code traceability are disabled for that block.

• If an asterisk (*) in a block name in your model causes a name-mangling ambiguity relative to other names in the model, code-to-model highlighting and model-to-code highlighting are disabled for that block. This is most likely to occur if an asterisk precedes or follows a slash (/) in a block name or appears at the end of a block name.

• If a block name in your model contains the character ÿ (char(255)), code-to-model highlighting and model-to-code highlighting are disabled for that block.

• If you use certain subsystem types, the Subsystem block is not traceable from the model to the HDL code at the subsystem level. It is possible that you can trace individual blocks within the Subsystem block. You cannot trace from the model to the code for these subsystem types:

  • Virtual

  • Masked

  • Nonvirtual for which code has been optimized away

• Traceability does not support Model Reference as the top-level Subsystem block.

Related Topics

• Create and Use Code Generation Reports