Simulink.MSFcnRunTimeBlock - Get run-time information about Level-2 MATLAB S-function block - MATLAB (original) (raw)

Get run-time information about Level-2 MATLAB S-function block

Description

This class allows a Level-2 MATLAB® S-function or other MATLAB program to obtain information from Simulink® software and provide information to Simulink software about a Level-2 MATLAB S-Function block. Simulink software creates an instance of this class for each Level-2 MATLAB S-Function block in a model. Simulink software passes the object to the callback methods of Level-2 MATLAB S-functions when it updates or simulates a model, allowing the callback methods to get and provide block-related information to Simulink software. See Write Level-2 MATLAB S-Functions for more information.

You can also use instances of this class in MATLAB programs to obtain information about Level-2 MATLAB S-Function blocks during a simulation. See Access Block Data During Simulation for more information.

The Level-2 MATLAB S-function template_matlabroot_/toolbox/simulink/blocks/[msfuntmpl.m](https://mdsite.deno.dev/matlab:edit%28[matlabroot,'/toolbox/simulink/blocks/msfuntmpl.m']%29;) shows how to use a number of the following methods.

Property Summary

Method Summary

Properties

AllowSignalsWithMoreThan2D

Description

Allow Level-2 MATLAB S-functions to use multidimensional signals. You must set theAllowSignalsWithMoreThan2D property in the setup method.

DialogPrmsTunable

Description

Specifies whether a dialog parameter of the S-function is tunable. Tunable parameters are registered as run-time parameters when you call the AutoRegRuntimePrms method. Note that SimOnlyTunable parameters are not registered as run-time parameters. For example, the following lines initializes three dialog parameters where the first is tunable, the second in not tunable, and the third is tunable only during simulation.

block.NumDialogPrms = 3; block.DialogPrmsTunable = {'Tunable','Nontunable','SimOnlyTunable'};

NextTimeHit

Description

Time of the next sample hit for variable sample-time S-functions.

Methods

AutoRegRuntimePrms

Purpose

Register a block's tunable dialog parameters as run-time parameters.

Syntax

AutoRegRuntimePrms;

Description

The default names for the MATLAB S-Function tunable parameters are MSFcnParameter,MSFcnParameter1, … MSFcnParameterN. You can assign other names by passing a cell array to AutoRegRuntimePrms. UseAutoRegRuntimePrms in the PostPropagationSetup method to register this block's tunable dialog parameters as run-time parameters.

AutoUpdateRuntimePrms

Purpose

Update a block's run-time parameters.

Syntax

AutoUpdateRuntimePrms;

Description

Automatically update the values of the run-time parameters during a call to [ProcessParameters](../sfg/mdlprocessparameters.html).

IsDoingConstantOutput

Purpose

Determine whether this is in the constant sample time stage of a simulation.

Syntax

bVal = IsDoingConstantOutput;

Description

Returns true if this is the constant sample time stage of a simulation, i.e., the stage at the beginning of a simulation where Simulink software computes the values of block outputs that cannot change during the simulation (see Constant Sample Time). Use this method in the [Outputs](../sfg/mdloutputs.html) method of an S-function with port-based sample times to avoid unnecessarily computing the outputs of ports that have constant sample time, i.e., [inf, 0].

function Outputs(block) . . if block.IsDoingConstantOutput ts = block.OutputPort(1).SampleTime; if ts(1) == Inf %% Compute port's output. end end . . %% end of Outputs

See Specifying Port-Based Sample Times for more information.

IsMajorTimeStep

Purpose.

Determine whether current time step is a major or a minor time step.

Syntax

bVal = IsMajorTimeStep;

Description

Returns true if the current time step is a major time step; false, if it is a minor time step. This method can be called only from the [Outputs](../sfg/mdloutputs.html) or [Update](../sfg/mdlupdate.html) methods.

IsSampleHit

Purpose

Determine whether the current simulation time is one at which a task handled by this block is active.

Syntax

bVal = IsSampleHit(stIdx);

Arguments

stIdx

Global index of the sample time to be queried.

Description

Use in Outputs or Update block methods when the MATLAB S-function has multiple sample times to determine whether a sample hit has occurred at stIdx. The sample time index stIdx is a global index for the Simulink model. For example, consider a model that contains three sample rates of 0.1, 0.2, and 0.5, and a MATLAB S-function block that contains two rates of 0.2 and 0.5. In the MATLAB S-function, block.IsSampleHit(0) returns true for the rate 0.1, not the rate 0.2.

This block method is similar to ssIsSampleHit for C-MeX S-functions, however ssIsSampleHit returns values based on only the sample times contained in the S-function. For example, if the model described above contained a C-MeX S-function with sample rates of 0.2 and 0.5, ssIsSampleHit(S,0,tid) returns true for the rate of 0.2.

Use port-based sample times to avoid using the global sample time index for multi-rate systems (see Simulink.BlockPortData).

IsSpecialSampleHit

Purpose

Determine whether the current simulation time is one at which multiple tasks implemented by this block are active.

Syntax

bVal = IsSpecialSampleHit(stIdx1,stIdx1);

Arguments

stIdx1

Index of sample time of first task to be queried.

stIdx2

Index of sample time of second task to be queried.

Description

Use in Outputs or Update block methods to ensure the validity of data shared by multiple tasks running at different rates. Returns true if a sample hit has occurred at stIdx1 and a sample hit has also occurred at stIdx2 in the same time step (similar to ssIsSpecialSampleHit for C-Mex S-functions).

When using the IsSpecialSampleHit macro, the slower sample time must be an integer multiple of the faster sample time.

RegBlockMethod

Purpose

Register a block callback method.

Syntax

RegBlockMethod(methName, methHandle);

Arguments

methName

Name of method to be registered.

methHandle

MATLAB function handle of the callback method to be registered.

Description

Registers the block callback method specified by methName andmethHandle. Use this method in the setup function of a Level-2 MATLAB S-function to specify the block callback methods that the S-function implements.

RegisterDataTypeFxpBinaryPoint

Purpose

Register fixed-point data type with binary point-only scaling.

Syntax

dtID = RegisterDataTypeFxpBinaryPoint(isSigned, wordLength, fractionalLength, obeyDataTypeOverride);

Arguments

isSigned

true if the data type is signed.

false if the data type is unsigned.

wordLength

Total number of bits in the data type, including any sign bit.

fractionalLength

Number of bits in the data type to the right of the binary point.

obeyDataTypeOverride

true indicates that the Data Type Override setting for the subsystem is to be obeyed. Depending on the value of Data Type Override, the resulting data type could be Double, Single, ScaledDouble, or the fixed-point data type specified by the other arguments of the function.

false indicates that the Data Type Override setting is to be ignored.

Description

This method registers a fixed-point data type with Simulink software and returns a data type ID. The data type ID can be used to specify the data types of input and output ports, run-time parameters, and DWork states. It can also be used with all the standard data type access methods defined for instances of this class, such as DatatypeSize.

Use this function if you want to register a fixed-point data type with binary point-only scaling. Alternatively, you can use one of the other fixed-point registration functions:

If the registered data type is not one of the Simulink built-in data types, a Fixed-Point Designer™ license is checked out.

RegisterDataTypeFxpFSlopeFixexpBias

Purpose

Register fixed-point data type with [Slope Bias] scaling specified in terms of fractional slope, fixed exponent, and bias

Syntax

dtID = RegisterDataTypeFxpFSlopeFixexpBias(isSigned, wordLength, fractionalSlope, fixedexponent, bias, obeyDataTypeOverride);

Arguments

isSigned

true if the data type is signed.

false if the data type is unsigned.

wordLength

Total number of bits in the data type, including any sign bit.

fractionalSlope

Fractional slope of the data type.

fixedexponent

exponent of the slope of the data type.

bias

Bias of the scaling of the data type.

obeyDataTypeOverride

true indicates that the Data Type Override setting for the subsystem is to be obeyed. Depending on the value of Data Type Override, the resulting data type could be True Doubles, True Singles, ScaledDouble, or the fixed-point data type specified by the other arguments of the function.

false indicates that the Data Type Override setting is to be ignored.

Description

This method registers a fixed-point data type with Simulink software and returns a data type ID. The data type ID can be used to specify the data types of input and output ports, run-time parameters, and DWork states. It can also be used with all the standard data type access methods defined for instances of this class, such as DatatypeSize.

Use this function if you want to register a fixed-point data type by specifying the word length, fractional slope, fixed exponent, and bias. Alternatively, you can use one of the other fixed-point registration functions:

If the registered data type is not one of the Simulink built-in data types, a Fixed-Point Designer license is checked out.

RegisterDataTypeFxpSlopeBias

Purpose

Register data type with [Slope Bias] scaling.

Syntax

dtID = RegisterDataTypeFxpSlopeBias(isSigned, wordLength, totalSlope, bias, obeyDataTypeOverride);

Arguments

isSigned

true if the data type is signed.

false if the data type is unsigned.

wordLength

Total number of bits in the data type, including any sign bit.

totalSlope

Total slope of the scaling of the data type.

bias

Bias of the scaling of the data type.

obeyDataTypeOverride

true indicates that the Data Type Override setting for the subsystem is to be obeyed. Depending on the value of Data Type Override, the resulting data type could be True Doubles, True Singles, ScaledDouble, or the fixed-point data type specified by the other arguments of the function.

false indicates that the Data Type Override setting is to be ignored.

Description

This method registers a fixed-point data type with Simulink software and returns a data type ID. The data type ID can be used to specify the data types of input and output ports, run-time parameters, and DWork states. It can also be used with all the standard data type access methods defined for instances of this class, such as DatatypeSize.

Use this function if you want to register a fixed-point data type with [Slope Bias] scaling. Alternatively, you can use one of the other fixed-point registration functions:

If the registered data type is not one of the Simulink built-in data types, a Fixed-Point Designer license is checked out.

SetAccelRunOnTLC

Purpose

Specify whether to use block's TLC file to generate code for the Accelerator mode of Simulink software.

Syntax

SetAccelRunOnTLC(bVal);

Arguments

bVal

May be 'true' (use TLC file) or 'false' (run block in interpreted mode).

Description

Specify if the block should use its TLC file to generate code that runs with the accelerator. If this option is 'false', the block runs in interpreted mode. See the S-function [msfcn_times_two.m](https://mdsite.deno.dev/matlab:edit%28'msfcn%5Ftimes%5Ftwo.m'%29) in the Simulink model [msfcndemo_timestwo](https://mdsite.deno.dev/matlab:open%5Fsystem%28'msfcndemo%5Ftimestwo'%29;) for an example.

SetPreCompInpPortInfoToDynamic

Purpose

Set precompiled attributes of this block's input ports to be inherited.

Syntax

SetPreCompInpPortInfoToDynamic;

Description

Initialize the compiled information (dimensions, data type, complexity, and sampling mode) of this block's input ports to be inherited.

SetPreCompOutPortInfoToDynamic

Purpose

Set precompiled attributes of this block's output ports to be inherited.

Syntax

SetPreCompOutPortInfoToDynamic;

Description

Initialize the compiled information (dimensions, data type, complexity, and sampling mode) of the block's output ports to be inherited.

SetPreCompPortInfoToDefaults

Purpose

Set precompiled attributes of this block's ports to the default values.

Syntax

SetPreCompPortInfoToDefaults;

Description

Initialize the compiled information (dimensions, data type, complexity, and sampling mode) of the block's ports to the default values. By default, a port accepts a real scalar sampled signal with a data type of double.

SetSimViewingDevice

Purpose

Specify whether this block is a viewer.

Syntax

SetSimViewingDevice(bVal);

Arguments

bVal

May be 'true' (is a viewer) or 'false' (is not a viewer).

Description

Specify if the block is a viewer/scope. If this flag is specified, the block will be used only during simulation and automatically stubbed out in generated code.

SupportsMultipleExecInstances

Purpose

Specify whether or not a For Each Subsystem supports an S-function inside of it.

Syntax

SupportsMultipleExecInstances(bVal);

Arguments

bVal

May be 'true' (S-function is supported) or 'false' (S-function is not supported).

Description

Specify if an S-function can operate within a For Each Subsystem.

WriteRTWParam

Purpose

Write a custom parameter to the Simulink Coder information file used for code generation.

Syntax

WriteRTWParam(pType, pName, pVal)

Arguments

pType

Type of the parameter to be written. Valid values are 'string' and 'matrix'.

pName

Name of the parameter to be written.

pVal

Value of the parameter to be written.

Description

Use in the WriteRTW method of the MATLAB S-function to write out custom parameters. These parameters are generally settings used to determine how code should be generated in the TLC file for the S-function.

Version History

Introduced before R2006a