Simulink与C/C++联合开发：结构体变量导入完整实践指南

做Simulink与C/C++联合的人，迟早都会撞上一面墙：标量、数组怎么传都没问题，一旦轮到自定义结构体，立刻各种奇奇怪怪的幺蛾子。我记得第一次在Simulink里导入一个带位域和#pragma pack的CAN协议结构体时，读出来的速度值始终对不上，偏移量整整差了4字节，排查了大半天才意识到是结构体对齐在作怪。这篇文章把我长期实战中处理“结构体变量导入”的完整路径、代码模板和踩坑记录整理出来，覆盖从C头文件生成Bus对象、S-Function参数解析、嵌套结构体展开到外部模式联调，希望给正在做车辆控制器、机器人或嵌入式算法仿真的朋友一些参考。

1. 结构体导入的几条主流路径，以及我为什么最终选S-Function

1.1 四条路线速览

Simulink与C/C++的对接，常见的路数其实就四条，但每条路的适用场景差异很大，选错了后面全是坑。

第一条是MATLAB Function模块。在MATLAB Function里面用coder.extrinsic或者直接写struct操作，优点是上手快，适合原型验证，但缺点也明显：一是运行效率不如原生C，二是结构体字段多、类型复杂时，代码生成出来的中间变量非常啰嗦，很不好查。

第二条是C MEX S-Function。用C写一个符合Simulink S-Function API的模块，把自定义结构体当作对话框参数传进去，或者在端口数据类型里挂Bus。这是我这篇文章的主战场，后面会详细展开。它的核心优势是：结构体在C侧就是真实的内存布局，直接读写字段，效率高、可控性强，而且可以把整套参数校验放在mdlCheckParameters里做，非常顺手。

第三条是C Caller模块。Simulink 2018b之后提供了C Caller，可以直接调用C头文件里声明的函数，结构体可以以cPtr类型或者Bus类型作为函数入参。优点是不需要手写S-Function样板代码，缺点是要求函数接口非常干净，结构体字段一复杂，配置起来也够折腾。

第四条是通过Embedded Coder做代码生成。在模型配置里把自定义结构体映射到生成的C代码结构体，更多是“导出”而非“导入”的视角。但实际做联合开发时，原始C代码里的结构体类型能不能在生成的代码里被复用，往往取决于Bus对象的定义是否和C头文件一致，所以这条路径和前面的Bus对象也绕不开。

1.2 选型逻辑：什么时候选哪条路

我这几年做VCU和机器人控制器仿真，得出的选择规律大致是这样：

场景	推荐路线	理由
快速原型、不追求性能	MATLAB Function	开发快，字段访问直观
已有大量C算法代码、参数以结构体传入	C MEX S-Function	结构体指针直读，性能好，代码复用率高
函数接口明确、参数体量大但结构简单	C Caller	少写S-Function，配置相对简单
模型最终要生成产品级C代码	Embedded Coder + Bus对象	类型映射可控，头和源文件可指定

我自己的项目里，算法模块基本都用C MEX S-Function。原因很朴素：结构体在C侧就是一块连续内存，我可以用memcpy、可以直接取字段地址传给底层函数，这个自由度是MATLAB Function给不了的。

1.3 一个容易忽略的前提：Bus对象是结构体的“身份证”

不管走哪条路，进入Simulink之前，C结构体都得先对应到一个Simulink.Bus对象。你可以把它理解为结构体的“身份证”——Simulink靠它识别字段名、字段类型、维度，以及它在模型里能不能被Bus Selector拆开。

很多人在这里犯的第一个错误，是直接在Constant模块里填一个MATLAB结构体，信号线一拖出来就发现没有字段可以选。原因是MATLAB工作区里的普通结构体和Bus对象是两回事。想要在信号线上传递自定义结构体，必须先把它变成Bus对象，然后通过Bus Creator或者S-Function的端口类型挂上去。

2. 从C头文件到Simulink.Bus：结构体变量导入的主干路径

2.1 以头文件为单一事实来源，定义参数与输出结构体

工程上最推荐的起点，不是打开MATLAB敲BusElement，而是先在C头文件里把结构体定义好。因为你的底层算法、标定工具、编译环境都认这份头文件，它是“单一事实来源”。Simulink那边只是它的一个镜像。

