Writing S-Functions

Creating 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 mdlOutputs or mdlGetTimeOfNextVarHit routine. Setting the direct feedthrough flag to 0 tells Simulink that u is not used in either of these S-function routines. Violating this leads 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 is accessing invalid memory and Simulink crashes.

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)
  

• You can use this function 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 might want to set the dimensionality of the input port to match the dimensionality of the signal 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 an 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 an 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 of the block's ports to 1-D scalar.

Run-Time Parameters

Creating Output Ports