247 lines
20 KiB
C
247 lines
20 KiB
C
/*
|
||
* 104时钟同步(C_CS_NA_1):处理主站COT=6校时及COT=5读时,设备时钟由应用提供。
|
||
* 本模块负责校验、设时时区换算/滞留补偿及应答;实际读/设时由应用提供的回调完成。
|
||
* Handle_Event/Process不调用应用代码;显式执行入口每次至多同步设时或读时一次,不保存回调。
|
||
* 设备日历与协议单调计时分开:设置设备时间不应改变Net提供的单调毫秒基准。
|
||
* 所有接口与Slave在同一线程串行调用;模块内应答严格按请求顺序。
|
||
* 执行后应答进入HIGH,不等待NORMAL排空;校时确认回显原时标,读取回复固定的本地时间快照。
|
||
* 设时TEST只校验并肯定回显,不调用设时action;读TEST仍取只读快照,两类都保持T位。
|
||
* 退出顺序:Cancel -> Slave_Close -> 读空并分派通知 -> Destroy -> Remove_Station -> Slave_Destroy。
|
||
*/
|
||
#ifndef IEC104_CLOCK_SYNCHRONIZATION_H
|
||
#define IEC104_CLOCK_SYNCHRONIZATION_H
|
||
|
||
#include "IEC104_Slave.h"
|
||
#include "IEC60870_Time.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
typedef struct IEC104_ClockSynchronization IEC104_ClockSynchronization_t;
|
||
|
||
typedef struct {
|
||
int16_t master_utc_offset_minutes; /* 仅用于设时源时间:主站标准当地时间减UTC,-1439..1439分钟,默认480。
|
||
* 不含SU;读取回复固定为本站UTC+8标准日历,不受此配置影响。 */
|
||
uint32_t execute_timeout_ms; /* 受理至读/设时执行检查的期限,单位ms,默认15000;0禁用,仍检查时间范围。 */
|
||
} IEC104_ClockSynchronizationConfig_t;
|
||
|
||
/* 交给action的只读纯值请求,指针仅在本次回调期间有效。
|
||
* utc_ms/local_time已补偿受理至base_ms的等待;应用不再叠加时区或同一段等待。
|
||
* 不补偿网络、Slave通知FIFO及action内部耗时;base_ms不是硬件实际生效时刻。 */
|
||
typedef struct {
|
||
uint64_t generation, receive_serial; /* generation:原TCP会话代次;receive_serial:原I帧接收流水号。 */
|
||
uint64_t station_id; /* 定向请求的原站点注册编号,不是CA;广播为0,不绑定某个目标站。 */
|
||
uint16_t common_address; /* 请求原CA,广播保留65535;逐站确认的CA由模块另行填写。 */
|
||
uint8_t originator_address; /* 请求原OA,供应用识别发起方;本字段不是权限校验结果。 */
|
||
IEC60870_CP56Time2a_t master_time; /* 原CP56解码值,IV=0,保留主站日历和SU;未作时区换算及滞留补偿。 */
|
||
IEC60870_WallTime_t local_time; /* 对应base_ms的固定UTC+8标准日历,可直接交给Clock_Set或RTC适配。 */
|
||
uint64_t utc_ms; /* 对应base_ms的UTC纪元毫秒,自1970-01-01 00:00:00 UTC起算。 */
|
||
/* accepted_ms:Handle_Event受理时刻;base_ms:执行检查时刻。均为Net单调毫秒,允许为0。 */
|
||
uint64_t accepted_ms, base_ms;
|
||
} IEC104_ClockSynchronizationRequest_t;
|
||
|
||
/* 交给只读回调的请求身份;无主站时间,因为COT=5的七字节时间域必须全零。
|
||
* 指针仅在本次回调期间有效,不表示模块保存了应用时钟或采样结果。
|
||
* accepted_ms是Handle_Event受理tick,base_ms是本次执行检查tick,均不是RTC实际采样或发送时刻。
|
||
* 回调负责取得当前日历;读时动作不使用设时的等待补偿,也不更改同步基准。 */
|
||
typedef struct {
|
||
uint64_t generation, receive_serial, station_id; /* 同设时身份;广播station_id为0。 */
|
||
uint16_t common_address; /* 原CA;广播保留65535,回复按受理时的目标快照逐站填写。 */
|
||
uint8_t originator_address;
|
||
bool is_test; /* 读TEST仍可取只读快照并回显T位,但不得产生设时副作用。 */
|
||
uint64_t accepted_ms, base_ms;
|
||
} IEC104_ClockSynchronizationReadRequest_t;
|
||
|
||
/* 应用同步设时动作:context由Execute_Next原样传入,允许NULL;request为本次校验后的只读请求。
|
||
* true报告设置成功,false未报告成功;false不保证时钟未变,模块不提供硬件回滚。
|
||
* 须短时完成,不保留request指针等待异步执行;权限、允许回拨幅度和设备操作由应用判断。
|
||
* 不得重入本模块的修改入口或推进Slave事件循环;回调内仅允许查询本模块Get_Status。
|
||
* 每条通过执行检查的新请求各调用一次,不按内容去重;主站重发旧时标仍可能再次回拨。 */
|
||
typedef bool (*IEC104_ClockSynchronizationAction_t)(void *context,
|
||
const IEC104_ClockSynchronizationRequest_t *request);
|
||
|
||
/* 应用同步读时动作:context原样传入且允许NULL,request仅供本次读取身份/TEST信息,time为非NULL输出。
|
||
* 成功返回固定UTC+8标准本地日历,不按master_utc_offset_minutes解释;合法IV=1可表示未同步时间。
|
||
* time在调用前清零;true后仍校验2000..2099日期、IV/has_weekday为0/1且SU=0,再按日期带星期。
|
||
* 回调日历必须已经是标准本地时间,SU=1也视为非法,不通过单独清标志改变其含义。
|
||
* true且日历合法时P/N=0,时标IV原样保留;IV=1不是读取失败,也不意味着设备已取得同步。
|
||
* false时忽略输出;false或输出非法均回复COT=5、P/N=1及已受理请求的原全零占位。
|
||
* 每条合法请求(含TEST、广播)至多调用一次;广播各目标共享该快照,不逐站重新读取。
|
||
* 主站再次发来的新读请求会重新取样;发送WAIT重试同一请求则不重读、不补偿传输等待。
|
||
* 与设时action相同,只能短时同步完成,不保存指针、不推进Slave或重入修改接口;Get_Status可用。 */
|
||
typedef bool (*IEC104_ClockSynchronizationReadAction_t)(void *context,
|
||
const IEC104_ClockSynchronizationReadRequest_t *request, IEC60870_CP56Time2a_t *time);
|
||
|
||
typedef enum {
|
||
IEC104_CLOCK_SYNCHRONIZATION_EVENT_ERROR = -1, /* 参数、事件归属、重入或内部准备失败。 */
|
||
IEC104_CLOCK_SYNCHRONIZATION_EVENT_IGNORED = 0, /* 非103 I帧或本模块当前不能接手的通知。 */
|
||
IEC104_CLOCK_SYNCHRONIZATION_EVENT_HANDLED = 1 /* 含拒绝和丢新,不表示已应答。 */
|
||
} IEC104_ClockSynchronizationEventResult_t;
|
||
|
||
typedef enum {
|
||
IEC104_CLOCK_SYNCHRONIZATION_EXECUTE_ERROR = -1, /* 参数、缺少所需回调、重入或服务查询失败;未调用应用。 */
|
||
IEC104_CLOCK_SYNCHRONIZATION_EXECUTE_EMPTY = 0, /* 无可执行请求;仍可能有待提交应答。 */
|
||
IEC104_CLOCK_SYNCHRONIZATION_EXECUTE_WAIT = 1, /* 先处理未读Slave通知。 */
|
||
IEC104_CLOCK_SYNCHRONIZATION_EXECUTE_OK = 2 /* 已调用一次读/设时动作;回复可能因后续STOP/故障取消。 */
|
||
} IEC104_ClockSynchronizationExecuteResult_t;
|
||
|
||
/* 只读调度快照;计数从Create起累计,Cancel及连接启停不清零,不代表对端已经收到应答。 */
|
||
typedef struct {
|
||
uint64_t generation; /* 已分派给模块的会话代次;消费DISCONNECTED后为0。 */
|
||
bool active; /* 模块根据已分派通知及推进结果维护的激活状态,不替代当前网络状态查询。 */
|
||
bool events_pending; /* Slave尚有未读通知;应先NextEvent并按FIFO分派,再执行或续发。 */
|
||
bool execute_pending; /* 仍有待执行的读/设时请求;不保证当前会话、期限已允许调用应用。 */
|
||
bool read_pending; /* execute_pending中尚未取样的COT=5请求,包含TEST;回调中及取样后待发均不在此项。
|
||
* false不表示读回复已交接,仍须结合pending_requests并持续Process。 */
|
||
bool confirm_pending; /* 设时action已开始且确认未全部接手,含回调期间;不含读取、设时TEST及校验失败。 */
|
||
bool need_process; /* 当前有状态清理、到期或待尝试回复;false仍不能跳过每轮Process的WAIT重试。 */
|
||
bool timer_active; /* 存在尚未执行且启用了执行期限的请求。 */
|
||
uint32_t timeout_remaining_ms; /* 所有执行期限的最小剩余ms;到期为0,无计时任务时也为0。 */
|
||
unsigned pending_requests; /* 占用任务槽数,含待执行、回调中及待回复;一条广播始终只占一槽。 */
|
||
/* accepted:合法且成功入槽的请求数,含TEST及后来超时/取消者。
|
||
* executed:设时action已返回的次数;synchronized:其中返回true的次数;读取及TEST不增加两者。 */
|
||
unsigned long accepted, executed, synchronized;
|
||
/* read_executed:只读回调已返回次数,包含TEST;read_succeeded:其中true且输出合法的次数,含IV=1。
|
||
* 按请求而非广播目标计数;回调期间尚未累计,发送WAIT或之后取消也不回退已累计的结果。
|
||
* 读失败为两者之差;执行前超时/取消/校验拒绝均不增加它们,也不计入旧executed/synchronized。 */
|
||
unsigned long read_executed, read_succeeded;
|
||
/* submitted:发送层返回OK的ASDU数,广播逐目标计数;negative_submitted为其中P/N=1的数量。 */
|
||
unsigned long submitted, negative_submitted;
|
||
/* rejected:受理校验拒绝数,含无法应答的畸形请求,不含后续超时或action失败。
|
||
* waits:发送返回WAIT的次数,重试可重复累计;不计等待Slave通知的次数。
|
||
* cancelled:取消的占槽请求数,广播部分确认后取消也只计一次,不保证设备时间未变。
|
||
* overloads/dropped_requests:槽满丢新的次数/请求数,同时增加;对象数错误/对象截短只计rejected。
|
||
* timeouts:启用期限时,执行前到期或单调倒退而转否定的请求数。
|
||
* time_errors:执行检查的换算/范围失败,以及禁用期限时的单调倒退,不含受理校验拒绝。 */
|
||
unsigned long rejected, waits, cancelled, overloads, dropped_requests, timeouts, time_errors;
|
||
} IEC104_ClockSynchronizationStatus_t;
|
||
|
||
/**
|
||
* 功能:向config写默认源时区480分钟、执行期限15000ms;config为NULL时无操作。
|
||
* 输入参数:config——配置。
|
||
* 输出参数:config——配置的更新结果。
|
||
* 返回值:无。
|
||
* 说明:只填写配置,不创建实例;调用方可修改后交给Create。
|
||
*/
|
||
void IEC104_ClockSynchronization_Config_Default(IEC104_ClockSynchronizationConfig_t *config);
|
||
/**
|
||
* 功能:为有效slave创建独立校时实例;config须非NULL,按值复制,返回后不再借用配置指针。
|
||
* 输入参数:slave——所属从站服务。
|
||
* config——配置。
|
||
* 输出参数:无。
|
||
* 返回值:按处理分支返回NULL、free_slot。
|
||
* 说明:slave由应用拥有,寿命须覆盖本实例;可在Slave_Init前创建,但必须早于消费该服务的通知。
|
||
* 每服务只允许一个实例,按共用站点表路由;不分配堆内存、不建立监听、不保存应用action。
|
||
* 成功返回池内句柄;参数/配置非法、重复绑定或池/身份资源耗尽返回NULL。
|
||
* IEC104_CLOCK_SYNCHRONIZATION_CAPACITY默认等于TCP服务容量;
|
||
* IEC104_CLOCK_SYNCHRONIZATION_TASK_CAPACITY默认4,限定每实例的任务槽数。
|
||
*/
|
||
IEC104_ClockSynchronization_t *IEC104_ClockSynchronization_Create(IEC104_Slave_t *slave,
|
||
const IEC104_ClockSynchronizationConfig_t *config);
|
||
/**
|
||
* 功能:归还self占用的静态池槽;true成功,成功后必须停止使用旧句柄。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:!Owned(self) || self->in_action || self->count != 0U时返回false;其余分支返回false、true。
|
||
* 说明:句柄无效、仍有占槽任务或处于action回调中返回false;不隐式Cancel,也不关闭Slave。
|
||
*/
|
||
bool IEC104_ClockSynchronization_Destroy(IEC104_ClockSynchronization_t *self);
|
||
/**
|
||
* 功能:取消self的全部占槽任务并归还站点引用/快照,每条请求增加一次cancelled。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:无。
|
||
* 说明:不停用连接,可继续接手后续请求;不撤回已交接帧、不回滚设备时间。
|
||
* 无返回值;无效句柄或action回调中调用均无操作。
|
||
*/
|
||
void IEC104_ClockSynchronization_Cancel(IEC104_ClockSynchronization_t *self);
|
||
/**
|
||
* 功能:将event按Slave FIFO次序交给self;event须来自所属Slave的NextEvent或合法Copy_Event副本。
|
||
* 输入参数:self——本模块实例。
|
||
* event——事件。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:按处理分支返回IEC104_CLOCK_SYNCHRONIZATION_EVENT_ERROR、IEC104_CLOCK_SYNCHRONIZATION_EVENT_HANDLED、IEC104_CLOCK_SYNCHRONIZATION_EVENT_IGNORED、Request(self, event, &identity)。
|
||
* 说明:所有连接/启停通知都须分派,103 I帧由本模块接手;不修改输入事件,不调用action。
|
||
* COT=6校时保持原契约:合法非TEST进入待设时;合法TEST只回肯定ACT_CON,不调用设时action。
|
||
* COT=5读取只接受16字节、SQ=0、单对象、IOA=0和七个零字节;不解码占位日期,含TEST均进入待读时。
|
||
* COT/CA/IOA优先回45/46/47;其余可对应的非法请求校时否定7、读取否定5,并保留T位及请求原文。
|
||
* 非零读占位属于受理拒绝,否定回复保留其原内容;只有已受理的读失败/超时才自然回显七个零字节。
|
||
* 不能保留唯一完整对象时仅计拒绝,槽满丢新并计数、不断链。错误回复可当场提交。
|
||
* 广播只执行一次读/设时,按受理时快照逐站回复;已删除的待提交目标跳过,新注册站不参与。
|
||
* 读TEST/广播/失败的处理是本模块明确的接入策略,不把读TEST当作设时测试或返回全零成功数据。
|
||
* 返回HANDLED包含保存、拒绝、丢新和状态通知处理,不表示已应答;IGNORED表示未接手;
|
||
* ERROR表示参数/归属/重入或内部准备失败,不可作为IGNORED继续生成兜底应答。
|
||
*/
|
||
IEC104_ClockSynchronizationEventResult_t IEC104_ClockSynchronization_Handle_Event(
|
||
IEC104_ClockSynchronization_t *self, const IEC104_SlaveEvent_t *event);
|
||
/**
|
||
* 功能:为self有界推进执行期限及队首回复,不调用action;须在每轮网络推进、通知分派后调用。
|
||
* 输入参数:self——本模块实例。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:ERROR/FATAL已按提交结果清理任务时返回true,false仅表示接口/查询/组包故障。
|
||
* 说明:true表示完成本轮检查,可能仍在等待、已取消任务或没有任务,不表示应答成功。
|
||
* 参数、重入、查询或组包错误返回false。发送ERROR/FATAL取消任务后返回true,
|
||
* 正常STOP待通知的ERROR先让出;应用继续消费Slave通知处理后续断线/启停。
|
||
* 即使need_process为false也须每轮调用,以重试发送WAIT;不能以忙循环代替网络推进。
|
||
*/
|
||
bool IEC104_ClockSynchronization_Process(IEC104_ClockSynchronization_t *self);
|
||
/**
|
||
* 功能:兼容的仅设时入口:action须非NULL,等价于With_Read传入空read_action。
|
||
* 输入参数:self——本模块实例。
|
||
* action——动作回调。
|
||
* context——调用方上下文。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:按处理分支返回IEC104_CLOCK_SYNCHRONIZATION_EXECUTE_ERROR、IEC104_ClockSynchronization_Execute_Next_With_Read(self, action, NULL, context)。
|
||
* 说明:最早待执行操作为读取时返回ERROR,不消费或越过它;应用须用With_Read提供读取回调。
|
||
* 先检查会话、未读通知、期限及补偿范围;每次至多调用一次action,过期请求只转为否定回复。
|
||
* 可越过已生成回复的任务,但不能越过未取快照的读取;确认仍按模块内请求顺序提交。
|
||
* OK表示action已经返回,可能报告失败,确认也可能待发或被后续STOP/故障取消;
|
||
* WAIT表示先处理Slave通知;EMPTY表示已无可执行请求,仍可能有待回复任务;
|
||
* ERROR为参数、缺少所需读回调、重入或服务查询失败。WAIT/EMPTY/ERROR均未调用action。
|
||
* 动作开始后不再判该任务的执行期限;确认发送WAIT只重试确认,绝不重复动作。
|
||
*/
|
||
IEC104_ClockSynchronizationExecuteResult_t IEC104_ClockSynchronization_Execute_Next(
|
||
IEC104_ClockSynchronization_t *self, IEC104_ClockSynchronizationAction_t action, void *context);
|
||
/**
|
||
* 功能:统一执行最早尚需应用处理的读/设时操作;每次至多调用一种回调,不保存回调或context。
|
||
* 输入参数:self——本模块实例。
|
||
* set_action——设置动作回调。
|
||
* read_action——读取动作回调。
|
||
* context——调用方上下文。
|
||
* 输出参数:self——本模块实例的更新结果。
|
||
* 返回值:缺当前回调返回ERROR且保留任务,未读通知返回WAIT,无待执行操作返回EMPTY;
|
||
* 这些返回均不调用应用。
|
||
* 一次回调返回即为OK,即使其结果失败或应答发送WAIT;
|
||
* 说明:至少一个回调非NULL;当前操作缺少对应回调则ERROR,不消费它,不跳到后续操作。
|
||
* 缺回调检查先于本入口的到期推进;应用仍须Process,才能独立处理该任务期限及已有回复。
|
||
* 会话、未读通知及执行期限沿用旧入口;读取超时否定5,设时超时否定7,不调用应用。
|
||
* 读取成功后立即把规范CP56冻结到原16字节任务中;发送WAIT只重发,不重新取时。
|
||
* 取样后可越过此REPLY执行后续设时,读回复仍保持取样时刻;只有队首可提交应答。
|
||
* OK只表示一次回调已返回,读取是否成功见read_succeeded;不表示主站已经收到。
|
||
* WAIT只表示先消费未读Slave通知;发送层WAIT发生在回调之后时,本入口仍返回OK并保存待发快照。
|
||
* EMPTY表示无尚需调用应用的操作,可能仍有回复待发;不能据此停止Process。
|
||
* 读失败/非法输出及合法IV=1的语义见ReadAction;返回WAIT/EMPTY/ERROR均未调用应用。
|
||
*/
|
||
IEC104_ClockSynchronizationExecuteResult_t IEC104_ClockSynchronization_Execute_Next_With_Read(
|
||
IEC104_ClockSynchronization_t *self, IEC104_ClockSynchronizationAction_t set_action,
|
||
IEC104_ClockSynchronizationReadAction_t read_action, void *context);
|
||
/**
|
||
* 功能:将self的当前只读快照写入非NULL的status;true成功,句柄/参数或服务查询失败返回false且不改输出。
|
||
* 输入参数:self——本模块实例。
|
||
* status——状态快照。
|
||
* 输出参数:status——状态快照的更新结果。
|
||
* 返回值:!Owned(self) || status == NULL时返回false;state == IEC104_SLAVE_REQUEST_ERROR时返回false;其余分支返回false、true。
|
||
* 说明:可在读/设时回调内查询,不推进任务、不预留发送资源;当前操作不再计期限,仅设时置confirm_pending。
|
||
* 执行后的确认走HIGH,与NORMAL按发送配额调度,不提供跨队列的时标先后保证。
|
||
* 接手不表示交给SendBuffer,仍在HIGH中的确认可被STOP取消,不重新执行action。
|
||
* confirm_pending仅描述业务状态;事件时间解释与主站处理策略由应用另行约定。
|
||
*/
|
||
bool IEC104_ClockSynchronization_Get_Status(const IEC104_ClockSynchronization_t *self,
|
||
IEC104_ClockSynchronizationStatus_t *status);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* IEC104_CLOCK_SYNCHRONIZATION_H */
|