举个实际例子，假设我在做一套车辆速度估计模块，需要传一个参数结构体和一个输出结构体：

#ifndef SPEED_PARAMS_H #define SPEED_PARAMS_H #include <stdint.h> #ifdef __cplusplus extern "C" { #endif typedef struct { double wheelRadius_m; /* 车轮半径，单位m */ double filterAlpha; /* 一阶低通滤波系数 0~1 */ int32_t sensorCount; /* 参与融合的传感器数量 */ uint8_t enableFlag; /* 使能标志 */ } SpeedParams; typedef struct { double speed_kmh; /* 估计车速 */ double conf_level; /* 置信度 0~1 */ uint8_t valid; /* 结果有效标志 */ } SpeedOutput; #ifdef __cplusplus } #endif #endif

结构体的字段命名和类型都必须想清楚，因为后面Bus对象会完全照搬这套定义。double、int32_t、uint8_t这些类型，Simulink里都有一一对应的数据类型字符串，这个映射关系后面踩坑部分还会细说。

2.2 用 importExternalCTypes 一键生成Bus对象

如果头文件里没有位域、没有编译器专有的预处理宏，最省事的方式就是直接用importExternalCTypes。这个函数会自动扫描你指定的C头文件，把里面的结构体、枚举转换成当前工作区里的Bus对象：

% 确保 speed_params.h 在 MATLAB 路径下 Simulink.importExternalCTypes('speed_params.h');

运行完之后，工作区会多出两个Bus对象：SpeedParams和SpeedOutput。打开Bus对象看，Elements里已经包含了每个字段的名称、数据类型、维度信息，HeaderFile属性也会自动填上speed_params.h。

这个函数的价值在于：它保证Simulink侧的数据类型映射和C编译器保持一致。你不需要手动去核对字段顺序、字节宽度，字段的偏移量完全由导入结果决定，后面S-Function去读的时候，只要两边用的是同一份头文件，内存布局天然对齐。

2.3 位域和pack结构体：为什么自动导入有时会失败

但是自动导入不是万能的。我踩过最深的一个坑，就是通信协议里的位域结构体。比如CAN报文解析常用的：

#pragma pack(push,1) typedef struct { uint8_t msgId; uint32_t timestamp; uint16_t counter; uint8_t flags[4]; } CanFrame; #pragma pack(pop)

这种带#pragma pack的结构体，importExternalCTypes能处理一部分，但一旦结构体里出现位域（bit-field），比如：

typedef struct { uint16_t id : 11; uint16_t dlc : 4; uint16_t rtr : 1; } CanHeader;

importExternalCTypes基本就抓瞎了，要么跳过位域字段，要么直接报错。这个我没有找到特别优雅的自动化解法，项目里的做法是：位域结构体不导入Simulink，在C MEX S-Function里用位运算手动解析。Simulink侧只保留解析完之后的结果字段，比如msgId、timestamp、counter这些干净的类型。

2.4 嵌套结构体与数组维度的手写Bus展开规则

如果不想依赖自动导入，或者必须绕开某些C预处理语法，那就得手写Bus。嵌套结构体展开的时候，最核心的一条规则是：每个C结构体对应一个Bus对象，字段的数据类型填另一个Bus对象的名字，要加Bus:前缀。

比如C侧有这样的嵌套结构体：

typedef struct { double kp; double ki; } PidGain; typedef struct { PidGain steer; PidGain speed; uint8_t enable; } VehicleControllerParams;

对应的MATLAB脚本：

% 创建 PidGain Bus pidElems = Simulink.BusElement.empty(0, 2); pidElems(1) = Simulink.BusElement; pidElems(1).Name = 'kp'; pidElems(1).DataType = 'double'; pidElems(1).Dimensions = 1; pidElems(2) = Simulink.BusElement; pidElems(2).Name = 'ki'; pidElems(2).DataType = 'double'; pidElems(2).Dimensions = 1; PidGain = Simulink.Bus; PidGain.Elements = pidElems; % 创建 VehicleControllerParams Bus vehElems = Simulink.BusElement.empty(0, 3); vehElems(1) = Simulink.BusElement; vehElems(1).Name = 'steer'; vehElems(1).DataType = 'Bus: PidGain'; vehElems(1).Dimensions = 1; vehElems(2) = Simulink.BusElement; vehElems(2).Name = 'speed'; vehElems(2).DataType = 'Bus: PidGain'; vehElems(2).Dimensions = 1; vehElems(3) = Simulink.BusElement; vehElems(3).Name = 'enable'; vehElems(3).DataType = 'uint8'; vehElems(3).Dimensions = 1; VehicleControllerParams = Simulink.Bus; VehicleControllerParams.Elements = vehElems;

