Simulink C Caller模块详解：轻松集成外部C代码

如果你在 Simulink 里做过控制算法或信号处理，一定遇到过这个尴尬：模型搭得挺顺利，但核心算法却是以前用 C 写过的一整块。比如一个卡尔曼滤波、一段 Modbus CRC 校验、一个底层驱动函数。想在模型里用上这段代码，脑子里的第一反应往往是写 S-Function；翻资料又会看到 Legacy Code Tool；折腾一圈后发现，自己只是想把一个函数接进模型，却被迫理解了一堆 Simulink API。后来看到模块库里有一个 C Caller 模块，双击配置一下函数原型，就能把外部 C 函数“拉”进模型。但先别高兴太早，这个模块用起来比看起来更讲究。

C Caller 的真正价值，不是“能调用 C 函数”这个表面功能，而是它把“外部算法接入模型”这件事，从写适配器变成了配置接口。它让同一个 C 函数既可以参与仿真，又可以进入代码生成链路，而且整个过程比手写 S-Function 少掉大量模板代码。但要真正用好它，你得先理解函数声明、数据类型映射、仿真和代码生成之间的差异。这篇文章就按“为什么要用、怎么配置、怎么避开坑、什么情况别用它”的顺序展开。

1. 为什么不是又一个 S-Function：C Caller 的设计动机

1.1 在 C Caller 出现之前，调用外部 C 代码有多麻烦

在 Simulink 里复用 C 代码，过去有几条路，但每条路都有点重。

第一种是写 S-Function。你需要按固定流程实现回调函数，至少包括初始化、输出更新、结束清理。如果还要支持代码生成，那大概率要再写一份 TLC 文件，告诉代码生成器怎么把模块转成目标代码。这个门槛对算法工程师来说偏高。很多人想把一个滤波函数接进模型，结果一整天都耗在mdlOutputs的索引计算上。

第二种是用 Legacy Code Tool。它比手写 S-Function 友好，可以用legacy_code('initialize')定义接口，再自动生成对应的 S-Function 模块。但问题在配置过程太长：要写 legacy code spec 结构体，要运行初始化、生成代码、编译、加载模型。一两个函数还好，函数一多，这些脚本本身就成了要维护的东西。

第三种是在 MATLAB Function 块里用coder.ceval。这种方法适合代码量不大、只在代码生成时调用的情况。但如果你需要纯仿真环境也调用外部 C 代码，coder.ceval在 MATLAB Function 块里的行为需要额外处理，而且代码可读性会变差。

这几条路的共同问题是：外部 C 代码本身并不是模型的一部分，你需要为它再写一层适配层。适配层一旦多了，维护成本就盖过了复用带来的收益。

1.2 C Caller 做了什么：先给函数签名建一座桥

C Caller 模块的设计思路，是把“适配层”收窄到一个模块参数面板里。你只需要告诉 Simulink：函数叫什么、头文件在哪、源文件在哪、参数顺序和类型是什么。剩下的封装由模块自动完成。

从使用体验上说，它更像是在模型的 User-Defined Functions 库里面放了一个“标准接头”。你不需要写 mdL 回调，不需要编 TLC，不需要维护 legacy spec 脚本。只要函数签名能被正确解析，模块就能自动生成对应的输入输出端口。

这块比较适合的比喻是 USB 接口。以前你要把一个外部 C 函数接进 Simulink，相当于给设备做一个专用接口；现在 C Caller 相当于把接口标准化了，只要你的函数是“普通函数”，就能插上去。

不过要注意，它只标准化了“函数调用”这一层。函数内部是什么语言、依赖什么库、有没有全局状态，C Caller 并不过问。它更像一座桥，而不是一台翻译机。桥接不了的场景，后面会单独讲。

1.3 这个模块真正解决的问题：把单次调用变成可复用模块

我见过不少项目，为了调用一个 C 函数专门生成了一个 S-Function 模块，结果下一次要调用另一个函数时，又要重新生成。C Caller 避免了这种重复劳动。

它的核心变化在于：外部函数的“接入信息”变成了模块参数。函数原型、头文件路径、源文件路径、采样时间都随模型保存。如果你把一个 C Caller 模块封装成子系统，再加上 Mask 参数，别人拿到库之后只需要填函数名和路径，就能复用同一套模块。这个价值不是省几分钟，而是把“接入外部算法”从一次性工作变成了可复制、可扩展的流程。

