s-function学习之sfuntmpl_doc.c
本文章用来做simulink的S-function函数的学习笔记：
#define S_FUNCTION_NAME your_sfunction_name_here
#define S_FUNCTION_LEVEL 2
// simstruc.h包含tmwtypes.h(general types)、mex.h、matrix.h
#include "simstruc.h"
//异常处理：
// ssSetErrorStatus(S, "error encountered due to ...");
// return;
// ssSetErrorStatus的处理方法建议使用mexErrMsgTxt，mexErrMsgTxt立即终止s-function的执行和返回。如果不使用mexRrrMsgTxt或任何其他引起异常的方式，则应该使用SS_OPTION_EXCEPTION_FREE_CODE。
// ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
//设置此选项会允许simulink绕过异常处理的设置。但当使用这个选项时，必须格外小心验证代码是无异常的。如果s函数生成异常的时候该选项开启，将出现不可预测的结果。
// 在内存分配的问题上使用mxCalloc可能会照成不可预知的问题，如果必须使用内存分配，建议直接使用stdlib.h分配
//以下不会抛出异常：mxGetPr, mxGetData, mxGetNumberOfDimensions, mxGetM, mxGetN, mxGetNumberOfElements.
//如果你所有使用的方法都不会抛出异常，则可以使用：
// ssSerOptions(S, SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE);
// 警告 & Printf's
// 输出警告： ssWarning(S, msg), 当s-function编译之后，ssWarning等同于mexWarnMsgTxt。
//Printf's: ssPrintf(fmt, ...), 当s-function编译之后，ssPrintf等同于mexPrintf。
//你可以通过这种方法来实现标准I/O：
#if defined(SS_STDIO_AVAILABLE)
if ((fp=fopen(file, "w")) == NULl){
ssSetErrorStatus(S, "open failed");
return ;
}
...
#endif
//s-function methods:
注意： 以下许多方法只适用于level C-MEX S-function
**表示该函数必须存在 ， []表示该函数可供选择。
Model Initialization in Simulink：
**mdlInitializeSizes： 初始化Simstruct数组大小
**mdlInitializeSampleTimes： 初始化采样时间和可选择的函数调用连接
[mdlInputPortComplexSignal]/[mdlOutputPortComplexSignal]: 检查并设置输入／输出端口复杂属性（COMPLEX_YES，C OMPLEX_NO）。
[mdlSetWorkWidths]: 设置状态，iwork，rwork,pwork,dwork etc.
[mdlSetSimState]: 当初始化模拟状态时，s-function将ssSetSimStateCompliance 设置为 UES_CUSTOM_SIM_STATE，并把完整的模拟状态加载到此模块中。see also mdlGetSimState。
Model simulation loop in simulink：
**mdlOutputs： 更新输出信号。
**mdlTerminate： 终止模型管理，如释放内存等。
参数处理方法（这些方法不适用于RTW）：
#define MDL_CHECK_PARAMETERS //#undef则去除函数方法
#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)
//mdlCheckParameters： 这个函数应该在mdlInitalizeSizes后被调用。如果你想使用ssSetNumSFcnParams(S, n)：
#if defined(MATLAB_MEX_FILE)
if (ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S)) {
mdlCheckParamters(S);
if (ssGetErrorStatus(S) != NULL) return;
}
else{
return;//simulink will report a parameter mismatch error
}
#endif
详例见 Matlabbroot/simulink/src/sfun_errhdl.c
static void mdlCheckParameters(SimStruct *S)
{
}
#endif //MDL_CHECK_PARAMETERS
#define MDL_PROCESS_PARAMETERS
#if defined(MDL_PROCESS_PARAMETERS) && defined(MATLAB_MEX_FILE)
//mdlProcessParameters: 这个函数将在mdlCheckParameters之后被调用，处理新更新的参数。
static void mdlProcessParameters(SimStruct *S)
{
}
#endif //MDL_PROCESS_PARAMETERS
Configuration and execution methods:
//mdlInitializeSizes:
Direct Feedthough:
直接反馈的值可以为或者，如果为输入，则必须置为，‘u’可被用于mdlOutput或者mdlGetTImeOfNextVarHit()。若置为，‘u’则不能被用于这两个函数。如：要使用ssGetInputPortSignal(S, inputPortIndex),则需要ssSetInputPortDirectFeedThrough(S, inputPortIdx, );
//如果需要debug s-function则：mex -g sfunction_name.c
static void mdlInitializeSizes(SimStruct *S)
{
int_T nInputPorts = ;//输入端口的参数个数
int_T nOutputPorts = ;//输出端口的参数个数
int_T needsInput = ;//直接反馈？
int_T inputPortIdx = ;
int_T outputPortIdx = ;
ssSetNumSFcnParams(S, );//预期参数个数
if (ssGetNumSFcnParams(S) != ssGetNumParamsCount(S)) {
//如果预期参数个数与所获参数个数不一样，则返回参数不匹配错误。
return;
}
//任何参数在模拟中是可以更改的，但若想将参数设置为不可更改，则使用：
ssSetSFcnParamTunable(S, , );
ssSetNumContStates( S, );//连续参数的个数
ssSetNumDiscStates( S, );//离散参数的个数
//设置输入端口的个数：
if(! ssSetNumInputPorts(S, nInputPorts)) return;
if(!ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION)) return;
// 1.若输入端口维数未知，则用：ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION)。
若输入信号是无定向矢量，输入端口宽度为w(DYNAMICALLY_SIZED或大于)，则用：ssSetInputPortVectorDimension(S, inputPortIdx, w)或 ssSetInputPortWidth(S, inputPortIdx, w)。
若输入信号为m*n的矩阵，m,n(DYNAMICALLY_SIZED或大于),则用： ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)。
其他情况，则用：ssSetInputPortDimensionInfo(S, inputPortIdx, dimsInfo)。dimsInfo结构体包含：width, number of dimensions, dimensions of the port。
ssSetInputPortDirectFeedThrough(S, inputPortIdx, needsInput);
// mdlOutputs,mdlGetTimeOfNextVarHit
//详见 sfuntmpl_directfeed.txt
if(!ssSetNumOutputPorts(S, nOutputPorts)) return;
//设置输出端口的个数
if(!ssSetOutputPortDimensionInfo(S, outputPortIdx, DYNAMIC_DIMENSION)) return;
//与input相似
ssSetNumSampleTimes( S, );
//设置采样时间(大于0的整数或PORT_BASED_SAMPLE_TIMES)
ssSetNumRWork( S, );//number of real work vector elements
ssSetNumIWork( S, );//number of integer work vector elements
ssSetNumPWork( S, );//number of pointer work vector elements
ssSetNumModes( S, );//number of mode work vector elements
ssSetNumNonsampledZCs( S, );//number of nonsampled zero crossings
ssSetSimStateCompliance(S, USE_DEFAULT_SIM_STATE);
//详见sfun_simstate.c
ssSetOptions( S, );
//ssSetOptions(S, (SS_OPTION_name1 | SS_OPTION_name2))
}//mdlInitializeSizes结束
#define MDL_SET_INPUT_PORT_FRAME_DATA
#if defined(MDL_SET_INPUT_PORT_FRAME_DATA) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortFrameData(SimStruct *S,
int portIndex,
Frame_T frameData)
{
//这个函数为输入端口的候选框设置(FRAME_YES,FRAME_NO),如果设置成功，则函数可继续并设置ssSetInputPortFrameData(S, portIndex, frameData);如果设置失败，则通过ssSetErrorStatus生成错误。任何的其他动态输入输出都会调用ssSetInputPortFrameData,ssSetOutputPortFrameData。
}
#endif //MDL_SET_INPUT_PORT_FRAME_DATA
#define MDL_SET_INPUT_PORT_WIDTH
#if defined(MDL_SET_INPUT_PORT_WIDTH) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortWidth(SimStruct *S, int portIndex, int width)
{
//端口宽度动态调节ssSetInputPortWidth,ssSetOutputPortWidth
}
#endif //MDL_SET_INPUT_PORT_WIDTH
#define MDL_SET_OUTPUT_PORT_WIDTH
#if defined(MDL_SET_OUTPUT_PORT_WIDTH) && defined(MATLAB_MEX_FILE)
static void mdlSetOutputPortWidth(SimStruct *S, int portIndex, int width)
{
//端口宽度动态调节ssSetInputPortWidth,ssSetOutputPortWidth
}
#endif //MDL_SET_OUTPUT_PORT_WIDTH
#define MDL_SET_INPUT_PORT_DIMENSION_INFO
#if defined(MDL_SET_INPUT_PORT_DIMENSION_INFO) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortDimensionInfo(SimStruct *S,
int_T portIndex,
const DimsInfo_T)
{
//为未知维度的输入端口做备选设置。例详见：matlabroot／simulink/src/sfun_matadd.c
}
#endif //MDL_SET_INPUT_PORT_DIMENSION_INFO
#define MDL_SET_OUTPUT_PORT_DIMENSION_INFO
#if defined(MDL_SET_OUTPUT_PORT_DIMENSION_INFO) && defined(MATLAB_MEX_FILE)
static void mdlSetOutputPortDimensionInfo(SimStruct *S,
int_T portIndex,
const DimsInfo_T)
{
//为未知维度的输入端口做备选设置。例详见：matlabroot／simulink/src/sfun_matadd.c
}
#endif //MDL_SET_OUTPUT_PORT_DIMENSION_INFO
#define MDL_SET_INPUT_PORT_SAMPLE_TIME
#if defined(MDL_SET_INPUT_PORT_SAMPLE_TIME) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortSampleTime(SimStruct *S,
int_T portIdx,
real_T sampleTime,
real_T offsetTime)
{
//
}
#endif //MDL_SET_INPUT_PORT_SMAPLE_TIME
#define MDL_SET_OUTPUT_PORT_SAMPLE_TIME
#if defined(MDL_SET_OUTPUT_PORT_SAMPLE_TIME) && defined(MATLAB_MEX_FILE)
static void mdlSetOutputPortSampleTime(SimStruct *S,
int_T portIdx,
real_T sampleTime,
real_T offsetTime)
{
//
}
#endif //MDL_SET_OUTPUT_PORT_SMAPLE_TIME
static void mdlInitializeSampleTimes(SimStruct *S)
{
//设置采样时间，如果未设置，则假定有个继承的采样时间。
//格式：[sample_time, offset_time]
//ssSetSampleTime(S, sampleTimePairIndex, sample_time)
//ssSetOffsetTime(S, offsetTimePairIndex, offset_time)
ssSetSampleTime(S, , CONTINUOUS_SAMPLE_TIME);
ssSetOffsetTime(S, , );
}//end mdlInitializeSampleTimes
#define MDL_SET_INPUT_PORT_DATA_TYPE
#if defined(MDL_SET_INPUT_PORT_DATA_TYPE) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortDataType(SimStrcut *S,
int portIndex,
DTypeId dType)
{
// 该方法和动态的输入端口候选数据一起调用。详见matlabroot/simulink/include/simstruc_types.h 中的内置类型定义：SS_DOUBLE, SS_BOOLEAN, etc; 例详见：matlabroot/simulink/src/sfun_dtype_io.c 。
}
#endif//MDL_SET_INPUT_PORT_DATA_TYPE
#define MDL_SET_OUTPUT_PORT_DATA_TYPE
#if defined(MDL_SET_OUTPUT_PORT_DATA_TYPE) && defined(MATLAB_MEX_FILE)
static void mdlSetOutputPortDataType(SimStrcut *S,
int portIndex,
DTypeId dType)
{
// 同上
}
#endif//MDL_SET_OUTPUT_PORT_DATA_TYPE
#define MDL_SET_DEFAULT_PORT_DATA_TYPE
#if defined(MDL_SET_DEFAULT_PORT_DATA_TYPE) && defined(MATLAB_MEX_FILE)
static void mdlSetDefaultPortDataTypes(SimStruct *S)
{
//当你的信息不足以确定唯一的输入输出数据类型时调用此函数。
}
#endif //MDL_SET_DEFAULT_PORT_DATA_TYPE
#define MDL_SET_INPUT_PORT_COMPLEX_SIGNAL
#if defined(MDL_SET_INPUT_PORT_COMPLEX_SIGNAL) && defined(MATLAB_MEX_FILE)
static void mdlSetInputPortComplexSignal(SimStruct *S,
int portIndex,
CSignal_T cSignalSetting)
{
//用于候选复杂信号设置（COMPLEX_YES,COMPLEX_NO）。
//ssSetInputPortComplexSignal , ssSetOutputPortComplexSignal
}
#endif //MDL_SET_INPUT_PORT_COMPLEX_SIGNAL
#define MDL_SET_OUTPUT_PORT_COMPLEX_SIGNAL
#if defined(MDL_SET_OUTPUT_PORT_COMPLEX_SIGNAL) && defined(MATLAB_MEX_FILE)
static void mdlSetOutputPortComplexSignal(SimStruct *S,
int portIndex,
CSignal_T cSignalSetting)
{
//同上。
//ssSetInputPortComplexSignal , ssSetOutputPortComplexSignal
}
#endif //MDL_SET_OUTPUT_PORT_COMPLEX_SIGNAL
#define MDL_SET_DEFAULT_PORT_COMPLEX_SIGNALS
#if defined(MDL_SET_DEFAULT_PORT_COMPLEX_SIGNALS) && defined(MATLAB_MEX_FILE)
static void mdlSetDefaultPortComplexSignals(SimStruct *S)
{
//当信息不足时调用
}
#endif// MDL_SET_DEFAULT_PORT_COMPLEX_SIGNALS
#define MDL_INITIALIZE_CONDITIONS
#if defined(MDL_INITIALIZE_CONDITIONS)
static void mdlInitializeConditions(SimStruct *S)
{
//初始化连续变量和离散变量。
}
#endif //MDL_INITIALIZE_CONDITIONS
#define MDL_START
#if defined(MDL_START)
static void mdlStart(SimStruct *S)
{
//在模块执行时调用一次（初始化）。
}
#endif //MDL_START
#define MDL_SIM_STATE
#if defined(MDL_SIM_STATE)
static mxArray* mdlGetSimState(SimStruct *S)
{
//inSinState MATLAB data structure
}
#endif//MDL_SIM_STATE
#define MDL_GET_TIME_OF_NEXT_VAR_HIT
#if defined(MDL_GET_TIME_OF_NEXT_VAR_HIT) && (defined(MATLAB_MEX_FILE)) || defined(NRT))
static void mdlGetTimeOfNextVarHit(SimStruct *S)
{
time_T timeOfNextHit = ssGetT(S)
ssSetTNext(S, timeOfNextHit);
}
#endif//MDL_GET_TIME_OF_NEXT_VAR_HIT
static void mdlOutputs(SimStruct *S, int_T tid)
{
}
#define MDL_UPDATE
#if defined(MDL_UPDATE)
static void mdlUpdate(SimStruct *S, int_T tid)
{
//更新离散变量
}
#endif //MDL_UPDATE
static void mdlTerminate(SimStruct *S)
{
//在这个函数中，执行模拟终止所需操作。如释放内存。
}
}
#ifdef MATLAB_MEX_FILE
#include "simulink.c"
#else
#include "cg_sfun.h"
#endif
如果有什么错误望指教。
参考Matlab官方文档sfuntmpl_doc.c
![数学建模浅谈[图]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)