通过精密时间协议（PTP）对计算机网络中的多个设备进行时间同步

PTP 模块 - 使用教程

[PTP 模块 - 使用教程](#PTP 模块 - 使用教程)
- 简介
- [第 1 步：为主时钟创建一个 PTP 时钟实例](#第 1 步：为主时钟创建一个 PTP 时钟实例)
- [第 2 步：添加 PTP 端口](#第 2 步：添加 PTP 端口)
- [第 3 步：查询 PTP 时钟或 PTP 端口的状态](#第 3 步：查询 PTP 时钟或 PTP 端口的状态)
- [第 4 步：清除 FAULTY 状态](#第 4 步：清除 FAULTY 状态)
- [第 5 步：为 PTP 事件安装处理程序](#第 5 步：为 PTP 事件安装处理程序)
- [第 6 步：锁定 PTP 时钟](#第 6 步：锁定 PTP 时钟)
- [第 7 步：获取当前 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),选定的网络控制器支持硬件时间戳。本教程将引导您完成以下步骤：

bash 复制代码

 	第 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 为单位计数。它确实考虑了闰秒。