但也要有个清醒的边界：C Caller 不是万能的。它解决的是“调用接口简单、以函数为粒度”的场景。如果外部代码需要访问 Simulink 的工作向量、事件、动态多实例状态，C Caller 就不够用了，那确实是 S-Function 的地盘。

2. 上手前先理解接口：函数声明、数据映射和最小流程

2.1 头文件与源文件：C Caller 怎么解析外部函数

C Caller 模块要正常工作，至少需要拿到两样东西：函数声明所在的头文件，以及函数实现所在的源文件。

头文件用来解析函数原型。模块从原型里读取函数名、参数类型、返回值类型，然后自动推断出模块端口。源文件则是在仿真或代码生成阶段参与编译链接。如果只有一个源文件，不带头文件，模块在解析时会缺少函数声明，往往报“function not found”。

在设计阶段，我建议把外部算法整理成“一个算法一个头文件、一个头文件对应一个源文件”的结构。头文件里只放这个函数的最小声明，不要贪多把系统里所有头文件都塞进来。比如：

/* extern_add.h */ #ifndef EXTERN_ADD_H #define EXTERN_ADD_H double extern_add(double a, double b); #endif

对应的源文件：

/* extern_add.c */ #include "extern_add.h" double extern_add(double a, double b) { return a + b; }

路径方面，尽量把外部 C 文件放进当前模型项目的某个子目录，用相对路径或通过 MATLAB 路径方式索引。不要长期依赖绝对路径，否则换一台电脑、换一个分支，模块就全部红了。

2.2 函数原型怎么写：返回值、参数和 const 的处理

C Caller 模块对函数原型的格式比较挑剔。常见要求是：函数原型要以分号结尾，参数要写明类型，最好与头文件里的声明完全一致。

如果函数的返回值不是void，模块通常会自动多出一个输出端口。返回值可以是double、float、整数类型等内置类型。比如double extern_add(double a, double b)会生成两个输入端口和一个输出端口。

如果函数返回值是void，但通过修改指针参数来输出结果，那么这些指针参数需要被声明为输出或输入输出类型。以double *out和const double *in为例，const关键字是重要的提示：const修饰的指针大概率是输入，非const指针很可能是输出或被修改。这会影响 Simulink 端口方向。

一个容易踩的细节是：C 语言里double *u可以由调用方决定是输入还是输出，但 C Caller 模块只看到原型，它无法猜出你的习惯。所以配置模块时，要主动指定每个参数的方向。实际项目中，尽量让函数签名写清楚：

• 输入用const double *u
• 输出用double *y
• 长度用int len作为普通输入参数

这样配置模块时，代码维护者和模块使用者都不需要读函数体。

2.3 数据类型映射：数组、指针与 Simulink 信号维度的对应

C Caller 最让人迷惑的地方，是 C 语言里的数组和指针到底对应 Simulink 的什么信号维度。

如果函数是double scale(double x)，那么映射关系很简单：Simulink 的一个双精度信号接到模块输入，模块输出一个双精度信号。

如果函数是void scale_array(const double *in, double *out, int len, double gain)，那么in和out会对应一个向量信号。len是标量信号，你可以从 Constant 模块给它一个固定值，也可以从上游计算。只要 Simulink 信号的数据类型和维度与函数参数一致，C Caller 就可以直接调用。

矩阵的情况要更小心。Simulink 中的矩阵默认按列优先存储。C 函数如果按行遍历，容易得到错误的结果。比如一个 3×4 矩阵在内存里会按第一列、第二列的顺序连续排列。C 代码如果习惯用for(row) for(column)访问，索引经常会错位。处理这类问题时，要么在 C 函数内部严格按列优先规则遍历，要么在 Simulink 端先把矩阵 reshap 成一个向量，再传入 C 函数。

数据类型方面，优先使用明确宽度的类型，例如int8_t、uint16_t、float、double。int、long这类类型在不同编译器和目标平台下宽度可能不同，容易在仿真通过、代码生成部署到别的平台后出问题。如果 C 代码由其他团队提供，而他们大量使用int，你在 Simulink 端就要特别注意目标平台的长度假设。

2.4 一个最小示例：加法函数接入模型

接下来做一个最小验证。先把上面的extern_add函数文件放到当前模型目录下。然后在 Simulink 模型画布里，从 User-Defined Functions 库拖一个 C Caller 模块进来。

