本篇是 EtherCAT 主站实战系列第 38 篇,B 线 · IgH 主站架构 · 操作篇。
API 签名以 IgH 2.5.2 的 include/ecrt.h 与 lib/ 实现为参照;不同版本请核对自家头文件。文中代码为骨架示例,未经实测,集成前请在你的平台上验证。

一、全局地图:应用代码的五个阶段

任何 IgH 应用,不管用什么实时框架(pthread + SCHED_FIFO、Xenomai、RTAI),代码结构都是同一条流水线。按执行时间分五个阶段:

阶段什么时候跑核心动作允许失败吗
① 请求与识别启动时request_master、扫描、读身份否,失败即退出
② 配置启动时slave config、PDO 映射、domain 登记、DC 配置否
③ 激活启动时master_activate,切进 OPERATION否
④ 周期每个节拍process → 算法 → queue/send/receive有降级策略
⑤ 释放退出时master_release尽力而为

这五个阶段有一条铁律贯穿始终:阶段顺序不可乱、阶段④内部顺序不可乱。IgH 的 API 不是"随时都能调"的自由接口——每个调用都有 phase 前置检查(篇 37 讲过 ec_master_t.phase),调错顺序轻则返回错误,重则行为未定义。下面逐阶段展开。

在这里插入图片描述
图1:从启动到退出的五阶段地图,每阶段标注核心 API 与是否允许失败。

二、阶段①②:配置序列的每一步

2.1 请求主站

master = ecrt_request_master(0);          /* 主站索引 0 */
if (!master) { /* 初始化失败:模块没加载?设备没绑定? */ }

失败原因排查顺序:内核模块加载了吗(lsmod | grep ec_master)→ 网卡被原生驱动占了还是被 EtherCAT 驱动接管了 → 主站索引对不对。这一步失败没有任何恢复手段,直接退出并把原因写日志。

2.2 从站配置对象

ec_slave_config_t *sc = ecrt_master_slave_config(
        master, 0, 0,          /* alias, position */
        VENDOR_ID, PRODUCT_CODE);
if (!sc) { /* 创建失败 */ }

注意两个易错点:

  1. alias 与 position 的匹配规则:position 是环形拓扑上的物理序号(从站跳线/拨码之外由主站按端口顺序编号),alias 是 SII 里写的别名。两个参数都给 0 意味着"总线第一个从站、无别名"——只对单从站或第一个从站安全。多从站系统建议给每个从站写 alias(用 ethercat 命令行工具写 SII),配置代码里按 alias 定位,拓扑重排就不用改代码;
  2. 身份校验在这里发生:ecrt_master_slave_config() 带 VID/PID 参数时,激活阶段会核对实际扫描到的从站身份。身份不符不会在这一步报错,而是在 activate 时——这也是新手最困惑的"配置代码没报错,activate 却失败"的来源。真正的识别报错在激活阶段,配置阶段的返回值只代表"配置对象建出来了"。

2.3 PDO 映射与 domain 登记

/* 同步管理器与 PDO:优先用 op 值(来自从站固件) */
if (ecrt_slave_config_pdos(sc, EC_END, syncs)) {
    /* syncs 数组不匹配从站能力 */
}

/* 登记 PDO 条目 */
const ec_pdo_entry_info_t slave0_channels[] = {
    {0x7000, 1, 32},   /* 输出,32 位 */
    {0x6000, 1, 32},   /* 输入,32 位 */
};
/* ……组 pdo_entries / pdos / syncs,最后传给 pdos() */

ec_pdo_entry_registration_t domain1_regs[] = {
    {0, 0, 0x7000, 1, 4, NULL},   /* alias=0, pos=0, idx, sub, 位长, offset 指针 */
    {0, 0, 0x6000, 1, 4, NULL},
    {}
};
domain1 = ecrt_master_create_domain(master);
if (!domain1) { /* 失败 */ }
if (ecrt_domain_reg_pdo_entry_list(domain1, domain1_regs)) {
    /* 登记失败:条目不在配置的 PDO 里?位长超了? */
}

