Stateflow®

Traceability of Stateflow^® Objects in Generated Code

What Is Traceability?

Traceability is the ability to navigate between a line of generated code and its corresponding object. For example, you can click a hyperlink in a traceability comment to go from that line of code to the object in the model. You can also right-click an object in your model to find the line in the code that corresponds to the object. This two-way navigation is known as bidirectional traceability.

See Tracing Generated Code Back to Your Simulink^® Model in the Real-Time Workshop^® User's Guide for information about how traceability works for Simulink^® blocks.

Back to Top

Traceability Requirements

To enable traceability comments, you must have a license for Real-Time Workshop^® Embedded Coder™ software. These comments appear only in code that you generate for an embedded real-time (ert) based target.

Back to Top

Traceable Stateflow^® Objects

Bidirectional traceability is supported for these Stateflow^® objects:

• States

• Transitions

• Embedded MATLAB™ functions

  Note   Traceability is not supported for M-files that you call from an Embedded MATLAB function.

• Truth Table blocks and truth table functions

• Graphical functions

Traceability in one direction is supported for these Stateflow objects:

• Events (code-to-model)

  Code-to-model traceability works for explicit events, but not implicit events. Clicking a hyperlink for an explicit event in the generated code highlights that item in the Contents pane of the Model Explorer.

• Junctions (model-to-code)

  Model-to-code traceability works for junctions with at least one outgoing transition. Right-clicking such a junction in the Stateflow Editor highlights the line of code that corresponds to the first outgoing transition for that junction.

Note   Embedded MATLAB Function blocks that you insert directly in a Simulink model are also traceable. For more information, see Using Traceability in Embedded MATLAB™ Function Blocks in the Simulink software documentation.

Back to Top

When to Use Traceability

Comments for Large-Scale Models

Use traceability when you want to generate commented code for a large-scale model. You can identify chart objects in the code and avoid manually entering comments or descriptions.

Validation of Generated Code

Use traceability when you want to validate generated code. You can identify which chart object corresponds to a particular line of code and keep track of code from different objects that you have or have not reviewed.

Back to Top

Basic Workflow for Using Traceability

The basic workflow for using traceability is:

1. Open your model, if necessary.

2. Define your system target file to be an embedded real-time (ert) target.

3. Enable and configure the traceability options.

4. Generate the source code and header files for your model.

5. Do one or both of these steps:

   • Trace a line of generated code to the model.

   • Trace an object in the model to a line of code.

Back to Top

Examples of Using Traceability

Bidirectional Traceability for States and Transitions

You can see how bidirectional traceability works for states and transitions in the sf_car demo by doing these steps:

1. Type sf_car at the MATLAB^® prompt.

2. In the Simulink model window or the Stateflow Editor, select Simulation > Configuration Parameters.

3. In the Real-Time Workshop pane, go to the Target selection section and enter ert.tlc for the system target file. Click Apply in the lower right corner of the window.

   Note   Traceability comments appear in generated code only for embedded real-time targets.

4. In the Real-Time Workshop > Report pane, select the Create code generation report option.

   This action automatically selects the Launch report automatically and Code-to-model options.

5. Select the Model-to-code option in the Navigation section. Then click Apply.

   This action automatically selects all options in the Traceability Report Contents section.

   Note   For large models that contain over 1000 blocks, disable the Model-to-code option to speed up code generation.

6. Go to the Real-Time Workshop > Interface pane. In the Software environment section, select the continuous time option. Then click Apply.

   Note   Because this demo model contains a block with a continuous sample time, you must perform this step before generating code.

7. In the Real-Time Workshop pane, click Build in the lower right corner.

   This action generates source code and header files for the sf_car model that contains the shift_logic chart. After the code generation process is complete, the code generation report appears automatically.

8. Click the sf_car.c hyperlink in the report.

9. Scroll down through the code to see the traceability comments.

   

   Note   The line numbers shown above can differ from the numbers that appear in your code generation report.