双击模块，在参数面板里填入：

double extern_add(double a, double b);

指定头文件为extern_add.h，源文件为extern_add.c，点击加载或更新按钮。当模块端口刷新出来后，接上两个 Constant 输入和一个 Display，运行仿真。如果能正确输出两数之和，说明整个链路已经通了。

这个最小示例的价值不是“加法很简单”，而是验证你的编译环境、路径配置、模块配置这三点是否同时正常。很多复杂函数接入异常，最后都能回溯到这三点。

注意：不要一上来就把复杂的 C 函数塞进 C Caller。先用一个最简函数跑通，确认你的 C 编译器可用、文件路径可访问、模块能正常解析，再逐步替换成真实算法。

3. 从仿真跑到生成代码：中间隔着哪些雷

3.1 仿真和代码生成是两条路径

C Caller 在仿真和代码生成中的工作方式不一样。仿真时，Simulink 会利用本机编译器把外部 C 代码和包装代码一起编译成可执行文件或 MEX，然后在仿真循环里调用它。代码生成时，Simulink Coder 生成的是目标代码，C Caller 模块会在生成代码里保留对原始 C 函数的调用。真正把 C 源文件编译进最终产物，是在后续的构建步骤里完成的。

这就导致一个常见现象：模型仿真完全正常，但点击“Generate Code”或“Build”之后，突然报找不到头文件、找不到函数定义。原因往往是在仿真目标的 Custom Code 里配置了源文件，却忘了在 Code Generation 的 Custom Code 里配置同样的文件。

所以，把一个 C Caller 模块放进模型后，不要只检查模块参数。要同时检查模型配置参数里的两块：

• Simulation Target → Custom Code：负责仿真时编译外部代码。
• Code Generation → Custom Code：负责生成代码后的编译和链接。

如果外部 C 代码很简单，仿真配置会自动带上源文件；但代码生成配置通常需要显式添加。不同版本的具体路径和字段名可能有差异，第一次使用时要主动确认。

3.2 什么情况下 C Caller 能直接生成代码

C Caller 能不能直接用于代码生成，主要看外部函数是否满足几个条件：

• 函数本身是普通 C 函数，接口可以通过函数原型完整描述。
• 参数类型都是代码生成器支持的内置类型，比如double、float、整数类型和对应的指针。
• 外部源文件能够在目标平台上交叉编译，不依赖目标机上不存在的库。
• 函数内部没有使用动态内存申请、系统调用或 C++ 对象构造析构等行为。
• 模型配置的目标语言和外部代码语言匹配。如果生成代码是 C++，调用 C 函数通常没问题，但要在头文件里包好extern "C"；如果生成代码是 C，而外部函数是 C++，则需要中间包装层。

如果你需要在单片机或嵌入式目标上生成代码，C Caller 会更谨慎。因为嵌入式代码生成通常要求代码可重入、无动态内存、无文件系统依赖。C Caller 本身不会禁止这些，但它也不负责帮你修正外部函数里的问题。更多时候，你需要在外部 C 代码层面做改造。

3.3 C Caller、S-Function 与 Legacy Code Tool 怎么选

这个表格是我常用的选型判断表。一个函数到底用什么方案接入，先问三个问题：接口是不是简单 C 函数？是不是要代码生成？是不是需要访问 Simulink 运行状态？如果第一个和第二个是，第三个否，C Caller 往往是性价比最高的选择。

3.4 代码生成时的自定义代码配置

假设你的函数要进入代码生成流程，除了在 C Caller 模块里填写头文件和源文件，通常还要在模型配置里明确外部代码的编译方式。

常见的配置点包括：

• 附加头文件目录：告诉代码生成器去哪里找.h文件。
• 附加源文件列表：把.c文件加入最终构建。
• 预处理宏：如果外部代码需要编译开关，可以在这里定义。
• 库路径和链接选项：如果函数依赖第三方静态库或动态库，需要额外配置。

在实际项目中，我见过有人在模块参数里填了绝对路径，结果代码生成时构建服务器上路径不一样，于是整个 Jenkins 任务失败。后来改成项目相对路径，问题才消失。如果你也在做 CI 构建，最好规定所有外部 C 代码都必须放在模型项目目录下，并使用统一目录结构。这样模块配置可以随着代码库一起迁移。

4. 最容易踩的坑和一套排查顺序

4.1 函数解析失败：先查路径和头文件

