📚 课程目录第4章开发环境搭建

4. 开发环境搭建

4.1 核心原理：为什么需要实时内核与IgH主站

EtherCAT是一种基于以太网的实时工业总线协议，其核心优势在于主站通过硬件网卡在数据链路层直接处理帧，实现微秒级的周期同步。然而，标准Linux内核的调度延迟通常在数毫秒到数十毫秒之间，无法满足EtherCAT对周期抖动（通常要求<50μs）的硬实时需求。因此，必须对Linux内核应用PREEMPT_RT补丁，将内核改造为完全可抢占模式，使实时任务能够优先获得CPU资源。

IgH（EtherCAT Master for Linux）是开源的EtherCAT主站协议栈，运行在用户空间，通过内核模块与网卡驱动交互。其架构分为三层：应用层（用户程序调用API）、主站核心层（状态机、邮箱通信、过程数据管理）和硬件驱动层（基于网卡驱动的EtherCAT帧收发）。搭建开发环境时，需要同时准备实时内核、IgH源码以及匹配的网卡驱动。

关键认知：实时内核补丁并非“锦上添花”，而是EtherCAT周期通信的必要条件。若使用普通内核，即使IgH主站能运行，也会因调度延迟导致看门狗超时、从站丢站等问题。

4.2 方法流程：从Linux系统配置到IgH编译安装

4.2.1 Linux系统基础配置

推荐使用Ubuntu 20.04 LTS或Debian 11作为开发系统，内核版本需与PREEMPT_RT补丁版本严格对应。系统安装完成后，首先进行以下基础配置：

更新软件源并安装编译工具链：包括gcc、make、libtool、autoconf等。
安装内核开发包：用于编译内核模块，需与当前内核版本完全一致。
禁用无关服务：如NetworkManager（避免干扰网卡）、irqbalance（避免中断均衡影响实时性）。
配置GRUB启动参数：添加isolcpus=2,3（隔离CPU）、nohz_full=2,3（全无时钟中断）等参数。

# 基础工具安装
sudo apt update
sudo apt install -y build-essential libncurses-dev bison flex libssl-dev \
    libelf-dev bc curl wget git

# 查看当前内核版本
uname -r   # 例如: 5.4.0-26-generic

# 安装对应内核头文件
sudo apt install -y linux-headers-$(uname -r)

4.2.2 实时内核补丁（PREEMPT_RT）的获取与编译

PREEMPT_RT补丁由内核社区维护，需要从kernel.org下载与当前内核版本完全匹配的补丁文件。补丁版本号格式为patch-5.4.x-rtY.patch.gz，其中5.4.x必须与内核小版本号一致。

版本匹配陷阱：内核版本与补丁版本必须逐位精确匹配。例如，内核为5.4.0，补丁必须为patch-5.4.0-rt11.patch.gz，不能使用5.4.1或5.4.0-rt10的补丁，否则编译必然失败。

# 下载内核源码（以5.4.0为例）
wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.4.0.tar.xz
tar -xf linux-5.4.0.tar.xz
cd linux-5.4.0

# 下载并应用PREEMPT_RT补丁
wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/5.4/older/patch-5.4.0-rt11.patch.gz
zcat patch-5.4.0-rt11.patch.gz | patch -p1

# 配置内核（基于现有配置修改）
cp /boot/config-$(uname -r) .config
make menuconfig
# 在菜单中启用以下选项：
#   General setup → Preemption Model → Fully Preemptible Kernel (RT)
#   Device Drivers → Network device support → Ethernet driver support → 选择对应网卡驱动

内核配置完成后，进行编译和安装。编译时间取决于CPU核心数，通常需要20~40分钟。安装完成后重启，通过uname -a确认内核名称中带有PREEMPT RT字样。

# 编译并安装内核（使用多核加速）
make -j$(nproc)
sudo make modules_install
sudo make install

# 更新GRUB并重启
sudo update-grub
sudo reboot

# 重启后验证实时内核
uname -a
# 输出应包含: #1 SMP PREEMPT_RT ...

4.2.3 IgH源码获取与编译安装

IgH主站源码托管在GitLab上，官方仓库地址为https://gitlab.com/etherlab.org/ethercat。推荐使用稳定分支（如stable-1.5），该分支经过充分测试，适合工业应用。

# 克隆IgH源码
git clone -b stable-1.5 https://gitlab.com/etherlab.org/ethercat.git
cd ethercat

# 生成configure脚本
./bootstrap

# 配置编译选项（关键参数说明见下表）
./configure --prefix=/opt/etherlab \
            --enable-rtdm \
            --enable-generic \
            --disable-8139too \
            --enable-e1000e

# 编译并安装
make -j$(nproc)
sudo make install

配置参数	作用	推荐值
`--prefix`	指定安装路径	`/opt/etherlab`
`--enable-rtdm`	启用RTDM实时驱动接口	必须启用
`--enable-generic`	启用通用网卡驱动	建议启用
`--enable-e1000e`	启用Intel e1000e网卡驱动	根据网卡型号选择
`--disable-8139too`	禁用Realtek 8139驱动	若使用其他网卡则禁用

4.2.4 环境变量与设备节点配置

安装完成后，需要配置环境变量和创建设备节点，使IgH主站能够被用户程序访问。

# 添加环境变量到~/.bashrc
echo 'export PATH=$PATH:/opt/etherlab/sbin:/opt/etherlab/bin' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/etherlab/lib' >> ~/.bashrc
source ~/.bashrc

# 创建设备节点（主站0）
sudo mknod --mode=666 /dev/EtherCAT0 c 240 0

# 加载主站内核模块
sudo modprobe ec_master
# 查看主站是否加载成功
dmesg | grep -i ethercat
# 输出示例: EtherCAT: Master driver 1.5.2 initialized

4.3 案例：基于Intel I210网卡的完整搭建过程

以下是一个实际项目中使用的完整搭建流程，目标平台为Intel I210网卡，内核版本5.4.0，IgH版本1.5.2。

  硬件环境：工控机（CPU: Intel Core i5-8500，内存: 8GB），板载Intel I210网卡，Ubuntu 20.04系统。

# 1. 确认网卡型号
lspci | grep -i ethernet
# 输出: 00:1f.6 Ethernet controller: Intel Corporation Ethernet Connection I219-LM

# 2. 下载并编译实时内核（步骤同4.2.2，此处省略重复命令）
# 关键：在make menuconfig中确认启用
#   CONFIG_PREEMPT_RT=y
#   CONFIG_E1000E=y

# 3. 编译IgH时启用e1000e驱动
./configure --prefix=/opt/etherlab \
            --enable-rtdm \
            --enable-e1000e \
            --disable-generic

# 4. 加载驱动并绑定网卡
sudo modprobe ec_master
sudo modprobe ec_e1000e

# 5. 查看主站状态
ethercat master
# 输出示例:
# Master 0:  Version 1.5.2,  Phase: Idle
#   Slave Count: 0
#   Ethernet Devices: eth0 (MAC: 00:1b:21:xx:xx:xx)

若输出中Phase: Idle且Slave Count: 0，说明主站已成功加载但尚未连接从站。此时可通过ethercat slaves命令扫描总线上的从站设备。

4.4 误区与复盘：常见搭建问题及解决策略

在开发环境搭建过程中，工程师常遇到以下几类问题，提前了解可大幅缩短排障时间。

误区一：内核版本与补丁不匹配
表现为patch命令报错或编译时出现大量reversed patch detected警告。解决方法是严格核对uname -r输出与补丁文件名中的版本号，确保完全一致。
误区二：网卡驱动未正确绑定
IgH主站加载后，ethercat master显示No Ethernet Device。原因通常是网卡已被内核原生驱动占用。需先卸载原生驱动，再加载IgH驱动：sudo rmmod e1000e && sudo modprobe ec_e1000e。
误区三：设备节点权限不足
用户程序调用ecrt_master_create时返回Permission denied。需确保/dev/EtherCAT0节点权限为666，或使用sudo运行程序。
误区四：RTDM接口未启用
编译IgH时未加--enable-rtdm，导致后续无法使用实时接口。需重新配置并编译安装。

复盘建议：搭建完成后，建议编写一个简单的测试程序（如ethercat master命令查看状态），并记录dmesg输出。若主站能正常进入Idle状态，说明环境搭建成功。后续调试中，dmesg是定位主站与从站通信问题的第一手资料。

通过以上步骤，即可完成EtherCAT IgH主站开发环境的搭建。该环境支持后续的从站配置、过程数据映射和实时控制应用开发。建议将整个搭建过程记录为自动化脚本，便于在多台开发机上快速复现环境。