From 4decd8579c3c6584b0e51b95908b691403a18f2d Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Fri, 21 Aug 2026 09:30:48 +0200 Subject: [PATCH 1/4] Update the Time Architecture --- docs/features/time/_assets/data_flow.puml | 98 ------ .../_assets/absolute_time_read_flow.puml | 51 +++ .../_assets/clock_testability.puml | 34 ++ .../_assets/local_time_read_flow.puml | 46 +++ .../architecture/_assets/static_arch.puml | 38 ++ .../_assets/vehicle_time_notification.puml | 57 +++ .../_assets/vehicle_time_read_flow.puml | 43 +++ docs/features/time/architecture/index.rst | 332 +++++++++++++++++- docs/features/time/glossary.rst | 199 +++++++++++ docs/features/time/index.rst | 121 +++---- docs/features/time/requirements/index.rst | 12 +- 11 files changed, 845 insertions(+), 186 deletions(-) delete mode 100644 docs/features/time/_assets/data_flow.puml create mode 100644 docs/features/time/architecture/_assets/absolute_time_read_flow.puml create mode 100644 docs/features/time/architecture/_assets/clock_testability.puml create mode 100644 docs/features/time/architecture/_assets/local_time_read_flow.puml create mode 100644 docs/features/time/architecture/_assets/static_arch.puml create mode 100644 docs/features/time/architecture/_assets/vehicle_time_notification.puml create mode 100644 docs/features/time/architecture/_assets/vehicle_time_read_flow.puml create mode 100644 docs/features/time/glossary.rst diff --git a/docs/features/time/_assets/data_flow.puml b/docs/features/time/_assets/data_flow.puml deleted file mode 100644 index 11477fb8256..00000000000 --- a/docs/features/time/_assets/data_flow.puml +++ /dev/null @@ -1,98 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title PTP data flow - -legend top left -| <#LightCoral> | external ECU/Switch | -| <#LightBlue> | gptp stack | -| <#LightGrey> | hw on ECU | -| <#LightGreen> | mw stack | -| <#LightSalmon> | applications | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "ClientApp" #e6ffe6 - participant "Business logic" as app #LightSalmon - participant "score::time" as mw #LightGreen - end box - participant "Shared resource (ipc)" as sh #LightGreen - box "Time base provider" #LightSteelBlue - participant "Business logic" as timed_bs #LightBlue - participant "libgptp" as libgptp #LightBlue - end box - participant "OS" as os #LightBlue - participant "Time Slave" as gptp #LightBlue - participant "EMAC(eth)" as emac #LightGrey -end box -participant "TimeMaster" as ptp #LightCoral - -==Setup and Initialization== -timed_bs -> sh : create() -app -> mw: init() -note right - Create and initialize - score::time -end note -mw -> sh: init() -mw --> app : timebase ptr* - -==PTP synchronization== -loop every 125ms - ptp <--> gptp : Performing ptp\ncommunication - gptp -> gptp : Calculation GM time\nas per ptp protocol - gptp -> emac : Set synchronized time\nbased on ptp -end loop - -==Main Loop / Runtime== -loop every 50ms - timed_bs -> libgptp : Read current synchronized ptp time - libgptp -> gptp : Use `devctl` to obtain\ncurrent time - note left - switch to kernel space and involve resource manager - end note - gptp -> emac : Read time from\nEMAC register - gptp -> os : get current system (local) time - os --> gptp : Read local clock(TL0) - emac --> gptp: Synchronized ptp time 'Tptp0' - gptp --> libgptp : Current synchronized ptp time 'Tptp0' and 'TL0' - note left - switch to user space - end note - libgptp --> timed_bs : Current synchronized ptp time 'Tptp0' and 'TL0' - timed_bs -> os : get current system (local) time - os --> timed_bs : current time (TL1) - timed_bs -> timed_bs : Validate ptp time and set status flags - note left - Validation of ptp time using local clock ('TL2'): - 1. Inaccuracy detection - 2. loosing data frames detection - 3. verification for monotonicity - end note - timed_bs -> sh : Write data - note left - Store to shared resource received data - 1. last ptp time 'Tptp0' - 2. local clock 'TL0', when ptp was read and - 3. status flags - end note - -end loop - -==Client use-case== -app -> mw : Call ::Now() to read time status -mw -> sh : Read data -sh --> mw -mw -> os : get current system (local) time -os --> mw : Current time (TL2) -mw -> mw : Adjust ptp time, with local clock -note right - current_ptp_time = Tptp0 + (Tl2 - TL0) -end note -mw --> app : Adjusted ptp time and it's status - -@enduml diff --git a/docs/features/time/architecture/_assets/absolute_time_read_flow.puml b/docs/features/time/architecture/_assets/absolute_time_read_flow.puml new file mode 100644 index 00000000000..124979c4383 --- /dev/null +++ b/docs/features/time/architecture/_assets/absolute_time_read_flow.puml @@ -0,0 +1,51 @@ +@startuml + +hide footbox + +autonumber "[00]" + +title Absolute Time read (feature view) + +legend top left +| <#LightCoral> | external time source | +| <#LightBlue> | score platform stack | +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +endlegend + +!pragma teoz true +box "ECU" #f0f5f5 + box "Application process" #e6ffe6 + participant "Application" as app #LightSalmon + participant "Absolute Clock\n(client side)" as ac #LightGreen + end box + box "score::time provider process" #e6ffe6 + participant "Absolute time\nreceiver" as recv #LightGreen + end box + participant "score::someip" as someip #LightBlue +end box +participant "External time master" as master #LightCoral + +== Initialization == +app -> ac : init() +ac --> app : ready + +== Absolute time provisioning (background) == +loop periodically + master -> master : capture absolute time;\nattach Delay Tag;\nderive accuracy & security + master -> someip : absolute time, Delay Tag,\naccuracy & security + someip -->> recv : deliver the four values + recv -> recv : convert Delay Tag to a local monotonic tag;\nderive Absolute Time status + note left + Side effect: absolute time is + also applied to OS CLOCK_REALTIME + end note + recv -->> ac : publish latest snapshot +end + +== Reading the time == +app -> ac : now() +ac -> ac : compensate on the local monotonic base\n(elapsed since the local tag) +ac --> app : Snapshot\n(absolute TimePoint + \nAbsolute Time status) + +@enduml diff --git a/docs/features/time/architecture/_assets/clock_testability.puml b/docs/features/time/architecture/_assets/clock_testability.puml new file mode 100644 index 00000000000..cbb4ebbde4e --- /dev/null +++ b/docs/features/time/architecture/_assets/clock_testability.puml @@ -0,0 +1,34 @@ +@startuml + +hide footbox + +autonumber "[00]" + +title Clock mocking support (feature view) + +legend top left +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +endlegend + +!pragma teoz true +box "ECU" #f0f5f5 + box "Application process" #e6ffe6 + participant "Application" as app #LightSalmon + participant "Clock interface\n(mock)" as clock #LightGreen + end box +end box + +note over app, clock + Applies to Vehicle Clock, Local Clock + and Absolute Clock +end note + +== Test setup == +app -> clock : inject mock + +== Application reads time == +app -> clock : now() +clock --> app : controlled Snapshot\n(predetermined TimePoint + status) + +@enduml diff --git a/docs/features/time/architecture/_assets/local_time_read_flow.puml b/docs/features/time/architecture/_assets/local_time_read_flow.puml new file mode 100644 index 00000000000..8cc15ddac16 --- /dev/null +++ b/docs/features/time/architecture/_assets/local_time_read_flow.puml @@ -0,0 +1,46 @@ +@startuml + +hide footbox + +autonumber "[00]" + +title Local Time read (feature view) + +legend top left +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +| <#LightGrey> | OS / local time base | +endlegend + +!pragma teoz true +box "ECU" #f0f5f5 + box "Application process" #e6ffe6 + participant "Application" as app #LightSalmon + participant "Local Clock\n(client side)" as lc #LightGreen + end box + participant "OS" as os #LightGrey +end box + +== Steady Clock == +app -> lc : now() +lc -> os : CLOCK_MONOTONIC\n(std::chrono::steady_clock) +os --> lc : TimePoint +lc --> app : Snapshot (TimePoint) + +== System Clock == +app -> lc : now() +lc -> os : CLOCK_REALTIME\n(std::chrono::system_clock) +os --> lc : TimePoint +note left + Kept aligned to Absolute Time + by score::time +end note +lc --> app : Snapshot (TimePoint) + +== High-Resolution Clock == +app -> lc : now() +lc -> os : ClockCycles +os --> lc : TimePoint +lc --> app : Snapshot (TimePoint) + +@enduml diff --git a/docs/features/time/architecture/_assets/static_arch.puml b/docs/features/time/architecture/_assets/static_arch.puml new file mode 100644 index 00000000000..8c0fb431f0a --- /dev/null +++ b/docs/features/time/architecture/_assets/static_arch.puml @@ -0,0 +1,38 @@ +@startuml + +title Time feature static architecture + +legend top left +| <#LightCoral> | external time source | +| <#LightGrey> | OS / local time base | +| <#LightBlue> | score platform stack | +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +endlegend + +rectangle "ECU" #f0f5f5 { + actor "Feature User" as user #LightSalmon + + package "score::time" #e6ffe6 { + component "Vehicle Clock" as vc #LightGreen + component "Local Clock" as lc #LightGreen + component "Absolute Clock" as ac #LightGreen + } + + component "score::someip" as someip #LightBlue + component "OS / local clock" as os #LightGrey +} + +cloud "Vehicle network time\n(PTP)" as veh #LightCoral +cloud "Absolute time source\n(e.g. GPS / UTC)" as abs #LightCoral + +user --> vc : read vehicle time +user --> lc : read local time +user --> ac : read absolute time + +vc ..> veh : synchronized to (PTP) +lc ..> os : reads +ac ..> someip : IPC +someip ..> abs : obtains absolute time + +@enduml diff --git a/docs/features/time/architecture/_assets/vehicle_time_notification.puml b/docs/features/time/architecture/_assets/vehicle_time_notification.puml new file mode 100644 index 00000000000..2579ad28623 --- /dev/null +++ b/docs/features/time/architecture/_assets/vehicle_time_notification.puml @@ -0,0 +1,57 @@ +@startuml + +hide footbox + +autonumber "[00]" + +title Vehicle Time notification (feature view) + +legend top left +| <#LightCoral> | external time source | +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +endlegend + +!pragma teoz true +box "ECU" #f0f5f5 + box "Application process" #e6ffe6 + participant "Application" as app #LightSalmon + participant "Vehicle Clock\n(client side)" as vc #LightGreen + end box + box "score::time provider process" #e6ffe6 + participant "Time slave\n(synchronization)" as slave #LightGreen + end box +end box +participant "Grand Master" as host #LightCoral + +== Subscribe == +app -> vc : subscribe(handler, event kind) +note right + Event kinds: + - Vehicle Time status change + - sync / follow-up frame (sync-fup) + - pdelay frame + sync-fup and pdelay are independent sequences +end note +vc --> app : subscribed + +== Event (background) == +loop on each subscribed event + host <--> slave : synchronize to network time (PTP) + slave -> slave : validate, derive Vehicle Time status + slave -->> vc : notify event + vc -->> app : invoke handler(event) +end + +note over app, slave + The PTP payload data (sync-fup / pdelay) is available only via + subscription. The Vehicle Time status can also be read from now(); + subscription additionally delivers it on change. + Main use case: diagnostics. +end note + +== Unsubscribe == +app -> vc : unsubscribe() +vc --> app : unsubscribed + +@enduml diff --git a/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml b/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml new file mode 100644 index 00000000000..dd22feba266 --- /dev/null +++ b/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml @@ -0,0 +1,43 @@ +@startuml + +hide footbox + +autonumber "[00]" + +title Vehicle Time read (feature view) + +legend top left +| <#LightCoral> | external time source | +| <#LightGreen> | score::time feature | +| <#LightSalmon> | application | +endlegend + +!pragma teoz true +box "ECU" #f0f5f5 + box "Application process" #e6ffe6 + participant "Application" as app #LightSalmon + participant "Vehicle Clock\n(client side)" as vc #LightGreen + end box + box "score::time provider process" #e6ffe6 + participant "Time slave\n(synchronization)" as slave #LightGreen + end box +end box +participant "Grand Master" as host #LightCoral + +== Initialization == +app -> vc : init() +vc --> app : ready + +== Synchronization (background) == +loop periodically + host <--> slave : synchronize to network time (PTP) + slave -> slave : validate, derive Vehicle Time status,\ntimestamp on local monotonic clock + slave -->> vc : accumulate latest snapshot\n(time, local timestamp, status, metadata) +end + +== Reading the time (on demand) == +app -> vc : now() +vc -> vc : use latest accumulated snapshot;\ninterpolate on current local monotonic clock +vc --> app : Snapshot\n(vehicle TimePoint + Vehicle Time status) + +@enduml diff --git a/docs/features/time/architecture/index.rst b/docs/features/time/architecture/index.rst index 638b983ea9f..7bfcbfce204 100644 --- a/docs/features/time/architecture/index.rst +++ b/docs/features/time/architecture/index.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2025 Contributors to the Eclipse Foundation + # Copyright (c) 2026 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -17,15 +17,343 @@ Time Architecture .. document:: Time Architecture :id: doc__time_architecture - :status: draft + :status: valid :version: 1 :safety: ASIL_B :security: YES :realizes: wp__feature_arch[version==1] +Overview +-------- + +The Time feature (:term:`score::time`) provides applications with a uniform way to read +time from several distinct :term:`clock domain` s. The domain is selected explicitly by the +application, which keeps the interface consistent across domains while preventing accidental +mixing of incompatible :term:`TimePoint` types. + +The architecture distinguishes three time bases (:term:`clock domain` s), each exposed through its +own clock interface: + +* **Vehicle Time** — the network-synchronized (:term:`PTP protocol`) vehicle-wide time base, + carrying a :term:`Vehicle Time status` qualifier. It is exposed through the + :term:`Vehicle Clock`, which — because the time base depends on external synchronization — also + offers initialization, availability checks and event subscription in addition to reading the time. +* **Local Time** — the local, non-synchronized time bases (steady, system and high-resolution). + They are exposed through the :term:`Local Clock`, need no initialization and are always + available. +* **Absolute Time** — an external absolute time base (e.g. UTC from GPS), carrying an + :term:`Absolute Time status` qualifier that reflects both accuracy and security. It is exposed + through the :term:`Absolute Clock`. + +Because each :term:`clock domain` is independent and exposed through its own logical interface, +the architecture is open to future time bases (for example a further synchronized or secure +domain): a new domain is added as an additional interface without changing the existing ones. + +Description +----------- + +Uniform clock access +******************** + +All clock domains are exposed through a common, domain-agnostic interface so that +applications use the same operations regardless of which time base they read. Reading the +time returns a :term:`Snapshot` that bundles the :term:`TimePoint` with the domain's status +concept (:term:`Vehicle Time status` for the vehicle clock, :term:`Absolute Time status` for the +absolute clock; the local clocks carry no status), so callers can read the time and judge its +quality in a single call. + +Rationale Behind Architecture Decomposition +******************************************* + +The feature is decomposed along its **time bases**. Each :term:`clock domain` is an independent +time base with its own epoch, progression semantics, :term:`TimePoint` type and status concept. +The domains are logically and functionally independent: an application selects one explicitly, +and time values of different domains are distinct, incompatible types that cannot be mixed. + +Independence does not imply isolation. A time base may build on or use another — for example a +synchronized domain interpolates between synchronization updates on top of a local monotonic base, +and the :term:`System Clock` is kept aligned to :term:`Absolute Time` through the OS +``CLOCK_REALTIME`` — but such relationships are internal and do not couple the interfaces the +domains expose. + +The synchronized time bases (Vehicle Clock and Absolute Clock) additionally rely on an external +time reference and on validation of the received time. They *may* share a common supporting +component for obtaining and validating that time, but such reuse is an implementation choice, not +an architectural constraint: each synchronized domain could equally be served on its own. + +Accordingly the feature exposes one self-contained logical interface per group of time bases: +the Vehicle Clock, the Absolute Clock, and the Local Clock. The local, non-synchronized clocks +(steady, system and high-resolution) are grouped behind a single interface because they share the +same minimal operation surface (a single time read); they remain distinct domains, differing only +in their semantics, which is captured in a domain table rather than in separate architectural +elements. + +Requirements +------------ + +The Feature requirements are described in the :doc:`requirements index <../requirements/index>`. + +Static Architecture +------------------- + .. feat:: Time :id: feat__time :security: YES :safety: ASIL_B :status: valid :version: 1 + +The feature-wide static view shows the Time feature and the logical interfaces it exposes — +one per time base. Each interface is detailed in its time-base section below. + +.. feat_arc_sta:: Time Static Architecture + :id: feat_arc_sta__time__static_view + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :includes: logic_arc_int__time__vehicle_clock, logic_arc_int__time__local_clock, logic_arc_int__time__absolute_clock + :fulfils: feat_req__time__mocking_apis[version==1], feat_req__time__vehicle_time_sync[version==1], feat_req__time__abs_sync[version==1] + :belongs_to: feat__time[version==1] + + .. uml:: _assets/static_arch.puml + :scale: 50 + :align: center + + +Time Bases +---------- + +Each time base is presented with the logical interface it exposes and, where it involves +runtime synchronization behavior, its dynamic view. The local, non-synchronized clocks +resolve to a direct time read from the OS. + +Vehicle Time +************ + +The Vehicle Clock exposes the network-synchronized vehicle time. Because it depends on external +synchronization, it additionally offers subscription to synchronization events, on top of reading the time. + +Logical Interface +^^^^^^^^^^^^^^^^^ + +.. logic_arc_int:: Vehicle Clock + :id: logic_arc_int__time__vehicle_clock + :included_by: feat__time + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__vehicle_time_time_api[version==1], feat_req__time__vehicle_time_acc_qual_api[version==1], feat_req__time__vehicle_time_time_pt_qual[version==1], feat_req__time__vehicle_time_sync_log[version==1] + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_interface(need(), needs) }} + +.. logic_arc_int_op:: now + :id: logic_arc_int_op__time__vehicle_now + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__time__vehicle_clock + + Returns the current vehicle-time :term:`Snapshot` (:term:`TimePoint` plus :term:`Vehicle Time status`). + +.. logic_arc_int_op:: subscribe + :id: logic_arc_int_op__time__vehicle_subscribe + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__time__vehicle_clock + + Registers a callback that is notified on vehicle-time synchronization events. + +.. logic_arc_int_op:: unsubscribe + :id: logic_arc_int_op__time__vehicle_unsubscribe + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__time__vehicle_clock + + Removes a previously registered synchronization-event callback. + +Dynamic Architecture +^^^^^^^^^^^^^^^^^^^^ + +The :term:`Vehicle Clock` exposes two runtime interaction modes: a **pull** model — reading the +latest accumulated snapshot on demand — and an **event notification** model — subscribing to +receive notifications when new data arrives. + +.. rubric:: Reading the time + +Applications read the current vehicle time through the :term:`Vehicle Clock` (``now``). In the +background the time is continuously synchronized to the external network time +(:term:`PTP protocol`), validated, and accumulated as a snapshot. The read uses the latest +accumulated snapshot and interpolates it on the current local monotonic clock — a fast local +operation that does not cross the process boundary. + +.. feat_arc_dyn:: Vehicle Time Read + :id: feat_arc_dyn__time__vehicle + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__vehicle_time_ctrl_flow[version==1] + :belongs_to: feat__time[version==1] + + .. uml:: _assets/vehicle_time_read_flow.puml + :scale: 50 + :align: center + +.. rubric:: Receiving notifications + +Applications can subscribe to :term:`Vehicle Clock` events. Subscription is the only way to obtain +the PTP payload data (the sync/follow-up and pdelay sequences, which are independent); the +:term:`Vehicle Time status` can also be read from ``now``, and subscription additionally delivers +it as it changes. The primary use case is diagnostics — reacting to a status change or a PTP data +update in a diagnostic manner. + +.. feat_arc_dyn:: Vehicle Time Notification + :id: feat_arc_dyn__time__vehicle_subscription + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__vehicle_time_sync_log[version==1] + :belongs_to: feat__time[version==1] + + .. uml:: _assets/vehicle_time_notification.puml + :scale: 50 + :align: center + +Local Time +********** + +The Local Clock groups the local, non-synchronized time bases, provided directly by the +operating system clocks. All variants expose a single ``now`` operation returning a +:term:`Snapshot`; they require no initialization and are always available. The concrete domains +are: + +.. list-table:: Local Clock domains + :header-rows: 1 + :widths: 30,70 + + * - Domain + - Semantics + * - :term:`High-Resolution Clock` + - Monotonic, nanosecond-resolution, lowest-overhead clock. Fulfils the high-precision clock API. + * - :term:`Steady Clock` + - Monotonic, never adjusted. Preferred for elapsed-time and timeouts. Fulfils the monotonic clock API. + * - :term:`System Clock` + - Wall-clock (UTC-based) OS ``CLOCK_REALTIME``, may jump or be adjusted. Used for calendar + timestamps. Kept aligned to :term:`Absolute Time` by :term:`score::time`, so POSIX/C++ + system-clock consumers obtain the absolute time as QM data. + +Logical Interface +^^^^^^^^^^^^^^^^^ + +.. logic_arc_int:: Local Clock + :id: logic_arc_int__time__local_clock + :included_by: feat__time + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__high_prec_clock_api[version==1], feat_req__time__monotonic_clock_api[version==1] + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_interface(need(), needs) }} + +.. logic_arc_int_op:: now + :id: logic_arc_int_op__time__local_now + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__time__local_clock + + Returns the current :term:`Snapshot` (a :term:`TimePoint`) of the selected local clock domain. + +Dynamic Architecture +^^^^^^^^^^^^^^^^^^^^ + +.. rubric:: Reading the time + +All three local clock domains share the same ``now`` interface and resolve directly to an OS +clock read — no initialization or background synchronization is required. The domain is selected +at construction time and is always available. + +.. uml:: _assets/local_time_read_flow.puml + :scale: 50 + :align: center + +Absolute Time +************* + +The Absolute Clock exposes an external absolute time source (e.g. UTC from GPS). Its +:term:`Absolute Time status` carries both an :term:`accuracy qualifier` and a +:term:`security qualifier`. + +Logical Interface +^^^^^^^^^^^^^^^^^ + +.. logic_arc_int:: Absolute Clock + :id: logic_arc_int__time__absolute_clock + :included_by: feat__time + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__abs_base_api[version==1], feat_req__time__abs_acc_qual[version==1], feat_req__time__abs_sec_qual[version==1], feat_req__time__abs_sync_log[version==1] + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_interface(need(), needs) }} + +.. logic_arc_int_op:: now + :id: logic_arc_int_op__time__absolute_now + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :included_by: logic_arc_int__time__absolute_clock + + Returns the current :term:`Snapshot` (:term:`TimePoint` with :term:`Absolute Time status`). + +Dynamic Architecture +^^^^^^^^^^^^^^^^^^^^ + +.. rubric:: Reading the time + +Absolute time is delivered from an external time master through the ``score::someip`` stack. Each +sample carries a :term:`Delay Tag` so the transmission delay can be compensated. The +:term:`score::time` feature converts the :term:`Delay Tag` to a local monotonic tag before +publishing, so the :term:`Absolute Clock` compensates the delay on the local monotonic base — +preserving precision without making clients depend on the :term:`Vehicle Clock`. + +.. uml:: _assets/absolute_time_read_flow.puml + :scale: 50 + :align: center + +Mocking Support +--------------- + +The :term:`score::time` feature provides a mockable interface for each clock domain — +:term:`Vehicle Clock`, :term:`Local Clock` and :term:`Absolute Clock`. Application developers +can substitute any clock interface with a controlled implementation during testing, enabling +deterministic unit, component and integration tests of time-dependent code without requiring +a real time source (:need:`feat_req__time__mocking_apis`). + +.. uml:: _assets/clock_testability.puml + :scale: 50 + :align: center diff --git a/docs/features/time/glossary.rst b/docs/features/time/glossary.rst new file mode 100644 index 00000000000..b169ee934c2 --- /dev/null +++ b/docs/features/time/glossary.rst @@ -0,0 +1,199 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Time Glossary +============= + +Time Feature +------------ + +.. glossary:: + score::time + The Time feature. It provides applications with access to several time bases — local, + vehicle and absolute — through a uniform :term:`Clock` interface, and owns the + synchronization of the synchronized time bases. + +Core Time Model +--------------- + +.. glossary:: + Clock + A source of time. A clock produces a monotonically progressing sequence of + :term:`TimePoint` values for a given :term:`clock domain`. All clocks are read + through a uniform interface, independent of the underlying time base. + + Clock domain + The kind of time a :term:`Clock` represents (e.g. :term:`Vehicle Time` or the + :term:`Local Clock` variants). The domain is selected explicitly by the application; + each domain has its own :term:`TimePoint` type and status concept, so time values of + different domains are incompatible and cannot be mixed unintentionally. + + TimePoint + A specific point in time issued by a :term:`Clock`. TimePoints of one + :term:`clock domain` are ordered (the relations *equal* and *less than* are defined), + so two TimePoints of the same domain can be subtracted to yield a :term:`TimeSpan`. + + TimeSpan + A duration, i.e. the difference between two :term:`TimePoint` values of the same + :term:`clock domain`. Supported operations include ``TimePoint - TimePoint``, + ``TimePoint + TimeSpan``, ``TimeSpan + TimeSpan``, scaling by a factor, equality and + comparison. Subtraction saturates to zero (negative TimeSpans are not produced). + + Snapshot + The value returned when reading a :term:`Clock`. It bundles a :term:`TimePoint` with + the domain-specific status concept (e.g. :term:`Vehicle Time status`, or no status for + the local clocks), allowing a caller to read the time and judge its quality in a single + call. + + Epoch + The reference TimePoint at which a :term:`Clock` starts counting. The semantics of the + epoch are a documented property of the clock (e.g. the Unix system clock epoch is + ``1970-01-01 00:00:00 UTC``). + + Resolution + The smallest time difference an individual :term:`TimePoint` can represent. For an + ideal clock the resolution equals the reciprocal of the :term:`frequency`, but in + practice it may be coarser. + + Frequency + The rate at which a :term:`Clock` updates the :term:`TimePoint` values it issues. + + Monotonic + Property of a :term:`Clock` whose successive TimePoints never decrease + (``TP[n+1] >= TP[n]``). A *strictly monotonic* clock never repeats a value. The + :term:`System Clock` is not monotonic (it may jump backward). + + Steady + Property of a :term:`Clock` whose TimePoints advance in fixed increments of exactly + ``1 / frequency``, without jumps or rate adjustments. + + Delay Tag + A timestamp of an event — a datagram, frame, message, or any produced value — expressed in + the :term:`Vehicle Time` base. Comparing a Delay Tag against a later :term:`Vehicle Time` + yields the time elapsed since the event, for example to compensate a transmission delay. + +Clocks and Clock Domains +------------------------ + +Naming convention: a **"… Time"** term names a :term:`clock domain` — a *time base*, i.e. the +kind of time and its properties (epoch, monotony, status concept, synchronization source). A +**"… Clock"** term names the :term:`Clock` interface that *provides* that time base to +applications (the ``now`` operation, plus initialization, availability and subscription where the +time base requires it). The local time bases keep their conventional names +(:term:`Steady Clock`, :term:`System Clock`, :term:`High-Resolution Clock`) even though they are +all provided by the single :term:`Local Clock` interface. + +.. glossary:: + Vehicle Time + The :term:`clock domain` (time base) representing the vehicle-wide synchronized time, + driven by the external :term:`Grand Master` via the :term:`PTP protocol`. + Reading it yields a :term:`Snapshot` carrying a :term:`Vehicle Time status`. It is exposed + to applications through the :term:`Vehicle Clock`. + + Vehicle Clock + The :term:`Clock` interface that provides :term:`Vehicle Time`. Because that time base + depends on external synchronization, the interface additionally offers initialization, + availability checks and subscription to synchronization events, on top of reading the time. + + Local Clock + The :term:`Clock` interface that provides the local, non-synchronized time bases — + :term:`Steady Clock`, :term:`System Clock` and :term:`High-Resolution Clock`. They need no + initialization and are always available. + + Steady Clock + A monotonic, non-adjustable local time base. It never goes backward, which makes it the + standard choice for measuring elapsed time and computing timeouts. + + System Clock + A wall-clock (UTC-based) local time base — the OS ``CLOCK_REALTIME``, also reachable through + standard POSIX (``clock_gettime``) and C++ (``std::chrono::system_clock``) APIs. It may jump + or be adjusted, so it is used for calendar timestamps, not for measuring elapsed time. Its + value is kept aligned to :term:`Absolute Time` by :term:`score::time`; consumers reading it + thus obtain the absolute time, but as QM data without the :term:`accuracy qualifier` and + :term:`security qualifier`. + + High-Resolution Clock + A monotonic, nanosecond-resolution local time base optimized for low-overhead timing. + Used for tight timing loops and deadline checks. + + Absolute Time + The :term:`clock domain` (time base) representing an external absolute time source + (e.g. UTC from GPS). Reading it yields a :term:`Snapshot` carrying an + :term:`Absolute Time status`. It is exposed to applications through the + :term:`Absolute Clock`. Its transmission delay is compensated using a :term:`Delay Tag`. + + Absolute Clock + The :term:`Clock` interface that provides :term:`Absolute Time`. + +Time Quality and Status +----------------------- + +.. glossary:: + Vehicle Time status + The status concept attached to a :term:`Vehicle Time` :term:`Snapshot`. It indicates + the reliability of the time value — for example whether it is synchronized, whether a + timeout occurred, and whether the time leaped to the future or the past — together with + a rate-deviation measurement. It also carries the :term:`accuracy qualifier` and the + :term:`Time point qualifier`, letting a caller decide both whether the time value is + reliable and whether it may be treated as ASIL-B data. + + Accuracy qualifier + An indication of how accurate a :term:`TimePoint` is, i.e. how close it is to the + corresponding point in the reference time base. The accuracy qualifier is a property of + the :term:`clock domain` and is reflected in the :term:`Snapshot` returned by the :term:`Clock` interface. + + Security qualifier + An indication of the security level of a :term:`TimePoint`, i.e. whether it may be + treated as trustworthy data or not. + + Time point qualifier + An indication of the integrity level of a :term:`TimePoint`, i.e. whether it may be + treated as ASIL-B data or only as QM data. + + Absolute Time status + The status concept attached to an :term:`Absolute Time` :term:`Snapshot`. It indicates the :term:`accuracy qualifier` and + the :term:`security qualifier` of the time value, letting a caller decide whether the value is reliable enough for its use case. + +Synchronization Infrastructure +------------------------------ + +.. glossary:: + PTP protocol + Precision Time Protocol - a protocol (IEEE 802.1AS) used to synchronize clocks in a + network. + + gPTP + Generalized Precision Time Protocol, the IEEE 802.1AS profile of the + :term:`PTP protocol` used for in-vehicle Ethernet time synchronization. + + Syntonization + Alignment of clock *frequency* (rate) between nodes, as opposed to synchronization + which aligns the absolute :term:`TimePoint`. Both are required for long-term timing + consistency. + + Synchronization process metadata + Data produced by the :term:`Time slave` that includes the current vehicle time, + synchronization status, rate correction and similar values, which are the output or + intermediate artifacts of the synchronization process. + + Grand Master + The external, network-wide time source (the PTP Grand Master) that the system + synchronizes to using the :term:`PTP protocol`. + + Time slave + The synchronization actor **within the** :term:`score::time` **feature**, responsible for + synchronizing the local clock with the external :term:`Grand Master` using the + :term:`PTP protocol`, and for producing the synchronized time together with its + :term:`Synchronization process metadata` (synchronization status, time difference to the + external source, last synchronization time and the corresponding local :term:`TimePoint`). diff --git a/docs/features/time/index.rst b/docs/features/time/index.rst index 0a8bf5abfbb..f97286a0a28 100644 --- a/docs/features/time/index.rst +++ b/docs/features/time/index.rst @@ -33,20 +33,14 @@ Time :titlesonly: :hidden: - architecture/index - requirements/index - -Feature flag -============ - -To activate this feature, use the following feature flag: - -``experimental_time`` - - Abstract ======== +The :term:`score::time` feature provides applications with a uniform, type-safe API for reading +time from three independent time bases: :term:`Vehicle Time` (network-synchronized), +local time (OS clocks) and :term:`Absolute Time` (external UTC source). The feature owns +the synchronization of the synchronized time bases and supports test-time substitution of all +clock interfaces. Motivation ========== @@ -73,7 +67,7 @@ In-Vehicle Time Synchronization Within the vehicle, synchronization ensures that all ECUs reference a consistent internal time. In modern architectures, this is achieved by designating a statically defined Time Grand Master, typically a zonal controller equipped with a fast-booting microcontroller and responsible for early vehicle functions such as key detection. This controller synchronizes with the external time source and propagates time over the in-vehicle network. -The synchronization protocols relevant here are primarily Ethernet-based. The focus lies on gPTP (IEEE 802.1AS) and the corresponding specifications in AUTOSAR Adaptive to ensure compatibility with existing ECUs. Syntonization, the alignment of clock frequency, is as essential as synchronization and must be supported to maintain long-term timing consistency. +The synchronization protocols relevant here are primarily Ethernet-based. The focus lies on gPTP (IEEE 802.1AS) and the corresponding specifications in AUTOSAR Adaptive to ensure compatibility with existing ECUs. :term:`Syntonization`, the alignment of clock frequency, is as essential as synchronization and must be supported to maintain long-term timing consistency. Bridging between different network domains (e.g., Ethernet to CAN) is outside the scope of this feature. In the system context, the High-Performance Computer (HPC) is assumed to be a slave in the time distribution topology and connects via Ethernet to the grandmaster. Time synchronization within CAN segments, typically handled by zonal controllers, is not covered by this feature. @@ -96,7 +90,11 @@ Access to TimePoints should be as performant as technically feasible due to thei For cryptographic scenarios the feature also targets secure or authentic clocks. In such cases, a tamper-resistant time source is needed to ensure that time cannot be rolled back to re-enable expired certificates or bypass security controls. Authentic clocks might be signed or verified using hardware security modules. -To integrate cleanly with modern programming languages, the time access API should align with idiomatic constructs (e.g., ``std::chrono`` in C++, ``time`` in Rust), while making clear that the source of time is provided by the S-CORE platform. A dedicated namespace such as ``score::chrono`` may wrap native types to make the time source explicit. +Within :term:`score::time`, secure or authentic clocks correspond to the :term:`Absolute Clock`, +which carries a :term:`security qualifier` indicating whether the received time may be treated as +trustworthy. Hardware security module integration is out of scope for the feature. + +To integrate cleanly with modern programming languages, the time access API aligns with idiomatic constructs (e.g., ``std::chrono`` in C++, ``time`` in Rust), while making clear that the source of time is provided by the S-CORE platform. The :term:`score::time` namespace wraps native types to make the time source explicit. Consistent Logical Time Within Cause-Effect Cycles -------------------------------------------------- @@ -111,6 +109,9 @@ Sharing a consistent logical timestamp ensures deterministic computations. For i Logical time must be explicitly provided to the tasks within these cause-effect chains, but its availability in background processes or non-time-sensitive tasks is not required. +Consistent logical time for cause-effect chains is out of scope for :term:`score::time`; it is a +scheduling and middleware concern, not a clock domain provided by this feature. + .. Rationale .. ========== @@ -119,88 +120,48 @@ Logical time must be explicitly provided to the tasks within these cause-effect Specification ============= -.. note:: - From S-CORE workshop regarding Clocks, Accuracy, and Reading Current Time: - - The basic concept of Time is represented by two initial and one derived element: - - *Clocks* are the sources of time. A clock produced a sequence on *Timepoints*, each representing a specific point in time. - Timepoints have an Order, i.e. the relations "equal" and "less than" are defined. Because of this, TimePoints can be substracted, creating a *TimeSpan*. - - The following operations are valid between TimePoints and TimeSpans: - - * Substraction: TimeSpan := TimePoint - TimePoint; TimeSpan := [TimeSpan - TimeSpan] | Negative TimeSpans shall not be allowed, the substraction saturates to zero. - * Addition: TimePoint := TimePoint + TimeSpan; TimeSpan := TimeSpan + TimeSpan - * Multiplication: TimeSpan := Factor * TimeSpan - * Equality: bool := TimePoint == TimePoint; bool := TimeSpan == TimeSpan - * Comparison: bool := TimePoint < TimePoint; bool := TimeSpan < TimeSpan (this includes with equality the less-than-or-equal relation) - - The clock is characterized by main attributes: - - * Frequency: The frequency with which the clock updates the TimePoints it issues. - * Resolution: The accuracy of an individual timepoint. While an ideal clock would have a resolution that is the reciproke of the frequency in reality this may not be the case. - * Monotony: A clock can be monotonous (TP[n+1] >= TP[n] is always maintained), strictly monotonous or not monotonous - * Steady: A steady clock will update in fixed intervals, i.e. each increment is exactly 1/Frequency. For example system clock is neither monotonous nor steady because of summer/winter time and leap seconds. - * Epoch: The TimePoint the clock started ticking. The semantic of the epoch is a documentation property of the clock. Example: Unix system clock has an Epoch value of 0 on 01.01.1970, 00:00:00 UTC. - -In-Vehicle Time Synchronization -------------------------------- - -Definitions: - -**Time client** -An actor that runs on the system and is responsible for +The core time model concepts — :term:`Clock`, :term:`TimePoint`, :term:`TimeSpan` and their +operations and properties — are formally defined in the :doc:`Terms and Definitions `. -* synchronizing the local clock with an external *time host* using the PTP protocol (IEEE 802.1AS). -* providing the synchronization meta information to the clients, including score::time feature. Where meta information includes, but not limited to synchronization status (synchronized, not synchronized, unstable), time difference to the external time source, last synchronization time, current time point of the local clock and so on. +Architectural design +-------------------- -**Synchronization process metadata** -Data which is provided by the **time client** and includes the current synchronized time, synchronization status, rate correction, and so on, which are the output or intermediate artifacts of the synchronization process. - -The diagram bellow illustrates the data flow and interactions between the Time client, score::time middleware, and client applications within an ECU during PTP-based time synchronization. - -.. uml:: _assets/data_flow.puml - :caption: Data flow between time client, score::time, and clients - -Where - -* The **time client** (gPTP stack) communicates with an external time host to maintain accurate time synchronization using the PTP protocol. -* The **Time base provider** periodically reads the synchronized time from the Time client, validates it, and writes the results (including status flags and timestamps) into some shared resource towards **score::time** middleware. Different IPC mechanisms can be used for to provide actual synchronized time and its metadata to **Time base provider**, like: +.. toctree:: + :maxdepth: 1 + :glob: - * shared memory, then the **time client** writes the synchronized time and its metadata into the shared memory, which is then read by the **Time base provider** middleware. - * **Time base provider** polls for current EMAC value with ``devctl`` calls. - * other IPC methods. + ./architecture/index -* The **score::time** middleware accesses this shared resource to obtain the latest synchronized time and its metadata, adjusting the time as needed based on the local clock by requests from client applications. -* This architecture ensures efficient, low-overhead distribution of synchronized time and its status to multiple applications within the ECU, supporting both real-time and diagnostic use cases. +Requirements +============ -.. Backwards Compatibility -.. ======================= +.. toctree:: + :maxdepth: 1 + :glob: + ./requirements/* Security Impact =============== +:term:`Absolute Time` carries a :term:`security qualifier` indicating whether the received time +may be treated as trustworthy. :term:`Vehicle Time` and local time bases have no security +relevance. Applications consuming Absolute Time shall check the security qualifier before using +the :term:`TimePoint` in security-sensitive operations. Safety Impact ============= +:term:`Vehicle Time` is the only time base with a safety-relevant qualifier. Its +:term:`Snapshot` carries a :term:`Time point qualifier` indicating whether the +:term:`TimePoint` may be treated as ASIL-B data or only as QM data. All other time bases +(local time bases, :term:`Absolute Time`) are QM. -.. License Impact -.. ============== - - -How to Teach This -================== - -.. Rejected Ideas -.. ============== - - -.. Open Issues -.. =========== +Terms and Definitions +===================== +.. toctree:: + :maxdepth: 1 -Glossary -======== + glossary diff --git a/docs/features/time/requirements/index.rst b/docs/features/time/requirements/index.rst index e9183e6a850..23c5025ce5f 100644 --- a/docs/features/time/requirements/index.rst +++ b/docs/features/time/requirements/index.rst @@ -29,7 +29,7 @@ Time Synchronization :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall synchronize the local clock with an external **Time Master** using the gPTP protocol (IEEE 802.1AS). + The **score::time feature** shall synchronize the local clock with an external **Grand Master** using the gPTP protocol (IEEE 802.1AS). .. feat_req:: Vehicle Time synchronization precision :id: feat_req__time__vehicle_time_sync_prec @@ -42,8 +42,8 @@ Time Synchronization :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall synchronize the local time, see feat_req__time__vehicle_time__sync, base with **Time Master** within a defined - precision, based on the system setup. + The **score::time feature** shall synchronize the local time base with the **Grand Master** within a defined + precision, based on the system setup (see :need:`feat_req__time__vehicle_time_sync`). Note: @@ -115,9 +115,9 @@ Time Synchronization For APIs see: - * feat_req__time__vehicle_time__time_api - * feat_req__time__vehicle_time__acc_qual_api - * feat_req__time__vehicle_time__time_pt_qual + * :need:`feat_req__time__vehicle_time_time_api` + * :need:`feat_req__time__vehicle_time_acc_qual_api` + * :need:`feat_req__time__vehicle_time_time_pt_qual` *Use case:* frequent access to the current synchronized time and its metadata by multiple clients within one ECU. From 016a329766175425494ca5c104e0968792aaeaca Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Mon, 24 Aug 2026 23:36:54 +0200 Subject: [PATCH 2/4] docs(time): slim platform feature architecture page --- .../_assets/absolute_time_read_flow.puml | 51 -------- .../_assets/clock_testability.puml | 34 ------ .../_assets/local_time_read_flow.puml | 46 ------- .../architecture/_assets/static_arch.puml | 38 ------ .../_assets/vehicle_time_notification.puml | 57 --------- .../_assets/vehicle_time_read_flow.puml | 43 ------- docs/features/time/architecture/index.rst | 113 +----------------- 7 files changed, 4 insertions(+), 378 deletions(-) delete mode 100644 docs/features/time/architecture/_assets/absolute_time_read_flow.puml delete mode 100644 docs/features/time/architecture/_assets/clock_testability.puml delete mode 100644 docs/features/time/architecture/_assets/local_time_read_flow.puml delete mode 100644 docs/features/time/architecture/_assets/static_arch.puml delete mode 100644 docs/features/time/architecture/_assets/vehicle_time_notification.puml delete mode 100644 docs/features/time/architecture/_assets/vehicle_time_read_flow.puml diff --git a/docs/features/time/architecture/_assets/absolute_time_read_flow.puml b/docs/features/time/architecture/_assets/absolute_time_read_flow.puml deleted file mode 100644 index 124979c4383..00000000000 --- a/docs/features/time/architecture/_assets/absolute_time_read_flow.puml +++ /dev/null @@ -1,51 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title Absolute Time read (feature view) - -legend top left -| <#LightCoral> | external time source | -| <#LightBlue> | score platform stack | -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "Application process" #e6ffe6 - participant "Application" as app #LightSalmon - participant "Absolute Clock\n(client side)" as ac #LightGreen - end box - box "score::time provider process" #e6ffe6 - participant "Absolute time\nreceiver" as recv #LightGreen - end box - participant "score::someip" as someip #LightBlue -end box -participant "External time master" as master #LightCoral - -== Initialization == -app -> ac : init() -ac --> app : ready - -== Absolute time provisioning (background) == -loop periodically - master -> master : capture absolute time;\nattach Delay Tag;\nderive accuracy & security - master -> someip : absolute time, Delay Tag,\naccuracy & security - someip -->> recv : deliver the four values - recv -> recv : convert Delay Tag to a local monotonic tag;\nderive Absolute Time status - note left - Side effect: absolute time is - also applied to OS CLOCK_REALTIME - end note - recv -->> ac : publish latest snapshot -end - -== Reading the time == -app -> ac : now() -ac -> ac : compensate on the local monotonic base\n(elapsed since the local tag) -ac --> app : Snapshot\n(absolute TimePoint + \nAbsolute Time status) - -@enduml diff --git a/docs/features/time/architecture/_assets/clock_testability.puml b/docs/features/time/architecture/_assets/clock_testability.puml deleted file mode 100644 index cbb4ebbde4e..00000000000 --- a/docs/features/time/architecture/_assets/clock_testability.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title Clock mocking support (feature view) - -legend top left -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "Application process" #e6ffe6 - participant "Application" as app #LightSalmon - participant "Clock interface\n(mock)" as clock #LightGreen - end box -end box - -note over app, clock - Applies to Vehicle Clock, Local Clock - and Absolute Clock -end note - -== Test setup == -app -> clock : inject mock - -== Application reads time == -app -> clock : now() -clock --> app : controlled Snapshot\n(predetermined TimePoint + status) - -@enduml diff --git a/docs/features/time/architecture/_assets/local_time_read_flow.puml b/docs/features/time/architecture/_assets/local_time_read_flow.puml deleted file mode 100644 index 8cc15ddac16..00000000000 --- a/docs/features/time/architecture/_assets/local_time_read_flow.puml +++ /dev/null @@ -1,46 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title Local Time read (feature view) - -legend top left -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -| <#LightGrey> | OS / local time base | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "Application process" #e6ffe6 - participant "Application" as app #LightSalmon - participant "Local Clock\n(client side)" as lc #LightGreen - end box - participant "OS" as os #LightGrey -end box - -== Steady Clock == -app -> lc : now() -lc -> os : CLOCK_MONOTONIC\n(std::chrono::steady_clock) -os --> lc : TimePoint -lc --> app : Snapshot (TimePoint) - -== System Clock == -app -> lc : now() -lc -> os : CLOCK_REALTIME\n(std::chrono::system_clock) -os --> lc : TimePoint -note left - Kept aligned to Absolute Time - by score::time -end note -lc --> app : Snapshot (TimePoint) - -== High-Resolution Clock == -app -> lc : now() -lc -> os : ClockCycles -os --> lc : TimePoint -lc --> app : Snapshot (TimePoint) - -@enduml diff --git a/docs/features/time/architecture/_assets/static_arch.puml b/docs/features/time/architecture/_assets/static_arch.puml deleted file mode 100644 index 8c0fb431f0a..00000000000 --- a/docs/features/time/architecture/_assets/static_arch.puml +++ /dev/null @@ -1,38 +0,0 @@ -@startuml - -title Time feature static architecture - -legend top left -| <#LightCoral> | external time source | -| <#LightGrey> | OS / local time base | -| <#LightBlue> | score platform stack | -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -endlegend - -rectangle "ECU" #f0f5f5 { - actor "Feature User" as user #LightSalmon - - package "score::time" #e6ffe6 { - component "Vehicle Clock" as vc #LightGreen - component "Local Clock" as lc #LightGreen - component "Absolute Clock" as ac #LightGreen - } - - component "score::someip" as someip #LightBlue - component "OS / local clock" as os #LightGrey -} - -cloud "Vehicle network time\n(PTP)" as veh #LightCoral -cloud "Absolute time source\n(e.g. GPS / UTC)" as abs #LightCoral - -user --> vc : read vehicle time -user --> lc : read local time -user --> ac : read absolute time - -vc ..> veh : synchronized to (PTP) -lc ..> os : reads -ac ..> someip : IPC -someip ..> abs : obtains absolute time - -@enduml diff --git a/docs/features/time/architecture/_assets/vehicle_time_notification.puml b/docs/features/time/architecture/_assets/vehicle_time_notification.puml deleted file mode 100644 index 2579ad28623..00000000000 --- a/docs/features/time/architecture/_assets/vehicle_time_notification.puml +++ /dev/null @@ -1,57 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title Vehicle Time notification (feature view) - -legend top left -| <#LightCoral> | external time source | -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "Application process" #e6ffe6 - participant "Application" as app #LightSalmon - participant "Vehicle Clock\n(client side)" as vc #LightGreen - end box - box "score::time provider process" #e6ffe6 - participant "Time slave\n(synchronization)" as slave #LightGreen - end box -end box -participant "Grand Master" as host #LightCoral - -== Subscribe == -app -> vc : subscribe(handler, event kind) -note right - Event kinds: - - Vehicle Time status change - - sync / follow-up frame (sync-fup) - - pdelay frame - sync-fup and pdelay are independent sequences -end note -vc --> app : subscribed - -== Event (background) == -loop on each subscribed event - host <--> slave : synchronize to network time (PTP) - slave -> slave : validate, derive Vehicle Time status - slave -->> vc : notify event - vc -->> app : invoke handler(event) -end - -note over app, slave - The PTP payload data (sync-fup / pdelay) is available only via - subscription. The Vehicle Time status can also be read from now(); - subscription additionally delivers it on change. - Main use case: diagnostics. -end note - -== Unsubscribe == -app -> vc : unsubscribe() -vc --> app : unsubscribed - -@enduml diff --git a/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml b/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml deleted file mode 100644 index dd22feba266..00000000000 --- a/docs/features/time/architecture/_assets/vehicle_time_read_flow.puml +++ /dev/null @@ -1,43 +0,0 @@ -@startuml - -hide footbox - -autonumber "[00]" - -title Vehicle Time read (feature view) - -legend top left -| <#LightCoral> | external time source | -| <#LightGreen> | score::time feature | -| <#LightSalmon> | application | -endlegend - -!pragma teoz true -box "ECU" #f0f5f5 - box "Application process" #e6ffe6 - participant "Application" as app #LightSalmon - participant "Vehicle Clock\n(client side)" as vc #LightGreen - end box - box "score::time provider process" #e6ffe6 - participant "Time slave\n(synchronization)" as slave #LightGreen - end box -end box -participant "Grand Master" as host #LightCoral - -== Initialization == -app -> vc : init() -vc --> app : ready - -== Synchronization (background) == -loop periodically - host <--> slave : synchronize to network time (PTP) - slave -> slave : validate, derive Vehicle Time status,\ntimestamp on local monotonic clock - slave -->> vc : accumulate latest snapshot\n(time, local timestamp, status, metadata) -end - -== Reading the time (on demand) == -app -> vc : now() -vc -> vc : use latest accumulated snapshot;\ninterpolate on current local monotonic clock -vc --> app : Snapshot\n(vehicle TimePoint + Vehicle Time status) - -@enduml diff --git a/docs/features/time/architecture/index.rst b/docs/features/time/architecture/index.rst index 7bfcbfce204..e0887c25571 100644 --- a/docs/features/time/architecture/index.rst +++ b/docs/features/time/architecture/index.rst @@ -93,8 +93,8 @@ Requirements The Feature requirements are described in the :doc:`requirements index <../requirements/index>`. -Static Architecture -------------------- +Feature Overview +---------------- .. feat:: Time :id: feat__time @@ -103,23 +103,8 @@ Static Architecture :status: valid :version: 1 -The feature-wide static view shows the Time feature and the logical interfaces it exposes — -one per time base. Each interface is detailed in its time-base section below. - -.. feat_arc_sta:: Time Static Architecture - :id: feat_arc_sta__time__static_view - :security: YES - :safety: ASIL_B - :status: valid - :version: 1 - :includes: logic_arc_int__time__vehicle_clock, logic_arc_int__time__local_clock, logic_arc_int__time__absolute_clock - :fulfils: feat_req__time__mocking_apis[version==1], feat_req__time__vehicle_time_sync[version==1], feat_req__time__abs_sync[version==1] - :belongs_to: feat__time[version==1] - - .. uml:: _assets/static_arch.puml - :scale: 50 - :align: center - +The runtime (static and dynamic) architecture is defined in the ``inc_time`` module +(`Time Feature Architecture `_). Time Bases ---------- @@ -182,55 +167,6 @@ Logical Interface Removes a previously registered synchronization-event callback. -Dynamic Architecture -^^^^^^^^^^^^^^^^^^^^ - -The :term:`Vehicle Clock` exposes two runtime interaction modes: a **pull** model — reading the -latest accumulated snapshot on demand — and an **event notification** model — subscribing to -receive notifications when new data arrives. - -.. rubric:: Reading the time - -Applications read the current vehicle time through the :term:`Vehicle Clock` (``now``). In the -background the time is continuously synchronized to the external network time -(:term:`PTP protocol`), validated, and accumulated as a snapshot. The read uses the latest -accumulated snapshot and interpolates it on the current local monotonic clock — a fast local -operation that does not cross the process boundary. - -.. feat_arc_dyn:: Vehicle Time Read - :id: feat_arc_dyn__time__vehicle - :security: NO - :safety: ASIL_B - :status: valid - :version: 1 - :fulfils: feat_req__time__vehicle_time_ctrl_flow[version==1] - :belongs_to: feat__time[version==1] - - .. uml:: _assets/vehicle_time_read_flow.puml - :scale: 50 - :align: center - -.. rubric:: Receiving notifications - -Applications can subscribe to :term:`Vehicle Clock` events. Subscription is the only way to obtain -the PTP payload data (the sync/follow-up and pdelay sequences, which are independent); the -:term:`Vehicle Time status` can also be read from ``now``, and subscription additionally delivers -it as it changes. The primary use case is diagnostics — reacting to a status change or a PTP data -update in a diagnostic manner. - -.. feat_arc_dyn:: Vehicle Time Notification - :id: feat_arc_dyn__time__vehicle_subscription - :security: NO - :safety: ASIL_B - :status: valid - :version: 1 - :fulfils: feat_req__time__vehicle_time_sync_log[version==1] - :belongs_to: feat__time[version==1] - - .. uml:: _assets/vehicle_time_notification.puml - :scale: 50 - :align: center - Local Time ********** @@ -282,19 +218,6 @@ Logical Interface Returns the current :term:`Snapshot` (a :term:`TimePoint`) of the selected local clock domain. -Dynamic Architecture -^^^^^^^^^^^^^^^^^^^^ - -.. rubric:: Reading the time - -All three local clock domains share the same ``now`` interface and resolve directly to an OS -clock read — no initialization or background synchronization is required. The domain is selected -at construction time and is always available. - -.. uml:: _assets/local_time_read_flow.puml - :scale: 50 - :align: center - Absolute Time ************* @@ -329,31 +252,3 @@ Logical Interface :included_by: logic_arc_int__time__absolute_clock Returns the current :term:`Snapshot` (:term:`TimePoint` with :term:`Absolute Time status`). - -Dynamic Architecture -^^^^^^^^^^^^^^^^^^^^ - -.. rubric:: Reading the time - -Absolute time is delivered from an external time master through the ``score::someip`` stack. Each -sample carries a :term:`Delay Tag` so the transmission delay can be compensated. The -:term:`score::time` feature converts the :term:`Delay Tag` to a local monotonic tag before -publishing, so the :term:`Absolute Clock` compensates the delay on the local monotonic base — -preserving precision without making clients depend on the :term:`Vehicle Clock`. - -.. uml:: _assets/absolute_time_read_flow.puml - :scale: 50 - :align: center - -Mocking Support ---------------- - -The :term:`score::time` feature provides a mockable interface for each clock domain — -:term:`Vehicle Clock`, :term:`Local Clock` and :term:`Absolute Clock`. Application developers -can substitute any clock interface with a controlled implementation during testing, enabling -deterministic unit, component and integration tests of time-dependent code without requiring -a real time source (:need:`feat_req__time__mocking_apis`). - -.. uml:: _assets/clock_testability.puml - :scale: 50 - :align: center From e3fa0511714da6dfcf664f5367c9dcf673905abe Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Tue, 25 Aug 2026 10:21:48 +0200 Subject: [PATCH 3/4] Remove dynamic and static architecture Move dyn and static architecture to the module repo --- docs/features/time/architecture/index.rst | 8 +++----- docs/features/time/glossary.rst | 12 ------------ 2 files changed, 3 insertions(+), 17 deletions(-) diff --git a/docs/features/time/architecture/index.rst b/docs/features/time/architecture/index.rst index e0887c25571..67a77bb9a27 100644 --- a/docs/features/time/architecture/index.rst +++ b/docs/features/time/architecture/index.rst @@ -103,15 +103,13 @@ Feature Overview :status: valid :version: 1 -The runtime (static and dynamic) architecture is defined in the ``inc_time`` module +The runtime (static and dynamic) architecture is defined in the ``time`` module (`Time Feature Architecture `_). Time Bases ---------- -Each time base is presented with the logical interface it exposes and, where it involves -runtime synchronization behavior, its dynamic view. The local, non-synchronized clocks -resolve to a direct time read from the OS. +Each time base is presented with the logical interface it exposes. Vehicle Time ************ @@ -129,7 +127,7 @@ Logical Interface :safety: ASIL_B :status: valid :version: 1 - :fulfils: feat_req__time__vehicle_time_time_api[version==1], feat_req__time__vehicle_time_acc_qual_api[version==1], feat_req__time__vehicle_time_time_pt_qual[version==1], feat_req__time__vehicle_time_sync_log[version==1] + :fulfils: feat_req__time__vehicle_time_time_api[version==1], feat_req__time__vehicle_time_acc_qual_api[version==1], feat_req__time__vehicle_time_time_pt_qual[version==1], feat_req__time__vehicle_time_ctrl_flow[version==1], feat_req__time__vehicle_time_sync_log[version==1] .. needarch:: :scale: 50 diff --git a/docs/features/time/glossary.rst b/docs/features/time/glossary.rst index b169ee934c2..2fe6ade9597 100644 --- a/docs/features/time/glossary.rst +++ b/docs/features/time/glossary.rst @@ -182,18 +182,6 @@ Synchronization Infrastructure which aligns the absolute :term:`TimePoint`. Both are required for long-term timing consistency. - Synchronization process metadata - Data produced by the :term:`Time slave` that includes the current vehicle time, - synchronization status, rate correction and similar values, which are the output or - intermediate artifacts of the synchronization process. - Grand Master The external, network-wide time source (the PTP Grand Master) that the system synchronizes to using the :term:`PTP protocol`. - - Time slave - The synchronization actor **within the** :term:`score::time` **feature**, responsible for - synchronizing the local clock with the external :term:`Grand Master` using the - :term:`PTP protocol`, and for producing the synchronized time together with its - :term:`Synchronization process metadata` (synchronization status, time difference to the - external source, last synchronization time and the corresponding local :term:`TimePoint`). From e10d73f56534de15b7b2fe9e05d408deca2be40d Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Thu, 27 Aug 2026 17:56:08 +0200 Subject: [PATCH 4/4] Adjust glossary --- docs/features/time/architecture/index.rst | 4 ++-- docs/features/time/glossary.rst | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/features/time/architecture/index.rst b/docs/features/time/architecture/index.rst index 67a77bb9a27..54f945e2fe0 100644 --- a/docs/features/time/architecture/index.rst +++ b/docs/features/time/architecture/index.rst @@ -34,7 +34,7 @@ mixing of incompatible :term:`TimePoint` types. The architecture distinguishes three time bases (:term:`clock domain` s), each exposed through its own clock interface: -* **Vehicle Time** — the network-synchronized (:term:`PTP protocol`) vehicle-wide time base, +* **Vehicle Time** — the network-synchronized (:term:`gPTP`) vehicle-wide time base, carrying a :term:`Vehicle Time status` qualifier. It is exposed through the :term:`Vehicle Clock`, which — because the time base depends on external synchronization — also offers initialization, availability checks and event subscription in addition to reading the time. @@ -179,7 +179,7 @@ are: * - Domain - Semantics - * - :term:`High-Resolution Clock` + * - :term:`High-Resolution Steady Clock` - Monotonic, nanosecond-resolution, lowest-overhead clock. Fulfils the high-precision clock API. * - :term:`Steady Clock` - Monotonic, never adjusted. Preferred for elapsed-time and timeouts. Fulfils the monotonic clock API. diff --git a/docs/features/time/glossary.rst b/docs/features/time/glossary.rst index 2fe6ade9597..f3b4c7b121a 100644 --- a/docs/features/time/glossary.rst +++ b/docs/features/time/glossary.rst @@ -29,7 +29,7 @@ Core Time Model .. glossary:: Clock - A source of time. A clock produces a monotonically progressing sequence of + A source of time. A clock produces a progressing sequence of :term:`TimePoint` values for a given :term:`clock domain`. All clocks are read through a uniform interface, independent of the underlying time base. @@ -91,13 +91,13 @@ kind of time and its properties (epoch, monotony, status concept, synchronizatio **"… Clock"** term names the :term:`Clock` interface that *provides* that time base to applications (the ``now`` operation, plus initialization, availability and subscription where the time base requires it). The local time bases keep their conventional names -(:term:`Steady Clock`, :term:`System Clock`, :term:`High-Resolution Clock`) even though they are +(:term:`Steady Clock`, :term:`System Clock`, :term:`High-Resolution Steady Clock`) even though they are all provided by the single :term:`Local Clock` interface. .. glossary:: Vehicle Time The :term:`clock domain` (time base) representing the vehicle-wide synchronized time, - driven by the external :term:`Grand Master` via the :term:`PTP protocol`. + driven by the external :term:`Grand Master` via the :term:`gPTP`. Reading it yields a :term:`Snapshot` carrying a :term:`Vehicle Time status`. It is exposed to applications through the :term:`Vehicle Clock`. @@ -108,7 +108,7 @@ all provided by the single :term:`Local Clock` interface. Local Clock The :term:`Clock` interface that provides the local, non-synchronized time bases — - :term:`Steady Clock`, :term:`System Clock` and :term:`High-Resolution Clock`. They need no + :term:`Steady Clock`, :term:`System Clock` and :term:`High-Resolution Steady Clock`. They need no initialization and are always available. Steady Clock @@ -123,7 +123,7 @@ all provided by the single :term:`Local Clock` interface. thus obtain the absolute time, but as QM data without the :term:`accuracy qualifier` and :term:`security qualifier`. - High-Resolution Clock + High-Resolution Steady Clock A monotonic, nanosecond-resolution local time base optimized for low-overhead timing. Used for tight timing loops and deadline checks. @@ -169,13 +169,13 @@ Synchronization Infrastructure ------------------------------ .. glossary:: - PTP protocol - Precision Time Protocol - a protocol (IEEE 802.1AS) used to synchronize clocks in a + PTP + Precision Time Protocol - a protocol (IEEE 1588) used to synchronize clocks in a network. gPTP Generalized Precision Time Protocol, the IEEE 802.1AS profile of the - :term:`PTP protocol` used for in-vehicle Ethernet time synchronization. + :term:`PTP` used for in-vehicle Ethernet time synchronization. Syntonization Alignment of clock *frequency* (rate) between nodes, as opposed to synchronization @@ -184,4 +184,4 @@ Synchronization Infrastructure Grand Master The external, network-wide time source (the PTP Grand Master) that the system - synchronizes to using the :term:`PTP protocol`. + synchronizes to using the :term:`gPTP`.