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
ssCallExternalModeFcn	Invoke the external mode function for an S-function.
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.
ssGetUserData	Access user data.
ssSetExternalModeFcn	Specify the external mode function for an S-function.
ssSetOptions	Set various simulation options.
ssSetPlacementGroup	Specify the execution order of a sink or source S-function.
ssSetUserData	Specify user data.

Error Handling and Status

Macros	Description
ssGetErrorStatus	Get a string that identifies the last error.
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.
ssGetInputPortComplexSignal	Get the numeric type (complex or real) of an input port.
ssGetInputPortConnected	Determine whether an S-Function block port is connected to a nonvirtual block.
ssGetInputPortDataType	Get the data type of an input port.
ssGetInputPortDimensions	Get the dimensions of the signal accepted by an input port.
ssGetInputPortDirectFeedThrough	Determine whether an input port has direct feedthrough.
ssGetInputPortFrameData	Determine whether a port accepts signal frames.
ssGetInputPortNumDimensions	Get the dimensionality of the signals accepted by an input port.
ssGetInputPortOffsetTime	Determine the offset time of an input port.
ssGetInputPortOverWritable	Determine whether an input port can be overwritten.
ssGetInputPortRealSignal	Get the address of a real, contiguous signal entering an input port.
ssGetInputPortRealSignalPtrs	Access the signal elements connected to an input port.
ssGetInputPortRequiredContiguous	Determine whether the signal elements entering a port must be contiguous.
ssGetInputPortReusable	Determine whether memory allocated to the input port is reusable.
ssGetInputPortSampleTime	Determine the sample time of an input port.
ssGetInputPortSampleTimeIndex	Get the sample time index of an input port.
ssGetInputPortSignal	Get the address of a contiguous signal entering an input port.
ssGetInputPortSignalAddress	Get the address of an input port's signal (Ada only).
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.
ssGetOutputPortBeingMerged	Determine whether the output of this block is connected to a Merge block.
ssGetOutputPortComplexSignal	Get the numeric type (complex or real) of an output port
ssGetOutputPortDataType	Get the data type of an output port.
ssGetOutputPortDimensions	Get the dimensions of the signal leaving an output port.
ssGetOutputPortFrameData	Determine whether a port outputs signal frames.
ssGetOutputPortNumDimensions	Get the number of dimensions of an output port.
ssGetOutputPortOffsetTime	Determine the offset time of an output port.
ssGetOutputPortRealSignal	Access the elements of a signal connected to an output port.
ssGetOutputPortReusable	Determine whether memory allocated to the output port is reusable
ssGetOutputPortSampleTime	Determine the sample time of an output port.
ssGetOutputPortSignal	Get the vector of signal elements emitted by an output port.
ssGetOutputPortSignalAddress	Get address of an output port's signal (Ada only).
ssGetOutputPortWidth	Determine the width of an output port.
ssSetInputPortComplexSignal	Set the numeric type (real or complex) of an input port.
ssSetInputPortDataType	Set the data type of an input port.
ssSetInputPortDimensionInfo	Specify the dimensionality of an input port.
ssSetInputPortDirectFeedThrough	Specify that an input port is a direct-feedthrough port.
ssSetInputPortFrameData	Specify whether a port accepts signal frames.
ssSetInputPortMatrixDimensions	Specify dimension information for an input port that accepts matrix signals.
ssSetInputPortOffsetTime	Specify the sample time offset for an input port.
ssSetInputPortOverWritable	Specify whether an input port is overwritable by an output port.
ssSetInputPortRequiredContiguous	Specify that the signal elements entering a port must be contiguous.
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.
ssSetInputPortSampleTimeIndex	Specify the sample time index of an input port.
ssSetInputPortVectorDimension	Specify dimension information for an input port that accepts vector signals.
ssSetInputPortWidth	Set the 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.
ssSetOutputPortDimensionInfo	Specify the dimensionality of an output port.
ssSetOutputPortFrameData	Specify whether a port outputs framed data.
ssSetOutputPortMatrixDimensions	Specify dimension information for an output port that emits matrix signals
ssSetOutputPortOffsetTime	Specify the sample time offset value of an output port.
ssSetOutputPortReusable	Specify whether an output port's memory can be reused.
ssSetOutputPortSampleTime	Specify the sample time of an output port.
ssSetOutputPortVectorDimension	Specify dimension information for an output port that emits vector signals
ssSetOutputPortWidth	Specify the width of a 1-D (vector) output port.
ssSetOutputPortMatrixDimensions	Specify the dimensions of a 2-D (matrix) signal.
ssSetOutputPortVectorDimension	Specify the dimension of a 1-2 (vector) signal.
ssSetVectorMode	Specify the vector mode that an S-function supports.

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	Return the Simulink data type of a dialog parameter.
ssGetNumParameters	Get the number of parameters that this block has (Ada only).
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.
ssSetParameterName	Set the name of a parameter (Ada only).
ssSetParameterTunable	Set the tunability of a parameter (Ada only).
ssGetSFcnParamsCount	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
ssRegDlgParamAsRunTimeParam	Register a run-time parameter.
ssUpdateDlgParamAsRunTimeParam	Update a run-time parameter.
ssGetNumRunTimeParams	Get the number of run-time parameters created by this S-function.
ssGetRunTimeParamInfo	Get the 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 the 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 parameter from the attributes of the corresponding dialog parameters.

