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 13 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 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.
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: 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
168 changes: 168 additions & 0 deletions asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,17 @@ NOTE: The 50ms target accuracy is suitable for highly demanding use cases like r
====
****

.R1521
[sdpi_requirement#r1521,sdpi_req_level=should]
****
The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_participant>> should configure its <<acronym_ts_service>> client to give priority to system clock adjustments that are slewing (over stepping adjustments).
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

.Notes
[%collapsible]
====
NOTE: If possible, the priority of slewing adjustments starts applying once the <<vol1_spec_sdpi_p_actor_somds_participant>> has acquired synchronization to the <<acronym_ts_service>> after a system (re)start.
====
****


===== Scenario: <<acronym_stad>> {var_use_case_id}.2 - Device is connected to the MD LAN network and a user wants to change the device's time
Expand Down Expand Up @@ -214,6 +225,163 @@ NOTE: This requirement supplements RR1162 in <<ref_ieee_11073_10700_2022>>: _The
====
****

[#vol1_clause_appendix_c_use_case_stad_non_slew]
===== Scenario: <<acronym_stad>> {var_use_case_id}.6 - A device, operational in the MD LAN network, determines a non-slewing time adjustment is required

*Given* The device is operational on the <<acronym_md_lan>> network,

*When* The device's clock-discipline algorithm determines a non-slewing time adjustment is required,

*Then* The device will create a log entry that includes at least a time-stamp for the adjustment in both the time-reference frame before and after the non-slewing adjustment was made,

*And* The <<vol1_spec_sdpi_p_actor_somds_provider>> will notify <<vol1_spec_sdpi_p_actor_somds_consumer>>s, using its system function contributions (<<acronym_sfc>>), of the change to the provider's time-reference frame,

*Or* The <<vol1_spec_sdpi_p_actor_somds_provider>> will initiate a new MDIB sequence.

NOTE: a device's time-reference frame may jump forward or backward in time in a single, large, step (from the perspective of an external observer) following a non-slewing time adjustment.

NOTE: two distinct epochs are created by a non-slewing time adjustment, each with a distinct time-reference frame. Both the rate of the passage of time and the determination time assigned to a single event may differ significantly between epochs (from the perspective of an external observer).

NOTE: non-slewing time adjustments may occur, for example, when a device rejoins a network, an absent <<acronym_ts_service>> returns to operation or be caused by hardware failure or operator error (e.g., making non-slewing adjustments to the <<acronym_ts_service>> time-reference frame while it is being used by one or more <<vol1_spec_sdpi_p_actor_somds_participant>>s).

NOTE: non-slewing time adjustments may result in a constant or variable offset between epochs. For constant offsets, the difference (to an unbiased observer) between any two timestamps obtained in different epochs is constant. For variable offsets, the difference (to an unbiased observer) between any two timestamps obtained in different epochs depends on when, within each epoch, the timestamp was obtained.

====== Safety, Effectiveness & Security Considerations and Requirements

// This provides information for auditing.
.R1560
[sdpi_requirement#r1560,sdpi_req_level=shall]
****
The <<vol1_spec_sdpi_p_actor_somds_participant>> shall include the determination time of the log entry in both the time-reference frame before, and after, each non-slewing clock adjustment.
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

.Notes
[%collapsible]
====

NOTE: This requirement supplements TR1340 in <<ref_ieee_11073_10700_2022>>: _An SDC BASE PARTICIPANT SHOULD log each non-slewing adjustment of the local clock._

====
****

// This is for providers to inform consumers of the non-slewing adjustment.
// It is necessary to have a version here for providers that don't use NTP clock-discipline to smoothly adjust clocks and just set the clock (hopefully not going back in time).
// Using `ClockState/@LastSet` like this avoids having to extend everything that needs a timestamp to support versioning (because any timestamp in the MDIB before the LastSet
// is questionable following a transition to a new epoch). Epoch versioning is then an extension that lets the consumer determine how questionable a timestamp is.
// If we have a `Epochs/@Current` and update `ClockState/@LastSet` I don't think we need to also include a "Questionable" flag or change `ClockState/@ActiviationState` as proposed
// during the workshop. Using `ClockState/@LastSet` seems better than just changing the @Activation state because the consumer could determine which timestamps are questionable.
.R1522
[sdpi_requirement#r1522,sdpi_req_level=shall]
****
When the <<vol1_spec_sdpi_p_actor_somds_provider>> detects a step adjustment of a system clock, used in making its System Function Contribution (<<acronym_sfc>>), the <<vol1_spec_sdpi_p_actor_somds_provider>> shall either:

* initiate a new MDIB sequence by assigning a new MDIB sequence identifier, or
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved
* set `pm:ClockState/@LastSet` to the earliest time that is unambiguously in the current epoch and increment `sdpi:Epochs/@Version`.

.Notes
[%collapsible]
====
NOTE: The <<term_manufacturer>> of the <<vol1_spec_sdpi_p_actor_somds_consumer>> considers the risks arising from timestamps spanning time-reference frames from a non-slewing clock adjustment having occurred at the <<vol1_spec_sdpi_p_actor_somds_provider>> when the <<vol1_spec_sdpi_p_actor_somds_consumer>> receives a changed value in the <<vol1_spec_sdpi_p_actor_somds_provider>>'s MDIB sequence identifier or `pm:ClockState/@LastSet` and `sdpi:Epochs/@Version`.

NOTE: This clarifies the ambiguity in <<ref_ieee_11073_10207_2017>>, section B.182 when slewing is used to smoothly adjust the time-reference frame (using, for example, the <<ref_rfc_5905, NTPv4>> clock-discipline algorithm) where information from one or more <<acronym_ts_service>>s is used to maintain clock-discipline and does not "set" the clock.

NOTE: Any timestamps in the MDIB prior to `pm:ClockState/@LastSet` may not have been obtained from the current time-reference.

====
****

Timestamps obtained in an ealier epoch may be treated with greater suspicion than those obtained in the current epoch by a <<vol1_spec_sdpi_p_actor_somds_participant>>. `pm:ClockState/@LastSet` provides the unambiguous begining of the current epoch in the time-reference frame of the current epoch. For example, when a non-slewing adjustment moves the device's time-reference frame forward, any timestamps in the MDIB greater than start of the new epoch are unambiguously in the new epoch. In contrast, when the device's time-reference frame moves backward, only timestamps greater than the latest timestamp obtained from the epoch before the time-reference frame moved backward are unambiguously in the current epoch. That is, the timestamps obtained from the new time-reference frame may overlap timestamps obtained from the prior time-reference frame. These examples are illustrated below:

There is no overlap in timestamps when a non-slewing adjustment shifts the device clock forward in time.

image::vol1-diagram-use-case-stad-ns-forward.svg[align=center]

When a non-slewing adjustment shifts the device's time-reference frame back in time, only timestamps before the last timestamp recorded in the MDIB from epoch 0 belong unambiguously to the new time-reference frame.

image::vol1-diagram-use-case-stad-ns-back.svg[align=center]

When a device experiences multiple non-slewing adjustments in a short period of time, the earliest timestamp unambiguously in the current time-reference frame may be from an earlier epoch.

image::vol1-diagram-use-case-stad-ns-back-forth.svg[align=center]

// This is to introduce versioning epochs.
.R1561
[sdpi_requirement#r1561,sdpi_req_level=may]
****
The <<vol1_spec_sdpi_p_actor_somds_provider>> may indicate a timestamp belongs to a specific epoch using the SDPi epoch extension.
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

.Notes
[NOTE]
[%collapsible]
====
Binding timestamps in the <<acronym_mdib>> to a specific epoch may be useful for states that are not updated frequently.

====
****

.R1562
[sdpi_requirement#r1562,sdpi_req_level=shall]
****
The <<vol1_spec_sdpi_p_actor_somds_consumer>> shall consider the risks arising from relying on timestamps obtained from different epochs.
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

.Notes
[NOTE]
[%collapsible]
====
It may not be possible to reliably determine the relationship between timestamps obtained from different time-reference frames without addition information regarding the cause of the non-slewing adjustment. For example, if a non-slewing adjustment arises because the device clock was running faster (or slower) than the reference clock then the arithmetic difference between two events spanning the adjustment (even when combined with the step adjustment duration) may not match the elapsed time experienced by an unbiased observer.

====
****


// This is for the sledge hammer approach. I can't figure out what a universal rule could be or how to communicate epoch changes
// across MdibVersionGroup/@SequenceId since it seems that any information inside the MDS implicitly is scoped to the
// sequence id.
.R1566
[sdpi_requirement#r1566,sdpi_req_level=shall]
****
The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_provider>> that changes the MDIB sequence identifier when it can no longer make smooth adjustments to its time-reference frame shall consider the risks arising from gaps in continuous data.
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

.Notes
[NOTE]
[%collapsible]
====
Non-slewing time-adjustments may indicate a serious error that impacts data that has already been:

* displayed on a chart to the user,
* exported to other systems.

====
****

// This may be unneccessary since it applies to all participants from 10700:§5.2.2,RR1162. It does make it clear
// that epoch versions aren't required though.
.R1568
[sdpi_requirement#r1568,sdpi_req_level=shall]
****
The <<term_manufacturer>> of a <<vol1_spec_sdpi_p_actor_somds_provider>> that chooses to omit epoch versions from any timestamp shall consider the risks arising from erroneous timestamps.
PaulMartinsen marked this conversation as resolved.
Show resolved Hide resolved

[NOTE]
[%collapsible]
====
Epoch versions may not be required for timestamps on items that update frequently.

====
****

// This may be unnecessary as the device could fault at any time. However, perhaps it is useful as a way
// to surface behaviours as part of conformity statements. And it emphasises the myriad of problems with
// time steps.
.R1569
[sdpi_requirement#r1569,sdpi_req_level=may]
****
A <<vol1_spec_sdpi_p_actor_somds_participant>> may enter a fault state by, for example, setting the `MdsState/@ActivationState` to `Fail` upon detecting a non-slewing time adjustment that it otherwise cannot recover from.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I want this to be even more strict:

While a provider cannot verify coherency of timestamps in the MDIB, for every MDS that is affected, the provider shall set pm:Clock/@ActivationState = Fail.

NOTE: If for technical reasons or risk related measures a provider cannot set a new sequence id after a non-slewing time adjustment ensued, the provider sets the clock into fail mode such that consumers know they must not trust any timestamps that are read from the provider's MDIB.


That includes setting the clock to fail even if epoch versions are used. This allows for the consumers that do not understand epoch versions to act as if the clock would not be reliable anymore. From that it follows that the epoch versioning extension is required to be uniquely identifiable by a consumer as a means to recover from a failed clock.


If a provider does not want to set its clock to Fail, it may produce a new MDIB sequence at any time.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Sorry, I'm not sure I completely follow this one and its interaction with other points. I think it depends on whether we put mustUnderstand="true" on some extension in the clock descriptor, and whether we are trying to deal with participants outside SDPi. This is where I got to:

If we put mustUnderstand="true" on in the clock's descriptor for an versioning extension:

  • consumers have to understand whatever we come up with in SDPi otherwise they must not to process messages.
  • the 3rd option in 1522 provides more nuance on which timestamps are reliable and which are not:
    • sdpi:Epochs/@Version changing signals a abrupt time adjustment,
    • pm:ClockState/@LastSet signals when that occurred (in the current time-reference frame),
    • no timestamps before @LastSet can be relied on even if the consumer understands epoch versioning and the timestamps are versioned because:
      • the reason for the abrupt timestamp can't be determined by the participants, and
      • the timing for the abrupt time adjustment can't be determined by any participant to a resolution any higher than the sync timing.
  • I don't think there's really any downside to setting pm:ClockState/@ActivationState != "On" but in the above context it isn't necessary.
  • We could reserve Fail for clock failures (e.g., hardware fault) and use Stndby for synchronization failures; maybe we don't need to separate these things though.
  • I think the strict part is in 1522 (providers must chose one of the options); 1569 is more about consumers understanding of what the fault state means; I assume providers can go into a fault state whenever they like.
  • Perhaps a pm:AbstractDescriptor/@SafetyClassification="MedA" (display only) might have a relaxed attitude to abrupt time jumps happy to just convey the information while a MedC (clinical function) provider might fault the whole device.
  • I better make 1569 refer to the provider as consumers don't have a activation state to set.
  • Is world time always a vital part of system function contribution? Perhaps a heart-lung machine would be more interested in continuing oxygenation than time-stamping exactly when a time-discontinuity occurred?

If mustUnderstand isn't true, I don't think there is anything about how a consumer should interpret ClockState/@ActivationState != "On". It might surprise them but SDPi conformance testing could validate they do something sensible. Although consumers that are on-board with SDPi should know what do with mustUnderstand=true. Are we worried about non SDPi compliant consumers? This just makes me think we should have mustUnderstand=true.

In conclusion, I'm not sure what to do next here.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Ok, I think there is a lot of confusion going on - let my try to settle things:

  • The requirement I listed above is needed to determine the time frame in which the clock is not trustworthy - it is not sufficient to formulate something along the lines of R1522, because it does only determine how to act at the time when there is a non-slewing adjustment. However, there was no restriction on the duration of keeping the activation state in StdBy
  • Eventually, things need to be integratable in a way that consumers who do not support epoch versions can seemlessly rely on the StdBy to express incoherent timestamps - epoch versions is an extra feature consumers may use to adjust otherwise broken timestamps.

Now that I am getting depper into the topic, I think we can make the extension mustUnderstand=false, because we signify "something is being wrong" by using the StdBy flag and add epoch information to allow for consumers to calculate correct times based on epoch versions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

This time business is much more complicated than it looks! I intended the latest R1522 to do all the things you mentioned:


When the <<vol1_spec_sdpi_p_actor_somds_provider>> detects an abrupt time adjustment of a system clock, used in making its System Function Contribution (<<acronym_sfc>>), the <<vol1_spec_sdpi_p_actor_somds_provider>> shall either:

  1. initiate a new MDIB sequence by assigning a new MDIB sequence identifier, or
  2. set pm:ClockState/@ActivationState to StndBy when any timestamp in a <<acronym_mdib>> version was not obtained from the time-reference frame of the active clock in the same version, or
  3. set pm:ClockState/@LastSet to the earliest time that is unambiguously in the current epoch and increment sdpi:Epochs/@Version.

To break it down:

  • (1) is the sledgehammer, providing no information about the timeframe for invalid clock but may be a useful option for some providers.
  • (2) signals to the consumer, using ClockState/@ActivationState, that there are one or more timestamps from a different time-reference frame in the mdib. They could be anywhere (metrics, components or extensions etc) and there is no way to tell which timestamps are trustworthy and which are not.
  • (3) does two things:
    • it provides equivalent information to consumers as (2), though it does it using sdpi:Epochs/@Version changing and pm:ClockState/@LastSet. That is a consumer can compare every timestamp (whether metric, component or extension) to the value of pm:ClockState/@LastSet; any that are strictly less are untrustworthy. That's the case at the time of the adjustment or six months later.
    • it lets consumers figure out which timestamps are untrustworthy (by comparing with pm:ClockState/@LastSet).

Note

the provider may generate timestamps from the current time-reference frame that are less than pm:ClockState/@LastSet. This can happen when a non-slewing adjustment moves the clock backwards in time and the MDIB previously contained timestamps from the "future".

The downside of (3) not setting the @ActivationState is that the consumer has to:

  1. understand sdpi:Epochs/@Version, and
  2. check every timestamp for validity.

One approach I can see providers taking with option 3 is leaving timestamps to update of their own accord. Notably, contexts may have untrustworthy timestamps until they are validated again, perhaps in a week or two when the provider is used on a new patient. It seems consumers might have a hard time figuring out what to do if @ActivationState="StndBy" for a week or two. However, if only setting @ActivationState="StndBy" is one of the approaches we want to have here, then I think it would make sense for the versioned one to also do that.

So, I'll update the text to:


When the <<vol1_spec_sdpi_p_actor_somds_provider>> detects an abrupt time adjustment of a system clock, used in making its System Function Contribution (<<acronym_sfc>>), the <<vol1_spec_sdpi_p_actor_somds_provider>> shall either:

  1. initiate a new MDIB sequence by assigning a new MDIB sequence identifier, or
  2. set pm:ClockState/@ActivationState to StndBy when any timestamp in a <<acronym_mdib>> version was not obtained from the time-reference frame of the active clock in the same version, or
  3. set pm:ClockState/@LastSet to the earliest time that is unambiguously in the current epoch and increment sdpi:Epochs/@Version and set pm:ClockState/@ActivationState to StndBy while any timestamp in a <<acronym_mdib>> version is less than pm:ClockState/@LastSet.

I worded it slightly differently for greater clarity with the relationship to pm:ClockState/@LastSet but the behaviour of pm:ClockState/@ActivationState is identical for 2 & 3.


[NOTE]
[%collapsible]
====

* A sudden change in a participant's time-reference frame may require intervention by the OPERATOR or RESPONSIBLE ORGANIZATION.
* A <<vol1_spec_sdpi_p_actor_somds_participant>> may continue delivery with a subset one or more of its nominal System Function Contribution (<<acronym_sfc>>) following a non-slewing adjustment reporting the activation state of components using `AbstractDeviceComponentState/@ActivationState`.

====
****
Loading
Loading