Writing S-Functions

The SimStruct

The file matlabroot/simulink/include/simstruc.h is a C language header file that defines the Simulink data structure and the SimStruct access macros. It encapsulates all the data relating to the model or S-function, including block parameters and outputs.

There is one SimStruct data structure allocated for the Simulink model. Each S-function in the model has its own SimStruct associated with it. The organization of these SimStructs is much like a directory tree. The SimStruct associated with the model is the root SimStruct. The SimStructs associated with the S-functions are the child SimStructs.

SimStruct Macros and Functions Listed by Usage

This section groups SimStruct macros by usage.

Miscellaneous

Macro	Description
ssGetModelName	Get the name of an S-function block or model containing the S-function.
ssGetParentSS	Get the parent of an S-function.
ssGetPath	Get the path of an S-function or the model containing the S-function.
ssGetRootSS	Return the root (model) SimStruct.
ssSetOptions	Set various simulation options.
ssSetPlacementGroup	Specify the execution order of a sink or source S-function.

Error Handling and Status

Macros	Description
ssGetSimMode	Determine context in which an S-function is being invoked: normal simulation, external-mode simulation, model editor, etc.
ssGetSolverName	Get name of the solver being used for the simulation.
ssIsVariableStepSolver	Determine if the current solver is a variable step solver.
ssPrintf	Print a variable-content msg.
ssSetErrorStatus	Report errors.
ssWarning	Display a warning message.

I/O Port

Macro	Description
ssGetInputPortBufferDstPort	Determine the output port that is overwriting an input port's memory buffer.
ssGetInputPortConnected	Determine if an S-function block port is connected to a nonvirtual block.
ssGetInputPortDirectFeedThrough	Determine if an input port has direct feedthrough.
ssGetInputPortOffsetTime	Determine the offset time of an input port.
ssGetInputPortRealSignalPtrs	Access the signal elements connected to an input port.
ssGetInputPortSampleTime	Determine the sample time of an input port.
ssGetInputPortSignalPtrs	Get pointers to input signal elements of type other than double.
ssGetInputPortWidth	Determine the width of an input port.
ssGetNumInputPorts	Determine how many input ports a block has.
ssGetNumOutputPorts	Can be used in any routine (except mdlInitializeSizes) to determine how many output ports you have set.
ssGetOutputPortOffsetTime	Determine the offset time of an output port.
ssGetOutputPortRealSignal	Access the elements of a signal connected to an output port.
ssGetOutputPortSample Time	Determine the sample time of an output port.
ssGetOutputPortWidth	Determine the width of an output port.
ssSetInputPortDirectFeedThrough	Specify that an input port is a direct feedthrough port.
ssSetInputPortOffsetTime	Specify the sample time offset for an input port.
ssSetInputPortOver Writable	Specify whether an input port is overwritable by an output port.
ssSetInputPortReusable	Specify whether an input port's memory buffer can be reused by other signals in the model.
ssSetInputPortSampleTime	Set the sample time of an input port.
ssSetInputPortWidth	Set width of an input port.
ssSetNumInputPorts	Set the number of input ports on an S-function block.
ssSetNumOutputPorts	Specify the number of output ports on an S-function block.
ssSetOutputPortComplexSignal	Specify the numeric type (real or complex) of this port.
ssSetOutputPortDataType	Specify the data type of an output port.
ssSetOutputPortOffsetTime	Specify the sample time offset value of an output port.
ssSetOutputPortReusable	Specify whether an output port's memory can be reused.
ssSetOutputPortSample Time	Specify the sample time of an output port.
ssSetOutputPortWidth	Specify width of a 1-D (vector) output port.
ssSetOutputPortDimensionInfo	Specify the dimensions of an output port.
ssSetOutputPortMatrixDimensions	Specify the dimensions of a 2-D (matrix) signal.
ssSetOutputPortVectorDimension	Specify the dimension of a 1-2 (vector) signal.

Dialog Box Parameters

These macros enable an S-function to access and set the tunability of parameters that a user specifies in the S-function's dialog box.

Macro	Description
ssGetDTypeIdFromMxArray	Returns the Simulink data type of a dialog parameter.
ssGetNumSFcnParams	Get the number of parameters that an S-function expects.
ssGetSFcnParam	Get a parameter entered by a user in the S-function block dialog box.
ssSetNumSFcnParams	Set the number of parameters that an S-function expects.
ssGetSfcnParamCount	Get the actual number of parameters specified by the user.
ssSetSFcnParamNotTunable	Obsolete.
ssSetSFcnParamTunable	Specify the tunability of a dialog box parameter.

Run-Time Parameters

These macros allow you to create, update, and access run-time parameters corresponding to a block's dialog parameters.

Macro	Description
ssGetNumRunTimeParams	Gets the number of run-time parameters created by this S-function.
ssGetRunTimeParamInfo	Gets attributes of a specified run-time parameter.
ssRegAllTunableParamsAsRunTimeParams	Register all tunable dialog parameters as run-time parameters.
ssSetNumRunTimeParams	Specify the number of run-time parameters to be created by this S-function.
ssSetRunTimeParamInfo	Specify attributes of a specified run-time parameter.
ssUpdateAllTunableParamsAsRunTimeParams	Update all run-time parameters corresponding to tunable dialog parameters.
ssUpdateRunTimeParamData	Update the value of a specified run-time parameter.
ssUpdateRunTimeParamInfo	Update the attributes of a specified run-time from the attributes of the corresponding dialog parameters.

Sample Time