这一段是配置序列里最容易出错的地方,三个高频问题:

  1. syncs 数组与从站实际 SM/PDO 不一致:ecrt_slave_config_pdos() 只检查"你给的映射是否合法",不检查"是否与从站默认映射一致"。映射不一致的后果是激活后数据错位——症状与篇 36 的"DC 不同步"完全不同但抓包同样能看到 WKC 正常,所以映射问题要在激活前用配置核对抓,不要指望运行时报错;
  2. offset 指针的使用:domain1_regs 里每条的最后一个是 unsigned int *offset,登记成功后 IgH 把该条目在 domain process data 里的字节偏移写进去。周期任务里访问数据就是 base_ptr + *offset。这个偏移在 activate 之后才有效——有人在登记完立刻解引用,读到的是垃圾;
  3. 完整映射 vs 简化映射:如果从站不需要重新映射 PDO(默认映射已够用),可以跳过 syncs 数组直接 ecrt_slave_config_pdos(sc, EC_END, NULL) 然后按默认映射登记条目。但"默认映射里有哪些条目"要从从站手册或 ethercat pdos 输出里来,不能猜。

2.4 DC 配置(可选但常见)

ecrt_slave_config_dc(sc, 0x0300,   /* assign+activate,参照篇 35 */
        1000000, 0,                /* 周期 1ms,shift0 相位 0 */
        0, 0);                     /* shift1 不用 */

DC 的 assign/activate 值、SYNC0 周期与 shift 的取法在篇 35 已逐条讲过,本篇只强调调用位置:必须在 activate 之前、配置序列之内。它本质是往从站配置状态机里塞了一组寄存器写任务,激活时随配置流程一起下发。放错位置(比如激活后再调)不会崩溃,但不生效——这是"DC 配了却没同步"的第二个高频原因(第一个见篇 36)。

另外两行容易被漏掉的:

ecrt_slave_config_watchdog(sc, 0, 1000000, 10000000);  /* 看门狗分频/超时 */
ecrt_slave_config_sdo8(sc, 0x1c32, 1, 1);              /* DC 模式使能,按手册 */

看门狗不配,从站用自己的默认值,多数情况能用;但一旦主站卡顿超过从站看门狗窗口,输出会按从站策略掉安全值——这个行为是否合意,应当在设计期决定而不是默认接受。

2.5 激活

if (ecrt_master_activate(master)) { /* 身份校验失败/映射非法 */ }

activate 做的事:逐从站跑配置状态机(SM/FMMU/PDO 映射/DC 下发)、身份校验、domain 切 datagram。它可能花几百毫秒(慢从站、大配置),所以必须在实时节拍开始前完成,不能放在第一个实时周期里。配置状态机中途失败的报错会通过日志与返回值暴露,常见的三类:身份不符、SM 大小不符、邮箱配置失败——分别对应核对 VID/PID、核对 syncs 与从站手册、核对邮箱协议支持。

三、阶段④:周期任务里的调用顺序

激活完成后,实时线程的标准骨架(以 clock_nanosleep 驱动的 pthread 为例):

/* 周期任务里,顺序是硬约束 */
while (running) {
    clock_nanosleep(CLOCK_MONOTONIC, TIMER_ABSTIME, &next, NULL);
    timespec_add(&next, period);                 /* 先算下一拍,防漂移 */

    ecrt_domain_process(domain1);                /* 1. 结算上一拍 */
    check_domain_state(domain1);                 /* 2. 看域状态(WKC 汇总)*/
    check_master_state();                        /* 3. 低频轮询主站状态 */
    check_slave_config_states();                 /* 4. 低频轮询从站状态 */

    /* 5. 读输入(base + *offset),跑控制算法,写输出 */

    ecrt_domain_queue(domain1);                  /* 6. 提交本拍 */
    ecrt_master_send(master);                    /* 7. 打包发送 */
    ecrt_master_receive(master);                 /* 8. 收回处理 */
}

