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-fileMEX-file  Functions are invoked via flags  Easier access to MATLAB and toolbox functions  Ease of development  Functions are invoked directly  Speed of simulation  Can access workspace directly  Much larger callback functions can be implemented

4 Callback methods : mdlInitializeSizes  Syntax: void mdlInitializeSizes(SimStruct *S) { }  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 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 : mdlInitializeSizes configuration of input and output ports  ssSetNumInput(Output)Ports ssSetNumInput(Output)Ports Specify the number of input and output ports that this S-function has  ssSetInput(Output)PortDimensionInfo ssSetInput(Output)PortDimensionInfo Specify the dimensions of the input and output ports  ssSetInputPortDirectFeedThrough 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 Time Block-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: C onsider 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, ssSetNumSampleTimesssSetNumSampleTimes(S,numSampleTimes); numSampleTimes > 0  In mdlInitializeSampleTimes, ssSetSampleTimessSetSampleTime(S, PortIndex, sample_time) sample_time: CONTINUOUS_SAMPLE_TIME, discrete_sample_period, INHERITED_SAMPLE_TIME

10 Port-Based Sample Time  In mdlInitializesize: ssSetNumSampleTimesssSetNumSampleTimes(S, PORT_BASED_SAMPLE_TIMES) ssSetInputPortSampleTimessSetInputPortSampleTime(S, idx, period) ssSetOutputPortSampleTimessSetOutputPortSampleTime(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_EXITSS_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: mdlInitializeSizes mdlInitializeSampleTimes mdlOutputs mdlTerminate  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 mdlOutputs mdlUpdate mdlDerivatives

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)mdlInitializeSizes { 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 Code static void mdlInitializeSampleTimes(SimStruct *S)dlInitializeSampleTimes { ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME); ssSetOffsetTime(S, 0, 0.0); } static void mdlOutputs(SimStruct *S, int_T tid)mdlOutputs { 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) {}mdlTerminate #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