ecrt 主站 API 手册:周期任务里的调用顺序、时序约束与错误处理
本篇是 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) { /* 创建失败 */ }
注意两个易错点:
- alias 与 position 的匹配规则:position 是环形拓扑上的物理序号(从站跳线/拨码之外由主站按端口顺序编号),alias 是 SII 里写的别名。两个参数都给 0 意味着"总线第一个从站、无别名"——只对单从站或第一个从站安全。多从站系统建议给每个从站写 alias(用 ethercat 命令行工具写 SII),配置代码里按 alias 定位,拓扑重排就不用改代码;
- 身份校验在这里发生:
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 里?位长超了? */
}
这一段是配置序列里最容易出错的地方,三个高频问题:
- syncs 数组与从站实际 SM/PDO 不一致:
ecrt_slave_config_pdos()只检查"你给的映射是否合法",不检查"是否与从站默认映射一致"。映射不一致的后果是激活后数据错位——症状与篇 36 的"DC 不同步"完全不同但抓包同样能看到 WKC 正常,所以映射问题要在激活前用配置核对抓,不要指望运行时报错; - offset 指针的使用:
domain1_regs里每条的最后一个是unsigned int *offset,登记成功后 IgH 把该条目在 domain process data 里的字节偏移写进去。周期任务里访问数据就是base_ptr + *offset。这个偏移在 activate 之后才有效——有人在登记完立刻解引用,读到的是垃圾; - 完整映射 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 的调用顺序,箭头标注顺序约束不可交换的原因。
顺序约束逐条解释:
- process 必须在读数据之前。process 把上一拍收到的帧内容结算进 process data 内存,不 process 直接读,读到的是更旧的数据。反过来 queue 必须在写完输出之后——queue 只是把 datagram 标记为待发,你 queue 之后又写输出,写入的内容会随本拍发出(这在"部分输出希望晚一拍生效"的场景反而是个技巧,但要刻意使用而不是无意为之);
- send 必须在 queue 之后、receive 必须在 send 之后。send 打包并发出所有 QUEUED 报文;receive 收帧、按 index 匹配、结算 WKC。两步在同一拍里先后调用,中间不睡不等;
- receive 的一个细节:它只处理"已经到达的帧"。如果网卡还没收到,receive 直接返回,本拍该 datagram 保持 SENT 状态,下一拍 receive 继续尝试结算——这意味着 WKC 状态天然滞后于周期,偶发的"上一拍数据"不是 bug,是模型本身的性质。对时序敏感的场合(比如需要确认本拍输出已送达从站),IgH 没有原语直接表达"已确认",要靠外部 WKC 与从站反馈设计;
- 状态轮询要限频。check_master_state / check_slave_config_states 内部是 ioctl 或共享状态读取,虽不重,但每拍都查没有意义——常用做法是每 100 拍或每 10ms 查一次,或注册 domain 回调由 IgH 在 WKC 变化时通知;
- 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_statevsal_state:请求态与实际态是否一致——不一致就是状态机正在迁移或迁移失败;link_state:链路质量。
三个组合出四种典型状态:online=1 且 al=OP 是常态;online=1 但 al 掉到 SAFEOP 通常是 WKC 持续异常被从站主动降级(先修链路再看状态机,顺序别反);online=0 但 al 还显示旧值说明从站刚掉、状态还没结算完;online 在 0/1 之间反复跳是链路不稳(接头、干扰、冗余切换抖动),此时任何上层恢复动作都别做——先止抖。恢复动作只应该在状态稳定后触发一次,而不是每拍重试:状态机在迁移中再请求迁移,IgH 会排队但 fsm 时间线被拉长,表现为配置越来越慢。
4.5 模板之外的三条纪律
- 周期路径里不许有分配。malloc、新开 fd、printf 都可能在分配路径上被抖动拖住(参照 D7 期 rtmutex/malloc 那几篇的结论)。IgH 周期 API 本身无分配,你的应用也要守住这条线;
- 错误日志从周期路径摘出去。日志写文件是阻塞操作,周期内只能写环形缓冲/无锁队列,由低优先级线程落盘;
- 每个 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 的报错风格是"内核日志为主、返回值简短"。标准排障路径:
- dmesg 先看。主站的内核态日志全部进 dmesg,关键行有固定前缀(如
EtherCAT 0:),能过滤出单主站的时间线。配置失败、身份不符、SM 校验错误、fsm 中途失败,原因都会写在这里——API 返回 -1 只告诉你失败了,为什么失败在 dmesg 里; - 返回值三档语义:0 成功;-1 通用失败(查日志);-EAGAIN/-EBUSY 等 errno(对象状态不对,多半是调用顺序违反了篇五自查表);
- 运行期诊断三件套(ethercat 命令行工具):
ethercat master(主站状态、丢帧计数)、ethercat domains -v(datagram/WKC 细节)、ethercat slaves(从站 AL 状态与错误码)。周期运行中也可以调,工具走的是非周期通道,不影响实时任务; - 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——启动期总线还没稳定,非周期报文成功率没有保障。
两个工程细节:
- SDO 下发顺序有依赖:部分从站要求先写某参数再写另一参数(比如先设编码器分辨率再设位置环增益)。配置期接口按登记顺序下发,登记顺序就是代码书写顺序,把有依赖的参数放相邻行并加注释,别依赖"从站应该能容忍乱序";
- 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); /* 最后释放 */
启动顺序的三个设计点:
- 配置放普通线程、周期放实时线程:activate 可能要几百毫秒,绝不能在实时线程里做。配置线程完成 activate 后再放行实时线程,中间用一个原子标志交接;
- mlockall 在实时线程启动前:先锁后跑,首次缺页不进周期(D5 期 mlockall 手册的完整方法直接套用);
- 优先级要给内核线程让路:主站周期线程不是系统里最高的——softirq/irq 线程、kworker 在 RT 内核下是 FIFO 高优先级,应用线程压在它们之下(数值上低 10-20,经验取值),否则反向压制内核线程反而拖慢网卡收包。
三种实时框架的差异只有"外壳":
| 框架 | 睡眠/节拍 | 需要注意的差异 |
|---|---|---|
| pthread + PREEMPT_RT | clock_nanosleep(CLOCK_MONOTONIC, ABSTIME) | 本文默认写法;注意 D8 期隔离核与 IRQ 亲和配套 |
| Xenomai(cobalt) | clock_nanosleep(CLOCK_MONOTONIC) 走 cobalt 系统调用 | 双核架构下 ecrt 的内核路径与 Xenomai 调度并存,网卡中断归属要统一规划;IgH 提供 xenomai/rtdm 示例 |
| RTAI | rt_task_wait_period | 历史项目多见;API 语义同,示例在 examples/rtai |
ecrt API 本身在三种框架下语义一致(它是内核态主站 + 用户态库),差异全在节拍与优先级管理层。换框架不换调用顺序——篇九自查表跨框架有效。
还有一条跨框架都成立的提醒:示例代码 ≠ 推荐实践。examples/ 里的工程为了演示 API 把很多动作塞在 main 里(配置与周期同线程、activate 后立即进循环、错误处理只打日志)。拿示例当起点没问题,但要按本篇的结构拆开:配置线程、实时线程、退出路径三件事各归各位,否则示例的偷懒会原样搬进产线代码。
退出路径也要设计:信号进来 → running=0 → 周期线程跑完当前拍退出 → 输出到安全值(或从站掉 OP)→ master_release。跳过安全值直发 release,从站看门狗会在超时后自己掉输出——两种行为选哪种,是工艺安全评审的事,代码里显式写注释注明选了哪种。
九、一张自查表:调用顺序的 10 条约束
| # | 约束 | 违反后果 |
|---|---|---|
| 1 | request_master 在一切之前 | 直接失败 |
| 2 | slave_config 在 domain 登记之前 | 登记失败 |
| 3 | pdos/sdos/dc 都在 activate 前 | 不生效或 activate 失败 |
| 4 | activate 在第一个实时节拍前 | 配置状态机与周期抢时间 |
| 5 | process 在读输入前 | 读到旧数据 |
| 6 | queue 在写输出后 | 输出晚一拍(或被无意提前发出) |
| 7 | send 在 queue 后 | 本拍报文发不出去 |
| 8 | receive 在 send 后 | WKC/输入永远差一拍 |
| 9 | 状态轮询限频,不每拍 ioctl | 白白增加周期负载 |
| 10 | 周期路径零分配零阻塞 | 抖动(回看 D7-D9 系列) |
把这张表贴在代码评审时对着查,比读十篇博客有效。使用时三个提示:
- 约束 5/6/7/8 是同一拍的内部顺序,违反它们不会报错,只会产生"数据旧一拍""输出晚一拍"这类不易察觉的行为偏差——所以这四条不能靠运行时验证,只能靠代码评审;
- 约束 2/3/4 是启动期的顺序,违反会被 phase 检查或 activate 拦下,dmesg 里能看到原因(呼应第六节)。启动期错误好查,别把精力浪费在"为什么编译不过"之前,先跑一遍看日志;
- 这张表与篇 37 的三层对象一一对应:约束 2/3 发生在 config/domain 层,5-8 发生在 datagram/master 层。评审某一行有问题时,回篇 37 找对应对象的实现,就能看出违反的机制。
更多推荐

所有评论(0)