数组字段也类似，C里如果写的是double x[4]，对应BusElement的Dimensions设置成[1 4]即可。这个“嵌套Bus对象”的语义在信号线上是逐级展开的，Bus Selector能一层一层往下选字段，用起来非常自然。

3. C MEX S-Function 中读写结构体：一份可直接改的完整模板

3.1 S-Function 框架设计与参数解析时机

结构体导入Simulink之后，真正高频用到的场景还是在S-Function里读参数结构体，然后做算法计算。我建议把结构体参数放在S-Function的P0参数对话框里，这样模型里每一份模块实例都可以独立配置，仿真和生成代码都能复用。

解析结构体参数的时机很关键。最干净的做法是在mdlStart阶段把参数结构体从mxArray里解出来，拷贝到模块内部的静态结构体全局变量中，后续计算直接访问这个全局变量。mdlCheckParameters只做校验，不做赋值，避免参数非法时带病运行。

3.2 完整代码：s_vehicle_speed

下面是一个可以直接改的速度估计示例，包含两个输出端口：一个double类型的估算车速，一个uint8_t类型的结果有效标志：

#define S_FUNCTION_NAME s_vehicle_speed #define S_FUNCTION_LEVEL 2 #include "simstruc.h" #include "speed_params.h" static SpeedParams g_params; /* 参数校验 */ #define MDL_CHECK_PARAMETERS #if defined(MDL_CHECK_PARAMETERS) static void mdlCheckParameters(SimStruct *S) { const mxArray *prm = ssGetSFcnParam(S, 0); if (prm == NULL || mxIsEmpty(prm)) { ssSetErrorStatus(S, "参数结构体不能为空"); return; } /* 可按需要继续校验每个字段的范围，比如 wheelRadius_m > 0 */ } #endif /* 从 mxArray 结构体参数解析出 C 结构体 */ static void parseParams(SimStruct *S) { const mxArray *prm = ssGetSFcnParam(S, 0); mxArray *f = NULL; if (prm == NULL || mxIsEmpty(prm)) return; f = mxGetField(prm, 0, "wheelRadius_m"); if (f != NULL) g_params.wheelRadius_m = mxGetScalar(f); f = mxGetField(prm, 0, "filterAlpha"); if (f != NULL) g_params.filterAlpha = mxGetScalar(f); f = mxGetField(prm, 0, "sensorCount"); if (f != NULL) g_params.sensorCount = (int32_T)mxGetScalar(f); f = mxGetField(prm, 0, "enableFlag"); if (f != NULL) g_params.enableFlag = (uint8_T)mxGetScalar(f); } static void mdlInitializeSizes(SimStruct *S) { if (!ssSetNumSFcnParams(S, 1)) return; ssSetSFcnParamTunable(S, 0, SS_PRM_SIM_ONLY_TUNABLE); ssSetNumContStates(S, 0); ssSetNumDiscStates(S, 0); ssSetNumInputPorts(S, 0); ssSetNumOutputPorts(S, 2); if (!ssSetOutputPortWidth(S, 0, 1)) return; if (!ssSetOutputPortDataType(S, 0, SS_DOUBLE)) return; if (!ssSetOutputPortWidth(S, 1, 1)) return; if (!ssSetOutputPortDataType(S, 1, SS_UINT8)) return; ssSetNumSampleTimes(S, 1); ssSetNumRWork(S, 1); /* 保存上一次的滤波输出 */ ssSetNumPWork(S, 0); ssSetNumIWork(S, 0); ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE | SS_OPTION_RUNTIME_IO); } #define MDL_START #if defined(MDL_START) static void mdlStart(SimStruct *S) { parseParams(S); } #endif static void mdlInitializeSampleTimes(SimStruct *S) { ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME); ssSetOffsetTime(S, 0, 0.0); } static void mdlOutputs(SimStruct *S, int_T tid) { real_T *ySpeed = ssGetOutputPortRealSignal(S, 0); uint8_T *yValid = ssGetOutputPortUint8Signal(S, 1); real_T pi = 3.14159265358979; real_T rawSpeed; real_T lastOutput = ssGetRWorkValue(S, 0); real_T filteredSpeed; if (!g_params.enableFlag || g_params.sensorCount <= 0) { ySpeed[0] = 0.0; yValid[0] = 0; return; } /* 模拟：假设当前电机转速为 30 rad/s */ rawSpeed = 30.0 * g_params.wheelRadius_m; /* 一阶低通滤波 */ filteredSpeed = lastOutput + g_params.filterAlpha * (rawSpeed - lastOutput); ySpeed[0] = filteredSpeed; yValid[0] = 1; ssSetRWorkValue(S, 0, filteredSpeed); } static void mdlTerminate(SimStruct *S) { /* 无动态内存，无需清理 */ } #include "simulink.c"

