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

项目
03/08/2024

本章按字母顺序介绍了所有 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. */