Note: This page has been translated by MathWorks. Please click here

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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

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.

None

Name | Description |
---|---|

enable Level-2 MATLAB S-function to use multidimensional signals. | |

Specifies which of the S-function's dialog parameters are tunable. | |

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

Name | Description |
---|---|

Register this block's dialog parameters as run-time parameters. | |

Update this block's run-time parameters. | |

Determine whether the current simulation stage is the constant sample time stage. | |

Determine whether the current simulation time step is a major time step. | |

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

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

Register a callback method for this block. | |

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

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

Register data type with [Slope Bias] scaling. | |

Specify whether to use this block's TLC file to generate the simulation target for the model that uses it. | |

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

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

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

Specify whether block is a viewer. | |

Write custom parameter information to Simulink Coder™ file. |

Allow Level-2 MATLAB S-functions
to use multidimensional signals. You must set the `AllowSignalsWithMoreThan2D`

property
in the `setup`

method.

Boolean

`RW`

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

array

`RW`

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

double

`RW`

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

`AutoRegRuntimePrms;`

Use in the `PostPropagationSetup`

method to
register this block's tunable dialog parameters as run-time parameters.

Update a block's run-time parameters.

`AutoUpdateRuntimePrms;`

Automatically update the values of the run-time parameters during
a call to `ProcessParameters`

.

See the S-function `matlabroot`

`/toolbox/simulink/simdemos/simfeatures/adapt_lms.m`

in
the Simulink model `sldemo_msfcn_lms`

for
an example.

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

`bVal = IsDoingConstantOutput;`

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.

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

`bVal = IsMajorTimeStep;`

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.

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

`bVal = IsSampleHit(stIdx);`

`stIdx`

Global index of the sample time to be queried.

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`

).

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

`bVal = IsSpecialSampleHit(stIdx1,stIdx1);`

`stIdx1`

Index of sample time of first task to be queried.

`stIdx2`

Index of sample time of second task to be queried.

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.

Register a block callback method.

`RegBlockMethod(methName, methHandle);`

`methName`

Name of method to be registered.

`methHandle`

MATLAB function handle of the callback method to be registered.

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.

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

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

`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.

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.

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

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

`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.

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:

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.

Register data type with [Slope Bias] scaling.

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

`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.

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:

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.

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

`SetAccelRunOnTLC(bVal);`

`bVal`

May be

`'true'`

(use TLC file) or`'false'`

(run block in interpreted mode).

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 `matlabroot`

`/toolbox/simulink/blocks/msfcn_times_two.m`

in
the Simulink model `msfcndemo_timestwo`

for
an example.

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

`SetPreCompInpPortInfoToDynamic;`

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

`/toolbox/simulink/simdemos/simfeatures/adapt_lms.m`

in
the Simulink model `sldemo_msfcn_lms`

for
an example.

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

`SetPreCompOutPortInfoToDynamic;`

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

`/toolbox/simulink/simdemos/simfeatures/adapt_lms.m`

in
the Simulink model `sldemo_msfcn_lms`

for
an example.

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

`SetPreCompPortInfoToDefaults;`

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`

.

Specify whether this block is a viewer.

`SetSimViewingDevice(bVal);`

`bVal`

May be

`'true'`

(is a viewer) or`'false'`

(is not a viewer).

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.

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

`SupportsMultipleExecInstances(bVal);`

`bVal`

May be

`'true'`

(S-function is supported) or`'false'`

(S-function is not supported).

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

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

`WriteRTWParam(pType, pName, pVal)`

`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.

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. See
the S-function `matlabroot`

`/toolbox/simulink/simdemos/simfeatures/adapt_lms.m`

in
the Simulink model `sldemo_msfcn_lms`

for
an example.

Was this topic helpful?