IgH EtherCAT 主站详解 --- 博客系列索引
作者：wsg1100（沐多） | 博客园：https://www.cnblogs.com/wsg1100/
本系列共 24 篇（含 2 篇同号并行章节），另附 1 篇独立参考手册，系统讲解 IgH EtherCAT Master 的协议原理、内核架构、驱动开发与实战调优。
本文档基于非官方版本 github.com/ribalda/ethercat，是功能更为全面的 IgH EtherCAT 主站。
官方版本为 gitlab.com/etherlab.org/ethercat。
etherlab 官方主站从 2013 年 1.5.2 版本起至 2021 年没有维护，但该时间段内有一个非官方版本的分支一直维护，功能比较全面。虽然 2021 年开始官方重新维护（当前版本 1.6.8），但功能、支持的 OS、从站启动速度等方面不如非官方维护版本，这需要自行选择使用哪个版本。
比如从站进 OP 速度：etherlab 官方主站是 slave 1 从 Init 切到 OP，再处理 slave 2 从 Init 切到 OP，串行处理 ，实测 32 个从站需要 40 秒；非官方版本是所有从站并行从 Init 切到 OP，速度取决于最慢的那个从站，实测 32 轴启动时间 3 秒内。
第一部分：协议基础（第 1 ~ 3 章）
第 1 章 EtherCAT协议、帧格式和ESC
链接： 【原创】IgH EtherCAT主站详解(一)--EtherCAT协议、帧格式和ESC
概要： 从零介绍 EtherCAT 协议基础，涵盖协议概述（通信原理、帧处理流程、核心协议组成、与其他工业以太网对比）、EtherCAT 数据帧结构（物理层帧结构与传输时序、EtherCAT Header、Datagram 结构、命令类型、三种寻址模式、WKC 工作计数器机制、帧校验），以及 ESC 从站控制器详解（内部功能模块、内存映射、环路控制、FMMU 寄存器、同步管理器寄存器、错误计数器、看门狗、中断机制、SII EEPROM、物理层要求、LED 信号、DC 分布式时钟基础）。
章节目录
- 一、EtherCAT 协议概述
- 概览：EtherCAT 是什么、协议栈位置、核心优势、与其他工业以太网协议对比
- 技术详情：帧处理流程、核心协议组成、从站状态机
- 深入源码：IgH 中的协议实现概览
- 二、EtherCAT 数据帧结构
- 概览：帧结构层次
- 技术详情：物理层帧结构与传输时序、EtherCAT Header、Datagram 结构详解、命令类型、三种寻址模式、WKC 机制、帧校验
- 深入源码：ec_datagram 结构体、Datagram 类型/状态枚举、关键函数
- 三、ESC 从站控制器
- 概览：ESC 是什么、内部功能模块、内存映射全景
- 技术详情：环路控制、影子缓冲区、循环帧防护、ESC 寄存器映射、内存空间、FMMU 寄存器、同步管理器寄存器、错误计数器、看门狗、写保护、ESC 复位、LED 信号、中断机制、SII EEPROM、物理层要求、命令类型、WKC
- 深入源码：ec_slave 结构体、ESC 寄存器访问方式
- 分布式时钟（DC 基础部分）
第 2 章 DC分布时钟与AL状态
链接： 【原创】IgH EtherCAT主站详解(二)--DC分布时钟与AL状态
概要： 深入讲解两大核心机制。分布式时钟（DC）部分覆盖 64 位系统时间、时钟同步关键概念、DC 寄存器映射、参考时钟选择、同步四步骤、传播延迟测量、DC 配置子状态机、从站时钟类型、SYNC0/SYNC1 同步信号、LATCH0/LATCH1 锁存信号、通信模式、漂移补偿算法。AL 状态机部分介绍 AL 状态机简介、完整状态转换图、各状态能力对比、请求-确认机制、ESC 相关寄存器、常见 AL 状态码、各状态转换要求，以及 State Change FSM 的 9 个状态。
章节目录
- 一、分布式时钟
- 概览：为什么需要分布式时钟、DC 同步时序
- 技术详情：64位系统时间、DC 寄存器映射、参考时钟选择、同步四步骤、传播延迟测量、DC 配置子状态机、从站时钟类型、SYNC0/SYNC1、LATCH0/LATCH1、通信模式、漂移补偿
- 深入源码：ec_sync 结构体、DC 配置状态机、ec_master_calc_dc() 调用链、SYNC0/SYNC1 时序、初始化步骤、DC 中断方式
- 二、AL 状态机
- 概览：AL 状态机简介、完整状态机图、各状态能力对比
- 技术详情：状态转换请求-确认机制、ESC 寄存器、常见 AL 状态码、各状态转换要求
- 深入源码：fsm_change.h、State Change FSM（9个状态）、关键实现细节
第 3 章 邮箱(Mailbox)、FMMU和同步管理器(Sync Manager)
链接： 【原创】IgH EtherCAT主站详解(三)--邮箱(Mailbox)、FMMU和同步管理器 (Sync Manager)
概要： 解析 EtherCAT 三大数据通信机制。邮箱协议部分涵盖邮箱通信原理、帧格式、CoE（SDO 上传/下载、21个 FSM 状态）、EoE（帧分片与重组）、FoE（固件升级流程）、SoE、VoE 等协议。FMMU 部分讲解地址映射原理、16 字节配置字段、配置处理流程及多 FMMU 条目协同。同步管理器部分介绍 SM 缓冲区工作原理、SM 通道典型分配、8 字节配置寄存器、邮箱模式与过程数据模式对比、SM 配置流程。
章节目录
- 一、邮箱协议
- 概览：邮箱通信原理、邮箱协议概览
- 技术详情：邮箱帧格式、CoE（SDO 上传/下载、21个FSM状态）、EoE（帧分片与重组）、FoE（固件升级流程）、SoE、VoE
- 深入源码：mailbox.h 邮箱类型枚举、mailbox.c 核心函数、各 FSM 状态计数总览
- 二、FMMU 原理与处理流程
- 概览：FMMU 是什么、地址映射示意图
- 技术详情：16字节配置字段、配置处理流程、多 FMMU 协同
- 深入源码：fmmu_config.h、ec_fmmu_config_page() 配置页生成、domain.c FMMU 相关函数
- 三、同步管理器
- 概览：SM 是什么、缓冲区工作原理
- 技术详情：SM 通道分配、8字节配置寄存器、Control 寄存器位域、邮箱vs过程数据模式、SM 配置流程
- 深入源码：ec_sync 结构体、ec_sync_config 结构体、ec_sync_page() 配置页生成
第二部分：架构与核心模块（第 4 ~ 7 章）
第 4 章 并行启动、总体架构及软件分层
链接： 【原创】IgH EtherCAT主站详解(四)--并行启动、总体架构及软件分层
概要： 全景展现 IgH 主站的系统架构。架构概览部分介绍 etherlab 项目全貌、系统全景架构、核心能力、目录结构。软件分层部分详解四层架构（应用层、库层 lib/、内核主站层 master/、驱动层 devices/）、完整数据流向图、ecrt.h API 到内核的映射、关键结构体关系、主站 Phase 转换。模块依赖部分展示模块依赖全景、核心模块清单、FSM 状态机模块、模块间关键关系。并行启动部分介绍启动流程三阶段（ORPHANED/IDLE/OPERATION）、从站并行状态切换、多主站并行运行、模块参数。
章节目录
- 一、架构概览
- 概览：etherlab 是什么、系统全景架构、核心能力一览、目录结构总览
- 技术详情：协议栈完整性、实时框架集成、关键源文件索引、版本信息
- 二、软件分层架构
- 概览：四层架构概览
- 技术详情：应用层、库层(lib/)、内核主站层(master/)、驱动层(devices/)、完整数据流向图
- 深入源码：ecrt.h API 到内核映射、关键结构体关系、主站 Phase 转换
- 三、模块依赖关系
- 概览：模块依赖全景
- 技术详情：核心模块清单、FSM 状态机模块、模块间关键关系、头文件包含关系
- 四、并行启动与初始化
- 概览：启动流程三阶段、整体启动流程
- 技术详情：EC_ORPHANED/EC_IDLE/EC_OPERATION 阶段详解、从站并行状态切换、多主站并行运行、模块参数说明、典型加载命令
- 深入源码：ec_init_module() 完整流程、ecdev_offer() 设备匹配、Phase 转换状态机、线程模型
第 5 章 Master、Slave及Domain模块介绍
链接： 【原创】IgH EtherCAT主站详解(五)--Master、Slave及Domain模块介绍
概要： 深入解析 IgH 三大核心数据模块。Master 模块涵盖三阶段生命周期、线程模型（IDLE/OPERATION 线程循环）、ec_master 结构体字段、Datagram 收发流程、并发控制及关键源码（ec_master_init、ec_master_send_datagrams、ec_master_receive_datagrams 等）。Domain 模块讲解 Domain 概念、多 Domain FMMU 内存布局、ec_domain 结构体、Domain 生命周期、FMMU 配置与偏移计算。Slave 模块介绍从站概述、配置请求生命周期、ec_slave/ec_slave_config 结构体、SII 信息提取及传播延迟递归计算。
章节目录
- 一、Master 模块
- 概览：Master 是什么、三阶段生命周期
- 技术详情：线程模型、ec_master 结构体字段、线程循环流程、Datagram 收发流程、并发控制
- 深入源码：ec_master_init()、ec_master_idle_thread()、ec_master_operation_thread()、ec_master_send_datagrams()、ec_master_receive_datagrams()、Phase 转换、DC 相关数据报
- 二、Domain 模块
- 概览：Domain 是什么、多 Domain FMMU 内存布局
- 技术详情：ec_domain 结构体、Domain 生命周期、FMMU 配置与偏移计算
- 深入源码：ec_domain_init()、ec_domain_add_fmmu_config()、ec_domain_finish()
- 三、Slave 模块
- 概览：Slave 模块概述、配置请求生命周期
- 技术详情：ec_slave 结构体、ec_slave_config 结构体、SII 信息提取
- 深入源码：ec_slave_init()、ec_slave_clear()、ec_slave_config_attach()、ec_slave_config_detach()、ec_slave_calc_transmission_delays_rec()、端口数据结构
第 6 章 Datagram、PDO及Mailbox模块介绍
链接： 【原创】IgH EtherCAT主站详解(六)--Datagram、PDO及Mailbox模块介绍
概要： 详细解析 IgH 主站三大核心模块。Datagram 数据报是 EtherCAT 通信的基本传输单元，支持四种寻址模式，具有独立状态机和超时重试机制。PDO 过程数据对象定义从站 I/O 数据格式，通过 TxPDO/RxPDO 和 PDO Entry 描述数据字段，其总大小决定 FMMU 和 Domain 的逻辑地址空间分配。Mailbox 邮箱模块基于 Sync Manager 实现主从站之间的非周期性通信，采用双缓冲区和握手机制确保可靠传输，支持 CoE/EoE/FoE/SoE/VoE 等多种协议复用。
第 7 章 Device网卡、EEPROM(SII)和EoE模块介绍
链接： 【原创】IgH EtherCAT主站详解(七)--Device网卡、EEPROM(SII)和EoE模块介绍
概要： 介绍 IgH 主站的设备抽象层、EEPROM 和 EoE 三大模块。Device 模块封装 Linux net_device，提供 16 个预分配 SKB 环形缓冲实现确定性帧收发，禁用网卡中断改由主站线程主动 poll 获取数据。EoE 模块为每个支持 EoE 的从站创建虚拟网络接口，通过邮箱分片传输标准以太网帧，支持 IP 参数配置。EEPROM/SII 模块通过 FSM 状态机读写从站非易失性存储器，解析固定信息区和 Category 链（字符串、Sync Manager、PDO 映射、DC 参数等），并支持从固件文件加载 SII 镜像覆盖 EEPROM 内容。
第三部分：状态机深度解析（第 8 ~ 10 章）
第 8 章 Master状态机与Slave状态机
链接： 【原创】IgH EtherCAT主站详解(八)--Master状态机与Slave状态机
概要： 深入剖析 IgH 主站两个核心状态机。Master FSM 运行在内核线程中，负责总线监控（周期性 BRD 广播）、从站扫描触发、DC 时间同步（支持 32 位和 64 位偏移计算）以及 EEPROM 写入，通过检测 WKC 和从站数量变化自动发现拓扑改变。Slave FSM 是每个从站独立运行的请求分发状态机，按 11 级优先级依次轮询 Scan、Config、SDO、SoE、字典、寄存器、FoE、EoE、MBG 等各类请求，各从站之间无耦合互不等待，实现并行处理。
第 9 章 从站扫描、配置、AL状态切换状态机
链接： 【原创】IgH EtherCAT主站详解(九)--从站扫描、配置、AL状态切换状态机
概要： 详细解析三个关键子状态机。Slave Config FSM 是 IgH 中最大的 FSM（约 1940 行），完成从站从 INIT 到 OP 的完整配置流程，分阶段执行 FMMU/SM 清除、邮箱配置、SDO/SoE/PDO 配置、DC 同步检查、看门狗设置和 AL 状态切换。Slave Scan FSM 负责扫描单个从站完整信息，包括站地址分配、基础数据读取、EEPROM 全文读取与 Category 解析、PDO 映射构建。State Change FSM 处理 AL 状态转换的请求-确认机制，支持 FULL 完整转换和 ACK_ONLY 错误确认两种模式，超时阈值 5 秒。
第 10 章 CoE、EoE、FoE和SII执行状态机
链接： 【原创】IgH EtherCAT主站详解(十)--CoE、EoE、FoE和SII执行状态机
概要： 解析五种邮箱协议状态机的实现。CoE FSM（约 2600 行）包含 SDO 字典读取、SDO 下载和 SDO 上传三个独立子功能，支持分段传输和 toggle 位校验。EoE FSM 通过 INIT_REQ 报文设置从站 IP 参数（MAC、IP、子网掩码、网关、DNS），超时 3 秒。FoE FSM 实现文件传输协议，通过 WRQ/RRQ/DATA/ACK 报文交互完成固件升级。SoE FSM 实现 SERCOS over EtherCAT 协议，读写伺服驱动 IDN 参数。SII FSM 通过 ESC 寄存器 0x0502 读写 EEPROM，每次操作 4 字节，具有加载超时 500ms 和操作超时 20ms 的容错机制。
第四部分：运行流程与机制（第 11 ~ 13 章）
第 11 章（上）主站启动配置流程
链接： 【原创】IgH EtherCAT主站详解(十一)--主站启动配置流程
概要： 梳理 EtherCAT 主站从加载到运行的五阶段启动流程：阶段 1 通过 insmod 加载内核模块并分配主站实例（ORPHANED 状态）；阶段 2 网卡驱动 probe 时调用 ecdev_offer 绑定设备，主站进入 IDLE 阶段；阶段 3 IDLE 线程中 Master FSM 自动触发总线扫描，完成从站识别和 EEPROM 读取；阶段 4 自动将每个从站从 Init 配置到 OP 状态（各从站并行独立）；阶段 5 应用程序通过 ecrt API（创建 Domain、注册 PDO、activate）接管控制权，主站进入 OPERATION 阶段开始实时通信。
第 11 章（下）拓扑扫描流程
链接： 【原创】IgH EtherCAT主站详解(十一)--拓扑扫描流程
概要： 专门讲解 EtherCAT 总线拓扑扫描的完整过程。Master FSM 通过周期性 BRD 广播读取寄存器 0x0130 获取在线从站数量，检测到变化后自动触发扫描。扫描流程包括：先读取旧 DC 时间快照，然后广播清除站地址，接着测量传播延迟，最后为每个从站启动独立的 Slave Scan FSM。每个从站的扫描依次完成站地址分配（APWR 递增）、基础信息读取（ESC 类型/FMMU 数/SM 数/DC 能力）、DC 时间参数读取、EEPROM 全文读取与 Category 解析，最终构建 PDO 映射表供 Domain 注册使用。
第 12 章 EtherCAT热插拔处理
链接： 【原创】IgH EtherCAT主站详解(十二)--EtherCAT热插拔处理
概要： 介绍 IgH 主站的热插拔处理机制。Master FSM 通过周期性 BRD 广播读取从站数量，利用 WKC（Working Counter）变化检测从站上线或离线。检测到拓扑变化后自动触发重新扫描，扫描完成后根据已有的 slave_config（通过 VendorID+ProductCode+Alias/Position 匹配）自动恢复从站配置，将重新上线的从站重新配置到 Init-Pre-Op-Safe-Op-OP 的完整流程。IDLE 阶段自动处理热插拔，OPERATION 阶段默认禁止扫描需手动触发（ethercat rescan），从站掉线不会导致主站崩溃但 PDO 数据变为无效。
第 13 章 EtherCAT线缆冗余与双网卡故障切换机制
链接： 【原创】IgH EtherCAT主站详解(十三)--EtherCAT 线缆冗余与双网卡故障切换机制
概要： 讲解 EtherCAT 线缆冗余的两种拓扑模式（主站侧冗余和从站侧冗余），以及 IgH 主站的双网卡故障切换机制。详细介绍主站 Main/Backup 网卡的自动检测、故障判定和切换策略，分析线缆断开、从站掉电等故障场景下的恢复行为。
第五部分：应用层与调用链（第 14 ~ 15 章）
第 14 章 应用层与协议栈调用链
链接： 【原创】IgH EtherCAT主站详解(十四)--应用层与协议栈调用链
概要： 分析应用层 API（ecrt）到底层协议栈的完整调用链。详解 ecrt_request_master、ecrt_master_create_domain、ecrt_slave_config_pdos、ecrt_domain_register_pdo_entry、ecrt_master_activate 等关键 API 的内部实现，追踪用户空间调用如何通过 ioctl 穿透到内核模块，最终驱动硬件完成 EtherCAT 帧的收发。
第 15 章 EoE网络桥接与FoE固件升级
链接： 【原创】IgH EtherCAT主站详解(十五)--EOE网络桥架与FoE固件升级
概要： 介绍 EoE（Ethernet over EtherCAT）虚拟网络桥接和 FoE（File Access over EtherCAT）固件升级两大应用。EoE 部分讲解虚拟网络接口创建、帧分片与重组、IP 参数配置、NAT 桥接完整流程。FoE 部分讲解 FoE 协议帧格式（WRQ/RRQ/DATA/ACK）、固件升级操作流程、断点续传机制以及升级失败的恢复策略。
第六部分：驱动与工具链（第 16 ~ 19 章）
第 16 章 Igh主站实时网卡驱动开发指南（以r8169为例）
链接： 【原创】IgH EtherCAT主站详解(十六)--Igh主站实时网卡驱动开发指南(以r8169为例)
概要： 以 r8169 网卡为例，系统讲解如何为 IgH 主站适配实时网卡驱动。核心是将标准 Linux 网卡驱动的中断驱动模型改造为 poll 模式以满足 EtherCAT 周期性通信的确定性要求。涵盖四种通用适配模式（Guard-Return、Guard-Skip、Branch、Override）、RX/TX 路径改造、SKB 环形缓冲管理、中断禁用与 NAPI 替换，以及 Makefile 和 configure.ac 集成方法。提供的 diff 模式可复用于任意网卡的 EtherCAT 适配。
第 17 章 命令行管理工具解析及使用说明
链接： 【原创】IgH EtherCAT主站详解(十七)--命令行管理工具解析及使用说明
概要： 全面解析 ethercat 命令行工具，涵盖 33 个子命令的分类使用与源码架构。命令详解包括：主站命令组（master/debug/rescan/version）、从站命令组（slaves/alias/states/reboot）、域命令组（domains/data/pcap）、PDO 命令组（pdos/graph/cstruct）、SDO 命令组（sdos/upload/download）、SoE/FoE/EoE 命令组、SII/EEPROM 命令组、寄存器命令组（reg_read/reg_write/reg_rdwr）、配置/诊断/XML 命令。并提供 5 个典型故障排查实战场景和排障黄金法则。源码部分详解命令注册匹配机制和 ioctl 通信架构。
第 18 章 IgH编译配置说明
链接： 【原创】IgH EtherCAT主站详解(十八)--IgH编译配置说明
概要： 详细说明 IgH EtherCAT Master 的编译配置选项。涵盖 configure 脚本的所有参数选项（实时框架选择、网卡驱动启用、功能模块开关）、内核模块参数、构建目标选择、交叉编译配置，以及编译过程中常见问题的排查与解决。
第 19 章 Xenomai/Xenomai POSIX/RTAI/RT-Preempt 编译部署与平台选型
链接： 【原创】IgH EtherCAT主站详解(十九)--Xenomai/Xenomai POSIX/RTAI / RT-Preempt 编译部署与平台选型
概要： 对比分析 IgH 主站支持的四种实时平台（Xenomai、Xenomai POSIX、RTAI、PREEMPT_RT），包括各平台的实时性能特征、内核补丁安装、IgH 编译配置差异、部署注意事项和选型建议。帮助开发者根据应用场景的实时性需求选择最合适的实时平台方案。
第七部分：实战与调优（第 20 ~ 24 章）
第 20 章 EtherCAT主站实时性能调优
链接： 【原创】IgH EtherCAT主站详解(二十)-- EtherCAT 主站实时性能调优
概要： 聚焦 EtherCAT 主站的实时性能分析与调优。涵盖周期时间优化、Datagram 分帧策略、Domain 数据布局优化、CPU 亲和性绑定、中断线程化配置、内核启动参数调优、网卡驱动性能参数等。提供系统的性能测量方法和常见性能瓶颈的诊断手段。
第 21 章 从零搭建EtherCAT主站
链接： 【原创】IgH EtherCAT主站详解(二十一)--从零搭建 EtherCAT 主站
概要： 从零开始的完整实战教程，指导搭建一个可运行的 EtherCAT 主站系统。覆盖硬件选型、实时内核安装、IgH 主站编译部署、网卡驱动适配、从站连接与扫描、应用程序开发（基于 ecrt API 的完整示例代码）、调试排障等全流程。适合初学者快速上手 IgH EtherCAT 主站开发。
第 22 章 ENI XML结构、生成与使用
链接： 【原创】IgH EtherCAT主站详解(二十二)--ENI XML 结构、生成与使用
概要： 讲解 EtherCAT Network Information (ENI) XML 配置文件的结构、生成方法与使用场景。详解 ENI XML 的 Schema 层次（EtherCATConfig/Config/Slave/...）、各节点含义、如何通过 EtherCATConfig 工具或在线方式生成 ENI、以及在 TwinCAT 等配置工具中导入使用的方法。
第 23 章（上）DC同步实战
链接： 【原创】IgH EtherCAT主站详解(二十三)--DC 同步实战
概要： DC 分布式时钟同步的实战操作指南。从理论到实践，详解主站参考时钟 DC 同步和从站参考时钟 DC 同步两种模式的配置方法。包括 DC 寄存器配置、SYNC0/SYNC1 周期设置、PI 漂移补偿算法参数调优、Xenomai POSIX 环境下的 DC 同步示例代码，以及 DC 同步异常的典型诊断流程。
第 23 章（下）API参考
链接： 【原创】IgH EtherCAT主站详解(二十三)--API 参考
概要： IgH EtherCAT Master 的 ecrt 用户空间 API 完整参考手册。涵盖所有公开 API 函数的原型、参数说明、返回值和使用示例，包括主站管理（request/release/activate/deactivate）、Domain 操作（create/register/process）、从站配置（pdo/sdo/dc/watchdog）、数据交换（domain data、SDO request）等接口。
第 24 章 FoE固件升级操作指南
链接： 【原创】IgH EtherCAT主站详解(二十四)--FoE固件升级操作指南
概要： 使用 FoE（File Access over EtherCAT）协议进行从站固件升级的完整操作指南。涵盖固件文件准备与校验、通过 ethercat foe_write 命令执行升级、升级过程中的状态监控、断电恢复策略、固件版本验证，以及多从站批量升级的自动化脚本示例。
附录：独立参考
EtherCAT从站控制器寄存器地址与功能速查
概要： ESC（EtherCAT Slave Controller）寄存器地址与功能的快速参考手册。按地址范围分类列出所有关键寄存器，包括 ESC 类型/版本、DL 状态/控制、AL 状态/控制/状态码、FMMU 配置、同步管理器配置、DC 分布式时钟、错误计数器、看门狗、EEPROM 控制、厂商 ID/产品码/序列号等，便于开发调试时快速查阅。