Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resolution of issue "Non slewing time adjustments #203" V2 #354

Open
wants to merge 15 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<msg:GetMdibResponse
SequenceId="urn:uuid:09578906-7efd-43a7-8344-8bf37b674524"
xmlns:ext="http://standards.ieee.org/downloads/11073/11073-10207-2017/extension"
xmlns:pm="http://standards.ieee.org/downloads/11073/11073-10207-2017/participant"
xmlns:msg="http://standards.ieee.org/downloads/11073/11073-10207-2017/message"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sdpi="urn:oid:1.3.6.1.4.1.19376.1.6.2.10.1.1.1">
<msg:Mdib SequenceId="urn:uuid:09578906-7efd-43a7-8344-8bf37b674524">
<pm:MdDescription>
<pm:Mds Handle="mds0">
<pm:Clock Handle="clk"/>
<pm:Vmd Handle="vmd">
<pm:Channel Handle="ch">
<pm:Metric Handle="m1" MetricAvailability="Intr" MetricCategory="Msrmt">
<pm:Type Code="67108871"/>
<pm:Unit Code="262656" />
</pm:Metric>
<pm:Metric Handle="m2" MetricAvailability="Intr" MetricCategory="Msrmt">
<pm:Type Code="67108871"/>
<pm:Unit Code="262656" />
</pm:Metric>
</pm:Channel>
</pm:Vmd>
</pm:Mds>
</pm:MdDescription>
<pm:MdState>
<pm:State LastSet="1733270400" DateAndTime="1733268600" DescriptorHandle="clk" StateVersion="15" RemoteSync="1" xsi:type="pm:ClockState">
<ext:Extension>
<sdpi:Epochs Version="5">
<!-- non-slewing adjustment at 11 am -->
<sdpi:Epoch Version="4" Timestamp="1733270400" Offset="-PT3H" />
<!-- non-slewing adjustment at 7 am -->
<sdpi:Epoch Version="3" Timestamp="1733248800" Offset="PT4H" />
</sdpi:Epochs>
</ext:Extension>
</pm:State>

<pm:State DescriptorHandle="m1" xsi:type="pm:NumericMetricState" StateVersion="123">
<!-- determination time = 3 am, epoch 3 clock -->
<pm:MetricValue Value="0" DeterminationTime="1733238000" StartTime="1733237090" StopTime="1733237097">
<ext:Extension>
<sdpi:MetricEpoch Clock="clk" DeterminationTime="3" StartTime="3" StopTime="3" />
</ext:Extension>
<pm:MetricQuality Validity="Vld" Qi="1.00"/>
</pm:MetricValue>
</pm:State>

<pm:State DescriptorHandle="m2" xsi:type="pm:NumericMetricState" StateVersion="321">
<!-- determination time = 12 am, epoch 4 clock -->
<pm:MetricValue Value="0" DeterminationTime="1733266800" >
<pm:MetricQuality Validity="Vld" Qi="1.00"/>
</pm:MetricValue>
</pm:State>

</pm:MdState>
</msg:Mdib>
</msg:GetMdibResponse>
2 changes: 1 addition & 1 deletion asciidoc/volume0/tf0-ch-d-glossary.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ elements, from requirements to system components to Verification & Validation te
| A networking protocol for clock synchronization between computer systems over packet-switched, variable-latency data networks.
|
| [[acronym_ntp,NTP]] NTP
| https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP wikipedia article]
| https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP wikipedia article], <<ref_rfc_5905>>
|

| [[term_object_management_group, Object Management Group (OMG)]] Object Management Group
Expand Down
2 changes: 2 additions & 0 deletions asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ No content from those three standards - including their requirements - is norma

* [[[ref_rfc_3986, RFC 3986]]] T. Berners-Lee et al., RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005, available at https://www.rfc-editor.org/rfc/rfc3986

* [[[ref_rfc_5905, RFC 5905]]] D. Mills et al., RFC 5905, Network Time Protocol Version 4: Protocol And Algorithms Specification, June 2010, available at https://www.rfc-editor.org/rfc/rfc5905

