IEEE 802.1AS-2011 第九章 应用接口(API)

本文翻译自IEEE Standard for Local and metropolitan area networks—Timing and Synchronization for Time-Sensitive Applications in Bridged Local Area Networks

9. 应用接口

9.1 接口总览

以下子条款定义了ClockSource实体和ClockMaster实体（见10.1.1）之间的一个应用程序接口，以及ClockTarget实体和ClockSlave实体之间的四个应用程序接口（见10.1.1）。 ClockSource是一个可以用作gPTP域的外部定时源的实体。 ClockSource实体包含或可以访问时钟（见3.3）。 ClockTarget实体表示使用ClockSlave实体通过任何应用程序接口提供的信息的任何应用程序。
注 - ClockSource实体获取时间的方式超出了本标准的范围。 ClockTarget使用应用程序接口提供的信息的方式超出了本标准的范围。
五个接口如图9-1所示。它们包括以下内容：
a) ClockSourceTime接口，为时间感知系统提供外部定时，
b) ClockTargetEventCapture接口，它返回由ClockTarget实体发出的捕捉事件信号的同步时间，
c) ClockTargetTriggerGenerate接口，它返回事件在ClockTarget实体指定发出信号时的同步时间，
d) ClockTargetClockGenerator接口，它导致生成周期性结果序列，其中相位和速率由ClockTarget实体指定，并且
e) ClockTargetPhaseDiscontinuity接口，它提供应用程序可用于确定是否发生了特级大师相位或频率不连续的信息。
注 - 本节中描述的应用程序接口是行为模型，而不是应用程序接口。除了上述a）到e）项之外的其他应用程序接口也是可能的，但这里不再描述。此外，可以有特定接口的多个实例。

9.2 ClockSourceTime

9.2.1 概述

ClockSource实体使用此接口为时间感知系统的ClockMaster实体提供时间。 ClockSource实体调用ClockSourceTime.invoke函数来提供，相对于ClockSource来说，调用此函数的时间。

9.2.2 ClockSourceTime.invoke函数参数

ClockSourceTime.invoke {
	sourceTime,
	timeBaseIndicator,
	lastGmPhaseChange,
	lastGmFreqChange
}

参数定义如下：

9.2.2.1 sourceTime(ExtendedTimestamp)

sourceTime的值是ClockSource实体调用此函数的时间。

9.2.2.2 timeBaseIndicator (UInteger16)

timeBaseIndicator是由ClockSource实体设置的二进制值。 ClockSource实体会在其时基更改时更改该值。 当且仅当存在相位或频率变化时，ClockSource实体才应更改timeBaseIndicator的值。
注 - 虽然为ClockSource实体提供时间的时钟可能会丢失，即时间感知系统可以进入保持状态，但ClockSource实体本身不会丢失。 如果时间源丢失，ClockSource实体确保timeBaseIndicator更改。

9.2.2.3 lastGmPhaseChange (ScaledNs)

lastGmPhaseChange的值是timeBaseIndicator中最近更改时发生的相位更改（即sourceTime中的更改）。 该值初始化为0。

9.2.2.4 lastGmFreqChange (Double)

lastGmFreqChange的值是在timeBaseIndicator的最近变化中发生的分数频率变化（即，表示为纯分数的频率变化）。 该值初始化为0。

9.3 ClockTargetEventCapture

9.3.1 概述

ClockTarget实体使用此接口来请求它向时间感知系统的ClockSlave实体发信号的事件的同步时间。 ClockTarget实体调用ClockTargetEventCapture.invoke函数向ClockSlave实体发送事件信号。 ClockSlave实体调用ClockTargetEventCapture.result函数来返回事件相对于当前大师的时间，或者，如果没有时间感知系统是大师级的，则返回LocalClock。 ClockTargetEventCapture.result函数还返回gmPresent，以向ClockTarget指示是否存在特级大师。

9.3.2 ClockTargetEventCapture.invoke参数

ClockTargetEventCapture.invoke {
}

该函数没有参数

9.3.3 ClockTargetEventCapture.result参数

ClockTargetEventCapture.result {
	slaveTimeCallback,
	gmPresent
}

参数定义如下

9.3.3.1 slaveTimeCallback (ExtendedTimestamp)

slaveTimeCallback的值是相对于特级大师调用相应的ClockTargetEventCapture.invoke函数的时间。
注 - ClockSlagetEventCapture.invoke函数的调用以及ClockSlave实体对此调用的检测在此抽象接口中是同步的。

9.3.3.2 gmPresent (Boolean)

gmPresent的值设置为等于全局变量gmPresent的值（见10.2.3.13）。 此参数向ClockTarget指示是否存在特级大师。

9.4 ClockTargetTriggerGenerate

9.4.1 概述

ClockTarget实体使用此接口来请求ClockSlave实体在指定时间相对于特级大师发送结果。 ClockTarget实体调用ClockTargetTriggerGenerate.invoke函数来指示事件的同步时间。 ClockSlave实体调用ClockTargetTriggerGenerate.result函数，以在请求的同步时间发出事件信号或指示错误情况。

9.4.2 ClockTargetTriggerGenerate.invoke参数

ClockTargetTriggerGenerate.invoke {
	slaveTimeCallback
}

参数定义如下：

9.4.2.1 slaveTimeCallback (ExtendedTimestamp)

如果slaveTimeCallback非零，则其值是相应的ClockTargetTriggerGenerate.result函数（即触发器）将被调用的同步时间。 如果slaveTimeCallback为零，则取消尚未发出ClockTargetTriggerGenerate.result函数的任何先前ClockTargetTriggerGenerate.invoke函数。

