C-MEX S-Function

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
MATLAB m-file MEX-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)
• ltfunctions to be performedgt
• 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 mdlInitializeSizesconfiguratio
n 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 gt 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 ssSetInputPortSam
  pleTime(S, 0, -1)
• Constant Sample Time for a Port
• ssSetOptions(S, SS_OPTION_ALLOW_CONSTANT_PORT_SAMP
  LE_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 ssGetInputPortRealSigna
  lPtrs(S,0)
• real_T y ssGetOutputPortRealSignal(S,0)
• int_T width ssGetOutputPortWidth(S,0)
• for (i0 iltwidth i)
• y 2.0 (uPtrsi)

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
(No Transcript)
21
Thank You