Define Subsystem Reference Interfaces Using Test Harnesses and Generate Reusable Code

This example shows you how to define interfaces for a subsystem reference component using test harnesses and verify that the model reuses the component in defined interfaces only. It also shows how you can generate code for the subsystem reference component and reuse it in a model.

Subsystem Reference components adapt to the environment in which they are used. As a result, you might get undesired results when you use a subsystem reference component in an untested environment. To ensure pertinent results, you can mark the test harnesses of a subsystem file that produce the intended results as unit tests.

Use the Unit Test features available in the Simulink^® toolstrip to:

Specify valid testing environments of a subsystem file.
Capture signatures to diagnose and resolve invalid use of components.
Generate code for components to reuse in the top model.

Video Walkthrough

For a walkthrough of the example, play the video.

This video shows you how to define interfaces for a subsystem reference using test harnesses, verify that a model uses the subsystem reference in defined interfaces only, and how you can generate code for the subsystem reference component and reuse it in a model.

When you reference a subsystem file using a subsystem reference block in a model, the block inherits the attributes of the input signal, such as signal dimension and data type. If you use subsystem reference in an untested environment, you might get unexpected results. Hence, it is essential you use your subsystem reference components in tested environments.

The unit test features available in the Simulink Toolstrip enable you to specify valid testing environments of the subsystem reference component, generate the signature and code of the component, verify whether the use of the component in a model is valid or not, using signature matching, and reuse component code to build the model.

Let's look at an example with a reusable subsystem reference component. Open the subsystem file. The subsystem limits the input between minus 10 and 10 and then amplifies the result by a factor of 50. For these conditions, the output data varies between minus 500 and 500. There are two test harnesses defined for the subsystem file.

The first test harness uses the double data type. And the second test harness uses the int32 data type. As these two test harnesses give desired results for the subsystem file, these test harnesses are valid test environments for this component.

Open the model in which you want to reference the subsystem file. The model uses three instances of the same subsystem file, named Double Input, Int32 Input, and Int8 Input. The inputs to these subsystem reference instances are constants of type double, int32, and int8 respectively.

You can verify that a model uses the subsystem reference in defined interfaces in three steps. First, mark the tested environments of the subsystem file as unit tests. Then generate signatures for the unit tests. Finally, simulate the model to verify if the subsystem reference component is used in a tested environment.

To select the unit tests of the subsystem file, on the Simulink Toolstrip, click the "Select unit tests" button, and select both test harnesses from the dropdown menu. Next, generate signatures for the selected unit tests. Click "Generate signature," and select the "Generate signature" option from the menu. Save the subsystem file. This saves the generated signatures of the unit tests within the subsystem file.

Alternatively, to speed up signature generation in complex subsystems, you can use Parallel Computing Toolbox. To generate signatures of the unit tests in parallel, use the MATLAB script generateSignatureInParallel. After generating signatures, simulate the parent model. When you simulate the model, Simulink compares the signatures of each subsystem reference block in the model with the signatures of the subsystem reference blocks in the unit tests of the subsystem file.

The Diagnostic Viewer displays an error message to highlight the invalid use of the subsystem reference block Int8 Input in the model, as its signature does not match any of the unit test signatures. To diagnose and resolve the error, the first suggested action is to open the Signature Difference Viewer.

The Signature Difference Viewer provides past differences of the signatures of the subsystem reference blocks in the model and the unit tests. Depending on the type of mismatch, the differences are listed in the "Mismatch in port properties" and "Mismatch in compiled properties" tabs. Use the Attribute field in these tabs to identify the reason for the signature mismatch.

In this model, there is a mismatch in the import and outport data types of the subsystem reference block Int8 Input with the subsystem reference blocks in the unit tests. You may choose to remove the mismatch in the subsystem reference blocks in the model. Or use the second suggested action to disable signature check.

In the Configuration Parameters dialog box, set the diagnostic parameter "Behavior when a matching unit test for the subsystem reference is missing" to warning. When you select none or warning and simulate the model, Simulink simulates the model even if matching unit tests are missing.

Simulate the model. The model simulates, and the Diagnostic Viewer displays the message as a warning. For the subsystem reference blocks that have a valid use in the model, you can reuse the codes of the unit tests of the subsystem file.

You can do so in two steps. Generate code of the component in the unit tests of the subsystem file, and build the parent model to reuse component code. In the subsystem file, open the test harness. And go to Model Settings, Code Generation, Interface.

Set "Shared code placement" to "Shared location." And click OK. Apply the same settings to the other test harness. To generate code of the subsystem file, on the Simulink Toolstrip, click "Generate signature," and select the "Generate code" option from the menu. This generates code for the subsystem reference component in the selected unit tests. Save the subsystem file.