* [[[ref_oasis_dpws_2009,OASIS DPWS:2009]]] OASIS Standard, Devices Profile for Web Services Version 1.1, OASIS Standard, 1 July 2009, available at http://docs.oasis-open.org/ws-dd/dpws/wsdd-dpws-1.1-spec.html

* [[[ref_oasis_soap_over_udp_v1_1, OASIS SOAP-over-UDP Version 1.1]]] OASIS Standard, SOAP-over-UDP Version 1.1, July 2009, available at http://docs.oasis-open.org/ws-dd/soapoverudp/1.1/os/wsdd-soapoverudp-1.1-spec-os.docx.
Expand Down
209 changes: 208 additions & 1 deletion asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
[#vol3_clause_timestamp_versioning]
====== Timestamp versioning
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need some sort of a formula to provide guidance as to how a consumer may calculate actual timestamps based on the epoch version and a base/reference timestamp.

So far I did not read the whole text, so the following questions came up:

  • Is the offset based on the previous epoch or based on a reference timestamp?
  • How does this design take into consideration that there may be timestamps affected by non-slewing adjustments in extensions?
  • Do we need the epoch version extension to be mustUnderstand? If yes, we need to show that somewhere in the descriptor as otherwise consumers may bump into a mustUnderstand extension after inspection of the description (perhaps something attached to the decriptor to signify support of epoch versions)

Copy link
Collaborator Author

@PaulMartinsen PaulMartinsen Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally I don't think it is possible for a consumer to calculate actual timestamps following an abrupt change in time. Here's an attempt to show why:

Let's say T0 is the current time obtained from a stratum 0 clock, the most accurate timekeeper on the planet, an atomic clock for example. And TP is the time from a provider's clock. Then: $$T_P = T_0 ( 1 + f(T_0)) + \Delta + \eta$$.

Here:

  • $$\Delta$$ is the average difference in time between the reference and provider's clocks,
  • $$\eta$$ is a random number, probably from a normal distribution, that reflects the uncertainty in transferring time from reference clocks through to the provider's clock. I think this would be quite small under the right (or even sensibly typical) conditions; maybe a few milliseconds or less.
  • $$f(T_0)$$ is a scaling function that represents the behaviour of the providers time service client tyring to keep the times in sync. Since non-slewing adjustments (loosely) occur when the difference between reference and provider clocks exceed a bit over four minutes, one possibility for $$f(T_0)$$ might be:
    $$f(T_0) = 5 minutes * T_0$$, although if it was then the provider's clock discipline algorithm should compensate for that (with a slewing adjustment)
    another might be:
    $$f(T_0) = \delta(T_0 - t_{adjust})*2$$, which could be a 2 hour forward adjustment of the reference clock at some point $$t_{adjust}$$; the provider doesn't know exactly when that happens because it is probably checking in with the reference clock every 10 minutes or 2 hours or something.

$$f(T_0)$$ might also be much more complicated. I'd actually expect something more like one of these examples because the clock-discipline algorithm seems to be a closed loop controller so it probably oscillates towards an equilibrium, or maybe (probably) its well tuned and just decays to a small error. Left graph illustrates time from provider plotted against time from precision source; right graph is the difference between them:
image

Note, these don't illustrate the non-slewing adjustment; this is just the slewing behaviour. And they should be considered a novice guess. I can't recall enough of the algorithm to know how it behaves following a non-slewing adjustment; possibly a step change followed by damped oscillations.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What we can do is be very clear about how the sdpi:Epoch adjustments must be implemented. This is covered inthe schema and 3:8.3.2.10.8.1 Model, but I've added a diagram too since it is critical every implementation does it the same way.

image

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think there should be an extension in the clock descriptor with a must-understand attribute. I think this would prevent consumers that aren't fully up to date with SDPi requirements being surprised by epoch versions as if they don't understand they should cease any further communication with the provider.

I'll add something in the next couple of days to the schema as a starting point. Do you think this would be a place to declare how the provider handles non-slewing adjustments (e.g., new sequence id vs setting activation state), or is this just a guard against surprises?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a sdpi:EpochSupport element to advise support for the extension inside a pm:ClockDescriptor and updated requirements. It includes an optional MustUnderstand and a Version that defaults to 1. Not sure if this is the right approach, but a start.

After more consideration, I don't think it makes sense provide more detail on how non-slewing adjustments would be handled both (1) to reduce complexity and (2) a provider might choose different options in different scenarios. For example, it may switch from timestamp versions to starting a new sequence id if it decides to abandon a time server following a lot of non-slewing adjustments.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've pointed out participants may not be able to determine the relationship between timestamps in different epochs. Both in the timestamp versioning extension:

The presence of <<term_abrupt_time_adjustment>> creates <<term_epoch>>s of consistency: periods where the <<vol1_spec_sdpi_p_actor_somds_participant>>'s timestamps are well-behaved, separated by step-changes. At best, <<term_epoch>> are separated by a constant temporal offset; at worst <<vol1_spec_sdpi_p_actor_somds_participant>>s may have insufficient information to determine the relationship between <<term_epoch>> (e.g., changes at the <<acronym_ts_service>> that do not represent a change in elapsed time to unbiased observers).

and in the use case:

although an <<term_abrupt_time_adjustment>> starts with a constant offset between two <<term_epoch>>s at a single point in time, it may introduce constant or variable (linear and/or non-linear) offsets between timestamps obtained within the <<term_epoch>>s. That is, the difference (to an unbiased observer) between any two timestamps from different epochs may depend (linearly or non-linearly) on when, within each epoch, the timestamp was obtained. It is typically not possible to establish a common <<term_time_reference_frame>> following an <<term_abrupt_time_adjustment>> without additional information not available to the <<vol1_spec_sdpi_p_actor_somds_participant>>.


BICEPS does not provide any means to convey step-changes in a <<vol1_spec_sdpi_p_actor_somds_participant>>'s <<term_time_reference_frame>> (see <<vol1_clause_appendix_c_use_case_stad_non_slew, use case for non-slewing time adjustments>>).

A <<vol1_spec_sdpi_p_actor_somds_provider>> includes <<term_timestamp>>s in many state updates including `pm:AlertConditionState/@DeterminationTime`, `pm:AbstractMetricValue/@DeterminationTime` and `pm:AbstractContextState/@BindingStartTime`. From time-to-time, though rarely in normal operation, a
<<vol1_spec_sdpi_p_actor_somds_participant>> may determine that the difference between its <<term_time_reference_frame>> and that of the <<acronym_ts_service>> is greater than can be accommodated by <<term_smooth_time_adjustments>> to the <<term_system_clock>>. This may occur, for example:

* when the <<acronym_ts_service>> is unreachable for prolonged periods, or
* following hardware failures and/or operator errors in the <<vol1_spec_sdpi_p_actor_somds_provider>> and/or <<acronym_ts_service>>, or
* after switching to a different and/or backup <<acronym_ts_service>> when the primary <<acronym_ts_service>> becomes unavailable, or
* when network congestion leads to asymmetrical network transport delays while exchanging messages with the <<acronym_ts_service>>.

In <<ref_rfc_5905>> this is referred to as a step-adjustment or a non-slewing time adjustment. In the absence of step-adjustments, <<term_timestamp>>s generated by a <<vol1_spec_sdpi_p_actor_somds_participant>>'s <<term_system_clock>> are well-behaved:

* they never decrease,
* have a well defined relationship to timestamps within the same <<term_epoch>>, and
* have well defined relationships to peer <<term_system_clock>>s and <<term_reference_clock>>s.

The presence of <<term_abrupt_time_adjustment>> creates <<term_epoch>>s of consistency: periods where the <<vol1_spec_sdpi_p_actor_somds_participant>>'s timestamps are well-behaved, separated by step-changes. At best, <<term_epoch>> are separated by a constant temporal offset; at worst <<vol1_spec_sdpi_p_actor_somds_participant>>s may have insufficient information to determine the relationship between <<term_epoch>> (e.g., changes at the <<acronym_ts_service>> that do not represent a change in elapsed time to unbiased observers).

[NOTE]
====
R1520 excludes non-slewing adjustments (<<term_abrupt_time_adjustment>>s) to the <<acronym_ts_service>> by the RESPONSIBLE ORGANIZATION during normal operation.

====

The diagram below illustrates a sequence of state updates incorporating <<term_timestamp>>s from two different epochs. In the illustration, an <<term_abrupt_time_adjustment>> has shifted the device's <<term_time_reference_frame>> forward, creating (from the device's perspective) a gap in time. Timestamps obtained in epoch 0, before the required <<term_abrupt_time_adjustment>> was detected, may not be accurate (from the perspective of an unbiased observer).