Macro	Description
ssGetTNext	Get the time of the next sample hit in a discrete S-function with a variable sample time.
ssGetNumSampleTimes	Get the number of sample times an S-function has.
ssIsContinuousTask	Determine if a specified rate is the continuous rate.
ssIsSampleHit	Determine the sample rate at which an S-function is operating.
ssIsSpecialSampleHit	Determine if the current sample time hits two specified rates.
ssSetNumSampleTimes	Set the number of sample times an S-function has.
ssSetOffsetTime	Specify the offset of a sample time.
ssSetSampleTime	Specify a sample time for an S-function.
ssSetTNext	Specify time of next sample hit in an S-function.

State and Work Vector

Macro	Description
ssGetContStates	Get an S-function's continuous states.
ssGetDiscStates	Get an S-function's discrete states.
ssGetDWorkComplexSignal	Determine whether the elements of a data type work vector are real or complex numbers.
ssGetDWorkDataType	Get the data type of a data type work vector.
ssGetDWorkName	Get the name of a data type work vector.
ssGetDWorkUsedAsDState	Determine whether a data type work vector is used as a discrete state vector.
ssGetDWorkWidth	Get the size of a data type work vector.
ssGetdX	Get the derivatives of the continuous states of an S-function.
ssGetIWork	Get an S-function's integer-valued (int_T) work vector.
ssGetModeVector	Get an S-function's mode work vector.
ssGetNonsampledZCs	Get an S-function's zero-crossing signals vector.
ssGetNumContStates	Determine the number of continuous states that an S-function has.
ssGetNumDiscStates	Determine the number of discrete states that an S-function has.
ssGetNumDWork	Get the number of data type work vectors used by a block
ssGetNumIWork	Get the size of an S-function's integer work vector.
ssGetNumModes	Determine the size of an S-function's mode vector.
ssGetNumNonsampledZCs	Determine the number of nonsampled zero crossings that an S-function detects.
ssGetNumPWork	Determine the size of an S-function's pointer work vector.
ssGetNumRWork	Determine the size of an S-function's real-valued (real_T) work vector.
ssGetPWork	Get an S-function's pointer (void *) work vector.
ssGetRealDiscStates	Get the real (real_T) values of an S-function's discrete state vector.
ssGetRWork	Get an S-function's real-valued (real_T) work vector.
ssSetDWorkComplexSignal	Specify whether the elements of a data type work vector are real or complex.
ssSetDWorkDataType	Specify the data type of a data type work vector.
ssSetDWorkName	Specify the name of a data type work vector.
ssSetDWorkUsedAsDState	Specify that a data type work vector is used as a discrete state vector.
ssSetDWorkWidth	Specify the width of a data type work vector.
ssSetNumContStates	Specify the number of continuous states that an S-function has.
ssSetNumDiscStates	Specify the number of discrete states a that an S-function has.
ssSetNumDWork	Specify the number of data type work vectors used by a block.
ssSetNumIWork	Specify the size of an S-function's integer (int_T) work vector.
ssSetNumModes	Specify the number of operating modes that an S-function has.
ssSetNumNonsampledZCs	Specify the number of zero crossings that an S-function detects.
ssSetNumPWork	Specify the size of an S-function's pointer (void *) work vector.
ssSetNumRWork	Specify the size of an S-function's real (real_T) work vector.

Simulation Information

Macro	Description
ssGetT	Get the current base simulation time.
ssGetTaskTime	Get the current time for a task.
ssGetTFinal	Get the end time of the current simulation.
ssGetTStart	Get the start time of the current simulation.
ssIsMajorTimeStep	Determine if the current time step is a major time step.
ssIsMinorTimeStep	Determine if the current time step is a minor time step.
ssSetSolverNeedsReset	Ask Simulink to reset the solver.
ssSetStopRequested	Ask Simulink to terminate the simulation at the end of the current time step.

 

Function Call

Macro	Description
ssCallSystemWithTid	Execute a function-call subsystem connected to an S-function.
ssSetCallSystemOutput	Specify that an output port element issues a function call.

Data Type

Macro	Description
ssGetDataTypeId	Get the id for a data type.
ssGetDataTypeName	Get a data type's name.
ssGetDataTypeSize	Get a data type's size.
ssGetDataTypeZero	Get the zero representation of a data type.
ssGetInputPortDataType	Get the data type of an input port.
ssGetNumDataTypes	Get the number of data types defined by an S-function or the model.
ssGetOutputPortDataType	Get the data type of an output port.
ssGetOutputPortSignal	Get an output signal of any type except double.
ssRegisterDataType	Register a data type.
ssSetDataTypeSize	Specify the size of a data type.
ssSetDataTypeZero	Specify the zero representation of a data type.
ssSetInputPortDataType	Specify the data type of signals accepted by an input port.

Real-Time Workshop

Macro	Description
ssWriteRTWParameter	Write tunable parameters to the S-function's model.rtw file.
ssWriteRTWParamSettings	Write settings for the S-function's parameters to the model.rtw file.
ssWriteRTWWorkVect	Write the S-function's work vectors to the model.rtw file.
ssWriteRTWStr	Write a string to the S-function's model.rtw file.
ssWriteRTWStrParam	Write a string parameter to the S-function's model.rtw file.
ssWriteRTWScalarParam	Write a scalar parameter to the S-function's model.rtw file.
ssWriteRTWStrVectParam	Write a string vector parameter to the S-function's model.rtw file
ssWriteRTWVectParam	Write a Simulink vector parameter to the S-function's model.rtw file.
ssWriteRTW2dMatParam	Write a Simulink matrix parameter to the S-function's model.rtw file.
ssWriteRTWMxVectParam	Write a MATLAB vector parameter to the S-function's model.rtw file.
ssWriteRTWMx2dMatParam	Write a MATLAB matrix parameter to the S-function's model.rtw file.

Language Support

Macro Reference