Files
STM32F4-Base/IEC60870-Slave/104/business/IEC104_ClockSynchronization.h
T
STF bdcc8b6500
CI / L0 静态门禁 (pre-commit) (push) Failing after 7m46s
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
添加遥控、参数装载、文件传输等业务
2026-11-16 22:19:17 -08:00

247 lines
20 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
* 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 */