几个细节值得说明：

ssGetOutputPortUint8Signal这个宏要求输出端口的数据类型必须设置成SS_UINT8，否则取指针的类型对不上。参数结构体里的filterAlpha用于一阶低通滤波，sensorCount做分母前必须判断是否大于0，这种防御性检查在控制器代码里非常重要，模型仿真时可能没感觉，一旦烧到目标机，除零就是死机。

3.3 在Simulink里搭一个最小验证模型

代码写好之后，先用mex s_vehicle_speed.c speed_params.c编译（如果头文件里没有单独源文件，直接mex s_vehicle_speed.c），然后把S-Function模块拖到Simulink模型里。

在S-Function模块参数对话框中，P0参数填一个结构体变量名，比如speedParams。这个变量需要在工作区里定义成Bus对象对应的结构体格式，最方便的做法是用前面生成的SpeedParamsBus对象配合Simulink.Bus.createMATLABStruct：

speedParams = Simulink.Bus.createMATLABStruct('SpeedParams'); speedParams.wheelRadius_m = 0.3; speedParams.filterAlpha = 0.8; speedParams.sensorCount = 4; speedParams.enableFlag = 1;

运行模型后，把第二个输出端口的valid信号接到Display，第一个接Scope。如果一切正常，速度输出应该是一个平滑上升并稳定的曲线，valid恒为1。把enableFlag改成0再跑一遍，输出立刻归零，说明结构体解析和算法逻辑都工作正常。

3.4 参数结构体的可调性：调不动的根源

很多人在S-Function里传结构体参数后，发现仿真过程中改参数值，模型输出纹丝不动。原因多半是参数被设成了不可调。

ssSetSFcnParamNotTunable(S, 0)会让参数在仿真启动后锁定，外部模式也没法调。如果需要在外部模式里在线调参，要用ssSetSFcnParamTunable(S, 0, SS_PRM_SIM_ONLY_TUNABLE)。但别忘了，parseParams只在mdlStart里执行了一次，即使参数可调，模型也不会重新解析。完整方案是在mdlProcessParameters回调里再调用一次parseParams，并在mdlInitializeSizes里加上ssSetOptions(S, SS_OPTION_WORKS_WITH_CODE_REUSE | SS_OPTION_ASYNC_RATE)之类的配置。这块稍麻烦，但做标定时非常关键。

4. 参数结构体的另外两种玩法：数据字典、C Caller指针直传

4.1 通过数据字典/Model Workspace定义结构体参数

除了在S-Function对话框里手填结构体变量名，产品级开发更推荐通过数据字典来管理结构体参数。在Model Explorer里把结构体参数定义成Simulink.Parameter，数据类型选Bus: SpeedParams，值保持为对应的MATLAB结构体即可。

这样做的最大好处是：参数和Bus定义一起进入数据字典，多人协同、版本管理、标定量导出都方便，而且模型里任何模块引用同一个参数名，调参时不会出现“各调各的”混乱。

用S-Function连数据字典里的结构体参数时，对话框填的仍然是参数对象名，但解析逻辑不变。仿真时如果发现参数读数不对，先看是不是数据字典里参数对象的StorageClass指定成了Define/Imported，那会影响生成代码阶段的使用，仿真阶段一般无碍。

4.2 C Caller 以指针方式直传结构体

