C语言编写S函数方法.doc

S函数（system function）是模块的核心，是完成功能实现的关键。S函数的编写可以使用多种程序语言，其中M语言是最常用的，同时也是最简单的。在运用M语言进行s函数编写的时候，可以调用MATLAB提供的函数，简化了开发过程。但是如果要与其他进程通讯或驱动外部硬件接口，则要调用API函数，这样就需要用C语言来开发S函数。较M语言的开发，C语言开发S函数更具有灵活性，但是相对复杂一些。C语言写S函数，顾名思义，运用C语言语法，依照S函数格式要求，最后在MATLAB中MEX命令编译，编译成功既得函数。S函数格式可简单看成：初始化、采样时间设定、系统输出、结束四个部分。对应的函数分别为mdlInitializeSizes()、mdlInitializeSampleTimes()、mdlOutputs()、mdlTerminate()。这四个函数是一个S函数必不可少的，缺少任何一个在编译的时候都无法通过，输出信息会提示哪个函数没有写。一个最基本的C语言S函数模版如下：#defineS_FUNCTION_NAMEname#define S_FUNCTION_LEVEL2#include“simstruc.h”Static void mdlInitializeSizes(SimStruct *S)Static void mdlInitializeSampleTimes(SimStruct *S)Static void mdlOutputs(SimStruct *S,int_T tid)Static void mdlTerminate(SimStruct *S)#ifdefMATLAB_MEX_FILE#include“Simulink.c”#else#include“cg_sfun.h”#endifS函数的运行依托于Simulink，Simulink的运行是采用循环方式，计算各采样时间点的系统状态得到的，由此可理解S函数，在初始化之后，S函数也通过循环完成输出状态计算。结合上述格式，首先自定义S函数名称，然后定义S函数级别，这里写2，1级是老版本Simulink使用的，现已经不是用，之所以保留1级是为了兼容原有的老程序，现在写的S函数都是2级的。接下来将需要的头文件包含进来，这里必须包含simstruc.h文件，这里的SimStruc是Simulink提供的数据结构，S函数中的输入输出等信息都包含在这个结构体中，同时，在编写S函数的时候也要把使用到的C语言库中的头文件包含进来，所有的C语言库文件在这里都可以使用。接下来即可按照格式顺序编写代码。最后要注意，如果用于仿真则添加Simulink.c文件，如果用于RTW代码生成，则添加cg_sfun.h头文件。这里的RTW代码生成是指非内嵌的S函数，如果要做一个内嵌的S函数则需要在S函数中添加mdlRTW()函数，并额外编写TLC文件。其中，TLC文件用于优化的C代码生成，mdlRTW()函数则把模块参数传递到生成的代码当中。具体TLC文件的编写方法这里不再赘述。除了上述必需的函数外，系统提供了其他可选用的函数，功能各异，例如mdlStart()等。只要理解了Simulink运行方式就可以理解文件的开发过程了，其中，系统函数和特定的变量类型都可以在SimStruct数据结构中找到。至此，基本的S函数都可以编写了。在编写结束后，将S函数源文件存储在MATLAB路径下，打开MATLAB命令行窗口，选择当前路径为存储路径，运用MEX命令编译C源文件，如果成功则在当前路径下生成一个后缀名为mexw32的文件（后缀名随系统环境不同而不同，32指32位系统，如果是64位系统则不同），如果使用的是MATLAB早期版本，则生成的文件后缀名为dll，即动态链接库。两者等价，这里可以用dll来理解mexw32文件的作用。当S函数编译写好之后，还不能在Simulink中直接调用，因为缺少一个可视化的模块。这时候打开Simulink，在用户自定义模块库中找到名称为S_function的模块，并将它拖拽到模型文件中。可以把它看成一个S函数的通用的容器，下面介绍如何把编写好的S函数放入这个容器，即模块封装。下面讲解S函数的模块封装方法：右键点击S函数模块，选择MASK选项，弹出封装编辑框，在这里有四个栏，分别为图标、参数、初始化、文档。其中参数最为重要。图标即模块上显示的图形，可以编辑自己需要的文字，也可以用图片包装模块。初始化可以对模块参数进行默认设置，文档中可以编写模块说明和帮助链接。而最重要的参数栏中，要把模块对应的S函数的参数列出来，每一个参数有三种形式：编辑、下拉框、复选框。如果是下拉框形式，要编辑对应的选项。如果S函数需要响应不同操作，可以对每一个参数选择编写对应的回调函数。值得一提的是，可以用set_param()函数直接对封装模块进行操作，可以实现更加灵活的封装。封装编辑好后，右键点击S函数模块选择LOOK UNDER MASK选项，在弹出的对话框中，首先填写原文件，把编译过的文件（mexw32）放置在当前目录下，在对话框中正确填写文件名（不写后缀），然后再把封装时定义的参数变量按顺序写在参数框中，每个参数用逗号隔开，注意变量名必须与封装填写的名称一致，且数目相同。最有一个框不用填写。点击OK。则完成了对S函数的模块封装。完成上述两个步骤之后，即完成了自定义的Simulink驱动模块，这时要做的工作是对该模块经行测试。若测试通过，可以将该模块添加进Simulink模块库，和Simulink提供的模块并没有任何的区别，方便以后工作中的重复利用。若测试未通过，则返回S函数编写工作中，重新编写S函数，重复上述步骤。由于封装只是一个将S函数图形化的过程，当测试出现问题的时候，可以确定是S函数的工作出现了问题，而不是因为封装引发的。由于水平有限，这里讲解不那么易于理解，可以在学习过程中，参照现有程序和MATLAB帮助文档，从自己动手编写简单的S函数入手，一旦完成一次，以后就很好理解了。4.1 C MEX-file S-function简介定义了S-function模块的C MEX-file必须在仿真过程中向Simulink提供模型信息。在仿真中Simulink、ODE求解器、MEX-file协作完成指定任务。这些任务包括：定义初始条件和模块特性，计算微分、离散状态和输出。Simulink与C MEX-file S-function模块的交互仍是通过S-function的回调方法。每个回调方法执行一个预定义的，实现仿真所需功能的任务。S-function可以执行任何其实现的任务。一系列C MEX-file S-function实现的回调方法，都远大于M-file S-function中的。与M-file S-function不同的是，C MEX-file可以访问并修改Simulink内部用来存储S-function信息的数据结构。更多的回调方法和对Simulink内部数据结构的访问能力，使得C MEX-file S-function可以实现更丰富的模块特性，如处理矩阵信号和多种数据类型。C MEX-file S-function只需实现Simulink定义的回调方法的一个小子集即可。如果不实现某个回调方法，相应的功能将被省略掉。这有利于快速开发简单的模块。通常C MEX-file S-function的形式如下：#define S_FUNCTION_NAME your_sfunction_name_here#define S_FUNCTION_LEVEL 2#include simstruc.hstatic void mdlInitializeSizes(SimStruct *S)static void mdlTerminate(SimStruct *S)#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */#include simulink.c /* MEX-file interface mechanism */#else#include cg_sfun.h /* Code generation registration function */#endifmdlInitializeSizes是Simulink与S-function交互时调用的第一个方法。随后Simulink将调用其他S-function方法（都以mdl开头）。仿真结束时，Simulink调用mdlTerminate。注意：与M-file S-function不同，C MEX-file S-function回调方法不是每个都具有flag参数。这是因为，Simulink仿真时直接在适当的时间调用每个回调方法。4.2 自动建立S-function模块S-Function Builder是通过规范定义和用户提供的C代码建立S-function的Simulink模块。S-Function Builder还用作普通的S-function在Simulink模型中的包装。通过S-Function Builder建立S-function。1. 将MATLAB当前目录设置到需要建立S-function的目录。2. 创建新的Simulink模型。3. 从Simulink User-Defined Functions library中将S-Function Builder拖入新建的ulink模型。4. 双击模块打开S-Function Builder对话框。5. 输入所需信息和用户代码。（详见下节）6. 如果还未设置mex编译器，用mex setup在MATLAB命令行设置。7. 点Build按钮，启动建立过程。Simulink建立MEX文件实现指定的S-function，并存放在当前目录8. 保存包含S-Function Builder模块的模型。部署生成的S-Function要在其他模型中使用生成的S-Function，首先必须检查生成的S-Function所在的目录是否在MATLAB路径中。然后把S-Function Builder模块从创建它的模型复制到目标模型并设置其参数。S-Function Builder如何建立S-Function4.3 S-Function Builder对话框4.4 基本的C MEX-file S-function实例本节介绍一个C MEX-file S-function实例：timestwo，实现输出信号放大为输入信号的2倍。以下是模型图：以下是timestwo.c文件的代码：#define S_FUNCTION_NAME timestwo#define S_FUNCTION_LEVEL 2#include simstruc.hstatic void mdlInitializeSizes(SimStruct *S)ssSetNumSFcnParams(S, 0);if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S) return; /* Parameter mismatch will be reported by Simulink */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_WORKS_WITH_CODE_REUSE |SS_OPTION_EXCEPTION_FREE_CODE |SS_OPTION_USE_TLC_WITH_ACCELERATOR);static void mdlInitializeSampleTimes(SimStruct *S)ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);ssSetOffsetTime(S, 0, 0.0);ssSetModelReferenceSampleTimeDefaultInheritance(S);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; iwidth; i+)*y+ = 2.0 *(*uPtrsi);static void mdlTerminate(SimStruct *S)#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */#include simulink.c /* MEX-file interface mechanism */#else#include cg_sfun.h /* Code generation registration function */#endif这个实例包括3部分：宏定义和头文件；回调方法的实现；Simulink (或 Real-Time Workshop)接口。宏定义和头文件示例程序中包含两个宏定义：#define S_FUNCTION_NAME timestwo#define S_FUNCTION_LEVEL 2第一个指定S-function的名字，第二个指示该S-function是Level-2格式的。然后是包含头文件simstruc.h，在其中定义了SimStruct数据结构和MATLAB应用程序接口(API)函数。SimStruct是Simulink用于保持S-function信息的数据结构，simstruc.h中还有用于MEX文件设置或获取SimStruct属性值的宏定义。回调方法的实现mdlInitializeSizes：Simulink调用mdlInitializeSizes方法查询S-function模块的输入输出端口数，端口容量，以及S-function所需的其他对象（如，状态个数等）。Timestwo实现的mdlInitializeSizes方法指定了下面信息 零参数：意味着S-function对话框的参数框必须为空。否则，Simulink将报告参数不匹配。 一个输入和一个输出端口：输入输出端口的宽度可以动态变化。Simulink将把所有输入信号乘以2作为输出信号的结果。注意，在这种情况下（一个输入一个输出端口），Simulink对S-function宽度的默认处理是输入和输出宽度相等。 一个采样时间例子timestwo在mdlInitializeSampleTimes中指定实际的采样时间。 代码无异常处理指定无异常处理的代码可以加速S-function的执行。作这项指定必须谨慎。通常，如果用户S-function与MATLAB没有交互，指定无异常处理的代码是安全的。mdlInitializeSampleTimes：Simulink调用mdlInitializeSampleTimes设置S-function的采样时间。每当timestwo模块的前驱模块执行一次，timestwo模块就执行一次，所以timestwo模块采用继承的采样时间。mdlOutputsSimulink在每个时间步调用mdlOutputs计算模块的输出。Timestwo模块的mdlOutputs方法实现了将输入信号乘以2，将结果写到输出信号。Timestwo模块的mdlOutputs方法使用了SimStruct中的宏：InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);来实现对输入信号的访问。这个宏返回一个指针向量，必须通过*uPtrsi来访问。Timestwo模块的mdlOutputs方法还使用了real_T *y = ssGetOutputPortRealSignal(S,0);来访问输出信号。这个宏返回一个包含模块输出的数组。S-function使用int_T width = ssGetOutputPortWidth(S,0);来得到通过该模块的信号宽度。最后S-function循环通过输入得到输出。mdlTerminate执行仿真结束最后的任务。这是一个强制的S-function过程。不过由于timestwo模块不需要任何终止操作，所以其函数为空。Simulink/Real-Time Workshop 接口在S-function的最后，下面的特定代码将该例子关联到Simulink或者Real-Time Workshop：#ifdef MATLAB_MEX_FILE#include simulink.c#else#include cg_sfun.h#endif生成timestwo实例在命令行键入：mex timestwo.cmex命令将把timestwo.c编译、链接为一个可由Simulink动态加载执行的模块。这是一个动态链接库文件，在Window中，是个dll文件。4.5 C MEX S-functions模板Simulink提供了C MEX S-functions模板。/simulink/src/sfuntmpl_basic.c提供了C MEX S-functions的常用功能方法。/simulink/src/sfuntmpl_doc.c则描述了C MEX S-functions的全部实现方法。S-function源代码文件的要求用户S-function要访问SimStruct结构，则必须在文件头部具备下列宏定义和头文件：#define S_FUNCTION_NAME your_sfunction_name_here#define S_FUNCTION_LEVEL 2#include simstruc.h这里your_sfunction_name_here指得是用户S-function的模块名。这些声明使S-function能访问SimStruct结构。当被编译为MEX文件时，matlabroot/simulink/include/simstruc.h将包括下面头文件：Header FileDescriptionmatlabroot/extern/include/tmwtypes.hGeneral data types, e.g., real_Tmatlabroot/extern/include/mex.hMATLAB MEX-file API routinesmatlabroot/extern/include/matrix.hMATLAB MEX-file API routines当被编译为MEX文件时，matlabroot/simulink/include/simstruc.h将包括下面头文件：Header FileDescriptionmatlabroot/extern/include/tmwtypes.hGeneral types, e.g., real_Tmatlabroot/rtw/c/libsrc/rt_matrx.hMacros for MATLAB API routines用户C MEX S-function文件尾部必须包括下面声明：#ifdef MATLAB_MEX_FILE /* Is this being compiled as MEX-file? */#include simulink.c /* MEX-file interface mechanism */#else#include cg_sfun.h /* Code generation registration func */#endif这些声明确保针对用户具体应用选择适当的代码： 当被编译为MEX文件的时候，simulink.c文件将被包含。 当被编译为关联了实时工具箱（Real-Time Workshop）的独立程序时，cg_sfun.h文件将被包含。SimStruct结构C头文件matlabroot/simulink/include/simstruc.h定义了Simulink数据结构和访问SimStruct的宏定义。SimStruct封装了所有模型和S-function相关的数据。Simulink模型具有一个与之关联的SimStruct结构，而模型中的每个S-function模块也具有自己的SimStruct结构。这些SimStruct组成一个目录树，模型的SimStruct为根，S-function模块的SimStruct为孩子。编译C S-functionS-function可以以下列三种方式编译： MATLAB_MEX_FILE 编译为用于Simulink的MEX文件。 RT 通过Real-Time Workshop生成代码，成为一个具有固定步长求解器的实时应用程序。 NRT 通过Real-Time Workshop生成代码，成为一个具有变步长求解器的非实时应用程序。4.6 Simulink和C MEX S-functions的互操作本节从过程和数据两方面的观点来介绍Simulink和C MEX S-functions的交互。过程观点下图描述了Simulink调用S-function回调方法的顺序。实线框表示该回调函数在初始化和（或）仿真循环的每个时间步都被调用；虚线框表示该回调函数可能在初始化和（或）仿真循环的每个时间步被调用。S-function模块具有输入、输出信号，参数，内部状态，加上其他普通的工作区间。通常模块的输入输出信号都从模块的I/O向量读写。输入还可来自： 根输入模块的外部输入。 本地磁盘，如果没有输入信号连接或者是落地的数据。输出也可以写到根输出模块的外部输出。除了输入、输出信号，S-functions还具有: 连续状态。 离散状态。 其他工作区间，如实型、整形或指针工作向量。利用S-function的对话框还可以实现S-function模块的参数化。S-function的mdlInit