pslinkfun

Manage model analysis at the command line

Syntax

pslinkfun('annotations','type',typeValue,'kind',kindValue,Name,Value)

pslinkfun('openresults',systemName)

pslinkfun('advancedoptions')

pslinkfun('enablebacktomodel')

pslinkfun('help')

pslinkfun('jobmonitor')

Description

pslinkfun('annotations','type',typeValue,'kind',kindValue,Name,Value) adds an annotation of type typeValue and kind kindValue to the selected block in the model. You can specify a different block using a Name,Value pair argument. You can also add notes about a severity classification, an action status, or other comments using Name,Value pairs.

In the generated code associated with the annotated block, Polyspace^® adds code comments before and after the lines of code. Polyspace reads these comments and marks Polyspace results of the specified kind with the annotated information.

Syntax limitations:

• You can have only one annotation per block. If a block produces both a rule violation and an error, you can annotate only one type.

• Even though you apply annotations to individual blocks, the scope of the annotation can be larger. The generated code from one block can overlap with another, causing the annotation to also overlap.

  For example, consider this model. The first summation block has a Polyspace annotation, but the second does not.

  

  However, the associated generated code adds all three inputs in one line of code.

  /* polyspace:begin<RTE:OVFL:Medium:To Fix>*/
  annotate_y.Out1=(annotate_u.In1+annotate_U.In2)+annotate_U.In3;
  /* polyspace:end<RTE:OVFL:Medium:To Fix> */

  Therefore, the annotation justifies both summations.

pslinkfun('openresults',systemName) opens the Polyspace results associated with the model or subsystem systemName in the Polyspace environment.

pslinkfun('advancedoptions') opens the advanced verification options window to configure additional options for the current model.

pslinkfun('enablebacktomodel') enables the back-to-model feature of the Simulink^® plug-in. If your Polyspace results do not properly link to back to the model blocks, run this command.

pslinkfun('help') opens the Polyspace documentation in a separate window. Use this option for only pre-R2013b versions of MATLAB^®.

pslinkfun('jobmonitor') opens the Polyspace Job Monitor to display remote verifications in the queue.

Examples

Annotate a Block and Run a Polyspace Code Prover Verification

Use the Polyspace annotation function to annotate a block and see the annotation in the verification results.

In the example model WhereAreTheErrors, set the current block to the division block of the 10* x // (x-y) subsystem. Then, add an annotation to the current block to mark division by zero (DIV) errors as justified with the annotation.

model = 'WhereAreTheErrors';
open(model)
gcb = 'WhereAreTheErrors/10* x // (x-y)/Divide';
pslinkfun('annotations','type','RTE','kind','ZDV','status',...
	'justified','comment','verified not an error')

In Simulink, the division block of the 10* x // (x-y) subsystem now has a Polyspace annotation.

At the command line, generate code for the model and run a verification. After the analysis is finished, open the result in the Polyspace environment:

slbuild(model)
pslinkrun(model)
pslinkfun('openresults',model)

If you look at the orange division by zero error, the check is justified and includes the status and comments from your annotation.

Specify Polyspace Configuration Options

Change advanced Polyspace options and set the new configuration as a template.

Load the model WhereAreTheErrors and open the advanced options window.

model = 'WhereAreTheErrors';
load_system(model)
pslinkfun('advancedoptions')

The Polyspace configuration window opens. Specify Polyspace options such as compiler behavior, target language, and target environment using the configuration window.

This workflow for specifying Polyspace configuration is not recommended. Use the function pslinkoptions instead. See Create generic options object for code generated by Embedded Coder.

View Polyspace Queue

Run a remote analysis, view the analysis in the queue.

Before performing this example, check that your Polyspace configuration is set up for remote analysis.

Build the model WhereAreTheErrors, create a Polyspace options object, set the verification mode, and open the advanced options window.

model = 'WhereAreTheErrors';
load_system(model)
slbuild(model)
opts = pslinkoptions(model);
opts.VerificationMode = 'CodeProver';
pslinkfun('advancedoptions')

In the Run Settings pane, select the options Run Code Prover analysis on a remote cluster.

Run Polyspace, then open the Job Monitor to monitor your remote job.

pslinkrun(model,opts)
pslinkfun('jobmonitor')

Input Arguments

typeValue — type of result

type acronym

The type of check with which to annotate the block, specified as an acronym. The acronyms for different Bug Finder and Code Prover results are:

• 'RTE' for Code Prover run-time errors. For examples of run-time error result, see Run-Time Checks.

• 'MISRA-C' for MISRA C™: 2004 coding rule violations (C code only). See MISRA C:2004 and MISRA AC AGC Coding Rules.

• 'MISRA-AC-AGC' for MISRA™ AC AGC coding rule violations (C code only). See MISRA C:2004 and MISRA AC AGC Coding Rules.

• 'MISRA-C3' for MISRA C: 2012 coding rule violations (C code only). See MISRA C:2012 Directives and Rules.

• 'MISRA-C-2023' for MISRA C: 2023 coding rule violations (C code only). See MISRA C:2023 Directives and Rules.

• 'MISRA-CPP' for MISRA C++:2008 coding rule violations (C++ code only). See MISRA C++:2008 Rules.

• 'MISRA-CPP-2023' for MISRA C++:2023 coding rule violations (C++ code only). See MISRA C++:2023 Rules and Directives.