10. Click the <S5>:2 hyperlink in this traceability comment:

    /* During 'gear_state': '<S5>:2' */

    In the Stateflow Editor, the object gear_state appears highlighted.

    

11. Click the <S5>:12 hyperlink in this traceability comment:

    /* Transition: '<S5>:12' */

    In the Stateflow Editor, the corresponding transition appears highlighted.

    

    Note   To remove highlighting from an object in the Stateflow Editor, select View > Remove Highlighting.

12. You can also trace an object in the model to a line of generated code. In the Stateflow Editor, right-click the object gear_state and select Real-Time Workshop > Navigate to Code from the context menu.

    The code for that state appears highlighted in sf_car.c.

    

13. In the Stateflow Editor, right-click the transition with the condition [speed > up_th] and select Real-Time Workshop > Navigate to Code from the context menu.

    The code for that transition appears highlighted in sf_car.c.

    

Note   For a list of all Stateflow objects in your model that are traceable, click the Traceability Report hyperlink in the code generation report.

See Creating and Using a Code Generation Report in the Real-Time Workshop Embedded Coder User's Guide for more information about the code generation report.

Bidirectional Traceability for Truth Table Blocks

You can see how bidirectional traceability works for a Truth Table block in the sf_climate_control demo by doing these steps:

1. Type sf_climate_control at the MATLAB prompt.

2. Complete steps 2–5 in Bidirectional Traceability for States and Transitions.

3. In the Real-Time Workshop pane of the Configuration Parameters dialog, click Build in the lower right corner.

   The code generation report appears automatically.

4. Click the sf_climate_control.c hyperlink in the report.

5. Scroll down through the code to see the traceability comments.

   

   Note   The line numbers shown above can differ from the numbers that appear in your code generation report.

6. Click the <S1>:1:45 hyperlink in this traceability comment:

   /* Action '3': '<S1>:1:45' */

   In the Truth Table Editor, row 3 of the Action Table appears highlighted.

   

7. You can also trace a condition, decision, or action in the table to a line of generated code. For example, right-click a cell in the column D2 and select Real-Time Workshop > Navigate to Code from the context menu.

   The code for that decision appears highlighted in sf_climate_control.c.

   

   Note   To select the Real-Time Workshop > Navigate to Code option for a condition, decision, or action, right-click a cell in the row or column that corresponds to that truth table element.

Bidirectional Traceability for Graphical Functions

You can see how bidirectional traceability works for graphical functions in the sf_clutch demo by doing these steps:

1. Type sf_clutch at the MATLAB prompt.

2. Complete steps 2–6 in Bidirectional Traceability for States and Transitions.

3. Go to the Solver pane in the Configuration Parameters dialog. In the Solver options section, select Fixed-step in the Type field. Then click Apply.

   Note   Because this demo model does not work with variable-step solvers, you must perform this step before generating code.

4. In the Real-Time Workshop pane of the Configuration Parameters dialog, click Build in the lower right corner.

   The code generation report appears automatically.

5. Click the sf_clutch.c hyperlink in the report.

6. Scroll down through the code to see the traceability comments.

   

   Note   The line numbers shown above can differ from the numbers that appear in your code generation report.

7. Click the <S1>:3 hyperlink in this traceability comment:

   /* Graphical Function 'getSlipTorque': '<S1>:3' */

   In the Stateflow Editor, the graphical function getSlipTorque appears highlighted.

   

8. You can also trace a graphical function in the Stateflow Editor to a line of generated code. For example, right-click the graphical function detectSlip and select Real-Time Workshop > Navigate to Code from the context menu.

   The code for that graphical function appears highlighted in sf_clutch.c.

   

Code-to-Model Traceability for Events

You can see how code-to-model traceability works for events in the sf_security demo by doing these steps:

1. Type sf_security at the MATLAB prompt.

2. Complete steps 2–6 in Bidirectional Traceability for States and Transitions.