image::vol3-diagram-biceps-ext-non-slewing_time.svg[align=center]


A <<vol1_spec_sdpi_p_actor_somds_provider>> may start a new MDIB versioning sequence when it requires an <<term_abrupt_time_adjustment>>. However, this may disrupt one or more System Function Contributions (<<acronym_sfc>>) by the <<vol1_spec_sdpi_p_actor_somds_provider>> or its <<acronym_somds>> peers.

This specification adds an extension to the BICEPS Participant Model enabling richer communication of changes to the <<vol1_spec_sdpi_p_actor_somds_participant>>'s local time-reference frame using:

* epoch versioning,
* optional epoch time-step offsets,
* optional versioning of `pm:CalibrationInfo/@Time`, `pm:AlertSystemState/@LastSelfCheck`, `pm:AlertConditionState/@DeterminationTime`, `pm:AbstractMetricValue/@StartTime`, `pm:AbstractMetricValue/@StopTime`, `pm:AbstractMetricValue/@DeterminationTime`, `pm:AbstractContextState/@BindingStartTime` and `pm:AbstractContextState/@BindingEndTime`.

[sdpi_level=+1]
====== Model

The clock epoch schema is available in <<vol3_appendix_a_xml_schemas_timestamp_version>>. <<vol3_example_extension_clock_discontinuities>> shows an exemplary XML instance of a <<vol2_clause_dev_30_message_getmdibresponse, {var_label_dev_30_message_getmdibresponse}>> from a device that has experienced two recent <<term_abrupt_time_adjustment>>s following three adjustments some time in the past. Of particular note:

