PTP 模块 - 使用教程
目录
- PTP 模块 - 使用教程
- 简介
- 第 1 步：为主时钟创建一个 PTP 时钟实例
- 第 2 步：添加 PTP 端口
- 第 3 步：查询 PTP 时钟或 PTP 端口的状态
- 第 4 步：清除 FAULTY 状态
- 第 5 步：为 PTP 事件安装处理程序
- 第 6 步：锁定 PTP 时钟
- 第 7 步：获取当前 PTP 时间
简介
在本教程中,您将了解如何使用 PTP 协议在网络中设置时间同步。我们假设您已经知道如何设置项目并打开驱动程序以开始工作。如果你不熟悉这个,你应该看看 第一个项目 教程。
精确时间协议 (PTP) 是遵循 IEEE 1588 标准的网络协议。使用此协议,可以同步计算机网络中多个设备的时间。Kithara PTP模块实现了PTP Version 2 IEEE 1588-2008的 “边界时钟”,它可以通过多个网络连接拥有多个端口。
主时钟可以是 grandmaster、master 或 slave。它也可以在一个端口上是 slave 端口,在其他端口上是 master 端口。该模式可通过 API 选择： 1. 大师 2.最佳主时钟算法 (BMCA) 3.仅限 Slave。通过为网络中的 PTP 时钟设置优先级,可以配置特定的层次结构。这还可能包括在发生故障时接管的冗余组件。否则,clock 参数,如 clocksource 的精度和 type (例如 Atomic clock,GPS) 决定哪个 clock 成为 master。
作为传输层,Raw-Ethernet 和 IPv4/UDP 是可能的为了获得极高的精度 (< 1 us),选定的网络控制器支持硬件时间戳。本教程将引导您完成以下步骤：
第 1 步：为主时钟创建 PTP 时钟实例
第 2 步：添加 PTP 端口
第 3 步：查询 PTP 时钟或 PTP 端口的状态
第 4 步：清除 FAULTY 状态
第 5 步：为 PTP 事件安装处理程序
第 6 步：锁定 PTP 时钟]
第 7 步：获取当前 PTP 时间
第 1 步：为主时钟创建一个 PTP 时钟实例
要为 system-master-clock 创建 PTP 时钟实例,请调用 KS_createPtpClock 并将 KS_INVALID_HANDLE传递给 hDevice。可以为一个或多个进程创建多个句柄,这些进程共享这个 master-clock-instance。使用 KSPtpClockConfig 结构,可以设置 clock 参数。参数 0 ,代表使用默认值。
KSPtpClockConfig clockConfig = {0};
clockConfig.structSize = sizeof(KSPtpClockConfig);
clockConfig.mode = KS_PTP_BEST_MASTER_CLOCK_ALGORITHM;
clockConfig.priority1 = 128;
clockConfig.priority2 = 128;
KSHandle hClock;
ksError = KS_createPtpClock(
&hClock, // 指向 store Handle 的指针
KS_INVALID_HANDLE, // 设备句柄(可选)
&clockConfig, // 指向 KSPtpClockConfig 的指针
0); // 标志
第 2 步：添加 PTP 端口
要首先将 PTP 端口添加到 PTP 时钟,必须打开应建立协议的网络适配器。通过在 KSNetworkAdapterConfig 结构的 configFlags 中设置配置标志 KS_NETWORK_ENABLE_PTP,将为网络适配器启用硬件时间戳(如果支持)。
KSNetworkAdapterConfig adapterConfig = {0};
adapterConfig.structSize = sizeof(KSNetworkAdapterConfig);
adapterConfig.configFlags = KS_NETWORK_ACCEPT_ALL |KS_NETWORK_ENABLE_PTP;
KSHandle hAdapter;
ksError = KS_openNetworkAdapter(
&hAdapter, // 适配器手柄
pDeviceName, // 适配器的设备名称
&adapterConfig, // 指向到 KSNetworkAdapterConfig
0); // 标志
如果是 UDP/IPv4 用作传输层,则必须设置适配器的 IP 配置。
if (portConfig.transportLayer == KS_PTP_UDP) {
KSIPConfig config;
KS_makeIPv4(&config.localAddress,192,168,0,5);
KS_makeIPv4(&config.subnetMask,255,255,255,0);
KS_makeIPv4(&config.gatewayAddress,192,168,0,1);
ksError = KS_execNetworkCommand(
hAdapter, // 适配器句柄
KS_NETWORK_SET_IP_CONFIG, // 命令
&config, // 参数
0); // 标志
}
最后,通过使用 KS_addPtpPort 传递时钟句柄和网络适配器句柄来添加 PTP 端口。使用 KSPtpPortConfig 可以设置 PTP 端口选项。
KSPtpPortConfig portConfig = {0};
portConfig.structSize = sizeof(KSPtpPortConfig);
portConfig.transportLayer = KS_PTP_ETHERNET; // 或 KS_PTP_UDP
portConfig.announceInterval = 1;
portConfig.syncInterval = 0;
portConfig.delayRequestInterval = 0;
KSHandle hPort;
ksError = KS_addPtpPort(
hClock, // PTP 时钟句柄
&hPort, // PTP 端口句柄
hAdapter, // 连接句柄
&portConfig, // 指向 KSPtpPortConfig 的指针
0); // 标志
第 3 步：查询 PTP 时钟或 PTP 端口的状态
要查询 PTP 时钟状态,请调用 KS_getPtpClockState。它返回一个填充的 KSPtpClockState 结构,其中包含时钟 ID、父端口 ID 和主 ID 等信息,以及此时钟与所选主时钟之间的步骤。
KSPtpClockState state = {0};
state.structSize = sizeof(KSPtpClockState);
ksError = KS_getPtpClockState(
hClock, // PTP 时钟句柄
&state, // 指向 KSPtpClockState 的指针
0); // 标志
要查询 PTP 端口状态,请使用 KS_getPtpPortState。它返回一个填充的 KSPtpPortState 结构,其中包含端口的当前 PTP 状态。
KSPtpPortState portState = {0};
portState.structSize = sizeof(KSPtpPortState);
ksError = KS_getPtpPortState(
hPort, // PTP 端口句柄
&portState, // 指向 KSPtpPortState 的指针
0); // 标志
第 4 步：清除 FAULTY 状态
如果发生故障或检测到故障,PTP 端口将进入 KS_PTP_STATE_FAULTY 状态。可以通过运行以下命令来清除此状态：
ksError = KS_execPtpCommand(
hPort, // PTP 句柄
KS_PTP_CLEAR_FAULTS, // 命令
NULL, // 参数
0); // 标志
执行此命令后,PTP 端口将重新初始化。
第 5 步：为 PTP 事件安装处理程序
使用 KS_installPtpHandler 可以安装 PTP 事件的处理程序：
要安装一个处理程序,如果为 PTP 时钟选择了新的 PTP 主节点,则将被调用,请使用 KS_PTP_MASTER_SELECTED 事件代码：
ksError = KS_installPtpHandler(
hClock, // PTP 句柄
KS_PTP_MASTER_SELECTED, // 事件代码
hCallBack, // 信号句柄
0); // 标志
要在每次 PTP 端口更改其状态时收到通知,请使用 KS_PTP_PORT_STATE_CHANGED 事件代码：
ksError = KS_installPtpHandler(
hPort, // PTP 句柄
KS_PTP_PORT_STATE_CHANGED, // 事件代码
hCallBack, // 信号句柄
0); // 标志
第 6 步：锁定 PTP 时钟
通过调用 KS_lockPtpClock ,绝对时间偏移量被锁定。这对于避免时间关键型应用程序中的时间跳跃是必要的。当处于锁定状态时,漂移校正保持工作,偏移量在内部保持。
ksError = KS_lockPtpClock(hClock,0);
解锁调用 KS_unlockPtpClock
ksError = KS_unlockPtpClock(hClock,0);
第 7 步：获取当前 PTP 时间
要获取当前的 PTP 时间调用_KS_getClock_ 和 KS_CLOCK_PTP_TIME 时钟源。
int64 time;
KS_getClock(&time,KS_CLOCK_PTP_TIME);
PTP 时间纪元以纳秒为单位计数,自 1970 年 1 月 1 日 00：00：00 TAI(原子时)以来。除了 UTC 时间之外,它不考虑闰秒。要获取当前的 UTC 时间,请使用 KS_CLOCK_ABSOLUTE_TIME 时钟源调用 KS_getClock。
int64 time;
KS_getClock(&time,KS_CLOCK_ABSOLUTE_TIME);
KS_CLOCK_ABSOLUTE_TIME 自 1.1.1601 00：00：00 以来以 100ns 为单位计数。它确实考虑了闰秒。
建立 PTP 网络后,所有设备中主时钟的时间将同步。根据所使用的硬件,在网络中可以实现低于 1 us 的永久精度。