3. In the Real-Time Workshop pane of the Configuration Parameters dialog, click Build in the lower right corner.

   The code generation report appears automatically.

4. Click the sf_security.c hyperlink in the report.

5. Scroll down through the code to see the following traceability comment.

   

   Note   The line numbers shown above can differ from the numbers that appear in your code generation report.

6. Click the <S8>:56 hyperlink in this traceability comment:

   /* Event: '<S8>:56' */

   In the Contents pane of the Model Explorer, the event Sound appears highlighted.

   

Model-to-Code Traceability for Junctions

You can see how model-to-code traceability works for junctions in the sf_abs demo by doing these steps:

1. Type sf_abs at the MATLAB prompt.

2. Complete steps 2–6 in Bidirectional Traceability for States and Transitions.

3. Go to the Solver pane in the Configuration Parameters dialog. In the Solver options section, select Fixed-step in the Type field. Then click Apply.

   Note   Because this demo model does not work with variable-step solvers, you must perform this step before generating code.

4. In the Real-Time Workshop pane, click Build in the lower right corner.

   The code generation report appears automatically.

5. Open the AbsoluteValue chart in the Stateflow Editor.

6. Right-click the left junction and select Real-Time Workshop > Navigate to Code from the context menu.

   The code for the first outgoing transition of that junction appears highlighted in sf_abs.c.

   

Back to Top

Format of Traceability Comments

The format of a traceability comment depends on the Stateflow object type.

State

Syntax.  

/* <ActionType> '<StateName>': '<ObjectHyperlink>' */

Example.  

/* During 'gear_state': '<S5>:2' */

This comment refers to the during action of the state gear_state, which has the hyperlink <S5>:2.

Transition

Syntax.  

/* Transition: '<ObjectHyperlink>' */

Example.  

/* Transition: '<S5>:12' */

This comment refers to a transition, which has the hyperlink <S5>:12.

Embedded MATLAB™ Function

Syntax.  

/* Embedded MATLAB Function '<Name>': '<ObjectHyperlink>' */

Within the inlined code for an Embedded MATLAB function, comments that link to individual lines of the function have the following syntax:

/* '<ObjectHyperlink>' */

Examples.  

/* Embedded MATLAB Function 'test_function': '<S50>:99' */

/* '<S50>:99:20' */

The first comment refers to the Embedded MATLAB function named test_function, which has the hyperlink <S50>:99.

The second comment refers to line 20 of the Embedded MATLAB function in your chart.

Truth Table Block

Syntax.  

/* Truth Table Function '<Name>': '<ObjectHyperlink>' */

Within the inlined code for a Truth Table block, comments for conditions, decisions, and actions have the following syntax:

/* Condition '#<Num>': '<ObjectHyperlink>' */
/* Decision 'D<Num>': '<ObjectHyperlink>' */
/* Action '<Num>': '<ObjectHyperlink>' */

<Num> is the row or column number that appears in the Truth Table Editor.

Examples.  

/* Truth Table Function 'truth_table_default': '<S10>:100' */

/* Condition '#1': '<S10>:100:8' */
/* Decision 'D1': '<S10>:100:16' */
/* Action '1': '<S10>:100:31' */

The first comment refers to a Truth Table block named truth_table_default, which has the hyperlink <S10>:100.

The other three comments refer to elements of that Truth Table block. Each condition, decision, and action in the Truth Table block has a unique hyperlink.

Truth Table Function

See Truth Table Block for syntax and examples.

Graphical Function

Syntax.  

/* Graphical Function '<Name>': '<ObjectHyperlink>' */

Example.  

/* Graphical Function 'hello': '<S1>:123' */

This comment refers to a graphical function named hello, which has the hyperlink <S1>:123.

Event

Syntax.  

/* Event: '<ObjectHyperlink>' */

Example.  

/* Event: '<S3>:33' */

This comment refers to an event, which has the hyperlink <S3>:33.

Back to Top

Generated Code Files for Targets You Build

Debugging and Testing