Best Practices for Implementing Modeling Guidelines in Simulink
By David Jaffry, MathWorks
Embedded systems continue to become larger and more complex. At the same time, design teams are becoming more dispersed, both geographically and in terms of team members’ skills and experience. In this challenging development environment, implementing modeling guidelines to ensure modeling consistency is vital. Modeling guidelines establish a homogenous approach within the design team, making it easier to reuse the models for new projects. Guidelines also help new members of the team become familiar with your development process.
For some projects, implementing modeling guidelines is not simply a best practice; it is a requirement. Software systems deployed in high-integrity applications in aerospace and other industries must satisfy rigorous development and verification standards. Industry standards such as ISO 26262, EN 50128, IEC 61508, and DO-178C make modeling guidelines a prerequisite (Figure 1).
This article describes best practices for creating, implementing, validating, and promoting new modeling guidelines. The approach recommended will enable you to efficiently apply the standard within the team and ease the qualification of your modeling guidelines.
Defining Rules: Considerations and Best Practices
Modeling guidelines can and should meet several requirements, including readability, design reuse, and problem-free exchange of Simulink® models. The modeling guidelines enable the verification not only of models and model objects but also other artifacts, including object properties and workspace variables.
For this reason a modeling guideline consists of a set of rules. Each guideline lists the checks applicable to that guideline and provides detailed recommendations for resolving issues.
It is important to define rules that can be clearly understood and automatically verified. If a rule cannot be verified automatically, you will need to weigh the importance of having the rule against the time required for its manual verification.
Table 1 provides examples of how ambiguously worded or subjectively defined rules can be improved.
Rule | Issue | Recommended Change |
---|---|---|
The model shall be readable | Subjective | Replace with “Each sheet of the model shall contain less than 50 blocks. Maximum depth of subsystems is 10.” |
The model shall generate code | Incomplete | Complete with “The model shall be compliant with Embedded Coder target ert.tlc.” |
The model should be optimized for efficiency. | Vague | Specify the model parameters that should be optimized. |
Table 1. Sample rules with recommended improvements.
Before creating a new rule, consider using the rules available in Simulink, Simulink Check™, Embedded Coder®, IEC Certification Kit, and DO Qualification Kit. Most of the rules in these products are qualifiable and can be used in certification processes. By reusing these existing rules, you reduce the effort of creating your own modeling guidelines not only in the short term but also in the long term, as the rules are maintained for each new release of MATLAB.
Each rule in your modeling guidelines should use a template that includes the following elements:
- Title
- Identifier
- Description
- Rationale
- Level (mandatory or optional)
- Application examples (at least one example that complies with the rule and at least one that violates the rule, preferably with a workaround to enable the design team to deal with it)
- A reference to the individual responsible for implementing the check (for an existing rule)
In addition, the modeling guidelines should specify the version(s) of MATLAB and Simulink to which the rules apply. Verification options change from release to release. For example, in R2012b some verification tools support bus of arrays but not array of buses. By associating the rationale with the product version, you avoid including obsolete rules in your guidelines. The modeling guideline should also include references to all external standards documents.
Figure 2 shows a sample guideline.
Implementing the Modeling Guidelines
The Model Advisor in Simulink Check provides a framework for enforcing modeling guidelines. The Model Advisor checks a Simulink model for inconsistencies and for model objects that do not comply with the guidelines. Each guideline lists the checks applicable to that guideline and provides detailed recommendations for resolving issues
The tool proposes many checks that can be reused. Alternatively, you can create custom checks using an API available through Simulink Check. A Fix action can be associated to a check to correct any violations found.
All rules implemented in the Model Advisor should use the same template. For each failed check, include its location, the problem, and a suggested fix. It is a good idea to include a “See also” paragraph that links directly to the modeling guidelines documentation.
Generally, one rule defined in the modeling guidelines matches one check in Model Advisor. Each rule will be implemented in a separate MATLAB file. The Model Advisor API eases the formatting of the check by proposing which MATLAB functions to include, as well as where to include images, tables, and formatting. Figure 3 shows an example of a formatting check.
The Simulink or Stateflow APIs will be used mainly during the authoring of the check to verify the Simulink model. For example:
% Look for all 'Inport' blocks using find_system function inportBlockList = find_system(bdroot,'BlockType', 'Inport'); % Get name of all Inport Blocks using get_param function inportBlockName = get_param(inportBlockList,'Name');
Table 2 shows examples of functions from the Simulink API that you can use to create your own checks and verify some properties of the Simulink model.
Function | Description |
---|---|
find_system | Finds systems, blocks, lines, ports, and annotations |
get_param | Gets system and block parameter values |
bdroot | Returns name of top-level Simulink system (useful during the writing of the check) |
gcb | Gets pathname of current block (useful during the writing of the check) |
Table 2. Sample API functions.
Notice that some checks require an update of the Simulink model, as they need to manage data types or dimensions of signals or ports. A compiled model is very useful because it identifies all port data types and port dimensions for each block.
The check definition must use the following format to make it post-compile:
rec.Title = 'Check if root inport name begins with "in_" prefix'; setCallbackFcn(rec, @checkRootInportName,'None','StyleOne'); rec.CallbackContext = 'PostCompile';
A check that requires an update to the model starts with the character “^”. For ease of identification it is best to separate these checks from others (for example, by placing them at the end of the list of checks). Note that checks can share data for efficient computation using callbacks.
Validating the Modeling Guidelines
Provide failed and passed model examples for each rule. Keep these models as simple as possible to ensure that the check catches all violations.
You can use these models for the validation or certification of the modeling guidelines checks and for performing non-regression tests.
Figure 4 shows a sample architecture for test models.
Organizing and Promoting the Modeling Guidelines
The Configuration Editor in Model Advisor enables you to organize and keep only the rules you want to share. The custom configuration of Model Advisor is contained in a MAT-file that can be shared with others.
Figure 5 shows an example of modeling guidelines customized with the Configuration Editor. Notice that all unused checks have been removed from the Model Advisor interface.
Now you are ready to deploy the modeling guidelines to your design teams. The first step is to create a package that includes the following:
- Current version of your modeling guidelines
- Implementation of the checks
- Simulink models used to perform validation or non-regression tests
- Documentation
- Custom configuration or MAT-file created by the Model Advisor Configuration Editor
- MATLAB file
sl_customization.m
for deploying the custom configuration
It is a good idea to apply a subset of the modeling guidelines at the beginning of the project. Phased implementation will make it easier for the design team to adopt the new guidelines. It will also enable you to set checks relevant to a specific stage in your development process.
Published 2014 - 92216v00