Skip to Main Content Skip to Search
Product Documentation

Input and Output Ports

On this page…

Creating Input Ports for C S-Functions

Creating Input Ports for Level-2 MATLAB S-Functions

Creating Output Ports for C S-Functions

Creating Output Ports for Level-2 MATLAB S-Functions

Scalar Expansion of Inputs

Masked Multiport S-Functions

Creating Input Ports for C S-Functions

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

You can configure additional input port properties using other S-function macros. See Input and Output Ports in the "SimStruct Macros and Functions Listed by Usage" section for more information.

Initializing Input Port Dimensions

You can set input port dimensions using one of the following macros:

Sizing an Input Port Dynamically

If your S-function does not require that its input signals have specific dimensions, you can set the dimensionality of the input ports to match the dimensionality of the signals connected to them.

To dynamically dimension an input port:

Example: Defining Multiple S-Function Input Ports

The following code in mdlInitializeSizes configures an S-function with two input ports. See Input and Output Ports in the "SimStruct Macros and Functions Listed by Usage" section for more information on the macros used in this example.

if (!ssSetNumInputPorts(S, 2)) return;

for (i = 0; i < 2; i++) {
  /* Input has direct feedthrough */
  ssSetInputPortDirectFeedThrough(S, i, 1);

  /* Input supports frames: 
     Requires a DSP System Toolbox license*/
  ssSetInputPortFrameData(S, i, FRAME_YES);

  /* Input is a real signal */
  ssSetInputPortComplexSignal(S, i, COMPLEX_NO);

  /* Input is a dynamically sized 2-D matrix */
  ssSetInputPortMatrixDimensions(S ,i, 
     DYNAMICALLY_SIZED, DYNAMICALLY_SIZED);

  /* Input inherits its sample time */
  ssSetInputPortSampleTime(S, i,INHERITED_SAMPLE_TIME);

  /* Input signal must be contiguous */
  ssSetInputPortRequiredContiguous(S, i, 1);

  /* The input port cannot share memory */
  ssSetInputPortOverWritable(S, i, 0);
}

During signal propagation, the Simulink engine calls this S-function's mdlSetInputPortDimensionInfo macro to initialize the input port dimensions. In this example, mdlSetInputPortDimensionInfo sets the input dimensions to the candidate dimensions passed to the macro by the engine.

#if defined(MATLAB_MEX_FILE)
#define MDL_SET_INPUT_PORT_DIMENSION_INFO
static void mdlSetInputPortDimensionInfo(SimStruct        *S,
                                  int_T            port,
                                  const DimsInfo_T *dimsInfo)
{
    if(!ssSetInputPortDimensionInfo(S, port, dimsInfo)) return;
}
#endif

For an example that configures an S-function with multiple input and output ports, open the Simulink model sfcndemo_sfun_multiport.mdl and inspect the S-function sfun_multiport.c.

Back to Top

Creating Input Ports for Level-2 MATLAB S-Functions

To create and configure input ports, the setup method should first specify the number of S-function input ports, using the run-time object NumInputPorts property. Next, if all input ports inherit their functional properties (data type, dimensions, complexity, and sampling mode) from their input signals, include the following line in the setup method:

block.SetPreCompInpPortInfoToDynamic;

Then, for each input port, the setup method can specify

For an example that configures a Level-2 MATLAB S-function with multiple input and output ports, open the model sldemo_msfcn_lms.mdl and inspect the S-function adapt_lms.m.

Back to Top

Creating Output Ports for C S-Functions

To create and configure output ports, the mdlInitializeSizes method should first specify the number of S-function output ports, using ssSetNumOutputPorts. Then, for each output port, the method should specify

See Creating Input Ports for C S-Functions for an example showing how to initialize an S-function input port. You use the same procedure to initialize the S-function output ports, but with the corresponding output port macro.

Back to Top

Creating Output Ports for Level-2 MATLAB S-Functions

To create output ports for Level-2 MATLAB S-functions the setup method should first specify the number of S-function output ports, using the run-time object NumOutputPorts property. Next, if all output ports inherit their functional properties (data type, dimensions, complexity, and sampling mode), include the following line in the setup method:

block.SetPreCompOutPortInfoToDynamic;

Configure the output ports exactly as you configure input ports. See Creating Input Ports for Level-2 MATLAB S-Functions for a list of properties you can specify for each output port, substituting OutputPort for InputPort in each call to the run-time object.

Back to Top

Scalar Expansion of Inputs

Scalar expansion of inputs refers conceptually to the process of expanding scalar input signals to the same dimensions as wide input signals connected to other S-function input ports. This is done by setting each element of the expanded signal to the value of the scalar input.

With scalar expansion on, the S-function mdlInitializeSizes method should specify that the input and output ports are dynamically sized. The Simulink engine uses a default method to set the dimensions of the input and output ports. If the block has more than two inputs, the input signals can be scalar or wide signals, where the wide signals all have the same number of elements. In this case, the engine sets the dimensions of the output ports to the width of the wide input signals and expands any scalar inputs to this width. If the wide inputs are driven by 1-D and 2-D vectors, the output is a 2-D vector signal, and the scalar inputs are expanded to a 2-D vector signal.

If scalar expansion is not on, the engine assumes that all ports (input and output ports) must have the same dimensions, and it sets all port dimensions to the same dimensions specified by one of the driving blocks.

The best way to understand how to use scalar expansion is to consider the example sfcndemo_sfun_multiport.mdl. This model contains three S-function blocks, each with multiple input ports. The S-function sfun_multiport.c used in these blocks sets the SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION option in its mdlInitializeSizes method, allowing scalar expansion of the inputs. The S-function specifies that its inputs and outputs are dynamically sized. Therefore, during signal propagation, the engine sets the width of the input ports to the width of the signal connected to the port, and the width of the output ports to the width of any wide input signal. The mdlOutputs method performs an element-by-element sum on the input signals, expanding any scalar inputs, as needed. 

/* Calculate an element-by-element sum of the input signals.
   yWidth is the width of the output signal. */

for (el = 0; el < yWidth; el++) {

   int_T  port;
   real_T sum = 0.0;
   for (port = 0; port < nInputPorts; port++) {
      /* Get the input signal value */
      InputRealPtrsType uPtrs = 
                   ssGetInputPortRealSignalPtrs(S,port);

      if (el < ssGetInputPortWidth(S,port)) {
         /* Input is a wide signal. Use specific element */
         sum = sum + ((real_T)signs[port] * (*uPtrs[el]));

      } else { 
         /* Use the scalar value to expand the signal */
         sum = sum + ((real_T)signs[port] * (*uPtrs[0]));
      }
   }
}

Back to Top

Masked Multiport S-Functions

If you are developing masked multiport S-function blocks whose number of ports varies based on some parameter, and want to place them in a Simulink library, you must specify that the mask modifies the appearance of the block. To do this, execute the command

  set_param(blockname,'MaskSelfModifiable','on')

at the MATLAB command prompt before saving the library, where blockname is the full path to the block. Failure to specify that the mask modifies the appearance of the block means that an instance of the block in a model reverts to the number of ports in the library whenever you load the model or update the library link.

Back to Top

  

Run-Time ParametersRun-Time Parameters Custom Data TypesCustom Data Types

Related Products & Applications

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit

 © 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS