IgH EtherCAT Master在工业运动控制圈子里基本属于“标配级”的存在尤其是做多轴同步、插补算法、总线式IO的工程师几乎绕不开它。我之前在x86平台上调过好几套IgH主站后来因为设备体积和成本原因把整套方案切到ARM开发板上跑光移植就折腾了将近两周踩了不少文档里根本不会写的坑。这篇东西就是基于那次实际移植经历把从零到能扫到从站、跑起来DC同步的完整过程整理出来主要针对Linux 4.19内核给准备在ARM上搞EtherCAT主站的同行们一个可以直接照着操作的参考。要说清楚的是这里有两条技术路线最容易混一是主站跑在ARM的Linux上通过有线网卡接EtherCAT从站也就是本文要说的“Linux主站”二是把IgH移植到裸机RTOS上。两回事难度也完全不在一个量级。Linux这边的好处是网络协议栈、驱动框架、内存管理都不用你操心缺点是内核版本一变IgH这种外挂内核模块就要跟着适配Linux 4.19正好处在新旧API交替的节点上很多老教程里的代码根本编不过去这也是我写这篇的核心原因。1. 移植前先把账算清楚IgH到底在ARM上做了什么1.1 IgH的架构拆解与移植本质很多人一听“移植”第一反应是拿源码交叉编译编完拷过去就完事。这种理解只对了一半而且是一小半。IgH EtherCAT Master不是单一程序它拆开是三个部分内核态主站模块、用户态EtherCAT库、以及ethercat命令行工具。真正跟硬件打交道的是内核模块这部分源码必须放到目标板Linux内核的编译框架里用目标内核的源码树和交叉工具链编出来出来的.ko文件跟你目标板子上跑的Linux内核版本严格绑定。用户态的libethercat和ethercat命令相对简单交叉编译链能做出来就行但它们依赖内核模块暴露的设备接口所以顺序上必须先搞定内核模块。内核模块里又分两块ec_master是主站核心逻辑负责状态机、寻址、周期性通信调度、DC同步、错误处理这部分是所有平台通用的ec_generic或者说ec_e1000e、ec_igb这类是网卡驱动适配层负责把EtherCAT帧发送到具体网卡硬件上。移植到ARM开发板时最核心的问题就是网卡适配层——开发板上的MAC控制器到底走generic模式用内核自带的macb驱动还是专门为某些Intel网卡编译native驱动这会直接影响实时性和稳定性表现。讲白了IgH移植到ARM这件事本质上不是“把代码编一遍”而是“让IgH的实时调度逻辑跑在你的目标内核和网卡之上”。这句话想明白后面所有配置都是为它服务的。1.2 为什么要自己折腾IgH而不是用商业方案或轻量主站市面上EtherCAT主站方案不算少SOEM、SSC、TwinCAT ADS、Acontis等各有拥趸。我在选型时也把几条路都趟过一遍。SOEM是纯用户态协议栈移植简单跑通demo速度极快但在多从站、长周期、需要DC同步的场景下稳定性明显不如IgH这种内核态主站。Acontis等商业主站性能确实不错但授权费用对于小批量设备来说性价比偏低。IgH开源免费内核态调度能拿到底层实时性优势社区活跃EtherCAT官方协议分析文档的解码逻辑基本都对得上这三点凑一起决定了自己动手移植是性价比最高的路径。当然IgH也有代价代码风格偏学术文档偏少版本跟内核API走得比较紧Linux内核一变它就崩给你看。Linux 4.19刚好是这样的节点之一。所以本文后面会花大量篇幅讲版本匹配和内核编译这部分不是过度谨慎而是这条路上最容易翻车的地方。1.3 移植前必做的硬件确认清单动手之前先花半天做硬件确认绝对比后面折腾一周划算。需要确认的点有三个。第一目标板网卡控制器的型号和Linux内核里对应的驱动是什么。像瑞芯微RK3288/RK3399、NXP i.MX6ULL这类常用平台多数板载MAC走的是macb或者stmmac驱动IgH的generic网卡驱动可以在这个基础上工作但前提是内核源码里这个网卡驱动得编成模块或者编译进内核并且不能和别的驱动抢占中断。第二确认CMOS时钟和定时器精度。EtherCAT DC同步定时的关键在于微秒级时钟精度所以目标板上的定时器频率要在MHz量级否则后面做分布时钟同步时会发现周期抖动根本压不下去。第三确认网卡支持多帧发送和中断延迟控制说白了就是这网卡能不能在软件层面满足周期通信的实时性要求。这三点里任何一点不满足移植完了也是白搭。2. 环境准备版本匹配是这条路上最大的坑2.1 内核版本、IgH分支、交叉编译器的三角关系先说结论Linux 4.19内核配IgH stable-1.5分支是可以跑起来的但是要打补丁stable-1.6分支对4.19的支持就要顺滑很多。这个结论不是凭空来的是实际编译对比出来的结果。IgH官方代码仓库的主线一直在动但维护节奏跟Linux内核API的变化比是滞后的。4.19内核里修改了net_device结构体的一些字段改了中断注册接口还把一部分timekeeping相关接口换了这些改动直接影响IgH的网卡驱动和时钟模块能否编过。如果非要停留在stable-1.5分支需要自己维护一个补丁集合并不断跟进社区修复这对绝大多数项目来说完全划不来。我当时是从官网下载的stable-1.5编译时报了一堆struct初始化错误后来切换到stable-1.6才算顺利。交叉编译器这边也别乱用太新版本。ARM板上跑Linux 4.19的工具链用gcc 7.x或8.x的arm-linux-gnueabihf系列就够了太新的gcc比如11以上编译出来的内核模块在某些老内核上会报module version magic不匹配太老的gcc 4.x又缺一些新语法支持。我用的是Linaro 7.5版本稳定。2.2 内核源码准备与版本号对齐这块一定要仔细因为后面所有编译都建立在“IgH内核模块看到的内核源码树”和“板上实际运行的内核”完全一致的基础上。先查板子的uname -r确定当前内核版本再去找对应版本的内核源码。可以通过某种方式从板子上抓取当前内核的配置文件也可以直接找厂商提供的kernel source包。关键操作是拿到源码后先用当前板子的config生成.config然后执行make zImage或make uImage生成内核确认Module.symvers文件生成成功。Module.symvers里面记录了所有编译过的内核符号IgH在编译时靠这个东西解析依赖如果文件缺失或不是同一份源码生成的后面的insmod基本必然报Unknown symbol。我踩过最疼的一个坑就是用了板子厂商提供的内核源码但是源码里.config不是从板子上抓的而是厂商自己留了一份版本号一致但内容有差异的配置编译出来的内核模块insmod时疯狂报错。后来老老实实从板子上拉/boot/config-$(uname -r)出来当作.config基础问题才解决。2.3 下载IgH源码与版本确认IgH官方仓库在Etherlab的Bitbucket上没的选但下载时要注意分支。官方默认的default分支不一定是最稳的我建议直接切到stable-1.6分支。下载后用git tag确认版本号最好记录一下commit hash方便后续问题回溯。有一点必须提醒IgH源码里带着一套完整的autotools构建系统这意味着必须在交叉编译前先在源码目录里执行autogen.sh生成configure脚本。另外它依赖Linux内核头文件但你千万不要用板子上的/lib/modules里那种精简头文件去编一定要用前面准备好的完整内核源码树。2.4 交叉编译工具链安装与环境变量交叉编译工具链安装本身不难发行版包管理器里直接装或者用Linaro的预编译包都行。关键是环境变量的设置要贯穿始终。我当时在~/.bashrc里统一配置了如下变量export ARCHarm export CROSS_COMPILEarm-linux-gnueabihf- export PATH/opt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf/bin:$PATH export CCarm-linux-gnueabihf-gcc这里的ARCH和CROSS_COMPILE是给Linux内核构建系统和IgH的configure脚本用的CC是给IgH用户态部分用的。我见过很多人在内核编译时明明配好了ARCH和CROSS_COMPILE结果执行IgH configure时忘了带CC导致用户态工具用gcc编成x86的了考试不及格。这一点哪怕编译器路径写对了也要在configure输出里反复确认host是arm而不是x86_64。3. 内核侧准备让EtherCAT主站能真正跑实时周期3.1 内核编译为什么绕不开很多从单片机转过来的朋友不理解为什么移植一个EtherCAT主站还要重新编译内核。简单解释一下IgH的ec_master模块要调用内核里的实时调度、中断管理、时间管理接口这些接口的实现在不同内核配置下差别巨大。为了保证接口可用且性能达标至少需要在内核配置里打开几项关键开关。特别是如果你要做DC同步实时性必须要有保障内核需要配置成可抢占模式。Linux 4.19里面跟IgH直接相关的内核配置项主要有这么几个CONFIG_MODULES必须开启否则.ko模块根本没法加载CONFIG_PREEMPT建议开启这样内核调度能支持实时抢占CONFIG_HZ建议配成1000也就是系统时钟节拍是1毫秒一次这是我们做运动控制周期调度的基础CONFIG_NET和对应的网卡驱动要编进内核或者编成模块。另外如果板子本身有较多外设中断干扰建议把CONFIG_IRQ_FORCED_THREADING也开起来Inspiration是让中断处理线程化进一步减少中断延迟。把这些配置项手工改.config之后重新编译内核是必须的。编译完的内核烧到板子上后先确认uname -r能看到新内核版本再进入IgH编译阶段。3.2 网络驱动与DMA相关配置EtherCAT主站的性能瓶颈在网络收发的实时性上。4.19内核里常见板载MAC驱动有这么几类macb很多Atmel/Microchip平台在用、stmmacST和部分全志平台、dwmacSynopsys DesignWare MACRK平台比较常见。IgH的generic网卡驱动并不去管具体的MAC控制器怎么初始化它直接复用内核里已经注册好的net_device结构体然后接管它的收发包路径。所以网卡驱动本身必须能正常出网卡设备并且DMA相关配置要正确。DMA这块特别容易出问题。开发板如果内存大于一定量级比如RK3399常见4GB可能需要在设备树或内核配置里开启CMAContiguous Memory Allocator否则网卡DMA分配大块连续内存容易失败。我在RK3399上就遇到了网卡能link up但是收发不了EtherCAT帧的问题最后查下来是CMA那块没配好DMA内存申请不到IgH的generic发送函数一直返回错误。这里给个排查经验先用Linux自带的ethtool或者简单的ping测试确认网卡本身就通再用tcpdump抓包确认EtherCAT帧能正常发出去从站那边会回应最后才轮到怀疑IgH的问题。基础网络不通就怀疑IgH是新手最容易犯的错误。3.3 实时性增强PREEMPT_RT还是普通抢占很多项目在ARM上跑IgH还想着用PREEMPT_RT补丁把内核变成硬实时。这里我给出自己的经验如果只是做运动控制周期同步普通内核加CONFIG_PREEMPT在多数场景下已经够用配合高优先级RT线程抖动控制在几十微秒是可能的。PREEMPT_RT补丁能让最坏情况延迟更低、更确定但补丁的适配跟内核版本强绑定每个内核版本都要重新打、重新测维护成本很高。所以我的建议分情况如果你的从站是伺服驱动器走周期同步位置模式CSP周期很敏感而且对同步性能有硬指标建议上PREEMPT_RT如果只是接IO模块采集开关量周期要求不高普通抢占内核就够了。Linux 4.19版本往上PREEMPT_RT补丁已经比较成熟RT补丁可以直接从官方rt仓库拉但依然建议在项目启动阶段就评估好这个需求别等到移植完了再改内核配置。4. IgH主站交叉编译全过程实操4.1 configure参数全解释下载完IgH源码并确认版本后进到源码根目录第一步要执行autogen.sh生成configure脚本这一步需要系统里装了autoconf、automake、libtool。接下来是configure这是整个移植过程中参数最密集、最考验对IgH理解程度的一步。我实际使用的配置命令如下./configure \ --prefix/opt/etherlab \ --with-linux-dir/home/user/kernel/linux-4.19 \ --enable-generic \ --disable-cycles \ --disable-eoe \ --enable-debug-if \ CCarm-linux-gnueabihf-gcc几个参数的语义得搞清楚。--with-linux-dir指向完整内核源码树不是头文件目录这个路径必须和之前编译内核、生成Module.symvers用的是同一份源码这一点上面强调过这里再强调一次。--enable-generic是让IgH使用generic网卡驱动方案走Linux的net_device接口适合大多数ARM开发板不用等IgH专门适配板载MAC型号。--disable-cycles是因为很多ARM板上的CPU没有周期计数器x86有TSC开了cycles会导致时钟相关代码编不过去或者运行时出错。--disable-eoe是关掉Ethernet over EtherCAT功能这个功能平时不怎么用关了能减少编译和运行时的复杂度。--enable-debug-if是启用调试接口只不过会把一些调试信息暴露到debugfs在前期适配阶段建议开着后面稳定后关掉。configure成功的关键标志是最后输出的summary里面会明确列出target、linux_dir、generic enabled等信息。务必逐行确认target是armlinux_dir路径正确generic那一栏显示yes。4.2 编译执行与常见编译报错configure通过之后在源码根目录执行make正常情况下会先编译内核模块再编译用户态工具和库。如果之前configure没配好CC这一步就会出现大量交叉编译工具链找不到的问题。我在Linux 4.19上编译时遇到过一个经典报错编译ec_master相关文件时提示找不到linux/version.h。这个头文件位于内核源码include/generated目录必须事先编译过内核才会生成。解决方法是回到内核源码目录先执行make一定编译流程生成这个目录。更稳的做法是我们在第3章已经让内核完整编译过一遍了所以此时应该已经有这个目录。另一个常见问题是模块符号解析失败提示undefined symbol。这个多半是因为ECAT_MASTER和内核源码之间版本不匹配或者Module.symvers没有正确被IgH的Makefile读取。检查内核源码根目录的Module.symvers文件是否存在并且文件里包含一些网络相关符号。如果文件不存在回到内核编译那一步重新生成。4.3 安装与文件部署make成功之后在源码目录执行make install会在configure指定的--prefix目录这里是/opt/etherlab下生成三个子目录sbin里面有ethercat命令行工具lib里面有libethercat库modules里面有编译好的内核模块ec_master.ko和ec_generic.ko。把这三个部分拷贝到ARM开发板上对应路径后还有一步必须做在板子上用depmod更新模块依赖关系这样才能在modprobe时自动加载正确的模块依赖。命令是depmod -a。另外为了方便管理可以把ethercat工具路径加入PATH或者创建软链到/usr/local/bin下。除了这些还要准备好IgH运行需要的系统配置文件。IgH默认读取/etc/sysconfig/ethercat这个配置文件里面主要定义了主站数量、给每个主站绑定的MAC地址、以及使用哪种网卡驱动。这个文件在安装的时候不会自动生成需要手动创建具体内容在第五章会详细讲。4.4 用户态工具链的自测装完后在板子上先执行一下ethercat version看看能不能正常输出版本信息。输出正常说明libethercat库和设备节点之间基本通路没问题。此时还没有任何主站运行ethercat master肯定报错这不用慌。接下来进入模块加载阶段。我在调试过程中发现一个特别好用的细节ethercat命令的很多子命令支持直接连主站ID但如果系统里只有一个主站可以不指定ID直接执行。这个对快速验证很有帮助比如ethercat master、ethercat slaves、ethercat pdos等命令省去了每次都要带主站编号的麻烦。5. 模块装载、网卡绑定与从站扫描5.1 正确的主站启动顺序刚装完IgH的人往往会在加载顺序上犯迷糊。IgH的模块加载顺序有讲究必须先加载ec_master再加载具体网卡驱动适配模块。因为ec_master初始化时会去读取系统配置确定主站要使用的网卡物理地址和驱动模式后续网卡驱动模块加载时会把使用generic模式的所有网卡挂到主站名下。我通常手动执行以下命令insmod /opt/etherlab/modules/ec_master.ko insmod /opt/etherlab/modules/ec_generic.ko注意ec_master加载时如果配置了主站数量为0它就不会创建任何主站实例后面的ec_generic加载了也白搭。所以/etc/sysconfig/ethercat这个文件的配置要先做对。我的配置文件内容如下MASTER0_DEVICE00:11:22:33:44:55 DEVICE_MODULESgenericMASTER0_DEVICE是开发板网卡的MAC地址通过ip link命令可以查到。DEVICE_MODULES要写generic对应我们编译时用的generic驱动。5.2 网卡绑定失败的处理主站加载后用ethercat master查看主站状态能看到主站的链路状态是UP还是DOWN。如果显示DOWN多半是MAC地址绑定有问题或者网卡驱动没有正确匹配。我遇到过一次很奇怪的现象MAC地址明明写对了但主站链路就是起不来。排查到最后发现是系统里其他网络服务比如NetworkManager抢占了网卡把网卡设置成了managed模式导致IgH没法干净地接管网卡收发路径。解决办法是把对应的网卡从NetworkManager管理列表里排除或者直接禁用该网卡的IP分配让网卡处于无IP、纯链路层状态。这里有个重要原则IgH使用的网卡不要在系统里配置IP地址也不要被DHCP管理。EtherCAT主站是独占网卡访问权的如果你给它配了IP轻则链路起不来重则主站工作异常帧冲突、丢帧、从站断线都见过。5.3 从站扫描与PDO映射主站链路起来后接上从站比如一个伺服驱动器或EtherCAT耦合器执行ethercat slaves理想情况是能看到从站拓扑和厂商信息。如果看不到从站先查物理接线和供电再查主站链路状态。能看到从站后下一步是PDO配置。IgH有两种方式一种是在主站配置阶段通过脚本定义PDO映射一种是在运行时用ethercat命令动态配置。后者更适合调试阶段比如可以用ethercat pdos查看当前从站的PDO信息用ethercat mapping把需要的变量映射到主站的过程数据区。我做CSP同步时惯用的流程是先扫到伺服从站看它支持哪些PDO再把控制字、目标位置、实际位置这些关键对象映射进过程数据最后在应用层通过rtdm接口读写。这样调试起来逻辑清晰也方便排查某个对象字典地址写错的问题。5.4 DC同步与周期运行验证这一步是验证主站是否真正达到工业可用状态的关键。EtherCAT从站如果支持DCDistributed Clocks那么主站需要周期性地给从站发同步帧让所有从站的时间基准保持一致。IgH主站里DC启用和参数配置都在sysconfig文件里设置。当DC启用且从站正常同步后用dmesg看内核日志能看到主站周期性发帧的调度信息。另外调试阶段可以通过自己的周期任务打印实际周期时间戳测试抖动大小。我实测过在i.MX6ULL加Linux 4.19普通抢占内核下1ms周期抖动大概在正负20微秒左右如果这时启用PREEMPT_RT可以压到正负10微秒以内。具体数值因平台而异但量级可以作为参考。值得一提的是DC同步模式下从站的工作状态由主站通过SYNC0事件驱动而不是应用周期直接驱动。所以应用层每个周期把目标位置写入后真正让伺服执行动作的是最近的SYNC0中断。这个机制决定了位置写入时刻和实际执行时刻之间可能有最多一个通信周期的延迟做插补算法时务必把这个延时考虑进去不然多轴联动时会出现明显的轮廓误差。6. 高频问题与实战排查记录6.1 模块加载与符号错误速查表移植过程中我遇到过大量问题挑几个典型的整理成表方便对照排查现象最可能原因快速定位方法insmod ec_master.ko报Invalid module format内核版本、编译器版本、或配置与当前运行内核不一致对比uname -r和内核源码版本检查Module.symvers是否来自当前源码确认交叉编译器版本insmod报Unknown symbolModule.symvers缺失或符号版本不匹配确认内核已完整编译过一遍且生成Module.symvers检查ec_master.ko的依赖符号主站链路DOWNMAC地址绑定错误、网卡被网络管理工具占用用ip link确认MAC检查NetworkManager是否管控该网卡从站扫描不到网卡驱动模式不对、物理链路断先确认主站链路UP用ethtool确认网卡link检查从站供电和接线周期抖动过大内核中断被干扰、CPU频率调节未关闭关闭CPU调频中断隔离检查是否有大量其他中断抢占位置写入后伺服不动作控制字未正确切换、DC同步未建立用ethercat dict读取控制字确认状态查看DC同步状态日志这张表看起来简单但每一条背后都是一个真实项目里耗费最少半天到一天的时间换来的教训。这里把每条再展开说一下。6.2 Invalid module format的深层原因这个报错非常常见但原因往往不是一个。最多的情况是编译内核模块时用的内核源码和运行中的内核版本号不一致版本号一致性检查直接抛错。其次是交叉编译器版本和生成内核时用的编译器版本不一致比如内核是用gcc 7编译的但你用gcc 11编IgH模块模块里嵌入的编译器版本信息和内核自己的version magic对不上。还有个比较隐蔽的问题发生在内核源码目录被改动过即使版本号相同content hash不一致也会报这个错。我解决这类问题的方法是把编译内核时用的工具链和.config记录下来IgH编译时强制使用同样的工具链和源码目录。不要把.config拷来拷去后在另一个目录编译IgH直接在编译过内核的同一份源码目录里编译模块这样最大程度减少变量。6.3 从站掉线的间歇性故障这个问题最让人头疼因为它不是必现往往是跑了几十分钟甚至几个小时后突然发生。我遇到过的典型案例是网卡中断被高负载的USB或MMC操作干扰导致主站周期性帧超时从站进入Safe-OP或Init态。排查思路如下先看dmesg里有没有ec_master的WARNING日志如果有Watchdog timeout之类的字样基本可以锁定是帧超时。再查网卡中断号有没有和别的高频中断共用用cat /proc/interrupts观察中断次数增长情况。如果发现某中断在故障时段暴增考虑强制中断亲和性或隔离中断。另外有一种情况是CPU频率调节导致的。很多ARM开发板默认开启cpufreq调速CPU频率跑在低档时主站实时线程调度延迟会上升导致周期超时。建议在系统启动脚本里把CPU governor固定为performance避免这种随机性的性能波动影响主站调度。6.4 实时性调优的几个小技巧除了内核配置系统中还有很多环节会影响主站实时性。下面几个是我亲测有效的微调手段。第一把主站相关的用户态周期线程优先级调高IgH提供rtdm接口的实时线程本身就属于RT调度类但应用层的周期任务需要自己用sched_setscheduler设置SCHED_FIFO优先级建议设85以上但不能超过内核实时线程的优先级等级。第二屏蔽掉CPU的SMP负载均衡如果目标板是双核或四核可以使用taskset把周期线程绑到特定核心另一颗核跑系统其它任务。第三禁用内核的dynamic tick也就是CONFIG_NO_HZ_FULL相关的配置保证周期调度的确定性。这三个手段叠加后抖动下降幅度往往非常明显。另外我强烈建议在板子上放一个cyclictest或者自己写一个简单的时间戳打印工具专门用来测量周期抖动。没有量化数据就去调实时性跟蒙眼开车没区别。我写的一个简易测试方法是在用户态周期线程里每次读clock_gettime(CLOCK_MONOTONIC)算出相邻两次调用的时间差打点记录最大值、最小值和平均值。这个数据能直接反映整个软件链路的实时性水平也方便对比内核配置调整前后的效果。最后再分享一个实操过程中的小技巧移植完成后系统里会残留两个容易忽略的地方。一个是IgH在调试阶段会创建debugfs节点位置一般在/sys/kernel/debug/ethercat里面有很详细的帧统计、错误计数、周期时间数据遇到问题先来这里翻数据比自己盲猜要高效得多。另一个是IgH的主站配置在/etc/sysconfig/ethercat里改了主站数量或MAC绑定后一定要先卸载ec_master再重新加载直接modprobe -r再modprobe有时会因为模块引用计数不为0而卸载失败需要先停掉所有用户态访问程序。我在这个项目里最大的体会是IgH移植到ARM上真正的难点不在代码能不能编过而在于你要建立起一套“内核、工具链、网卡、实时性”整体协同的判断能力。很多人编过之后跑不起来问题往往出在细节上——某个内核配置没开、某份符号表对不上、某个网卡被系统抢占。把这些细节头一次就处理好移植这条路就能走得顺很多。上面写到的这些坑和排查方法都是我实际项目里一条条趟出来的照着走能给你省下至少好几天的折腾时间。
IgH EtherCAT Master在ARM Linux上的移植实战指南
IgH EtherCAT Master在工业运动控制圈子里基本属于“标配级”的存在尤其是做多轴同步、插补算法、总线式IO的工程师几乎绕不开它。我之前在x86平台上调过好几套IgH主站后来因为设备体积和成本原因把整套方案切到ARM开发板上跑光移植就折腾了将近两周踩了不少文档里根本不会写的坑。这篇东西就是基于那次实际移植经历把从零到能扫到从站、跑起来DC同步的完整过程整理出来主要针对Linux 4.19内核给准备在ARM上搞EtherCAT主站的同行们一个可以直接照着操作的参考。要说清楚的是这里有两条技术路线最容易混一是主站跑在ARM的Linux上通过有线网卡接EtherCAT从站也就是本文要说的“Linux主站”二是把IgH移植到裸机RTOS上。两回事难度也完全不在一个量级。Linux这边的好处是网络协议栈、驱动框架、内存管理都不用你操心缺点是内核版本一变IgH这种外挂内核模块就要跟着适配Linux 4.19正好处在新旧API交替的节点上很多老教程里的代码根本编不过去这也是我写这篇的核心原因。1. 移植前先把账算清楚IgH到底在ARM上做了什么1.1 IgH的架构拆解与移植本质很多人一听“移植”第一反应是拿源码交叉编译编完拷过去就完事。这种理解只对了一半而且是一小半。IgH EtherCAT Master不是单一程序它拆开是三个部分内核态主站模块、用户态EtherCAT库、以及ethercat命令行工具。真正跟硬件打交道的是内核模块这部分源码必须放到目标板Linux内核的编译框架里用目标内核的源码树和交叉工具链编出来出来的.ko文件跟你目标板子上跑的Linux内核版本严格绑定。用户态的libethercat和ethercat命令相对简单交叉编译链能做出来就行但它们依赖内核模块暴露的设备接口所以顺序上必须先搞定内核模块。内核模块里又分两块ec_master是主站核心逻辑负责状态机、寻址、周期性通信调度、DC同步、错误处理这部分是所有平台通用的ec_generic或者说ec_e1000e、ec_igb这类是网卡驱动适配层负责把EtherCAT帧发送到具体网卡硬件上。移植到ARM开发板时最核心的问题就是网卡适配层——开发板上的MAC控制器到底走generic模式用内核自带的macb驱动还是专门为某些Intel网卡编译native驱动这会直接影响实时性和稳定性表现。讲白了IgH移植到ARM这件事本质上不是“把代码编一遍”而是“让IgH的实时调度逻辑跑在你的目标内核和网卡之上”。这句话想明白后面所有配置都是为它服务的。1.2 为什么要自己折腾IgH而不是用商业方案或轻量主站市面上EtherCAT主站方案不算少SOEM、SSC、TwinCAT ADS、Acontis等各有拥趸。我在选型时也把几条路都趟过一遍。SOEM是纯用户态协议栈移植简单跑通demo速度极快但在多从站、长周期、需要DC同步的场景下稳定性明显不如IgH这种内核态主站。Acontis等商业主站性能确实不错但授权费用对于小批量设备来说性价比偏低。IgH开源免费内核态调度能拿到底层实时性优势社区活跃EtherCAT官方协议分析文档的解码逻辑基本都对得上这三点凑一起决定了自己动手移植是性价比最高的路径。当然IgH也有代价代码风格偏学术文档偏少版本跟内核API走得比较紧Linux内核一变它就崩给你看。Linux 4.19刚好是这样的节点之一。所以本文后面会花大量篇幅讲版本匹配和内核编译这部分不是过度谨慎而是这条路上最容易翻车的地方。1.3 移植前必做的硬件确认清单动手之前先花半天做硬件确认绝对比后面折腾一周划算。需要确认的点有三个。第一目标板网卡控制器的型号和Linux内核里对应的驱动是什么。像瑞芯微RK3288/RK3399、NXP i.MX6ULL这类常用平台多数板载MAC走的是macb或者stmmac驱动IgH的generic网卡驱动可以在这个基础上工作但前提是内核源码里这个网卡驱动得编成模块或者编译进内核并且不能和别的驱动抢占中断。第二确认CMOS时钟和定时器精度。EtherCAT DC同步定时的关键在于微秒级时钟精度所以目标板上的定时器频率要在MHz量级否则后面做分布时钟同步时会发现周期抖动根本压不下去。第三确认网卡支持多帧发送和中断延迟控制说白了就是这网卡能不能在软件层面满足周期通信的实时性要求。这三点里任何一点不满足移植完了也是白搭。2. 环境准备版本匹配是这条路上最大的坑2.1 内核版本、IgH分支、交叉编译器的三角关系先说结论Linux 4.19内核配IgH stable-1.5分支是可以跑起来的但是要打补丁stable-1.6分支对4.19的支持就要顺滑很多。这个结论不是凭空来的是实际编译对比出来的结果。IgH官方代码仓库的主线一直在动但维护节奏跟Linux内核API的变化比是滞后的。4.19内核里修改了net_device结构体的一些字段改了中断注册接口还把一部分timekeeping相关接口换了这些改动直接影响IgH的网卡驱动和时钟模块能否编过。如果非要停留在stable-1.5分支需要自己维护一个补丁集合并不断跟进社区修复这对绝大多数项目来说完全划不来。我当时是从官网下载的stable-1.5编译时报了一堆struct初始化错误后来切换到stable-1.6才算顺利。交叉编译器这边也别乱用太新版本。ARM板上跑Linux 4.19的工具链用gcc 7.x或8.x的arm-linux-gnueabihf系列就够了太新的gcc比如11以上编译出来的内核模块在某些老内核上会报module version magic不匹配太老的gcc 4.x又缺一些新语法支持。我用的是Linaro 7.5版本稳定。2.2 内核源码准备与版本号对齐这块一定要仔细因为后面所有编译都建立在“IgH内核模块看到的内核源码树”和“板上实际运行的内核”完全一致的基础上。先查板子的uname -r确定当前内核版本再去找对应版本的内核源码。可以通过某种方式从板子上抓取当前内核的配置文件也可以直接找厂商提供的kernel source包。关键操作是拿到源码后先用当前板子的config生成.config然后执行make zImage或make uImage生成内核确认Module.symvers文件生成成功。Module.symvers里面记录了所有编译过的内核符号IgH在编译时靠这个东西解析依赖如果文件缺失或不是同一份源码生成的后面的insmod基本必然报Unknown symbol。我踩过最疼的一个坑就是用了板子厂商提供的内核源码但是源码里.config不是从板子上抓的而是厂商自己留了一份版本号一致但内容有差异的配置编译出来的内核模块insmod时疯狂报错。后来老老实实从板子上拉/boot/config-$(uname -r)出来当作.config基础问题才解决。2.3 下载IgH源码与版本确认IgH官方仓库在Etherlab的Bitbucket上没的选但下载时要注意分支。官方默认的default分支不一定是最稳的我建议直接切到stable-1.6分支。下载后用git tag确认版本号最好记录一下commit hash方便后续问题回溯。有一点必须提醒IgH源码里带着一套完整的autotools构建系统这意味着必须在交叉编译前先在源码目录里执行autogen.sh生成configure脚本。另外它依赖Linux内核头文件但你千万不要用板子上的/lib/modules里那种精简头文件去编一定要用前面准备好的完整内核源码树。2.4 交叉编译工具链安装与环境变量交叉编译工具链安装本身不难发行版包管理器里直接装或者用Linaro的预编译包都行。关键是环境变量的设置要贯穿始终。我当时在~/.bashrc里统一配置了如下变量export ARCHarm export CROSS_COMPILEarm-linux-gnueabihf- export PATH/opt/gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf/bin:$PATH export CCarm-linux-gnueabihf-gcc这里的ARCH和CROSS_COMPILE是给Linux内核构建系统和IgH的configure脚本用的CC是给IgH用户态部分用的。我见过很多人在内核编译时明明配好了ARCH和CROSS_COMPILE结果执行IgH configure时忘了带CC导致用户态工具用gcc编成x86的了考试不及格。这一点哪怕编译器路径写对了也要在configure输出里反复确认host是arm而不是x86_64。3. 内核侧准备让EtherCAT主站能真正跑实时周期3.1 内核编译为什么绕不开很多从单片机转过来的朋友不理解为什么移植一个EtherCAT主站还要重新编译内核。简单解释一下IgH的ec_master模块要调用内核里的实时调度、中断管理、时间管理接口这些接口的实现在不同内核配置下差别巨大。为了保证接口可用且性能达标至少需要在内核配置里打开几项关键开关。特别是如果你要做DC同步实时性必须要有保障内核需要配置成可抢占模式。Linux 4.19里面跟IgH直接相关的内核配置项主要有这么几个CONFIG_MODULES必须开启否则.ko模块根本没法加载CONFIG_PREEMPT建议开启这样内核调度能支持实时抢占CONFIG_HZ建议配成1000也就是系统时钟节拍是1毫秒一次这是我们做运动控制周期调度的基础CONFIG_NET和对应的网卡驱动要编进内核或者编成模块。另外如果板子本身有较多外设中断干扰建议把CONFIG_IRQ_FORCED_THREADING也开起来Inspiration是让中断处理线程化进一步减少中断延迟。把这些配置项手工改.config之后重新编译内核是必须的。编译完的内核烧到板子上后先确认uname -r能看到新内核版本再进入IgH编译阶段。3.2 网络驱动与DMA相关配置EtherCAT主站的性能瓶颈在网络收发的实时性上。4.19内核里常见板载MAC驱动有这么几类macb很多Atmel/Microchip平台在用、stmmacST和部分全志平台、dwmacSynopsys DesignWare MACRK平台比较常见。IgH的generic网卡驱动并不去管具体的MAC控制器怎么初始化它直接复用内核里已经注册好的net_device结构体然后接管它的收发包路径。所以网卡驱动本身必须能正常出网卡设备并且DMA相关配置要正确。DMA这块特别容易出问题。开发板如果内存大于一定量级比如RK3399常见4GB可能需要在设备树或内核配置里开启CMAContiguous Memory Allocator否则网卡DMA分配大块连续内存容易失败。我在RK3399上就遇到了网卡能link up但是收发不了EtherCAT帧的问题最后查下来是CMA那块没配好DMA内存申请不到IgH的generic发送函数一直返回错误。这里给个排查经验先用Linux自带的ethtool或者简单的ping测试确认网卡本身就通再用tcpdump抓包确认EtherCAT帧能正常发出去从站那边会回应最后才轮到怀疑IgH的问题。基础网络不通就怀疑IgH是新手最容易犯的错误。3.3 实时性增强PREEMPT_RT还是普通抢占很多项目在ARM上跑IgH还想着用PREEMPT_RT补丁把内核变成硬实时。这里我给出自己的经验如果只是做运动控制周期同步普通内核加CONFIG_PREEMPT在多数场景下已经够用配合高优先级RT线程抖动控制在几十微秒是可能的。PREEMPT_RT补丁能让最坏情况延迟更低、更确定但补丁的适配跟内核版本强绑定每个内核版本都要重新打、重新测维护成本很高。所以我的建议分情况如果你的从站是伺服驱动器走周期同步位置模式CSP周期很敏感而且对同步性能有硬指标建议上PREEMPT_RT如果只是接IO模块采集开关量周期要求不高普通抢占内核就够了。Linux 4.19版本往上PREEMPT_RT补丁已经比较成熟RT补丁可以直接从官方rt仓库拉但依然建议在项目启动阶段就评估好这个需求别等到移植完了再改内核配置。4. IgH主站交叉编译全过程实操4.1 configure参数全解释下载完IgH源码并确认版本后进到源码根目录第一步要执行autogen.sh生成configure脚本这一步需要系统里装了autoconf、automake、libtool。接下来是configure这是整个移植过程中参数最密集、最考验对IgH理解程度的一步。我实际使用的配置命令如下./configure \ --prefix/opt/etherlab \ --with-linux-dir/home/user/kernel/linux-4.19 \ --enable-generic \ --disable-cycles \ --disable-eoe \ --enable-debug-if \ CCarm-linux-gnueabihf-gcc几个参数的语义得搞清楚。--with-linux-dir指向完整内核源码树不是头文件目录这个路径必须和之前编译内核、生成Module.symvers用的是同一份源码这一点上面强调过这里再强调一次。--enable-generic是让IgH使用generic网卡驱动方案走Linux的net_device接口适合大多数ARM开发板不用等IgH专门适配板载MAC型号。--disable-cycles是因为很多ARM板上的CPU没有周期计数器x86有TSC开了cycles会导致时钟相关代码编不过去或者运行时出错。--disable-eoe是关掉Ethernet over EtherCAT功能这个功能平时不怎么用关了能减少编译和运行时的复杂度。--enable-debug-if是启用调试接口只不过会把一些调试信息暴露到debugfs在前期适配阶段建议开着后面稳定后关掉。configure成功的关键标志是最后输出的summary里面会明确列出target、linux_dir、generic enabled等信息。务必逐行确认target是armlinux_dir路径正确generic那一栏显示yes。4.2 编译执行与常见编译报错configure通过之后在源码根目录执行make正常情况下会先编译内核模块再编译用户态工具和库。如果之前configure没配好CC这一步就会出现大量交叉编译工具链找不到的问题。我在Linux 4.19上编译时遇到过一个经典报错编译ec_master相关文件时提示找不到linux/version.h。这个头文件位于内核源码include/generated目录必须事先编译过内核才会生成。解决方法是回到内核源码目录先执行make一定编译流程生成这个目录。更稳的做法是我们在第3章已经让内核完整编译过一遍了所以此时应该已经有这个目录。另一个常见问题是模块符号解析失败提示undefined symbol。这个多半是因为ECAT_MASTER和内核源码之间版本不匹配或者Module.symvers没有正确被IgH的Makefile读取。检查内核源码根目录的Module.symvers文件是否存在并且文件里包含一些网络相关符号。如果文件不存在回到内核编译那一步重新生成。4.3 安装与文件部署make成功之后在源码目录执行make install会在configure指定的--prefix目录这里是/opt/etherlab下生成三个子目录sbin里面有ethercat命令行工具lib里面有libethercat库modules里面有编译好的内核模块ec_master.ko和ec_generic.ko。把这三个部分拷贝到ARM开发板上对应路径后还有一步必须做在板子上用depmod更新模块依赖关系这样才能在modprobe时自动加载正确的模块依赖。命令是depmod -a。另外为了方便管理可以把ethercat工具路径加入PATH或者创建软链到/usr/local/bin下。除了这些还要准备好IgH运行需要的系统配置文件。IgH默认读取/etc/sysconfig/ethercat这个配置文件里面主要定义了主站数量、给每个主站绑定的MAC地址、以及使用哪种网卡驱动。这个文件在安装的时候不会自动生成需要手动创建具体内容在第五章会详细讲。4.4 用户态工具链的自测装完后在板子上先执行一下ethercat version看看能不能正常输出版本信息。输出正常说明libethercat库和设备节点之间基本通路没问题。此时还没有任何主站运行ethercat master肯定报错这不用慌。接下来进入模块加载阶段。我在调试过程中发现一个特别好用的细节ethercat命令的很多子命令支持直接连主站ID但如果系统里只有一个主站可以不指定ID直接执行。这个对快速验证很有帮助比如ethercat master、ethercat slaves、ethercat pdos等命令省去了每次都要带主站编号的麻烦。5. 模块装载、网卡绑定与从站扫描5.1 正确的主站启动顺序刚装完IgH的人往往会在加载顺序上犯迷糊。IgH的模块加载顺序有讲究必须先加载ec_master再加载具体网卡驱动适配模块。因为ec_master初始化时会去读取系统配置确定主站要使用的网卡物理地址和驱动模式后续网卡驱动模块加载时会把使用generic模式的所有网卡挂到主站名下。我通常手动执行以下命令insmod /opt/etherlab/modules/ec_master.ko insmod /opt/etherlab/modules/ec_generic.ko注意ec_master加载时如果配置了主站数量为0它就不会创建任何主站实例后面的ec_generic加载了也白搭。所以/etc/sysconfig/ethercat这个文件的配置要先做对。我的配置文件内容如下MASTER0_DEVICE00:11:22:33:44:55 DEVICE_MODULESgenericMASTER0_DEVICE是开发板网卡的MAC地址通过ip link命令可以查到。DEVICE_MODULES要写generic对应我们编译时用的generic驱动。5.2 网卡绑定失败的处理主站加载后用ethercat master查看主站状态能看到主站的链路状态是UP还是DOWN。如果显示DOWN多半是MAC地址绑定有问题或者网卡驱动没有正确匹配。我遇到过一次很奇怪的现象MAC地址明明写对了但主站链路就是起不来。排查到最后发现是系统里其他网络服务比如NetworkManager抢占了网卡把网卡设置成了managed模式导致IgH没法干净地接管网卡收发路径。解决办法是把对应的网卡从NetworkManager管理列表里排除或者直接禁用该网卡的IP分配让网卡处于无IP、纯链路层状态。这里有个重要原则IgH使用的网卡不要在系统里配置IP地址也不要被DHCP管理。EtherCAT主站是独占网卡访问权的如果你给它配了IP轻则链路起不来重则主站工作异常帧冲突、丢帧、从站断线都见过。5.3 从站扫描与PDO映射主站链路起来后接上从站比如一个伺服驱动器或EtherCAT耦合器执行ethercat slaves理想情况是能看到从站拓扑和厂商信息。如果看不到从站先查物理接线和供电再查主站链路状态。能看到从站后下一步是PDO配置。IgH有两种方式一种是在主站配置阶段通过脚本定义PDO映射一种是在运行时用ethercat命令动态配置。后者更适合调试阶段比如可以用ethercat pdos查看当前从站的PDO信息用ethercat mapping把需要的变量映射到主站的过程数据区。我做CSP同步时惯用的流程是先扫到伺服从站看它支持哪些PDO再把控制字、目标位置、实际位置这些关键对象映射进过程数据最后在应用层通过rtdm接口读写。这样调试起来逻辑清晰也方便排查某个对象字典地址写错的问题。5.4 DC同步与周期运行验证这一步是验证主站是否真正达到工业可用状态的关键。EtherCAT从站如果支持DCDistributed Clocks那么主站需要周期性地给从站发同步帧让所有从站的时间基准保持一致。IgH主站里DC启用和参数配置都在sysconfig文件里设置。当DC启用且从站正常同步后用dmesg看内核日志能看到主站周期性发帧的调度信息。另外调试阶段可以通过自己的周期任务打印实际周期时间戳测试抖动大小。我实测过在i.MX6ULL加Linux 4.19普通抢占内核下1ms周期抖动大概在正负20微秒左右如果这时启用PREEMPT_RT可以压到正负10微秒以内。具体数值因平台而异但量级可以作为参考。值得一提的是DC同步模式下从站的工作状态由主站通过SYNC0事件驱动而不是应用周期直接驱动。所以应用层每个周期把目标位置写入后真正让伺服执行动作的是最近的SYNC0中断。这个机制决定了位置写入时刻和实际执行时刻之间可能有最多一个通信周期的延迟做插补算法时务必把这个延时考虑进去不然多轴联动时会出现明显的轮廓误差。6. 高频问题与实战排查记录6.1 模块加载与符号错误速查表移植过程中我遇到过大量问题挑几个典型的整理成表方便对照排查现象最可能原因快速定位方法insmod ec_master.ko报Invalid module format内核版本、编译器版本、或配置与当前运行内核不一致对比uname -r和内核源码版本检查Module.symvers是否来自当前源码确认交叉编译器版本insmod报Unknown symbolModule.symvers缺失或符号版本不匹配确认内核已完整编译过一遍且生成Module.symvers检查ec_master.ko的依赖符号主站链路DOWNMAC地址绑定错误、网卡被网络管理工具占用用ip link确认MAC检查NetworkManager是否管控该网卡从站扫描不到网卡驱动模式不对、物理链路断先确认主站链路UP用ethtool确认网卡link检查从站供电和接线周期抖动过大内核中断被干扰、CPU频率调节未关闭关闭CPU调频中断隔离检查是否有大量其他中断抢占位置写入后伺服不动作控制字未正确切换、DC同步未建立用ethercat dict读取控制字确认状态查看DC同步状态日志这张表看起来简单但每一条背后都是一个真实项目里耗费最少半天到一天的时间换来的教训。这里把每条再展开说一下。6.2 Invalid module format的深层原因这个报错非常常见但原因往往不是一个。最多的情况是编译内核模块时用的内核源码和运行中的内核版本号不一致版本号一致性检查直接抛错。其次是交叉编译器版本和生成内核时用的编译器版本不一致比如内核是用gcc 7编译的但你用gcc 11编IgH模块模块里嵌入的编译器版本信息和内核自己的version magic对不上。还有个比较隐蔽的问题发生在内核源码目录被改动过即使版本号相同content hash不一致也会报这个错。我解决这类问题的方法是把编译内核时用的工具链和.config记录下来IgH编译时强制使用同样的工具链和源码目录。不要把.config拷来拷去后在另一个目录编译IgH直接在编译过内核的同一份源码目录里编译模块这样最大程度减少变量。6.3 从站掉线的间歇性故障这个问题最让人头疼因为它不是必现往往是跑了几十分钟甚至几个小时后突然发生。我遇到过的典型案例是网卡中断被高负载的USB或MMC操作干扰导致主站周期性帧超时从站进入Safe-OP或Init态。排查思路如下先看dmesg里有没有ec_master的WARNING日志如果有Watchdog timeout之类的字样基本可以锁定是帧超时。再查网卡中断号有没有和别的高频中断共用用cat /proc/interrupts观察中断次数增长情况。如果发现某中断在故障时段暴增考虑强制中断亲和性或隔离中断。另外有一种情况是CPU频率调节导致的。很多ARM开发板默认开启cpufreq调速CPU频率跑在低档时主站实时线程调度延迟会上升导致周期超时。建议在系统启动脚本里把CPU governor固定为performance避免这种随机性的性能波动影响主站调度。6.4 实时性调优的几个小技巧除了内核配置系统中还有很多环节会影响主站实时性。下面几个是我亲测有效的微调手段。第一把主站相关的用户态周期线程优先级调高IgH提供rtdm接口的实时线程本身就属于RT调度类但应用层的周期任务需要自己用sched_setscheduler设置SCHED_FIFO优先级建议设85以上但不能超过内核实时线程的优先级等级。第二屏蔽掉CPU的SMP负载均衡如果目标板是双核或四核可以使用taskset把周期线程绑到特定核心另一颗核跑系统其它任务。第三禁用内核的dynamic tick也就是CONFIG_NO_HZ_FULL相关的配置保证周期调度的确定性。这三个手段叠加后抖动下降幅度往往非常明显。另外我强烈建议在板子上放一个cyclictest或者自己写一个简单的时间戳打印工具专门用来测量周期抖动。没有量化数据就去调实时性跟蒙眼开车没区别。我写的一个简易测试方法是在用户态周期线程里每次读clock_gettime(CLOCK_MONOTONIC)算出相邻两次调用的时间差打点记录最大值、最小值和平均值。这个数据能直接反映整个软件链路的实时性水平也方便对比内核配置调整前后的效果。最后再分享一个实操过程中的小技巧移植完成后系统里会残留两个容易忽略的地方。一个是IgH在调试阶段会创建debugfs节点位置一般在/sys/kernel/debug/ethercat里面有很详细的帧统计、错误计数、周期时间数据遇到问题先来这里翻数据比自己盲猜要高效得多。另一个是IgH的主站配置在/etc/sysconfig/ethercat里改了主站数量或MAC绑定后一定要先卸载ec_master再重新加载直接modprobe -r再modprobe有时会因为模块引用计数不为0而卸载失败需要先停掉所有用户态访问程序。我在这个项目里最大的体会是IgH移植到ARM上真正的难点不在代码能不能编过而在于你要建立起一套“内核、工具链、网卡、实时性”整体协同的判断能力。很多人编过之后跑不起来问题往往出在细节上——某个内核配置没开、某份符号表对不上、某个网卡被系统抢占。把这些细节头一次就处理好移植这条路就能走得顺很多。上面写到的这些坑和排查方法都是我实际项目里一条条趟出来的照着走能给你省下至少好几天的折腾时间。