在这里插入图片描述
图2:每拍内部 1→8 的调用顺序,箭头标注顺序约束不可交换的原因。

顺序约束逐条解释:

  1. process 必须在读数据之前。process 把上一拍收到的帧内容结算进 process data 内存,不 process 直接读,读到的是更旧的数据。反过来 queue 必须在写完输出之后——queue 只是把 datagram 标记为待发,你 queue 之后又写输出,写入的内容会随本拍发出(这在"部分输出希望晚一拍生效"的场景反而是个技巧,但要刻意使用而不是无意为之);
  2. send 必须在 queue 之后、receive 必须在 send 之后。send 打包并发出所有 QUEUED 报文;receive 收帧、按 index 匹配、结算 WKC。两步在同一拍里先后调用,中间不睡不等;
  3. receive 的一个细节:它只处理"已经到达的帧"。如果网卡还没收到,receive 直接返回,本拍该 datagram 保持 SENT 状态,下一拍 receive 继续尝试结算——这意味着 WKC 状态天然滞后于周期,偶发的"上一拍数据"不是 bug,是模型本身的性质。对时序敏感的场合(比如需要确认本拍输出已送达从站),IgH 没有原语直接表达"已确认",要靠外部 WKC 与从站反馈设计;
  4. 状态轮询要限频。check_master_state / check_slave_config_states 内部是 ioctl 或共享状态读取,虽不重,但每拍都查没有意义——常用做法是每 100 拍或每 10ms 查一次,或注册 domain 回调由 IgH 在 WKC 变化时通知;
  5. clock_nanosleep 用 ABSTIME。RELTIME 睡眠会把处理时间累积进节拍,造成"周期实际大于名义周期"的慢漂;ABSTIME + 先推进 next 的时间轴,处理时间超长时会自动"追赶或丢拍",节奏不漂移。丢拍的检测与处理见下节错误处理。

四、错误处理模板:三类故障分别怎么接

4.1 domain WKC 异常(链路类)

static void check_domain_state(ec_domain_t *d)
{
    ec_domain_state_t s;
    ecrt_domain_state(d, &s);
    if (s.wc_state == s_prev) return;
    s_prev = s.wc_state;
    switch (s.wc_state) {
    case EC_WC_COMPLETE:  /* 全部从站应答,一切正常 */ break;
    case EC_WC_INCOMPLETE:
        /* 部分从站没应答:链路断了/从站掉了。策略:保持输出安全值,
           记日志,等 N 拍后仍异常则进入安全停机 */
        break;
    case EC_WC_ZERO:
        /* 没有任何从站应答:总线级故障。策略:立即进入安全状态 */
        break;
    }
}

降级策略要分级:INCOMPLETE 通常对应单从站离线,机械系统里"保持上一个安全输出 + 限时停机"比"立刻断使能"更平滑;ZERO 是总线级故障,动作要快。两级动作差异是设计决定,不是代码风格问题,评审时应明确到毫秒级时限。

在这里插入图片描述
图3:WKC / AL 状态 / 周期超时三类故障的响应分级,右侧标注各级的设计决定点。

4.2 从站状态异常(OP 掉线类)

/* 低频调用 */
ec_slave_config_state_t st;
ecrt_slave_config_state(sc, &st);
if (!st.operational || st.al_state != EC_AL_STATE_OP) {
    /* OP 掉了:AL 状态寄存器里有错误码,走 ethercat 工具或
       ecrt_slave_config_reg_so_entries 记录的 error 码定位 */
}

从站状态掉出 OP 的常见触发:WKC 长期异常导致从站主动退出、DC 漂移超限被从站判死(见篇 36)、看门狗超时。恢复路径有两条:让主站状态机自动重试(IDLE 后 fsm 会重新请求 OP),或应用主动调 ecrt_slave_config_set_... 系列。自动恢复的前提是故障源已消除,盲目重试只是掩盖。