To reuse the component code in the model, first set the code generation folder structure. Type this command in the Command Window. In the parent model, press Command-B on Mac or Control-B on all other operating systems to build the model. To view the code files, open the code generation report for the model. In the build, the model reuses the code generated for the subsystem reference blocks in the unit tests of the subsystem file.

Video Player is loading.

Current Time 0:00

Duration 6:43

Loaded: 0%

Stream Type LIVE

Remaining Time 6:43

Validate Subsystem Reference Use in Model and Generate Reusable Code

This example uses:

Open Model

Explore the Model

1. Open the subsystem file slexReusableSS.

The subsystem slexReusableSS limits the input between (-10,10) and then amplifies the result by a factor of 50. slexReusableSS has two test harnesses, ssref1_double and ssref1_int32. To accommodate data between (-500,500), ssref1_double and ssref1_int32 use double and int32 data types, respectively.

2. Open the model slexModelUsingReusableSS.

The model slexModelUsingReusableSS uses three instances of the subsystem file slexReusableSS named Double Input, Int32 Input2, and Int8 Input. The inputs to Double Input, Int32 Input, and Int8 Input are constants of type double, int32, and int8, respectively.

Define Interfaces and Verify Component Use

This section explains how to validate the use of Subsystem Reference blocks Double Input, Int32 Input2, and Int8 Input in the model slexModelUsingReusableSS using unit test features.

1. In the subsystem file slexReusableSS, select the test harnesses ssref1_double and ssref1_int32 from the drop-down menu of the Select unit tests button on the Simulink® toolstrip.

If you create new test harnesses for the subsystem file, set the Subsystem Reference block in the test harness as Atomic with Reusable function packaging.

2. To generate signatures, select Generate Signature option from the Generate Signature menu on the Simulink® toolstrip. This action generates signatures for the Subsystem Reference block in the unit tests ssref1_double and ssref1_int32 of the subsystem file.

Alternatively, in complex subsystems, you can generate signatures for the selected unit tests in parallel using multiple instances of MATLAB®. This approach enables you to speed up signature generation. For more information, see Parallel Computing Toolbox Product Description (Parallel Computing Toolbox). To generate signatures in parallel, run the MATLAB® script generateSignatureInParallel.m. The script performs the following steps:

Load subsystem file and unit tests.
Set up parallel computing.
Generate signatures in parallel using multiple MATLAB® sessions.
Save signatures in subsystem file.

3. Save the subsystem file slexReusableSS.

4. To verify use of subsystem reference instances in the model, simulate the model slexModelUsingReusableSS. Simulink® compares the signatures of the Subsystem Reference blocks Double Input, Int32 Input2, and Int8 Input in the model with the signatures of the Subsystem Reference block in the unit tests ssref1_double and ssref1_int32. Use of a subsystem reference is valid when its signature matches at least one unit test signature.

5. Diagnostic Viewer displays an error message to highlight the invalid use of the subsystem reference Int8 Input in the model as Int8 Input does not have matching signature with any of the unit tests.

To disable the error message, set the diagnostic parameter Behavior when a matching unit test for subsystem reference is missing to none or warning in the Configuration Parameters dialog box.

Alternatively, use the Signature Difference Viewer to identify the reason for the signature mismatch and resolve these differences. The Signature Difference Viewer box provides parsed differences between the attributes of the Subsystem Reference block Int8 Input in the model and the attributes of the Subsystem Reference block in the test harnesses ssref1_double and ssref1_int32 of slexReusableSS.

6. Resolve the diagnostic messages and run the model slexModelUsingReusableSS again.

Generate Code

This section explains how to generate code for the Subsystem Reference block in the test harnesses ssref1_double and ssref1_int32.

1. In the subsystem file slexReusableSS, open test harness ssref1_double and go to Model Settings > Code Generation > Interface and set Shared code placement to Shared location. This action sets a common location to save generated codes. For more information, see Shared code placement (Simulink Coder). Save test harness ssref1_double and apply the same setting to the other test harness ssref1_int32.

2. To generate code, select the Generate Code option from the Generate Signature menu on the Simulink® toolstrip. This action generates code for the Subsystem Reference block in the selected test harnesses ssref1_double and ssref1_int32.

3. Save slexReusableSS.

Reuse Code

This section explains how you can reuse the generated code of the Subsystem Reference block to build the model.

1. Set the code generation folder structure using Simulink.fileGenControl (Simulink Coder).

Simulink.fileGenControl('set','CodeGenFolderStructure',...
Simulink.filegen.CodeGenFolderStructure.TargetEnvironmentSubfolder);

2. Press Command + B on Mac or Ctrl + B on all other operating systems to build the model slexModelUsingReusableSS.

In the build, the model slexModelUsingReusableSS uses the code generated for subsystem reference slexReusableSS. To check the reused codes, open the code generation report for the model.