Frame-Based Signals

About Frame-Based Signals

This section explains how to create an S-function that accepts or produces frame-based signals. For more information, see Sample- and Frame-Based Concepts in the DSP System Toolbox™ documentation.

    Note   Simulating a model containing an S-function that accepts or produces frames requires a DSP System Toolbox product license.

Using Frame-Based Signals in C S-Functions

To accept or produce frame-based signals, a C MEX S-function must perform the following tasks:

  • The S-function mdlInitializeSizes callback method must set the port frame status to FRAME_YES, FRAME_NO, or FRAME_INHERITED for each of the S-function I/O ports, using the ssSetInputPortFrameData and ssSetOutputPortFrameData functions. The frame status for a port must be set after the call to ssSetNumInputPorts and ssSetNumOutputPorts. For example, the following code in mdlInitializeSizes specifies that the first input port accepts a frame-based signal while the first output port emits a sample-based signal:

    ssSetNumInputPorts(S, 1);
    ssSetInputPortFrameData(S, 0, FRAME_YES);
    ssSetOutputPortFrameData(S, 0, FRAME_NO);
  • The S-function should specify the dimensions of the signals that its frame-based ports accept or produce in its mdlInitializeSizes or mdlSetInputPortDimensionInfo and mdlSetOutputPortDimensionInfo callback methods. Note that frame-based signals must be dimensioned as 2-D arrays. For example, the following code in mdlInitializeSizes specifies that the first frame-based input port is dynamically sized. This S-function must then also have an mdlSetInputPortDimensionInfo callback that sets the specific dimensions of this input port.

    ssSetNumInputPorts(S, 1);
    ssSetInputPortFrameData(S, 0, FRAME_YES);
    ssSetInputPortMatrixDimensions(S, 0, DYNAMICALLY_SIZED, DYNAMICALLY_SIZED);
  • If the frame status of any of the S-function input ports is inherited, the S-function should define a mdlSetInputPortFrameData callback method. The Simulink® engine passes the frame status that it assigns to the port, based on frame signal propagation rules, as an argument to this callback method. The callback method should in turn use the ssSetInputPortFrameData function to set the port to the assigned status if it is acceptable or signal an error using ssSetErrorStatus if it is not. If the frame status of other ports of the S-function depend on the status inherited by one of its input ports, the callback method can also use ssSetInputPortFrameData to set the frame status of the other ports based on the status that the input port inherits. A template for the mdlSetInputPortFrameData callback is shown below.

    #if defined(MATLAB_MEX_FILE)
    static void mdlSetInputPortFrameData(SimStruct *S, 
                                         int_T       portIndex, 
                                         Frame_T   frameData)
       if(!frameData==FRAME_YES) {
                ssSetErrorStatus(S, "Incorrect frame status");
       ssSetInputPortFrameData(S, portIndex, frameData); /* Sets frame status */
    } /* end mdlSetInputPortFrameData */
  • The S-function mdlOutputs method should include code to process the signals. The macro ssGetInputPortDimensions can be used in mdlOutputs to determine the dimensions of dynamically sized frame-based inputs, as follows:

    int *dims   = ssGetInputPortDimensions(S, 0);
    int frameSize = dims[0];
    int numChannels  = dims[1];

See the frame-based A/D converter S-function example (sfun_frmad.csfun_frmad.c) for an example of how to create a frame-based S-function. This S-function is one of several S-functions that manipulate frame-based signals found in the Simulink model sfcndemo_framesfcndemo_frame.

Using Frame-Based Signals in Level-2 MATLAB S-Functions

In a Level-2 MATLAB® S-function, set the SamplingMode property of the port to indicate if the block accepts frame-based signals, for example:

block.InputPort(1).SamplingMode = 'Inherited';

If any of the ports inherited their sampling mode, define a SetInputPortSamplingMode callback method to specify the sampling mode.

Was this topic helpful?