C-MEX S-Function MATLAB SIMULINK

1. 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

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)PortDimensionInfo Specify 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: 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) { 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) { 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

21. Thank You