9.4.3 ClockTargetTriggerGenerate.result参数

ClockTargetTriggerGenerate.result {
	errorCondition,
	gmPresent
}

参数定义如下：

9.4.3.1 errorCondition (Boolean)

值FALSE表示相对于特级大师，当时调用了ClockTargetTriggerGenerate.result函数，该函数包含在相应的ClockTargetTriggerGenerate.invoke函数中。 值TRUE表示无法在相应的ClockTargetTriggerGenerate.invoke函数中包含的同步时间调用ClockTargetTriggerGenerate.result函数。
注 - 例如，如果请求的slaveTimeCallback是调用相应ClockTargetTriggerGenerate.invoke函数的同步时间之前的时间，则调用ClockTargetTriggerGenerate.result函数并使用errorCondition = TRUE。 另一个例子，如果同步时间中的不连续导致请求的slaveTimeCallback被跳过，则调用ClockTargetTriggerGenerate.result函数并使用errorCondition = TRUE。

9.4.3.2 gmPresent (Boolean)

gmPresent的值设置为等于全局变量gmPresent的值（见10.2.3.13）。 此参数向ClockTarget指示是否存在特级大师。

9.4.4 ClockTargetTriggerGenerate接口定义

调用ClockTargetTriggerGenerate.invoke函数会导致ClockSlave实体将slaveTimeCallback参数的值存储在内部变量中（替换该变量的任何先前值），直到同步时间，或者如果gmPresent为FALSE，则为LocalClock时间，等于该变量，此时使用errorCondition = FALSE调用ClockTargetTriggerGenerate.result函数。 如果无法在slaveTimeCallback上调用ClockTargetTriggerGenerate.result函数，例如，如果在调用ClockTargetTriggerGenerate.invoke函数时slaveTimeCallback早于同步时间（或者如果gmPresent为FALSE则为LocalClock时间），则调用ClockTargetTriggerGenerate.result函数 with errorCondition = TRUE。 使用slaveTimeCallback = 0（早于任何同步时间）调用ClockTargetTriggerGenerate.invoke函数用于取消挂起的请求。

9.5 ClockTargetClockGenerator

9.5.1 概述

ClockTarget实体使用此接口来请求ClockSlave实体提供指定周期和相位的周期性时钟信号。 ClockTarget实体调用ClockTargetClockGenerator.invoke函数来请求ClockSlave实体生成周期时钟信号。 ClockSlave实体在所需时钟信号的重要时刻调用ClockTargetClockGenerator.result函数。

9.5.2 ClockTargetClockGenerator.invoke参数

ClockTargetClockGenerator.invoke {
	clockPeriod,
	slaveTimeCallbackPhase
}

参数定义如下：

9.5.2.1 clockPeriod (TimeInterval)

clockPeriod的值是ClockTargetClockGenerator.result函数连续调用之间的时间段。 零或负值会导致通过此应用程序接口生成的任何现有周期时钟信号终止。

9.5.2.2 slaveTimeCallbackPhase (ExtendedTimestamp)

slaveTimeCallbackPhase的值通过指定PTP时间刻度上的点来描述生成的时钟信号的相位，使得ClockTargetClockGenerator.result调用在与slaveTimeCallbackPhase不同的同步时间发生n×clockPeriod，其中n是整数。
注 - slaveTimeCallbackPhase的值可以早于或晚于调用ClockTargetClockGenerator.invoke函数的同步时间; 将来使用slaveTimeCallbackPhase值并不意味着在该同步时间之前抑制周期性时钟信号的启动。

9.5.3 ClockTargetClockGenerator.result参数

ClockTargetClockGenerator.result {
	slaveTimeCallback,
}

参数定义如下：

9.5.3.1 slaveTimeCallback (ExtendedTimestamp)

slaveTimeCallback的值是此事件的同步时间。

9.6 ClockTargetPhaseDiscontinuity

9.6.1 概述

该接口提供从主时钟发送到站内应用程序的不连续信息。 ClockSlave实体使用它向ClockTarget实体提供足够的信息，以使ClockTarget实体能够确定是否发生了相位或频率不连续。 ClockSlave调用ClockSlaveSync状态机的SEND_SYNC_INDICATION块中的ClockTargetPhaseDiscontinuity.result函数（见10.2.12和图10-9）。 在ClockSlaveSync状态机计算所需信息之后，在收到PortSyncSync结构时发生调用。

9.6.2 ClockTargetPhaseDiscontinuity.result参数

ClockTargetPhaseDiscontinuity.result {
	gmIdentity,
	gmTimeBaseIndicator,
	lastGmPhaseChange,
	lastGmFreqChange
}

参数定义如下：

9.6.2.1 gmIdentity (ClockIdentity)

如果gmPresent（见10.2.3.13）为TRUE，则gmIdentity的值是当前特级大师的ClockIdentity。 如果gmPresent为FALSE，则gmIdentity的值为0x0。

9.6.2.2 gmTimeBaseIndicator (UInteger16)

gmTimeBaseIndicator的值是当前特级大师的timeBaseIndicator。

9.6.2.3 lastGmPhaseChange (ScaledNs)

从特级大师收到的全局lastGmPhaseChange参数（见10.2.3.16）的值。

9.6.2.4 lastGmFreqChange (Double)

从特级大师收到的lastGmFreqChange参数（见10.2.3.17）的值。