第 3 章 - Azure RTOS NetX Duo PTP 客户端服务说明

本章按字母顺序介绍了所有 NetX Duo PTP 客户端服务(如下所列)。

[!NOTE]

在以下 API 函数说明的“返回值”部分中,以粗体显示的值不受定义用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 影响,而不以粗体显示的值则完全禁用。

nx_ptp_client_create

创建 PTP 客户端实例。

原型

UINT nx_ptp_client_create(
    NX_PTP_CLIENT *client_ptr, 
    NX_IP *ip_ptr, 
    UINT interface_index,
    NX_PACKET_POOL *packet_pool_ptr, 
    UINT thread_priority, 
    UCHAR *thread_stack, 
    UINT stack_size,
    NX_PTP_CLIENT_CLOCK_CALLBACK clock_callback, 
    VOID *clock_callback_data);

说明

此服务用于创建 PTP 客户端实例。

请注意,应用程序必须先为 PTP 客户端创建 IP 实例和数据包池,以用于传输数据包。 对于数据包池,应用程序可以使用 IP 实例中的相同数据包池;也可以为 PTP 客户端创建专用数据包池。 创建专用数据包池这种方法的优点是,可以使用小数据包(如果使用的是 IPv6,则为 128 字节的数据包,如果使用的是仅 IPv4,则为 108 字节的数据包)。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • ip_ptr:指向 IP 实例的指针
  • interface_index:PTP 网络接口的索引
  • packet_pool_ptr:指向客户端数据包池的指针
  • thread_priority:PTP 线程的优先级
  • thread_stack:指向线程堆栈的指针
  • stack_size:线程堆栈的大小
  • clock_callback:PTP 时钟回调
  • clock_callback_data:时钟回调数据

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • NX_PTP_CLIENT_INSUFFICIENT_PACKET_PAYLOAD (0xD04):数据包有效负载太小
  • NX_PTP_CLIENT_CLOCK_CALLBACK_FAILURE (0xD05):时钟回叫失败
  • status:NetX Duo 和 ThreadX 服务调用处于完成状态
  • NX_PTR_ERROR (0x07):输入指针参数无效
  • NX_INVALID_INTERFACE (0x4C):接口无效

允许调用自

线程数

示例

/* Create the PTP client instance */
status = nx_ptp_client_create(&ptp_client, &ip_0, 0, &pool_0, 
                              PTP_THREAD_PRIORITY, (UCHAR *)ptp_stack, sizeof(ptp_stack),
                              clock_callback, NX_NULL);

/* If the client was successfully created, status = NX_SUCCESS. */

nx_ptp_client_delete

删除 PTP 客户端实例。

原型

UINT nx_ptp_client_delete(NX_PTP_CLIENT *client_ptr);

说明

此服务用于删除 PTP 客户端实例。

输入参数

  • client_ptr:指向要删除的 PTP 客户端的指针

返回值

  • NX_SUCCESS (0x00):已成功删除客户端
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

/* Delete the PTP client instance */
status = nx_ptp_client_delete(&ptp_client);

/* If the client was successfully deleted, status = NX_SUCCESS. */

nx_ptp_client_master_info_get

获取主时钟信息。

原型

UINT nx_ptp_client_master_info_get(
    NX_PTP_CLIENT_MASTER *master_ptr, 
    NXD_ADDRESS *address, 
    UCHAR **port_identity, 
    UINT *port_identity_length, 
    UCHAR *priority1, 
    UCHAR *priority2, 
    UCHAR *clock_class,
    UCHAR *clock_accuracy, 
    USHORT *clock_variance, 
    UCHAR **grandmaster_identity,
    UINT *grandmaster_identity_length, 
    USHORT *steps_removed, 
    UCHAR *time_source);

说明

此服务用于获取主时钟信息。 主控制块通过事件回叫函数传递给用户应用程序。

输入参数

  • master_ptr:指向 PTP 主时钟的指针
  • address:主时钟地址
  • port_identity:PTP 主端口和标识
  • port_identity_length:PTP 主端口和标识的长度
  • priority1:PTP 主时钟的 Priority1
  • priority2:PTP 主时钟的 Priority2
  • clock_class:PTP 主时钟的类
  • clock_accuracy:PTP 主时钟的准确度
  • clock_variance:PTP 主时钟的时钟差
  • grandmaster_identity:祖父时钟的标识
  • grandmaster_identity_length:祖父时钟标识的长度
  • steps_removed:从 PTP 头中删除的步骤
  • time_source:祖父时钟使用的计时器源

返回值

  • NX_SUCCESS (0x00):已成功获取主时钟信息
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