4.3 周期超时(时序类)

/* 用 ABSTIME 醒来时,比较当前时间与期望时间 */
struct timespec now;
clock_gettime(CLOCK_MONOTONIC, &now);
int32_t late_us = diff_us(now, expected);
if (late_us > budget_us) {
    overrun_count++;
    /* 记录 late 分布,超过阈值触发降级 */
}

"超了怎么办"比"超了报错"重要得多,三个层级:偶发小幅超时(< 周期的 10%,经验区间)→ 记录不动作;连续超时 → 报警并检查是什么新增负载(篇 39 的时间预算表就是干这个用的);超时过半周期 → 本拍跳过 send(不 queue)比"延迟发送"更安全——延迟发送等于改变总线的节拍相位,DC 系统里会把 SYNC0 与数据到达的关系拉坏。

4.4 状态轮询与故障恢复的握手细节

check_slave_config_state 里除了 AL 状态,还有三个标志位值得单列:

  • online:从站还在总线上吗(链路层视角);
  • requested_state vs al_state:请求态与实际态是否一致——不一致就是状态机正在迁移或迁移失败;
  • link_state:链路质量。

三个组合出四种典型状态:online=1 且 al=OP 是常态;online=1 但 al 掉到 SAFEOP 通常是 WKC 持续异常被从站主动降级(先修链路再看状态机,顺序别反);online=0 但 al 还显示旧值说明从站刚掉、状态还没结算完;online 在 0/1 之间反复跳是链路不稳(接头、干扰、冗余切换抖动),此时任何上层恢复动作都别做——先止抖。恢复动作只应该在状态稳定后触发一次,而不是每拍重试:状态机在迁移中再请求迁移,IgH 会排队但 fsm 时间线被拉长,表现为配置越来越慢。

4.5 模板之外的三条纪律

  1. 周期路径里不许有分配。malloc、新开 fd、printf 都可能在分配路径上被抖动拖住(参照 D7 期 rtmutex/malloc 那几篇的结论)。IgH 周期 API 本身无分配,你的应用也要守住这条线;
  2. 错误日志从周期路径摘出去。日志写文件是阻塞操作,周期内只能写环形缓冲/无锁队列,由低优先级线程落盘;
  3. 每个 check 函数保留"上次状态"做边沿触发。每拍打印全状态等于日志洪水,边沿触发(状态变化才记录)才能让日志可读。

五、进阶场景:多 domain 与双节拍

单 domain 单节拍覆盖大多数场景,但两类需求会逼出多 domain 结构:

场景一:不同刷新率共存。 伺服轴要 250μs 刷,慢速 I/O 1ms 刷就够。做法:两个 domain,两个(或一个)实时线程各自用自己的节拍驱动自己的 domain 的 process/queue/send/receive。几个约束要写进设计文档:快 domain 的帧预算独立核算(篇 39 的表按 domain 分别建);慢 domain 的节拍相位与快 domain 错开(避免两 domain 的 send 挤在同一瞬间,B 桶瞬时翻倍);从站同时挂在两个 domain 上时,各自条目独立登记,从站侧 SM 是共享的——这意味着慢 domain 的 SM 更新被快节拍"捎带"刷新,这是允许且常见的。

场景二:关键数据与诊断数据分域。 把 WKC 核算责任分开:控制闭环数据一个 domain(WKC 异常立即降级),诊断/参数类数据另一个 domain(WKC 异常只记日志)。这样诊断链路的抖动不会污染控制链路的故障判定——评审时这条经常被问到,提前想好回答口径。

多 domain 的调用顺序纪律:每个 domain 的 process/queue 只对该 domain 生效,但 send/receive 是 master 级的(发的是 master 队列里所有 QUEUED 报文)。所以多线程分别驱动两个 domain 时,send/receive 必须互斥(加锁或合到一个线程),否则两个线程同时 pack/send 会踩 datagram 队列——这是多 domain 系统排障的头号坑。

六、日志与错误码:出错之后怎么找原因

IgH 的报错风格是"内核日志为主、返回值简短"。标准排障路径:

  1. dmesg 先看。主站的内核态日志全部进 dmesg,关键行有固定前缀(如 EtherCAT 0:),能过滤出单主站的时间线。配置失败、身份不符、SM 校验错误、fsm 中途失败,原因都会写在这里——API 返回 -1 只告诉你失败了,为什么失败在 dmesg 里;
  2. 返回值三档语义:0 成功;-1 通用失败(查日志);-EAGAIN/-EBUSY 等 errno(对象状态不对,多半是调用顺序违反了篇五自查表);
  3. 运行期诊断三件套(ethercat 命令行工具):ethercat master(主站状态、丢帧计数)、ethercat domains -v(datagram/WKC 细节)、ethercat slaves(从站 AL 状态与错误码)。周期运行中也可以调,工具走的是非周期通道,不影响实时任务;
  4. AL 状态错误码:从站掉 OP 时,ethercat slaves 显示的 AL 状态码(如 0x001B 输出看门狗)是硬件口径,与主站软件错误不同源——别拿主站日志硬套从站错误码,两边是两套语义(呼应篇 36 的"像 DC 其实不是"判读)。

给一个"配置失败三连查"的固定动作:activate 失败 → dmesg 最后 50 行 → ethercat slaves 看身份与 AL 状态 → 对照篇 38 第二节逐项核对配置。三步覆盖 90% 的启动期失败。

七、SDO 下发的时机与两种模式

从站参数(如驱动器的电流环增益、编码器分辨率)通过 SDO 写入。ecrt 提供两组接口,行为模式不同,放错位置是又一类高频错误:

配置期 SDO(推荐):ecrt_slave_config_sdo8/16/32/... 系列。这些调用把 SDO 写登记进配置对象,激活时随配置状态机统一下发。优势:从站尚未进 OP 时也能写(配置态走邮箱,状态机自己保证时序);激活失败会带着 SDO 错误一起暴露;代码顺序与下发顺序解耦。周期应用里的参数下发一律用这组。

运行期 SDO(慎用):ecrt_master_sdo_download() 系列在运行态直接下发。它走非周期报文通道(篇 37 讲过 ext datagram 队列),调用方需要处理超时与重试。适用场景:运行中的在线整定、诊断工具。不适合在启动序列里代替配置期 SDO——启动期总线还没稳定,非周期报文成功率没有保障。

两个工程细节:

  1. SDO 下发顺序有依赖:部分从站要求先写某参数再写另一参数(比如先设编码器分辨率再设位置环增益)。配置期接口按登记顺序下发,登记顺序就是代码书写顺序,把有依赖的参数放相邻行并加注释,别依赖"从站应该能容忍乱序";
  2. SDO 写完从站可能要重启或重新初始化才生效:常见于协议类参数(模式选择、通讯周期)。这类参数要么在从站断电保存后重新上电验证,要么明确确认从站支持运行中生效——"写了但没生效"的排查,先查从站手册的生效条件,再怀疑主站。

八、完整启动模板与实时框架差异

把前几节拼成可落地的启动流程(伪代码骨架,非实测,按你的框架改写):

/* main: 配置线程(低优先级) */
signal_handlers_install();            /* 退出信号 → running=0 */
master = ecrt_request_master(0);
/* …… 2.2-2.4 全部配置动作 …… */
ecrt_master_activate(master);

/* 实时线程:高优先级启动,等配置线程放行 */
lock_all_memory();                    /* mlockall,D5 期结论 */
set_fifo_priority(90);                /* 低于内核线程,高于普通任务 */
bind_to_isolated_core(2);             /* 隔离核,D8 期方法 */
rt_thread_create(cycle_task, domain1);
rt_thread_join();                     /* 等周期任务退出 */

