Documentation |
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.mmsfuntmpl.m shows how to use a number of the following methods.
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.madapt_lms.m in the Simulink model sldemo_msfcn_lmssldemo_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);
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);
Index of sample time of first task to be queried.
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);
Name of method to be registered.
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);
true if the data type is signed.
false if the data type is unsigned.
Total number of bits in the data type, including any sign bit.
Number of bits in the data type to the right of the binary point.
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);
true if the data type is signed.
false if the data type is unsigned.
Total number of bits in the data type, including any sign bit.
Fractional slope of the data type.
exponent of the slope of the data type.
Bias of the scaling of the data type.
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);
true if the data type is signed.
false if the data type is unsigned.
Total number of bits in the data type, including any sign bit.
Total slope of the scaling of the data type.
Bias of the scaling of the data type.
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);
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.mmsfcn_times_two.m in the Simulink model msfcndemo_timestwomsfcndemo_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.madapt_lms.m in the Simulink model sldemo_msfcn_lmssldemo_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.madapt_lms.m in the Simulink model sldemo_msfcn_lmssldemo_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);
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);
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)
Type of the parameter to be written. Valid values are 'string' and 'matrix'.
Name of the parameter to be written.
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.madapt_lms.m in the Simulink model sldemo_msfcn_lmssldemo_msfcn_lms for an example.