static UINT ptp_event_callback(NX_PTP_CLIENT *ptp_client_ptr, UINT event, VOID *event_data, VOID *callback_data)
{
NXD_ADDRESS address;
UCHAR *port_identity;
UINT port_identity_length;
UCHAR priority1, priority2;
UCHAR clock_class, clock_accuracy;
USHORT clock_variance;
UCHAR *grandmaster_identity;
UINT grandmaster_identity_length;
USHORT steps_removed;
UCHAR time_source;

    switch (event)
    {
        case NX_PTP_CLIENT_EVENT_MASTER:
        {
            status = nx_ptp_client_master_info_get((NX_PTP_CLIENT_MASTER *)event_data, 
                                                   &address, &port_identity,
                                                   &port_identity_length, &priority1, 
                                                   &priority2, &clock_class,
                                                   &clock_accuracy, &clock_variance, 
                                                   &grandmaster_identity,
                                                   &grandmaster_identity_length, 
                                                   &steps_removed, &time_source);

            /* If the master clock information was successfully get, status = NX_SUCCESS. */
            break;
        }

        /* Other event process. */
    }
}

nx_ptp_client_packet_timestamp_notify

将数据包的时间戳通知给 PTP 客户端。

原型

VOID nx_ptp_client_packet_timestamp_notify(
    NX_PTP_CLIENT *client_ptr, 
    NX_PACKET *packet_ptr, 
    NX_PTP_TIME *timestamp_ptr);

说明

此服务用于通知 PTP 客户端,数据包已传输且有时间戳。 此服务是为网络驱动程序设计的,并在数据包传输时调用。 时间戳通常由硬件生成。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • packet_ptr:指向传输的 PTP 数据包的指针
  • timestamp_ptr:指向 PTP 数据包的时间戳的指针

返回值

获准方式

线程数

示例

/* Call notification callback */
nx_ptp_client_packet_timestamp_notify(client_ptr, packet_ptr, &ts);

nx_ptp_client_soft_clock_callback

PTP 时钟的软件实现。

原型

UINT nx_ptp_client_soft_clock_callback(
    NX_PTP_CLIENT *client_ptr, 
    UINT operation,
    NX_PTP_TIME *time_ptr, 
    NX_PACKET *packet_ptr,
    VOID *callback_data);

说明

此回叫函数用作 PTP 的模拟低分辨率时钟源。 此例程是作为参考提供的,不能用于生产。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • operation:回调操作,有效值定义为:
    • NX_PTP_CLIENT_CLOCK_INIT:初始化时钟。
    • NX_PTP_CLIENT_CLOCK_SET:设置由 time_ptr 指定的当前时间戳。
    • NX_PTP_CLIENT_CLOCK_GET:将当前时间戳返回到 time_ptr
    • NX_PTP_CLIENT_CLOCK_PACKET_TS_EXTRACT:从 packet_ptr 提取时间戳并将其返回到 time_ptr
    • NX_PTP_CLIENT_CLOCK_ADJUST:将当前时间戳调整不超过 1 秒。
    • NX_PTP_CLIENT_CLOCK_PACKET_TS_PREPARE:标记 packet_ptr,这要求在传输数据包时向 PTP 客户端通知时间戳。
    • NX_PTP_CLIENT_CLOCK_SOFT_TIMER_UPDATE:更新软件计时器。 硬件时钟可忽略此值。
  • time_ptr:指向时间戳的指针。
  • packet_ptr:指向数据包的指针。
  • callback_data:指向不透明回调数据的指针。

返回值

  • NX_SUCCESS (0x00):操作成功
  • NX_PTP_PARAM_ERROR (0xD03):参数无效

允许调用自

PTP 内部

示例

status = nx_ptp_client_create(&ptp_client, &ip_0, 0, &pool_0, 
                              PTP_THREAD_PRIORITY, (UCHAR *)ptp_stack, sizeof(ptp_stack),
                              nx_ptp_client_soft_clock_callback, NX_NULL);

/* If the client was successfully created, status = NX_SUCCESS. */

nx_ptp_client_start

启动 PTP 客户端。

原型

UINT nx_ptp_client_start(
    NX_PTP_CLIENT *client_ptr, 
    UCHAR *client_port_identity_ptr, 
    UINT client_port_identity_length,
    UINT domain, 
    UINT transport_specific, 
    NX_PTP_CLIENT_EVENT_CALLBACK event_callback,
    VOID *event_callback_data)

说明

此服务用于启动之前创建的 PTP 客户端实例。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • client_port_identity_ptr:指向客户端端口和标识的指针,可以为 NULL
  • client_port_identity_length:客户端端口和标识的长度。 如果 client_port_identity_ptr 为 NULL 或 NX_PTP_CLOCK_PORT_IDENTITY_SIZE (10),则它必须为 0
  • domain:PTP 时钟域
  • transport_specific:4 位的传输细节
  • event_callback:在事件上调用的回调函数
  • event_callback_data:事件回调数据

返回值

  • NX_SUCCESS (0x00):已成功启动客户端
  • NX_PTP_CLIENT_ALREADY_STARTED (0xD02):已成功启动 PTP 客户端
  • status:NetX Duo 和 ThreadX 服务调用处于完成状态
  • NX_PTR_ERROR (0x07):输入指针参数无效