Sample Time

Macro	Description
ssGetSampleTimeOffset	Get the offset of the current sample time (Ada only).
ssGetSampleTimePeriod	Get the period of the current sample time (Ada only).
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.
ssGetPortBasedSampleTimeBlockIsTriggered	Determine whether a block that uses port-based sample times resides in a triggered subsystem.
ssIsContinuousTask	Determine whether a specified rate is the continuous rate.
ssIsSampleHit	Determine the sample rate at which an S-function is operating.
ssIsSpecialSampleHit	Determine whether the current sample time hits two specified rates.
ssSampleAndOffsetAreTriggered	Determine whether a sample time and offset value pair indicate a triggered sample time.
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 the time of the next sample hit in an S-function.

State and Work Vector

Macro	Description
ssGetContStateAddress	Get the address of a block's continuous state vector.
ssGetContStates	Get an S-function's continuous states.
ssGetDiscStates	Get an S-function's discrete states.
ssGetDWork	Get a DWork vector.
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.
ssGetIWorkValue	Get a value from a block's integer work vector.
ssGetModeVector	Get an S-function's mode work vector.
ssGetModeVectorValue	Get an element of a block's mode 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.
ssGetPWorkValue	Get a pointer from a pointer 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.
ssGetRWorkValue	Get an element of an S-function's real-valued 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.
ssSetIWorkValue	Set an element of a block's integer work vector.
ssSetModeVectorValue	Set an element of a block's mode vector.
ssSetNumContStates	Specify the number of continuous states that an S-function has.
ssSetNumDiscStates	Specify the number of discrete states 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.
ssSetPWorkValue	Set an element of a block's pointer work vector.
ssSetRWorkValue	Set an element of a block's floating-point work vector.

Simulation Information

Macro	Description
ssGetAbsTol	Get the absolute tolerances used by a model's variable-step solver.
ssGetBlockReduction	Determine whether a block has requested block reduction before the simulation has begun and whether it has actually been reduced after the simulation loop has begun
ssGetErrorStatus	Get a string that identifies the last error.
ssGetInlineParameters	Determine whether the user has set the inline parameters option for the model containing this S-function.
ssGetSimMode	Determine the context in which an S-function is being invoked: normal simulation, external-mode simulation, model editor, etc.
ssGetSolverMode	Get the solver mode being used to solve the S-function.
ssGetSolverName	Get the name of the solver being used for the simulation.
ssGetStateAbsTol	Get the absolute tolerance used by the model's variable-step solver for a specified state
ssGetStopRequested	Get the value of the simulation stop requested flag
ssGetT	Get the current base simulation time.
ssGetTaskTime	Get the current time for a task.
ssGetTFinal	Get the end time of the current simulation.
ssGetTNext	Get the time of the next sample hit.
ssGetTStart	Get the start time of the current simulation.
ssIsFirstInitCond	Determine whether this is the first call to mdlInitializeConditions.
ssIsMajorTimeStep	Determine whether the current time step is a major time step.
ssIsMinorTimeStep	Determine if the current time step is a minor time step.
ssIsVariableStepSolver	Determine whether the current solver is a variable-step solver.
ssSetBlockReduction	Request that Simulink attempt to reduce a block.
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
ssGetDWorkRTWIdentifier	Get the identifier used to declare a DWork vector in code generated from the associated S-function.
ssGetDWorkRTWStorageClass	Get the storage class of a DWork vector in code generated from the associated S-function.
ssGetDWorkRTWTypeQualifier	Get the C type qualifier (e.g., const) used to declare a DWork vector in code generated from the associated S-function.
ssGetDWorkRTWTypeQualifier	Set the identifier used to declare a DWork vector in code generated from the associated S-function.
ssGetPlacementGroup	Get the name of the placement group of a block
ssSetDWorkRTWIdentifier	Set the storage class of a DWork vector in code generated from the associated S-function.
ssSetDWorkRTWStorageClass	Set the C type qualifier (e.g., const) used to declare a DWork vector in code generated from the associated S-function.
ssSetPlacementGroup	Specify the name of the placement group of a block.
ssWriteRTW2dMatParam	Write a Simulink matrix parameter to the S-function's model.rtw file.
ssWriteRTWMx2dMatParam	Write a MATLAB matrix parameter to the S-function's model.rtw file.
ssWriteRTWMxVectParam	Write a MATLAB vector parameter to the S-function's model.rtw file.
ssWriteRTWParameters	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.
ssWriteRTWScalarParam	Write a scalar parameter to the S-function's 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.
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.
ssWriteRTWWorkVect	Write the S-function's work vectors to the model.rtw file.

Language Support

Macro Reference