• 'JSF' for JSF^® AV C++ coding rule violations (C++ code only). See JSF AV C++ Coding Rules.

• 'CERT-C' for CERT^® C coding rule violations (C code only). See CERT C Rules and Recommendations.

• 'CERT-CPP' for CERT C++ coding rule violations (C++ code only). See CERT C++ Rules.

• 'ISO-17961' for ISO/IEC TS 17961 rule violations (C code only). See ISO/IEC TS 17961 Rules.

• 'AUTOSAR-CPP14' for AUTOSAR C++14 rule violations (C++ code only). See AUTOSAR C++14 Rules.

• 'CWE' for common weakness enumeration violations. See Common Weakness Enumeration (CWE).

• 'GUIDELINE' for guideline violations. See Guidelines.

• 'CUSTOM' for custom rule violations. See Custom Coding Rules.

Use the typeValue and kindvalue together to specify the result with which to annotate a Simulink block.

Example: pslinkfun('annotations','type','MISRA-C-2023','kind','2.2')

kindValue — specific check or coding rule

check acronym | rule number

The specific check or coding rule specified by the acronym of the check or the coding rule number. See the table for the specific input for each type of annotation:

type Value	kind Values
'RTE'	Use the abbreviation associated with the type of check that you want to annotate. For example, 'UNR' – Unreachable Code. For the list of possible checks, see: Run-Time Checks.
'Defect'	Use the abbreviation associated with the type of check that you want to annotate. For example, 'INT_OVFL' – Integer Overflow. For the list of possible checks, see: Defects.
'MISRA-C'	Use the rule number that you want to annotate. For example, '2.2'. For the list of supported MISRA C:2004 rules and their numbers, see Supported MISRA C:2004 and MISRA AC AGC Rules.
'MISRA-AC-AGC'	Use the rule number that you want to annotate. For example, '2.2'. For the list of supported MISRA AC AGC rules and their numbers, see Supported MISRA C:2004 and MISRA AC AGC Rules.
'MISRA-C3'	Use the rule number that you want to annotate. For example, '2.2'. For the list of supported MISRA C:2012 rules and their numbers, see MISRA C:2012 Directives and Rules.
'MISRA-C-2023'	Use the rule number that you want to annotate. For example, '2.2'. For the list of supported MISRA C:2023 rules and their numbers, see MISRA C:2023 Directives and Rules.
'MISRA-CPP'	Use the rule number that you want to annotate. For example, '0-1-1'. For the list of supported MISRA C++ rules and their numbers, see MISRA C++:2008 Rules.
'MISRA-CPP-2023'	Use the rule number that you want to annotate. For example, '0.0.1'. For the list of supported MISRA C++ rules and their numbers, see MISRA C++:2023 Rules and Directives.
'JSF'	Use the rule number that you want to annotate. For example, '3'. For the list of supported JSF C++ rules and their numbers, see Supported JSF C++ Coding Rules.
'CERT-C'	Use the rule number that you want to annotate. For example, 'PRE00-C'. For the list of supported JSF C++ rules and their numbers, see CERT C Rules and Recommendations.
'CERT-CPP'	Use the rule number that you want to annotate. For example, 'PRE00-C'. For the list of supported JSF C++ rules and their numbers, see CERT C++ Rules.
'ISO-17961'	Use the rule number that you want to annotate. For example, 'accfree'. For the list of supported JSF C++ rules and their numbers, see ISO/IEC TS 17961 Rules.
'AUTOSAR-CPP14'	Use the rule number that you want to annotate. For example, 'A0-1-1'. For the list of supported JSF C++ rules and their numbers, see AUTOSAR C++14 Rules.
'CWE'	Use the rule number that you want to annotate. For example, '14'. For the list of supported JSF C++ rules and their numbers, see Common Weakness Enumeration (CWE).
'GUIDELINE'	Use the rule number that you want to annotate. For example, 'SC03'. For the list of supported JSF C++ rules and their numbers, see Guidelines.
'CUSTOM'	Use the rule number that you want to annotate. For example, '1.1'. For the list of supported JSF C++ rules and their numbers, see Custom Coding Rules.

Use the typeValue and kindvalue together to specify the result with which to annotate a Simulink block.

Example: pslinkfun('annotations','type','MISRA-CPP-2023','kind','0.0.1')

Data Types: char

systemName — Simulink model

system | subsystem

Simulink model specified by the system or subsystem name.

Example: pslinkfun('openresults','WhereAreTheErrors')

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'block','MyModel\Sum', 'status','to fix'

block — block to be annotated

gcb (default) | block name

The block you want to annotate specified by the block name. If you do not use this option, the block returned by the function gcb is annotated.

Example: 'block','MyModel\Sum'

class — severity of the check

'high' | 'medium' | 'low' | 'unset'

Severity of the check specified as high, medium, low, or unset.

Example: 'class','high'

status — action status

'unreviewed' | 'to investigate' | 'to fix' | 'justified' | 'no action planned' | 'not a defect' | 'other'

Action status of the check specified as unreviewed, to investigate, to fix, justified, no action planned, not a defect, or other.

The statuses, justified, not a defect, and no action planned also mark the result as justified.

Example: 'status','no action planned'

comment — additional comments

character vector

Additional comments specified as a character vector. The comments provide more information about why the results are justified.

Example: 'comment','defensive code'

Version History

Introduced in R2014a