IgH EtherCAT 从入门到精通：第 2 章 环境搭建与编译安装

第 2 章 环境搭建与编译安装导读摘要本章将带你从零开始搭建 IgH EtherCAT Master 的开发环境。我们会逐步讲解硬件与软件的前置要求、源码获取方式、configure 配置选项的含义、内核模块与用户空间库的编译流程、安装部署与 udev 规则配置以及常见编译错误的排查方法。完成本章后你将拥有一个可运行的 EtherCAT 主站环境。2.1 硬件与软件环境要求硬件要求IgH EtherCAT Master 对硬件的核心要求是一块受支持的以太网卡NIC。主站通过专用的网卡驱动直接控制以太网硬件绕过 Linux 网络协议栈以获得确定性的通信时序。项目内置了多款 Intel 和 Realtek 系列网卡的 EtherCAT 化驱动Native Driver包括驱动名称适用硬件configure 选项generic通用以太网卡任意 NIC--enable-generic默认开启e1000Intel 82540/82545 等千兆网卡--enable-e1000e1000eIntel I217/I218/I219 等 PCIe 千兆网卡--enable-e1000eigbIntel I350/I210 等服务器级千兆网卡--enable-igbigcIntel I225/I226 2.5G 网卡--enable-igcr8169Realtek RTL8111/RTL8168 千兆网卡--enable-r8169genet树莓派 4Raspberry Pi 4板载网卡--enable-genet8139tooRealtek RTL8139 百兆网卡--enable-8139too如果你手头没有上述专用驱动支持的网卡可以使用generic 驱动。它适配任何 Linux 以太网卡但性能和实时性不如 Native Driver。对于入门学习和功能验证来说generic 驱动完全够用。提示完整的受支持硬件列表可参阅 EtherLab 官方文档。软件要求编译 IgH EtherCAT Master 1.6.8 版本需要以下软件环境操作系统Linux内核版本 2.6 或更新已配置的内核源码编译内核模块时需要当前运行内核的源码目录含.config文件Autotools 工具链autoconf 2.59、automake、libtoolpkg-config版本 0.27GCC 编译器支持 C 和 C 编译gcc、g内核头文件通常通过linux-headers-$(uname -r)包安装在 Debian/Ubuntu 系统上可以一键安装依赖sudoapt-getinstallbuild-essential autoconf automake libtool pkg-config\linux-headers-$(uname-r)在 CentOS/RHEL 系统上sudoyuminstallgcc gcc-c autoconf automake libtool pkgconfig\kernel-devel-$(uname-r)2.2 获取源码Git 克隆与版本选择IgH EtherCAT Master 的官方源码托管在 GitLab 上。我们推荐使用 Git 克隆的方式获取源码这样便于后续跟踪更新和切换版本。# 克隆官方仓库gitclone https://gitlab.com/etherlab.org/ethercat.gitcdethercat# 查看所有可用的版本标签gittag-l# 切换到稳定分支推荐用于生产环境gitcheckout stable-1.5# 或者切换到特定的版本标签gitcheckout v1.6.8如果你需要使用 Doxygen 文档功能还需要初始化子模块gitsubmodule update--init建议生产环境推荐使用stable-1.5分支或正式的版本标签。master分支包含最新的开发代码可能存在不稳定因素。2.3 bootstrap 与 configure 配置选项详解bootstrap 脚本从 Git 仓库克隆的源码不包含configure脚本需要先运行bootstrap来生成。这个脚本的核心逻辑非常简洁#!/bin/bashset-eset-xtouchChangeLogmkdir-pm4 autoreconf-i它做了三件事创建空的 ChangeLog 文件、确保m4宏目录存在、然后调用autoreconf -i生成完整的 Autotools 构建系统包括configure脚本和Makefile.in文件。# 运行 bootstrap仅从 Git 仓库获取源码时需要./bootstrapconfigure 核心选项configure脚本提供了丰富的配置选项。我们按功能分类梳理最常用的选项基础路径选项选项说明默认值--prefixDIR安装前缀路径/usr/local--sysconfdirDIR配置文件目录${prefix}/etc--with-linux-dirDIRLinux 内核源码路径自动检测当前内核--with-module-dirDIR内核模块安装子目录ethercat功能开关选项选项说明默认值--enable-kernel构建内核模块yes--enable-tool构建命令行工具ethercatyes--enable-userlib构建用户空间库libethercatyes--enable-eoe启用 EoEEthernet over EtherCAT支持yes--enable-cycles使用 CPU 时间戳计数器TSCno--enable-hrtimer使用高精度定时器High-Resolution Timer调度no--enable-rtdm启用 RTDMReal-Time Driver Model接口no--enable-debug-if创建调试网络接口no--enable-tty构建 TTY 驱动模块ec_ttyno--enable-sii-assign将 SIISlave Information Interface分配给 PDIyes--enable-wildcards启用 Vendor ID / Product Code 通配符no实时框架选项可选选项说明--with-rtai-dirDIRRTAI 安装路径启用 RTAI 支持--with-xenomai-dirDIRXenomai 安装路径启用 Xenomai 支持--with-devicesN每个主站的以太网设备数量大于 1 时启用冗余Redundancy默认 1典型配置示例下面是一个适合入门学习的最小配置./configure--sysconfdir/etc --enable-generic下面是一个用于生产环境的配置示例使用 Intel I210 网卡并启用冗余./configure\--sysconfdir/etc\--enable-generic\--enable-igb\--with-devices2\--enable-cycles\--enable-hrtimer\--enable-sii-assign2.4 编译内核模块与用户空间库配置完成后整个编译流程可以用下面的流程图概括┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │ bootstrap │────│ configure │────│ make all │ │ (生成构建系统) │ │ (检测环境配置) │ │ (编译用户空间组件) │ └─────────────┘ └──────────────┘ └────────┬──────────┘ │ v ┌───────────────────┐ │ make modules │ │ (编译内核模块) │ └────────┬──────────┘ │ v ┌───────────────────┐ │ make modules_install│ │ make install │ │ (安装到系统) │ └───────────────────┘编译用户空间组件make all命令会编译以下组件取决于你的 configure 配置命令行工具ethercat用于主站管理和从站诊断用户空间库libethercat应用程序通过此库与内核主站通信init 脚本和 systemd 服务文件用于系统服务管理makeall编译内核模块make modules命令会编译内核空间的模块ec_master.koEtherCAT 主站核心模块ec_generic.ko通用以太网驱动模块如果启用了--enable-genericec_driver.ko各 Native Driver 模块如ec_e1000e.ko、ec_igb.ko等makemodules编译完成后你可以在master/目录下找到ec_master.ko在devices/目录下找到各驱动模块。注意make all和make modules是两个独立的构建目标。all只编译用户空间组件modules编译内核模块。两者都需要执行。如果你的机器有多个 CPU 核心可以使用-j参数并行编译以加快速度make-j$(nproc)all modules2.5 安装部署与 udev 规则配置安装编译完成后以 root 权限执行安装命令sudomakemodules_installinstallsudodepmodmake modules_install将内核模块安装到/lib/modules/$(uname -r)/ethercat/目录可通过--with-module-dir修改子目录名。make install安装用户空间的库、头文件、命令行工具和服务脚本。depmod更新内核模块依赖关系。配置文件安装后你需要编辑配置文件来指定主站使用的网卡 MAC 地址和驱动类型# systemd 发行版sudovi/etc/ethercat.conf# init.d 发行版sudovi/etc/sysconfig/ethercat配置文件中最关键的两个参数MASTER0_DEVICEEtherCAT 主站使用的网卡 MAC 地址DEVICE_MODULES使用的驱动模块名称如generic、igb等udev 规则配置IgH EtherCAT Master 通过字符设备Character Device与用户空间通信。udev会在主站启动时自动创建/dev/EtherCAT0等设备节点。默认情况下设备权限为0660仅 root 用户和 root 组可读写。如果希望普通用户也能读取设备信息例如使用ethercat命令行工具需要创建 udev 规则# 允许普通用户读取 EtherCAT 设备echoKERNELEtherCAT[0-9]*, MODE0664|\sudotee/etc/udev/rules.d/99-EtherCAT.rules如果你需要更精细的权限控制可以创建专用用户组sudogroupaddethercatsudousermod-aGethercat$USERechoKERNELEtherCAT[0-9]*, MODE0660, GROUPethercat|\sudotee/etc/udev/rules.d/99-EtherCAT.rules启动主站服务一切就绪后启动 EtherCAT 主站# systemd 发行版sudosystemctl start ethercatsudosystemctlenableethercat# 设置开机自启# init.d 发行版sudo/etc/init.d/ethercat start验证主站是否正常运行# 查看主站状态ethercat master# 扫描总线上的从站ethercat slaves2.6 常见编译错误排查错误 1找不到内核源码configure: error: Failed to find Linux sources. Use --with-linux-dir!原因系统未安装当前内核的头文件/源码或/lib/modules/$(uname -r)/build链接缺失。解决方法# Debian/Ubuntusudoapt-getinstalllinux-headers-$(uname-r)# CentOS/RHELsudoyuminstallkernel-devel-$(uname-r)# 或者手动指定内核源码路径./configure --with-linux-dir/path/to/kernel/sources...错误 2内核源码未配置configure: error: No configured Linux kernel sources in /lib/modules/.../build原因内核源码目录下缺少.config文件说明内核源码尚未配置。解决方法确保安装了正确版本的内核头文件包或进入内核源码目录执行make oldconfig。错误 3autoconf/automake 版本不满足bootstrap: autoreconf: command not found原因系统缺少 Autotools 工具链。解决方法sudoapt-getinstallautoconf automake libtool# Debian/Ubuntusudoyuminstallautoconf automake libtool# CentOS/RHEL错误 4pkg-config 版本过低或缺失m4_fatal: pkgconf or pkg-config not found or too old原因pkg-config未安装或版本低于 0.27。解决方法sudoapt-getinstallpkg-config# Debian/Ubuntusudoyuminstallpkgconfig# CentOS/RHEL错误 5驱动内核版本不匹配configure: error: kernel X.Y.Z not available for e1000e driver!原因你启用了某个 Native Driver但项目中没有适配你当前内核版本的驱动源码。解决方法查看devices/目录下该驱动支持的内核版本列表或使用--with-driver-kernelX.Y.Z指定一个可用的版本。如果确实没有匹配的版本改用 generic 驱动是最简单的替代方案。错误 6模块编译时 GPL 符号错误ERROR: modpost: GPL-incompatible module ... uses GPL-only symbol ...原因内核版本与驱动代码之间存在兼容性问题。解决方法确认你的内核版本在项目支持范围内必要时更换到项目已适配的内核版本。小结本章我们完成了 IgH EtherCAT Master 从零到运行的完整搭建过程环境准备安装了编译工具链和内核头文件源码获取通过 Git 克隆并选择了合适的版本配置使用 bootstrap 和 configure 定制了构建选项编译分别构建了用户空间组件和内核模块安装与部署安装到系统并配置了 udev 规则和服务如果你在编译过程中遇到问题请优先检查内核头文件是否匹配、Autotools 版本是否满足要求。大多数编译问题都源于环境依赖不完整。下一章预告在第 3 章中我们将深入分析 IgH EtherCAT Master 的内核模块架构。你将了解ec_master.ko的内部结构、主站状态机的工作原理、以及内核模块与用户空间之间的通信机制。这些知识将帮助你理解主站的核心运行逻辑为后续的应用开发打下坚实基础。