如果你的C函数接口长这样：

int32_t VehicleSpeed_Update(SpeedParams *params, SpeedOutput *out);

那么用C Caller模块会更省事。在C Caller里配置函数原型时，SpeedParams *和SpeedOutput *对应Simulink端的两个Bus对象类型的端口。连线时，输入端口需要提供SpeedParams结构体信号，可以用Bus Creator把多个标量信号打包成SpeedParams；输出端口则直接拉出SpeedOutput，用Bus Selector拆字段。

这里有个技术细节：C Caller会为每个结构体指针参数生成一个内部端口，端口数据类型就是Bus。仿真时Simulink负责把Bus信号组织成连续内存，函数调用时传的是指向这块内存的指针。正因为这个特性，结构体字段顺序和字节对齐必须和C头文件完全一致，否则函数内部读到的就是错位的值。这和前面S-Function场景下的对齐问题其实是同一个根源，只是C Caller把内存管理的复杂度藏起来了。

4.3 嵌套字段的展开扫描

多层嵌套结构体在实际工程里非常常见。比如一个“车辆控制器参数”大结构体里，包了“转向PID”和“速度PID”两个子结构体。如果你用S-Function的mxGetField去解析，需要逐层往下取：

mxArray *pidField = mxGetField(prm, 0, "steer"); mxArray *kpField = mxGetField(pidField, 0, "kp"); g_params.steer.kp = mxGetScalar(kpField);

嵌套层级越深，代码越啰嗦。但使用C Caller时不需要做这些解析，函数入参直接就是指向完整嵌套结构体的指针，编译器自动处理偏移。这也是我建议“能用C Caller就不手写解析”的原因。不过C Caller对函数原型的要求比较严，入参必须是明确的指针或值类型，不能有变参、回调函数这种“高级”语法。

5. 实测踩坑记录：对齐、端序、类型不匹配的完整排查链路

5.1 现象：读取结果整体偏移4字节

有次做一个底盘控制器跨平台移植，C代码里结构体定义和头文件都一样，Simulink仿真一切正常，但同一个S-Function编译到嵌入式Linux目标机上后，读出来的sensorCount经常是乱值，而且所有字段都像是“串位”了。

第一个反映是怀疑目标机端序问题，但实际上去查发现目标机和宿主机都是小端。真正的原因在结构体对齐：宿主机编译器默认#pragma pack(8)，目标机编译器因为某些历史头文件，把默认对齐改成了#pragma pack(4)。两边sizeof(SpeedParams)算出来不一样，Bus对象按宿主机偏移量排好的内存布局，在目标机上对不上。

5.2 根因：pack带来的布局差异

#pragma pack这类指令在通信协议解析中实在太常见。但它直接改变结构体内存布局，而Simulink.Bus对象本身没有任何表达打包对齐的属性。你导入Bus时，它隐含假设的就是“当前编译器和MATLAB所在平台的默认对齐方式”。

排查的时候，我写了一个小的offsetof测试程序，把结构体每个字段的偏移量打印出来，和Simulink里Simulink.Bus对象每个元素的Dimensions、DataType、SampleTime这些属性逐项对比，才发现字段偏移全部错位了。

这类问题最稳妥的解法是：让Bus对象和C结构体始终在同一语义下定义。项目里给协议结构体单独建头文件，里面不写任何#pragma pack，需要解析的报文用专门的字节流解析函数处理，而不是靠memcpy硬灌。这样Simulink端保持一致，目标机端也保持一致。

5.3 端序问题什么时候才会真正出现

很多人一碰结构体跨平台就怀疑端序，但说实话，Simulink和C MEX代码运行在同一个进程里，内存是共享的，端序天然一致，几乎不可能因为端序导致结构体字段读错。

真正会出现端序问题的地方，是结构体被序列化成字节流传输或存储时。例如把SpeedParams用fwrite写进二进制文件，或者通过Socket发给另一台大端机器，接收端再用memcpy还原成结构体，这时才会出现字节序不匹配。解决方案很简单：传输层统一用明确的大小端字节序函数做一线转换，绝不直接memcpy结构体。

在Simulink侧，如果你用MATLAB Function去解析一个字节流缓冲区，也记得用uint8数组做移位拼接，而不是把字节流强转成结构体：

