generated from IHE/supplement-template
-
Notifications
You must be signed in to change notification settings - Fork 1
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
PaulMartinsen
wants to merge
15
commits into
master
Choose a base branch
from
203b-non-slewing-time-adjustment
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
9f1e31c
Added first solution by Javier Espina, which added requirements to re…
PaulMartinsen d18ed6d
Added new extension to support versioning timestamps
PaulMartinsen 99b980c
* Clarified link to TR1340
PaulMartinsen dcf91d7
Added requirement to reset epoch versions with MDIBVersionGroup/@Sequ…
PaulMartinsen 326d7c2
Added diagram to be extra clear about timestamps and offsets.
PaulMartinsen 32670f0
Made `pm:ClockState/@ActivationState` part of 3rd option in R1522.
PaulMartinsen 7b4b61c
Disable R1568, to remove later. The consumer is responsible for deali…
PaulMartinsen 70308df
Reference 20701, which also references "setting" the clock.
PaulMartinsen 2aa9627
Added note to clarify link between abrupt and non-slewing time adjust…
PaulMartinsen 693dc87
Editorial changes to improve clarity and consistency.
PaulMartinsen d9c5cd6
Clarify what needs to be changed when there is a new sequence.
PaulMartinsen 222b1b9
First attempt at an extension element to declare support for epoch ve…
PaulMartinsen 485d076
Split consumer and provider parts of requirement R0600 into two separ…
PaulMartinsen ea16987
Normalize terms for clarity and consistency.
PaulMartinsen 7b89337
Added reference to terms.
PaulMartinsen File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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.
58 changes: 58 additions & 0 deletions
58
asciidoc/listings/vol3-clause-biceps-content-example-timestamp-version.xml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
137 changes: 137 additions & 0 deletions
137
...c/volume3/biceps-extension-provisions/tf3-ch-8.3.2.9.8-extension-timestamp.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,137 @@ | ||
[#vol3_clause_timestamp_versioning] | ||
====== Timestamp versioning | ||
|
||
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. | ||
|
||
==== | ||
**** | ||
|
||
|
7 changes: 7 additions & 0 deletions
7
...volume3/biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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[] | ||
---- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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:
There was a problem hiding this comment.
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:
another might be:
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.
There was a problem hiding this comment.
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.There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 apm:ClockDescriptor
and updated requirements. It includes an optionalMustUnderstand
and aVersion
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.
There was a problem hiding this comment.
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:
and in the use case: