程序包 com.darra.ethercat.master

类 Diagnostics

java.lang.Object
com.darra.ethercat.master.Diagnostics
public class Diagnostics extends Object
主站诊断功能 对应 C# Master/Diagnostics.cs 提供诊断计数器重置、全局从站诊断数据快照等

  • 构造器详细资料

    • Diagnostics

      public Diagnostics(short masterIndex)
      创建诊断功能实例
      参数:
      masterIndex - 主站编号

  • 方法详细资料

    • getDiagnosticsPointer

      public com.sun.jna.Pointer getDiagnosticsPointer()
      获取内部诊断数据结构指针 (零拷贝访问)
      返回:
      指针, 失败返回 null

    • getSummaryPointer

      public com.sun.jna.Pointer getSummaryPointer()
      获取诊断摘要指针
      返回:
      指针, 失败返回 null

    • resetDiagnostics

      public void resetDiagnostics()
      重置诊断计数器

    • resetSlavePortErrorCounters

      public boolean resetSlavePortErrorCounters(short slaveIndex)
      重置指定从站的端口错误计数器
      参数:
      slaveIndex - 从站编号
      返回:
      成功返回 true

    • updateSnapshot

      public void updateSnapshot()
      更新诊断数据快照

    • setEnabled

      public void setEnabled(boolean enable)
      启用/禁用诊断数据收集
      参数:
      enable - 是否启用

    • isEnabled

      public boolean isEnabled()
      获取诊断数据收集是否启用
      返回:
      是否启用

    • getExpectedWKC

      public short getExpectedWKC()
      获取期望的 WKC
      返回:
      期望 WKC

    • setExpectedWKC

      public void setExpectedWKC(short expectedWkc)
      设置期望的 WKC
      参数:
      expectedWkc - 期望 WKC

    • getWcDeficit

      public int getWcDeficit()
      WKC 缺口 (= 期望镜像 - 实测镜像, 内核如实算永不下调 expected).

      native short GetWcDeficit 有符号, & 0xFFFF 还原 unsigned.

      返回:
      >0 = 有从站掉 (缺口数, 报警依据); 0 = 全在线或未知 (无 wdk_shm)

    • getWcStateSeq

      public long getWcStateSeq()
      per-slave 诊断序列号 (内核每 PDO 周期 +1, SDK 据此判缓存新鲜度: 停增=内核未跑).

      native long GetWcStateSeq (uint64, Java long 容纳, 内核计数不溢出符号位).

      返回:
      单调递增序号; 0 = 未知 (无 wdk_shm)

    • getMappedSlaveCount

      public int getMappedSlaveCount()
      DLL 已向内核下发映射的 slave 数 (per-slave WKC 契约就绪度).

      native short GetMappedSlaveCount 有符号, & 0xFFFF 还原 unsigned. >0 = WcContributed 可信; 0 = 契约未就绪, 上层应显 "未知" 而非 "掉站".

      返回:
      已映射 slave 数; 0 = 不可信 / 未进 OP / 无 wdk_shm

    • getWkcActualMirror

      public int getWkcActualMirror()
      聚合 LRW WKC 实测镜像 (= 本周期响应 slave 总数, 如实反映硬件现实永不篡改).

      native short GetWkcActualMirror 有符号, & 0xFFFF 还原 unsigned.

      返回:
      总线实测 WKC; 0 = 未知 (无 wdk_shm)

    • getWkcExpectedMirror

      public int getWkcExpectedMirror()
      期望 WKC 镜像 (配置期/进 OP 确定的固定真值, 拓扑固定即固定, 绝不篡改).

      native short GetWkcExpectedMirror 有符号, & 0xFFFF 还原 unsigned.

      返回:
      期望 WKC; 0 = 未知 (无 wdk_shm)

    • getSlaveLinkQuality

      public short getSlaveLinkQuality(short slaveIndex)
      获取从站链路质量 (0-100%)
      参数:
      slaveIndex - 从站编号
      返回:
      链路质量百分比, 失败返回 -1

    • recordPDOCycleStart

      public void recordPDOCycleStart()
      记录 PDO 周期开始

    • recordWKC

      public void recordWKC(short wkc)
      记录 WKC 值
      参数:
      wkc - WKC 值

    • getPDOAvgCycleTimeNs

      public long getPDOAvgCycleTimeNs()
      获取 PDO 平均周期时间 (纳秒).

      [审计修复 roundSDKSAN2] 原经已删除的 native GetPDOAvgCycleTimeNs 取值 (该函数运行库未导出). 改为从 GetCommunicationStats 的 average_cycle_time_us 派生 (微秒 × 1000 = 纳秒), 与真实导出函数一致.

      返回:
      平均周期时间 ns, 异常/无数据返回 0

    • getPDOErrorCount

      public int getPDOErrorCount()
      获取 PDO 错误计数.

      [审计修复 roundSDKSAN2] 原经已删除的 native GetPDOErrorCount 取值 (该函数运行库未导出). 改为从 GetCommunicationStats 的 failed_cycles (失败周期数) 派生, 与真实导出函数一致.

      返回:
      错误计数, 异常/无数据返回 0

    • getCycleStatistics

      public DarraCore.CommunicationStats getCycleStatistics()
      获取 PDO 周期统计快照 (avg/min/max + 失败/超时计数) 字段聚合自 DarraCore.CommunicationStats, 对应 C# Diagnostics.GetCycleStatistics()
      返回:
      通信统计结构, 异常返回 null

    • getJitterUs

      public double getJitterUs()
      获取 PDO 周期抖动 (max - min, 微秒) 对齐 C# Diagnostics.JitterUs (派生自 CommunicationStats Max/Min).
      返回:
      抖动微秒数, 异常或无数据返回 0

    • getRedundancyStatus

      public DarraCore.RedundancyStatus getRedundancyStatus()
      获取冗余链路状态 (主/副 link up/down) 对齐 C# Diagnostics.RedundancyStatus 派生.
      返回:
      冗余状态结构, null=未启用冗余或未连接

    • isPrimaryLinkUp

      public boolean isPrimaryLinkUp()
      主链路是否连通

    • isSecondaryLinkUp

      public boolean isSecondaryLinkUp()
      副链路是否连通

    • getFailoverCount

      public int getFailoverCount()
      故障切换次数

    • getSmiCount

      public long getSmiCount()
      获取 SMI 检测计数 (System Management Interrupt 累计次数).

      对齐 C# Diagnostics.SmiCount / MasterDiagnosticsInfo.SmiCount: 从 GetSummaryPointer 指向的诊断摘要结构体读取 smi_count 字段 (内核每周期维护, 零帧). DLL 无独立 SMI 计数导出函数.

      返回:
      SMI 总计数, 摘要不可用返回 -1

    • getSmiPeakUs

      public double getSmiPeakUs()
      获取 SMI 峰值抖动 (微秒).

      对齐 C# MasterDiagnosticsInfo.SmiPeakUs: 从诊断摘要结构体读取 smi_peak_us 字段. 原 getSmiMaxLatencyNs 调用的 DLL 函数并不存在, 概念也与 C# 不一致 (C# 暴露的是峰值抖动 µs, 非纳秒延迟), 故按 C# 口径改为峰值抖动.

      返回:
      SMI 峰值抖动 µs, 摘要不可用返回 -1

    • readEtg1510Object

      public byte[] readEtg1510Object(int index, byte subindex)
      通过 ETG.1510 OD 读取主站对象 (managed 实装).

      对应 C# DarraEtherCAT.ReadMasterObject(). ETG.1510 主站 OD 标准索引:

      • 0xF120 — Master Identity (VendorId/ProductCode/Revision/SerialNumber)
      • 0x1018 — Master Identity (CANopen 兼容)
      • 0x8nnn / 0x9nnn / 0xAnnn — Slave-specific objects (Configuration / Information / Diagnosis)
      • 0x10F0 / 0x10F3 — Backup parameter handling / Diagnosis history

      实装策略: 主站自身 OD 通过 SDORead 路由到 slave_index=0 (master OD), 直接复用 已有 FFI 原语. 不再依赖 DLL 端 Diag_Etg1510Read 单独导出.

      参数:
      index - OD 索引 (0x1000-0xFFFF)
      subindex - OD 子索引
      返回:
      读取的字节数据, null=失败

    • writeEtg1510Object

      public boolean writeEtg1510Object(int index, byte subindex, byte[] data)
      通过 ETG.1510 OD 写入主站对象 (managed 实装).

      对齐 C# DarraEtherCAT.WriteMasterObject(). 通过 SDOwrite 路由到 slave_index=0 (master OD), 不依赖 DLL 端单独的 Diag_Etg1510Write 导出.

      参数:
      index - OD 索引 (0x1000-0xFFFF, 常见 0xF120 / 0x1018 / 0x8nnn / 0x9nnn / 0xAnnn)
      subindex - OD 子索引
      data - 写入数据 (不可为 null)
      返回:
      写盘成功返回 true; 参数错误或 SDO 失败返回 false

    • getTopoPriIntact

      public int getTopoPriIntact()
      主拓扑环路完好性 (内核每周期实测). 异常返回 -1.

    • getTopoSecIntact

      public int getTopoSecIntact()
      冗余拓扑环路完好性 (内核每周期实测). 异常返回 -1.

    • hotSwapRebuild

      public int hotSwapRebuild()
      [roundHOTSWAP1 2026-06-08] 运行中一次性热插拔重建拓扑 (重扫从站+重建拓扑图+恢复 OP, 不停总线). 返回错误码: 0=成功, 负值=失败 (-20 BUSY / -21 RESCAN_0 / -22 SDO_ABORT / -23 NO_OP / -24 TIMEOUT / -25 IDX_FULL). 异常返回 -1, 不抛.

    • getRtPreemptCount

      public long getRtPreemptCount()
      RT 线程被抢占累计次数 (uint64). 异常返回 0.

    • getRtPreemptPeakNs

      public long getRtPreemptPeakNs()
      RT 线程被抢占峰值时长 ns (uint32). 异常返回 0.

    • getBigGapUnknownCount

      public long getBigGapUnknownCount()
      大间隙未知原因计数 (uint64). 异常返回 0.

    • getSmiMsrAvailable

      public long getSmiMsrAvailable()
      SMI MSR 是否可用 (uint32, 1=可用). 异常返回 0.

    • getWdkRtCpuIndex

      public int getWdkRtCpuIndex()
      WDK RT 线程绑定 CPU 序号 (-1=未绑). 异常返回 -1.

    • getWdkRxCpuIndex

      public int getWdkRxCpuIndex()
      WDK RX 线程绑定 CPU 序号 (-1=未绑). 异常返回 -1.

    • getWdkJitterInstrumentVer

      public long getWdkJitterInstrumentVer()
      WDK 抖动仪表版本号 (uint32). 异常返回 0.

    • getWdkJitterHistBin

      public long getWdkJitterHistBin(int binIndex)
      WDK 抖动直方图指定 bin 计数 (uint32). @param binIndex bin 索引. 异常返回 0.

    • getWdkJitterTotalSamples

      public long getWdkJitterTotalSamples()
      WDK 抖动样本总数 (uint64). 异常返回 0.

    • getWdkJitterMinNs

      public long getWdkJitterMinNs()
      WDK 抖动最小值 ns (uint32). 异常返回 0.

    • getWdkJitterLastWakeDeltaNs

      public int getWdkJitterLastWakeDeltaNs()
      WDK 上次唤醒偏差 ns (int, 可正可负). 异常返回 0.

    • getWdkPathCountFast

      public long getWdkPathCountFast()
      WDK 快路径处理计数 (uint32). 异常返回 0.

    • getWdkPathCountMed

      public long getWdkPathCountMed()
      WDK 中路径处理计数 (uint32). 异常返回 0.

    • getWdkPathCountSlow

      public long getWdkPathCountSlow()
      WDK 慢路径处理计数 (uint32). 异常返回 0.

    • getWdkKtimerWakeNormalCnt

      public long getWdkKtimerWakeNormalCnt()
      WDK KTIMER 正常唤醒计数 (uint32). 异常返回 0.

    • getWdkKtimerWakeOverrunCnt

      public long getWdkKtimerWakeOverrunCnt()
      WDK KTIMER 超时唤醒计数 (uint32). 异常返回 0.

    • getWdkDispatchCycleMaxJitterNs

      public long getWdkDispatchCycleMaxJitterNs()
      WDK 调度周期最大抖动 ns (uint32). 异常返回 0.

    • getWdkDrainCycleMaxJitterNs

      public long getWdkDrainCycleMaxJitterNs()
      WDK 排空周期最大抖动 ns (uint32). 异常返回 0.

    • getWdkDiagCounter

      public long getWdkDiagCounter(int counterId)
      WDK 通用诊断计数器 (uint32). @param counterId 计数器 ID (见 C# WdkDiagCounter id 表). 异常返回 0.