diff --git a/CHANGELOG.md b/CHANGELOG.md index 870681f8..e723294f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ Each section shall contain a list of action items of the following format: ` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 13:00 + 12:00 + + 2:00 + 1:00 + + + 0 + :00 + + + + + + + + + + + + + + + + + + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 13:00 + 12:00 + 11:00 + 10:00 + 9:00 + 8:00 + 7:00 + 6:00 + 6:00 + 5 + :00 + 4:00 + 3 + :00 + + + Synchronize + clock + + Time source + Device + clock (T + ) + D + + + + + + +4:00 + + + Epoch 2 + Epoch 3 + + + + + + + + + + + + + + + + + + + + Organization + reference + clock (T + ) + R + + diff --git a/asciidoc/images/vol1-diagram-use-case-stad-cns-non-linear.svg b/asciidoc/images/vol1-diagram-use-case-stad-cns-non-linear.svg new file mode 100644 index 00000000..9bfd3ff9 --- /dev/null +++ b/asciidoc/images/vol1-diagram-use-case-stad-cns-non-linear.svg @@ -0,0 +1,222 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 13:00 + 12:00 + 11:00 + 10:00 + 9:00 + 8:00 + 7:00 + 6:00 + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 11:00 + 10:00 + 9:00 + 8:00 + 7:00 + + + + + + + + + + + + + + + + Epoch 0 + Epoch 1 + Organization + reference clock (T + ) + R + Device + clock (T + ) + D + + + Synchronize + clock + + +2:00 + + + + +3:00 + +1:00 + + + :00 + 0 + -1 + :00 + Time source + + + Report delivered + + + + + + + + diff --git a/asciidoc/images/vol1-diagram-use-case-stad-cns-schedule.svg b/asciidoc/images/vol1-diagram-use-case-stad-cns-schedule.svg new file mode 100644 index 00000000..47dd2682 --- /dev/null +++ b/asciidoc/images/vol1-diagram-use-case-stad-cns-schedule.svg @@ -0,0 +1,404 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Synchronize + clock + + 16:00 + 17:00 + 18:00 + 19:00 + + + + + + + + Epoch 4 + Epoch 5 + + + + + + + + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 13:00 + 12:00 + + 2:00 + 1:00 + + + 0 + :00 + + + + + + + + + + + + + + + + + + 14:00 + 15:00 + 16:00 + 17:00 + 18:00 + 19:00 + 13:00 + 12:00 + 11:00 + 10:00 + 9:00 + 8:00 + 7:00 + 6:00 + 6:00 + 5 + :00 + 4:00 + 3 + :00 + + + Synchronize + clock + + + + Synchronize + clock + + + + Synchronize + clock + + 2:00 + 1:00 + 0 + :00 + 6:00 + 5 + :00 + 4:00 + 3 + :00 + 10:00 + 9:00 + 8:00 + 7:00 + + + + + + + + + + + + + + + + + + + + + + + + + + + Time source + Stratum 0 + clock (T + ) + 0 + Organization + reference + clock (T + ) + R + Device 1 + clock (T + ) + D + + + + + + + + + +4:00 + +4:00 + + + + + + + + + + + + + + + + + + Synchronize + clock + + 16:00 + 17:00 + 18:00 + 19:00 + + + + + + + + + + Epoch 4 + Epoch 5 + + + Synchronize + clock + + 2:00 + 1:00 + 0 + :00 + 6:00 + 5 + :00 + 4:00 + 3 + :00 + 7:00 + + + + + + + + + + + + + + + + + + + + + Device 2 + clock (T + ) + D + +4:00 + + 14:00 + 15:00 + 13:00 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/asciidoc/images/vol1-diagram-use-case-stad-ns-back-forth.svg b/asciidoc/images/vol1-diagram-use-case-stad-ns-back-forth.svg new file mode 100644 index 00000000..2e5978bd Binary files /dev/null and b/asciidoc/images/vol1-diagram-use-case-stad-ns-back-forth.svg differ diff --git a/asciidoc/images/vol1-diagram-use-case-stad-ns-back.svg b/asciidoc/images/vol1-diagram-use-case-stad-ns-back.svg new file mode 100644 index 00000000..814a0f48 Binary files /dev/null and b/asciidoc/images/vol1-diagram-use-case-stad-ns-back.svg differ diff --git a/asciidoc/images/vol1-diagram-use-case-stad-ns-forward.svg b/asciidoc/images/vol1-diagram-use-case-stad-ns-forward.svg new file mode 100644 index 00000000..242138d9 Binary files /dev/null and b/asciidoc/images/vol1-diagram-use-case-stad-ns-forward.svg differ diff --git a/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_adj.svg b/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_adj.svg new file mode 100644 index 00000000..f39b8e30 Binary files /dev/null and b/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_adj.svg differ diff --git a/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_time.svg b/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_time.svg new file mode 100644 index 00000000..fa76dd69 --- /dev/null +++ b/asciidoc/images/vol3-diagram-biceps-ext-non-slewing_time.svg @@ -0,0 +1,282 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + midnight + 3 am + 6 am + 9 am + noon + + + 3 + 2024 12 04 + + m1 + m2 + + + 3h + + + + 4h + + 1733270400 + 1733274000 + 1733277600 + 1733281200 + 1733292000 + 1733302800 + 1733270400 + 1733284800 + 1733295600 + 1733306400 + 1733317200 + 1733288400 + 1733299200 + 1733310000 + 1733320800 + + Epoch time [seconds since 1 January 1970] + + + + + + + 5 + 4 + + + + + + + Epoch + + + + ü + + + + ü + + pm:ClockState/@LastSet + + + + pm:ClockState/@LastSet + + + + + m4 + + m3 + + + + + pm:ClockState/ + @ + DateAndTime + 1733324400 + 3 pm + + + + + + + + + + + + + + + + diff --git a/asciidoc/listings/vol3-clause-biceps-content-example-timestamp-version.xml b/asciidoc/listings/vol3-clause-biceps-content-example-timestamp-version.xml new file mode 100644 index 00000000..13fa9853 --- /dev/null +++ b/asciidoc/listings/vol3-clause-biceps-content-example-timestamp-version.xml @@ -0,0 +1,96 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/asciidoc/volume0/tf0-ch-d-glossary.adoc b/asciidoc/volume0/tf0-ch-d-glossary.adoc index 0396782f..ba22c453 100644 --- a/asciidoc/volume0/tf0-ch-d-glossary.adoc +++ b/asciidoc/volume0/tf0-ch-d-glossary.adoc @@ -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], <> | | [[term_object_management_group, Object Management Group (OMG)]] Object Management Group diff --git a/asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc b/asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc index 9de67842..e9656fe8 100644 --- a/asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc +++ b/asciidoc/volume1/tf1-ch-b-ref-standards-conformance.adoc @@ -66,6 +66,10 @@ 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_rfc_9110, RFC 9110]]] R. Fielding, M. Nottingham, J. Reschke, RFC 9110, HTTP Semantics, June 2022, available at https://www.rfc-editor.org/rfc/rfc9110 + * [[[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. diff --git a/asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc b/asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc index 83e4c134..107d10ed 100644 --- a/asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc +++ b/asciidoc/volume1/use-cases/tf1-ch-c-use-case-stad.adoc @@ -52,6 +52,22 @@ NOTE: The 50ms target accuracy is suitable for highly demanding use cases like r ==== **** +.R1521 +[sdpi_requirement#r1521,sdpi_req_level=should] +**** +The <> of a <> should configure its <> client to prioritize <> to the <>. + +.Notes +[%collapsible] +==== +NOTE: <>s could use, for example, <> to satisfy this requirement. That is, employing cold and warm startup and <>s to synchronize the <> with a <> <>. + +NOTE: <>s using other synchronization standards +should strongly favour methods such as adjusting clock frequency over large changes (forward +or backward in time) to maintain an accurate <>. + +==== +**** ===== Scenario: <> {var_use_case_id}.2 - Device is connected to the MD LAN network and a user wants to change the device's time @@ -178,7 +194,7 @@ If a <> cannot reach the <> {var_use_case_id}.5 - Devices are operational in the MD LAN network but cannot access the TS Service and clock drift is unacceptable -*Given* The <> is operational on the <> network +*Given* The <> is operational on the <> network *And* The <> is no longer operational or otherwise inaccessible @@ -194,7 +210,7 @@ If a <> cannot reach the <>'s risk management, the device may be disconnected entirely from the <> network. -NOTE: It is the <>'s responsibility to decide if timestamps are accurate enough to execute its <>. +NOTE: As a consequence of requirements <> and <>, it is the <>'s responsibility to decide if timestamps are accurate enough to execute its <>. ====== Safety, Effectiveness and Security - Requirements and Considerations @@ -207,13 +223,302 @@ The <> of a <> shal [%collapsible] ==== -NOTE: Clocks of <>s run apart due to lack of synchronization with NTP servers, different clock drifts or cyberattacks. +NOTE: Clocks of <>s run apart due to lack of synchronization with NTP servers, different clock drifts or cyber-attacks. NOTE: This requirement supplements RR1162 in <>: _The MANUFACTURER of an SDC BASE CONSUMER SHALL consider the RISKs resulting from erroneous timestamps._ ==== **** +[#vol1_clause_appendix_c_use_case_stad_non_slew] +===== Scenario: <> {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 <> network, + +*When* The device's <> determines an <> is required, + +*Then* The device will create a log entry that includes at least a <> for the adjustment in both the <> before and after the <> was made, + +*And* The <> will notify <>s, using its system function contributions (<>), of the change to the provider's <>, + +*Or* The <> will initiate a new MDIB sequence. + +NOTE: a device's <> may jump forward or backward in time in a single large (e.g., more than 5 minutes), step (from the perspective of an external observer) following an <>. + +NOTE: two distinct <>s are created by an <>: one prior to the abrupt adjustment and one after. Each epoch has a distinct <>. Both the rate which time passes and the determination time assigned to a single event may differ significantly between epochs (from the perspective of an external observer). + +NOTE: <>s may occur, for example, when a device is used in an emergency or wireless situation and collects data before joining a network and updating its clock, an absent <> returns to operation, following hardware failure or operator error (e.g., making <>s to the <> <> while it is being used by one or more <>s). + +NOTE: although an <> starts with a constant offset between two <>s at a single point in time, it may introduce constant or variable (linear and/or non-linear) offsets between timestamps obtained within the <>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 <> following an <> without additional information not available to the <>. + +====== Terms +// figure out where to put this. + +[%autowidth] +[cols="^1,<3"] +|=== +|Term |Definition + +| [[term_abrupt_time_adjustment,abrupt time adjustment]] Abrupt time adjustment +| A large change (typically more than 5 minutes) to a <>'s <> to reconcile differences between the time reported by a <> and a <>, within the statistical uncertainty of the synchronization algorithm, as quickly as possible. Abrupt time-adjustments are also known as step-changes and <>s, particularly when using <> to synchronize a <>. + +| [[term_clock_discipline_algorithm,clock-discipline algorithm]] Clock-discipline algorithm +| The algorithm employed by a <> client to minimize the error between the <> and the <>. It my include include startup calibration steps, smooth (e.g., slewing) and, rarely, abrupt (e.g., non-slewing) corrections. + +| [[term_epoch,epoch]] Epoch +| A distinct period of time characterized by a consistent temporal properties described by a <>. + +| [[term_non_slewing_time_adjustment,non-slewing time adjustment]] Non-slewing time adjustment +| The <> to a system clock's <> described by <>. + +| [[term_reference_clock,reference clock]] Reference clock +| The source of time obtained from a <> and shared between <>s. + +| [[term_slewing_adjustments,slewing time adjustments]] Slewing time adjustments +| Adjustments, typically small, made to a <>'s frequency described by <>. Generally so the time reported by the <> matches that of a <> at some point in the not too distant future, within the statistical uncertainty of the synchronization algorithm. + +| [[term_smooth_time_adjustments,smooth time adjustments]] Smooth time adjustments +| A gradual adjustment within a <>, characterised by a continuous and monotonically increasing progression of timestamps without abrupt jumps or disruptions to the passage of time. Generally so that the time reported by a system clock matches that of a <> at some point in the future, within the statistical uncertainty of the synchronization algorithm. Typically involves running the <> faster or slower for some period. + +| [[term_system_clock,system clock]] System clock +| A source of <>s used in a <>s system function contributions (<>). + +| [[term_time_reference_frame,time-reference frame]] Time-reference frame +| A device-specific context for measuring and assigning timestamps to events. The reference frame is defined by its rate of passage of time and alignment to some external temporal standard (e.g., provided by a <>). The reference frame's time-rate may vary with time (e.g., a <> to synchronize with an external temporal standard). Abrupt changes to the time-reference frame alignment to an external standard (e.g., <>), create distinct time-reference frames with different temporal characteristics. + +| [[term_timestamp,timestamp]] Timestamp +| A point in time obtained from a <>. Timestamps are obtained within the context of a <>. + +| [[term_timestamp_version,timestamp version]] Timestamp version +| A unique identifier, within the scope of a MDIB sequence, of a <> epoch. + +|=== + + +====== Safety, Effectiveness & Security Considerations and Requirements + +// This provides information for auditing. +.R1560 +[sdpi_requirement#r1560,sdpi_req_level=shall] +**** +The <> shall log each <> of the <> with an entry that includes the determination time of the log entry in both the <> before, and after, each <>. + +.Notes +[%collapsible] +==== + +NOTE: This requirement supplements TR1340 in <>— _An SDC BASE PARTICIPANT SHOULD log each <> of the device clock_ — requiring specific information in the log to support post incident analysis. + +==== +**** + +// 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. + +.R1522 +[sdpi_requirement#r1522,sdpi_req_level=shall] +**** +When the <> detects an <> of a <>, the <> shall either: + +* initiate a new MDIB sequence by assigning a new <> sequence identifier, or +* set `pm:ClockState/@ActivationState` to `StndBy` when any timestamp in a <> version was not obtained from the time-reference frame of the active clock in the same version, or +* set `pm:ClockState/@LastSet` to the earliest time that is unambiguously in the current <> and increment `sdpi:Epochs/@Version` and set `pm:ClockState/@ActivationState` to `StndBy` while any timestamp in a <> version is less than `pm:ClockState/@LastSet`. + +.Notes +[%collapsible] +==== +NOTE: The <> of the <> considers the risks arising from <>s spanning <>s from an <> having occurred at the <> when the <> receives a changed value in the <>'s MDIB sequence identifier or when the `pm:ClockState/@ActivationState` is `StndBy`. + +NOTE: This clarifies the ambiguity in <>, section B.182 and <>, R0014 when a participant uses slewing to make <> (using, for example, the <> <>) where information from one or more <>s is used to maintain clock-discipline and does not (generally) "set" the clock. + +NOTE: Any <> strictly-less than `pm:ClockState/@LastSet` in the MDIB when `pm:ClockState/@ActivationState` is set to `StndBy` may be untrustworthy. + +==== +**** + +Timestamps obtained in an earlier <> may be treated with greater suspicion than those obtained in the current epoch by a <>. `pm:ClockState/@LastSet` provides the unambiguous beginning of the current epoch using a <> from the current epoch. For example (and illustrated below): + +* when an <> moves the device's <> forward, any <> in the MDIB greater than start of the new epoch are unambiguously in the new epoch. +* when the device's <> moves backward, only <>s greater than the latest timestamp obtained from the prior epoch are unambiguously in the current epoch. That is, timestamps obtained from the new <> may overlap timestamps obtained from the prior <>. + +There is no overlap in timestamps when an <> shifts the device clock forward in time. + +image::../images/vol1-diagram-use-case-stad-ns-forward.svg[align=center] + +When an <> shifts the device's <> back in time, only timestamps before the last timestamp recorded in the MDIB from epoch 0 belong unambiguously to the new <>. +image::../images/vol1-diagram-use-case-stad-ns-back.svg[align=center] +When a device experiences several <>s in a short period of time, the earliest timestamp unambiguously in the current <> may be from an earlier <>. +image::../images/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 <> may indicate a <> belongs to a specific <> using the SDPi epoch extension. + +.Notes +[NOTE] +[%collapsible] +==== +Binding timestamps in the <> to a specific <> may be useful for states that are not updated frequently. + +==== +**** + +.R1562 +[sdpi_requirement#r1562,sdpi_req_level=shall] +**** +The <> of a <> shall consider the risks arising from relying on <>s obtained from different <>s. + +.Notes +[NOTE] +[%collapsible] +==== +It may not be possible to reliably determine the relationship between <> obtained from different <>s without addition information regarding the cause of an <>. Consider, for example, an <> that arises when the <> was running significantly faster (or slower) than the <>. The arithmetic difference in time between two events spanning the adjustment (even when combined with the size of the step adjustment) may not match the elapsed time experienced by an unbiased observer because time passed at different rates in the different epochs. + +==== +**** + + +// 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 <> of a <> that changes the MDIB sequence identifier when it can no longer make <> to its <> shall consider the risks arising from gaps in continuous data. + +.Notes +[NOTE] +[%collapsible] +==== +An abrupt time adjustment 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 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 emphasizes the myriad of problems with +// time steps. +.R1569 +[sdpi_requirement#r1569,sdpi_req_level=may] +**** +A <> may enter a fault state by, for example, setting the `MdsState/@ActivationState` to `Fail` following an <> that it otherwise cannot recover from. + +[NOTE] +[%collapsible] +==== + +* A sudden change in a participant's time-reference frame may require intervention by the OPERATOR or RESPONSIBLE ORGANIZATION. +* A <> may continue delivery with a subset one or more of its nominal System Function Contribution (<>) following an <> reporting the activation state of components using `AbstractDeviceComponentState/@ActivationState`. + +==== +**** + + +[#vol1_clause_appendix_c_use_case_stad_non_slew_received] +===== Scenario: <> {var_use_case_id}.7 - A <>, operational in the MD LAN network, receives data affected by an abrupt time adjustment + +*Given* The <> is operational on the <> network, + +*When* The <> receives notifications and/or <> state indicating a <> has made abrupt time adjustment to its device clock, + +*Then* The <> will notify next users of data of suspicious timestamps. + +NOTE: an <> is an extremely rare event on a properly functioning <> network, nonetheless participants should be prepared to continue <> where possible. + +Consider, for example, a medical device used for spot measurements, and +collects measurements in an area without network coverage before connecting to a <> network, synchronizing its clock and making collected data available. Such a device may have a precise, though inaccurate, clock before synchronizing with the organization reference clock creating an <>, as shown below. The clock might be inaccurate because the medical device was powered off for some time or it may have been used on a different <> network with a different reference clock. Measurements made before the <> could be corrected by applying a suitable offset. These adjustments could be made, before making the data available to a <>, by the medical device itself, or later using offsets conveyed using the <> extension. + +image::../images/vol1-diagram-use-case-stad-cns-linear.svg[align-center] + +It may be difficult or impossible for a device to determine the correct timestamp for a historical measurement following an <>. Consider, for example, a device with a clock that is running slower than the Responsible Organization's reference clock as illustrated below (exaggerated for clarity). Synchronizing the clock at 14:00 (organization-time) corrects future timestamps but it is not possible to correctly adjust earlier timestamps from device reports which differ from organization time between -1:00 and +3:00, depending on when they were made. + +image::../images/vol1-diagram-use-case-stad-cns-non-linear.svg[align-center] + +An <> occurring at the Responsible Organization's reference clock (when compared to global time standards) may also be difficult reconcile with various devices updating their clock following different synchronization schedules, as illustrated below. + +image::../images/vol1-diagram-use-case-stad-cns-schedule.svg[align-center] + +// Its okay to give up following an abrupt time step +.R1600 +[sdpi_requirement#r1600,sdpi_req_level=may] +**** +A <> may disconnect or go into a fail-safe mode when it determines an <> has occurred in a <> required to continue its <>. + +.Notes +[NOTE] +[%collapsible] +==== +A consumer relying on the temporal accuracy of historic data for its <> may require operator input to continue safe operation following an <> to one or more of its data sources. +==== +**** + +// Use the message timestamp for early detection of temporal anomalies +.R1601 +[sdpi_requirement#r1601,sdpi_req_level=should] +**** +A <> should use the mandatory, low-precision, `Date` field included in HTTP response messages (<>, §6.6.1) to determine if discrepancies between <> clocks exceed requirements for its <>. + +.Notes +[NOTE] +[%collapsible] +==== +* This requirement supports a <> considering the risk resulting from erroneous timestamps <>, RR1162. +* By monitoring timestamp on message responses (such as subscription renew requests), a <> may be able to take appropriate action, such as alerting the operator, before using data with suspicious timestamps. +==== +**** + +// Include message timestamp in reports too, and use the preferred format (not the obsolete ones) +.R1602 +[sdpi_requirement#r1602,sdpi_req_level=shall] +**** +A <> shall include the `Date` field in all HTTP response messages and notification messages sent to a <> as the best available approximation of the date and time of message generation, using the "preferred format" defined in <>, §5.6.7. + +.Notes +[NOTE] +[%collapsible] +==== +* The `Date` field in HTTP response messages is mandatory for an origin server with a clock (<>, §6.6.1). This requirement extends the presence of the date field to reports and clarifies the format to use. +* The <> may respond with the 409 (conflict) HTTP status code if it finds the time supplied by the <> conflicts with its current perception of time. +==== +**** + +// Alert next users of the problem. +.R1603 +[sdpi_requirement#r1603,sdpi_req_level=shall] +**** +A <> shall notify next users of invalid and/or suspicious timestamps arising from <> that affect its <>. + +.Notes +[NOTE] +[%collapsible] +==== +* Operators and downstream systems (e.g., central record keeping systems) may be impacted beyond the <>'s immediate <> by inconsistencies in temporal data. +* Notifying next users could include writing an entry in a log accessible to next users. +* Notifying next users could visual and/or audible indication to operators through colour, iconography or visual styling on timestamps affected by the <>. +==== +**** + +// Adjust timestamps. +.R1604 +[sdpi_requirement#r1604,sdpi_req_level=shall] +**** +A <> adjusting invalid and/or suspicious timestamps arising from <> shall continue to treat the adjusted timestamp as invalid and/or suspicious. + +.Notes +[NOTE] +[%collapsible] +==== +* A <> may use information provided, for example, by the <> using, for example, the <> extension to improve the accuracy of a suspicious timestamp, however it should still notify next users. +==== +**** \ No newline at end of file diff --git a/asciidoc/volume3/biceps-content-module/tf3-ch-8.3.2.9.1-extension-constraints.adoc b/asciidoc/volume3/biceps-content-module/tf3-ch-8.3.2.9.1-extension-constraints.adoc index 6c16aa5e..bdb3f610 100644 --- a/asciidoc/volume3/biceps-content-module/tf3-ch-8.3.2.9.1-extension-constraints.adoc +++ b/asciidoc/volume3/biceps-content-module/tf3-ch-8.3.2.9.1-extension-constraints.adoc @@ -50,3 +50,22 @@ In order to strengthen interoperability and avoid leaky abstraction, <> p **** A <> shall not provide BICEPS extensions that are based on or use the XML Schema QName type. **** + +[#vol3_clause_extension_timestamp_versioning, sdpi_level=+1] +====== Timestamp versioning + +The <> extension provides mechanisms to relate `pm:Timestamp` to <>s created by <>s. + +.R0021 +[sdpi_requirement#r0021,sdpi_req_level=should] +**** +Biceps extensions, with timestamps who's interpretation by a <> would be affected by unexpected abrupt time adjustments, should support timestamp versioning using the <> extension. + +.Notes +[NOTE] +[%collapsible] +==== +* Extension authors can add types that inherit from `sdpi:TimestampEpochVersionType` to support versioning their timestamps. +==== + +**** diff --git a/asciidoc/volume3/biceps-extension-provisions/tf3-ch-8.3.2.9.8-extension-timestamp.adoc b/asciidoc/volume3/biceps-extension-provisions/tf3-ch-8.3.2.9.8-extension-timestamp.adoc new file mode 100644 index 00000000..8731acb0 --- /dev/null +++ b/asciidoc/volume3/biceps-extension-provisions/tf3-ch-8.3.2.9.8-extension-timestamp.adoc @@ -0,0 +1,185 @@ +[#vol3_clause_timestamp_versioning] +====== Timestamp versioning + +BICEPS does not provide any means to convey step-changes in a <>'s <> (see <>). + +A <> includes <>s in many state updates. For example: `pm:AlertConditionState/@DeterminationTime`, `pm:AbstractMetricValue/@DeterminationTime` and `pm:AbstractContextState/@BindingStartTime`. From time-to-time, though rarely in normal operation, a +<> may determine that the difference between its <> and that of the <> is greater than can be accommodated by <> to the <>. This may occur, for example: + +* when a device is used in an emergency or wireless situation, collecting data before joining a network and updating its clock, +* when the <> is unreachable for prolonged periods, or +* following hardware failures and/or operator errors in the <> and/or <>, or +* after switching to a different and/or backup <> when the primary <> becomes unavailable, or +* when network congestion leads to asymmetrical network transport delays while exchanging messages with the <>. + +In <> this is referred to as a step-adjustment or a non-slewing time adjustment. In the absence of step-adjustments, <>s generated by a <>'s <> are well-behaved: + +* they never decrease, +* have a well defined relationship to timestamps within the same <>, and +* have well defined relationships to peer <>s and <>s. + +The presence of <> creates <>s of consistency: periods where the <>'s timestamps are well-behaved, separated by step-changes. At best, <> are separated by a constant temporal offset; at worst <>s may have insufficient information to determine the relationship between <> (e.g., changes at the <> that do not represent a change in elapsed time to unbiased observers). + +[NOTE] +==== +<> excludes non-slewing adjustments (<>s) to the <> by the RESPONSIBLE ORGANIZATION during normal operation. + +==== + +The diagram below illustrates a sequence of state updates (`m1`, `m2`, `m3`, `m4`) using <>s from three different epochs (3, 4, 5). In the illustration, an <> shifted the device's <> forward by four hours from 7 am to 11 am, creating (from the device's perspective) a gap in time. A second <> shifted the device's <> backward three hours from 1 pm to 10 am. The device experienced three <>s in the past (because the first epoch version is 0). + +image::../images/vol3-diagram-biceps-ext-non-slewing_time.svg[align=center] + +NOTE: The <>s serve to illustrate the extension only; it would be very unusual for a device to experience the time adjustments shown. + +A <> may start a new MDIB versioning sequence when it encounters an <>. However, this may disrupt one or more System Function Contributions (<>) by the <> or its <> peers. + +NOTE: A <> is not required to create a new MDIB versioning sequence when it encounters an <> (see <>). + +This specification adds an extension to the BICEPS Participant Model enabling richer communication of changes to the <>'s local time-reference frame using a combination of: + +* 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`. + +Other Biceps extensions should provide similar mechanisms to version appropriate timestamps (<>). Refer to the extension documentation and schema for details. + + + +[sdpi_level=+1] +====== Model + +The clock epoch schema is available in <>. There are three parts to the extension: + +. `sdpi:EpochSupport`, an extension for `pm:ClockDescriptor` so that <>s are aware that a <> implements this extension and may prepare to receive versioned timestamps. +. `sdpi:Epochs`, an extension for `pm:ClockState`, which contains a list of the <>s referenced in the <>. +. extensions to (optionally) attach epoch versions to `pm:AbstractState` timestamps found in `pm:CalibrationInfo`, `pm:AlertSystemState`, `pm:AlertConditionState`, `pm:AbstractMetricValue`, `pm:AbstractContextState`. + +In addition, this extension defines specific interpretation for `pm:ClockState/@ActivationState` and `pm:ClockState/@LastSet`. The `pm:ClockState/@ActivationState` is set to `StndBy` when any timestamp in a <> version was not obtained from the current <> regardless of whether that timestamp is versioned or not. This lets consumers know they may not be able to trust some or all of the timestamps in a <> even if they don't understand this extension. To identify which timestamps are unreliable, `pm:ClockState/@LastSet` is set to the earliest reliable timestamp. That is, the earliest timestamp in a <> version that is guaranteed to be in the current <> considering the entire history of <>s. It may be used to determine if a timestamp is reliable, even if it is not versioned. + +<> shows an exemplary XML instance of a <> from a device that has experienced two recent <>s following three adjustments some time in the past. It corresponds to the sequence of events in the diagram above. Of particular note: + +* the provider supports this version of the timestamp versioning extension because the `pm:Clock` descriptor includes `sdpi:EpochSupport/[@Version='1']`. +* in `pm:State[@xsi:type='pm:ClockState']`: +** `@ActivationState` is `StndBy` because the mdib contains timestamps that were not obtained from the current epoch (that is, `@DeterminationTime` for `m1` and `m2`), +** `@LastSet` shows any timestamp less than "1733317200000" (1 p.m.) may not be from the current epoch, +** `@DateAndTime` shows this mdib snapshot was created at "1733324400000" (3 p.m.), +** `sdpi:Epochs[@Version='5']` indicates the current epoch is 5, +** `sdpi:Epochs/Epoch` shows timestamps from epochs 4 and 3 may be used in the mdib; earlier versions are not included because they are not referenced in the mdib. The `@Timestamp` on, for example, epoch 4 records the time (in the epoch 4 <> when the abrupt time adjustment was made; the equivalent time in epoch 5, the next <>, can be determined by adding the `@Offset` to the `@Timestamp`). +* `pm:State[@DescriptorHandle='m1']` includes three timestamps (`DeterminationTime`, `StartTime` and `StopTime`); all were created in epoch 3 using a clock with the descriptor handle `clk`. It was not necessary to include the `@Clock` attribute because there is only one clock in the <>. +* `pm:State[@DescriptorHandle='m2']` includes a single timestamp (`DeterminationTime`); it doesn't contain a specific epoch version however, the `DeterminationTime` is less than `pm:State[xsi:type='pm:ClockState']/@LastSet` so the timestamp _may_ be from an earlier epoch (and, as the diagram shows, `m2` was determined in epoch 4. However, the provider has decided not to provide that information, perhaps because this metric is regularly updated and a new value will be reported soon). +* `pm:State[@DescriptorHandle='m3']` also includes a single timestamp (`DeterminationTime`); it doesn't contain a specific epoch version however, the `DeterminationTime` is less than `pm:State[xsi:type='pm:ClockState']/@LastSet` so the timestamp _may_ be from an earlier epoch (in this case, as the diagram shows, `m3` was determined in the current epoch. However, the provider has decided not to provide that information, perhaps because this metric is regularly updated and a new value will be reported soon). +* `pm:State[@DescriptorHandle='m4']` also includes a single timestamp (`DeterminationTime`); again without an epoch version. However, the `DeterminationTime` is greater than `pm:State[xsi:type='pm:ClockState']/@LastSet` so the timestamp is from the current epoch. + +`sdpi:Epoch/@Offset` gives the change in time from the `sdpi:Epoch/@Timestamp` in the previous <> to an equivalent point in time in the new epoch as shown in the diagram below. + +image::../images/vol3-diagram-biceps-ext-non-slewing_adj.svg[align=center] + +.Example MDIB state following two recent <>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 <> shall include the `sdpi:EpochSupport` extension and set `sdpi:EpochSupport/@Version=1` in every <> `pm:ClockDescriptor`, used as part of its System Function Contribution (<>), that uses epoch versioning for <>s. + +.Notes +[NOTE] +[%collapsible] +==== +* The presence of `sdpi:EpochSupport` indicates support for this extension and related requirements. +* A <> may set `ext:MustUnderstand="true"` to prevent consumers that do not understand this extension from processing the <>. + +==== + +**** + +.R0601 +[sdpi_requirement#r0601,sdpi_req_level=shall] +**** +A <> 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 be immutable. +* A <> may rely on future versions of the extension being backwards compatible. + +==== + +**** + +.R0605 +[sdpi_requirement#r0605,sdpi_req_level=shall] +**** +The <> 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 (<>). + +**** + +.R0606 +[sdpi_requirement#r0606,sdpi_req_level=should] +**** +A <> should 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 generally scoped to the `pm:MdibVersionGroup/@SequenceId`. Some providers may carry versioned timestamps across new sequences, particularly if the new sequence is created for reasons other than an abrupt time adjustment. + +==== +**** + +.R0610 +[sdpi_requirement#r0610,sdpi_req_level=shall] +**** +A <> 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 <>. +* This allows a <> 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. + +==== +**** + +.R0611 +[sdpi_requirement#r0611,sdpi_req_level=shall] +**** +A <> shall not change the epoch version assigned to a timestamp without creating a new timestamp. + +.Notes +[NOTE] +[%collapsible] +==== +* Epoch versions and timestamps are immutable and may not change independently. + +==== +**** + +.R0612 +[sdpi_requirement#r0612,sdpi_req_level=shall] +**** +When the source clock of a versioned timestamp is ambiguous, a <> shall include a reference to the `pm:ClockDescriptor/@Handle` in `sdpi:TimestampEpochVersionType/@Clock`. + +.Notes +[NOTE] +[%collapsible] +==== +* The clock source is not ambiguous when there is only one clock in the whole <>, or there is only one clock in the `pm:Mds` containing the `pm:AbstractState` that includes the versioned timestamp and the version timestamp does not use a clock from a different `pm:Mds`. +* The `sdpi:TimestampEpochVersionType/@Clock` may be omitted when the source clock is not ambiguous to reduce message size. +* This extension does not support timestamps in a single `pm:AbstractState` to be versioned from more than one source clock. +==== +**** diff --git a/asciidoc/volume3/biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc b/asciidoc/volume3/biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc new file mode 100644 index 00000000..da0f972c --- /dev/null +++ b/asciidoc/volume3/biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc @@ -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[] +---- diff --git a/asciidoc/volume3/tf3-ch-8.3.2-biceps-content.adoc b/asciidoc/volume3/tf3-ch-8.3.2-biceps-content.adoc index b19098c9..41198e6a 100644 --- a/asciidoc/volume3/tf3-ch-8.3.2-biceps-content.adoc +++ b/asciidoc/volume3/tf3-ch-8.3.2-biceps-content.adoc @@ -276,5 +276,7 @@ include::biceps-content-module/tf3-ch-8.3.2.9.7-compound-metric-modelling.adoc[] include::biceps-content-module/tf3-ch-8.3.2.9.8-localized-text-catalog-identification.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[] \ No newline at end of file diff --git a/asciidoc/volume3/tf3-ch-a-xml-schemas.adoc b/asciidoc/volume3/tf3-ch-a-xml-schemas.adoc index 29903f9c..c672a40f 100644 --- a/asciidoc/volume3/tf3-ch-a-xml-schemas.adoc +++ b/asciidoc/volume3/tf3-ch-a-xml-schemas.adoc @@ -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[] \ No newline at end of file +include::biceps-extension-provisions/tf3-ch-a-xml-schemas-equipment-identifier.adoc[] + +include::biceps-extension-provisions/tf3-ch-a-xml-schemas-timestamp-version.adoc[] \ No newline at end of file diff --git a/sources/extension-models/timestamp/TimeStampVersion.xsd b/sources/extension-models/timestamp/TimeStampVersion.xsd new file mode 100644 index 00000000..40b2029c --- /dev/null +++ b/sources/extension-models/timestamp/TimeStampVersion.xsd @@ -0,0 +1,258 @@ + + + + + + + +An extension to indicate the MDIB may include versioned timestamps, particularly if an abrupt time adjustment occurs. + +This extension can be attached to the pm:ClockDescriptor descriptor. + + + + + Advises epoch versioning support level. + + + + True if consumers are not permitted to use information from the MDIB if they do not understand the version indicated. + + + + + Epoch support used in the MDIB. Currently only version 1 support is defined. + + + + + + Time-stamp epoch version. The default version for any timestamp not versioned is the current epoch version. + + + + + + + + + An extension to version epochs arising from non-slewing time adjustments. + +This extension can be attached to the pm:ClockState/ext:Extension element. + + + + + + + + Current epoch version. + + + + + + + + + + + + + + Collection of versioned transitions between epochs. Must include every version referenced elsewhere in the MDIB. + + + + + + + + +Type defining a transition between epochs. + +Defines the step-change, which occurs at a single point in time, from the previous time-reference frame to the next time-reference frame. Adding this Offset to this Timestamp gives the point in time (to an unbiased external observer) when this time-step occurred in the next epoch's time-reference frame. + +For example, if device time advanced by 1 hour in epoch 0 at 10 am, there will be an Epoch entry for epoch version 0 with a timestamp of 10am and Offset of +1 hour. The equivalent time in epoch version 1 will be 11 am. + + + + + Epoch version when the abrupt time adjustment occurred. + + + + + + + + Timestamp, in the time-reference frame of this epoch version, when the abrupt time adjustment occurred. + + + + + Offset from this time-reference frame to the next time-reference frame. + + + + + + Base type for extensions that version timestamps. + + + + The clock versioned by this element. + + + + + + + + + An extension to version timestamps on a pm:AbstractMetricValue. + + + + + An extension to version timestamps on a pm:AbstractMetricValue. + + + + + + Epoch version for the enclosing pm:AbstractMetricValue/@DeterminationTime. + + + + + Epoch version for the enclosing pm:AbstractMetricValue/@StartTime + + + + + Epoch version for the enclosing pm:AbstractMetricValue/@StopTime + + + + + + + + An extension to version timestamps on a pm:CalibrationInfo. + + + + + An extension to version timestamps on a pm:CalibrationInfo/@Time + + + + + + Epoch version for the enclosing pm:CalibrationInfo/@Time + + + + + + + + An extension to version timestamps on a pm:AlertSystemState. + + + + + An extension to version timestamps on a pm:AlertSystemState + + + + + + Epoch version for the enclosing pm:AlertSystemState/@LastSelfCheck + + + + + + + + An extension to version timestamps on a pm:AlertConditionState. + + + + + An extension to version timestamps on a pm:AlertConditionState/@DeterminationTime + + + + + + Epoch version for the enclosing pm:AlertConditionState/@DeterminationTime + + + + + + + + An extension to version timestamps on a pm:AbstractContextState. + + + + + An extension to version timestamps on a pm:AbstractContextState + + + + + + Epoch version for the enclosing pm:AbstractContextState/@BindingStartTime + + + + + Epoch version for the enclosing pm:AbstractContextState/@BindingEndTime + + + + + + \ No newline at end of file