📚 课程目录第4章主站代码框架解析

4. 主站代码框架解析

4.1 为什么先读框架，再读代码

EtherCAT主站代码动辄数万行，直接逐行阅读极易迷失。正确路径是：先建立“目录—模块—流程”三层地图，再带着问题深入具体函数。本章以两个最主流的开源主站——SOEM（Simple Open EtherCAT Master，侧重于轻量嵌入式）和IgH（EtherLab IgH Master，侧重于Linux内核/实时性）——为对象，剖析它们的目录结构、核心模块划分以及一次典型周期通信的工作流程。

核心结论先行：SOEM采用“用户态库+网卡驱动”的扁平架构，适合MCU和RTOS；IgH采用“内核模块+应用接口”的分层架构，适合Linux强实时场景。理解二者差异，是选型和二次开发的基础。

4.2 SOEM 目录结构与核心模块

SOEM 的源码结构非常紧凑，所有 EtherCAT 协议栈代码集中在 soem/ 目录下，上层应用只需包含 ethercat.h 并链接 libsoem 即可。其核心文件与职责如下表：

文件/目录	职责	关键函数
`nicdrv.c`	底层以太网帧收发，封装了 raw socket 或 pcap	`ec_setupnic()`, `ec_send_processdata()`
`ethercatmain.c`	主站初始化、从站扫描、状态机切换	`ec_init()`, `ec_config()`, `ec_statechange()`
`ethercatcoe.c`	CoE 协议：SDO 上传/下载、PDO 映射	`ec_SDOread()`, `ec_SDOwrite()`
`ethercatdc.c`	分布式时钟同步，计算时钟偏移与传播延迟	`ec_configdc()`, `ec_dcsync0()`
`ethercatconfig.c`	从站配置、FMMU/SM 通道分配	`ec_config_map()`, `ec_mapping()`
`osal/`	操作系统抽象层（定时器、线程、互斥锁）	`osal_timer()`, `osal_thread()`

SOEM 的典型工作流程可归纳为四个阶段：

初始化与网卡绑定：调用 ec_init("eth0") 打开指定网卡，并绑定原始套接字。
从站扫描与配置：调用 ec_config(FALSE, 0)，SOEM 自动发送广播帧，枚举总线上所有从站，读取其 EEPROM 中的厂商 ID、产品码，并建立从站信息列表。
状态机切换：通过 ec_statechange() 将每个从站从 INIT 依次切换到 PRE-OP、SAFE-OP，最终进入 OP 状态。此过程会配置 SM（同步管理器）和 FMMU（现场总线内存管理单元）。
周期数据交换：在 OP 状态下，应用循环调用 ec_send_processdata() 发送输出帧，随后调用 ec_receive_processdata() 接收输入帧。整个过程是阻塞式轮询，周期由应用层定时器控制。

实操提示：在 SOEM 的 test/ 目录下，simple_test.c 是最精简的示例。它演示了从 ec_init 到 ec_config 再到周期收发的最小代码路径，建议作为阅读起点。

4.3 IgH 主站的目录结构与分层架构

IgH 主站采用 Linux 内核模块 + 用户态库的双层结构。源码根目录下主要子目录包括：

master/：内核主站模块源码，包含 master.c（主站核心）、slave.c（从站对象管理）、cyclictask.c（实时周期任务）、cdev.c（字符设备接口）。
lib/：用户态库 libethercat，提供 ecrt_* 系列 API，封装了对内核的 ioctl 调用。
devices/：各类从站设备驱动，例如 generic.c（通用数字量 IO）、beckhoff_el*（Beckhoff 端子模块）。
tool/：命令行工具，如 ethercat 命令，用于查看总线状态、从站信息、SDO 读写。
script/：启动脚本，负责加载内核模块并创建设备节点。

IgH 的工作流程与 SOEM 有本质区别，它依赖内核的实时调度：

