diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..a3ca3cea --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,25 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* +# Based on the conf.py generated by the docs() macro; extends it with +# required_in_id so that feat_arc_sta__time__* / feat_arc_dyn__time__* IDs +# are accepted under docs/features/architecture/ (feature part "time" is +# declared as valid here rather than enforced via the folder path). + +project = "S-CORE Time" +project_url = "https://eclipse-score.github.io/time" +version = "0.0.0" + +extensions = ["score_sphinx_bundle"] + +# Allow IDs containing "time" to live outside a "time/" subdirectory. +required_in_id = ["time"] diff --git a/docs/features/architecture/_assets/absolute_time_read_flow.puml b/docs/features/architecture/_assets/absolute_time_read_flow.puml new file mode 100644 index 00000000..3ea4daf6 --- /dev/null +++ b/docs/features/architecture/_assets/absolute_time_read_flow.puml @@ -0,0 +1,62 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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 "score::time::AbsoluteClock" as ac #LightGreen + end box + participant "TimeDaemon\n(absolute time receiver)" as recv #LightGreen + 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/architecture/_assets/clock_testability.puml b/docs/features/architecture/_assets/clock_testability.puml new file mode 100644 index 00000000..20d7ab64 --- /dev/null +++ b/docs/features/architecture/_assets/clock_testability.puml @@ -0,0 +1,47 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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\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/architecture/_assets/local_time_read_flow.puml b/docs/features/architecture/_assets/local_time_read_flow.puml new file mode 100644 index 00000000..7f04fb0e --- /dev/null +++ b/docs/features/architecture/_assets/local_time_read_flow.puml @@ -0,0 +1,59 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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 "score::time::SteadyClock\n/ HighResSteadyClock\n/ SystemClock" 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 Steady Clock == +app -> lc : now() +lc -> os : ClockCycles +os --> lc : TimePoint +lc --> app : Snapshot (TimePoint) + +@enduml diff --git a/docs/features/architecture/_assets/static_arch.puml b/docs/features/architecture/_assets/static_arch.puml new file mode 100644 index 00000000..7e62abc5 --- /dev/null +++ b/docs/features/architecture/_assets/static_arch.puml @@ -0,0 +1,62 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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 "Application" as user #LightSalmon + + package "score::time feature" #e6ffe6 { + package "score::time\n(clock library)" #d4f7d4 { + component "score::time::VehicleClock" as veh_clock_api #LightGreen + component "score::time::Clock\n(Steady|HiRes|System)" as local_clock_api #LightGreen + component "score::time::AbsoluteClock" as abs_clock_api #LightGreen + } + component "ts_client\n(TimeSlave<->TimeDaemon shm IPC)" as time_slave_client #LightGreen + component "TimeDaemon\n" as time_daemon #LightGreen + component "TimeSlave\n(gPTP slave endpoint)" as time_slave #LightGreen + } + + component "score::someip" as score_someip #LightBlue + component "OS / local clock" as os #LightGrey +} + +cloud "Vehicle network\n(gPTP / IEEE 802.1AS)" as veh_net #LightCoral +cloud "Absolute time source\n(e.g. GPS / UTC)" as abs_master #LightCoral + +user --> veh_clock_api : read vehicle time +user --> local_clock_api : read local time +user --> abs_clock_api : read absolute time + +veh_clock_api --> time_daemon : IPC +abs_clock_api --> time_daemon : IPC +time_daemon --> time_slave_client : uses +time_slave_client <-- time_slave : PTP data +time_slave ..> veh_net : Synchronization via gPTP + +time_daemon <-- score_someip : absolute time +score_someip ..> abs_master : obtains absolute time + +local_clock_api ..> os : reads OS clock + +@enduml diff --git a/docs/features/architecture/_assets/vehicle_time_notification.puml b/docs/features/architecture/_assets/vehicle_time_notification.puml new file mode 100644 index 00000000..3c31c333 --- /dev/null +++ b/docs/features/architecture/_assets/vehicle_time_notification.puml @@ -0,0 +1,72 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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 "score::time::VehicleClock" as vc #LightGreen + end box + participant "TimeDaemon\n(validation & distribution)" as td #LightGreen + participant "ts_client\n(gPTP shm IPC)" as tsc #LightGreen + participant "TimeSlave\n(gPTP endpoint)" as ts #LightGreen +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 <--> ts : gPTP synchronization + ts -> tsc : publish PTP data (shared memory) + tsc --> td : receive PTP data + td -> td : validate, derive Vehicle Time status + td -->> vc : notify event + vc -->> app : invoke handler(event) +end + +note over app, td + 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/architecture/_assets/vehicle_time_read_flow.puml b/docs/features/architecture/_assets/vehicle_time_read_flow.puml new file mode 100644 index 00000000..9205cf8b --- /dev/null +++ b/docs/features/architecture/_assets/vehicle_time_read_flow.puml @@ -0,0 +1,58 @@ +' ******************************************************************************* +' 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 +' ******************************************************************************* + +@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 "score::time::VehicleClock" as vc #LightGreen + end box + participant "TimeDaemon\n(validation & distribution)" as td #LightGreen + participant "ts_client\n(gPTP shm IPC)" as tsc #LightGreen + participant "TimeSlave\n(gPTP endpoint)" as ts #LightGreen +end box +participant "Grand Master" as host #LightCoral + +== Initialization == +app -> vc : init() +vc --> app : ready + +== Synchronization (background) == +loop periodically + host <--> ts : gPTP synchronization + ts -> tsc : publish PTP data (shared memory) + tsc --> td : receive PTP data + td -> td : validate, derive Vehicle Time status,\ntimestamp on local monotonic clock + td -->> vc : distribute latest snapshot\n(time, local timestamp, status, metadata) +end + +== Reading the time (on demand) == +app -> vc : now() +vc -> vc : use latest snapshot;\ninterpolate on current local monotonic clock +vc --> app : Snapshot\n(vehicle TimePoint + Vehicle Time status) + +@enduml diff --git a/docs/features/architecture/index.rst b/docs/features/architecture/index.rst new file mode 100644 index 00000000..36dccc69 --- /dev/null +++ b/docs/features/architecture/index.rst @@ -0,0 +1,177 @@ +.. + # ******************************************************************************* + # 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 Feature Architecture +========================= + +.. document:: Time Feature Architecture + :id: doc__score_time_feat_architecture + :status: valid + :version: 1 + :safety: ASIL_B + :security: YES + :realizes: wp__feature_arch[version==1] + +This page defines the static and dynamic architecture of the :need:`feat__time` feature +(:term:`score::time`). The feature overview, logical interfaces, and requirements are +described in the `platform Time feature documentation +`_. + +Static Architecture +------------------- + +The feature-wide static view shows the Time feature, the three clock interfaces +it exposes, and the SW components that implement them: + +* **score::time** (clock library) — ``Clock`` API exposing + :term:`Vehicle Clock`, :term:`Local Clock`, and :term:`Absolute Clock` +* **TimeDaemon** — time validation, aggregation and distribution process +* **TimeSlave** — gPTP slave endpoint that receives network time +* **ts_client** — SW component implementing the gPTP shared-memory IPC channel + between ``TimeSlave`` (publisher) and ``TimeDaemon`` (reader) + +.. 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 + +Dynamic Architecture +-------------------- + +Vehicle Time +************ + +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 the :term:`Vehicle Time status` changes or new time-sync relevant +data from the :term:`Time slave` 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:`gPTP`), 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 primary +use case is diagnostics — reacting to a status change or a PTP data update in a diagnostic manner. +The :term:`Vehicle Time status` can also be read from ``now``, and subscription additionally +delivers it when it changes. + +.. 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 +********** + +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. + +.. rubric:: Reading the time + +.. feat_arc_dyn:: Local Time Read + :id: feat_arc_dyn__time__local + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__monotonic_clock_api[version==1], feat_req__time__high_prec_clock_api[version==1] + :belongs_to: feat__time[version==1] + + .. uml:: _assets/local_time_read_flow.puml + :scale: 50 + :align: center + +Absolute 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`. + +.. rubric:: Reading the time + +.. feat_arc_dyn:: Absolute Time Read + :id: feat_arc_dyn__time__absolute + :security: YES + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__abs_base_api[version==1], feat_req__time__abs_sync[version==1] + :belongs_to: feat__time[version==1] + + .. 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`). + +.. feat_arc_dyn:: Clock Mocking + :id: feat_arc_dyn__time__mocking + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :fulfils: feat_req__time__mocking_apis[version==1] + :belongs_to: feat__time[version==1] + + .. uml:: _assets/clock_testability.puml + :scale: 50 + :align: center diff --git a/docs/features/index.rst b/docs/features/index.rst index 79e11d7b..58e14d53 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -19,4 +19,5 @@ Features :maxdepth: 2 :caption: Features: + architecture/index test_cases diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 00000000..9952d6e4 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,194 @@ +.. + # ******************************************************************************* + # 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 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 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:`gPTP`. + 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 Steady 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 Steady 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 + 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` 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. + + Grand Master + The external, network-wide time source (the PTP Grand Master) that the system + synchronizes to using the :term:`gPTP`. + + 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:`gPTP`, and for producing the synchronized time together with its + synchronization metadata (synchronization status, time difference to the + external source, last synchronization time and the corresponding local :term:`TimePoint`). diff --git a/docs/index.rst b/docs/index.rst index d099c763..a927e7db 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,10 +12,10 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -time_daemon Documentation -========================= +S-CORE Time +=========== -This documentation describes the **time_daemon** and the **score::time** module. +This documentation covers the **score::time** feature and module. .. contents:: Table of Contents :depth: 2 @@ -24,19 +24,17 @@ This documentation describes the **time_daemon** and the **score::time** module. Overview -------- -**time_daemon** is a non-AUTOSAR adaptive process designed to provide synchronized vehicle time to client applications. -It supports multiple time bases including **in-vehicle synchronized time** (PTP - Precision Time Protocol) and -**external synchronized time** (absolute time base). The daemon retrieves time information from the respective time sources, -verifies and validates the timepoints, and distributes this time information across multiple clients through efficient IPC mechanisms. +**score::time** provides applications with a uniform API for reading time across +several distinct clock domains: vehicle-synchronized time (PTP), local monotonic +time, and absolute time. The feature architecture is described in +:doc:`features/architecture/index`. -The main responsibilities of time_daemon include: +The module consists of the following components: -- **Providing current Vehicle time** to different applications -- **Setting synchronization qualifiers** (e.g., Synchronized, Timeout, etc.) -- **Providing diagnostic information** for system monitoring -- **Supporting additional verification mechanisms** such as QualifiedVehicleTime (QVT) for safety-critical applications - -For a detailed concept and architectural design, please refer to the :doc:`time_daemon documentation `. +- **score::time** — client-facing ``Clock`` library +- **TimeDaemon** — time validation, aggregation and distribution process +- **TimeSlave** — gPTP slave endpoint process +- **ts_client** — gPTP shared-memory IPC between TimeSlave and TimeDaemon .. toctree:: :maxdepth: 2 @@ -44,6 +42,7 @@ For a detailed concept and architectural design, please refer to the :doc:`time_ features/index module/index + glossary Project Layout @@ -56,7 +55,7 @@ This module follows the Eclipse SCORE component structure: - `score/time/`: Client-facing time base libraries - `score/ts_client/`: Time synchronization client library - `examples/`: Usage examples -- `docs/features/`: Feature-level documentation +- `docs/features/architecture/`: Time Feature Architecture - `.github/workflows/`: CI/CD pipelines Quick Start