基于C-MEX的S-Function编写指导书

基于C-MEX的S-Function编写指导书1、、概述概述本文档用来介绍基于c语言的S-Function编写指导说明，并通过一个C-MEXS-Function的范例来演示如何一步步的建立自己的S-function。2、、S-function介绍介绍2.1S-function能做什么能做什么S-function（SystemFunction）为扩展Simulink的性能提供了一个强大的工具。S-function的典型应用包括：1.向向Simulink增加一些新的通用模块增加一些新的通用模块，比如自定义的PLL模块、SVPWM发波模块、坐标变换模块等；2.增加作为硬件设备驱动程序的模块增加作为硬件设备驱动程序的模块（应用于半实物仿真中）；3.将已有的将已有的C代码应用到仿真中代码应用到仿真中（我司仿真模型主要使用此功能）；4.使用一组数学方程式来对系统进行描述使用一组数学方程式来对系统进行描述，比如自定义双馈电机模型、自定义三相异步电机模型等；5.使用可视化动作使用可视化动作（参见MATLAB范例中的倒立摆模型，penddemo）2.2S-function的工作原理的工作原理要创建S-function，首先必须了解S-function是如何工作的。要了解S-function如何工作，则需要了解Simulink是如何进行模型仿真的，那么又需要了解Simulink模块的数学公式。因此，本节首先从一个模块的输入、状态和输出之间的数学关系开始介绍。2.2.1Simulink模块的数学模型模块的数学模型一个Simulink模块的数学模型，包含一组输入、一组状态和一组输出。其中输出是采样时间、模块状态和模块输入的函数。图1Simulink模块的数学模型下面的方程式表述了Simulink模块输入、状态和输出之间的数学关系：2.2.2Simulink仿真的执行步骤仿真的执行步骤Simulink模型的执行分几个阶段进行。首先进行的是初始化阶段，在此阶段，Simulink将library模块合并到模型中来，确定信号宽度、数据类型和采样时间，计算模块参数，确定模块的执行顺序，以及分配内存。然后，Simulink进入到“仿真循环”，每次循环可认为是一个“仿真步”。在每个仿真步期间，Simulink按照初始化阶段确定的模块执行顺序依次执行模型中的每个块。对于每个块而言，Simulink调用函数来计算模块在当前采样时间下的状态，导数和输出。如此反复，一直持续到仿真结束。下图所示为Simulink仿真运行的执行步骤：图1Simulink仿真执行的步骤2.2.3S-function模块的回调程序模块的回调程序一个S-function包含了一组S-function回调程序，用以执行在每个仿真阶段所必需的任务。在模型仿真运行的不同阶段，S-function模块调用对应的回调程序。通过S-function的回调程序来执行的任务包括：初始化初始化：在“仿真循环”之前，Simulink引擎对S-function进行初始化，包括：初始化SimStruct，这是一个仿真数据结构，包含了关于S-function的信息设置输入和输出端口的数量和宽度设置S-function模块的采样时间分配存贮区间计算下步采样点计算下步采样点——如果你创建了一个变步长模块，那么在这里计算下一步的采样点，即计算下一个仿真步长计算主步长的输出计算主步长的输出——在该调用完成后，模块的所有输出端口对于当前仿真步长有效按主步长更新离散状态按主步长更新离散状态——在这个调用中，所有的模块应该执行“每步一次”的动作，如为下一个仿真循环更新离散状态计算积分计算积分——这适用于连续状态和/或非采样过零的状态。如果S-function中具有连续状态，Simulink在积分微步中调用S-function的输出和导数部分。这也是Sinmulink可以计算S-function状态的原因。如果S-function（仅对于CMEX）具有非采样过零的状态，Simulink在积分微步中调用S-function的输出和过零部分，这样可以检测到过零点。2.2.4Sinulink如何与如何与S-Function相互作用相互作用了解Simulink如何与S-Function相互作用对于编写CMEX文件的S-Function是十分有帮助的。下面从两个层面来介绍这种相互作用：进程层面，比如在仿真的哪一时刻，Simulink调用S-Function；数据层面，比如在仿真的过程中，Simulink与S-Function如何交换信息。进程层面：进程层面：下图所示为Simulink调用S-function回调函数的顺序。实线框部分表示在模型初始化和/或每个仿真步长内需使用的回调函数；虚线框部分表示在初始化阶段和/或在仿真循环的一些或所有采样步长内使用的回调函数。数据层面：数据层面：S-function模块具有输入和输出信号、参数、以及内部状态，再外加其它一般的工作域。在一般情况下，对于模块输入和输出信号的读写是通过一个模块I/O向量来实现的。模块输入信号也可来源于：通过根输入端口块而来的外部输入如果输入信号未连接或者接地，作为接地输入模块输出也可通过根输出端口块传递到外部输出。除了输入和输出信号之外，S-function还具有：连续状态变量离散状态变量诸如实数的、整数的或者指针的工作向量等其它工作域。另外，通过S-Function的参数对话框进行参数传递，也可对S-function模块的参数进行赋值。下图所示为各种类型数据之间的一般映射关系：3、、使用使用C语言编写语言编写S-function3.1C-MEXS-Function的编写的编写下面通过介绍一个基本的CMEXS-Function范例，来了解S-function的基本框架基本框架。该例子是来自于Simulink的S-function范例timestwo（参考目录matlabroot/simulink/src/timestwo.c）。该S-function的输出是其输入的两倍。首先，创建一个Simulink仿真模型：Example1_timestwo.slx，如下图：然后，在S-Function模块的对话框中输入timestwo_sf作为S-function的函数名，参数区为空，如下图：接下来开始编写S-Function的源代码：timestwo_sf.c，详细内容见附录1。对timestwo_sf.c的代码框架进行分析，发现S-function主要包含以下三个部分：定义与包含定义与包含回调函数的编写回调函数的编写Simulink（或者（或者Real-timeWorkshop）接口）接口下面分别对上述三个部分进行介绍。定义与包含定义与包含该范例以以下定义开头：#defineS_FUNCTION_NAMEtimestwo_sf#defineS_FUNCTION_LEVEL2#includesimstruc.h第一条指定了S-function的名字（timestwo_sf），第二条指定了该S-function是按照level2的格式进行编写的。定义了这两条之后，该范例包含了头文件simstruc.h，这个头文件给出了Simstruct数据结构的访问通道，以及MATLAB应用程序接口（API）函数。simstruc.h文件定义了一个名为SimStruct的数据结构，Simulink使用它来维护S-function的有关信息。simstruc.h文件也定义了一些宏，可让你的MEX文件在SimStruct中设置某些值，或从SimStruct中获取某些值。另外，在利用现有代码进行S-function编写时，也将宏定义与文件包含放在此处。例如海得变流器仿真模型的S-function文件：#includemath.h#definelongint#definecregister#defineasm(r)#defineinterrupt#define_RUN_NO_DSP_#includeincludes.h回调函数的实现回调函数的实现编写一个S-Function的主要内容就是创建在仿真过程中由Simulink调用的回调函数。S-functiontimestwo的接下来一部分包含了Simulink所需要的回调函数的实现。整理成表格如下：回调函数的名称回调函数的名称回调函数的作用回调函数的作用mdlInitializeSizesSimulink调用mdlInitializeSizes来获取输入端口和输出端口的数量、端口宽度、以及S-function所需的任何其它对象（诸如状态数量）等有关信息。mdlInitializeSampleTimesSimulink调用mdlInitializeSampleTimes来设置S-function的采样时间。关于S-function采样时间如何设置，请参考附录2.该范例中，只要驱动模块执行，该S-function模块就必须执行，因此设置为继承采样时间-SAMPLE_TIME_INHERITEDmdlStart在模型开始仿真运行时只被调用一次。源程序中，变量初始化的代码可以放在此处。本范例中无需初始化，故为空。mdlOutputs在每个采样时间步长内，Simulink调用mdlOutputs来计算块的输出。源程序中，主循环部分可以放在此处。本范例中，算法：输出等于输入乘以2即在此处实现。mdlTerminate执行仿真结束时的任务。这是一个托管S-function程序。本范例中，不需要执行任何终止动作，所以该程序是空的。Simulink/Real-TimeWorkshop接口接口在S-function的结尾部分，使用代码判断该范例是植入Simulink中，或是Real-TimeWorkshop中。#ifdefMATLAB_MEX_FILE/*IsthisfilebeingcompiledasaMEX-file?*/#includesimulink.c/*MEX-fileinterfacemechanism*/#else#includecg_sfun.h/*Codegenerationregistrationfunction*/#endif3.2编译编译S-Function要将此S-function结合到Simulink中，在MATLAB命令行输入下面的命令mextimestwo_sf.cmex命令将timestwo_sf.c进行编译和链接。生成一个mex可执行文件（timestwo_sf.mexw32）供Simulink使用。MEX从字面上是MATLABEXecuteable两个单词的缩写。.MEX文件是由C语言（或者Fortran语言）编写的源代码，经过MATLAB编译器处理而生成的二级制文件。它是可以被MATLAB解释器自动装载并执行的动态链接程序，类似于Windows下的dll文件。MEX文件的后缀名按32位/64位分别为.mexw32/.mexw64。MEX文件的编写和编译需要两个基本条件：一是必须按照MATLAB要求配置接口组件和相关工具，二是要有C语言或Fortran语言的编译器。Matlab中的配置使用如下命令按照提示进行：mex–setup3.3运行运行S-FunctionMex文件生成之后，S-Function模块就可以正常运行。Example1_timestwo.slx仿真结果运行如下：3.4CMEXS-Function模板模板创建CMEXS-Function有多种方法，最简单的方法是使用S-FunctionBuilder自动生成S-function。但是这种方法只能生成几种简单的S-function，例如它生成的S-function的输入或输出端口的信号宽度只能为1，而且不能处理除了double以外的其它类型数据。另一种方法是根据“CS-Function模板”来创建。Simulink提供了实现一个CMEXS-function的架构文件，这里称之为模板。它是专门为用户编写的用于指导用户编写自己的S-function。该模板包含了