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）的值。