Simulink.MSFcnRunTimeBlock

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 shows how to use a number of the following methods.

Parent Class

Simulink.RunTimeBlock

Derived Classes

None

Property Summary

Name	Description
AllowSignalsWithMoreThan2D	enable Level-2 MATLAB S-function to use multidimensional signals.
DialogPrmsTunable	Specifies which of the S-function's dialog parameters are tunable.
NextTimeHit	Time of the next sample hit for variable sample time S-functions.

Method Summary

Name	Description
AutoRegRuntimePrms	Register this block's dialog parameters as run-time parameters.
AutoUpdateRuntimePrms	Update this block's run-time parameters.
IsDoingConstantOutput	Determine whether the current simulation stage is the constant sample time stage.
IsMajorTimeStep	Determine whether the current simulation time step is a major time step.
IsSampleHit	Determine whether the current simulation time is one at which a task handled by this block is active.
IsSpecialSampleHit	Determine whether the current simulation time is one at which multiple tasks handled by this block are active.
RegBlockMethod	Register a callback method for this block.
RegisterDataTypeFxpBinaryPoint	Register fixed-point data type with binary point-only scaling.
RegisterDataTypeFxpFSlopeFixexpBias	Register fixed-point data type with [Slope Bias] scaling specified in terms of fractional slope, fixed exponent, and bias.
RegisterDataTypeFxpSlopeBias	Register data type with [Slope Bias] scaling.
SetAccelRunOnTLC	Specify whether to use this block's TLC file to generate the simulation target for the model that uses it.
SetPreCompInpPortInfoToDynamic	Set precompiled attributes of this block's input ports to be inherited.
SetPreCompOutPortInfoToDynamic	Set precompiled attributes of this block's output ports to be inherited.
SetPreCompPortInfoToDefaults	Set precompiled attributes of this block's ports to the default values.
SetSimViewingDevice	Specify whether block is a viewer.
SupportsMultipleExecInstances
WriteRTWParam	Write custom parameter information to Simulink Coder™ file.

Properties

AllowSignalsWithMoreThan2D

Description

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

Data Type

Boolean

Access

RW

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'};

Data Type

array

Access

RW

NextTimeHit

Description

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

Data Type

double

Access

RW

Methods

AutoRegRuntimePrms

Purpose

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. Use AutoRegRuntimePrms 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.

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 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 or Update 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

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 and methHandle. 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

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:

Use RegisterDataTypeFxpFSlopeFixexpBias to register a data type with [Slope Bias] scaling by specifying the word length, fractional slope, fixed exponent, and bias.
Use RegisterDataTypeFxpSlopeBias to register a data type with [Slope Bias] scaling.

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

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:

Use RegisterDataTypeFxpBinaryPoint to register a data type with binary point-only scaling.
Use RegisterDataTypeFxpSlopeBias to register a data type with [Slope Bias] scaling.

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

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

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

Description

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:

Use RegisterDataTypeFxpBinaryPoint to register a data type with binary point-only scaling.
Use RegisterDataTypeFxpFSlopeFixexpBias to register a data type by specifying the word length, fractional slope, fixed exponent, and bias

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 in the Simulink model msfcndemo_timestwo for an example.

Note

The default JIT Accelerator mode does not support inlining of user-written TLC S-Functions. See How Acceleration Modes Work and Control S-Function Execution for more information.

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