C Caller 最常见的报错是“无法解析函数原型”。遇到这种问题，不要先怀疑模块，先检查几个基本点：

• 头文件名和源文件名是否拼写正确。
• 文件是否在当前 MATLAB 路径或模型所在工程目录里。
• 头文件是否依赖其他头文件，而依赖项没有被找到。
• 函数原型是否和头文件中的声明完全一致，包括参数类型、常量限定符和分号。
• 头文件里是否有条件编译，导致你想要的函数声明没有被编译进去。
• 如果外部代码是 C++ 编写的，C Caller 不一定能直接解析extern "C"块里的声明。建议先把接口改成 C 风格，或用一个独立的 C 头文件包装。

我的一般做法是：先在 MATLAB 命令行里用which extern_add.h确认这个文件能被找到。如果which返回空，说明路径设置有问题，这比在模块参数面板里反复改配置更高效。

在排查 C Caller 问题时，先确认路径和文件可访问，再检查参数配置。不要反复点 Load 按钮，那只是在重复同一个错误。

4.2 数据类型不匹配：指针、维度、定点数

很多时候函数解析成功，模块端口也生成出来了，但仿真结果不对，或者直接报“Port width mismatch”。问题往往不在 C Caller 模块，而在数据映射。

一个典型场景是 C 函数期望double *指向一个长度为 N 的数组，但 Simulink 端口接的是标量或维度不一致的信号。C Caller 模块不会帮你自动扩展维度，它只是按模块里配置的参数方向生成端口。所以在接线时，要确认信号的宽度、数据类型和 C 函数签名完全对齐。

还要注意定点数。Simulink 模型里很多信号是fixdt类型，但 C 函数一般不是fixdt原生的。C Caller 模块对定点类型的支持没有普通信号那么直接。如果确实要把定点信号传给 C 函数，通常需要先转成single或double，在 C 函数里计算完再转回去。这样可以避免定点缩放位问题，但代价是损失一点效率。

4.3 全局状态与多次实例化

C 函数里如果有static变量或全局变量，使用 C Caller 时要特别留意。Simulink 模型里可以同时存在多个 C Caller 模块，甚至同一个模块可以放在不同子系统中，运行时被多次调用。如果这些调用都指向同一个 C 函数，那么全局状态会在不同模块实例之间共享。

对于一些算法来说，这可能是你想要的，比如全局唯一的共享计数器；但对大多数算法来说，这是不希望发生的。因为同一算法模块被复制多份后，每一份都应该有独立状态，而不是共享同一组静态变量。

如果算法本身有记忆状态，最简单的方式是把状态作为函数参数传入和传出，比如：

void filter_step(const double in, double *out, FilterState *state);

这样 C 函数就是纯函数，C Caller 也能正常处理。如果状态复杂、数量多，用 S-Function 管理工作向量通常更合适。

4.4 链接错误：源文件没有进入构建

仿真时报undefined reference to extern_add，代码生成时报同样的链接错误，多半是源文件没有进入对应路径。

在仿真阶段，你需要看 Simulation Target 的 Custom Code 是否包含了源文件。在代码生成阶段，你需要看 Code Generation 的 Custom Code 是否包含了源文件。如果函数依赖第三方库，还要把库路径和链接选项都配进去。

我把这看作“两层配置”问题。很多人只配置了模块参数里的源文件路径，以为万事大吉，结果另一个构建流程里源文件根本没参与编译。可以先做一个实验：在 MATLAB 命令行里手动调用一下外部 C 函数的编译入口，或者用codegen做一次最小生成，看看是不是只有 C Caller 模块会失败。这样能快速区分是模块配置问题，还是外部代码本身的问题。

4.5 一套从现象到边界的排查链路

把常见问题整理成一套顺序，可以在遇到 C Caller 异常时避免乱试。

1. 先看现象：是模块图标变红，还是仿真报错，还是代码生成失败？这决定下一步要查哪条路径。
2. 再看输入：检查信号的数据类型和维度。用 Display 模块看端口值，用 Signal Attributes 模块看宽度。
3. 再看环境：确认 C 编译器可用；确认 MATLAB 路径中包含头文件目录；确认工作目录可写；确认构建服务器上路径一致。
4. 再看参数：核对函数原型字符串、头文件名、源文件名、参数方向、采样时间。
5. 最后看工具边界：检查函数是否涉及 C++、动态内存、全局状态、第三方库依赖；如果涉及，就要考虑换用 S-Function 或 Legacy Code Tool。