ecrt_master_release(master);          /* 最后释放 */

启动顺序的三个设计点:

  1. 配置放普通线程、周期放实时线程:activate 可能要几百毫秒,绝不能在实时线程里做。配置线程完成 activate 后再放行实时线程,中间用一个原子标志交接;
  2. mlockall 在实时线程启动前:先锁后跑,首次缺页不进周期(D5 期 mlockall 手册的完整方法直接套用);
  3. 优先级要给内核线程让路:主站周期线程不是系统里最高的——softirq/irq 线程、kworker 在 RT 内核下是 FIFO 高优先级,应用线程压在它们之下(数值上低 10-20,经验取值),否则反向压制内核线程反而拖慢网卡收包。

三种实时框架的差异只有"外壳":

框架睡眠/节拍需要注意的差异
pthread + PREEMPT_RTclock_nanosleep(CLOCK_MONOTONIC, ABSTIME)本文默认写法;注意 D8 期隔离核与 IRQ 亲和配套
Xenomai(cobalt)clock_nanosleep(CLOCK_MONOTONIC) 走 cobalt 系统调用双核架构下 ecrt 的内核路径与 Xenomai 调度并存,网卡中断归属要统一规划;IgH 提供 xenomai/rtdm 示例
RTAIrt_task_wait_period历史项目多见;API 语义同,示例在 examples/rtai

ecrt API 本身在三种框架下语义一致(它是内核态主站 + 用户态库),差异全在节拍与优先级管理层。换框架不换调用顺序——篇九自查表跨框架有效。

还有一条跨框架都成立的提醒:示例代码 ≠ 推荐实践。examples/ 里的工程为了演示 API 把很多动作塞在 main 里(配置与周期同线程、activate 后立即进循环、错误处理只打日志)。拿示例当起点没问题,但要按本篇的结构拆开:配置线程、实时线程、退出路径三件事各归各位,否则示例的偷懒会原样搬进产线代码。

退出路径也要设计:信号进来 → running=0 → 周期线程跑完当前拍退出 → 输出到安全值(或从站掉 OP)→ master_release。跳过安全值直发 release,从站看门狗会在超时后自己掉输出——两种行为选哪种,是工艺安全评审的事,代码里显式写注释注明选了哪种。

九、一张自查表:调用顺序的 10 条约束

#约束违反后果
1request_master 在一切之前直接失败
2slave_config 在 domain 登记之前登记失败
3pdos/sdos/dc 都在 activate 前不生效或 activate 失败
4activate 在第一个实时节拍前配置状态机与周期抢时间
5process 在读输入前读到旧数据
6queue 在写输出后输出晚一拍(或被无意提前发出)
7send 在 queue 后本拍报文发不出去
8receive 在 send 后WKC/输入永远差一拍
9状态轮询限频,不每拍 ioctl白白增加周期负载
10周期路径零分配零阻塞抖动(回看 D7-D9 系列)

把这张表贴在代码评审时对着查,比读十篇博客有效。使用时三个提示:

  1. 约束 5/6/7/8 是同一拍的内部顺序,违反它们不会报错,只会产生"数据旧一拍""输出晚一拍"这类不易察觉的行为偏差——所以这四条不能靠运行时验证,只能靠代码评审;
  2. 约束 2/3/4 是启动期的顺序,违反会被 phase 检查或 activate 拦下,dmesg 里能看到原因(呼应第六节)。启动期错误好查,别把精力浪费在"为什么编译不过"之前,先跑一遍看日志;
  3. 这张表与篇 37 的三层对象一一对应:约束 2/3 发生在 config/domain 层,5-8 发生在 datagram/master 层。评审某一行有问题时,回篇 37 找对应对象的实现,就能看出违反的机制。
Logo

有“AI”的1024 = 2048,欢迎大家加入2048 AI社区

更多推荐