* the clock state includes epoch time-step offsets for epochs 3 and 4; earlier versions are not referenced and therefore not required,
* the state for metric `m1` references epoch version 3; all timestamps in this state are versioned,
* the timestamp for metric `m2` is not versioned; its timestamp is less than `pm:ClockState/@LastSet` and its value should be treated with greater suspicion than later timestamps,
* although the current time (`pm:ClockState/@DateAndTime`) is also less than `pm:ClockState/@LastSet`, the current time is always reported using with <<term_timestamp>> from the current <<term_epoch>>; its value need not be treated with any more suspicion than normal,
* each `sdpi:Epoch` includes a `@Version`, `@Timestamp` and `@Offset`; the <<term_timestamp>> is from the versioned <<term_epoch>>, adding the `@Timestamp` and `@Offset` provides a timestamp for an equivalent point in time for the next epoch version (see illustration below),
* the default value of any timestamp not specifically versioned is the current <<term_epoch>> version.

`sdpi:Epoch/@Offset` gives the change in time from the `sdpi:Epoch/@Timestamp` in the previous <<term_epoch>> to an equivalent point in time in the new epoch:

image::vol3-diagram-biceps-ext-non-slewing_adj.svg[align=center]

.Example MDIB state following two recent <<term_abrupt_time_adjustment>>s
[#vol3_example_extension_clock_discontinuities]
====
[source,xml]
----
include::../../listings/vol3-clause-biceps-content-example-timestamp-version.xml[]
----
====

[sdpi_level=+1]
====== Requirements

.R0600
[sdpi_requirement#r0600,sdpi_req_level=shall]
****
A <<vol1_spec_sdpi_p_actor_somds_provider>> shall include the `sdpi:EpochSupport` extension and set `sdpi:EpochSupport/@Version=1` in every <<term_system_clock>> `pm:ClockDescriptor`, used as part of its System Function Contribution (<<acronym_sfc>>), that uses epoch versioning for <<term_abrupt_time_adjustment>>s.

.Notes
[NOTE]
[%collapsible]
====
* The presence of `sdpi:EpochSupport` indicates support for this extension and related requirements.
* A <<vol1_spec_sdpi_p_actor_somds_provider>> may set `ext:MustUnderstand="true"` to prevent consumers that do not understand this extension from processing the <<acronym_mdib>>.

====

****

.R0601
[sdpi_requirement#r0601,sdpi_req_level=shall]
****
A <<vol1_spec_sdpi_p_actor_somds_consumer>> shall ignore all epoch version information on any system clocks that do not include the `sdpi:EpochSupport` extension in any MDIB version or if the `sdpi:EpochSupport/@Version` changes within a single sequence id.

.Notes
[NOTE]
[%collapsible]
====
* The `spdi:EpochSupport` extension is intended to immutable.
* A <<vol1_spec_sdpi_p_actor_somds_consumer>> may rely on future versions of the extension being backwards compatible.

====

****

.R0605
[sdpi_requirement#r0605,sdpi_req_level=shall]
****
The <<vol1_spec_sdpi_p_actor_somds_provider>> shall increment `sdpi:Epochs/@Version` by exactly one, beginning from 0, for every non-slewing time adjustment to any system clock used as part of its System Function Contribution (<<acronym_sfc>>).

****

.R0606
[sdpi_requirement#r0606,sdpi_req_level=shall]
****
A <<vol1_spec_sdpi_p_actor_somds_provider>> shall set the version of all versioned timestamps to 0 when it assigns a new MDIB sequence identifier (`pm:MdibVersionGroup/@SequenceId`).

.Notes
[NOTE]
[%collapsible]
====
* Epoch versions are scoped to the `pm:MdibVersionGroup/@SequenceId`.

====
****

.R0610
[sdpi_requirement#r0610,sdpi_req_level=shall]
****
A <<vol1_spec_sdpi_p_actor_somds_provider>> that versions timestamps in any `pm:AbstractMetricValue`, `pm:AbstractContextState`, `pm:AlertSystemState`, `pm:CalibrationInfo` and/or `pm:AlertConditionState` shall include, in every clock state update, the complete history of epoch offsets from the earliest version referenced in the MDIB to the current epoch.

.Notes
[NOTE]
[%collapsible]
====
* Epoch offsets provide a mechanism for consumers to (approximately) reconstruct time between epochs. Reconstruction can only be approximate because there is no mechanism to determine the source and timing of any external discrepancies that led to the abrupt change in a <<term_time_reference_frame>>.
* This allows a <<vol1_spec_sdpi_p_actor_somds_provider>> to choose which timestamps it versions. For example context binding timestamps (which may remain out of date significantly longer than other metrics) could be versioned but regularly updated metrics may not require timestamp versions.

====
****


Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[#vol3_appendix_a_xml_schemas_timestamp_version]
=== Timestamp epoch version XML Schema

[source,xml]
----
include::../../../sources/extension-models/timestamp/TimestampVersion.xsd[]
----
2 changes: 2 additions & 0 deletions asciidoc/volume3/tf3-ch-8.3.2-biceps-content.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -274,5 +274,7 @@ include::biceps-extension-provisions/tf3-ch-8.3.2.9.6-extension-equipment-identi

include::biceps-content-module/tf3-ch-8.3.2.9.7-compound-metric-modelling.adoc[]

include::biceps-extension-provisions/tf3-ch-8.3.2.9.8-extension-timestamp.adoc[]

// 8.3.2.10
include::mdib-efficiency/tf3-ch-8.3.2.10-mdib-efficiency-considerations.adoc[]
4 changes: 3 additions & 1 deletion asciidoc/volume3/tf3-ch-a-xml-schemas.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,6 @@ include::biceps-extension-provisions/tf3-ch-a-xml-schemas-coded-attribute.adoc[]

include::biceps-extension-provisions/tf3-ch-a-xml-schemas-gender.adoc[]

include::biceps-extension-provisions/tf3-ch-a-xml-schemas-equipment-identifier.adoc[]
include::biceps-extension-provisions/tf3-ch-a-xml-schemas-equipment-identifier.adoc[]

include::biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc[]
Loading
Loading