val = uint32(buf(i+3)) * 2^24 + uint32(buf(i+2)) * 2^16 + ...

5.4 一套可复用的逐层核对法

结构体字段错乱的问题，排查思路其实非常有套路。我现在的习惯是这样的：

1. 先用Simulink.importExternalCTypes重新生成Bus对象，覆盖手动定义，排除手动定义字段顺序错误。
2. 在S-Function的mdlStart里加一段临时mexPrintf，打印sizeof(SpeedParams)以及offsetof每个字段的偏移量。
3. 在Simulink端通过Bus Selector获取某个字段的实际仿真值，和C侧打印的偏移量进行交叉验证。
4. 如果字段偏移和Bus定义不一致，优先怀疑#pragma pack、编译器默认对齐、或者C头文件实际被预处理宏改了定义。
5. 确认这两块都没问题后，再看字节序，但90%的情况到这一步就已经定位了。

这套方法我用了很多次，基本每条都能在半小时内定位问题，比瞎猜强太多。

6. 外部模式联调与代码生成：让结构体真正跑进目标工程

6.1 外部模式：在Simulink里实时调结构体参数

做了这么多结构体导入，最终目标一定是联调。Simulink的外部模式（External Mode）是我强烈推荐先掌握的功能。它能把你编译好的C MEX S-Function模型下载到目标机（或者本机），然后在Simulink界面里实时调整参数。

当年我用外部模式标定速度估计模块时，直接在Simulink里改speedParams.filterAlpha，曲线立刻响应，根本不需要反复重新编译。前提就是前面3.4节说的，参数必须设成可调，并且mdlProcessParameters里要做重新解析。

有一点要注意：外部模式下，S-Function里的mexPrintf不会显示在Simulink界面上，而是输出到目标机的控制台（本机联调时是MATLAB命令行）。调试结构体内容时，这个输出非常有用，但正式跑数据前记得删掉。

6.2 生成C代码后，如何确认结构体映射正确

如果是产品级交付，最终还得用Embedded Coder生成C代码。生成完代码后，第一时间不是直接拿去做集成，而是打开代码生成报告，查看model_initialize()函数里的结构体参数初始化段落。

我见过不止一次，Simulink端结构体字段明明是对的，生成代码里的赋值顺序却和C头文件定义不一致，导致集成时调用算法函数传入的实参全是错的。排查方法很简单：在代码生成报告里搜结构体类型名，对比字段顺序和头文件定义。如果只差几个字段顺序，基本可以确定是Bus对象的Elements顺序和C结构体定义不一致，重新导入头文件能解决。

6.3 VS Code 配置 C/C++ 环境看生成代码

生成代码和原始C算法代码混在一起之后，没有个好用的代码阅读环境效率会非常低。我习惯用VS Code配合C/C++扩展来看代码，智能提示、跳转、搜索都顺手。

关键配置是c_cpp_properties.json，把生成代码根目录、原始算法头文件目录、Simulink安装目录下的simulink/include和rtw/c/src都加进includePath：

{ "version": 4, "configurations": [ { "name": "SimulinkGenerated", "includePath": [ "${workspaceFolder}", "${workspaceFolder}/slprj/_sharedutils", "/path/to/matlab/simulink/include", "/path/to/matlab/rtw/c/src" ], "defines": [], "compilerPath": "/usr/bin/gcc", "cStandard": "c11", "intelliSenseMode": "gcc-x64" } ] }

配置好之后，在生成代码里跳转到结构体定义、查字段引用都很快，排查类型映射问题效率翻倍。VS Code的C/C++插件偶尔会有智能提示路径优先级不准的问题，我通常在.vscode/c_cpp_properties.json里把最常用的头文件目录放在最前面，基本能缓解。

6.4 最后一点个人体会

从最早在Simulink里硬塞结构体被报错，到现在能顺畅地在C、Bus、数据字典、生成代码之间来回切换，我最深的体会是：结构体导入这件事，80%的工作量发生在“定义”和“一致性检查”上，而不是“导入”本身。只要坚持头文件作为单一事实来源，让Bus对象跟着头文件走，维护一份完整的字段映射表，Simulink与C/C++之间的结构体交互完全可以做到平滑顺手。希望这份实践指南能帮你少踩几个我当年踩过的坑。