Simulink® Verification and Validation™ User's Guide R2015a
How to Contact MathWorks Latest news: www.mathworks.com Sales and services: www.mathworks.com/sales_and_services User community: www.mathworks.com/matlabcentral Technical support: www.mathworks.com/support/contact_us Phone: 508-647-7000 The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098 Simulink® Verification and Validation™ User's Guide © COPYRIGHT 2004–2015 by The MathWorks, Inc. The software described in this document is furnished under a license agreement.
Revision History June 2004 October 2004 March 2005 April 2005 September 2005 March 2006 September 2006 March 2007 September 2007 March 2008 October 2008 March 2009 September 2009 March 2010 September 2010 April 2011 September 2011 March 2012 September 2012 March 2013 September 2013 March 2014 October 2014 March 2015 First printing Online only Online only Second printing Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Onlin
Contents Getting Started 1 Simulink Verification and Validation Product Description . Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1-2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operating System Requirements . . . . . . . . . . . . . . . . . . . . . . Product Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Link to Requirements Document Using Selection-Based Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Configure RMI for IBM Rational DOORS or Microsoft ActiveX Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Requirements Traceability Link Editor . . . . . . . . . . . . Manage Requirements Traceability Links Using Link Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements Tab . . . . . . . . . . . . . . . . . .
3 Change Requirements Links . . . . . . . . . . . . . . . . . . . . 2-36 Link to Requirements in MuPAD Notebooks . . . . . . . . 2-39 Create Requirements Traceability Report for Model . 2-42 Link to Requirements Modeled in Simulink . . . . . . . . 2-44 Requirements Linking with Simulink Annotations . . . 2-53 Link Signal Builder Blocks to Requirements Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54 Link Signal Builder Blocks to Model Objects . . . . . . . .
4 5 Reviewing Requirements Highlight Model Objects with Requirements . . . . . . . . . Highlight Model Objects with Requirements Using Model Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Highlight Model Objects with Requirements Using Model Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Navigate to Requirements from Model . . . . . . . . . . . . . . Navigate from Model Object . . . . . . . . . . . . . . . . . . . . .
How the rmi Function Checks a Requirements Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validate Requirements Links in a Model . . . . . . . . . . . . Check Requirements Links with the Model Advisor . . . . Fix Invalid Requirements Links Detected by the Model Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5-3 5-4 5-4 5-7 Validate Requirements Links in a Requirements Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advantages of Synchronizing Your Model with a Surrogate Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Synchronize a Simulink Model to Create a Surrogate Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Create Links Between Surrogate Module and Formal Module in a DOORS Database . . . . . . . . . . . . . . . . . . . 6-7 Customize DOORS Synchronization . . . . . . . . . . . . . . . . DOORS Synchronization Settings . . . . . . . . . . . . . .
Microsoft Office . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why Add Navigation Objects to Microsoft Office Requirements? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enable Linking from Microsoft Office Documents to Simulink Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . Insert Navigation Objects in Microsoft Office Requirements Documents . . . . . . . . . . . . . . . . . . . . Customize Microsoft Office Navigation Objects . . . . . .
9 Custom Types of Requirements Documents Why Create a Custom Link Type? . . . . . . . . . . . . . . . . . . 9-2 Implement Custom Link Types . . . . . . . . . . . . . . . . . . . . 9-3 Custom Link Type Functions . . . . . . . . . . . . . . . . . . . . . . 9-4 Links and Link Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 Link Type Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Custom Link Type Registration . . . . . . . . . . . . . . . . . . .
Model Component Testing 11 Overview of Component Verification Component Verification . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 Component Verification Approaches . . . . . . . . . . . . . . 11-2 Simulink Verification and Validation Tools for Component Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 12 Basic Approach to Component Verification . . . . . . . . . Workflow for Component Verification . . . . . . . . . . . . .
Signal Monitoring with Model Verification Blocks 13 14 Using Model Verification Blocks Model Verification Blocks and the Verification Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 Use Check Static Lower Bound Block to Check for Outof-Bounds Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 Linear System Modeling Blocks in Simulink Control Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Model Coverage Analysis 15 Model Coverage Definition Model Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2 Types of Model Coverage . . . . . . . . . . . . . . . . . . . . . . . . Cyclomatic Complexity . . . . . . . . . . . . . . . . . . . . . . . . Condition Coverage (CC) . . . . . . . . . . . . . . . . . . . . . . . Decision Coverage (DC) . . . . . . . . . . . . . . . . . . . . . . . . Lookup Table Coverage . . . . . . . . . . . . . . . . . . . . . . . .
Discrete FIR Filter . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11 Discrete-Time Integrator . . . . . . . . . . . . . . . . . . . . . . 16-11 Discrete Transfer Fcn . . . . . . . . . . . . . . . . . . . . . . . . 16-12 Dot Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-13 Enabled Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . 16-13 Enabled and Triggered Subsystem . . . . . . . . . . . . . . 16-13 Fcn . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18 While Iterator, While Iterator Subsystem . . . . . . . . . 16-31 Model Objects That Do Not Receive Coverage . . . . . . 16-33 Setting Model Coverage Options Specify Model Coverage Options . . . . . . . . . . . . . . . . . . Coverage Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Results Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporting Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options Tab . . . . . . . . . . . . . . . . . .
How to Collect Coverage for MATLAB Functions . . . . Examples: Model Coverage for MATLAB Functions . . 18-22 18-23 Model Coverage for C and C++ S-Functions . . . . . . . . Make S-Function Compatible with Model Coverage . . Generate Coverage Report for S-Function . . . . . . . . . 18-37 18-37 18-38 View Coverage Results for C/C++ Code in S-Function Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-41 Model Coverage for Stateflow Charts . . . . . . . . . . . . .
20 Decisions Analyzed . . . . . . . . . . . . . . . . . . . . . . . . . . Conditions Analyzed . . . . . . . . . . . . . . . . . . . . . . . . . MCDC Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Cumulative Coverage . . . . . . . . . . . . . . . . . . . . . . . . N-Dimensional Lookup Table . . . . . . . . . . . . . . . . . . Block Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Relational Boundary . . . . . . . . . . . . . . . . . . . . . . . . .
Filter Filter Filter Filter 21 a Stateflow Event . . . . . . . . . . . . . . . . . . . . . . Library Reference Blocks . . . . . . . . . . . . . . . . . a Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . a Specific Block . . . . . . . . . . . . . . . . . . . . . . . . 20-15 20-19 20-20 20-21 Automating Model Coverage Tasks Commands for Automating Model Coverage Tasks . . . 21-2 Create Tests with cvtest . . . . . . . . . . . . . . . . . . . . . . . . . 21-3 Run Tests with cvsim . . . . .
Limit Model Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Model Advisor Exclusion? . . . . . . . . . . . . . . Model Advisor Exclusion Files . . . . . . . . . . . . . . . . . . . Create Model Advisor Exclusions . . . . . . . . . . . . . . . . Review Model Advisor Exclusions . . . . . . . . . . . . . . . . Manage Exclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 22-3 22-3 22-3 22-4 22-6 22-7 Limit Model Checks By Excluding Gain and Outport Blocks . . . . . .
View Results in Model Advisor GUI . . . . . . . . . . . . . View Model Advisor Report . . . . . . . . . . . . . . . . . . . . 23-11 23-12 Archive and View Model Advisor Run Results . . . . . . 23-13 Customizing the Model Advisor 24 Overview of Customizing the Model Advisor Model Advisor Customization . . . . . . . . . . . . . . . . . . . . Requirements for Customizing the Model Advisor . . . . 25 xxii Contents 24-2 24-2 Create Model Advisor Checks Create Model Advisor Checks Workflow . . . . . .
Register Checks and Process Callbacks . . . . . . . . . . . 25-27 Define Startup and Post-Execution Actions Using Process Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . 25-28 Define Custom Checks . . . . . . . . . . . . . . . . . . . . . . . . . About Custom Checks . . . . . . . . . . . . . . . . . . . . . . . . Contents of Check Definitions . . . . . . . . . . . . . . . . . . Display and Enable Checks . . . . . . . . . . . . . . . . . . . . Define Where Custom Checks Appear . . . . . .
26 Create Custom Configurations by Organizing Checks and Folders Create Custom Configurations . . . . . . . . . . . . . . . . . . . . 26-2 Create Configurations by Organizing Checks and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3 Create Procedural-Based Configurations . . . . . . . . . . . 26-4 Organize Checks and Folders Using the Model Advisor Configuration Editor . . . . . . . . . . . . . . . . . . . . . . . . . .
27 28 Create Procedural-Based Model Advisor Configurations Create Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Procedure? . . . . . . . . . . . . . . . . . . . . . . . . . Create Procedures Using the Procedures API . . . . . . . Define Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2 27-2 27-2 27-2 Create a Procedural-Based Configuration . . . . . . . . . . 27-5 Deploy Custom Configurations Overview of Deploying Custom Configurations . . . . .
1 Getting Started • “Simulink Verification and Validation Product Description” on page 1-2 • “System Requirements” on page 1-3
1 Getting Started Simulink Verification and Validation Product Description Verify models and generated code Simulink Verification and Validation automates requirements tracing, modeling standards compliance checking, and model coverage analysis. You can create detailed requirements traceability reports, author your own modeling style checks, and develop check configurations to share with engineering teams. Requirements documentation can be linked to models, test cases, and generated code.
System Requirements System Requirements In this section...
Requirements Traceability
2 Links Between Models and Requirements • “Overview of the Requirements Management Interface (RMI)” on page 2-3 • “Requirements Traceability Links” on page 2-4 • “Requirements Link Storage” on page 2-5 • “Supported Requirements Document Types” on page 2-6 • “Supported Model Objects for Requirements Linking” on page 2-9 • “Selection-Based Linking” on page 2-10 • “Link to Requirements Document Using Selection-Based Linking” on page 2-11 • “Configure RMI for IBM Rational DOORS or Microsoft ActiveX Navigation”
2 Links Between Models and Requirements • “Link Requirements to Simulink Data Dictionary Entries” on page 2-58 2-2
Overview of the Requirements Management Interface (RMI) Overview of the Requirements Management Interface (RMI) If you want to link Simulink and Stateflow objects to requirements, including external documents, verification objects, or tests, use the RMI to: • Associate Simulink and Stateflow objects with requirements. • Create links between Simulink and Stateflow model objects. • Navigate from a Simulink or Stateflow object to requirements.
2 Links Between Models and Requirements Requirements Traceability Links When you want to navigate from a Simulink model or from a region of MATLAB code to a location inside a requirements document, you can add requirements traceability links to the model or code. Requirements traceability links have the following attributes: • A description of up to 255 characters. • A requirements document path name, such as a Microsoft Word file or a module in an IBM Rational DOORS database.
Requirements Link Storage Requirements Link Storage When you create links from a model to external requirements, by default, the Requirements Management Interface (RMI) stores the information about the links internally in the model file. When links are stored with the model, each time you change requirements links, the time stamp and version number of the model changes. If you do not want to modify your model when creating or modifying requirements links, use external storage for requirements links.
2 Links Between Models and Requirements Supported Requirements Document Types The Requirements Management Interface (RMI) supports linking with external documents of the types listed in the table below. For each supported requirements document type, the table lists the options for requirements locations within the document. If you would like to implement linking with a requirements document of a type that is not listed in the table below, you can register a custom requirements document type with the RMI.
Supported Requirements Document Types Requirements Document Type Location Options IBM Rational DOORS Page/item number — The unique numeric ID of the target DOORS object. The RMI links to that object. MuPAD Named item — The name of a link target in a MuPAD notebook. Simulink Create links to the RTF file associated with the DocBlock block to a DocBlock block Microsoft Word file: (RTF format only) • Search text — A search string. The RMI links to the first occurrence of that string in the document.
2 Links Between Models and Requirements Requirements Document Type Location Options Web browser URL The RMI can link to a URL location. In the Document field, type the URL string. When you click the link, the document opens in a Web browser: • Named item — An anchor name. The RMI links to that location on the Web page at that URL. PDF • Named item — A bookmark name. The RMI links to the location of that bookmark in the document. Not fully supported, depends on the platform and bookmark type.
Supported Model Objects for Requirements Linking Supported Model Objects for Requirements Linking You can associate requirements links between the following types of Simulink model objects: • Simulink block diagrams and subsystems • Simulink blocks and annotations • Simulink data dictionary entries • Signal Builder signal groups • Stateflow charts, subcharts, states, transitions, and boxes • Stateflow functions • Lines of MATLAB code • Simulink Test™ test manager test cases 2-9
2 Links Between Models and Requirements Selection-Based Linking You can use selection-based linking to create links from a model object to another model object or to an object in a requirements document. Selection-based linking is the easiest way to create requirements links from a model to an external document. For examples of selection-based linking, see “Link to Requirements Document Using Selection-Based Linking” on page 2-11 and “Link Multiple Model Objects to a Requirements Document” on page 2-21.
Link to Requirements Document Using Selection-Based Linking Link to Requirements Document Using Selection-Based Linking To create a link from a model to a requirements document, using selection-based linking: 1 In the requirements document, select text or objects to link to. 2 Right-click the model object.
2 Links Between Models and Requirements Configure RMI for IBM Rational DOORS or Microsoft ActiveX Navigation To use the features of the Requirements Management Interface (RMI), you must communicate with external software products such as Microsoft Office and IBM Rational DOORS. Initial configuration steps are required to setup the RMI if you need to: • Use the RMI with DOORS applications (PC only). • Use ActiveX® controls for navigation from Microsoft Office documents to Simulink models.
Requirements Traceability Link Editor Requirements Traceability Link Editor In this section... “Manage Requirements Traceability Links Using Link Editor” on page 2-13 “Requirements Tab” on page 2-15 “Document Index Tab” on page 2-15 Manage Requirements Traceability Links Using Link Editor You can create, edit, and delete requirements traceability links using the Link Editor. To open the Link Editor: • in the Simulink Editor, right-click on a model object that has a requirements traceability link.
2 Links Between Models and Requirements In the Link Editor, you can: • Create requirements links from one or more Simulink model objects or MATLAB code lines. • Customize information about requirements links, including specifying user tags to filter requirements highlighting and reporting. • Delete existing requirements links. • Modify the stored order of requirements to control the order of labels in context menus for linked objects.
Requirements Traceability Link Editor Requirements Tab On the Requirements tab, you specify detailed information about the link, including: • Description of the requirement (up to 255 words). If you create a link using the document index, unless a description already exists, the name of the index location becomes the description for the link . • Path name to the requirements document. • Document type (Microsoft Word, Microsoft Excel, IBM Rational DOORS, MuPAD, HTML, text file, etc.).
2 Links Between Models and Requirements Requirements Settings You can manage your RMI preferences in the Requirements Settings dialog box. These settings are global and not associated with any particular model. To open the Requirements Settings dialog box, from the Simulink Editor, select Analysis > Requirements Traceability > Settings. In this dialog box, you can select the: • Storage tab to set the default way in which the RMI stores requirements links in a model.
Requirements Settings Options Description Modify destination for bi-directional linking Creates links both to and from selected link destination. Store absolute path to model file Select type of file reference. For information, see “Document Path Storage” on page 5-15. Use custom bitmap for navigation controls in documents Select and browse for your bitmap. You can use your own bitmap file to control the appearance of navigation links in your document.
2 Links Between Models and Requirements Link Model Objects In this section... “Link Objects in the Same Model” on page 2-18 “Link Objects in Different Models” on page 2-18 Link Objects in the Same Model You can create a requirements link from one model object to another model object: 1 Right-click the link destination model object and select Requirements Traceability > Select for Linking with Simulink.
Link Model Objects 5 Right-click the slvnvdemo_powerwindow_controller/control subsystem and select Requirements Traceability. The new RMI link appears at the top of the Requirements Traceability submenu. 6 To verify that the links were created, in the slvnvdemo_powerwindow_controller model window, select Analysis > Requirements Traceability > Highlight Model. The blocks with requirements links are highlighted. 7 Close the slvnvdemo_powerwindow_controller and slvnvdemo_powerwindow models.
2 Links Between Models and Requirements Link from External Applications You can navigate to Simulink objects or MATLAB code with requirements using the internal MATLAB HTTP server. To get the URL for an object in your model, right-click the object and select Requirements Traceability > Copy URL to Clipboard.
Link Multiple Model Objects to a Requirements Document Link Multiple Model Objects to a Requirements Document You can link multiple Simulink and Stateflow objects to a requirement. The workflow is: 1 In the requirements document, select the requirement. 2 In the Simulink Editor or Stateflow Editor, select the objects to link to the selected requirement. You can select multiple objects by holding down the Shift key while you click each object that you want to select.
2 Links Between Models and Requirements • Link to Selection in Excel • Link to Selection in DOORS 5 2-22 You can also add and edit links for multiple objects using the Requirements Traceability Link Editor. To open the Link Editor, in the Requirements Traceability context menu, select Add Links to All.
Link Multiple Model Objects to a Requirements Document 2-23
2 Links Between Models and Requirements Link Multiple Model Objects to a Requirement Document Using a Simulink DocBlock This example shows how to link multiple model objects to a requirement document using a DocBlock. You can minimize the number of links to the external requirements document by using a DocBlock in the model. You can insert aDocBlock at the top level of the model and link your external requirements document to it.
Link Multiple Model Objects to a Requirements Document The link to the new requirements are on the top menu option. 13 To verify that the links were created, select Analysis > Requirements Traceability > Highlight Model. The DocBlock, control logic chart, and Airflow calculation subsystem are highlighted. 14 Close the slvnvdemo_fuelsys_officereq model and the slvnvdemo_FuelSys_DesignDescription.docx requirements document.
2 Links Between Models and Requirements Link to Requirements in Microsoft Word Documents In this section...
Link to Requirements in Microsoft Word Documents 6 Open the document. The RMI populates the Document and Document type fields. 7 Click the Document Index tab of the Link Editor. The Document Index tab lists all bookmarks in the requirements document, as well as all section headings (text that you have styled as Heading 1, Heading 2, and so on). The document index lists the bookmarks in alphabetical order, not in order of location within the document.
2 Links Between Models and Requirements 8 Select the bookmark that you want to link the block to and click OK. The RMI creates a link from the block to the location of the bookmark in the requirements document without modifying the document itself. Open the Example Model and Associated Requirements Document This example describes how to create links from objects in a Simulink model to selected requirements text in a Microsoft Word document.
Link to Requirements in Microsoft Word Documents • Enable Modify destination for bi-directional linking. When you select this option, every time you create a selection-based link from a model object to a requirement, the RMI inserts navigation objects at the designated location. For more information about the settings, see “Requirements Settings” on page 2-16. 6 Double-click the fuel rate controller subsystem to open it. 7 Open the Airflow calculation subsystem.
2 Links Between Models and Requirements This dialog box contains the following information for the link you just created: • Description of the link, which for selection-based links, matches the text of the selected requirements document, in this case Determination of pumping efficiency. • Name of the requirements document, in this case slvnvdemo_FuelSys_DesignDescription.docx. • Document type, in this case, Microsoft Word.
Link to Requirements in Microsoft Word Documents • The type and identifier of the location in the requirements document. With selectionbased linking for Microsoft Word requirements documents, the RMI creates a bookmark in the requirements document. For this link, the RMI created a bookmark named Simulink_requirement_item_7.
2 Links Between Models and Requirements Link to Requirements in IBM Rational DOORS Databases This example shows how to create links from objects in a Simulink model to requirements in an IBM Rational DOORS database. 1 Open a DOORS formal module. 2 Click to select one of the requirement objects. 3 Open the example model: sldemo_fuelsys 2-32 4 Open the fuel_rate_control subsystem. 5 Right-click the airflow_calc subsystem and select Requirements Traceability > Link to Selection in DOORS.
Link to Requirements in IBM Rational DOORS Databases If you navigate to a DOORS requirement, the DOORS module opens in read only mode. If you want to modify the DOORS module, open the module using DOORS software. Note: To view an example of using the RMI with an IBM Rational DOORS database, run the Managing Requirements for Fault-Tolerant Fuel Control System (IBM Rational DOORS) example at the MATLAB command prompt.
2 Links Between Models and Requirements Link to Requirements in Microsoft Excel Workbooks In this section...
Link to Requirements in Microsoft Excel Workbooks You will link the speed sensor block to the Speed Sensor Failure information in the Microsoft Excel requirements document. 4 When you browse and select a requirements document, the RMI stores the document path as specified by the Document file reference option on the Requirements Settings dialog box, Selection Linking tab. For information about which setting to use for your working environment, see “Document Path Storage” on page 5-15.
2 Links Between Models and Requirements 4 Use the Link Editor to specify information about the Microsoft Excel requirements document, the requirement, and the link. 5 Click Apply or OK to create the link. Change Requirements Links 1 In the slvnvdemo_fuelsys_officereq model, right-click the MAP sensor block and select Requirements Traceability > Open Link Editor. The Requirements Traceability Link Editor opens displaying the information about the requirements link.
Link to Requirements in Microsoft Excel Workbooks 2 In the Description field, enter: MAP sensor test scenario The User tag field contains the tag test. User tags filter requirements for highlighting and reporting.
2 Links Between Models and Requirements Note: For more information about user tags, see “Filter Requirements with User Tags” on page 4-25. 3 Click Apply or OK to save the change. Keep the example model open.
Link to Requirements in MuPAD Notebooks Link to Requirements in MuPAD Notebooks This example shows how to create a link from a Simulink model to a MuPAD notebook. You use a model that simulates a nonlinear second-order system with the van der Pol equation. Before beginning this example, create a MuPAD notebook with one or more link targets. This example uses a MuPAD notebook that includes information about solving the van der Pol equation symbolically and numerically.
2 Links Between Models and Requirements This figure shows two link targets. Note: These link targets are in a MuPAD notebook that was created for this example. The Document Index tab displays only link targets that you have created in your MuPAD notebook. 9 2-40 Select a link target name and click Apply.
Link to Requirements in MuPAD Notebooks The Requirements tab reopens, displaying the details of the newly created link. Unless you have previously entered a description, the link target name appears in the Description field. 10 To confirm that you created the link, right-click a blank area of the model and select Requirement. The new link is at the top of the submenu.
2 Links Between Models and Requirements Create Requirements Traceability Report for Model To create the default requirements report for a Simulink model: 1 Open the example model: slvnvdemo_fuelsys_officereq 2 Make sure that your current working folder is writable. 3 In the Simulink Editor, select Analysis > Requirements Traceability > Generate Report. If your model is large and has many requirements links, it takes a few minutes to create the report.
Create Requirements Traceability Report for Model A typical requirements report includes: • Table of contents • List of tables • Per-subsystem sections that include: • Tables that list objects with requirements and include links to associated requirements documents • Graphic images of objects with requirements • Lists of objects with no requirements • MATLAB code lines with requirements in MATLAB Function blocks For detailed information about requirements reports, see “Customize Requirements Traceability R
2 Links Between Models and Requirements Link to Requirements Modeled in Simulink You can use Simulink to model your design requirements. For example, you can use verification blocks to specify desired system properties and model the design requirements. The Requirements Management Interface (RMI) allows you to create navigation links between the requirements modeled in Simulink, the associated Simulink objects, and related test cases.
Link to Requirements Modeled in Simulink Verification Subsystems for Power Window Controller Model Open the verification model, 'Power Window Controller Temporal Property Specification'. This model specifies properties and requirements of the slvnvdemo_powerwindowController model. Consider the following design requirements for the controller: 1 Requirement 1 (Obstacle Response) - Whenever an obstacle is detected, the controller shall give the down command for one second.
2 Links Between Models and Requirements 2 Requirement 2 (Autodown feature) - If the driver presses the down button for less than 1 second, the controller keeps issuing the down command until the end has been reached, or the driver presses the up button. This requirement is modeled in Verification Subsystem3 See Design Verifier Temporal Properties example for more details.
Link to Requirements Modeled in Simulink 2-47
2 Links Between Models and Requirements Create RMI Link to a Simulink Object Create an RMI link from Verification Subsystem2 to the emergencyDown state in the slvnvdemo_powerwindowController model. 1 Open slvnvdemo_powerwindowController model. 2 Right-click on emergencyDown state and select Requirements > Select for linking with Simulink. 3 Right-click on Verification Subsystem2 and select Requirements > Add link to selected object. 4 Right-click the Verification Subsystem2.
Link to Requirements Modeled in Simulink 1 Right-click on this group of objects, select Requirements > Select for linking with Simulink. Be careful to not lose the selections when you right-click. 2 Right-click on Verification Subsystem3 and select Requirements > Link to 4 selected objects. Link to a Group of Simulink Objects 1 Right-click on NAND block in Global Assumptions and select Requirements > Select for linking with Simulink.
2 Links Between Models and Requirements 5 Right-click each input and select Requirements to display new links. Click the new link, confirm that NAND is highlighted. Create Links for Navigation in Both Directions To create links for navigation in both directions: 1 Open Requirements Settings dialog box. 2 Select the Selection Linking tab. 3 Enable Modify destination for bi-directional linking.
Link to Requirements Modeled in Simulink Highlight and Report RMI Links Between Simulink Objects Create RMI links to Simulink objects in the same way as links to external documents: 1 In the slvnvdemo_powerwindow_vs model window, select Analysis > Requirements > Highlight Model to highlight all RMI links in the model, including links to Simulink objects. 2 In the slvnvdemo_powerwindow_vs model window, select Analysis > Requirements > Generate Report.
2 Links Between Models and Requirements Cleanup Close all open models. Do not save changes.
Requirements Linking with Simulink Annotations Requirements Linking with Simulink Annotations You can create requirements links to and from Simulink.Annotation objects using the Requirements Management Interface (RMI). Annotations are free-floating text boxes that you can place inside a Simulink model. For more information, see “Annotations” in the Simulink documentation. You can use RMI linking to associate annotations with other Simulink objects or external requirements documents.
2 Links Between Models and Requirements Link Signal Builder Blocks to Requirements Documents You can create links from a signal group in a Signal Builder block to a requirements document: 1 Open the model: sf_car 2 In the sf_car model window, double-click the User Inputs block. The Signal Builder dialog box opens, displaying four groups of signals. The Passing Maneuver signal group is the current active group. The RMI associates any requirements links that you add to the current active signal group.
Link Signal Builder Blocks to Requirements Documents 9 Next to the Location drop-down list, enter User Input Requirements. 10 Click Apply to create the link. 11 To verify that the RMI created the link, in the Simulink Editor, select the User Inputs block, right-click, and select Requirements Traceability. The link to the new requirement is the option at the top of the submenu. 12 Save the sf_car_linking model.
2 Links Between Models and Requirements Link Signal Builder Blocks to Model Objects This example shows how to create links from a signal group in a Signal Builder block to a model object: 1 Open the sf_car model. 2 Open the sf_car/shift_logic chart. 3 Right-click upshifting and select Requirements Traceability > Select for Linking with Simulink. 4 In the sf_car model window, double-click the User Inputs block. The Signal Builder dialog box opens, displaying four groups of signals.
Link Signal Builder Blocks to Model Objects 10 Click Apply to create the link. 11 In the model window, select the User Inputs block, right-click, and select Requirements Traceability. The link to the new requirement is the option at the top of the submenu. 12 To verify that the links were created, in the sf_car model window, select Analysis > Requirements Traceability > Highlight Model. The blocks with requirements links are highlighted.
2 Links Between Models and Requirements Link Requirements to Simulink Data Dictionary Entries You can create requirements traceability links for entries in Simulink data dictionaries. The process is similar to linking for other model objects. In the Model Explorer, rightclick a data dictionary entry, select Requirements Traceability, and choose one of the selection-based linking options. You can also use the Link Editor. This example demonstrates linking to a data dictionary entry.
Link Requirements to Simulink Data Dictionary Entries 5 Open the airflow_calc subsystem and select the Pumping Constant lookup table. 6 In the Model Explorer, right-click the PumpCon parameter and select Requirements Traceability > Link to Selection in Simulink. The two objects are linked. 7 Check the link. Right-click the PumpCon parameter and select Requirements Traceability, then select the navigation shortcut at the top of the Requirements Traceability submenu.
3 How Is Requirements Link Information Stored? • “External Storage” on page 3-2 • “Guidelines for External Storage of Requirements Links” on page 3-3 • “Specify Storage for Requirements Links” on page 3-4 • “Save Requirements Links in External Storage” on page 3-5 • “Load Requirements Links from External Storage” on page 3-6 • “Move Internally Stored Requirements Links to External Storage” on page 3-7 • “Move Externally Stored Requirements Links to the Model File” on page 3-8
3 How Is Requirements Link Information Stored? External Storage The first time you create links to requirements in a Simulink model, the RMI uses your designated storage preference. When you reopen the model, the RMI loads the internally stored links, or the links from the external file, as long as the file exists with the same name and location as when you last saved the links. The RMI allows you to save your links file as a different name or in a different folder.
Guidelines for External Storage of Requirements Links Guidelines for External Storage of Requirements Links If you decide to store requirements links in an external file, keep the following guidelines in mind: • When sharing models, use the default name and location. By default, external requirements are stored in a file named model_name.req in the same folder as the model. If you give your model to others to review the requirements traceability, give the reviewer both the model and .req files.
3 How Is Requirements Link Information Stored? Specify Storage for Requirements Links By default, the Requirements Management Interface (RMI) stores requirements links with the model file. In the Requirements Settings dialog box, on the Storage tab, you can enable external storage or reenable internal storage. This setting goes into effect immediately and applies to all new models and to existing models with no links to requirements.
Save Requirements Links in External Storage Save Requirements Links in External Storage The Requirements Management Interface (RMI) stores externally stored requirements links in a file whose name is based on the model file. Because of this, before you create requirements links to be stored in an external file, you must save the model with a value file name. You add, modify, and delete requirements links in external storage the same way you do when the requirements links are stored in the model file.
3 How Is Requirements Link Information Stored? Load Requirements Links from External Storage When you open a Simulink model that does not have internally stored requirements links, the RMI tries to load requirements links from an .req file, either the default file, or a previously specified file. If that file does not exist, the RMI assumes that this model has no requirements links. To explicitly load requirements links from an external file: 1 Select Analysis > Requirements Traceability > Load Links.
Move Internally Stored Requirements Links to External Storage Move Internally Stored Requirements Links to External Storage If you have a model with requirements links that are stored with the model, you can move those links to an external file. When you move internally stored links to a file, the RMI deleted the internally stored links from the model file and saves the model. From this point on, the data exists only in the external file.
3 How Is Requirements Link Information Stored? Move Externally Stored Requirements Links to the Model File If you have a model with requirements links that are stored in an external file, you can move those links to the model file. 1 Open the model that has only externally stored requirements links. 2 Make sure the right set of requirements links are loaded from the external file. 3 Select Analysis > Requirements Traceability > Copy to Model.
4 Reviewing Requirements • “Highlight Model Objects with Requirements” on page 4-2 • “Navigate to Requirements from Model” on page 4-5 • “Customize Requirements Traceability Report for Model” on page 4-7 • “Filter Requirements with User Tags” on page 4-25 • “Create Requirements Traceability Report for Simulink Project” on page 4-33 • “View Requirements Details for a Selected Block” on page 4-34
4 Reviewing Requirements Highlight Model Objects with Requirements You can highlight a model to see which objects in the model have links to requirements in external documents. You highlight a model from the Model Editor or from the Model Explorer. In this section...
Highlight Model Objects with Requirements Objects that do not have requirements are colored gray. 3 To remove the highlighting from the model, select Analysis > Requirements Traceability > Unhighlight Model. Alternatively, you can right-click anywhere in the model, and select Remove Highlighting. While a model is highlighted, you can still manage the model and its contents.
4 Reviewing Requirements 1 Open the example model: slvnvdemo_fuelsys_officereq 2 Select View > Model Explorer. 3 To highlight all model objects with requirements, click the Highlight items with requirements on model icon ( ). The Simulink Editor window opens, and all objects in the model with requirements are highlighted. Note: If you are running a 64-bit version of MATLAB, when you navigate to a requirement in a PDF file, the file opens at the top of the page, not at the bookmark location.
Navigate to Requirements from Model Navigate to Requirements from Model In this section... “Navigate from Model Object” on page 4-5 “Navigate from System Requirements Block” on page 4-5 Navigate from Model Object You can navigate directly from a model object to that object's associated requirement. When you take these steps, the external requirements document opens in the application, with the requirements text highlighted.
4 Reviewing Requirements 1 Open the example model: slvnvdemo_fuelsys_officereq 2 In the Simulink Editor, select Analysis > Requirements Traceability > Highlight Model. 3 Open the fuel rate controller subsystem. The Airflow calculation subsystem has a requirements link. 4 Open the Airflow calculation subsystem. 5 In the Simulink Editor, select View > Library Browser. 6 On the Libraries pane, select Simulink Verification and Validation.
Customize Requirements Traceability Report for Model Customize Requirements Traceability Report for Model In this section...
4 Reviewing Requirements 1 Select Analysis > Requirements Traceability > Generate Report. The Requirements Management Interface (RMI) searches through all the blocks and subsystems in the model for associated requirements. The RMI generates and displays a complete report in HTML format. The report is saved with the default name, model_name_requirements.html. If you generate a subsequent report on the same model, the new report file overwrites any earlier report file.
Customize Requirements Traceability Report for Model List of Tables The List of Tables includes links to each table in the report.
4 Reviewing Requirements Model Information The Model Information contains general information about the model, such as when the model was created and when the model was last modified. Documents Summary The Documents Summary section lists all the requirements documents to which objects in the slvnvdemo_fuelsys_officereq model link, along with some additional information about each document.
Customize Requirements Traceability Report for Model • ID — The ID. In this example, DOC1, DOC2, DOC3, and DOC4 are short names for the requirements documents linked from this model. Before you generate a report, in the Settings dialog box, on the Reports tab, if you select User document IDs in requirements tables, links with these short names are included throughout the report when referring to a requirements document.
4 Reviewing Requirements • A list of requirements associated with the model or model object. In this example, click the target document name to open the requirements document associated with the slvnvdemo_fuelsys_officereq model.
Customize Requirements Traceability Report for Model • A list of blocks in the top-level model that have requirements. In this example, only the MAP sensor block has a requirement at the top level. Click the link next to Target: to open the requirements document associated with the MAP sensor block. The preceding table does not include these blocks in the top-level model because: • The fuel rate controller and engine gas dynamics subsystems are in dedicated chapters of the report.
4 Reviewing Requirements Chart Each Chart section reports on requirements in Stateflow charts, and includes: • A graphic of the Stateflow chart that identifies each state. • A list of elements that have requirements. To navigate to the requirements document associated with a chart element, click the link next to Target.
Customize Requirements Traceability Report for Model Report for Requirements in Model Blocks If your model contains Model blocks that reference external models, the default report does not include information about requirements in the referenced models. To generate a report that includes requirements information for referenced models, you must have a license for the Simulink Report Generator™ software.
4 Reviewing Requirements 4 On the far-right pane, locate the Model reference field. If you cannot see the dropdown arrow for that field, expand the pane. 5 In the Model reference field drop-down list, select Follow all model reference blocks. 6 To generate a requirements report for the open model that includes information about referenced models, click the Report icon 4-16 .
Customize Requirements Traceability Report for Model Customize Requirements Report The Requirements Management Interface (RMI) uses the Simulink Report Generator software to generate the requirements report.
4 Reviewing Requirements On the Report tab, select options that specify the contents that you want in the report. Requirements Settings Report Option Description Highlight the model before generating Enables highlighting of Simulink objects with requirements in the report graphics. report 4-18 Show user tags for each reported link Lists the user tags, if any, for each reported link.
Customize Requirements Traceability Report for Model Requirements Settings Report Option Description prevents long path names to requirements documents from cluttering the report tables. Report objects with no links to requirements Includes lists of model objects that have no requirements. Include details from linked documents Includes additional content from linked requirements.
4 Reviewing Requirements 5 To close the Requirements Settings dialog box, click Close. 6 Generate a requirements report by selecting Analysis > Requirements Traceability > Generate Report. The requirements report opens in a browser window so that you can review the content of the report. 7 If you do not want to overwrite the current report when you regenerate the requirements report, rename the HTML file, for example, slvnvdemo_fuelsys_officereq_requirements_old.html.
Customize Requirements Traceability Report for Model Requirements Document Format Includes in the Report Use the RptgenRMI.doorsAttribs function to include or exclude specific attributes or groups of attributes. 10 Close the Requirements Settings dialog box. 11 Generate a new requirements report by selecting Analysis > Requirements Traceability > Generate Report. 12 Compare this new report to the report that you renamed in step 7: • User tags associated with requirements links are included.
4 Reviewing Requirements Simulink Report Generator Component Report Information Missing Requirements Block Loop Applies all child components to blocks that have no requirements Missing Requirements System Loop Applies all child components to systems that have no requirements Requirements Block Loop Applies all child components to blocks that have requirements Requirements Documents Table Inserts a table that lists requirements documents Requirements Signal Loop Applies all child components to s
Customize Requirements Traceability Report for Model System Design Description Report The System Design Description report describes a system design represented by the current Simulink model. You can use the System Design Description report to: • Review a system design without having the model open. • Generate summary and detailed descriptions of the design. • Assess compliance with design requirements. • Archive the system design in a format independent of the modeling environment.
4 Reviewing Requirements on page 4-7. This menu option is equivalent to Analysis > Requirements Traceability > Generate Report. To specify options for the report, select Analysis > Requirements Traceability > Settings. Before generating the report, on the Report tab, set the options that you want. For detailed information about these options, see “Customize Requirements Report” on page 4-17.
Filter Requirements with User Tags Filter Requirements with User Tags In this section... “User Tags and Requirements Filtering” on page 4-25 “Apply a User Tag to a Requirement” on page 4-25 “Filter, Highlight, and Report with User Tags” on page 4-27 “Apply User Tags During Selection-Based Linking” on page 4-29 “Configure Requirements Filtering” on page 4-31 User Tags and Requirements Filtering User tags are user-defined keywords that you associate with specific requirements.
4 Reviewing Requirements 4-26
Filter Requirements with User Tags 4 In the User tag field, enter one or more keywords, separated by commas, that the RMI can use to filter requirements. In this example, after design, enter a comma, followed by the user tag test to specify a second user tag for this requirement. User tags: • Are not case sensitive. • Can consist of multiple words. For example, if you enter design requirement, the entire phrase constitutes the user tag. Separate user tags with commas.
4 Reviewing Requirements 4 To enable filtering with user tags, click the Filter links by user tags when highlighting and reporting requirements option. 5 To include only those requirements that have the user tag, test, enter test in the Include links with any of these tags field. 6 Click Close. 7 In the Simulink Editor, select Analysis > Requirements Traceability > Highlight model. The RMI highlights only those model objects whose requirements have the user tag test, for example, the MAP sensor.
Filter Requirements with User Tags 8 Reopen the Requirements Settings dialog box to the Filters tab. 9 In the Include links with any of these tags field, delete test. In the Exclude links with any of these tags field, add test. In the model, the highlighting changes to exclude objects whose requirements have the test user tag. The MAP sensor and Test inputs blocks are no longer highlighted. 10 In the Simulink Editor, select Analysis > Requirements Traceability > Generate Report.
4 Reviewing Requirements 3 In the Apply this user tag to new links field, enter one or more user tags, separated by commas. The RMI applies these user tags to all new selection-based requirements links that you create. 4-30 4 Click Close to close the Requirements Settings dialog box. 5 In a requirements document, select the specific requirement text. 6 Right-click a model object and select Requirements Traceability.
Filter Requirements with User Tags The selection-based linking options specify which user tags the RMI applies to the link that you create. In the following example, you can apply the user tags design, general, and reqtslink to the link that you create to your selected text. Configure Requirements Filtering In the Requirements Settings dialog box, on the Filters tab, are the following options for filtering requirements in a model.
4 Reviewing Requirements 4-32 Option Description Apply same filters in consistency checking Includes or excludes requirements with specified user tags when running a consistency check between a model and its associated requirements documents. Under Link type filters, Disable DOORS surrogate item links in context menus Disables links to IBM Rational DOORS surrogate items from the context menus when you right-click a model object. This option does not depend on current user tag filters.
Create Requirements Traceability Report for Simulink Project Create Requirements Traceability Report for Simulink Project To create a report for requirements traceability data in a Simulink Project: 1 2 Open your Simulink Project. At the MATLAB command prompt, enter the following: rmi('projectreport') The MATLAB Web browser opens, showing the traceability report for the Simulink Project.
4 Reviewing Requirements View Requirements Details for a Selected Block In this section... “Requirements Details Workflow” on page 4-34 “Requirements Details Limitations” on page 4-34 Requirements Details Workflow When you highlight model objects with requirements, you can view the requirements details for a selected block. Follow this workflow: 1 From the menu bar, select Analysis > Requirements Traceability > Highlight Model.
View Requirements Details for a Selected Block documents stored on network drives, and documents with Microsoft Office Trust Center ActiveX control restrictions may not work correctly with RMI. Consider enabling ActiveX controls without prompting and using requirements stored in a writable location on the MATLAB path. Before loading requirements details for IBM Rational DOORS links, you must be logged in to the IBM Rational DOORS Client.
5 Requirements Links Maintenance • “Validation of Requirements Links” on page 5-2 • “Validate Requirements Links in a Model” on page 5-4 • “Validate Requirements Links in a Requirements Document” on page 5-11 • “Document Path Storage” on page 5-15 • “Delete Requirements Links from Simulink Objects” on page 5-17 • “Requirements Links for Library Blocks and Reference Blocks” on page 5-19
5 Requirements Links Maintenance Validation of Requirements Links Requirements links in a model can become outdated when requirements change over time. Similarly, links in requirements documents may become invalid when your Simulink model changes, for example, when the model, or objects in the model, are renamed, moved, or deleted. The Simulink Verification and Validation software provides tools that allow you to detect and resolve these problems in the model or in the requirements document.
Validation of Requirements Links How the rmi Function Checks a Requirements Document rmi performs the following actions: • Locates all links to Simulink objects in the specified requirements document. • Checks each link to verify that the target object is present in a Simulink model. If the target object is present, rmi checks that the link label matches the target object. • Modifies the navigation controls in the requirements document to identify any detected problems.
5 Requirements Links Maintenance Validate Requirements Links in a Model In this section...
Validate Requirements Links in a Model Consistency Check Problem Identified • Microsoft Excel documents • IBM Rational DOORS documents • Simulink objects Identify selection-based links having description fields that do not match their requirements document text The Description field for the link does not match the requirements document text. When you create selection-based links, the Requirements Management Interface (RMI) saves the selected text in the link Description field.
5 Requirements Links Maintenance continue the checks. The consistency checks must verify up-to-date stored copies of the requirements documents. • If your model has links to DOORS requirements, you must be logged in to the DOORS software. Your DOORS database must include the module that contains the target requirements. 3 For this tutorial, make sure that you close both Microsoft Word and Microsoft Excel. 4 Click Run Selected Checks.
Validate Requirements Links in a Model Fix Invalid Requirements Links Detected by the Model Advisor In “Check Requirements Links with the Model Advisor” on page 5-4, three requirements consistency checks generate warnings in the slvnvdemo_fuelsys_officereq model.
5 Requirements Links Maintenance • In the Location field, specify a valid location in the requirements document. • Delete the requirements link by selecting the link and clicking Delete. 4 In the Model Advisor, select the Requirements Consistency Checking category of checks. 5 Click Run Selected Checks again, and verify that the warning no longer occurs.
Validate Requirements Links in a Model The first message indicated that the model contains a link to a bookmark named Simulink_requirement_item_7 in the requirements document that does not exist. In addition, this check identified the following mismatching text between the requirements blocks and the requirements document: • The Description field in the Test inputs Signal Builder block link is Normal mode of operation.
5 Requirements Links Maintenance seconds, then back to 10 degrees over the next two seconds. This cycle repeats continuously while the engine is held at a constant speed. • The Description field in the MAP Estimate block link is Manifold pressure failure. The requirement text in slvnvdemo_FuelSys_DesignDescription.docx is Manifold pressure failure mode. 2 3 Get more information about this link: a To navigate to a block, under Block, click the hyperlink.
Validate Requirements Links in a Requirements Document Validate Requirements Links in a Requirements Document In this section...
5 Requirements Links Maintenance If you want to... Do the following... Fix the invalid links Follow the instructions in “Fix Invalid Links in a Requirements Document” on page 5-13. Keep the changes to the navigation controls without fixing the invalid links Save the requirements document. Ignore the invalid links Close the requirements document without saving it.
Validate Requirements Links in a Requirements Document link for that requirement. To rerun the check so that all requirements are checked, at the top of the report, click Refresh. • If you click No, the document check continues, and the report identifies that navigation object as a broken link. Fix Invalid Links in a Requirements Document Using the report that the rmi function creates, you may be able to fix the invalid links in your requirements document.
5 Requirements Links Maintenance 4 5-14 To... Click... Navigate to and select a new target model or new target objects for these broken links. Fix all Reset the navigation controls for these invalid links to their original state, the state before you checked the requirements document. Reset all Make no changes to the requirements document. Any modifications rmi made to the navigation controls remain in the requirements document.
Document Path Storage Document Path Storage When you create a requirements link, the RMI stores the location of the requirements document with the link. If you use selection-based linking or browse to select a requirements document, the RMI stores the document location as specified by the Document file reference option on the Requirements Settings dialog box, Selection Linking tab.
5 Requirements Links Maintenance Model file C:\work\models\controllers\pid.mdl Requirements document pid.html Documents searched for (in order) C:\work\scratch\pid.html \pid.html C:\work\models\controllers\pid.html Absolute Path Example 5-16 Current MATLAB folder C:\work\scratch Model file C:\work\models\controllers\pid.mdl Requirements document C:\work\reqs\pid.html Documents searched for C:\work\reqs\pid.
Delete Requirements Links from Simulink Objects Delete Requirements Links from Simulink Objects In this section... “Delete a Single Link from a Simulink Object” on page 5-17 “Delete All Links from a Simulink Object” on page 5-17 “Delete All Links from Multiple Simulink Objects” on page 5-18 Delete a Single Link from a Simulink Object If you have an obsolete link to a requirement, delete it from the model object.
5 Requirements Links Maintenance Delete All Links from Multiple Simulink Objects To delete all requirements links from a group of Simulink model objects in the same model diagram or Stateflow chart: 1 Select the model objects whose requirements links you want to delete. 2 Right-click one of the objects and select Requirements Traceability > Delete All. 3 Click OK to confirm the deletion. This action deletes all requirements at the top level of each object.
Requirements Links for Library Blocks and Reference Blocks Requirements Links for Library Blocks and Reference Blocks In this section...
5 Requirements Links Maintenance Copy Library Blocks with Requirements When you copy a library subsystem or masked block to a model, you can highlight, view and navigate requirements links on the library block and on objects inside the library block. However, those links are not associated with that model. The links are stored with the library, not with the model. You cannot add, modify, or delete requirements links on the library block from the context of the reference block.
Requirements Links for Library Blocks and Reference Blocks Manage Requirements Inside Reference Blocks If your library block is a subsystem or a Stateflow atomic subchart, you can create requirements links on objects inside the subsystem or subchart. If you disable the link from the reference block to the library, you can add, modify, or delete requirements links on objects inside a reference block. Once you have disabled the link, the RMI treats those links as locally created links.
5 Requirements Links Maintenance Library S1 Model 1 Reference block Library block Library link S1 2 Disable the library link between the reference block and the library block. Keep the library loaded while you disable the link to maintain RMI data. To disable the link, select the reference block and select Diagram > Library Link > Disable Link. 3 Create a link from the object inside the reference block to the requirements document.
Requirements Links for Library Blocks and Reference Blocks a Select the reference block. b Select Diagram > Library Link > Resolve Link. c In the Action column, click Push. d Click OK to resolve the link to the library block and push the newly added requirement to the object inside the library block. When you resolve the library link between the library block and the subsystem, Simulink pushes the new requirement link to the library block S1.
5 Requirements Links Maintenance Library model S1 Library link Library link Model 1 Reference block Library block S1 Link to requirement Link to requirement Requirement Model 2 S1 Reference block Link to requirement Requirements document Links from Requirements to Library Blocks If you have a requirement that links to a library block and you drag that library block to a model, the requirement does not link to the reference block; the requirement links only to the library block.
Requirements Links for Library Blocks and Reference Blocks Library Library block B1 Links to and from a requirement Requirement Requirements document When you use library block B1 in a model, you can navigate from the reference block to the requirement. However, the link from the requirement still points only to library block B1, not to the reference block.
6 IBM Rational DOORS Surrogate Module Synchronization • “Synchronization with DOORS Surrogate Modules” on page 6-2 • “Advantages of Synchronizing Your Model with a Surrogate Module” on page 6-4 • “Synchronize a Simulink Model to Create a Surrogate Module” on page 6-5 • “Create Links Between Surrogate Module and Formal Module in a DOORS Database” on page 6-7 • “Customize DOORS Synchronization” on page 6-8 • “Resynchronize DOORS Surrogate Module to Reflect Model Changes” on page 6-15 • “Navigate with the Surr
6 IBM Rational DOORS Surrogate Module Synchronization Synchronization with DOORS Surrogate Modules Synchronization is a user-initiated process that creates or updates a DOORS surrogate module. A surrogate module is a DOORS formal module that is a representation of a Simulink model hierarchy. When you synchronize a model for the first time, the DOORS software creates a surrogate module. The surrogate module contains a representation of the model, depending on your synchronization settings.
Synchronization with DOORS Surrogate Modules Objects in a Simulink Model DOORS Surrogate Module DOORS Formal Module(s) with Requirements Object ID D1 D2 D3 Requirement Requirement Name 1 Requirement text ... 1.1 ... ... 1.2 Requirement text ... Object ID 200 202 203 204 205 206 207 208 Block Name Model 1 Subsystem 1.1 Block 1.1.1 1.1.2 Block Block 1.1.3 Subsystem 1.2 Block 1.2.1 1.3 Block A surrogate module is a representation of a Simulink model hierarchy.
6 IBM Rational DOORS Surrogate Module Synchronization Advantages of Synchronizing Your Model with a Surrogate Module Synchronizing your Simulink model with a surrogate module offers the following advantages: • You can navigate from a requirement to a Simulink object without modifying the requirements modules. • You avoid cluttering your requirements modules with inserted navigation objects. • The DOORS database contains complete information about requirements links.
Synchronize a Simulink Model to Create a Surrogate Module Synchronize a Simulink Model to Create a Surrogate Module The first time that you synchronize your model with the DOORS software, the DOORS software creates a surrogate module. In this tutorial, you synchronize the sf_car model with the DOORS software. Note: Before you begin, make sure you know how to create links from a Simulink model object to a requirement in a DOORS database.
6 IBM Rational DOORS Surrogate Module Synchronization After synchronization with the None option, the surrogate module, a formal module named sf_car_doors, contains: • A top-level object for the model (sf_car_doors) • Objects that represent model objects with links to DOORS requirements (transmission, engine torque), and their parent objects (Engine). 9 6-6 Save the surrogate module and the model.
Create Links Between Surrogate Module and Formal Module in a DOORS Database Create Links Between Surrogate Module and Formal Module in a DOORS Database The surrogate module is the interface between the DOORS formal module that contains your requirements and the Simulink model. To establish links between the surrogate module and the requirements module, copy the link information from the model to the surrogate module: 1 Open the sf_car_doors model.
6 IBM Rational DOORS Surrogate Module Synchronization Customize DOORS Synchronization In this section... “DOORS Synchronization Settings” on page 6-8 “Resynchronize a Model with a Different Surrogate Module” on page 6-10 “Customize the Level of Detail in Synchronization” on page 6-11 “Resynchronize to Include All Simulink Objects” on page 6-12 DOORS Synchronization Settings When you synchronize your Simulink model with a DOORS database, you can: • Customize the level of detail for your surrogate module.
Customize DOORS Synchronization DOORS Settings Option Description Copy unmatched links During synchronization, selecting the following options has the following results: • from Simulink to DOORS: For links between the model and the formal module, the RMI creates matching links between the DOORS surrogate and formal modules. • from DOORS to Simulink: For links between the DOORS surrogate and formal modules, the RMI creates matching links between the model and the DOORS modules.
6 IBM Rational DOORS Surrogate Module Synchronization DOORS Settings Option Description Save Simulink model (recommended) After the synchronization, saves changes to the model. If you use a version control system, selecting this option changes the version of the model. Resynchronize a Model with a Different Surrogate Module You can synchronize the same Simulink model with a new DOORS surrogate module.
Customize DOORS Synchronization 4 Click Continue to create a new surrogate module with the new path or name. Customize the Level of Detail in Synchronization You can customize the level of detail in a surrogate module so that the module reflects the full or partial Simulink model hierarchy. In “Synchronize a Simulink Model to Create a Surrogate Module” on page 6-5, you synchronized the model with the Extra mapping additionally to objects with links option set to None.
6 IBM Rational DOORS Surrogate Module Synchronization Drop-Down List Option Description Moderate - Unmasked subsystems, Stateflow charts, and superstates Adds Stateflow superstates to the surrogate module. Average - Nontrivial Simulink blocks, Stateflow charts and states Adds all Stateflow charts and states and Simulink blocks, except for trivial blocks such as ports, bus objects, and data-type converters, to the surrogate module.
Customize DOORS Synchronization 4 Update the surrogate module to include all objects in your model. To do this, under Extra mapping additionally to objects with links, from the drop-down list, select Complete - All blocks, subsystems, states and transitions. 5 Click Synchronize. After synchronization, the DOORS surrogate module for the sf_car_doors model opens with the updates. All Simulink objects and all Stateflow objects in the sf_car_doors model are now mapped in the surrogate module.
6 IBM Rational DOORS Surrogate Module Synchronization 6 Scroll through the surrogate module. Notice that the objects with requirements (the engine torque block and transmission subsystem) retain their links to the DOORS formal module, as indicated by the red triangles. 7 Save the surrogate module.
Resynchronize DOORS Surrogate Module to Reflect Model Changes Resynchronize DOORS Surrogate Module to Reflect Model Changes If you change your model after synchronization, the RMI does not display a warning message. If you want the surrogate module to reflect changes to the Simulink model, resynchronize your model.
6 IBM Rational DOORS Surrogate Module Synchronization 6-16 5 Delete the copied object (vehicle mph (yellow) & throttle %1 and resynchronize the model. 6 Save the surrogate module. 7 Save the sf_car_doors model.
Navigate with the Surrogate Module Navigate with the Surrogate Module In this section... “Navigate Between Requirements and the Surrogate Module in the DOORS Database” on page 6-17 “Navigate Between DOORS Requirements and the Simulink Module via the Surrogate Module” on page 6-18 Navigate Between Requirements and the Surrogate Module in the DOORS Database The surrogate module and the requirements in the formal module are both in the DOORS database.
6 IBM Rational DOORS Surrogate Module Synchronization 2 Select the object name. The surrogate module for sf_car_doors opens, at the object associated with the transmission subsystem. Navigate Between DOORS Requirements and the Simulink Module via the Surrogate Module You can create links that allow you to navigate from Simulink objects to DOORS requirements and from DOORS requirements to the model.
Navigate with the Surrogate Module Navigate from a Requirement to the Model via the Surrogate Module To navigate from the Transmission Requirements requirement in the formal module to the transmission subsystem in the sf_car_doors model: 1 In the formal module, in the Transmission Requirements object, right-click the left-facing orange arrow. 2 Select the path to the linked surrogate object: /sf_car Project/sf_car_doors > 4. transmission. The surrogate module opens, at the transmission object.
7 Navigation from Requirements Documents • “IBM Rational DOORS” on page 7-2 • “Microsoft Office” on page 7-10
7 Navigation from Requirements Documents IBM Rational DOORS In this section...
IBM Rational DOORS Follow the instructions in “Configure RMI for IBM Rational DOORS or Microsoft ActiveX Navigation” on page 2-12. Manually Install Additional Files for DOORS Software The setup script automatically copies the required DOORS files to the installation folders. However, the script might fail because of file permissions in your DOORS installation. If the script fails, change the file permissions on the DOORS installation folders and rerun the script.
7 Navigation from Requirements Documents b In a text editor, open the copiedFromDoors7.dxl file. c Add // before this line to comment it out: #include d Save and close the file. 5 Start the DOORS and MATLAB software. 6 Run the setup script using the following MATLAB command. rmi setup Enable Linking from DOORS Databases to Simulink Objects By default, the RMI does not insert navigation objects into requirements documents.
IBM Rational DOORS 5 Select Store absolute path to model file. For this exercise, you save a copy of the example model on the MATLAB path. If you add requirements to a model that is not on the MATLAB path, you must select this option to enable linking from your requirements document to your model. 6 In the Apply this user tag to new links field, enter one or more user tags to apply to the links that you create.
7 Navigation from Requirements Documents 6 Close the model. Note: When you navigate to a DOORS requirement from outside the software, the DOORS module opens in read-only mode. If you want to modify the DOORS module, open the module using DOORS software. Insert Navigation Objects to Multiple Simulink Objects If you have several Simulink objects that correspond to one requirement, you can link them all to that requirement with a single navigation object.
IBM Rational DOORS Customize DOORS Navigation Objects If the RMI is configured to modify destination for bi-directional linking as described in “Enable Linking from DOORS Databases to Simulink Objects” on page 7-4, the RMI can insert a navigation object into your requirements document. This object looks like the icon for the Simulink software: Note: In IBM Rational DOORS requirements documents, clicking a navigation object does not navigate back to your Simulink object.
7 Navigation from Requirements Documents Navigate Between DOORS Requirement and Model Object In “Insert Navigation Objects into DOORS Requirements” on page 7-5, you created a link between a DOORS requirement and the fuel_rate_control subsystem in the sldemo_fuelsys model. Navigate the links in both directions: 1 With the sldemo_fuelsys model closed, go to the DOORS requirement in the formal module. 2 Left-click the Simulink reference object that you inserted to select it.
IBM Rational DOORS Diagnose and Fix DXL Errors If you try to synchronize your Simulink model to a DOORS project, you might see the following errors: -E- DXL: incorrectly concatenated tokens -E- DXL: undeclared variable (dmiRefreshModule) -I- DXL: all done with 2 errors and 0 warnings If you see these errors, exit the DOORS software, rerun the rmi setup command at the MATLAB command prompt, and restart the DOORS software.
7 Navigation from Requirements Documents Microsoft Office In this section...
Microsoft Office To enable linking from a Microsoft Office document to the example model: 1 Open the model: slvnvdemo_fuelsys_officereq Note: You can modify requirements settings in the Requirements Settings dialog box. These settings are global and not specific to open models. Changes you make apply not only to open models, but also persist for models you subsequently open. For more information about these settings, see “Requirements Settings” on page 2-16.
7 Navigation from Requirements Documents 2 Select the Throttle Sensor header. 3 In the slvnvdemo_fuelsys_officereq model, open the engine gas dynamics subsystem. 4 Right-click the Throttle & Manifold subsystem and select Requirements Traceability > Link to Selection in Word. 5 The RMI inserts an URL-based link into the requirements document.
Microsoft Office Note: In Microsoft Office requirements documents, following a navigation object link highlights the Simulink object that contains a bi-directional link to the associated requirement. To use an icon of your own choosing for the navigation object: 1 Select Analysis > Requirements Traceability > Settings. 2 Select the Selection Linking tab. 3 Select Modify destination for bi-directional linking.
7 Navigation from Requirements Documents 2 In the requirements document, next to Throttle Sensor, follow the navigation object link. The engine gas dynamics subsystem opens, with the Throttle & Manifold subsystem highlighted. Navigation from Microsoft Office requirements documents is not automatically enabled upon MATLAB startup.
Microsoft Office a document created in an earlier version and then save it in Microsoft Word 2007 format, make sure that the links to the models continue to work: 1 Open a requirements document saved in a release of Microsoft Word earlier than Microsoft Word 2007. 2 Depending on which version of Microsoft Word you are running, do one of the following: • In Microsoft Word 2007, in the upper-left corner, click the Microsoft Office Button. • In Microsoft Word 2010, select the File tab.
7 Navigation from Requirements Documents Note: You might need to enable ActiveX controls in the Microsoft Office Trust Center. Field Codes in Requirements Documents If your Microsoft Word requirements document displays the field codes in addition to, or instead of, the ActiveX icon, clear the Show field codes instead of their values option. The following graphic shows a requirements document created in Microsoft Word 2003, with the field codes (CONTROL mwSimulink1.SLRefButton \s) displayed.
Microsoft Office • In Microsoft Word 2010, select File > Options. 2 In the left-hand portion of the pane, click Advanced. 3 In the Advanced pane, scroll to the Show document content section and clear the Show field codes instead of their values option.
7 Navigation from Requirements Documents ActiveX Control Does Not Link to Model Object If you click an ActiveX control that links to a Simulink or Stateflow object, and the object does not open, do one of the following: • Store your requirements documents in trusted locations, as described in the Microsoft Office 2007 documentation. The Trust Center does not check files for ActiveX controls stored in trusted locations, so you can maintain your Trust Center restrictions.
Microsoft Office 5 Select the setting that you want for ActiveX controls: • Prompt me for enabling all controls with minimal restrictions to decide each time you click an ActiveX control if you want to enable all controls. • Enable all controls without restrictions and without prompting to enable all ActiveX controls whenever you open the document. 6 Close the open dialog boxes. 7 Restart the application for the settings to take effect.
7 Navigation from Requirements Documents 2 In the pane that opens, at the bottom, click Excel Options. 3 In the Microsoft Excel Options dialog box, in the left-hand pane, click Popular. 4 On the Popular pane, in the Top options for working with Excel section, select Show Developer tab in the Ribbon. 5 Click OK. 6 In the Ribbon, on the Developer tab, select Design Mode. When you select Design Mode, the ActiveX control is no longer visible in the cell.
8 MATLAB Code Traceability • “Link Between MATLAB Code Lines and Requirements Information in External Documents” on page 8-2 • “Enable or Disable Highlighting of Traceability Links for MATLAB Code” on page 8-4 • “Remove Traceability Links from MATLAB Code Lines” on page 8-5 • “Traceability for MATLAB Code Lines” on page 8-6 • “Associate Traceability Information with MATLAB Code Lines in Simulink” on page 8-8
8 MATLAB Code Traceability Link Between MATLAB Code Lines and Requirements Information in External Documents In this section... “Create Link Using Context Menu Shortcuts” on page 8-2 “Create Link Using Link Editor” on page 8-2 Create Link Using Context Menu Shortcuts To create requirements traceability links from MATLAB code lines to selections in Microsoft Word, Microsoft Excel, or IBM Rational DOORS documents, you can use shortcuts in the Requirements Traceability context menu.
Link Between MATLAB Code Lines and Requirements Information in External Documents • From the context menu, select Requirements Traceability > Open Link Editor. For detailed information on the Link Editor, see “Requirements Traceability Link Editor”.
8 MATLAB Code Traceability Enable or Disable Highlighting of Traceability Links for MATLAB Code In this section... “Enable Traceability Highlighting of MATLAB Code” on page 8-4 “Disable Traceability Highlighting of MATLAB Code” on page 8-4 Enable Traceability Highlighting of MATLAB Code To highlight traceability links in your MATLAB code, do one of the following: • In the View tab, in the Display section, select Highlight Traceability.
Remove Traceability Links from MATLAB Code Lines Remove Traceability Links from MATLAB Code Lines In this section... “Delete Links to Requirements from MATLAB Code Lines” on page 8-5 “Delete Link Targets in MATLAB Code Lines” on page 8-5 Delete Links to Requirements from MATLAB Code Lines To remove requirements traceability links from a line or lines of MATLAB code: 1 In the MATLAB Editor, right-click within a range of code that has requirements traceability links.
8 MATLAB Code Traceability Traceability for MATLAB Code Lines In this section... “Traceability Link Targets” on page 8-6 “Storage of Traceability Links” on page 8-6 “Limitations of MATLAB Code Traceability” on page 8-7 Traceability Link Targets You can create MATLAB code traceability links for: • Lines of MATLAB code in a standalone file. • Lines of MATLAB code inside a MATLAB Function block. You can create links from a line or lines of MATLAB code to: • Objects in Simulink models.
Traceability for MATLAB Code Lines If you want to create traceability links for lines of code in a MATLAB Function block, set the parent model to store requirements data externally. For a new model, see “Specify Storage for Requirements Links”. For an existing model, see “Move Internally Stored Requirements Links to External Storage”. When you create traceability links for code inside a MATLAB Function block, the RMI stores them in a .req file for the parent model. The .
8 MATLAB Code Traceability Associate Traceability Information with MATLAB Code Lines in Simulink Traceability management support in the MATLAB Editor is an extension of the Simulink-based Requirements Management Interface to allow associations between MATLAB code lines and external artifacts. This capability does not require editing MATLAB files; all traceability data is stored separately. This is similar to "external" storage of RMI links when working with Simulink models.
Associate Traceability Information with MATLAB Code Lines in Simulink Two MATLAB Functions between neurons calculate post-synaptic currents. When presynaptic depolarization crosses the neurotransmitter release threshold, we increment post-synaptic current by one pulse of given amplitude: Resulting total current decays exponentially according to We disallow the next increment for a certain timeframe after the previous pulse, to model the effect of short-term synaptic depression.
8 MATLAB Code Traceability 8-10
Associate Traceability Information with MATLAB Code Lines in Simulink 8-11
8 MATLAB Code Traceability Simulate Model and View Results Simulate slvnvdemo_synaptic_transmission model. Check Scope for results. The six plots are: • externally injected electrical current pulse, • injection-stimulated intracellular voltage spiking of the first neuron, • post-synaptic current generated in the second neuron, • synaptically stimulated activity of the second neuron, • post-synaptic current generated in the third neuron, • synaptically stimulated activity of the third neuron.
Associate Traceability Information with MATLAB Code Lines in Simulink file and navigate back to Simulink by selecting the shortcut in the Requirements Traceability context menu. rmi('highlightModel', 'slvnvdemo_synaptic_transmission'); rmipref('BiDirectionalLinking',true); Create Traceability Link for Lines of MATLAB Code The Synaptic time constant block in the bottom left corner of the model is not yet linked to its related line in parameters script.
8 MATLAB Code Traceability 8-14
Associate Traceability Information with MATLAB Code Lines in Simulink Create Traceability Link for Lines of Code Inside MATLAB Function Blocks The slvnvdemo_synaptic_transmission model has a MATLAB Function block that we will want to trace to parameter value sources. Instead of linking the block itself, open the MATLAB code of this block and link specific lines. For example, in the Simulink Editor, click on the Synaptic strength constant block to select it for linking.
8 MATLAB Code Traceability 8-16
Associate Traceability Information with MATLAB Code Lines in Simulink Report Traceability Links Traceability links associated with MATLAB code lines of MATLAB Function blocks are included in the Requirements Traceability Report generated for the parent Simulink model. Use Analysis > Requirements Traceability > Generate Report in slvnvdemo_neuron model window to generate the report. See MATLAB Function block links information present in the report, including quotations of linked MATLAB Code lines.
8 MATLAB Code Traceability 8-18
Associate Traceability Information with MATLAB Code Lines in Simulink 8-19
9 Custom Types of Requirements Documents • “Why Create a Custom Link Type?” on page 9-2 • “Implement Custom Link Types” on page 9-3 • “Custom Link Type Functions” on page 9-4 • “Links and Link Types” on page 9-5 • “Link Type Properties” on page 9-6 • “Custom Link Type Registration” on page 9-10 • “Create a Custom Requirements Link Type” on page 9-11 • “Custom Link Type Synchronization” on page 9-19 • “Navigate to Simulink Objects from External Documents” on page 9-20
9 Custom Types of Requirements Documents Why Create a Custom Link Type? In addition to linking to built-in types of requirements documents, you can register custom requirements document types with the Requirements Management Interface (RMI). Then you can create requirement links from your model to these types of documents.
Implement Custom Link Types Implement Custom Link Types To implement a custom link type: 1 Create a MATLAB function file based on the custom link type template, as described in “Custom Link Type Functions” on page 9-4. 2 Customize the custom link type file to specify the link type properties and custom callback functions required for the custom link type, as described in “Link Type Properties” on page 9-6.
9 Custom Types of Requirements Documents Custom Link Type Functions To create a MATLAB function file, start with the custom link type template, located in: matlabroot/toolbox/slvnv/reqmgt/linktypes/linktype_TEMPLATE.m Your custom link type function: • Must exist on the MATLAB path with a unique function and file name. • Cannot require input arguments. • Must return a single output argument that is an instance of the requirements link type class.
Links and Link Types Links and Link Types Requirements links are the data structures, managed by Simulink, that identify a specific location within a document. You get and set the links on a block using the rmi command. Links and link types work together to perform navigation and manage requirements. The doc and id fields of a link uniquely identify the linked item in the external document. The RMI passes both of these strings to the navigation command when you navigate a link from the model.
9 Custom Types of Requirements Documents Link Type Properties Link type properties define how links are created, identified, navigated to, and stored within the requirement management tool. The following table describes each of these properties. Property Description Registration The name of the function that creates the link type. The RMI stores this name in the Simulink model. Label A string to identify this link type.
Link Type Properties Property Description ContentsFcn The MATLAB callback invoked when you click the Document Index tab in the Requirements Traceability Link Editor. This function has a single input argument that contains the full path of the resolved function or, if the link type is not a file, the Document field contents. The function returns three outputs: • Labels • Depths • Locations BrowseFcn The MATLAB callback invoked when you click Browse in the Requirements Traceability Link Editor.
9 Custom Types of Requirements Documents Property Description IsValidIdFcn The MATLAB callback invoked when you run a requirements consistency check. This function takes two input arguments: • Fully qualified name for the requirements document • Location of the requirement in the document IsValidIdFcn returns true if it finds the requirement and false if it cannot find that requirement in the specified document. IsValidDescFcn The MATLAB callback invoked when you run a requirements consistency check.
Link Type Properties Property Description DetailsFcn The MATLAB callback invoked when you generate the requirements report with the Include details from linked documents option.
9 Custom Types of Requirements Documents Custom Link Type Registration Register your custom link type by passing the name of the MATLAB function file to the rmi command as follows: rmi register mytargetfilename Once you register a link type, it appears in the “Requirements Traceability Link Editor” as an entry in the Document type drop-down list. A file in your preference folder contains the list of registered link types, so the custom link type is loaded each time you run MATLAB.
Create a Custom Requirements Link Type Create a Custom Requirements Link Type In this example, you implement a custom link type to a hypothetical document type, a text file with the extension .abc. Within this document, the requirement items are identified with a special text string, Requirement::, followed by a single space and then the requirement item inside quotation marks ("). You will create a document index listing all the requirement items.
9 Custom Types of Requirements Documents % Create a default (blank) requirement link type linkType = ReqMgr.LinkType; linkType.Registration = mfilename; % Label describing this link type linkType.Label = 'ABC file (for demonstration)'; % File information linkType.IsFile = 1; linkType.Extensions = {'.abc'}; % Location delimiters linkType.LocDelimiters = '>@'; linkType.Version = ''; % not required % Uncomment the functions that are implemented below linkType.NavigateFcn = @NavigateFcn; linkType.
Create a Custom Requirements Link Type function [labels, depths, locations] = ContentsFcn(filePath) % Read the entire file into a variable fid = fopen(filePath,'r'); contents = char(fread(fid)'); fclose(fid); % Find all the requirement items fList1 = regexpi(contents,'\nRequirement:: "(.
9 Custom Types of Requirements Documents The user-selectable climb rate is always a positive number if the current altitude is above the target altitude. The actual target climb rate is the negative of the user setting.
Create a Custom Requirements Link Type ENd of "Autopilot Disable" Requirement:: "Glide Slope Armed" Glide Slope Control is armed when Glide Slope Enable and Glide Slope Signal are both true. Units: Glide Slope Enable - Logical Glide Slope Signal - Logical Description: ILS Glide Slope Control of altitude is only enabled when the pilot has enabled this mode and the Glide Slope Signal is true. This indicates the Glide Slope broadcast signal has been validated by the on board receiver.
9 Custom Types of Requirements Documents negative of the user setting. End of "Glide Slope Coupled" 5 Open the following example model: aero_dap3dof 6 Right-click the Reaction Jet Control subsystem and select Requirements Traceability > Open Link Editor. The Requirements Traceability Link Editor opens. 7 Click New to add a new requirement link. The Document type drop-down list now contains the ABC file (for demonstration) option.
Create a Custom Requirements Link Type Note: The rmi reference page describes other types of requirements location delimiters. The Location drop-down list contains these two types of location delimiters whenever you set Document type to ABC file (for demonstration). 10 Select Line number. Enter the number 26, which corresponds with the line number for the Altitude Hold requirement in demo_req_1.abc. 11 In the Description field, enter Altitude Hold, to identify the requirement by name. 12 Click Apply.
9 Custom Types of Requirements Documents 9-18
Custom Link Type Synchronization Custom Link Type Synchronization Simulink Verification and Validation provides an API for synchronization of links for custom requirements documents. To support synchronization for your custom requirements link type, create a custom type implementation in a new subclass and inherit from the rmisync.SyncApi base class in the Requirements Management Interface API.
9 Custom Types of Requirements Documents Navigate to Simulink Objects from External Documents The RMI includes several functions that simplify creating navigation interfaces in external documents. The external application that displays your document must support an application programming interface (API) for communicating with the MATLAB software.
Navigate to Simulink Objects from External Documents Use the ActiveX Navigation Control The RMI uses software that includes a special Microsoft ActiveX control to enable navigation to Simulink objects from Microsoft Word and Excel documents. You can use this same control in any other application that supports ActiveX within its documents. The control is derived from a push button and has the Simulink icon. There are two instance properties that define how the control works.
9 Custom Types of Requirements Documents 5 Create a navigation item in the external document using the scripting capability of the external tool. Set the MATLAB navigation command string in the property. When using ActiveX navigation objects provided by the external tool, set the MLEvalCmd property to the navCmd and set the tooltipstring property to objPath. You define the MATLAB code implementation of this procedure as the SelectionLinkFcn function in the link type definition file.
10 Requirements Information in Generated Code • “How Requirements Information Is Included in Generated Code” on page 10-2 • “Generate Code for Models with Requirements Links” on page 10-4
10 Requirements Information in Generated Code How Requirements Information Is Included in Generated Code After you simulate your model and verify its performance against the requirements, you can generate code from the model for an embedded real-time application. The Embedded Coder® software generates code for Embedded Real-Time (ERT) targets. If the model has any links to requirements, the Embedded Coder software inserts information about the requirements links into the code comments.
How Requirements Information Is Included in Generated Code Model Object with Requirement Location of Code Comments with Requirements Links Nonsubsystem block In the generated code for the block MATLAB code line in MATLAB Function block In the generated code for the MATLAB code line(s) 10-3
10 Requirements Information in Generated Code Generate Code for Models with Requirements Links To specify that generated code of an ERT target include requirements: 1 Open the rtwdemo_requirements example model. 2 Select Simulation > Model Configuration Parameters. 3 In the Select tree of the Configuration Parameters dialog box, select the Code Generation node. The currently configured system target must be an ERT target. 4 Under Code Generation, select Comments.
Generate Code for Models with Requirements Links 11 Click the link Clock period shall be consistent with chirp tolerance to open the HTML requirements document to the associated requirement. Note: When you click a requirements link in the code comments, the software opens the application for the requirements document, except if the requirements document is a DOORS module. To view a DOORS requirement, start the DOORS software and log in before clicking the hyperlink in the code comments.
Model Component Testing
11 Overview of Component Verification • “Component Verification” on page 11-2 • “Basic Approach to Component Verification” on page 11-4 • “Functions for Component Verification” on page 11-8
11 Overview of Component Verification Component Verification In this section...
Component Verification components individually, you can create test cases that fully specify the component interface, allowing the component to record 100% coverage. • Debug the component — To verify that each model component satisfies the specified design requirements, you can create test cases that verify that specific components perform as designed.
11 Overview of Component Verification Basic Approach to Component Verification In this section... “Workflow for Component Verification” on page 11-4 “Verify a Component Independently of the Container Model” on page 11-6 “Verify a Model Block in the Context of the Container Model” on page 11-7 Workflow for Component Verification The following graphic illustrates the common workflow for component verification.
Basic Approach to Component Verification • For closed-loop simulations, verify a component within the context of its container model by logging the signals to that component and storing them in a data file. If those signals do not constitute a complete test suite, generate a harness model and add or modify the test cases in the Signal Builder.
11 Overview of Component Verification Verify a Component Independently of the Container Model Use component analysis to verify: • Model blocks • Atomic subsystems • Stateflow atomic subcharts The recommended steps for verifying a component independently of the container model: 1 Depending on the type of component, take one of the following actions: • Model blocks — Open the referenced model. • Atomic subsystems — Extract the contents of the subsystem into its own Simulink model.
Basic Approach to Component Verification Verify a Model Block in the Context of the Container Model Use system analysis to verify a Model block in the context of the block's container model. Use this technique when you analyze a closed-loop controller. The recommended steps for system analysis: 1 Log the input signals to the component by simulating the container model. or Analyze the model using the Simulink Design Verifier™ software.
11 Overview of Component Verification Functions for Component Verification The Simulink Verification and Validation software provides several functions that facilitate the tasks associated with component verification. Task Function Simulate a Simulink model and log input signals to a slvnvlogsignals Model block in the model. If you modify the test cases in the Signal Builder harness model, use this approach for logging input signals to the harness model itself.
Functions for Component Verification • Multiword fixed-point data types 11-9
12 Verifying Generated Code for a Component
12 Verifying Generated Code for a Component Verify Generated Code for a Component In this section...
Verify Generated Code for a Component The Model block references the slvnvdemo_powerwindow_controller model. The referenced model contains a Stateflow chart control, which implements the logic for the power window controller.
12 Verifying Generated Code for a Component Prepare the Component for Verification To verify the referenced model slvnvdemo_powerwindow_controller, you need to create a harness model that contains the input signals that simulate the controller in the plant model. Perform the following steps: 1 Open the slvnvdemo_powerwindow example model: slvnvdemo_powerwindow 2 Open the power_window_control_system subsystem.
Verify Generated Code for a Component slvnvlogsignals stores the logged signals in loggedSignalsPlant. 5 Generate an empty harness model so that you can create new test cases manually: harnessModelFilePath = ... slvnvmakeharness('slvnvdemo_powerwindow_controller'); slvnvmakeharness creates a harness model named slvnvdemo_powerwindow_controller_harness. The harness model includes: • Test Unit — A Model block that references the slvnvdemo_powerwindow_controller model.
12 Verifying Generated Code for a Component 6 Save the name of the harness model for use later in this example: [~,harnessModel] = fileparts(harnessModelFilePath); 7 Leave all models open for the next part of this example. Next, create a test case that tests values for input signals to the component. Create and Log Test Cases Add a test case for your component to help you get closer to achieving 100% coverage.
Verify Generated Code for a Component 2 Add the new test case to the Signal Builder block in the harness model. signalBuilderBlock = slvnvdemo_signalbuilder_block(harnessModel); signalbuilder(signalBuilderBlock,'Append',... newTestTime, newTestData,... {'endstop','obstacle','driver(1)','driver(2)','driver(3)',...
12 Verifying Generated Code for a Component runopts = slvnvruntestopts; 2 Specify to simulate the model, and record coverage: runopts.coverageEnabled = true; 3 Simulate the model using the logged input signals: [~, covdata] = slvnvruntest('slvnvdemo_powerwindow_controller',...
Verify Generated Code for a Component runcgvopts.cgvConn = 'sim'; 3 Execute the slvnv_powerwindow_controller model using the two test cases and the runopts object: cgvSim = slvnvruncgvtest('slvnvdemo_powerwindow_controller', ... mergedTestCases, runcgvopts); These steps save the results in the workspace variable cgvSim. Next, execute the same model with the same test cases in Software-in-the-Loop (SIL) mode and compare the results from both simulations.
12 Verifying Generated Code for a Component silout = cgvSil.getOutputData(i); [matchNames, ~, mismatchNames, ~ ] = ... cgv.CGV.compare(simout, silout); 4 Display the results of the comparison in the MATLAB command window: fprintf('\nTest Case(%d): %d Signals match, ... %d Signals mismatch', i, length(matchNames), ...
Signal Monitoring with Model Verification Blocks
13 Using Model Verification Blocks • “Model Verification Blocks and the Verification Manager” on page 13-2 • “Use Check Static Lower Bound Block to Check for Out-of-Bounds Signal” on page 13-3 • “Linear System Modeling Blocks in Simulink Control Design” on page 13-6
13 Using Model Verification Blocks Model Verification Blocks and the Verification Manager Simulink Model Verification library blocks monitor time-domain signals in your model during simulation, according to the specifications that you assign to the blocks. Note: To see a complete description of all Simulink model verification blocks, see the “Model Verification” category in the Simulink documentation. You set a verification block to assert when its signal leaves the limit or range that you specify.
Use Check Static Lower Bound Block to Check for Out-of-Bounds Signal Use Check Static Lower Bound Block to Check for Out-of-Bounds Signal The following example uses a Check Static Lower Bound block to stop simulation when a signal from a Sine Wave block crosses its lower bound limit. 1 Attach a Check Static Lower Bound block to the signal from a Sine Wave block. 2 Set the Simulation stop time to 2 seconds. 3 Double-click the Sine Wave block and set the following parameters: • Set the Amplitude to 1.
13 Using Model Verification Blocks 6 13-4 To verify the signal value, double-click the Scope block.
Use Check Static Lower Bound Block to Check for Out-of-Bounds Signal 7 To disable the Check Static Lower Bound block from asserting its limit, clear the Enable assertion check box. The block is crossed out in the model, as shown.
13 Using Model Verification Blocks Linear System Modeling Blocks in Simulink Control Design If you have Simulink Control Design software, you can: • Specify bounds on linear system characteristics. • Check that the bounds are satisfied during simulation. For example, you can check if the linearized behavior of your model satisfied upper and lower magnitude bounds on a Bode plot or gain and phase margins.
14 Constructing Simulation Tests Using the Verification Manager • “What Is the Verification Manager?” on page 14-2 • “Construct Simulation Tests Using the Verification Manager” on page 14-3
14 Constructing Simulation Tests Using the Verification Manager What Is the Verification Manager? The Verification Manager is a graphical interface in the Signal Builder dialog box. Using this tool, you can manage all the Model Verification blocks in your model from a central location.
Construct Simulation Tests Using the Verification Manager Construct Simulation Tests Using the Verification Manager In this section...
14 Constructing Simulation Tests Using the Verification Manager In the example model, the contents of the subsystem are as follows. a 14-4 In the Signal Builder block, create a signal group with five signals in the group.
Construct Simulation Tests Using the Verification Manager b Make two copies of the signal group, so that you have three signal groups: Group 1, Group 2, Group 3. Note: A Signal Builder block provides test signals for an entire model from one location. This model contains a Signal Builder block that feeds five test signals to the Model Verification blocks. The model sends the first four signals directly to Check Static Upper Bound blocks.
14 Constructing Simulation Tests Using the Verification Manager 4 On the Signal Builder dialog box toolbar, select the Show Verification Settings tool . The Verification block settings pane and the Requirements pane are displayed.
Construct Simulation Tests Using the Verification Manager The Verification block settings pane lists all Model Verification blocks in the model, grouped by subsystem. If you right-click in this pane, you can select on of three options for viewing Model Verification blocks in this window: • Display > Tree format — If enabled, lists the blocks as they appear in the model hierarchy. • Display > Overridden blocks only — If enabled, lists only the blocks that have been disabled.
14 Constructing Simulation Tests Using the Verification Manager • Display > Active blocks only — If enabled, lists only the blocks that are enabled. Note: If both Overridden blocks only and Active blocks only are enabled, no Model Verification blocks appear. If both Overridden blocks only and Active blocks only are disabled, all Model Verification blocks appear. In this example, the Verification block settings pane displays five Check Static Upper Bound blocks.
Construct Simulation Tests Using the Verification Manager Enable and Disable Model Verification Blocks in a Model Use the Verification Manager to enable and disable individual Model Verification blocks in signal groups. To open the Verification Manager in the Signal Builder dialog box, click . The Verification block settings pane lists the Model Verification blocks in the model. Each verification block has a status node that indicates whether its assertion is enabled or disabled.
14 Constructing Simulation Tests Using the Verification Manager Because you enabled the Check Static Upper Bound1 block in the current group, an Override label is applied to the block and it is no longer crossed out. 14-10 2 In the Signal Builder, from the Active Group list, select Group 2. 3 Select the empty check box next to the Check Static Upper Bound2 node to enable that block for the current group (Group 2).
Construct Simulation Tests Using the Verification Manager The Check Static Upper Bound2 block is no longer crossed out, indicating that the block is enabled for the current group. Check Static Upper Bound1, however, is crossed out because it is enabled in a different group.
14 Constructing Simulation Tests Using the Verification Manager 4 Save the model with these changes. Enable and Disable Model Verification Blocks in a Subsystem If you have a lot of verification blocks, it is tedious to enable and disable blocks individually. Using the Verification Manager, you can enable and disable blocks from context menu options. Depending on the status of the node, you have the following options.
Construct Simulation Tests Using the Verification Manager Node Status Context Menu Options • Contents group enable • Contents group disable • Block enable by group • Block enable for all groups • Block group enable • Block enable for all groups • Block group disable For example, assume that you define the following groups in the Verification Manager for a model with five Model Verification blocks.
14 Constructing Simulation Tests Using the Verification Manager This option restores the individually enabled/disabled settings for each verification block in each group. Group 1 3 Group 2 Group 3 From the Active Group list, select Group 1. Right-click ex_verif_mgr_test_signals, and select Contents group enable. This option individually enables all contained blocks for only Group 1. Group 1 4 Group 2 (unchanged) Group 3 (unchanged) From the Active Group list, select Group 1.
Construct Simulation Tests Using the Verification Manager 5 From the Active Group list, select Group 1. Right-click the Check Static Upper Bound node, and select Block enable for all groups. This option enables the Check Static Upper Bound block for all groups. Group 1 6 Group 2 Group 3 From the Active Group list, select Group 1. Right-click the Check Static Upper Bound node, and select Block enable by group. This option restores the individually enabled/disabled state to this block for all groups.
14 Constructing Simulation Tests Using the Verification Manager Group 1 Group 2 (unchanged) Group 3 (unchanged) Selecting Block group disable disables the specified block for this group only. Use Check Static Lower Bound Block to Check for Out-of-Bounds Signal The following example uses a Check Static Lower Bound block to stop simulation when a signal from a Sine Wave block crosses its lower bound limit. 1 Attach a Check Static Lower Bound block to the signal from a Sine Wave block.
Construct Simulation Tests Using the Verification Manager 0.8 or lower. If the signal value reaches that value or falls below it, the simulation stops. 5 Run the simulation. The model stops simulating after 1.295 seconds, when the output is –0.8. The software highlights the Check Static Lower Bound block. When the simulation stops, you see the following diagnostic message. 6 To verify the signal value, double-click the Scope block.
14 Constructing Simulation Tests Using the Verification Manager 7 To disable the Check Static Lower Bound block from asserting its limit, clear the Enable assertion check box. The block is crossed out in the model, as shown.
Construct Simulation Tests Using the Verification Manager Link Test Cases to Requirements Documents Using the Verification Manager You can link requirements documents to test cases and their corresponding Model Verification blocks through the Verification Manager Requirements pane in the Signal Builder.
14 Constructing Simulation Tests Using the Verification Manager 14-20 6 To view the requirements document in its native editor, right-click a requirement link and select View. 7 Optionally, to delete a requirement link, right-click the link and select Delete.
Model Coverage Analysis
15 Model Coverage Definition • “Model Coverage” on page 15-2 • “Types of Model Coverage” on page 15-3 • “Simulink Optimizations and Model Coverage” on page 15-11
15 Model Coverage Definition Model Coverage Model coverage helps you validate your model tests by measuring how thoroughly the model objects are tested. Model coverage calculates how much a model test case exercises simulation pathways through a model. Model coverage is a measure of how thoroughly a test case tests a model and the percentage of pathways that a test case exercises. Model coverage helps you validate your model tests.
Types of Model Coverage Types of Model Coverage Simulink Verification and Validation software can perform several types of coverage analysis. In this section...
15 Model Coverage Definition For an example of cyclomatic complexity data in a model coverage report, see “Cyclomatic Complexity” on page 19-22. Condition Coverage (CC) Condition coverage analyzes blocks that output the logical combination of their inputs (for example, the Logical Operator block) and Stateflow transitions.
Types of Model Coverage indicating each interpolation. If the total number of breakpoints of an n-D Lookup Table block exceeds 1,500,000, the software cannot record coverage for that block. For an example of lookup table coverage data in a model coverage report, see “NDimensional Lookup Table” on page 19-30. Note: Configure lookup table coverage only at the start of a simulation.
15 Model Coverage Definition • Condition Coverage • Decision Coverage • MCDC Coverage When you collect coverage for a model, you may not be able to achieve 100% MCDC coverage. For example, if you specify to short-circuit logic blocks, you may not be able to achieve 100% MCDC coverage for that block. If you run the test cases independently and accumulate all the coverage results, you can determine if your model adheres to the modified condition and decision coverage standard.
Types of Model Coverage Data Type of Operand Tolerance Floating point, such as single or double max(absTol, relTol* max(|lhs|,| rhs|)) • absTol is an absolute tolerance value you specify. Default is 1e-05. • relTol is a relative tolerance value you specify. Default is 0.01. • lhs is the left operand and rhs the right operand. • max(x,y) returns x or y, whichever is greater. Fixed point Value corresponding to least significant bit. For more information, see “Precision”.
15 Model Coverage Definition • Which model objects receive this coverage, see the table in “Model Objects That Receive Coverage”. • How to obtain coverage results from the MATLAB command-line, see “Collect Relational Boundary Coverage for Supported Block in Model”. Saturate on Integer Overflow Coverage Saturate on integer overflow coverage examines blocks, such as the Abs block, with the Saturate on integer overflow parameter selected.
Types of Model Coverage Signal Size Coverage Signal size coverage records the minimum, maximum, and allocated size for all variablesize signals in a model. Only blocks with variable-size output signals are included in the report. If the total number of signals in your model exceeds 65535, or your model contains a signal whose width exceeds 65535, the software cannot record signal size coverage.
15 Model Coverage Definition • Analyze the model and use the Proof Assumption block to verify any counterexamples that the Simulink Design Verifier identifies. If you specify to collect Simulink Design Verifier coverage: • The software collects coverage for the Simulink Design Verifier blocks and functions. • The software checks the data type of the signal that links to each Simulink Design Verifier block. If the signal data type is fixed point, the block parameter must also be fixed point.
Simulink Optimizations and Model Coverage Simulink Optimizations and Model Coverage In the Configuration Parameters dialog box Optimization pane, there are three Simulink optimization parameters that can affect your model coverage data: In this section...
15 Model Coverage Definition Conditional input branch execution To improve model execution when the model contains Switch and Multiport Switch blocks, in the Configuration Parameters dialog box, on the Optimization pane, select Conditional input branch execution. If you select this parameter, the simulation executes only blocks that are required to compute the control input and the data input selected by the control input.
16 Model Objects That Receive Model Coverage
16 Model Objects That Receive Model Coverage Model Objects That Receive Coverage Certain Simulink objects can receive any type of model coverage. Other Simulink objects can receive only certain types of coverage, as the following table shows. Click a link in the first column to get more detailed information about coverage for specific model objects. For Stateflow states, events, and state temporal logic decisions, model coverage provides only decision coverage.
Model Objects That Receive Coverage Model Object Decision Condition MCDC Lookup Table Simulink Design Verifier Saturate Relational on Integer Boundary Overflow “Discrete Filter” on page 16-11 “Discrete FIR Filter” on page 16-11 “Discrete-Time Integrator” on page 16-11 (when saturation limits are enabled or reset) “Discrete Transfer Fcn” on page 16-12 “Dot Product” on page 16-13 “Enabled Subsystem” on page 16-13 “Enabled and Triggered Subsystem” on page 16-13 “Fcn” on page 16-14 “For Iterator, For It
16 Model Objects That Receive Model Coverage Model Object “If, If Action Subsystem” on page 16-16 “Interpolation Using Prelookup” on page 16-16 “Library-Linked Objects” on page 16-17 “Logical Operator” on page 16-17 “1-D Lookup Table” on page 16-18 “2-D Lookup Table” on page 16-18 “n-D Lookup Table” on page 16-19 “Math Function” on page 16-20 “MATLAB Function” on page 16-20 “MinMax” on page 16-20 16-4 Decision Condition MCDC Lookup Table Simulink Design Verifier Saturate Relational on Integer Bound
Model Objects That Receive Coverage Model Object Decision Condition MCDC Lookup Table Simulink Design Verifier Saturate Relational on Integer Boundary Overflow “Model” on page 16-20 See also “Triggered Models” on page 16-29.
16 Model Objects That Receive Model Coverage Model Object “C/C++ SFunction” on page 16-25 “Saturation” on page 16-26 “Saturation Dynamic” on page 16-26 “Simulink Design Verifier Functions in MATLAB Function Blocks” on page 16-27 Stateflow charts Stateflow state transition tables “Sqrt, Signed Sqrt, Reciprocal Sqrt” on page 16-27 “Sum, Add, Subtract, Sum of Elements” on page 16-27 “Switch” on page 16-27 “SwitchCase, SwitchCase Action Subsystem” on page 16-28 16-6 Decision Condition MCDC Lookup Table S
Model Objects That Receive Coverage Model Object Decision Condition MCDC Lookup Table Simulink Design Verifier Saturate Relational on Integer Boundary Overflow “Test Condition” on page 16-28 “Test Objective” on page 16-29 “Triggered Models” on page 16-29 “Triggered Subsystem” on page 16-30 “Truth Table” on page 16-31 “Unary Minus” on page 16-31 “Weighted Sample Time Math” on page 16-31 “While Iterator, While Iterator Subsystem” on page 16-31 Abs The Abs block receives decision coverage.
16 Model Objects That Receive Model Coverage • The number of time steps that the block input is less than zero, indicating a true decision. • The number of time steps the block input is not less than zero, indicating a false decision. If you select the Saturate on integer overflow coverage metric, the Abs block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”.
Model Objects That Receive Coverage table values. Because this block always has at least one value in the truth table as output, the minimum coverage reported is one divided by the total number of truth table values. If all block inputs are false for at least one time step and true for at least one time step, condition coverage is 100%.
16 Model Objects That Receive Model Coverage Data Type Conversion If you select the Saturate on integer overflow coverage metric, the Data Type Conversion block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”. Dead Zone The Dead Zone block receives decision coverage.
Model Objects That Receive Coverage Direct Lookup Table (n-D) The Direct Lookup Table (n-D) block receives lookup table coverage. For an ndimensional lookup table, the number of output break points is the product of all the number of break points for each table dimension. Lookup table coverage measures: • The number of times during simulation that each combination of dimension input values is between each of the break points.
16 Model Objects That Receive Model Coverage • External reset • Limit output If you set External reset to none, the Simulink Verification and Validation software does not report decision coverage for the reset decision. Otherwise, the decision coverage measures: • The number of time steps that the block output is reset, indicating a true decision. • The number of time steps that the block output is not reset, indicating a false decision.
Model Objects That Receive Coverage Dot Product If you select the Saturate on integer overflow coverage metric, the Dot Product block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”. Enabled Subsystem The Enabled Subsystem block receives decision, condition, and MCDC coverage. Decision coverage measures: • The number of time steps that the block is enabled, indicating a true decision.
16 Model Objects That Receive Model Coverage If at least one time step is true and at least one time step is false, decision coverage is 100%. If no time steps are true, or if no time steps are false, decision coverage is 50%. The software measures condition coverage for the enable input and for the trigger input separately: • For the enable input, condition coverage measures the number of time steps the enable input is true and the number of time steps the enable input is false.
Model Objects That Receive Coverage • The number of time steps that each input to a Boolean operator is false (equal to zero). If all Boolean operator inputs are false for at least one time step and true for at least one time step, condition coverage is 100%. Otherwise, the software reports condition coverage based on the total number of possible conditions and how many are true for at least one time step and how many are false for at least one time step.
16 Model Objects That Receive Model Coverage If, If Action Subsystem The If block that causes an If Action Subsystem to execute receives condition, decision, and MCDC coverage: • The software measures decision coverage for the if condition and all elseif conditions defined in the If block.
Model Objects That Receive Coverage increasing white-to-green color scale, with six evenly spaced data ranges starting with zero, indicates the number of time steps that the software measures each interpolation or extrapolation point. The software determines a percentage of total coverage by measuring the total interpolation and extrapolation points that achieve a measurement of at least one time step during simulation between a break point or beyond the end points.
16 Model Objects That Receive Model Coverage of them independently set the output to true for at least one time step and how many independently set the output to false for at least one time step. 1-D Lookup Table The 1-D Lookup Table block receives lookup table coverage; for a one-dimensional lookup table, the number of input and output break points is equal. Lookup table coverage measures: • The number of times during simulation that the input and output values are between each of the break points.
Model Objects That Receive Coverage The total number of coverage points for a two-dimensional lookup table is the number of row break points in the table plus one, multiplied by the number of column break points in the table plus one. In the coverage report, an increasing white-to-green color scale, with six evenly spaced data ranges starting with zero, indicates the number of time steps that the software measures each interpolation or extrapolation point.
16 Model Objects That Receive Model Coverage Math Function If you select the Saturate on integer overflow coverage metric, the Math Function block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”. The software treats each element of a vector or matrix as a separate coverage measurement.
Model Objects That Receive Coverage In the Coverage Settings dialog box, select the referenced models for which you want to report coverage. The software generates a coverage report for each referenced model you select. If your model contains multiple instances of the same referenced model, the software records coverage for all instances of that model where the simulation mode of the Model block is set to Normal.
16 Model Objects That Receive Model Coverage more information, see “Saturate on Integer Overflow Coverage”. The software treats each element of a vector or matrix as a separate coverage measurement. Product If you select the Saturate on integer overflow coverage metric, the Product block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”. The software treats each element of a vector or matrix as a separate coverage measurement.
Model Objects That Receive Coverage Rate Limiter The Rate Limiter block receives decision coverage. The Simulink Verification and Validation software reports decision coverage for the Rising slew rate and Falling slew rate parameters. For the Rising slew rate, decision coverage measures: • The number of time steps that the block input changes more than or equal to the rising rate, indicating a true decision.
16 Model Objects That Receive Model Coverage • the number of times that the specified relational operation was false. The Relational Operator block contains a comparison between its inputs. Therefore, if you select the Relational Boundary coverage metric, the Relational Operator block receives relational boundary coverage. For more information, see “Relational Boundary Coverage”. Relay The Relay block receives decision coverage.
Model Objects That Receive Coverage C/C++ S-Function Model coverage is supported for C/C++ S-Functions. The coverage report for the model contains results for each instance of an S-Function block in the model. The results for an S-Function block link to a separate coverage report for the C/C++ code in the block. To generate coverage report for S-Functions: 1 When creating the S-Functions, enable support for coverage. For more information, see “Make S-Function Compatible with Model Coverage”.
16 Model Objects That Receive Model Coverage • C++ class templates are not instrumented for coverage. Saturation The Saturation block receives decision coverage. The Simulink Verification and Validation software reports decision coverage for the Lower limit and Upper limit parameters. For the Upper limit, decision coverage measures: • The number of time steps that the block input is greater than or equal to the upper limit, indicating a true decision.
Model Objects That Receive Coverage “Saturate on Integer Overflow Coverage”. The software treats each element of a vector or matrix as a separate coverage measurement. Simulink Design Verifier Functions in MATLAB Function Blocks The following functions in MATLAB Function blocks receive Simulink Design Verifier coverage: • sldv.condition • sldv.test • sldv.assume • sldv.prove Each of these functions evaluates an expression expr, for example, sldv.
16 Model Objects That Receive Model Coverage • The number of time steps that the control input evaluates to true. • The number of time steps the control input evaluates to false. The number of decision points is based on whether the control input is scalar or vector. If you select the Saturate on integer overflow coverage metric, the Switch block receives saturate on integer overflow coverage. For more information, see “Saturate on Integer Overflow Coverage”.
Model Objects That Receive Coverage If all points and intervals defined in the block are satisfied for at least one time step, Simulink Design Verifier coverage is 100%. Otherwise, the Simulink Verification and Validation software reports coverage as the number of points and intervals satisfied during at least one time step, divided by the total number of points and intervals defined for the block. Test Objective The Test Objective block receives Simulink Design Verifier coverage.
16 Model Objects That Receive Model Coverage • The number of time steps that each element of the trigger port is false. The software reports condition coverage based on the total number of possible conditions and how many are true for at least one time step and how many are false for at least one time step. If the trigger port is a vector, the software measures MCDC coverage for the trigger port only.
Model Objects That Receive Coverage 100%. The software treats each element of the vector as a separate condition for MCDC coverage measurement. Truth Table The Truth Table block is a Stateflow block that enables you to use truth table logic directly in a Simulink model. The Truth Table block receives condition, decision, and MCDC coverage. For more information on model coverage with Stateflow truth tables, see “Model Coverage for Stateflow Truth Tables”.
16 Model Objects That Receive Model Coverage number of iterations to -1 (no limit), the decision coverage for the iteration limit is true for all iterations and false for zero iterations, and decision coverage is 50%.
Model Objects That Do Not Receive Coverage Model Objects That Do Not Receive Coverage The Simulink Verification and Validation software does not record coverage for blocks that are not listed in “Model Objects That Receive Coverage”. Note: The software only records coverage when the Simulation mode parameter is set to Normal. The following table identifies specific model objects that do not receive coverage in certain conditions. Model object Does not receive coverage...
17 Setting Model Coverage Options • “Specify Model Coverage Options” on page 17-2 • “Cumulative Coverage Data” on page 17-17
17 Setting Model Coverage Options Specify Model Coverage Options Before starting a model coverage analysis, you must specify several model coverage recording and reporting options. In the Simulink Editor, select Analysis > Coverage > Settings. The Coverage Settings dialog box opens, with the Coverage tab displayed. The following sections describe the settings for each tab in the Coverage Settings dialog box. In this section...
Specify Model Coverage Options Coverage for this model Instructs the software to gather and report the model coverages that you specify during simulation.
17 Setting Model Coverage Options Subsystem button and the Coverage metrics section of the Coverage pane become available. Select Subsystem Specifies the subsystem for which the software gathers and reports coverage data. When you select the Coverage for this model option, the software, by default, generates coverage data for the entire model. To restrict coverage reporting to a particular subsystem: 1 On the Coverage tab, click Select Subsystem. The Subsystem Selection dialog box opens.
Specify Model Coverage Options Select Models Click to specify the referenced models for which the Simulink Verification and Validation software records and reports coverage data. When you select Coverage for referenced models, the software, by default, generates coverage data for all referenced models where the simulation mode of the Model block is set to Normal. To enable coverage reporting for particular referenced models: 1 On the Coverage pane, click Select Models.
17 Setting Model Coverage Options The icon next to the model name indicates the simulation mode for that referenced model. You can select only referenced models whose simulation mode is set to Normal. If you have multiple Model blocks that reference the same model and whose simulation mode is set to Normal, selecting or clearing one check box for that model causes the check boxes for all Normal mode instances of that model to be selected or cleared.
Specify Model Coverage Options Enable cumulative data collection Accumulates model coverage results from successive simulations. Select this and Save cumulative results in workspace variable to collect model coverage results for multiple simulations in one cvdata object. For more information, see “Cumulative Coverage Data” on page 17-17.
17 Setting Model Coverage Options Clear data Removes existing internal cumulative coverage data. If cumulative coverage data is saved in a workspace variable, rename that workspace variable to avoid overwriting it in future simulations. Save cumulative results in workspace variable Accumulates and saves the results of successive simulations in a cvdata object in the workspace. Specify the workspace variable name in the cvdata object name field.
Specify Model Coverage Options Generate report Creates an HTML report containing the coverage data collected from simulation. Click the Settings button to select various reporting options.
17 Setting Model Coverage Options Show report Specifies whether to open the generated HTML coverage report in a MATLAB browser window at the end of model simulation. Settings On the Reporting tab, for Detailed Report, click Settings to open the Settings dialog box. In the Settings dialog box, choose model coverage report options.
Specify Model Coverage Options Option Description Do not report fully covered model objects The coverage report includes only model objects that the simulation does not cover fully, useful when developing tests, because it reduces the size of the generated reports. Display hit/count ratio in the model summary Reports coverage numbers as both a percentage and a ratio, for example, 67% (8/12).
17 Setting Model Coverage Options Options Tab On the Options tab, select options for model coverage reports. Treat Simulink logic blocks as short-circuited The Treat Simulink logic blocks as short-circuited option applies only to condition and MCDC coverage.
Specify Model Coverage Options blocks as if the block ignores remaining inputs when the previous inputs alone determine the block's output. For example, if the first input to a Logical Operator block whose Operator parameter specifies AND is false, MCDC coverage analysis ignores the values of the other inputs when determining MCDC coverage for a test case.
17 Setting Model Coverage Options Restrict recording to interval To record model coverage only inside a specified simulation time interval, check Restrict recording to interval and define a Start time and Stop time. Model coverage is not recorded for simulation times outside Start time and Stop time. If your simulation starts at a time greater than or equal to Stop time, model coverage is not recorded.
Specify Model Coverage Options Filename If you enable coverage for this model, you can create a filter file or open an existing filter file. In this filter file, you can then specify objects that you want to exclude from model coverage collection during simulation. In the Filename field, enter the full path to the file that specifies the model objects to be excluded from model coverage collection. You can also click Browse to navigate to the file. You can only open files that have the valid .
17 Setting Model Coverage Options If the current model has a filter file already associated with it, the file name appears in the Filename field, and the Open in Filter Viewer link is displayed. To edit the coverage filter settings, click this link. If the Open in Filter Viewer link is unavailable, go to the Coverage tab. Select Coverage for this model to enable coverage for the current model. You can then enter the filter file name and edit the file.
Cumulative Coverage Data Cumulative Coverage Data On the Results tab, if you select Enable cumulative data collection and Save cumulative results in workspace variable, a coverage running total is updated with new results at the end of each simulation. However, if you change model or block settings between simulations that are incompatible with settings from previous simulations and affect the type or number of coverage points, the cumulative coverage data resets.
18 Coverage Collection During Simulation • “Model Coverage Collection Workflow” on page 18-2 • “Create and Run Test Cases” on page 18-3 • “View Coverage Results in a Model” on page 18-4 • “Model Coverage for Multiple Instances of a Referenced Model” on page 18-10 • “Model Coverage for MATLAB Functions” on page 18-20 • “Model Coverage for C and C++ S-Functions” on page 18-37 • “View Coverage Results for C/C++ Code in S-Function Blocks” on page 18-41 • “Model Coverage for Stateflow Charts” on page 18-45
18 Coverage Collection During Simulation Model Coverage Collection Workflow To develop effective tests with model coverage: 1 Develop one or more test cases for your model. (See “Create and Run Test Cases” on page 18-3.) 2 Run the test cases to verify model behavior. 3 Analyze the coverage reports produced by the Simulink Verification and Validation software.
Create and Run Test Cases Create and Run Test Cases To create and run test cases, model coverage provides two MATLAB commands, cvtest and cvsim. The cvtest command creates test cases that the cvsim command runs. (See “Run Tests with cvsim” on page 21-5.) You can also run the coverage tool interactively: 1 Open the sldemo_fuelsys model. 2 In the Simulink model window, select Analysis > Coverage > Settings. The Coverage Settings dialog box appears, with the Coverage tab open.
18 Coverage Collection During Simulation View Coverage Results in a Model In this section... “Overview of Model Coverage Highlighting” on page 18-4 “Enable Coverage Highlighting” on page 18-5 “View Results in Coverage Display Window” on page 18-8 Overview of Model Coverage Highlighting When you simulate a Simulink model, you can configure your model to provide visual results that allow you to see at a glance which objects recorded 100% coverage.
View Coverage Results in a Model Enable Coverage Highlighting To enable the model coverage colored diagram display: 1 In the Simulink Editor, select Analysis > Coverage > Settings to open the Coverage Settings dialog box. 2 In the Coverage tab, select Coverage for this model. Click Select Subsystem to open the Subsystem Selection dialog box. Select the top-level model sldemo_fuelsys so that all subsystems are included in coverage analysis. Close the Subsystem Selection dialog box.
18 Coverage Collection During Simulation Red: Partial Coverage In this example, the control_logic Stateflow chart received the following coverage: • Decision: 25% • Condition: 21% • MCDC: 0% Inside the control_logic subsystem, the Pressure substate was never fail.
View Coverage Results in a Model In the next example, in the Multiport Switch block, two of the data ports were never executed.
18 Coverage Collection During Simulation Gray: Filtered Coverage In this example, the fuel_rate_control subsystem is highlighted in gray because it was filtered out of coverage recording. View Results in Coverage Display Window After simulating the model and recording coverage, by default, the Coverage Display Window is the top-most visible window. When you click an object that recorded coverage, the Coverage Display Window displays details of the coverage recorded during simulation.
View Coverage Results in a Model • Close the window. Press Alt+F4. • Close the window and remove highlighting on the model. Select Display > Remove Highlighting. Abbreviations in Coverage Results The Coverage Display Window shows results with abbreviations. You can view expanded results in the “Top-Level Model Coverage Report”.
18 Coverage Collection During Simulation Model Coverage for Multiple Instances of a Referenced Model In this section... “About Coverage for Model Blocks” on page 18-10 “Record Coverage for Multiple Instances of a Referenced Model” on page 18-10 About Coverage for Model Blocks Model blocks do not receive coverage directly; if you set the simulation mode of the Model block to Normal, the Simulink Verification and Validation software records coverage for the model referenced from the Model block.
Model Coverage for Multiple Instances of a Referenced Model This model contains three Model blocks that reference the sldemo_mdlref_counter_datamngt example model. The corners of each Model block indicate the value of their Simulation mode parameter: • Counter1 — Simulation mode: Normal • Counter2 — Simulation mode: Accelerator • Counter3 — Simulation mode: Accelerator 2 Configure your model to record coverage during simulation: a In the model window, select Analysis > Coverage > Settings.
18 Coverage Collection During Simulation models whose simulation mode is Normal. In this example, only the first Model block that references sldemo_mdlref_counter_datamngt is available for recording coverage. d Click OK to exit the Select Models for Coverage Analysis dialog box. e In the Coverage Settings dialog box, on the Reporting tab, select Last Run so that you can compare coverage data from individual simulations, not accumulated coverage for successive simulations.
Model Coverage for Multiple Instances of a Referenced Model Note the following about the coverage for the Range Check subsystem in this example: • The Saturate Count block executed 100 times. This block has four Boolean decisions. Decision coverage was 50%, because two of the four decisions were never recorded: • The decision input > lower limit was never false. • The decision input >= upper limit was never true.
18 Coverage Collection During Simulation • The DetectOverflow function executed 50 times. This script has five decisions. The DetectOverflow script achieved 60% coverage because two of the five decisions were never recorded: • The expression count >= CounterParams.UpperLimit was never true. • The expression count > CounterParams.LowerLimit was never false.
Model Coverage for Multiple Instances of a Referenced Model 18-15
18 Coverage Collection During Simulation Record Coverage for the Second Instance of the Referenced Model Record coverage for two Model blocks. Set the simulation mode of a second Model block to Normal and simulate the model. In this example, the Counter2 block adds to the coverage for the model referenced from both Model blocks. 1 In the Simulink Editor for your top-level model, right-click a second Model block and select Block Parameters (ModelReference). The Function Block Parameters dialog box opens.
Model Coverage for Multiple Instances of a Referenced Model 4 To make sure that the software records coverage for both instances of this model: a Select Analysis > Coverage > Settings. b On the Coverage pane, under Coverage for referenced models, click Select Models. In the Select Models for Coverage Analysis dialog box, verify that both instances of the referenced model are selected. In this example, the list now looks like the following.
18 Coverage Collection During Simulation • The DetectOverflow function executed 100 times. The simulation of the Counter2 block executed the DetectOverflow function an additional 50 times. The DetectOverflow function has five decisions. The expression count >= CounterParams.UpperLimit was true 21 times during this simulation, compared to 0 during the first simulation. The expression count > CounterParams.LowerLimit was never false.
Model Coverage for Multiple Instances of a Referenced Model 18-19
18 Coverage Collection During Simulation Model Coverage for MATLAB Functions In this section...
Model Coverage for MATLAB Functions • Function header — Decision coverage is 100% if the function or local function is executed. • if — Decision coverage is 100% if the if expression evaluates to true at least once, and false at least once. • switch — Decision coverage is 100% if every switch case is taken, including the fallthrough case. • for — Decision coverage is 100% if the equivalent loop condition evaluates to true at least once, and false at least once.
18 Coverage Collection During Simulation For an example of coverage data for Simulink Design Verifier functions in a coverage report, see “Simulink Design Verifier Coverage” on page 19-45. Relational Boundary Coverage If the MATLAB function block contains a relational operation, the relational boundary coverage metric applies to this block.
Model Coverage for MATLAB Functions To collect coverage for these functions, on the Coverage tab of the Coverage Settings dialog box, select the Simulink Design Verifier coverage metric. The following section provides model coverage examples for each of these situations.
18 Coverage Collection During Simulation The coordinates for the origin of the moving test rectangle are represented by persistent data x1 and y1, which are both initialized to -1. For the first sample, x1 and y1 both increase to 0. From then on, the progression of rectangle arguments during simulation is as shown in the following graphic. Stationary rectangle Test rectangles The fixed rectangle is shown in bold with a lower-left origin of (2,4) and a width and height of 2.
Model Coverage for MATLAB Functions The local function rect_intersect checks to see if its two rectangle arguments intersect. Each argument consists of coordinates for the lower-left corner of the rectangle (origin), and its width and height. x values for the left and right sides and y values for the top and bottom are calculated for each rectangle and compared in nested if-else decisions. The function returns a logical value of 1 if the rectangles intersect and 0 if they do not.
18 Coverage Collection During Simulation Coverage for the MATLAB Function run_intersect_test Model coverage for the MATLAB Function block function run_intersect_test appears under the linked name of the function. Clicking this link opens the function in the editor. Below the linked function name is a link to the model coverage report for the parent MATLAB Function block that contains the code for run_intersect_test. The top half of the report for the function summarizes its model coverage results.
Model Coverage for MATLAB Functions Lines with coverage elements are marked by a highlighted line number in the listing: • Line 1 receives decision coverage on whether the top-level function run_intersect_test is executed. • Line 6 receives decision coverage for its if statement. • Line 14 receives decision coverage on whether the local function rect_intersect is executed.
18 Coverage Collection During Simulation • Lines 27 and 30 receive decision, condition, and MCDC coverage for their if statements and conditions. Each of these lines is the subject of a report that follows the listing. The condition right1 < left2 in line 30 is highlighted in red. This means that this condition was not tested for all of its possible outcomes during simulation. Exactly which of the outcomes was not tested is in the report for the decision in line 30.
Model Coverage for MATLAB Functions Coverage for Line 14 The Decisions Analyzed table indicates that the local function rect_intersect executed during testing, thus receiving 100% coverage. Coverage for Line 27 The Decisions analyzed table indicates that there are two possible outcomes for the decision in line 27: true and false. Five of the eight times it was executed, the decision evaluated to false. The remaining three times, it evaluated to true.
18 Coverage Collection During Simulation brings the total true occurrences for the decision to three, as reported in the Decisions analyzed table. MCDC coverage looks for decision reversals that occur because one condition outcome changes from T to F or from F to T. The MC/DC analysis table identifies all possible combinations of outcomes for the conditions that lead to a reversal in the decision. The character x is used to indicate a condition outcome that is irrelevant to the decision reversal.
Model Coverage for MATLAB Functions Because the line 27 decision evaluated false five times, line 30 is evaluated five times, three of which are false. Because both the true and false outcomes are achieved, decision coverage for line 30 is 100%. Because line 30, like line 27, has two conditions related by a logical OR operator (||), condition 2 is tested only if condition 1 is false. Because condition 1 tests false five times, condition 2 is tested five times.
18 Coverage Collection During Simulation Coverage for run_intersect_test On the Details tab, the metrics that summarize coverage for the entire run_intersect_test function are reported and repeated as shown.
Model Coverage for MATLAB Functions • The MCDC coverage tables for decision lines 27 and 30 each list two cases of decision reversal for each condition, for a total of four possible reversals. Only the decision reversal for a change in the evaluation of the condition right1 < left2 of line 30 from true to false did not occur during simulation. This means that three of four, or 75% of the possible reversal cases were tested for during simulation, for a coverage of 75%.
18 Coverage Collection During Simulation • sldv.condition • sldv.test • sldv.assume • sldv.prove For this example, consider the following model that contains a MATLAB Function block. The MATLAB Function block contains the following code: function y = fcn(u) % This block supports MATLAB for code generation. sldv.condition(u > -30) sldv.
Model Coverage for MATLAB Functions 18-35
18 Coverage Collection During Simulation For an example of model coverage data for Simulink Design Verifier blocks, see “Simulink Design Verifier Coverage” on page 15-9.
Model Coverage for C and C++ S-Functions Model Coverage for C and C++ S-Functions Model coverage is supported for C/C++ S-Functions. The coverage results for S-Function blocks can be viewed in the same report as the rest of the model. For each S-Function block, the report links to a detailed coverage report for the C/C++ code in the block. To generate coverage report for S-Functions: 1 When creating S-Functions, enable support for coverage.
18 Coverage Collection During Simulation S-Function Using S-Function Builder 1 Copy an instance of the S-Function Builder block from the User-Defined Functions library in the Library Browser into the your model. 2 Double-click the block to open the S-Function Builder dialog box. 3 On the Build Info tab, select Enable support for coverage. S-Function Using mex Function If you use the mex function to compile and link your source files, use the slcovmex function instead.
Model Coverage for C and C++ S-Functions 18-39
18 Coverage Collection During Simulation When you run a simulation, the coverage report contains coverage metrics for C/C++ SFunction blocks in your model. For each S-Function block, the report links to a detailed coverage report for the C/C++ code in the block.
View Coverage Results for C/C++ Code in S-Function Blocks View Coverage Results for C/C++ Code in S-Function Blocks This example shows how to view coverage results for the C/C++ code in S-Function blocks in your model. To view coverage results for the C/C++ code in the blocks: • Enable support for S-Function coverage. For more information, see “Model Coverage for C and C++ S-Functions”. • Run simulation and view the coverage report.
18 Coverage Collection During Simulation 3 Select each of the links in Table Of Contents to navigate to various sections of the report. Section Title Purpose Analysis information Contains information such as time when model was created and last modified, and file size. Tests Contains information about the simulation such as start and end time. Summary Contains coverage information about the files and functions in the S-Function block.
View Coverage Results for C/C++ Code in S-Function Blocks 4 In the Summary section, select each file or function name to see details of coverage for statements in the file or function. 5 The condition, decision or MCDC outcomes that were not tested during simulation are highlighted in pink. Within the details for a file or function, scroll down to note these cases and investigate them further.
18 Coverage Collection During Simulation 6 To obtain an overview of the statements that were not covered, navigate to the Code section. This section contains your code with the uncovered statements highlighted in pink.
Model Coverage for Stateflow Charts Model Coverage for Stateflow Charts In this section...
18 Coverage Collection During Simulation • Have a Stateflow license. • Have debugging/animation enabled for the chart. Specify Coverage Report Settings To specify coverage report settings, select Analysis > Coverage > Settings in the Simulink Editor. By selecting the Generate HTML Report option in the Coverage Settings dialog box, you can create an HTML report containing the coverage data generated during simulation of the model. The report appears in the MATLAB Help browser at the end of simulation.
Model Coverage for Stateflow Charts For analysis purposes, each chart counts as a single component. Decision Coverage Decision coverage interprets a model execution in terms of underlying decisions where behavior or execution must take one outcome from a set of mutually exclusive outcomes. Note: Full coverage for an object of decision means that every decision has had at least one occurrence of each of its possible outcomes.
18 Coverage Collection During Simulation Chart Containing Exclusive OR Substates Decision If the chart contains exclusive (OR) substates, the decision on which substate to execute is tested. If the chart contains only parallel AND substates, this coverage measurement is not applicable (NA).
Model Coverage for Stateflow Charts Context Example Decisions That Occur and not to the parent state A. In this case, the transition marked by condition C2 is tested and a decision is made whether to take the transition to A2 or not. Implicit substate A transition takes place whose source is exit superstate A and whose destination is state B.
18 Coverage Collection During Simulation State with On Event_Name Action Statement Decision A state that has an on event_name action statement must decide whether to execute that statement based on the reception of a specified event or on an accumulation of the specified event when using temporal logic operators. Conditional Transition Decision A conditional transition is a transition with a triggering event and/or a guarding condition.
Model Coverage for Stateflow Charts Outcome A B C 8 F F F For more information, see “Transition Details Report Section” on page 18-59. MCDC Coverage The Modified Condition Decision Coverage (MCDC) option reports a test's coverage of occurrences in which changing an individual subcondition within a transition results in changing the entire transition trigger expression from true to false or false to true. Note: If matching true and false outcomes occur for each subcondition, coverage is 100%.
18 Coverage Collection During Simulation When you specify the Simulink Design Verifier coverage metric in the Coverage Settings dialog box, the Simulink Verification and Validation software records coverage for these functions. Each of these functions evaluates an expression expr, for example, sldv.test(expr), where expr is any valid Boolean MATLAB expression. Simulink Design Verifier coverage measures the number of time steps that the expression expr evaluates to true.
Model Coverage for Stateflow Charts Model Coverage Reports for Stateflow Charts • “Summary Report Section” on page 18-53 • “Subsystem and Chart Details Report Sections” on page 18-54 • “State Details Report Section” on page 18-56 • “Transition Details Report Section” on page 18-59 The following sections of a Model Coverage report were generated by simulating the sf_boiler model, which includes the Bang-Bang Controller chart.
18 Coverage Collection During Simulation Each line in the hierarchy summarizes the coverage results at that level and the levels below it. You can click a hyperlink to a later section in the report with the same assigned hierarchical order number that details that coverage and the coverage of its children. The top level, sf_boiler, is the Simulink model itself. The second level, Bang-Bang Controller, is the Stateflow chart.
Model Coverage for Stateflow Charts • Coverage (this object): Coverage data for the chart as a container object • Coverage (inc.) descendants: Coverage data for the chart and the states and transitions in the chart. If you click the hyperlink of the subsystem name in the section title, the Bang-Bang Controller block is highlighted in the block diagram. Decision coverage is not applicable (NA) because this chart does not have an explicit trigger.
18 Coverage Collection During Simulation State Details Report Section For each state in a chart, the coverage report includes a State section with details about the coverage recorded for that state. In the sf_boiler model, the state On resides in the box Heater.
Model Coverage for Stateflow Charts The coverage report includes a State section on the state On.
18 Coverage Collection During Simulation The decision coverage for the On state tests the decision of which substate to execute. The three decisions are listed in the report: • Under Substate executed, which substate to execute when On executes. • Under Substate exited when parent exited, which substate is active when On exits. NORM is listed as never being active when On exits because the coverage tool sees the supertransition from NORM to Off as a transition from On to Off.
Model Coverage for Stateflow Charts • Under Previously active substate entered due to history, which substate to reenter when On re-executes. The history junction records the previously active substate. Because each decision can result in either HIGH or NORM, the total possible outcomes are 3 × 2 = 6. The results indicate that five of six possible outcomes were tested during simulation. Cyclomatic complexity and decision coverage also apply to descendants of the On state.
18 Coverage Collection During Simulation The decision for this transition depends on the time delay of 40 seconds and the condition [cold()].
Model Coverage for Stateflow Charts decision to execute this transition and turn the Heater on is made. For other time intervals or environment conditions, the decision is made not to execute. For decision coverage, both true and false outcomes occurred. Because two of two decision outcomes occurred, coverage was full or 100%. Condition coverage shows that only 4 of 6 condition outcomes were tested.
18 Coverage Collection During Simulation conditions. Therefore, condition rows 1 and 3 are shaded. While condition 2 has been tested, conditions 1 and 3 have not and MCDC is 33%. For some decisions, the values of some conditions are irrelevant under certain circumstances. For example, in the decision [C1 & C2 & C3 | C4 & C5] the left side of the | is false if any one of the conditions C1, C2, or C3 is false. The same applies to the right side result if either C4 or C5 is false.
Model Coverage for Stateflow Charts Coverage results for state transition tables are the same as coverage results for equivalent Stateflow charts, except for a slight difference that arises in coverage of temporal logic. For example, consider the temporal logic expression after(4, tick) in the Mode Logic chart of the slvnvdemo_covfilt example model. In chart coverage, the after(4, tick) transition represents two conditions: the occurrence of tick and the time delay after(4, tick).
18 Coverage Collection During Simulation 1 Open the doc_atomic_subcharts_map_iodata model. This model contains two Sine Wave blocks that supply input signals to the Stateflow chart. Chart contains two atomic subcharts—A and B—that are linked from the same library chart, also named A. The library chart contains the following objects: 2 In the Simulink Editor, select Analysis > Coverage > Settings The Coverage Settings dialog box appears.
Model Coverage for Stateflow Charts • For the library chart A and its contents. The chart itself achieves 100% coverage on the input u1, and 88% coverage on the states and transitions inside the library chart. Atomic subchart B is a copy of the same library chart A. The coverage of the contents of subchart B is identical to the coverage of the contents of subchart A.
18 Coverage Collection During Simulation Model Coverage for Stateflow Truth Tables • “Types of Coverage in Stateflow Truth Tables” on page 18-66 • “Analyze Coverage in Stateflow Truth Tables” on page 18-66 Types of Coverage in Stateflow Truth Tables Simulink Verification and Validation software reports model coverage for the decisions the objects make in a Stateflow chart during model simulation. The report includes coverage for the decisions the truth table functions make. For this type of truth table...
Model Coverage for Stateflow Charts The Stateflow chart contains the following truth table: 18-67
18 Coverage Collection During Simulation When you simulate the model and collect coverage, the model coverage report includes the following data: 18-68
Model Coverage for Stateflow Charts The Coverage (this object) column shows no coverage. The reason is that the container object for the truth table function—the Stateflow chart—does not decide whether to execute the ttable truth table. The Coverage (inc. descendants) column shows coverage for the graphical function. The graphical function has the decision logic that makes the transitions for the truth table. The transitions in the graphical function contain the decisions and conditions of the truth table.
18 Coverage Collection During Simulation Note: See “How Stateflow Generates Content for Truth Tables” for a description of the graphical function for a truth table. Coverage for the decisions and their individual conditions in the ttable truth table function are as follows. Coverage Explanation No model coverage for the default decision, D5 All logic that leads to taking a default decision is based on a false outcome for all preceding decisions.
Model Coverage for Stateflow Charts Colored Stateflow Chart Coverage Display The Model Coverage tool displays model coverage results for individual blocks directly in Simulink diagrams.
18 Coverage Collection During Simulation Object highlighting indicates coverage as follows: • Light green for full coverage • Light red for partial coverage • No color for zero coverage Note: To revert the chart to show original colors, select and deselect any objects. 6 Click selection_state in the chart. The following summary report appears.
Model Coverage for Stateflow Charts When you click a highlighted Stateflow object, the summarized coverage for that object appears in the Coverage Display Window. Clicking the hyperlink opens the section of the coverage report for this object. Tip You can set the Coverage Display Window to appear for a block in response to a hovering mouse cursor instead of a mouse click in one of two ways: • Select the downward arrow on the right side of the Coverage Display Window and select Focus.
19 Results Review • “Types of Coverage Reports” on page 19-2 • “Top-Level Model Coverage Report” on page 19-12 • “Export Model Coverage Web View” on page 19-47
19 Results Review Types of Coverage Reports In the Coverage Settings dialog box, on the Report tab, if you select the Generate HTML report option, the Simulink Verification and Validation software creates one or more model coverage reports after a simulation. Report Type Description HTML Report File Name “Top-Level Model Coverage Report” on page 19-12 Provides coverage information for all model elements, including the model itself. model_name_cov.
Types of Coverage Reports Model Summary Report If the top-level model contains Model blocks or calls external files, the software creates a model summary coverage report named model_name_summary_cov.html. The title of this report is Coverage by Model. The summary report lists and provides links to coverage reports for Model block referenced models and external files called by MATLAB code in the model. For more information, see “External MATLAB File Coverage Report” on page 19-5.
19 Results Review Model Reference Coverage Report If your top-level model references a model in a Model block, the software creates a separate report, named reference_model_name_cov.html, that includes coverage for the referenced model. This report has the same format as the “Top-Level Model Coverage Report” on page 19-12. Coverage results are recorded as if the referenced model was a standalone model; the report gives no indication that the model is referenced in a Model block.
Types of Coverage Reports External MATLAB File Coverage Report If your top-level model calls any external MATLAB files, select Coverage for MATLAB files on the Coverage tab of the Coverage Settings dialog box. The software creates a report, named MATLAB_file_name_cov.html, for each distinct file called from the model. When there are several calls to a given file from the model, the software creates only one report for that file, but it accumulates coverage from all the calls to the file.
19 19-6 Results Review
Types of Coverage Reports The Details section reports coverage for the external file and the function in that file. The Details section also lists the content of the file, highlighting the code lines that have decision points or function definitions.
19 19-8 Results Review
Types of Coverage Reports Coverage results for each of the highlighted code lines follow in the report. The following graphic shows a portion of these coverage results from the preceding code example. Subsystem Coverage Report In the Coverage Settings dialog box, when you select Coverage for this model, you can click Select Subsystem to request coverage for only the selected subsystem in the model.
19 Results Review • The top-level model that includes the subsystem If the subsystem parameter Read/Write Permissions is set to NoReadOrWrite, the software does not record coverage for that subsystem. For example, in the fuelsys model, you click Select Subsystem, and select coverage for the feedforward_fuel_rate subsystem. The report is similar to the model coverage report, except that it includes only results for the feedforward_fuel_rate subsystem and its contents.
Types of Coverage Reports Code Coverage Report For each S-Function block, the model coverage report links to a detailed code coverage report for the C/C++ code in the block. For more information on how to navigate the report, see “View Coverage Results for C/C+ + Code in S-Function Blocks”.
19 Results Review Top-Level Model Coverage Report The Simulink Verification and Validation software always creates a model coverage report for the top-level model named model_name_cov.html. The model coverage report contains several sections: In this section...
Top-Level Model Coverage Report The coverage summary has two subsections: • Tests — The simulation start and stop time of each test case and any setup commands that preceded the simulation. The heading for each test case includes any test case label specified using the cvtest command. • Summary — Summaries of the subsystem results. To see detailed results for a specific subsystem, in the Summary subsection, click the subsystem name.
19 Results Review Details The Details section reports the detailed model coverage results.
Top-Level Model Coverage Report • “Chart Details” on page 19-18 • “Coverage Details for MATLAB Functions and Simulink Design Verifier Functions” on page 19-18 You can also access a model element Details subsection as follows: 1 Right-click a Simulink element. 2 In the context menu, select Coverage > Report. Filtered Objects The Filtered Objects section lists all the objects in the model that were filtered from coverage recording, and the rationale you specified for filtering those objects.
19 Results Review Subsystem Details Each subsystem Details section contains a summary of the test coverage results for the subsystem and a list of the subsystems it contains. The overview is followed by sections for blocks, charts, and MATLAB functions, one for each object that contains a decision point in the subsystem. The following graphic shows the coverage results for the Engine Gas Dynamics subsystem in the sldemo_fuelsys example model.
Top-Level Model Coverage Report Block Details The following graphic shows decision coverage results for the MinMax block in the Mixing & Combustion subsystem of the Engine Gas Dynamics subsystem in the sldemo_fuelsys example model. The Uncovered Links element first appears in the Block Details section of the first block in the model hierarchy that does not achieve 100% coverage.
19 Results Review Chart Details The following graphic shows the coverage results for the Stateflow chart control_logic in the sldemo_fuelsys example model. For more information about model coverage reports for Stateflow charts and their objects, see “Model Coverage for Stateflow Charts”. Coverage Details for MATLAB Functions and Simulink Design Verifier Functions By default, Simulink Verification and Validation records coverage for all MATLAB functions in a model.
Top-Level Model Coverage Report Note: For a detailed example of coverage reports for external MATLAB files, see “External MATLAB File Coverage Report” on page 19-5. To record Simulink Design Verifier coverage for sldv.* functions called by MATLAB functions, and any Simulink Design Verifier blocks, in the Coverage Settings dialog box, on the Coverage tab, select Simulink Design Verifier.
19 Results Review Coverage for the hFcnsInExternalEML function and the sldv.* calls is: • Line 1, the function declaration for hFcnsInExternalEMLis green because the simulation executes that function at least once. fcn calls hFcnsInExternalEML 11 times during simulation.
Top-Level Model Coverage Report Line 4, sldv.assume(u1 > u2), achieves 0% coverage because u1 > u2 never evaluates to true. • Line 5, sldv.condition(u1 == 0), achieves 100% coverage because u1 == 0 evaluates to true for at least one time step. • Line 6, switch u1, achieves 25% coverage because only one of the four outcomes in the switch statement (case 0) occurs during simulation.
19 Results Review • Line 17, sldv.test(y > u1); sldv.test (y == 4) achieves 50% coverage. The first sldv.test call achieves 100% coverage, but the second sldv.test call achieves 0% coverage. For more information about coverage for MATLAB functions, see “Model Coverage for MATLAB Functions” on page 18-20. For more information about coverage for Simulink Design Verifier functions, see “Simulink Design Verifier Coverage” on page 15-9.
Top-Level Model Coverage Report • The Summary section contains the cyclomatic complexity numbers for each object in the model hierarchy. For a subsystem or Stateflow chart, that number includes the cyclomatic complexity numbers for all their descendants. • The Details sections for each object list the cyclomatic complexity numbers for all individual objects.
19 Results Review Decisions Analyzed The Decisions analyzed table lists possible outcomes for a decision and the number of times that an outcome occurred in each test simulation. Outcomes that did not occur are in red highlighted table rows. The following graphic shows the Decisions analyzed table for the Saturate block in the Throttle & Manifold subsystem of the Engine Gas Dynamics subsystem in the sldemo_fuelsys example model.
Top-Level Model Coverage Report To display and highlight the block in question, click the block name at the top of the section containing the block’s Decisions analyzed table. Conditions Analyzed The Conditions analyzed table lists the number of occurrences of true and false conditions on each input port of the corresponding block.
19 Results Review MCDC Analysis The MC/DC analysis table lists the MCDC input condition cases represented by the corresponding block and the extent to which the reported test cases cover the condition cases. Each row of the MC/DC analysis table represents a condition case for a particular input to the block. A condition case for input n of a block is a combination of input values. Input n is called the deciding input of the condition case.
Top-Level Model Coverage Report • The position of a character in the string corresponds to the input port number. • The character at the position represents the value of the input. (T means true; F means false). • A boldface character corresponds to the value of the deciding input. For example, FTF represents a condition case for a three-input block where the second input is the deciding input. The Decision/Condition column specifies the deciding input for an input condition case.
19 Results Review • Current Run — The coverage results of the simulation just completed. • Delta — Percentage of coverage added to the cumulative coverage achieved with the simulation just completed. If the previous simulation's cumulative coverage and the current coverage are nonzero, the delta may be 0 if the new coverage does not add to the cumulative coverage. • Cumulative — The total coverage collected for the model up to, but not including, the simulation just completed.
Top-Level Model Coverage Report The Conditions analyzed table uses column headers #n T and #n F to indicate results for individual test cases. The table uses Tot T and Tot F for the cumulative results. You can identify the true and false conditions on each input port of the corresponding block for each test case. The MC/DC analysis #n True Out and #n False Out columns show the condition cases for each test case. The Total Out T and Total Out F column show the cumulative results.
19 Results Review Note: You can calculate cumulative coverage for reusable subsystems and Stateflow constructs at the command line. For more information, see “Obtain Cumulative Coverage for Reusable Subsystems and Stateflow® Constructs”. N-Dimensional Lookup Table The following interactive chart summarizes the extent to which elements of a lookup table are accessed.
Top-Level Model Coverage Report In this model, the lookup table indices are 1, 2,..., 10 in each direction. The Sine Wave 2 block is out of phase with the Sine Wave 1 block by pi/2 radians. This generates x and y numbers for the edge of a circle, which you see when you examine the resulting Lookup Table coverage.
19 Results Review The report contains a two-dimensional table representing the elements of the lookup table. The element indices are represented by the cell border grid lines, which number 10 in each dimension. Areas where the lookup table interpolates between table values are represented by the cell areas. Areas of extrapolation left of element 1 and right of element 10 are represented by cells at the edge of the table, which have no outside border.
Top-Level Model Coverage Report The selected cell is outlined in red. You can also click the extrapolation cells on the edge of the table. A bold grid line indicates that at least one block input equal to its exact index value occurred during the simulation. Click the border to display the exact number of hits for that index value. The following example model uses an n-D Lookup Table block of 10-by-10-by-5 elements filled with random values.
19 Results Review Both the x and y table axes have the indices 1, 2,..., 10. The z axis has the indices 10, 20,..., 50. Lookup table values are accessed with x and y indices that the two Sine Wave blocks generated, in the preceding example, and a z index that a Ramp block generates. After simulation, you see the following lookup table report.
Top-Level Model Coverage Report Lookup table coverage for a three-dimensional lookup table block is reported as a set of two-dimensional tables. The vertical bars represent the exact z index values: 10, 20, 30, 40, 50. If a vertical bar is bold, this indicates that at least one block input was equal to the exact index value it represents during the simulation. Click a bar to get a coverage report for the exact index value that bar represents.
19 Results Review Block Reduction All model coverage reports indicate the status of the Simulink Block reduction parameter at the beginning of the report. In the following example, you set Force block reduction off. In the next example, you enabled the Simulink Block reduction parameter, and you did not set Force block reduction off. Consider the following model where the simulation does not execute the MinMax1 block because there is only one input—the constant 3.
Top-Level Model Coverage Report If you set Force block reduction off, the report contains no coverage data for this block because the minimum input to the MinMax1 block is always 1. If you do not set Force block reduction off, the report contains no coverage data for reduced blocks.
19 Results Review • “Relational Boundary Coverage”. • The Relational Boundary column in “Model Objects That Receive Coverage”. The tables below show the relational boundary coverage report for the relation input1 <= input2. The appearance of the tables depend on the operand data type. • “Integers” on page 19-38 • “Fixed point” on page 19-39 • “Floating point” on page 19-39 Integers If both operands are integers (or if one operand is an integer and the other a Boolean), the table appears as follows.
Top-Level Model Coverage Report Fixed point If one of the operands has fixed-point type and the other operand is either a fixed point or an integer, the table appears as follows. LSB represents the value of the least significant bit. For more information, see “Precision”. If the two operands have different precision, the smaller value of precision is used. For a relational operation such as operand_1 <= operand_2: • The first row states the two operands in the form operand_1 - operand_2.
19 Results Review For a relational operation such as operand_1 <= operand_2: • The first row states the two operands in the form operand_1 - operand_2. • The second row states the number of times during the simulation that operand_1 operand_2 has values in the range [-tol..0]. • The third row states the number of times during the simulation that operand_1 operand_2 has values in the range (0..tol] during the simulation.
Top-Level Model Coverage Report Relational Operator Report Format Explanation < [-tol..0) 0 is included in the region above the relational boundary. [0..tol] >= [-tol..0) [0..tol] > [-tol..0] (0..tol] 0 is included in the region above the relational boundary. 0 is included in the region below the relational boundary. 0 is included below the relational boundary for <= but above the relational boundary for <. This rule is consistent with decision coverage.
19 Results Review To display and highlight the block in question, click the block name at the top of the section containing the block’s Saturation on Overflow analyzed table. Signal Range Analysis If you select Signal Range Coverage, the software creates a Signal Range Analysis section at the bottom of the model coverage report. This section lists the maximum and minimum signal values for each output signal in the model measured during simulation.
Top-Level Model Coverage Report Each block is reported in hierarchical fashion; child blocks appear directly under parent blocks. Each block name in the Signal Ranges report is a link. For example, select the EGO sensor link to display this block highlighted in its native diagram.
19 Results Review Signal Size Coverage for Variable-Dimension Signals If you select Signal Size, the software creates a Variable Signal Widths section after the Signal Ranges data in the model coverage report. This section lists the maximum and minimum signal sizes for all output ports in the model that have variable-size signals. It also lists the memory that Simulink allocated for that signal, as measured during simulation. This list does not include signals whose size does not vary during simulation.
Top-Level Model Coverage Report Simulink Design Verifier Coverage If you select Simulink Design Verifier, the analysis collects coverage data for all Simulink Design Verifier blocks in your model. For an example of how this works, open the sldvdemo_debounce_testobjblks model. This model contains two Test Objective blocks: • The True block defines a property that the signal have a value of 2.
19 Results Review 19-46
Export Model Coverage Web View Export Model Coverage Web View You can export a Model Coverage Web View for your model. A Web View is an interactive rendition of a model that you can view in a Web browser. A Model Coverage Web View includes model coverage highlighting and analysis information from the Coverage Display Window, as described in “View Coverage Results in a Model”. To generate a Model Coverage Web View, update coverage reporting settings for your model.
19 Results Review When you simulate your model with these coverage settings enabled, the software generates a Model Coverage Web View that you can open in a browser.
Export Model Coverage Web View coverage information for a block in a Model Coverage Web View, click that block. The model coverage data appears in the Informer pane, below the model. For more information, see “Web Views” in the Simulink Report Generator documentation.
20 Excluding Model Objects From Coverage • “Coverage Filtering” on page 20-2 • “Coverage Filter Rules and Files” on page 20-3 • “Model Objects to Filter from Coverage” on page 20-4 • “Create, Edit, and View Coverage Filter Rules” on page 20-5 • “Coverage Filter Viewer” on page 20-10 • “Filter Model Objects to Refine Coverage Results” on page 20-12
20 Excluding Model Objects From Coverage Coverage Filtering In this section... “What Is Coverage Filtering?” on page 20-2 “When to Use Coverage Filtering” on page 20-2 What Is Coverage Filtering? Coverage filtering is excluding model objects from model coverage when you simulate your Simulink model. You specify which objects you want to be excluded from coverage recording.
Coverage Filter Rules and Files Coverage Filter Rules and Files In this section...
20 Excluding Model Objects From Coverage Model Objects to Filter from Coverage In your model, the objects that you can filter from coverage recording are: • Simulink blocks that receive coverage, including MATLAB Function blocks • Subsystems and their contents. When you exclude a subsystem from coverage recording, none of the objects inside the subsystem record coverage.
Create, Edit, and View Coverage Filter Rules Create, Edit, and View Coverage Filter Rules In this section...
20 Excluding Model Objects From Coverage If you select Coverage > ... The rule type is ...
Create, Edit, and View Coverage Filter Rules Note: The Rationale field is the only coverage filter rule field that you can edit in the Coverage Filter Viewer. Create Additional Coverage Filter Rules From the Coverage Filter Viewer, you can navigate back to the model to create as many coverage filter rules as you need. To return to the model window, click Add new rule by right-clicking in the model.
20 Excluding Model Objects From Coverage Save Coverage Filter to File After you define the coverage filter rules, save the rules to a file so that you can reuse them with this model or with other models. By default, coverage filter files are named _covfilter.cvf. In the Coverage Filter Viewer: 1 2 In the File name field, specify a file name for the filter file or accept the default file name. Click Apply to save the coverage filter rules to that file.
Create, Edit, and View Coverage Filter Rules To open the Coverage Filter Viewer, right-click anywhere in the model window and select Coverage > Open Filter Viewer. If you are inside a subsystem, you can view any coverage filter rule attached to the subsystem. To open the Coverage Filter Viewer, right-click any object inside the subsystem and select Coverage > Show filter parent.
20 Excluding Model Objects From Coverage Coverage Filter Viewer In the Coverage Filter Viewer, you can: • Review and manage the coverage filter rules for your Simulink model. • Attach and detach coverage filter files for your model. • Navigate to the model to create additional coverage filter rules.
Coverage Filter Viewer To ... Do this: Navigate to the model to create coverage filter rules. Click Add new rule by right-clicking in the model. Navigate to a model object associated with a rule. 1 Select the rule. 2 Click View in model. Delete a rule. 1 Select the rule. 2 Click Remove rule. 1 Enter a file name or browse to the file. 2 Click Apply. 1 Clear the Attach file to model check box. 2 Click Apply. Detach the current filter file from the model. 1 Click Attach file to model.
20 Excluding Model Objects From Coverage Filter Model Objects to Refine Coverage Results In this section...
Filter Model Objects to Refine Coverage Results When the simulation is complete, an HTML coverage report opens. This model does not record 100% coverage. Filter a Stateflow Transition In the Mode Logic Stateflow chart, the [!on] transition is never false because it evaluates only when the [on] transition is false. If you do not collect coverage for the [!on] transition, the chart behavior does not change, so you should filter the [!on] transition. 1 Open the Mode Logic chart.
20 Excluding Model Objects From Coverage 2 Right-click the [!on] transition and select Coverage > Exclude this transition. The Coverage Filter Viewer opens with the new filter rule listed. 3 Click in the Rationale field and enter the reason for excluding this transition, for example, This transition is never evaluated. 4 Save this rule to a filter file with the default name, slvnvdemo_covfilt_covfilter.cvf. Click Apply.
Filter Model Objects to Refine Coverage Results If you open the Mode Logic chart and click the transition, the Informer window displays filtering information and the Rationale text. Filter a Stateflow Event Events in Stateflow are a common cause for missing coverage in a chart, because they sometimes form an condition for coverage that can never be satisfied. For example, in the Mode Logic chart, the temporal event tick is never false, as you can see from the coverage report.
20 Excluding Model Objects From Coverage 20-16
Filter Model Objects to Refine Coverage Results As a result, you cannot record 100% condition and MCDC coverage for the transition after(4, tick). To filter the temporal event tick from coverage analysis for this model: 1 Open the Mode Logic chart. 2 Right-click the after(4, tick) transition and select Coverage > Exclude temporal event tick. The Coverage Filter Viewer opens with the new filter rule listed. 3 Click in the Rationale field and enter explanatory text, for example, tick is never false.
20 Excluding Model Objects From Coverage Click OK to close the Coverage Filter Viewer. 5 Simulate the model again and review the results. The Objects filtered from coverage analysis section of the report lists the conditions of the event tick that are excluded, along with the corresponding Rationale text you entered in the Coverage Filter Viewer.
Filter Model Objects to Refine Coverage Results With the tick event filtered from coverage analysis, there is no longer a subcondition on the decision for the after(4, tick) transition. There are only two possible decision outcomes for the after(4, tick) transition.
20 Excluding Model Objects From Coverage • protected division1 The library subsystem is a protection against division by zero and might not be relevant in the coverage report. Exclude it from coverage for this model. 1 In the Simulink Editor, right-click either of the protected division reference blocks. When you filter a library block, all instances of that block are filtered from coverage. 2 Select Coverage > Exclude reference library: slvnvdemo_covfilt_lib/ protected division.
Filter Model Objects to Refine Coverage Results Exclude the Switchable config subsystem from coverage. 1 In the Simulink Editor, right-click the Switchable config subsystem. 2 Select Coverage > Exclude subsystem with all descendants. 3 Click in the Rationale field for this new rule and enter text for excluding this transition, for example, Never executed. 4 Save this rule to the current filter. Click Apply. 5 Simulate the model again and review the results.
21 Automating Model Coverage Tasks • “Commands for Automating Model Coverage Tasks” on page 21-2 • “Create Tests with cvtest” on page 21-3 • “Run Tests with cvsim” on page 21-5 • “Retrieve Coverage Details from Results” on page 21-7 • “Obtain Cumulative Coverage for Reusable Subsystems and Stateflow® Constructs” on page 21-8 • “Create HTML Reports with cvhtml” on page 21-11 • “Save Test Runs to File with cvsave” on page 21-12 • “Load Stored Coverage Test Results with cvload” on page 21-13 • “Use Coverage Co
21 Automating Model Coverage Tasks Commands for Automating Model Coverage Tasks Using model coverage commands lets you automate the entire model coverage process with MATLAB scripts. You can use model coverage commands to set up model coverage tests, execute them in simulation, and store and report the results.
Create Tests with cvtest Create Tests with cvtest The cvtest command creates a test specification object. Once you create the object, you simulate it with the cvsim command. The call to cvtest has the following default syntax: cvto = cvtest(root) root is the name of, or a handle to, a Simulink model or a subsystem of a model. cvto is a handle to the resulting test specification object. Only the specified model or subsystem and its descendants are subject to model coverage.
21 Automating Model Coverage Tasks Field Description settings.overflowsaturation Set to 1 for saturate on integer overflow coverage settings.sigrange Set to 1 for signal range coverage settings.sigsize Set to 1 for signal size coverage. settings.tableExec Set to 1 for lookup table coverage modelRefSettings.
Run Tests with cvsim Run Tests with cvsim Use the cvsim command to simulate a test specification object. The call to cvsim has the following default syntax: cvdo = cvsim(cvto) This command executes the cvtest object cvto by simulating the corresponding model. cvsim returns the coverage results in the cvdata object cvdo. When recording coverage for multiple models in a hierarchy, cvsim returns its results in a cv.cvdatagroup object.
21 Automating Model Coverage Tasks You can also execute multiple test objects with the cvsim command. The following command executes a set of coverage test objects, cvto1, cvto2, ... using the default simulation parameters. cvsim returns the coverage results in a set of cvdata objects, cvdo1, cvdo2, ... and returns the simulation outputs in simOut. [cvdo1, cvdo2, ..., simOut] = cvsim(cvto1, cvto2, ...
Retrieve Coverage Details from Results Retrieve Coverage Details from Results Simulink Verification and Validation provides commands that allow you to retrieve specific coverage information from the cvtest object after you have simulated your model and recorded coverage.
21 Automating Model Coverage Tasks Obtain Cumulative Coverage for Reusable Subsystems and Stateflow® Constructs This example shows how to create and view cumulative coverage results for a model with a reusable subsystem. Simulink® Verification and Validation™ provides cumulative coverage for multiple instances of identically configured: • Reusable subsystems • Stateflow™ constructs To obtain cumulative coverage, you add the individual coverage results at the command line.
Obtain Cumulative Coverage for Reusable Subsystems and Stateflow® Constructs Get decision coverage for Subsystem 1 Execute the commands for Subsystem 1 decision coverage: testobj1 = cvtest([model '/Subsystem 1']); testobj1.settings.decision = 1; covobj1 = cvsim(testobj1); Get decision coverage for Subsystem 2 Execute the commands for Subsystem 2 decision coverage: testobj2 = cvtest([model '/Subsystem 2']); testobj2.settings.
21 Automating Model Coverage Tasks cvhtml('cum_subsystem',covobj3) Cumulative decision coverage for reusable subsystems Subsystem 1 and Subsystem 2 is 100%. Both the true and false conditions for enable logical value are analyzed.
Create HTML Reports with cvhtml Create HTML Reports with cvhtml Once you run a test in simulation with cvsim, results are saved to cv.cvdatagroup or cvdata objects in the base MATLAB workspace. Use the cvhtml command to create an HTML report of these objects. The following command creates an HTML report of the coverage results in the cvdata object cvdo. The results are written to the file file in the current MATLAB folder.
21 Automating Model Coverage Tasks Save Test Runs to File with cvsave Once you run a test with cvsim, save its coverage tests and results to a file with the cvsave function: cvsave(filename, model) Save all the tests and results related to model in the text file filename.cvt: cvsave(filename, cvto1, cvto2, ...) Save the tests in the text file filename.cvt. Information about the referenced models is also saved. You can save specified cvdata objects to file.
Load Stored Coverage Test Results with cvload Load Stored Coverage Test Results with cvload The cvload command loads into memory the coverage tests and results stored in a file by the cvsave command. The following example loads the tests and data stored in the text file filename.cvt: [cvtos, cvdos] = cvload(filename) The cvtest objects that are loaded are returned in cvtos, a cell array of cvtest objects. The cvdata objects that are loaded are returned in cvdos, a cell array of cvdata objects.
21 Automating Model Coverage Tasks Use Coverage Commands in a Script The following script demonstrates some common model coverage commands. This script: • Creates two data files to load before simulation. • Creates two cvtest objects, testObj1 and testObj2, and simulates them using the default model parameters. Each cvtest object uses the setupCmd property to load a data file before simulation. • Enables decision, condition, and MCDC coverage.
Use Coverage Commands in a Script decision_cov2 = decisioninfo(dataObj2,mdl_subsys); percent_cov2 = 100 * decision_cov2(1) / decision_cov2(2) cc_cov2 = complexityinfo(dataObj1, mdl_subsys); cvhtml('ratelim_report',dataObj1,dataObj2); cumulative = dataObj1+dataObj2; cvsave('ratelim_testdata',cumulative); close_system('slvnvdemo_ratelim_harness',0); 21-15
Checking Systems with the Model Advisor
22 Checking Systems Interactively • “Check Model and Subsystems” on page 22-2 • “Limit Model Checks” on page 22-3 • “Limit Model Checks By Excluding Gain and Outport Blocks” on page 22-11 • “Model Checks for DO-178C/DO-331 Standard Compliance” on page 22-16 • “Model Checks for IEC 61508, ISO 26262, and EN 50128 Standard Compliance” on page 22-20 • “Model Checks for MathWorks Automotive Advisory Board (MAAB) Guideline Compliance” on page 22-23 • “Model Checks for Requirements Links” on page 22-28
22 Checking Systems Interactively Check Model and Subsystems You can use the Model Advisor to check a model or subsystem for adherence to modeling guidelines or standards. The Model Advisor includes checks that help you define and implement consistent design guidelines. Using model checks, you can apply guidelines across projects and development teams.
Limit Model Checks Limit Model Checks In this section... “What Is a Model Advisor Exclusion?” on page 22-3 “Model Advisor Exclusion Files” on page 22-3 “Create Model Advisor Exclusions” on page 22-4 “Review Model Advisor Exclusions” on page 22-6 “Manage Exclusions” on page 22-7 What Is a Model Advisor Exclusion? To save time during model development and verification, you might decide to limit the scope of a Model Advisor analysis of your model. You can do this by excluding individual blocks from checks.
22 Checking Systems Interactively To exclude blocks from specified checks during an analysis of your model, you first create exclusions and save them in an exclusion file. You can also use an existing Model Advisor exclusion file. When you analyze a model with Model Advisor exclusions, the blocks in the exclusion file are excluded from the specified checks during the analysis. You can use an exclusion file with several models. However, a model can have only one exclusion file.
Limit Model Checks To ... Select Model Advisor > ... Exclude the block from all Exclude block only > All Checks checks. Exclude all blocks of this type from all checks. Exclude all blocks with type > All Checks Exclude the block from selected checks. • Exclude block only > Select Checks. • In the Check Selector dialog box, select the checks. Click OK. Exclude all blocks of this • Exclude all blocks with type > type from selected checks. Select Checks.
22 Checking Systems Interactively the current folder. Optionally, in the Save Exclusion File dialog box, you can select a different file name or location. 3 If you want to change the exclusion file name or location: a In the Model Advisor Exclusion Editor dialog box, select Change. b In the Change Exclusion File dialog box, select Save as. c In the Save Exclusion File dialog box, navigate to the location that you want and enter a file name. Click Save.
Limit Model Checks 2 In the Model Advisor window, click the Enable highlighting toggle button ( 3 In the left pane of the Model Advisor window, select a check. The blocks excluded from the check appear in the model window, highlighted in gray with a black border. ). After the Model Advisor completes an analysis, you can view exclusion information for individual checks in the: • HTML report. In the Model Advisor window, make sure select the Show report after run check box before the analysis.
22 Checking Systems Interactively Note: The Rationale field is the only field that you can edit in the Model Advisor Exclusion Editor. Save Exclusions To a File To save an exclusion to a file: 22-8 1 In the Model Advisor Exclusion Editor dialog box, click OK or Apply. If this exclusion is the first one, a Save Exclusion File as dialog box opens. In this dialog box, click Save to create an exclusion file with the default name _exclusions.xml in the current folder.
Limit Model Checks Load an Exclusion File To load an existing exclusion file for use with your model: 1 In the Model Advisor Exclusion Editor dialog box, click Change. 2 In the Change Exclusion File Dialog box, click Load. 3 Navigate to the exclusion file that you want to use with your model. Select Open. 4 In the Model Advisor Exclusion Editor dialog box, click OK to associate the exclusion file with your model.
22 Checking Systems Interactively 1 Use get_param to obtain the model object. For example, for sldemo_mdladv: mo = get_param('sldemo_mdladv','Object') 2 Use MAModelExclusionFile to specify the name of an exclusion file. For example, to specify exclusion file my_exclusion.xml in S:\work: mo.MAModelExclusionFile = ['S:\work\','my_exclusion.xml'] 3 22-10 Open the Model Advisor Exclusion Editor dialog box. The Exclusion File field contains the specified exclusion file and path.
Limit Model Checks By Excluding Gain and Outport Blocks Limit Model Checks By Excluding Gain and Outport Blocks This example shows how to exclude a gain block and all outport blocks from a Model Advisor check during a Model Advisor analysis. By excluding individual blocks from checks, you limit the scope of the analysis and might save time during model development and verification. 1 At the MATLAB command line, type sldemo_mdladv.
22 Checking Systems Interactively 9 22-12 After reviewing the check results, exclude the Gain2 block from all Model Advisor checks: a In the model window, right-click the Gain2 block and select Model Advisor > Exclude block only > All Checks. b In the Model Advisor Exclusion Editor dialog box, double-click in the first row of the Rationale field, and enter Exclude gain block. c Click OK to create the exclusion file.
Limit Model Checks By Excluding Gain and Outport Blocks 10 After reviewing the check results, exclude all Outport blocks from the Identify unconnected lines, input ports, and output ports check: a In the model window, right-click the Out4 block and select Model Advisor > Exclude all blocks of type Outport > Select checks. b In the Check Selector dialog box, scroll down and select Identify unconnected lines, input ports, and output ports. Click OK.
22 Checking Systems Interactively ports check. The sldemo_mdladv_exclusions file is updated with the Outport block exclusions. 11 In the left pane of the Model Advisor window, select By Product > Simulink and then: • Select the Show report after run check box. • Select Run Selected Checks to run a Model Advisor analysis.
Limit Model Checks By Excluding Gain and Outport Blocks • Model window. In the left pane of the Model Advisor window, select By Product > Simulink > Identify unconnected lines, input ports, and output ports. Then click the Enable highlighting button ( ). 13 Close sldemo_mdladv.
22 Checking Systems Interactively Model Checks for DO-178C/DO-331 Standard Compliance You can check that your model or subsystem complies with selected aspects of the DO-178C safety standard by running the Model Advisor. Navigate to By Product > Simulink Verification and Validation > Modeling DO-178C/DO-331 Checks and run the checks.
Model Checks for DO-178C/DO-331 Standard Compliance DO-178C/DO-331 Check Applicable High-Integrity System Modeling Guidelines “Check safety-related diagnostic settings for sample time” “hisl_0044: Configuration Parameters > Diagnostics > Sample Time” “Check safety-related diagnostic settings for signal data” “hisl_0005: Usage of Product blocks” “Check safety-related diagnostic settings for parameters” “hisl_0302: Configuration Parameters > Diagnostics > Data Validity > Parameters” “Check safety-rel
22 Checking Systems Interactively DO-178C/DO-331 Check Applicable High-Integrity System Modeling Guidelines “Check for blocks that do not link to requirements” “Check state machine type of Stateflow charts” “hisf_0001: Mealy and Moore semantics” “Check Stateflow charts for ordering of states and transitions” “hisf_0002: User-specified state/transition execution order” “Check Stateflow debugging options” “hisf_0011: Stateflow debugging settings” “Check usage of lookup table blocks” “Check for MATLA
Model Checks for DO-178C/DO-331 Standard Compliance DO-178C/DO-331 Check Applicable High-Integrity System Modeling Guidelines “Check usage of Logic and Bit Operations blocks” • “hisl_0016: Usage of blocks that compute relational operators” • “hisl_0017: Usage of blocks that compute relational operators (2)” • “hisl_0018: Usage of Logical Operator block” “Check usage of Ports and Subsystems blocks” • “hisl_0006: Usage of While Iterator blocks” • “hisl_0007: Usage of While Iterator subsystems” • “hisl_0
22 Checking Systems Interactively Model Checks for IEC 61508, ISO 26262, and EN 50128 Standard Compliance You can check that your model or subsystem complies with selected aspects of the following safety standards by running the Model Advisor: • IEC 61508-3 Functional safety of electrical/electronic/programmable electronic safetyrelated systems - Part 3: Software requirements • ISO 26262-6 Road vehicles - Functional safety - Part 6: Product development: Software level • EN 50128 Railway applications - Com
Model Checks for IEC 61508, ISO 26262, and EN 50128 Standard Compliance IEC 61508, ISO 26262, and EN 50128 Checks Applicable High-Integrity System Modeling Guidelines “Check usage of Stateflow constructs” • “hisf_0002: User-specified state/ transition execution order” • “hisf_0009: Strong data typing (Simulink and Stateflow boundary)” • “hisf_0011: Stateflow debugging settings” • “hisl_0061: Unique identifiers for clarity” “Check state machine type of Stateflow charts” “hisf_0001: Mealy and Moore semant
22 Checking Systems Interactively IEC 61508, ISO 26262, and EN 50128 Checks Applicable High-Integrity System Modeling Guidelines “Check for MATLAB Function interfaces with inherited properties” “himl_0002: Strong data typing at MATLAB function boundaries” “Check MATLAB Function metrics” “himl_0003: Limitation of MATLAB function complexity” “Check MATLAB Code Analyzer messages” “himl_0004: MATLAB Code Analyzer recommendations for code generation” “Check MATLAB code for global variables” “himl_0005: Usa
Model Checks for MathWorks Automotive Advisory Board (MAAB) Guideline Compliance Model Checks for MathWorks Automotive Advisory Board (MAAB) Guideline Compliance You can check that your model or subsystem complies with MathWorks Automotive Advisory Board (MAAB) guidelines by running the Model Advisor. Navigate to By Task > Modeling Standards for MAAB and run the checks.
22 Checking Systems Interactively By Task > MathWorks Automotive Advisory Modeling Board (MAAB) Check Standards for MAAB subfolder Simulink 22-24 MAAB Control Algorithm Modeling Guidelines, Version 3.
Model Checks for MathWorks Automotive Advisory Board (MAAB) Guideline Compliance By Task > MathWorks Automotive Advisory Modeling Board (MAAB) Check Standards for MAAB subfolder MAAB Control Algorithm Modeling Guidelines, Version 3.
22 Checking Systems Interactively By Task > MathWorks Automotive Advisory Modeling Board (MAAB) Check Standards for MAAB subfolder MAAB Control Algorithm Modeling Guidelines, Version 3.
Model Checks for MathWorks Automotive Advisory Board (MAAB) Guideline Compliance By Task > MathWorks Automotive Advisory Modeling Board (MAAB) Check Standards for MAAB subfolder “Check MATLAB Function metrics” MAAB Control Algorithm Modeling Guidelines, Version 3.
22 Checking Systems Interactively Model Checks for Requirements Links To check that every requirements link in your model has a valid target in a requirements document, navigate to Analysis > Requirements Traceability > Check Consistency and run the Model Advisor checks: • “Identify requirement links with missing documents” • “Identify requirement links that specify invalid locations within documents” • “Identify selection-based links having descriptions that do not match their requirements document text”
23 Check Systems Programmatically • “Checking Systems Programmatically” on page 23-2 • “Finding Check IDs” on page 23-3 • “Create a Function for Checking Multiple Systems” on page 23-4 • “Check Multiple Systems in Parallel” on page 23-6 • “Create a Function for Checking Multiple Systems in Parallel” on page 23-7 • “Archive and View Results” on page 23-9 • “Archive and View Model Advisor Run Results” on page 23-13
23 Check Systems Programmatically Checking Systems Programmatically The Simulink Verification and Validation product includes a programmable interface for scripting and for command-line interaction with the Model Advisor. Using this interface, you can: • Create scripts and functions for distribution that check one or more systems using the Model Advisor. • Run the Model Advisor on multiple systems in parallel on multicore machines (requires a Parallel Computing Toolbox™ license).
Finding Check IDs Finding Check IDs An ID is a unique string that identifies a Model Advisor check. You find check IDs in the Model Advisor, using check context menus. To Find... Do This... Check Title, ID, or location 1 of the MATLAB source 2 code Check ID Check IDs for selected checks in a folder On the model window toolbar, select Settings > Preferences. In the Model Advisor Preferences dialog box, select Show Source Tab. 3 In the right pane of the Model Advisor window, click the Source tab.
23 Check Systems Programmatically Create a Function for Checking Multiple Systems The following tutorial guides you through creating and testing a function to run multiple checks on any model. The function returns the number of failures and warnings. 1 In the MATLAB window, select New > Function. 2 Save the function as run_configuration.m. 3 In the MATLAB Editor, specify [output_args] as [fail, warn]. 4 Rename the function run_configuration. 5 Specify input_args to SysList.
Create a Function for Checking Multiple Systems 9 Save the function. 10 Test the function. In the MATLAB Command Window, run run_configuration.m on the sldemo_auto_climatecontrol/Heater Control subsystem: [failures, warnings] = run_configuration(... 'sldemo_auto_climatecontrol/Heater Control'); 11 Review the results. Click the Summary Report link to open the Model Advisor Command-Line Summary report.
23 Check Systems Programmatically Check Multiple Systems in Parallel Checking multiple systems in parallel reduces the processing time required by the Model Advisor to check multiple systems. If you have a Parallel Computing Toolbox license, you can check multiple systems in parallel on a multicore host machine. To enable parallel processing, use the ModelAdvisor.run function with ‘ParallelMode’ set to ‘On’. By default, ‘ParallelMode’ is set to ‘Off’. When you use ModelAdvisor.
Create a Function for Checking Multiple Systems in Parallel Create a Function for Checking Multiple Systems in Parallel If you have a Parallel Computing Toolbox license and a multicore host machine, you can create the following function to check multiple systems in parallel: 1 Create the run_configuration function as described in “Create a Function for Checking Multiple Systems” on page 23-4. 2 Save the function as run_fast_configuration.m.
23 Check Systems Programmatically 8 Run run_fast_configuration on the list of systems, specifying numParallel to be the number of cores in your system. For example, the following command specifies two cores: % Run on 2 cores [failures, warnings] = run_fast_configuration(SysList, 2); 9 23-8 Review the results. Click the Summary Report link to open the Model Advisor Command-Line Summary report.
Archive and View Results Archive and View Results You can archive and view the results of running the Model Advisor programmatically as described in the following sections: In this section...
23 Check Systems Programmatically You can review additional results in the Command Window by calling the DisplayResults parameter when you run the Model Advisor. For example, run the Model Advisor as follows: SysResultObjArray = ModelAdvisor.run('sldemo_auto_climatecontrol/Heater Control',... 'Configuration','slvnvdemo_mdladv_config.
Archive and View Results To view the Model Advisor Command-Line Summary report after loading an object, use the ModelAdvisor.summaryReport function. View Results in Model Advisor GUI In the Model Advisor window, you can view the results of running the Model Advisor programmatically using the viewReport function. In the Model Advisor window, you can review results, run checks, fix warnings and failures, and view and save Model Advisor reports. For more information, see “Run Model Checks”.
23 Check Systems Programmatically View Model Advisor Report For a single system or check, you can view the same Model Advisor report that you access from the Model Advisor GUI. To view the Model Advisor report for a system: • Open the Model Advisor Command-Line Summary report. In the Systems Run table, click the link for the Model Advisor report. • Use the viewReport function.
Archive and View Model Advisor Run Results Archive and View Model Advisor Run Results The following example guides you through archiving the results of running checks so that you can review them at a later time. To simulate archiving and reviewing, the steps in the tutorial detail how to save the results, clear out the MATLAB workspace (simulates shutting down MATLAB), and then load and review the results. 1 Call the ModelAdvisor.run function: SysResultObjArray = ModelAdvisor.
Customizing the Model Advisor
24 Overview of Customizing the Model Advisor
24 Overview of Customizing the Model Advisor Model Advisor Customization Using Model Advisor APIs and the Model Advisor Configuration Editor, you can: • Create your own Model Advisor checks. • Create custom configurations. • Specify the order in which you make changes to your model. • Create multiple custom configurations for different projects or modeling guidelines, and switch between these configurations in the Model Advisor. • Deploy custom configurations to your users.
25 Create Model Advisor Checks • “Create Model Advisor Checks Workflow” on page 25-2 • “Customization File Overview” on page 25-3 • “Quick Start Examples” on page 25-6 • “Create Check for Model Configuration Parameters” on page 25-16 • “Register Checks and Process Callbacks” on page 25-27 • “Define Custom Checks” on page 25-30 • “Create Callback Functions and Results” on page 25-37 • “Exclude Blocks From Custom Checks” on page 25-49 • “Model Advisor Code Examples” on page 25-52
25 Create Model Advisor Checks Create Model Advisor Checks Workflow 25-2 1 On your MATLAB path, create a customization file named sl_customization.m. In this file, create a sl_customization() function to register the custom checks that you create and optional process callbacks with the Model Advisor. For detailed information, see “Register Checks and Process Callbacks” on page 25-27. 2 Define custom checks and where they appear in the Model Advisor.
Customization File Overview Customization File Overview A customization file is a MATLAB file that you create and name sl_customization.m. The sl_customization.m file contains a set of functions for registering and defining custom checks, tasks, and groups. To set up the sl_customization.m file, follow the guidelines in this table. Function Description When Required sl_customization() Registers custom checks, tasks, Required for customizations to folders, and callbacks with the Model Advisor.
25 Create Model Advisor Checks Function Description When Required One or more calls to check actions Specifies actions the software Optional. performs for custom checks (see “Define Check Actions” on page 25-36 and “Action Callback Function” on page 25-43). One process callback function Specifies actions to be Optional. performed at startup and postexecution time (see “Define Startup and Post-Execution Actions Using Process Callback Functions” on page 25-28).
Customization File Overview 25-5
25 Create Model Advisor Checks Quick Start Examples In this section... “Add Customized Check to By Product Folder” on page 25-6 “Create Customized Pass/Fail Check” on page 25-7 “Create Customized Pass/Fail Check with Fix Action” on page 25-11 Add Customized Check to By Product Folder The following example shows how to add a customized check to a Model Advisor By Product > Demo subfolder. In this example, the customized check does not check model elements.
Quick Start Examples 5 From the model window, select Analysis > Model Advisor > Model Advisor to open the Model Advisor. 6 A System Selector — Model Advisor dialog box opens. Click OK. The Model Advisor window opens. It might take a few minutes. 7 If the By Product folder is not displayed in the Model Advisor window, select Show By Product Folder from the Settings > Preferences dialog box. 8 In the left pane, expand the By Product folder to display the subfolders.
25 Create Model Advisor Checks 1 In your working directory, update the sl_customization.m file, as shown below. This file registers and creates the check registration function defineModelAdvisorChecks, which also registers the check callback function SimpleCallback. The function SimpleCallback creates a check that finds Constant blocks that have numeric values. SimpleCallback uses the Model Advisor format template. function sl_customization(cm) % --- register custom checks cm.
Quick Start Examples 3 It the Command Window, enter: sl_refresh_customizations 4 From the MATLAB window, select New > Model to open a new Simulink model window. 5 In the Simulink model window, create two Constant blocks named Const_One and Const_1: • Right-click the Const_One block, choose Constant Parameters, and assign a Constant value of one. • Right-click the Const_1 block, choose Constant Parameters, and assign a Constant value of 1.
25 Create Model Advisor Checks 11 Follow the Recommended Action to fix the failed Constant block. In the Model Advisor dialog box: • Double-click the example2_qs/Const_1 hyperlink. • Change Constant Parameters > Constant value to two, or a nonnumeric value. • Rerun the Model Advisor check. Both Constant blocks now pass the check. See Also • “Register Checks and Process Callbacks” • ModelAdvisor.
Quick Start Examples Create Customized Pass/Fail Check with Fix Action The following example shows how to create a Model Advisor pass/fail check with a fix action. In this example, the Model Advisor checks Constant blocks. If a Constant block value is numeric, the check fails. The Model Advisor is also customized to create a fix action for the failed checks. 1 In your working directory, update the sl_customization.m file, as shown below.
25 Create Model Advisor Checks 'Text entry example']; rec.setAction(myAction); mdladvRoot.publish(rec, 'Demo'); % --- SimpleCallback function that checks constant blocks function result = SimpleCallback(system) mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); result = {}; all_constant_blk=find_system(system,'LookUnderMasks','all',... 'FollowLinks','on','BlockType','Constant'); blk_with_value=find_system(all_constant_blk,'RegExp','On','Value','^[0-9]'); ft = ModelAdvisor.
Quick Start Examples end ft.setSubBar(0); result = ft; mdladvObj.setActionEnable(false); 2 Close the Model Advisor and your model if either are open. 3 At the command prompt, enter: sl_refresh_customizations 4 From the Command Window, select New > Model to open a new model. 5 In the Simulink model window, create two Constant blocks named Const_One and Const_1: • Right-click the Const_One block, choose Constant Parameters, and assign a Constant value of one.
25 Create Model Advisor Checks 11 In the Model Advisor Dialog box, enter a nonnumeric value in the Text entry example parameter field in the Analysis section of the Model Advisor dialog box. In this example, the value is VarNm. 12 Click Fix Constant blocks. The Const_1 Constant block value changes from 1 to the nonnumeric value that you entered in step 10. The Result section of the dialog box lists the Old Value and New Value of the Const_1 block.
Quick Start Examples 13 In the Model Advisor dialog box, click Run This Check. Both constant blocks now pass the check. See Also • “Register Checks and Process Callbacks” • ModelAdvisor.FormatTemplate class • “Define Check Input Parameters” to add input parameters to Model Advisor checks • ModelAdvisor.
25 Create Model Advisor Checks Create Check for Model Configuration Parameters In this section... “Create Data File for Diagnostics Pane Configuration Parameter Check” on page 25-17 “Create Check for Diagnostics Pane Model Configuration Parameters” on page 25-19 “Data File for Configuration Parameter Check” on page 25-22 To verify the configuration parameters for your model, you can create a configuration parameter check. Decide which configuration parameter settings to use for your model.
Create Check for Model Configuration Parameters Create Data File for Diagnostics Pane Configuration Parameter Check This example shows how to create a data file for Diagnostics pane model configuration parameter check that warns when: • Algebraic loop is set to none • Minimize algebraic loop is not set to error • Block Priority Violation is not set to error In the example, to create the data file, you use the Advisor.authoring.generateConfigurationParameterDataFile function.
25 Create Model Advisor Checks 5 fixvalue of error. When you run the configuration parameter check using ex_DataFile.xml, the check fails if the Block Priority Violation setting is not error. The check fix action modifies the setting to error. In ex_DataFile.xml, edit the Algebraic loop (commandline:AlgebraicLoopMsg) parameter tagging so that the check warns if the value is none. Because you are specifying a configuration parameter that you do not want, you need a NegativeModelParameterConstraint.
Create Check for Model Configuration Parameters 7 Verify the data syntax with Advisor.authoring.DataFile.validate. At the command prompt, type: dataFile = 'myDataFile.xml'; msg = Advisor.authoring.DataFile.validate(dataFile); if isempty(msg) disp('Data file passed the XSD schema validation.
25 Create Model Advisor Checks rec = ModelAdvisor.Check('com.mathworks.Check1'); rec.Title = 'Example: Check model configuration parameters'; rec.setCallbackFcn(@(system)(Advisor.authoring.CustomCheck.checkCallback... (system)), 'None', 'StyleOne'); rec.TitleTips = 'Example check for model configuration parameters'; % --- data file input parameters rec.setInputParametersLayoutGrid([1 1]); inputParam1 = ModelAdvisor.InputParameter; inputParam1.Name = 'Data File'; inputParam1.Value = 'ex_DataFile.
Create Check for Model Configuration Parameters 6 7 8 From the model window, select Analysis > Model Advisor > Model Advisor to open the Model Advisor. In the left pane, select By Task > Example: My Group > Example: Check model configuration parameters. In the right pane, Data File is set to ex_DataFile.xml. To create ex_DataFile.xml, see “Create Data File for Diagnostics Pane Configuration Parameter Check” on page 25-17. Click Run This Check.
25 Create Model Advisor Checks Data File for Configuration Parameter Check You use an XML data file to create a configuration parameter check. To create the data file, you can use Advisor.authoring.generateConfigurationParameterDataFile or manually create the file yourself. The data file contains tagging that specifies check behavior. Each model configuration parameter specified in the data file is a subcheck. The structure for the data file is as follows:
Create Check for Model Configuration Parameters Within the tagging, the data file specifies two types of constraints: • - Specifies the configuration parameter setting that you want. • - Specifies the configuration parameter setting that you do not want.
25 Create Model Advisor Checks • dependson - Specifies a prerequisite subcheck. Optional. For example, to specify that configuration parameter subcheck ID_B must pass before configuration parameter subcheck ID_A is run, use this tagging: ID_B Data file tagging specifying a configuration parameter The following tagging specifies a subcheck for configuration parameter SolverType.
Create Check for Model Configuration Parameters SolverType Fixed-step Fixed-step ID_B Data file tagging specifying unwanted configuration parameter The following tagging specifies a subcheck for configuration parameter SolverType. The subcheck does not pass if the configuration parameter is set to Fixed-Step.
25 Create Model Advisor Checks Variable-step ID_B 25-26
Register Checks and Process Callbacks Register Checks and Process Callbacks In this section... “Create sl_customization Function” on page 25-27 “Register Checks and Process Callbacks” on page 25-27 “Define Startup and Post-Execution Actions Using Process Callback Functions” on page 25-28 Create sl_customization Function To add checks to the Model Advisor, on your MATLAB path, in the sl_customization.m file, create the sl_customization() function. Tip • You can have more than one sl_customization.
25 Create Model Advisor Checks • addModelAdvisorCheckFcn (@checkDefinitionFcn) Registers the checks that you define in checkDefinitionFcn to the By Product folder of the Model Advisor. The checkDefinitionFcn argument is a handle to the function that defines custom checks that you want to add to the Model Advisor as instances of the ModelAdvisor.Check class (see “Define Custom Checks” on page 25-30).
Register Checks and Process Callbacks and Value properties. For example, you can remove, rename, and selectively display checks and tasks in the By Task folder. • process_results stage: The Model Advisor executes process_results actions after checks complete execution. You can specify actions to examine and report on the results returned by check callback functions. If you create a process callback function, you must register it, as described in “Register Checks and Process Callbacks” on page 25-27.
25 Create Model Advisor Checks Define Custom Checks In this section... “About Custom Checks” on page 25-30 “Contents of Check Definitions” on page 25-30 “Display and Enable Checks” on page 25-32 “Define Where Custom Checks Appear” on page 25-33 “Check Definition Function” on page 25-34 “Define Check Input Parameters” on page 25-34 “Define Model Advisor Result Explorer Views” on page 25-35 “Define Check Actions” on page 25-36 About Custom Checks You can create a custom check to use in the Model Advisor.
Define Custom Checks Contents Description Check ID (required) Uniquely identifies the check. The Model Advisor uses this id to access the check. Handle to check callback function (required) Function that specifies the contents of a check. Check name (recommended) Creates a name for the check that the Model Advisor displays. Check properties (optional) Creates a user interface with the check.
25 Create Model Advisor Checks Display and Enable Checks You can create a check and specify how it appears in the Model Advisor. You can define when to display a check, or whether a user can select or clear a check using the Visible, Enable, and Value properties of the ModelAdvisor.Check class. Note: When adding checks to the Model Advisor as tasks, specify these properties in the ModelAdvisor.Task class. If you specify the properties in both ModelAdvisor.Check and ModelAdvisor.Task, the ModelAdvisor.
Define Custom Checks Visible? false Do not display check or task Ignore Enable and Value properties Display check or task Display check box at current Value, but grayed out true Enabled? false true Display check or task with active check box Define Where Custom Checks Appear Specify where the Model Advisor places custom checks using the following guidelines: • To place a check in a new folder in the Model Advisor root, use the ModelAdvisor.Group class. See “Define Custom Tasks” on page 26-14.
25 Create Model Advisor Checks Check Definition Function The following is an example of a function that defines the custom checks associated with the callback functions described in “Create Callback Functions and Results” on page 25-37. The check definition function returns a cell array of custom checks to be added to the Model Advisor. The check definitions in the example use the tasks described in “Define Custom Tasks” on page 26-14.
Define Custom Checks must define one instance of this class for each input parameter that you want to add to a Model Advisor check. Note: You do not have to create input parameters for every custom check. For a code example, see “Input Parameter Definition” on page 25-53. Specify Input Parameter Layout Specify the layout of input parameters in an input parameter definition. To place input parameters, use the following methods. Method Description ModelAdvisor.
25 Create Model Advisor Checks instance of this class for each list view that you want to add to a Model Advisor Result Explorer window. Note: You do not have to create list views for every custom check. For a code example, see “List View Definition” on page 25-54. Define Check Actions An action provides a way for you to specify an action that the Model Advisor performs to fix a Model Advisor check. When you define an action, the Model Advisor window includes an Action box below the Analysis box.
Create Callback Functions and Results Create Callback Functions and Results In this section...
25 Create Model Advisor Checks Utility Used for... find_system Getting handle or path to: • Blocks • Lines • Annotations When getting the object, you can: • Specify a search depth • Search under masks and libraries get_param / set_param Getting and setting system and block parameter values. inspect Getting object properties. First you must get a handle to the object. evalin Working in the base workspace.
Create Callback Functions and Results Argument I/O Type Description result Output MATLAB string that supports Model Advisor Formatting API calls or embedded HTML tags for text formatting.
25 Create Model Advisor Checks Here is an example of a detailed check callback function that checks optimization settings for simulation and code generation. function [ResultDescription, ResultDetails] = SampleStyleTwoCallback(system) ResultDescription ={}; ResultDetails ={}; model = bdroot(system); mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); % get object mdladvObj.
Create Callback Functions and Results Argument I/O Type Description system Input Path to the model or system analyzed by the Model Advisor. ResultDescription Output Cell array of MATLAB strings that supports the Model Advisor Formatting API calls or embedded HTML tags for text formatting. ResultDetails Output Cell array of cell arrays, each of which contains one or more Simulink objects such as blocks, ports, lines, and Stateflow charts.
25 Create Model Advisor Checks return end regularFontSize = str2double(regularFontSize); if regularFontSize<1 || regularFontSize>=99 mdladvObj.setCheckResultStatus(false); ResultDescription{end+1} = ModelAdvisor.Paragraph(['Invalid font size. '...
Create Callback Functions and Results mdladvObj.setListViewParameters... ({mdladvObj.getListViewParameters{:}, myLVParam}); needEnableAction = true; else ResultDescription{end+1} = ModelAdvisor.Paragraph(['All block font sizes '... 'are identical.']); ResultDetails{end+1} = {}; end mdladvObj.setActionEnable(needEnableAction); mdladvObj.
25 Create Model Advisor Checks Format Model Advisor Results • “Overview of Displaying Results” on page 25-44 • “Format Model Advisor Results” on page 25-44 • “Format Text” on page 25-45 • “Format Lists” on page 25-45 • “Format Tables” on page 25-45 • “Format Paragraphs” on page 25-47 • “Formatted Output” on page 25-47 Overview of Displaying Results You can make the analysis results of your custom checks appear similar to each other with minimal scripting using the Model Advisor ModelAdvisor.
Create Callback Functions and Results Format Text Text is the simplest form of output. You can format text in many different ways. The default text formatting is: • Empty • Default color (black) • Unformatted (not bold, italicized, underlined, linked, subscripted, or superscripted) To change text formatting, use the ModelAdvisor.Text constructor. When you want one type of formatting for all text, use this syntax: ModelAdvisor.
25 Create Model Advisor Checks • Bold title, row, and column headings Change table formatting using the ModelAdvisor.Table constructor. The following example code creates a subtable within a table. table1 = ModelAdvisor.Table(1,1); table2 = ModelAdvisor.Table(2,3); table2.setHeading('Table 2'); table2.setHeadingAlign('center'); table2.setColHeading(1, 'Header 1'); table2.setColHeading(2, 'Header 2'); table2.setColHeading(3, 'Header 3'); table1.setHeading('Table 1'); table1.
Create Callback Functions and Results table1.setRowHeading(n, ['Row ', num2str(n)]); end % set Table content for rowIndex=1:5 for colIndex=1:5 table1.setEntry(rowIndex, colIndex, ... num2str(matrixData(rowIndex, colIndex))); % set alignment of entries in second row if colIndex == 2 table1.setEntryAlign(rowIndex, colIndex, 'center'); end end end % overwrite content of cell 3,3 with a ModelAdvisor.Text text = ModelAdvisor.Text('Example Text'); table1.
25 Create Model Advisor Checks function result = SampleStyleOneCallback(system) mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); if strcmp(get_param(bdroot(system), 'ScreenColor'),'white') result = ModelAdvisor.Text('Passed',{'pass'}); mdladvObj.setCheckResultStatus(true); else msg1 = ModelAdvisor.Text(... ['It is recommended to select a Simulink window screen color'... ' of white for a readable and printable model. Click ']); msg2 = ModelAdvisor.Text('here'); msg2.
Exclude Blocks From Custom Checks Exclude Blocks From Custom Checks This example shows how to exclude blocks from custom checks. To save time during model development and verification, you might decide to exclude individual blocks from custom checks in a Model Advisor analysis. By modifying the sl_customization.m file to include the ModelAdvisor.Check.supportExclusion and Simulink.ModelAdvisor.
25 Create Model Advisor Checks • After both instances of searchResult = mdladvObj.filterResultWithExclusion(searchResult);, add searchResult = setdiff(allBlks, regularBlks);. • In the first location, the function now looks like: % find regular font name blocks regularBlks = find_system(allBlks,'FontName',regularFontName); % look for different font blocks in the system searchResult = setdiff(allBlks, regularBlks); searchResult = mdladvObj.
Exclude Blocks From Custom Checks 11 In the model window, right-click the Input block and select Model Advisor > Exclude block only > Check Simulink block font. 12 In the Model Advisor Exclusion Editor, click OK to update the exclusion file. 13 In the left pane of the Model Advisor window, select the By Product > Demo > Check Simulink block font check. In the right pane, select Run This Check. The check now passes.
25 Create Model Advisor Checks Model Advisor Code Examples In this section...
Model Advisor Code Examples % Defines actions to execute at startup and post-execution function [checkCellArray taskCellArray] = ... ModelAdvisorProcessFunction(stage, system, checkCellArray, taskCellArray) switch stage % Specify the appearance of the Model Advisor window at startup case 'configure' for i=1:length(checkCellArray) % Hide all checks that do not belong to custom folder if isempty(strfind(checkCellArray{i}.ID, 'mathworks.example')) checkCellArray{i}.Visible = false; checkCellArray{i}.
25 Create Model Advisor Checks inputParam2.Name = 'Standard font size'; inputParam2.Value='12'; inputParam2.Type='String'; inputParam2.Description='sample tooltip'; inputParam2.setRowSpan([2 2]); inputParam2.setColSpan([1 1]); inputParam3 = ModelAdvisor.InputParameter; inputParam3.Name='Valid font'; inputParam3.Type='Combobox'; inputParam3.Description='sample tooltip'; inputParam3.Entries={'Arial', 'Arial Black'}; inputParam3.setRowSpan([2 2]); inputParam3.setColSpan([2 2]); rec.
Model Advisor Code Examples The following code, when included in a check definition function, adds the Explore Result button to the check in the Model Advisor. rec = ModelAdvisor.Check('com.mathworks.sample.Check1'); % add 'Explore Result' button rec.ListViewVisible = true; The following code, when included in a check callback function, provides the information to populate the Model Advisor Result Explorer. mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); mdladvObj.
25 Create Model Advisor Checks Informational Check Callback Function The following code is an example of a callback function for a custom informational check that finds and displays the model configuration and checksum information. The informational check uses the Result Template API to format the check result. An informational check includes the following items in the results: • A description of what the check is reviewing. • References to standards, if applicable.
Model Advisor Code Examples function resultDescription = modelVersionChecksumCallbackUsingFT(system) resultDescription = []; system = getfullname(system); model = bdroot(system); % Format results in a list using Model Advisor Result Template API ft = ModelAdvisor.FormatTemplate('ListTemplate'); % Add See Also section for references to standards docLinkSfunction{1} = {['IEC 61508-3, Table A.8 (5)' ...
25 Create Model Advisor Checks Basic Check with Pass/Fail Status Here is an example of a callback function for a custom basic check that finds and reports unconnected lines, input ports, and output ports. A basic check includes the following items in the results: • A description of what the check is reviewing. • References to standards, if applicable. • The status of the check. • A description of the status. • Results for the check. • The recommended actions to take when the check does not pass.
Model Advisor Code Examples % Basic checks do not have subresults, supress line setSubBar(ft,false); % Check for unconnected lines, inputs, and outputs sysHandle = get_param(system, 'Handle'); uLines = find_system(sysHandle, ... 'Findall', 'on', ... 'LookUnderMasks', 'on', ... 'Type', 'line', ... 'Connected', 'off'); uPorts = find_system(sysHandle, ... 'Findall', 'on', ... 'LookUnderMasks', 'on', ... 'Type', 'port', ...
25 Create Model Advisor Checks setRecAction(ft,'Connect the specified blocks.'); % Create a list of handles to problem objects setListObj(ft,modelObj); ResultStatus = false; end % Pass the list template object to the Model Advisor ResultDescription{end+1} = ft; % Set overall check status mdladvObj.setCheckResultStatus(ResultStatus); Check With Subchecks and Actions Here is an example of a callback function for a custom check that finds and reports optimization settings.
Model Advisor Code Examples % Title and description of first subcheck setSubTitle(ft1,'Verify Block reduction setting'); setInformation(ft1,'Check whether the ''Block reduction'' check box is cleared.'); % Add See Also section with references to applicable standards docLinks{1} = {['Reference DO-178B Section 6.3.4e - Source code ' ...
25 Create Model Advisor Checks ResultStatus = false; end ResultDescription{end+1} = ft2; % Pass list template object to Model Advisor mdladvObj.setCheckResultStatus(ResultStatus); % Set overall check status % Enable Modify Settings button when check fails mdladvObj.
26 Create Custom Configurations by Organizing Checks and Folders • “Create Custom Configurations” on page 26-2 • “Create Configurations by Organizing Checks and Folders” on page 26-3 • “Create Procedural-Based Configurations” on page 26-4 • “Organize Checks and Folders Using the Model Advisor Configuration Editor” on page 26-5 • “Organize Customization File Checks and Folders” on page 26-12 • “Verify and Use Custom Configurations” on page 26-18 • “Model Advisor Code Examples” on page 26-20
26 Create Custom Configurations by Organizing Checks and Folders Create Custom Configurations You can use the Model Advisor APIs and Model Advisor Configuration Editor available with Simulink Verification and Validation to do the tasks listed in the following table. To See Create custom configurations by organizing “Organize Checks and Folders Using the Model Advisor checks and folders. Model Advisor Configuration Editor” Specify the order in which you make changes to your model.
Create Configurations by Organizing Checks and Folders Create Configurations by Organizing Checks and Folders To customize the Model Advisor with MathWorks and custom checks, perform the following tasks: 1 Review the information in “Requirements for Customizing the Model Advisor” on page 24-2. 2 Optionally, author custom checks in a customization file. See “Create Model Advisor Checks”. 3 Organize the checks into new and existing folders to create custom configurations.
26 Create Custom Configurations by Organizing Checks and Folders Create Procedural-Based Configurations You can create a procedural-based configuration that allows you to specify the order in which you make changes to your model. You organize checks into procedures using the procedures API. A check in a procedure does not run until the previous check passes. A procedural-based configuration runs until a check fails, requiring you to modify the model to pass the check and proceed to the next check.
Organize Checks and Folders Using the Model Advisor Configuration Editor Organize Checks and Folders Using the Model Advisor Configuration Editor In this section...
26 Create Custom Configurations by Organizing Checks and Folders Model Advisor Configuration Editor When you select a folder or check in the Model Advisor Configuration Editor hierarchy, the Workflow pane changes to display information about the check or folder. You can change the display name of the check or folder in this pane.
Organize Checks and Folders Using the Model Advisor Configuration Editor The Model Advisor Check Browser window includes a read-only list of available checks. If you delete a check in the Model Advisor Configuration Editor, you can retrieve a copy of it from the Model Advisor Check Browser. Tip If you use a process callback function in a sl_customization file to hide checks and folders, the Model Advisor Configuration Editor and Model Advisor Check Browser do not display the hidden checks and folders.
26 Create Custom Configurations by Organizing Checks and Folders Model Advisor Check Browser Using the Model Advisor Configuration Editor, you can perform the following actions. To... Select...
Organize Checks and Folders Using the Model Advisor Configuration Editor To... Select... Edit > Move down The check or folder and drag and drop Rename checks and folders The check or folder and edit Display Name in right pane. Note: MathWorks folder display names are restricted. When you rename a folder, you cannot use the restricted display names.
26 Create Custom Configurations by Organizing Checks and Folders 1 To include custom checks in the new Model Advisor configuration, update the Simulink environment to include your sl_customization.m file. For more information, see “Update the Environment to Include Your sl_customization File”. 2 Start the Model Advisor Configuration Editor. To start the Model Advisor Configuration Editor... Do this: Programmatically At the MATLAB command line, enter Simulink.ModelAdvisor.openConfigUI.
Organize Checks and Folders Using the Model Advisor Configuration Editor 6 In the right pane, edit Display Name to rename the folder. For the purposes of this tutorial, rename the folder to Review Optimizations. 7 In the Model Advisor Check Browser window, in the Find field, enter optimization to find Simulink > Check optimization settings. 8 Drag and drop Check optimization settings into Review Optimizations.
26 Create Custom Configurations by Organizing Checks and Folders Organize Customization File Checks and Folders In this section... “Customization File Overview” on page 26-12 “Register Tasks and Folders” on page 26-13 “Define Custom Tasks” on page 26-14 “Define Custom Folders” on page 26-16 “Customization Example” on page 26-17 Note: While you can organize checks and folders within a customization file, use the Model Advisor Configuration Editor. Customization File Overview The sl_customization.
Organize Customization File Checks and Folders Function Description Required or Optional One or more groups Defines custom groups (see Required to add custom tasks “Define Custom Tasks” on page to new folders in the Model 26-14). Advisor, except when adding a new subfolder to the By Product folder. Write one group definition for each new folder. One process callback function Specifies actions that Simulink Optional.
26 Create Custom Configurations by Organizing Checks and Folders function sl_customization(cm) The customization manager object includes methods for registering custom checks, tasks, folders, and process callbacks. Use these methods to register customizations specific to your application, as described in the sections that follow.
Organize Customization File Checks and Folders Add Check to Custom or Multiple Folders Using Tasks You can use custom tasks for adding checks to the Model Advisor, either in multiple folders or in a single, custom folder. You define custom tasks in one or more functions that specify the properties of each instance of the ModelAdvisor.Task class. Define one instance of this class for each custom task that you want to add to the Model Advisor.
26 Create Custom Configurations by Organizing Checks and Folders Define Where Tasks Appear You can specify where the Model Advisor places tasks within the Model Advisor using the following guidelines: • To place a task in a new folder in the Model Advisor Task Manager, use the ModelAdvisor.Group class. See “Define Custom Folders” on page 26-16. • To place a task in a new folder in the By Task folder, use the ModelAdvisor.FactoryGroup class. See “Define Custom Folders” on page 26-16.
Organize Customization File Checks and Folders Define Where Custom Folders Appear You can specify the location of custom folders within the Model Advisor using the following guidelines: • To define a new folder in the Model Advisor Task Manager, use the ModelAdvisor.Group class. • To define a new folder in the By Task folder, use the ModelAdvisor.FactoryGroup class. Note: To define a new folder in the By Product folder, use the ModelAdvisor.Root.publish method within a custom check.
26 Create Custom Configurations by Organizing Checks and Folders Verify and Use Custom Configurations In this section... “Update the Environment to Include Your sl_customization File” on page 26-18 “Verify Custom Configurations” on page 26-18 Update the Environment to Include Your sl_customization File When you start Simulink, it reads customization (sl_customization.m) files.
Verify and Use Custom Configurations Folders Using the Model Advisor Configuration Editor” on page 26-10, select optimization_configuration.mat. 6 When the Model Advisor reopens, verify that the configuration contains the new folders and checks. For example, the Review Optimizations folder and the Check Simulink optimization settings and Check safety-related optimization settings checks. 7 Optionally, run the checks.
26 Create Custom Configurations by Organizing Checks and Folders Model Advisor Code Examples In this section... “Register Custom Tasks and Folders” on page 26-20 “Task Definition Function” on page 26-20 “Group Definition” on page 26-21 Register Custom Tasks and Folders The following code example registers custom tasks and folders: function sl_customization(cm) % register custom factory group cm.addModelAdvisorTaskFcn(@defineModelAdvisorTasks); % register custom tasks. cm.
Model Advisor Code Examples mdladvRoot.register(MAT1); % Define task that uses Sample Check 2: Basic Check with Pass/Fail Status MAT2 = ModelAdvisor.Task('mathworks.example.task.unconnectedObjects'); MAT2.DisplayName = 'Check for unconnected objects'; setCheck(MAT2, 'mathworks.example.unconnectedObjects'); MAT2.Description = ['Identify unconnected lines, input ports, and output ' ... 'ports in the model or subsystem.']; mdladvRoot.
26 Create Custom Configurations by Organizing Checks and Folders rec = ModelAdvisor.FactoryGroup('com.mathworks.sample.factorygroup'); rec.DisplayName='Demo Factory Group'; rec.Description='Demo Factory Group'; rec.addCheck('mathworks.example.configManagement'); rec.addCheck('mathworks.example.unconnectedObjects'); rec.addCheck('mathworks.example.optimizationSettings'); mdladvRoot.
27 Create Procedural-Based Model Advisor Configurations • “Create Procedures” on page 27-2 • “Create a Procedural-Based Configuration” on page 27-5
27 Create Procedural-Based Model Advisor Configurations Create Procedures In this section... “What Is a Procedure?” on page 27-2 “Create Procedures Using the Procedures API” on page 27-2 “Define Procedures” on page 27-2 What Is a Procedure? A procedure is a series of checks. The checks in a procedure depend on passing the previous checks. If Check A is the first check in a procedure and Check B follows, the Model Advisor does not run Check B until Check A passes.
Create Procedures Add Subprocedures and Tasks to Procedures You can add subprocedures or tasks to a procedure. The tasks are wrappers for checks. • Use the ModelAdvisor.Procedure.addProcedure method to add a subprocedure to a procedure. • Use the ModelAdvisor.Procedure.addTask method to add a task to a procedure. Define Where Procedures Appear You can specify where the Model Advisor places a procedure using the ModelAdvisor.Group.addProcedure method.
27 Create Procedural-Based Model Advisor Configurations MAP2=ModelAdvisor.Procedure('com.mathworks.example.procedure_sub2'); MAP3=ModelAdvisor.Procedure('com.mathworks.example.procedure_sub3'); %Add sub procedures to procedure addProcedure(MAP, MAP1); addProcedure(MAP, MAP2); addProcedure(MAP, MAP3); %register the procedures mdladvRoot = ModelAdvisor.Root; mdladvRoot.register(MAP); mdladvRoot.register(MAP1); mdladvRoot.register(MAP2); mdladvRoot.
Create a Procedural-Based Configuration Create a Procedural-Based Configuration In this example, you examine a procedural-based configuration. 1 At the MATLAB command line, type slvnvdemo_mdladv. 2 In the model window, select View demo sl_customization.m. The sl_customization.m file opens in the MATLAB Editor window. The file contains three checks created in the function defineModelAdvisorChecks: • ModelAdvisor.Check('com.mathworks.sample.Check1') - Checks Simulink block fonts. • ModelAdvisor.
27 Create Procedural-Based Model Advisor Configurations MAT6 = ModelAdvisor.Task('com.mathworks.sample.TaskSample6'); MAT6.DisplayName='Check model optimization settings'; MAT6.setCheck('com.mathworks.sample.Check3'); mdladvRoot.register(MAT6); • The ModelAdvisor.Procedure.addTask method adds task MAT4 to My Procedure and tasks MAT5 and MAT6 to My sub_Procedure. The ModelAdvisor.Procedure.addProcedure method adds My sub_Procedure to My Procedure: % Add tasks to procedures: % Add Task4 to MAP MAP.
Create a Procedural-Based Configuration 8 In the Action section of the Model Advisor dialog box, click Fix block fonts. 9 In the left pane of the Model Advisor, select My Procedure. In the right pane of the Model Advisor, click Run All. The Check Simulink block font check passes. The Model Advisor runs the Check Simulink window screen color check. This check fails and the Model Advisor stops checking. 10 In the Action section of the Model Advisor dialog box, click Fix window screen color.
28 Deploy Custom Configurations • “Overview of Deploying Custom Configurations” on page 28-2 • “How to Deploy Custom Configurations” on page 28-3 • “Manually Load and Set the Default Configuration” on page 28-4 • “Automatically Load and Set the Default Configuration” on page 28-5
28 Deploy Custom Configurations Overview of Deploying Custom Configurations In this section... “About Deploying Custom Configurations” on page 28-2 “Deploying Custom Configurations Workflow” on page 28-2 About Deploying Custom Configurations When you create a custom configuration, often you deploy the custom configuration to your development group. Deploying the custom configuration allows your development group to review models using the same checks.
How to Deploy Custom Configurations How to Deploy Custom Configurations To deploy a custom configuration: 1 Determine which files to distribute. You might need to distribute more than one file. If You... Using the... Distribute... Created custom checks Customization file • sl_customization.m • Files containing check and action callback functions (if separate) Organized checks and folders Model Advisor Configuration Editor Configuration MAT file Customization file sl_customization.
28 Deploy Custom Configurations Manually Load and Set the Default Configuration When you use the Model Advisor, you can load any configuration. Once you load a configuration, you can set it so that the Model Advisor use that configuration every time you open the Model Advisor. 1 Open the Model Advisor. 2 Select Settings > Load Configuration. 3 In the Open dialog box, navigate to and select the configuration file that you want to edit. 4 Click Open.
Automatically Load and Set the Default Configuration Automatically Load and Set the Default Configuration When you use the Model Advisor, you can automatically set the default configuration by modifying an sl_customization.m file. For more information on creating the sl_customization.m file, see “Register Checks and Process Callbacks” on page 25-27. 1 Place a configuration MAT file on your MATLAB path.
