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,          // 指向到 KSNetworkAdapterConfig0);                        // 标志

如果是 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_UDPportConfig.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 的永久精度。