模块加载：通过 insmod ec_master.ko 加载主站模块，模块初始化时注册网络设备通知链，等待网卡驱动绑定。
应用注册：用户态应用调用 ecrt_request_master(0) 请求主站，然后通过 ecrt_master_create_domain() 创建数据域（Domain），用于管理周期数据。
从站配置：应用通过 ecrt_master_slave_config() 指定从站地址、厂商 ID、产品码，并配置 PDO 映射。此阶段不直接操作硬件，而是构建配置数据结构。
激活与周期运行：调用 ecrt_master_activate() 后，主站进入 OP 状态。随后应用启动一个实时线程（通常使用 rt_task_start 或 POSIX 实时线程），在每次周期中断中调用 ecrt_master_send() 和 ecrt_master_receive() 完成数据交换。

关键差异：IgH 的周期任务由内核的 cyclictask 驱动，它使用高精度定时器（hrtimer）触发，确保抖动在微秒级。而 SOEM 的周期完全依赖应用层定时器，在非实时操作系统上抖动较大。

4.4 案例：用 SOEM 读取一个 EL1004 数字量输入模块

假设总线上挂接了一个 Beckhoff EL1004（4 通道数字量输入），使用 SOEM 读取其状态的代码路径如下：

// 1. 初始化
ec_init("eth0");
// 2. 扫描并配置从站
ec_config(FALSE, 0);
// 3. 查找从站索引（假设 EL1004 是第 1 个从站）
int slave_idx = 1;
// 4. 切换到 OP 状态
ec_slave[slave_idx].state = EC_STATE_OPERATIONAL;
ec_statechange(slave_idx);
// 5. 周期读取输入
while (1) {
    ec_send_processdata();
    ec_receive_processdata(EC_TIMEOUTRET);
    // EL1004 的输入数据位于 ec_slave[1].inputs 缓冲区
    uint8_t *input_data = ec_slave[1].inputs;
    // 第 0 通道状态
    int ch0 = (*input_data) & 0x01;
    usleep(1000); // 1ms 周期
}

这段代码展示了 SOEM 的“直接内存映射”风格：从站输入输出数据直接映射到 ec_slave[] 结构体的 inputs 和 outputs 指针，应用层读写这些缓冲区即可完成过程数据交换，无需额外 API。

4.5 常见误区与复盘

误区一：忽略状态机切换的时序要求。初学者常直接调用 ec_statechange() 试图一步切换到 OP，但 EtherCAT 规定必须逐级切换（INIT→PRE-OP→SAFE-OP→OP），且每步需等待从站确认。SOEM 的 ec_statechange() 内部会循环等待，但若从站未正确配置 SM/FMMU，会卡死在 SAFE-OP。正确做法是先调用 ec_config_map() 完成 PDO 映射，再切换状态。

误区二：在 IgH 中混淆 Domain 与从站的关系。Domain 是 IgH 中管理周期数据交换的容器，一个 Domain 可以包含多个从站的 PDO。但每个从站的 PDO 映射必须在 ecrt_master_activate() 之前完成配置。若在激活后修改映射，会导致主站返回 -EBUSY 错误。复盘时，应检查应用代码中是否在 activate 之后调用了任何 ecrt_slave_config_pdo_assign() 之类的函数。

误区三：SOEM 的 ec_receive_processdata() 超时参数设置不当。该函数的第二个参数是等待接收的超时时间（微秒）。若设置过短，在总线负载高或从站响应慢时，会频繁返回超时错误，导致数据丢失。建议设置为 1000~5000 微秒，并检查返回值是否为 0（成功）。

4.6 框架选择的决策清单

在实际项目中，选择 SOEM 还是 IgH，可参考以下清单：

运行平台：若使用 MCU（如 STM32）或 RTOS（如 FreeRTOS），选 SOEM；若使用 Linux 且要求实时性，选 IgH。
从站数量与周期：从站少于 32 个、周期大于 1ms，SOEM 足够；从站超过 64 个或周期要求 250μs 以下，IgH 更稳。
调试工具：IgH 自带 ethercat 命令行工具，可在线查看从站状态、SDO 读写；SOEM 需要自行编写调试打印。
代码体积：SOEM 编译后约 100KB，适合资源受限设备；IgH 内核模块加库约 1MB，且依赖 Linux 内核版本。
社区活跃度：IgH 在 Linux 生态中维护更频繁，SOEM 在嵌入式领域更流行。