C-MEX S-Function MATLAB SIMULINK

SI Lab Presentation

Presented by:

Ashkan Jalili

2007/12/08

2

S-Function

S-functions allow you to add your own blocks to Simulink models

Provide a powerful mechanism for extending the capabilities of Simulink

Can be written in MATLAB®, C, C++, Ada, or Fortran

3

Comparison

MATLAB m-file MEX-fileFunctions are invoked via flagsEasier access to MATLAB and toolbox functionsEase of development

Functions are invoked directlySpeed of simulationCan access workspace directlyMuch larger callback functions can be implemented

4

Callback methods : mdlInitializeSizes Syntax:

void mdlInitializeSizes(SimStruct *S) {

<functions to be performed>

}

This is the first of the S-function's callback methods that Simulink calls

Specifies the number of inputs, outputs, states, parameters, and other characteristics required for S-function

5

Callback methods : mdlInitializeSizes

ssSetNumSFcnParams Specify the number of parameters that this S-

function supports

ssSetSFcnParamTunable(S,paramIdx, 0) Specifies whether a parameter can change during simulation or not

6

Callback methods : mdlInitializeSizesconfiguration of input and output ports

ssSetNumInput(Output)Ports

Specify the number of input and output ports that this S-function has

ssSetInput(Output)PortDimensionInfoSpecify the dimensions of the input and output ports

ssSetInputPortDirectFeedThrough Specifies whether the input is used in mdlOutputs callback method for calculation of output or not

7

Sample Time Block-based sample times:

S-function specifies a set of operating rates for the block as a whole during the initialization phase of the simulation.

Port-based sample times:S-function specifies a sample time for each input and output port individually during initialization

8

Sample TimeBlock-Based VS Port-Based

With block-based sample times S-function processes all inputs and outputs each time a sample hit occurs for the block, while with port-based sample times, the block processes a particular port only

Example:Consider two sample times, 0.5 and 0.25 seconds • Block-based method, would direct the block to

execute inputs and outputs at 0.25 second increments • Port-based method, you could set the input port to 0.5 and

the output port to 0.25, and the block would process inputs at 2 Hz and outputs at 4 Hz.

9

Block-Based Sample Times In mdlInitializesize,

ssSetNumSampleTimes(S,numSampleTimes);

numSampleTimes > 0

In mdlInitializeSampleTimes,

ssSetSampleTime(S, PortIndex, sample_time) • sample_time:

CONTINUOUS_SAMPLE_TIME , discrete_sample_period , INHERITED_SAMPLE_TIME

10

Port-Based Sample Time

In mdlInitializesize:ssSetNumSampleTimes(S, PORT_BASED_SAMPLE_TIMES)

ssSetInputPortSampleTime(S, idx, period) ssSetOutputPortSampleTime(S, idx, period)

Inherited Sample Time for a Port ssSetInputPortSampleTime(S, 0, -1);

Constant Sample Time for a Port:ssSetOptions(S, SS_OPTION_ALLOW_CONSTANT_PORT_SAMPLE_TIME);ssSetInputPortSampleTime(S, 0, mxGetInf());

11

Callback methods: mdlOutputs Syntax

void mdlOutputs(SimStruct *S, int_T tid) Compute the signals that this block emits tid is from: ssIsSampleHit(S, st_index, tid)

• Example:ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME); ssSetSampleTime(S, 1, 0.75);

ssSetSampleTime(S, 2, 1.0);

if (ssIsSampleHit(S, 1, tid)) { } The second argument, 1, corresponds to the second sample time, 0.75 second

12

Callback methods: mdlTerminate Syntax

void mdlTerminate(SimStruct *S)

Perform any actions required at termination of the

simulation option SS_OPTION_CALL_TERMINATE_ON_EXIT mdlStart

• Initialize the continuous and discrete states, if any • Initialization activities such as allocating memory or setting

up user data

13

S-Function Source File Requirements

Statements Required at the Top of S-Functions:#define S_FUNCTION_NAME your_sfunction_name_here#define S_FUNCTION_LEVEL 2#include "simstruc.h“

Callback Methods That an S-Function Must Implement:mdlInitializeSizesmdlInitializeSampleTimesmdlOutputsmdlTerminate

Statements Required at the Bottom of S-Functions#ifdef MATLAB_MEX_FILE #include "simulink.c" #else#include "cg_sfun.h“#endif

14

Exception Free Code Refers to code that never long-jumps

• Ex: mexErrMsgTxt throws an exception when called.Issues error message and return to MATLAB prompt.

If code is exception free, in mdlInitializeSizes set:

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE); All mex* routines have the potential of long-jumping. Run time routines:

mdlGetTimeOfNextVarHit

mdlOutputsmdlUpdatemdlDerivatives

15

Example “timestwo” block double the input

16

Example Code#define S_FUNCTION_NAME timestwo #define S_FUNCTION_LEVEL 2 #include "simstruc.h" static void mdlInitializeSizes(SimStruct *S){

ssSetNumSFcnParams(S, 0); if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) { return;} if (!ssSetNumInputPorts(S, 1)) return; ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED); ssSetInputPortDirectFeedThrough(S, 0, 1); if (!ssSetNumOutputPorts(S,1)) return; ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED); ssSetNumSampleTimes(S, 1); ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);

}

17

Example Codestatic void mdlInitializeSampleTimes(SimStruct *S) {

ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME); ssSetOffsetTime(S, 0, 0.0);

} static void mdlOutputs(SimStruct *S, int_T tid) {

int_T i; InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0); real_T *y = ssGetOutputPortRealSignal(S,0); int_T width = ssGetOutputPortWidth(S,0); for (i=0; i<width; i++) { *y++ = 2.0 *(*uPtrs[i]); }

}

18

Example Code

static void mdlTerminate(SimStruct *S) {} #ifdef MATLAB_MEX_FILE #include "simulink.c" #else #include "cg_sfun.h" #endif

19

Compile and Link the code mex “s-fcname”.c

mex –setup

In S-Function Block:

• S-Function name (no extension and path name)

• Parameters

20

Thank You