这套顺序的核心思想是：先排除最简单的路径问题，再查数据问题，最后再判断是不是工具边界问题。

5. 适用边界与长期用法：不是所有外部代码都该用 C Caller

5.1 适合用 C Caller 的场景

从工程经验看，下面几类场景优先考虑 C Caller：

• 算法函数已经稳定，函数签名清晰，输入输出都是基本数值类型。
• 需要把现有 C 代码嵌入 Simulink 做闭环仿真，并且后续要生成代码。
• 项目里存在大量短小 C 函数，如果每个都手写 S-Function，维护成本太高。
• 在硬件在环或处理器在环部署时，需要调用底层驱动库或工具库的 C 接口。

比如一个无刷直流电机控制项目里，已经有了 FOC 算法和 SVPWM 生成函数，直接用 C Caller 把void foc_control(const MotorState *state, ControlOutput *out)接进模型，模型里重点做逻辑调度，控制算法留给 C 代码，这种分工比较舒服。

5.2 不建议用 C Caller 的场景

遇到这些情况，就不要再硬套 C Caller 了：

• 外部代码是 C++ 类，需要构造、析构和继承关系。
• 函数内部依赖大量平台库，需要专门配置很多链接选项。
• 需要在 Simulink 仿真中访问运行状态、零阶保持、连续状态或代数环信息。
• 希望同一个 C 函数在不同模块实例中有独立状态，而函数本身又无法改造成无状态形式。
• 需要处理结构体数组、嵌套结构体，并且希望 Simulink Bus 和 C 结构体自动映射。

这些场景下，C Caller 会把你推进一个“配置越来越黑盒”的困境。到头来，你既没有享受到 S-Function 的灵活性，又要处理 C Caller 的接口限制。不如一开始就选 Legacy Code Tool 或手写 S-Function。

5.3 把 C Caller 封装成自己的模块库

单个 C Caller 模块只是把一个函数接进模型。真正能在团队里沉淀价值的，是把这个模块封装成一个模板。

我的做法是建一个自定义模块库，在库里放一个 C Caller 模块作为“算法接入模板”。这个模块被打包到子系统里，子系统的端口按输入、输出、参数三类统一规范。然后给这个子系统建立一个 Mask，Mask 参数包含函数原型、头文件、源文件路径、采样时间。其他工程师使用时，只需要填写这几个参数，不需要理解 C Caller 内部要加载哪些文件。

这个封装的本质，是把 C Caller 的配置信息提升到“算法接口描述”层面。以后新增外部函数时，不需要新拖一个裸 C Caller 模块，而是复制这套模板，填新的函数签名和文件路径。久而久之，项目里的 C 算法接入方式会越来越一致。

5.4 工程化建议：可测试、可维护

最后给几条长期维护层面的建议。

第一，对外部 C 代码做单元测试。不要只依赖 Simulink 模型测试。因为 C Caller 只负责调用，不负责验证函数本身。函数里的越界、逻辑错误，会在 Simulink 仿真中暴露，但那时定位问题会慢。建议用 CTest 或其他框架对 C 函数做独立测试。

第二，把 C 文件纳入版本管理。头文件、源文件和模型放在同一个工程目录下，使用相对路径。不要出现“我这台机器跑得好好的，你那边全是红”的问题。

第三，在项目里固定一个“接入检查单”。每次新接入一个外部函数，走一遍：最小函数验证、仿真验证、代码生成验证、目标板验证。不要跳过其中任何一步。很多人只做仿真验证，结果代码生成时才发现头文件路径配置漏了。

第四，对函数接口的变化保持敏感。如果 C 函数签名改了，C Caller 模块不会自动感知，你需要手动更新模块参数。如果函数头文件被外部团队频繁修改，最好在模型的工程文档里记录版本号。

把 C Caller 用成“万能钥匙”是不现实的。它更合适被看作一条合规、直接的调用通道。真正的工程能力，体现在你能否把外部 C 代码整理成清晰的接口，让 Simulink 模型、生成代码和原始算法之间保持一致的边界。下一次你准备把一个 C 函数往模型里拖的时候，先问自己一句：这个函数是不是足够干净，能不能把接口描述清楚。如果答案是肯定的，C Caller 会让你省下大量重复劳动；如果答案是否定的，那说明问题不在工具，而在接口设计。