RSSP-I安全通信协议软件使用说明书-B.1

名称RSSP-I安全通信软件使用说明书编号版本编制工　艺校核标准化审核批准版本号更改人更改日期更改说明变更编号A.1陈昕系统创建（自动生成）A.2陈昕2016-6-12创建全文A.3陈昕2016-8-8增加Rsp1_Open函数，修改Rsp1_PackageData函数描述A.4陈昕2016-9-26按评审意见修改A.5陈昕2016-10-14修改使用条件中对于通信周期限制的描述B.1陈昕2017-12-21增加LEU通信相关接口描述；增加GetRunningCode函数接口描述；目 次1　目的和范围1.1　目的本文描述了RSSP-I安全通信协议软件的接口方式与具体方法。预期读者为上层应用开发用户及验证、确认人员等。1.2　范围本文适用于RSSP-I安全通信协议软件使用说明。2　性引用文件本文档所引用的轨道交通信号系统通用安全计算机平台文档，凡是标注版本的，只有标注版本适应本文档；没有标注版本的，则引用文档的最新版本适用于本文档。表1　序号标准/文件编号标准/文件名称备注1运基信号【2010】267号RSSP-I铁路信号安全通信协议3　参考资料表2　序号文件编号文件名称备注————————4　术语和缩略语术语和缩略语见表3。表3　序号术语/缩略语描述1LEULinesideElectronicUnit，轨旁电子设备2RSSPRailwaySignalSafetyProtocol铁路信号安全协议。5　概述6　时序接口轨道交通信号系统应用需在系统运行的不同阶段调用RSSP-I安全通信协议软件提供的不同函数接口用于实现相应的功能：1）初始化阶段系统应执行Rsp1_Init函数，完成对协议栈的初始化及参数配置；2）每个运行周期需要执行Rsp1_UpdateClock，以更新协议栈时钟；3）当接收到数据后，应用需要调用Rsp1_CheckPackage用以验证数据包有效性并更新协议栈；4）当需要发送数据时，应用需要调用Rsp1_PackageData用以打包需要发送的实时安全数据；5）当设备需要断开与某个外部设备的链接时，调用Rsp1_Close后，协议栈将拒绝对该外部设备发送过来的数据；当需要重新打开时，调用Rsp1_Open功能。6）设备通过调用Rsp1_GetChanelStatus获得某条链路状态及该链路上一包有效数据接收周期距当前周期数。7）当系统处于两系运行时，设备主系可在每周期所有Rsp1_PackageData函数执行后调用Rsp1_GetSynData，用以获取当前协议栈所有链路运行状态；8）当系统处于两系运行时，设备备系可在每周期Rsp1_UpdateClock函数执行前调用Rsp1_SetSynData，用以将主系协议栈数据同步到备系。系统初始化阶段示例如下图：图1　RSSP-I安全通信协议软件初始化LEU接口使用LEU_Init函数。系统每周期与RSSP-I安全通信协议软件接口接口示例如下：图2　RSSP-I安全通信协议软件接口调用顺序注：虚线框内接口应根据轨道交通信号系统应用实际情况调用，不强制调用。对于LEU操作如下流程图：图3　LEU通信接口接口调用顺序7　使用条件RSSP-I安全通信协议软件可用于：封闭式传输系统中的轨道交通信号系统信号设备；加入加密等，满足开放式传输系统防护条件的开放式传输系统中的轨道交通信号系统信号设备；适用于嵌入式、PC、工作站及服务器等硬件环境。RSSP-I安全通信协议软件可通过源码、链接库（可通过C或C编译器编译生成）等方式被轨道交通信号设备使用。RSSP-I安全通信协议软件应用于2乘2取2安全计算机平台时，可使用RSSP-I安全通信协议软件提供的获取同步数据接口及同步数据设置接口对主备系间协议状态进行同步，以保证主备系切换时，通信可以维持。RSSP-I安全通信协议软件应用于热备或其他计算机平台时，建议周期性使用RSSP-I安全通信协议软件提供的获取同步数据接口及同步数据设置接口对主备系间协议状态进行同步，以保证系别切换时，通信可以维持。如果不进行同步，可能会造成若干周期的通信中断。RSSP-I安全通信协议软件应集成在固定周期的轨道交通信号系统中的子系统应用中或轨道交通信号系统中的子系统应用按照固定周期触发RSSP-I安全通信协议软件。须满足基本运行硬件要求500K字节以上运行内存、10K字节以上的配置文件存储空间，并保证分配内存与配置文件存储空间独立。RSSP-I安全通信协议软件对传输系统的物理层和链路层无特定依赖，但需要用户考虑传输系统中的网络传输负载、带宽及网络拓扑等因素是否合理，并保证实时数据帧、对时请求帧、对时应答帧可以传输到对方。用户应正确使用RSSP-I安全通信协议软件提供的接口。目前RSSP-I安全通信协议软件仅进行了时代电气安全计算机平台提供的WindRiverCert平台编译器的确认测试，如用于其他平台或更换编译器、更换处理器，需要对使用的编译器、处理器进行确认测试，并对RSSP-I安全通信协议软件功能进行重新确认测试。8　数据类型定义表4　数据类型表数据类型原型说明UTinytypedefunsignedchar无符号8位UShorttypedefunsignedshort无符号16位ULongtypedefunsignedlong无符号32位S_MsgtypedefstructTAG_Msg{UShortlength;UTinybuff[c_BUFF_SIZE];}S_Msg;应用数据帧结构体S_SsMsgtypedefstructTAG_SsMsg{UShortlength;Tinybuff[c_SSR_SIZE];}S_SsMsg;对时数据结构体E_BooltypedefenumTAG_Bool{r_FALSE=0x05555555U,r_TRUE=0x0AAAAAAAU}E_Bool;自定义布尔枚举9　应用接口函数9.1　Rsp1_Init表5　接口函数Rsp1_Init描述接口函数Rsp1_Init原型声明E_BoolRsp1_Init(constUShortselfDevId_U16,constUShortinCfgLen_U16,UTiny*constinCfgBuf);包含文件提供方Rsp1组件调用方上层应用形参描述UShortselfDevId_U16:本设备ID;UShortinCfgLen_U16：配置数据长度；UTiny*inCfgBuf：配置数据缓存区首地址。返回值描述配置成功，返回r_TRUE；配置失败，返回r_FALSE。功能描述检查传入配置是否完整，如配置完整，初始化协议栈配置。为协议栈分配空间。该函数在系统初始化阶段调用。函数检查了传入的配置数据区域CRC的正确性，如果CRC检查正确，则执行初始化过程，否则将协议栈内容数据置为0。9.2　Rsp1_UpdateClock表6　接口函数Rsp1_UpdateClock描述接口函数Rsp1_UpdateClock原型声明voidRsp1_UpdateClock(void);包含文件提供方Rsp1组件调用方上层应用形参描述无返回值描述无功能描述更新周期时钟。该函数在系统执行每个通信周期都需要进行调用，如未每个通信周期进行调用，将导致所有通信链路通信状态判断错误。9.3　Rsp1_PackageData表7　接口函数Rsp1_PackageData描述接口函数Rsp1_PackageData原型声明UTinyRsp1_PackageData(constUShortinDstDevId_U16,constS_Msg*inMsg,S_Msg*outMsg,S_SsMsg*outSseMsg,S_SsMsg*outSsrMsg);包含文件提供方Rsp1组件调用方上层应用形参描述UShortinDstDevId_U16：设备识别号；S_Msg*inMsg：需要封装的数据；S_Msg*outMsg：封装后的数据；S_SsMsg*outSseMsg：封装后的对时请求数据;S_SsMsg*outSsrMsg：封装后的对时应答数据。返回值描述错误的数据接收方类型或识别号，返回0；打包数据长度大于最大允许长度，返回1；打包TSD和对时帧（SSR或SSE），返回2；已打包TSD，返回3。功能描述如发送对象的设备不在配置数据中，需要向上层应用汇报，并拒绝组帧。如发送数据大于最大应用数据允许长度(1200字节)，需要向上层应用汇报，并拒绝组帧。当查找到对应设备且发送数据在允许应用数据允许长度内时，则填入指定缓冲进行组帧。数据帧与对时帧（SSE与SSR）缓冲需要分开。并分别告知上层应用打包后的数据帧和对时帧数据包长度。9.4　Rsp1_CheckPackage表8　接口函数Rsp1_CheckPackage描述接口函数Rsp1_CheckPackage原型声明UTinyRsp1_CheckPackage(constUShortinDstDevId_U16,constUShortinLen_U16,UTiny*inBuf,UShort*outLen,UTiny*outBuf);包含文件提供方Rsp1组件调用方上层应用形参描述UShortinDstDevId_U16：设备识别号；UShortinLen_U16：需要校验数据长度；UTiny*inBuf：需要校验的数据起始地址；UShort*outLen：校验后的数据长度存放地址；UTiny*outBuf：校验后的数据起始地址。返回值描述错误的数据来源设备类型或识别号，返回0；接收数据长度大于最大允许长度，返回1；接收到SSE或SSR，返回2；接收到RSD，返回3。功能描述如填入数据长度大于协议允许数据长度，协议拒绝进行解析。当填入数据长度小于等于协议允许数据长度，协议栈检查传入的数据帧缓冲区，对不同的帧类型做判断：如为SSE帧，则反馈SSR帧；如为SSR帧，则更新本地连接序列号及时间戳；如果是数据帧，则对时间戳、序列号等做检查，如果在容忍范围内则认为该数据帧有效，更新通信链路状态，并将应用数据缓冲返回给上层应用。如时间戳、序列号超出允许范围或CRC校验失败，则需要丢弃该数据帧。建议安全设备中该函数输出的校验后数据应当Rsp1_GetChanelStatus结果为链路状态正常时才予以选用。9.5　Rsp1_Close表9　接口函数Rsp1_Close描述接口函数Rsp1_Close原型声明E_BoolRsp1_Close(constUShortinDstDevId_U16);包含文件提供方Rsp1组件调用方上层应用形参描述E_BoolinDstDevId_U16：数据接收方设备识别号。返回值描述关闭已关闭链路，返回r_TRUE；成功关闭链路，返回r_FALSE。功能描述将输入设备类型、设备识别号对应的链路置为关闭状态，协议栈将拒绝对应设备传入数据。如果传入设备无法找到时，将向上层汇报，并返回链路关闭失败。只有当查找到传入设备时，且链路处于打开状态，则关闭链路并返回“真”。9.6　Rsp1_Open表10　接口函数Rsp1_Open描述接口函数Rsp1_Open原型声明E_BoolRsp1_Open(constUShortinDstDevId_U16);包含文件提供方Rsp1组件调用方上层应用形参描述E_BoolinDstDevId_U16：数据接收方设备识别号。返回值描述打开已关闭链路，返回r_TRUE；成功打开链路，返回r_FALSE。功能描述将输入设备类型、设备识别号对应的链路置为打开状态，协议栈将允许对应设备传入数据。如果传入设备无法找到时，将向上层汇报，并返回链路打开失败。只有当查找到传入设备时，且链路处于关闭状态，则打开链路并返回“真”。9.7　Rsp1_GetChanelStatus表11　接口函数Rsp1_GetChanelStatus描述接口函数Rsp1_GetChanelStatus原型声明E_BoolRsp1_GetChanelStatus(constUShortinDstDevId_U16,UShort*constoutCycDiff);包含文件提供方Rsp1组件调用方上层应用形参描述UShortinDstDevId_U16：设备识别号。UShort*outCycDiff：返回的当前周期与上一次接收有效数据包的周期差值。返回值描述链路状态故障，返回r_FALSE；链路状态正常，返回r_TRUE。功能描述如果传入设备无法找到时，将向上层汇报，并返回断开状态及累计时钟值。只有当查找到传入设备时，则链路连接状态是否正常，并返回本周期协议栈时钟与上一有效数据帧接收周期时钟差值。9.8　Rsp1_GetSynData表12　接口函数Rsp1_GetSynData描述接口函数Rsp1_GetSynData原型声明UShortRsp1_GetSynData(UTiny*buf);包含文件提供方Rsp1组件调用方上层应用形参描述UTiny*buf：同步数据缓冲首地址。返回值描述返回同步数据字节数。功能描述协议栈同步数据获取接口，获取协议栈时钟、所有链路序列号与时间戳。注：两系运行时，主系应用应每个系统周期结束时调用本函数，备系不能调用本函数。本函数可用中间数据的CRC校验，以避免硬件环境的干扰或失效导致内存数据读写错误对运行数据造成的破坏。9.9　Rsp1_SetSynData表13　接口函数Rsp1_SetSynData描述接口函数Rsp1_SetSynData原型声明voidRsp1_SetSynData(constUTiny*inBuf,UShortinDataLength_U16);包含文件提供方Rsp1组件调用方上层应用形参描述UTiny*buf：同步数据缓冲；UShortinDataLength_U16：同步数据长度。返回值描述无。功能描述接收同步数据时将检查同步数据的CRC及可用链路数，如果校验失败，则向上层汇报，并拒绝同步。如CRC及可用链路数校验通过，则同步数据设置接口，设置协议栈时钟、所有链路序列号与时间戳。注：备系应用应每个系统周期开始时调用本函数，主系不能调用本函数。9.10　Rsp1_GetRunningCode表14　接口函数Rsp1_GetRunningCode描述接口函数Rsp1_GetRunningCode原型声明UShortRsp1_GetRunningCode(UTiny*outBuf);包含文件提供方Rsp1组件调用方上层应用形参描述返回故障码缓冲区。返回值描述本周期故障码长度。功能描述获取本周期故障码。9.11　LEU_Init表15　接口函数LEU_Init描述接口函数LEU_Init原型声明voidLEU_Init();包含文件提供方Rsp1组件调用方上层应用形参描述无。返回值描述无。功能描述初始化LEU接口所需要的内部变量。9.12　LEU_BtmCycle表16　接口函数LEU_BtmCycle描述接口函数LEU_BtmCycle原型声明voidLEU_BtmCycle(constUTinyLEUIndex);包含文件提供方Rsp1组件调用方上层应用形参描述UTinyLEUIndex：LEU序号。返回值描述无。功能描述更新指定序号的LEU的时钟。9.13　LEU_CheckBtmPackage表17　接口函数LEU_CheckBtmPackage描述接口函数LEU_CheckBtmPackage原型声明UTinyLEU_CheckBtmPackage(constUTinyLEUIndex,constUShortinLen_U16,UTiny*inBuf,UShort*outLen,UTiny*outBuf);包含文件提供方Rsp1组件调用方上层应用形参描述UTinyLEUIndex：LEU序号；constUShortinLen_U16：接收到的LEU数据长度；UTiny*inBuf：接收到LEU数据缓冲；UShort*outLen：校验后的数据长度；UTiny*outBuf：校验后的数据缓冲。返回值描述1：无效数据；2：数据帧；3：校时帧功能描述如填入数据长度大于协议允许数据长度，协议拒绝进行解析。当填入数据长度小于等于协议允许数据长度，协议栈检查传入的数据帧缓冲区，对不同的帧类型做判断：如为SSE帧，则反馈SSR帧；如为SSR帧，则更新本地连接序列号及时间戳；如果是数据帧，则对时间戳、序列号等做检查，如果在容忍范围内则认为该数据帧有效，更新通信链路状态，并将应用数据缓冲返回给上层应用。如时间戳、序列号超出允许范围或CRC校验失败，则需要丢弃该数据帧。建议安全设备中该函数输出的校验后数据应当Rsp1_GetChanelStatus结果为链路状态正常时才予以选用。9.14　LEU_PackageBtmData表18　接口函数LEU_PackageBtmData描述接口函数LEU_PackageBtmData原型声明UTinyLEU_PackageBtmData(constUShortLEUIndex,S_Msg*outMsg,S_SsMsg*outSseMsg,S_SsMsg*outSsrMsg);包含文件提供方Rsp1组件调用方上层应用形参描述constUShortLEUIndex：LEU序号；S_Msg*outMsg：输出的BTM帧；S_SsMsg*outSseMsg：输出的BTM对时请求；S_SsMsg*outSsrMsg：输出的BTM对时应答。返回值描述错误的数据接收方类型或识别号，返回0；打包数据长度大于最大允许长度，返回1；打包TSD和对时帧（SSR或SSE），返回2；已打包TSD，返回3。功能描述如发送对象的设备不在配置数据中，需要向上层应用汇报，并拒绝组帧。如发送数据大于最大应用数据允许长度(1200字节)，需要向上层应用汇报，并拒绝组帧。当查找到对应设备且发送数据在允许应用数据允许长度内时，则填入指定缓冲进行组帧。数据帧与对时帧（SSE与SSR）缓冲需要分开。并分别告知上层应用打包后的数据帧和对时帧数据包长度。9.15　LEU_CheckRsdPackage表19　接口函数LEU_CheckRsdPackage描述接口函数LEU_CheckRsdPackage原型声明UTinyLEU_CheckRsdPackage(constUShortLEUIndex,constUShortinLen_U16,UTiny*inBuf,UShort*outLen,UTiny*outBuf);包含文件提供方Rsp1组件调用方上层应用形参描述UTinyLEUIndex：LEU序号；constUShortinLen_U16：接收到的LEU数据长度；UTiny*inBuf：接收到LEU数据缓冲；UShort*outLen：校验后的数据长度；UTiny*outBuf：校验后的数据缓冲。返回值描述1：无效数据；2：数据帧；3：校时帧功能描述如填入数据长度大于协议允许数据长度，协议拒绝进行解析。当填入数据长度小于等于协议允许数据长度，协议栈检查传入的数据帧缓冲区，对不同的帧类型做判断：如为SSE帧，则反馈SSR帧；如为SSR帧，则更新本地连接序列号及时间戳；如果是数据帧，则对时间戳、序列号等做检查，如果在容忍范围内则认为该数据帧有效，更新通信链路状态，并将应用数据缓冲返回给上层应用。如时间戳、序列号超出允许范围或CRC校验失败，则需要丢弃该数据帧。建议安全设备中该函数输出的校验后数据应当Rsp1_GetChanelStatus结果为链路状态正常时才予以选用。9.16　LEU_PackageRsdData表20　接口函数LEU_PackageRsdData描述接口函数LEU_PackageRsdData原型声明UTinyLEU_PackageRsdData(constUShortLEUIndex,S_Msg*inMsg,S_Msg*outMsg,S_SsMsg*outSseMsg,S_SsMsg*outSsrMsg);包含文件提供方Rsp1组件调用方上层应用形参描述constUShortLEUIndex：LEU序号；S_Msg*outMsg：输出的BTM帧；S_SsMsg*outSseMsg：输出的BTM对时请求；S_SsMsg*outSsrMsg：输出的BTM对时应答。返回值描述错误的数据接收方类型或识别号，返回0；打包数据长度大于最大允许长度，返回1；打包TSD和对时帧（SSR或SSE），返回2；已打包TSD，返回3。功能描述如发送对象的设备不在配置数据中，需要向上层应用汇报，并拒绝组帧。如发送数据大于最大应用数据允许长度(1200字节)，需要向上层应用汇报，并拒绝组帧。当查找到对应设备且发送数据在允许应用数据允许长度内时，则填入指定缓冲进行组帧。数据帧与对时帧（SSE与SSR）缓冲需要分开。并分别告知上层应用打包后的数据帧和对时帧数据包长度。9.17　LEU_GetSynData表21　接口函数LEU_GetSynData描述接口函数LEU_GetSynData原型声明UShortLEU_GetSynData(UTiny*outBuf);包含文件提供方Rsp1组件调用方上层应用形参描述UTiny*buf：同步数据缓冲首地址。返回值描述返回同步数据字节数。功能描述协议栈同步数据获取接口，获取协议栈时钟、所有链路序列号与时间戳。注：两系运行时，主系应用应每个系统周期结束时调用本函数，备系不能调用本函数。本函数可用中间数据的CRC校验，以避免硬件环境的干扰或失效导致内存数据读写错误对运行数据造成的破坏。9.18　LEU_SetSynData表22　接口函数LEU_SetSynData描述接口函数LEU_SetSynData原型声明voidLEU_SetSynData(constUTiny*inBuf,UShortinDataLength_U16);包含文件提供方Rsp1组件调用方上层应用形参描述UTiny*buf：同步数据缓冲；UShortinDataLength_U16：同步数据长度。返回值描述无。功能描述接收同步数据时将检查同步数据的CRC及可用链路数，如果校验失败，则向上层汇报，并拒绝同步。如CRC及可用链路数校验通过，则同步数据设置接口，设置协议栈时钟、所有链路序列号与时间戳。注：备系应用应每个系统周期开始时调用本函数，主系不能调用本函数。附　录　AA.1　附录及说明文件符合性检查表表A.1　技术/措施检查表序号检查内容符合性描述说明1————23A.2　附件及说明表A.2　序号名称描述123