Writing S-Functions

Input and Output Ports

Simulink allows S-functions to create and use any number of block I/O ports. This section shows how to create and initialize I/O ports and how to change the characteristics of an S-function block's ports, such as dimensionality and data type, based on its connections to other blocks.

Creating Input Ports

To create and configure input ports, the mdlInitializeSizes method should first specify the number of input ports that the S-function has, using ssSetNumInputPorts. Then, for each input port, the method should specify:

• The dimensions of the input port (see Initializing Input Port Dimensions)

If you want your S-function to inherit its dimensionality from the port to which it is connected, you should specify that the port is dynamically sized in mdlInitializeSizes (see Sizing an Input Port Dynamically).

• Whether the input port allows scalar expansion of inputs (see Scalar Expansion of Inputs)
• Whether the input port has direct feedthrough, using ssSetInputPortDirectFeedThrough

A port has direct feedthrough if the input is used in either the mdlOutputs or mdlGetTimeOfNextVarHit functions. The direct feedthrough flag for each input port can be set to either 1=yes or 0=no. It should be set to 1 if the input, u, is used in the mdlOutput or mdlGetTimeOfNextVarHit routine. Setting the direct feedthrough flag to 0 tells Simulink that u will not be used in either of these S-function routines. Violating this will lead to unpredictable results.

• The data type of the input port, if not the default double

Use ssSetInputPortDataType to set the input port's data type. If you want the data type of the port to depend on the data type of the port to which it is connected, specify the data type as DYNAMICALLY_TYPED. In this case, you must provide implementations of the mdlSetInputPortDataType and mdlSetDefaultPortDataTypes methods to enable the data type to be set correctly during signal propagation.

• The numeric type of the input port, if the port accepts complex-valued signals

Use ssSetInputComplexSignal to set the input port's numeric type. If you want the numeric type of the port to depend on the numeric type of the port to which it is connected, specify the data type as inherited. In this case, you must provide implementations of the mdlSetInputPortComplexSignal and mdlSetDefaultPortComplexSignal methods to enable the numeric type to be set correctly during signal propagation.

Note    The mdlInitializeSizes method must specify the number of ports before setting any properties. If it attempts to set a property of a port that doesn't exist, it will be accessing invalid memory and Simulink will crash.

Initializing Input Port Dimensions

The following options exist for setting the input port dimensions:.

• If the input signal is one-dimensional, and the input port width is w, use

ssSetInputPortVectorDimension(S, inputPortIdx, w)

• If the input signal is a matrix of dimension m-by-n, use

ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)

• Otherwise use

ssSetInputPortDimensionInfo(S, inputPortIdx, dimsInfo)

This function can be used to fully or partially initialize the port dimensions (see next section).

Sizing an Input Port Dynamically

If your S-function does not require that an input signal have a specific dimensionality, you may want to set the dimensionality of the input port to match the dimensionality of the signal actually connected to the port. To dimension an input port dynamically, your S-function should:

• Specify some or all of the dimensions of the input port as dynamically sized in mdlInitializeSizes
• If the input port can accept a signal of any dimensionality, use

ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION)

to set the dimensionality of the input port.

• If the input port can accept only vector (1-D) signals but the signals can be of any size, use

ssSetInputPortWidth(S, inputPortIdx, DYNAMICALLY_SIZED)

to specify the dimensionality of the input port.

If the input port can accept only matrix signals but can accept any row or column size, use

ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)

where m and/or n are DYNAMICALLY_SIZED.

• Provide a mdlSetInputPortDimensionInfo method that sets the dimensions of the input port to the size of the signal connected to it

Simulink invokes this method during signal propagation when it has determined the dimensionality of the signal connected to the input port.

• Provide a mdlSetDefaultPortDimensionInfo method that sets the dimensions of the block's ports to a default value

Simulink invokes this method during signal propagation when it cannot determine the dimensionality of the signal connected to some or all of the block's input ports. This can happen, for example, if an input port is unconnected. If the S-function does not provide this method, Simulink sets the dimension the block's ports to 1-D scalar.

Run-Time Parameters

Creating Output Ports