1. 项目概述为什么我们需要S函数如果你用过一段时间Simulink肯定会遇到一个尴尬的局面库里的模块功能很强但有时候就是差那么一点。比如你想实现一个带死区的特殊PID或者想嵌入一段自己写的复杂算法甚至是想调用一个C语言写的现成函数库。这时候拖拽标准模块、用加减乘除和查表去“拼凑”一个功能不仅效率低下模型也变得臃肿不堪可读性直线下降。Simulink的S函数System-Function就是官方留给我们的“后门”一个让你能彻底自定义模块行为的强大工具。简单来说S函数让你能用MATLAB、C、C、Fortran甚至Ada来编写Simulink模块的核心算法。它像是一个标准化的接口协议你只要按照这个协议告诉Simulink“在我的模块里初始化要干嘛、每个仿真步长怎么算、仿真结束怎么收尾”Simulink就会在对应的时机调用你的代码。这样一来任何你能用代码描述的动态系统都能无缝集成到Simulink的图形化仿真环境中。无论是为了封装复杂逻辑、重用遗留代码还是为了追求极致的执行效率特别是C/C S函数S函数都是进阶Simulink建模的必修课。我最初接触S函数是为了把一个用C写的电机磁场计算程序嵌入到控制系统仿真里。当时试过用MATLAB Function模块但遇到循环调用和效率问题就卡住了直到用了S函数才豁然开朗。今天我就从一个实用主义者的角度带你初识S函数并通过一个最简单的案例让你亲手实现一个自定义模块感受它的威力。2. S函数核心概念与工作原理拆解2.1 S函数到底是什么一个“回调函数”集合不要把S函数想象成一个高深莫测的黑魔法。它的本质是一组约定好的回调函数Callback Functions。Simulink仿真引擎在运行过程中会在特定的时间点或称“阶段”去调用你编写的这些函数。你的任务就是为这些回调函数填写具体的执行内容。主要的回调函数包括mdlInitializeSizes这是“开工仪式”。在这里你需要定义模块的基本规格有几个输入端口、几个输出端口输入输出信号的维度是标量、向量还是矩阵和数据类型double, single, int32等是什么有没有需要持续存在的内部状态比如积分器的累加值有没有需要用户从模块参数对话框设置的参数这个函数只在仿真开始前调用一次用于搭建模块的框架。mdlInitializeSampleTimes定义模块的“心跳节奏”。你可以指定模块是连续运行、离散运行如果是离散采样周期是多少、还是继承上一级系统的采样时间。这是保证仿真时序正确的关键。mdlOutputs这是模块的“核心生产车间”。在每个仿真步长取决于你设置的采样时间Simulink都会调用这个函数。你在这里编写核心算法读取输入端口的值经过一系列计算将结果写入输出端口。对于纯增益、自定义运算等无状态模块主要代码就写在这里。mdlUpdate这是模块的“内部状态更新车间”。如果你的模块有内部状态例如当前输出依赖于上一次的输出就需要在这个函数里更新这些状态。例如实现一个离散积分器mdlOutputs里输出的是当前累积值而mdlUpdate里则需要根据输入计算新的累积值并存储起来供下一个步长使用。mdlTerminate仿真结束时的“收尾工作”。用于释放内存、关闭文件等清理操作通常不是必须的。Simulink仿真过程就像一个精准的舞台调度而你的S函数就是演员的剧本。调度员仿真引擎在“初始化”、“输出计算”、“状态更新”、“结束”这些cue点喊出指令演员你的代码就按照剧本执行相应的动作。2.2 编写S函数的两种主流方式M语言与C语言根据编写语言的不同S函数主要分为两类选择哪种取决于你的需求M文件S函数Level-2 M-file S-Function优点开发调试极其方便。直接用MATLAB语言编写无需编译修改后立即生效。可以利用MATLAB强大的矩阵运算和工具箱函数。非常适合算法原型验证、快速实现复杂数学运算。缺点执行速度慢。由于是解释执行在大型仿真或需要被反复调用的子系统中会成为性能瓶颈。不适合用于产品级代码生成。适用场景算法研究、概念验证、对仿真速度不敏感的复杂逻辑实现。C语言S函数C MEX S-Function优点执行速度快。编译成MEX文件后运行效率接近Simulink内置模块。是支持代码生成Simulink Coder的推荐方式生成的代码高效、可移植。缺点开发门槛高。需要熟悉C语言和Simulink S函数的API接口。需要配置编译器如MinGW-w64或Microsoft Visual C涉及编写、编译、调试的完整流程调试过程比M文件复杂。适用场景对仿真速度有要求的模型需要将模型生成产品级C代码的场景集成已有的C语言算法库。注意网上很多老教程提到的“Level-1 M-file S-Function”已经过时MathWorks官方推荐使用功能更强大、更稳定的Level-2格式。我们后续讨论均基于Level-2 M文件S函数这是最好的入门起点。2.3 S函数模块在Simulink中的使用流程无论你用哪种语言编写在Simulink模型中使用S函数的流程是统一的编写S函数源文件创建一个.m文件M文件或.c文件C文件。编译仅C语言在MATLAB命令行使用mex filename.c命令编译C文件生成同名的.mexw64Windows或.mexa64Linux等平台相关的MEX文件。在模型中放置S-Function模块从Simulink库浏览器中找到User-Defined Functions库将其中的S-Function模块拖到模型中。配置模块双击该模块在“S-function name”对话框中填入你的S函数名称不带扩展名。例如你写的M文件叫myPID.sfcn.m就填myPID编译后的C MEX文件叫myController就填myController。然后在“S-function parameters”中填入你想要传递给S函数的参数值。连接与仿真像使用普通模块一样连接输入输出信号线运行仿真。3. 手把手实现第一个S函数一个带限幅的增益模块理论说再多不如动手做一遍。我们来实现一个看似简单但很实用的模块带输出限幅的增益器。它完成输出 增益 * 输入的运算但会将输出限制在[下限, 上限]的范围内。这个功能用标准库模块组合也能实现Gain Saturation但用S函数封装成一个模块模型会更简洁也更利于理解S函数的工作流程。我们将使用Level-2 M文件S函数来实现因为无需编译最适合学习和快速验证。3.1 创建S函数模板与框架搭建MATLAB为我们提供了创建Level-2 M文件S函数的模板。最快捷的方法是使用内置向导在MATLAB命令行输入edit sfuntmpl.m。这会打开一个Level-2 M文件S函数的详细模板和说明。我们可以参考它但更简单的方法是直接基于一个更简洁的框架开始。我建议新建一个空白文件从头开始编写理解每一部分。我们在当前目录下创建一个新文件命名为GainWithLimits.m。首先搭建S函数的类框架。Level-2 M文件S函数本质上是一个MATLAB类它继承自Simulink.MSFcnRunTimeBlock类。function GainWithLimits(block) % Level-2 M文件S函数带限幅的增益器 % 输入u, 增益Gain, 下限LowerLimit, 上限UpperLimit % 输出y max(LowerLimit, min(UpperLimit, Gain * u)) setup(block); % ----------------------------------------------- function setup(block) % 初始化函数定义模块的基本属性 % ----------------------------------------------- % 注册输入输出端口数量 block.NumInputPorts 1; % 一个输入端口 block.NumOutputPorts 1; % 一个输出端口 % 设置端口属性 block.SetPreCompInpPortInfoToDynamic; % 输入端口属性继承或动态设置 block.SetPreCompOutPortInfoToDynamic; % 输出端口属性继承或动态设置 % 具体指定输入端口属性 block.InputPort(1).Dimensions 1; % 标量输入 block.InputPort(1).DatatypeID 0; % 0代表double类型 block.InputPort(1).Complexity Real; % 实数信号 block.InputPort(1).DirectFeedthrough true; % 重要输出直接依赖于输入必须设为true % 具体指定输出端口属性 block.OutputPort(1).Dimensions 1; % 标量输出 block.OutputPort(1).DatatypeID 0; % double类型 block.OutputPort(1).Complexity Real; % 实数信号 % 定义模块参数增益、下限、上限 block.NumDialogPrms 3; % 三个对话框参数 block.DialogPrmsTunable {Tunable, Tunable, Tunable}; % 参数可在仿真过程中调整 % 设置采样时间为继承-1 block.SampleTimes [-1 0]; % [采样周期, 偏移量]-1表示继承驱动端口的采样时间 % 指定主要的回调函数 block.RegBlockMethod(PostPropagationSetup, DoPostPropSetup); % 用于设置工作向量状态 block.RegBlockMethod(InitializeConditions, InitConditions); % 初始化状态本例不需要但展示流程 block.RegBlockMethod(Outputs, Output); % 计算输出 block.RegBlockMethod(Update, Update); % 更新状态本例不需要代码解读与注意事项block对象是Simulink与你的S函数通信的桥梁所有设置和操作都通过它进行。NumInputPorts和NumOutputPorts必须准确设置。端口索引从1开始。DirectFeedthrough是一个极易出错的关键属性。如果当前时刻的输出计算直接依赖于当前时刻的输入就像我们这个增益模块y Gain * u则必须设为true。如果输出只依赖于状态和过去的输入如积分器则设为false。设置错误会导致Simulink代数环检测或排序错误。NumDialogPrms定义了模块参数对话框中有几个参数。用户在S-Function模块参数栏输入的数值会按顺序传递给S函数。DialogPrmsTunable定义了参数是否可调。设为‘Tunable’意味着在仿真运行过程中你可以通过MATLAB命令或外部接口修改这些参数而无需停止仿真。这对于参数整定如调PID非常有用。SampleTimes [-1 0]是最常用的设置表示模块采样时间继承其输入信号的采样时间。对于多速率系统这里可以设置具体的采样周期。RegBlockMethod用于注册回调函数。我们注册了四个最常用的方法。3.2 实现回调函数定义模块行为接下来我们实现注册的那些回调函数。% ----------------------------------------------- function DoPostPropSetup(block) % 在工作向量中分配内存用于存储状态本例中我们不需要状态但展示方法 % 如果模块有离散状态可以在这里用 block.NumDworks 和 block.Dwork 来设置 % 本例无状态所以什么都不做 % ----------------------------------------------- % ----------------------------------------------- function InitConditions(block) % 初始化状态如果有的话 % 例如如果Dwork(1)用于存储积分值可以在这里初始化为0 % block.Dwork(1).Data 0; % ----------------------------------------------- % ----------------------------------------------- function Output(block) % 核心在每个仿真步长计算输出 % ----------------------------------------------- % 1. 从输入端口读取当前输入值 u block.InputPort(1).Data; % 2. 从对话框参数获取增益、下限、上限 Gain block.DialogPrm(1).Data; % 第一个参数增益 LowerLimit block.DialogPrm(2).Data; % 第二个参数下限 UpperLimit block.DialogPrm(3).Data; % 第三个参数上限 % 3. 执行核心算法先增益后限幅 y_unlimited Gain * u; y_limited max(LowerLimit, min(UpperLimit, y_unlimited)); % 4. 将计算结果写入输出端口 block.OutputPort(1).Data y_limited; % ----------------------------------------------- function Update(block) % 更新离散状态如果有的话 % 例如实现一个离散积分器block.Dwork(1).Data block.Dwork(1).Data block.InputPort(1).Data * block.SampleTimes(1); % 本例无状态需要更新所以留空 % -----------------------------------------------实操心得在Output函数中block.InputPort(1).Data获取的是当前仿真步长下输入端口1的信号值。如果输入是向量或矩阵Data就是一个数组。block.DialogPrm(1).Data获取的是用户在模块参数对话框中第一个参数框里填入的值。这些值在仿真过程中是常量除非设置为可调并在线修改。限幅逻辑max(LowerLimit, min(UpperLimit, value))是一个经典且高效的写法先通过min限制上限再通过max保证下限。即使Update函数当前用不到也最好保留一个空函数。这样当你未来需要添加状态时结构是清晰的。3.3 在Simulink中测试与验证现在我们已经在GainWithLimits.m文件中完成了S函数的编写。接下来在Simulink中测试它。新建模型打开Simulink新建一个空白模型。添加模块从Sources库拖入一个Sine Wave信号源频率设为1 Hz振幅设为5。从User-Defined Functions库拖入一个S-Function模块。从Sinks库拖入一个Scope示波器。配置S-Function模块双击S-Function模块打开参数对话框。在 “S-function name” 一栏填写GainWithLimits注意不要加.m后缀。在 “S-function parameters” 一栏填写2, -3, 3。这表示增益为2下限为-3上限为3。参数之间用逗号分隔。点击OK。连接模型将Sine Wave输出连接到S-Function模块输入再将S-Function模块输出连接到Scope。运行仿真点击运行按钮。双击Scope查看波形。你应该看到一个振幅为5的正弦波输入经过增益2后理论输出应为振幅10的正弦波。但由于我们设置了输出限幅[-3, 3]所以正弦波的波峰和波谷会被“削顶”和“削底”输出被限制在-3到3之间。测试可调参数为了验证Tunable参数的功能我们可以在仿真运行时动态修改增益。保持仿真处于运行状态或暂停状态。在MATLAB命令行输入set_param(你的模型名/S-Function, DialogPrm1, 5)将增益从2改为5。观察Scope你会发现输出波形立即发生了变化限幅后的平台区域变得更宽因为放大后的信号更容易达到限幅值。这就是参数在线调谐的功能。4. 从M文件S函数进阶到C MEX S函数当你用M文件S函数验证了算法正确性并且对仿真速度或代码生成有要求时就需要将其转换为C MEX S函数。我们以上面的带限幅增益器为例简述C S函数的实现要点。4.1 C S函数的基本骨架创建一个GainWithLimits.c文件。C S函数也有固定的回调函数名和参数列表。一个最简化的、实现同样功能的C S函数核心部分如下#define S_FUNCTION_NAME GainWithLimits #define S_FUNCTION_LEVEL 2 #include simstruc.h /* 算法核心输出计算函数 */ static void mdlOutputs(SimStruct *S, int_T tid) { // 获取输入、输出、参数指针 InputRealPtrsType uPtrs ssGetInputPortRealSignalPtrs(S, 0); real_T *y ssGetOutputPortRealSignal(S, 0); const real_T Gain *mxGetPr(ssGetSFcnParam(S, 0)); // 增益参数 const real_T LowerLimit *mxGetPr(ssGetSFcnParam(S, 1)); // 下限 const real_T UpperLimit *mxGetPr(ssGetSFcnParam(S, 2)); // 上限 real_T y_temp Gain * (*uPtrs[0]); // 计算增益后输出 // 限幅处理 if (y_temp UpperLimit) { y_temp UpperLimit; } else if (y_temp LowerLimit) { y_temp LowerLimit; } y[0] y_temp; // 赋值给输出 } /* 必须实现的几个回调函数 */ static void mdlInitializeSizes(SimStruct *S) { ssSetNumSFcnParams(S, 3); // 3个参数 if (ssGetNumSFcnParams(S) ! ssGetSFcnParamsCount(S)) return; ssSetNumContStates(S, 0); ssSetNumDiscStates(S, 0); // 配置输入端口 if (!ssSetNumInputPorts(S, 1)) return; ssSetInputPortWidth(S, 0, 1); // 端口0宽度为1标量 ssSetInputPortDirectFeedThrough(S, 0, 1); // 直接馈通 ssSetInputPortRequiredContiguous(S, 0, true); // 配置输出端口 if (!ssSetNumOutputPorts(S, 1)) return; ssSetOutputPortWidth(S, 0, 1); // 端口0宽度为1 ssSetNumSampleTimes(S, 1); // 一个采样时间 ssSetNumRWork(S, 0); ssSetNumIWork(S, 0); ssSetNumPWork(S, 0); ssSetNumModes(S, 0); ssSetNumNonsampledZCs(S, 0); } static void mdlInitializeSampleTimes(SimStruct *S) { ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME); // 继承采样时间 ssSetOffsetTime(S, 0, 0.0); } /* 将函数与Simulink调度关联 */ #ifdef MATLAB_MEX_FILE #include simulink.c #else #include cg_sfun.h #endif4.2 编译与使用C S函数确保有编译器在MATLAB命令行输入mex -setup按照提示选择和配置一个C/C编译器如MinGW-w64。编译在MATLAB命令行切换到GainWithLimits.c所在目录运行mex GainWithLimits.c。使用编译成功后会生成一个GainWithLimits.mexw64Windows文件。在Simulink的S-Function模块中S-function name 填GainWithLimitsSimulink会自动找到并调用这个MEX文件。使用方法与M文件S函数完全一致。C S函数的关键差异与注意事项API不同C S函数使用一套以ss开头的宏和函数如ssGetInputPortRealSignalPtrs,ssSetNumInputPorts来与Simulink交互。需要查阅simstruc.h头文件和文档。指针操作C语言中直接操作信号指针效率高但要小心指针越界。参数获取ssGetSFcnParam(S, idx)返回的是一个mxArray指针需要用mxGetPr来获取其中的数值数据。代码生成支持这个简单的C S函数已经具备了被Simulink Coder生成代码的潜力。更复杂的、涉及内存分配和复杂数据类型的S函数需要额外实现mdlStart,mdlTerminate以及为代码生成准备的mdlRTW等函数。5. S函数开发中的常见“坑”与调试技巧在实际项目中编写和调试S函数总会遇到一些问题。这里分享几个我踩过的坑和解决方法。5.1 典型错误与排查表错误现象可能原因排查与解决方法仿真报错“Algebraic loop detected”S函数模块的DirectFeedthrough属性设置错误。当输出依赖于当前输入时必须设为true。检查算法逻辑。如果y f(u)DirectFeedthrough必须为true。在M文件中检查block.InputPort(1).DirectFeedthrough设置。在C文件中检查ssSetInputPortDirectFeedThrough的调用。仿真报错“Invalid setting for input port dimensions”端口维度定义不一致或动态维度处理不当。在M文件的setup函数中确保block.InputPort(1).Dimensions设置正确。如果希望继承前级维度可以设为-1可变维度但需在PostPropagationSetup或Output中动态获取。C文件中对应检查ssSetInputPortWidth。S-Function模块显示“”或无法识别S函数名填写错误或MEX文件未成功编译/路径不对。1. 确认S-function name没有文件扩展名.m,.c,.mexw64。2. 对于M文件确保文件在MATLAB路径中。3. 对于C文件在命令行运行which GainWithLimits确认能找到MEX文件。使用rehash命令更新路径缓存。仿真结果与预期不符如输出为0算法逻辑错误或参数获取错误。1.使用调试器在M文件S函数的Output函数中设置断点dbstop if error或直接点击行号左侧单步执行查看变量值。2.打印调试在M文件的Output函数中使用disp或fprintf打印中间变量。对于C S函数使用mexPrintf函数输出调试信息到MATLAB命令行。3. 检查参数索引block.DialogPrm(1)对应的是对话框第一个参数确认顺序。仿真速度异常缓慢仅M文件M文件S函数本身解释执行慢或函数内有低效循环。1. 这是M文件S函数的固有缺点。对于性能关键部分考虑向量化操作或迁移到C S函数。2. 使用MATLAB Profiler (profile on运行仿真profile viewer) 分析S函数中哪些行耗时最多。代码生成失败针对C S函数C S函数使用了不支持的API或动态内存操作。1. 确保使用的API宏和函数在代码生成环境中有效。查阅Simulink Coder文档中关于S函数支持的部分。2. 避免使用malloc/free。使用Simulink提供的ssGetRWork,ssGetDWork等方法来分配持久化内存。5.2 高级调试技巧使用Simulink Debugger对于复杂的S函数尤其是C S函数Simulink Debugger是利器。在模型编辑界面菜单栏选择Debug - Step Over进入调试模式。仿真会逐步执行。当执行到包含S函数的模块时会跳入S函数的代码中对于M文件会直接在编辑器中高亮当前行对于C MEX文件如果你有源代码并编译时包含了调试信息也可以在Visual Studio等编译器中调试。你可以观察模型中的信号值同时查看S函数内部变量的变化精准定位逻辑错误。5.3 一个实用的封装技巧创建自定义模块库你肯定不希望每次都用那个通用的、丑陋的S-Function模块然后手动填写名字和参数。我们可以把它封装成一个具有自定义图标和参数对话框的“专业”模块。创建封装子系统在模型中选中你测试好的S-Function模块。右键点击选择Create Mask - Create Mask。在弹出的封装编辑器中切换到Parameters Dialog页签。添加三个参数例如Gain,LowerLimit,UpperLimit设置好提示Prompt和变量名Name。切换到Icon Ports页签可以绘制一个简单的图标例如用disp(‘Gain\nwith\nLimits’)显示文字或用port_label函数标注端口。切换到Initialization页签关键的一步是建立封装参数与底层S函数参数的连接。在初始化命令中写入% 获取封装参数的值 gain str2num(get_param(gcb, Gain)); lower str2num(get_param(gcb, LowerLimit)); upper str2num(get_param(gcb, UpperLimit)); % 设置底层S-Function模块的参数 set_param([gcb /S-Function], DialogPrm1, num2str(gain)); set_param([gcb /S-Function], DialogPrm2, num2str(lower)); set_param([gcb /S-Function], DialogPrm3, num2str(upper));保存为库将这个封装好的子系统拖拽到一个新建的库文件.slx中保存。以后你就可以像使用标准库模块一样从自己的库里拖出这个美观、易用的“带限幅增益器”模块了完全隐藏了S函数的底层细节。6. S函数的典型应用场景与进阶方向掌握了S函数的基础后你可以在很多场景中大显身手实现复杂/非线性控制器比如滑模控制、模型预测控制(MPC)、模糊PID等。这些算法的逻辑用基本模块搭建非常繁琐用S函数封装成单个模块模型清晰也便于复用。集成外部代码或硬件驱动将已有的C/C算法库如滤波库、通信协议栈包装成S函数在Simulink中调用。或者编写与特定硬件如数据采集卡通信的S函数用于硬件在环(HIL)仿真。创建自定义信号源或接收器生成符合特定统计特性的随机信号或者编写将仿真数据实时写入数据库或文件的S函数。构建自定义的物理模型当Simulink物理建模库不能满足需求时可以用S函数直接实现一组微分/代数方程来描述自定义的物理组件。进阶学习方向深入研究C MEX S函数学习simstruc.h中更多的API处理多维信号、总线信号、枚举类型等复杂数据类型。学习编写TLCTarget Language Compiler文件这是控制Simulink Coder如何从你的C S函数生成代码的关键。通过TLC文件你可以优化生成代码的效率、结构和可读性使其满足产品级嵌入式的需求。探索Legacy Code Tool如果你有一大堆遗留的C代码不想手动重写为S函数可以使用这个工具。它帮你自动生成包裹遗留代码的S函数和TLC文件是集成旧代码的神器。从我个人的经验来看S函数是区分Simulink普通用户和高级用户的一道分水岭。它打破图形化建模的束缚带来了无限的灵活性。初学时会觉得有些复杂但一旦理解了其“回调函数”的本质并成功调试通过第一个模块后面就一马平川了。建议从M文件S函数入手多做几个小例子再挑战C S函数最终你会发现自己掌控了整个仿真世界。