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/index.rst b/docs/features/time/architecture/index.rst index 638b983ea9f..54f945e2fe0 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,236 @@ 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:`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. +* **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>`. + +Feature Overview +---------------- + .. feat:: Time :id: feat__time :security: YES :safety: ASIL_B :status: valid :version: 1 + +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. + +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_ctrl_flow[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. + +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 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. + * - :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. + +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`). diff --git a/docs/features/time/glossary.rst b/docs/features/time/glossary.rst new file mode 100644 index 00000000000..f3b4c7b121a --- /dev/null +++ b/docs/features/time/glossary.rst @@ -0,0 +1,187 @@ +.. + # ******************************************************************************* + # 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`. 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.