获准方式

线程数

示例

status = nx_ptp_client_start(&ptp_client, NX_NULL, 0, 0, 0, ptp_event_callback, NX_NULL);

/* If the client was successfully started, status = NX_SUCCESS. */

nx_ptp_client_stop

停止 PTP 客户端。 在 PTP 客户端停止后,它既不处理 PTP 数据包,也不传输 PTP 数据包。

原型

UINT nx_ptp_client_stop(NX_PTP_CLIENT *client_ptr);

说明

此服务用于停止之前创建和启动的 PTP 客户端实例。

输入参数

  • client_ptr:指向要停止的 PTP 客户端的指针

返回值

  • NX_SUCCESS (0x00):已成功停止客户端
  • NX_PTP_CLIENT_NOT_STARTED (0xD01):客户端未启动
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

status = nx_ptp_client_stop(&ptp_client);

/* If the client was successfully stopped, status = NX_SUCCESS. */

nx_ptp_client_sync_info_get

获取同步信息。

原型

UINT nx_ptp_client_sync_info_get(
    NX_PTP_CLIENT_SYNC *sync_ptr, 
    USHORT *flags, 
    SHORT *utc_offset);

说明

此服务用于获取同步消息的信息。 同步控制块通过事件回叫函数传递给用户应用程序。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • flags:同步消息中的标志
  • utc_offset:TAI 与 UTC 之间的偏移

返回值

  • NX_SUCCESS (0x00):已成功获取同步信息
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

static UINT ptp_event_callback(NX_PTP_CLIENT *ptp_client_ptr, UINT event, VOID *event_data, VOID *callback_data)
{
USHORT utc_offset;

    switch (event)
    {
        case NX_PTP_CLIENT_EVENT_SYNC:
        {
            nx_ptp_client_sync_info_get((NX_PTP_CLIENT_SYNC *)event_data, NX_NULL, &utc_offset);

            /* If the Sync information was successfully get, status = NX_SUCCESS. */
            break;
        }

        /* Other event process. */
    }
}

nx_ptp_client_time_get

获取当前时间。

原型

UINT nx_ptp_client_time_get(
    NX_PTP_CLIENT *client_ptr, 
    NX_PTP_TIME *time_ptr);

说明

此服务用于获取 PTP 时钟的当前值。 无论 PTP 客户端是否与主时钟同步,都可以使用此服务。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • time_ptr:指向 PTP 时间的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

/* Get the PTP clock */
nx_ptp_client_time_get(&ptp_client, &tm);

nx_ptp_client_time_set

设置当前时间。

原型

UINT nx_ptp_client_time_set(
    NX_PTP_CLIENT *client_ptr, 
    NX_PTP_TIME *time_ptr);

说明

此服务用于设置 PTP 时钟的当前值。 必须在 PTP 客户端启动之前调用它。

输入参数

  • client_ptr:指向要创建的 PTP 客户端的指针
  • time_ptr:指向 PTP 时间的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • NX_PTP_CLIENT_ALREADY_STARTED (0xD02):已成功启动 PTP 客户端
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

/* Set current time before PTP client started.  */
status = nx_ptp_client_time_set(&ptp_client, &tm);

nx_ptp_client_utility_convert_time_to_date

将 PTP 时间转换为 UTC 日期和时间。

原型

UINT nx_ptp_client_utility_convert_time_to_date(
    NX_PTP_TIME *time_ptr, 
    LONG offset, 
    NX_PTP_DATE_TIME *date_time_ptr);

说明

此服务用于将 PTP 时间转换为 UTC 日期和时间。

输入参数

  • time_ptr:指向 PTP 时间的指针
  • offset:用于添加 PTP 时间的带符号秒偏移
  • date_time_ptr:指向所生成日期的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • 指向所生成日期的指针 (0xD03):输入参数无效
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

/* convert PTP time to UTC date and time */
status = nx_ptp_client_utility_convert_time_to_date(&tm, -ptp_utc_offset, &date);

/* If the time was successfully converted, status = NX_SUCCESS. */

nx_ptp_client_utility_time_diff

计算两个 PTP 时间的差值。

原型

UINT nx_ptp_client_utility_time_diff(
    NX_PTP_TIME *time1_ptr, 
    NX_PTP_TIME *time2_ptr, 
    NX_PTP_TIME *result_ptr);

说明

此服务用于计算两个 PTP 时间的差值。

输入参数

  • time1_ptr:指向第一个 PTP 时间的指针
  • time2_ptr:指向第二个 PTP 时间的指针
  • result_ptr:指向 time1-time2 结果的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

线程数

示例

/* Diff time.  */
status = nx_ptp_client_utility_time_diff(&time1, &time2, &result);

/* If the calculation was successfully, status = NX_SUCCESS. */