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..6505b151d35 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,239 @@ 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 domains `. 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 domains `), 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. :term:`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 + +.. note:: + + This document defines the feature-level logical (static) architecture. The feature's dynamic + architecture and the component-level detailed architecture are described in the ``time`` module + (see the `time module repository `_). + +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_res_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..d583ab49e07 --- /dev/null +++ b/docs/features/time/glossary.rst @@ -0,0 +1,192 @@ +.. + # ******************************************************************************* + # 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`` :term:`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 (:term:`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. :term:`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 — the path delay from the absolute-time + master to the client — is compensated using a :term:`Delay Tag`. + + Absolute Clock + The :term:`Clock` interface that provides :term:`Absolute Time`. + + UTC + Coordinated Universal Time — the primary global civil time standard. It is the reference + time scale for :term:`Absolute Time` and for the :term:`System Clock` wall-clock 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 05b9646b12d..4d2b2a47da2 100644 --- a/docs/features/time/index.rst +++ b/docs/features/time/index.rst @@ -27,27 +27,14 @@ Time :realizes: wp__feat_request[version==1] -.. toctree:: - :maxdepth: 1 - :glob: - :titlesonly: - :hidden: - - architecture/index - requirements/index - requirements/aou_req - -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 :term:`UTC` source). The feature owns +the synchronization of the synchronized time bases and supports test-time substitution of all +clock interfaces. Motivation ========== @@ -74,7 +61,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. @@ -97,7 +84,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 -------------------------------------------------- @@ -112,6 +103,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 .. ========== @@ -120,88 +114,62 @@ 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 - -* 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. - -**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 core time model concepts — :term:`Clock`, :term:`TimePoint`, :term:`TimeSpan` and their +operations and properties — are formally defined in the :doc:`Terms and Definitions `. -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. +Architectural design +-------------------- -.. 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 ============= +The Time feature separates the ASIL of the *clock interface* (a safety element that must not +interfere with the ASIL_B components calling it) from the *integrity of the time value* it +delivers: -.. License Impact -.. ============== - +* **Clock interfaces — ASIL_B.** The :term:`Vehicle Clock`, :term:`Local Clock` and + :term:`Absolute Clock` are developed as ASIL_B elements: access is free from interference for + the consuming components. For the Local Clock and Absolute Clock this relies on the platform/OS + assumptions of use (see :need:`aou_req__platform__os_safety_functions`). +* **Time-value integrity — per domain.** -How to Teach This -================== + * :term:`Vehicle Time` — **ASIL_B**. Its :term:`Snapshot` carries a :term:`Time point qualifier` + distinguishing ASIL-B data from QM data; the ASIL-B value integrity is achieved only if + :need:`aou_req__feature_time__veh_time_integrity` is fulfilled. + * :term:`Local Clock` bases (steady, monotonic, high-resolution) — **ASIL_B**. They expose no + runtime qualifier; the ASIL-B value integrity is achieved only if + :need:`aou_req__platform__os_safety_functions` is fulfilled. + * :term:`Absolute Time` — **QM** value. It is externally sourced and cannot be raised above QM; + its :term:`accuracy qualifier` and :term:`security qualifier` are QM runtime signals. -.. Rejected Ideas -.. ============== - - -.. Open Issues -.. =========== +Terms and Definitions +===================== +.. toctree:: + :maxdepth: 1 -Glossary -======== + glossary diff --git a/docs/features/time/requirements/aou_req.rst b/docs/features/time/requirements/aou_req.rst index 7357df7d0f8..2f5bf60aa95 100644 --- a/docs/features/time/requirements/aou_req.rst +++ b/docs/features/time/requirements/aou_req.rst @@ -1,6 +1,6 @@ - +.. # ******************************************************************************* - # Copyright (c) 2026 Contributors to the Eclipse Foundation + # Copyright (c) 2025 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -23,18 +23,39 @@ Time Feature Assumption of Use Requirements =========================================== -.. aou_req:: Vehicle time end-to-end integrity - :id: aou_req__feature__veh_time_e2e_integrity +.. aou_req:: Vehicle time value integrity + :id: aou_req__feature_time__veh_time_integrity :reqtype: Non-Functional :security: NO :safety: ASIL_B :status: valid :version: 1 - If the system using the S-CORE Time feature has the safety goal to achive end-to-end integrity of - the vehicle time information, the involved external components (like grand master clock, any - intermediate master clock, and time-aware bridges/switches) must support respective measures for - the integrity protection. + The integrity of the vehicle time *value* is not guaranteed by :term:`score::time` alone. If the + system using :term:`score::time` has the safety goal to treat the vehicle time as ASIL-B data, the + system integrator shall establish end-to-end integrity by suitable measures, e.g.: + + * integrity protection along the time-distribution chain (grand master, intermediate masters, + time-aware bridges/switches), and/or + * a receiver-side qualification/monitoring mechanism that evaluates the qualifiers provided by + :term:`score::time` (see :need:`feat_req__time__vehicle_time_time_pt_qual`, + :need:`feat_req__time__vehicle_time_acc_qual_api`) and reacts per the project safety concept. + + Note 1: :term:`score::time` provides the qualifier/detection hooks; the concrete integrity + mechanism, its redundancy, the safety reaction and the end-to-end safety argument are + project-specific and outside the scope of the :term:`score::time` SEooC. + + Note 2: If this assumption is not fulfilled, the vehicle time value integrity falls back to QM + and must be marked accordingly in the project documentation. + +.. aou_req:: Vehicle time integrity result reflected in qualifier + :id: aou_req__feature_time__veh_time_qual_reflect + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 - Note: If this assumption is violated, the data integrity level of the vehicle time information will fall - back to QM and must be marked accordingly in the respective project documentation. + Where the integrity check for the vehicle time is realized as a :term:`score::time` extension, the + system integrator shall ensure its result is reflected in the :term:`time point qualifier` + (see :need:`feat_req__time__vehicle_time_time_pt_qual`). diff --git a/docs/features/time/requirements/index.rst b/docs/features/time/requirements/index.rst index 0868d00d5a9..b303a02f51c 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 :term:`score::time` feature shall synchronize the local clock with an external :term:`Grand Master` using the :term:`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 :term:`score::time` feature shall synchronize the local time base with the :term:`Grand Master` within a defined + precision, based on the system setup (see :need:`feat_req__time__vehicle_time_sync`). Note: @@ -57,31 +57,29 @@ Time Synchronization :reqtype: Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__vehicle_time_api[version==1] + :derived_from: stkh_req__time__vehicle_time_sync[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to access the synchronized vehicle time. - Usage of this API shall be free from interferences for the consuming components. + The :term:`score::time` feature shall provide an API to access the synchronized :term:`Vehicle Time`. -Note (providing tracebility as long as safety analysis is not available): - :need:`feat_req__time__vehicle_time_time_api` requires backing by :need:`aou_req__feature__veh_time_e2e_integrity` - to guarantee end-to-end data integrity. + Note: the ASIL-B level applies to the interface/module; the delivered value integrity is reflected by the + :term:`time point qualifier` (see :need:`feat_req__time__vehicle_time_time_pt_qual`). .. feat_req:: Vehicle Time base accuracy qualifier :id: feat_req__time__vehicle_time_acc_qual_api :reqtype: Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__vehicle_time_api[version==1] + :derived_from: stkh_req__time__vehicle_time_sync[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read the accuracy qualifier of the local synchronized time base. + The :term:`score::time` feature shall provide an API to read the :term:`accuracy qualifier` of the local synchronized time base. Note: qualifier shall reflect the accuracy of the local time base, e.g. @@ -94,35 +92,39 @@ Note (providing tracebility as long as safety analysis is not available): :reqtype: Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__vehicle_time_api[version==1] + :derived_from: stkh_req__time__vehicle_time_sync[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read the time point qualifier of the local synchronized time base. + The :term:`score::time` feature shall provide an API to read the :term:`time point qualifier` of the local synchronized time base. - Note: qualifier shall reflect if the time point could be treated as ASIL-B data or QM data + Note: the qualifier tells the consumer whether the time point may currently be treated as ASIL-B data or + only as QM data. This verdict comes from the integrity check established for the vehicle time + (see :need:`aou_req__feature_time__veh_time_integrity`); if no such check exists, the qualifier is QM. + If that integrity check is integrated into :term:`score::time` as an extension, the extension delivers its + verdict through this qualifier (see :need:`aou_req__feature_time__veh_time_qual_reflect`). .. feat_req:: Vehicle Time control flow :id: feat_req__time__vehicle_time_ctrl_flow :reqtype: Non-Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__vehicle_time_api[version==1] + :derived_from: stkh_req__time__vehicle_time_sync[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an access its data via specified APIs in a fast and very efficient manner, + The :term:`score::time` feature shall provide an access its data via specified APIs in a fast and very efficient manner, avoiding, if possible, kernel calls, resource manager involvement and so on. 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. @@ -137,11 +139,27 @@ Note (providing tracebility as long as safety analysis is not available): :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide a mechanism to log the internal state of the synchronization process, + The :term:`score::time` feature shall provide a mechanism to log the internal state of the synchronization process, to be able to debug and diagnose the synchronization process. *Use case:* Debugging and diagnostics of the time synchronization process. +.. feat_req:: HW clock synchronization to Vehicle Time + :id: feat_req__time__hw_clock_sync + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: stkh_req__time__vehicle_time_sync[version==1] + :satisfied_by: feat__time[version==1] + :status: valid + :version: 1 + :valid_from: v1.0.0 + + The :term:`score::time` feature shall synchronize the local HW clock (e.g. NIC PHC) to :term:`Vehicle Time`, + enabling hardware timestamping of ingress and egress network frames. + + Note: the ownership of the HW clock discipline (score::time vs. the network/gPTP stack) is a system design choice. + Time Synchronization to absolute external sources ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -156,34 +174,35 @@ Time Synchronization to absolute external sources :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall support synchronization with external time sources, such as UTC time from GPS. + The :term:`score::time` feature shall support synchronization with external time sources, such as :term:`UTC` time from GPS. .. feat_req:: Absolute Time base API :id: feat_req__time__abs_base_api :reqtype: Functional :security: YES - :safety: QM - :derived_from: stkh_req__time__absolute_time_api[version==1] + :safety: ASIL_B + :derived_from: stkh_req__time__absolute_time_sync[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read the absolute time base, synchronized to external time sources. - Usage of this API shall be free from interferences for the consuming components. + The :term:`score::time` feature shall provide an API to read the :term:`Absolute Time` base, synchronized to external time sources. + + Note: the ASIL-B level applies to the interface/module; the delivered absolute time value integrity remains QM. .. feat_req:: Absolute Time base accuracy qualifier :id: feat_req__time__abs_acc_qual :reqtype: Functional :security: YES :safety: QM - :derived_from: stkh_req__time__absolute_time_api[version==1] + :derived_from: stkh_req__time__absolute_time_sync[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read accuracy qualifier of the absolute time base, synchronized to external time sources. + The :term:`score::time` feature shall provide an API to read :term:`accuracy qualifier` of the :term:`Absolute Time` base, synchronized to external time sources. Note: the inaccuracy could be indicated in the following manner @@ -205,13 +224,13 @@ Time Synchronization to absolute external sources :reqtype: Functional :security: YES :safety: QM - :derived_from: stkh_req__time__absolute_time_api[version==1] + :derived_from: stkh_req__time__absolute_time_sync[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read security qualifier of the absolute time base, synchronized to external time sources. + The :term:`score::time` feature shall provide an API to read :term:`security qualifier` of the :term:`Absolute Time` base, synchronized to external time sources. Note: the security level might be indicated in the following steps @@ -231,7 +250,7 @@ Time Synchronization to absolute external sources :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide a mechanism to log the internal state of the absolute time synchronization process, + The :term:`score::time` feature shall provide a mechanism to log the internal state of the :term:`Absolute Time` synchronization process, to be able to debug and diagnose the synchronization process. Local Clock @@ -242,14 +261,13 @@ Local Clock :reqtype: Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__high_res_clock_api[version==1] + :derived_from: stkh_req__time__high_res_clock_api[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read the high resolution clock in nanoseconds resolution. - Usage of this API shall be free from interferences for the consuming components. + The :term:`score::time` feature shall provide an API to read the :term:`High-Resolution Steady Clock` in nanoseconds resolution. Note: to which clock the high resolution clock is mapped, depends on the system design. @@ -260,14 +278,13 @@ Local Clock :reqtype: Functional :security: NO :safety: ASIL_B - :derived_from: stkh_req__time__monotonic_clock_api[version==1] + :derived_from: stkh_req__time__monotonic_clock_api[version==1], stkh_req__dependability__automotive_safety[version==1] :satisfied_by: feat__time[version==1] :status: valid :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide an API to read monotonic, not adjustable clock value. - Usage of this API shall be free from interferences for the consuming components. + The :term:`score::time` feature shall provide an API to read :term:`monotonic`, not adjustable clock value. Testability ^^^^^^^^^^^^ @@ -283,5 +300,5 @@ Testability :version: 1 :valid_from: v1.0.0 - The **score::time feature** shall provide support for mocking its public interfaces, enabling unit, + The :term:`score::time` feature shall provide support for mocking its public interfaces, enabling unit, component and integration testing of applications. diff --git a/docs/requirements/platform_assumptions/index.rst b/docs/requirements/platform_assumptions/index.rst index 172010507b9..8805571e99c 100644 --- a/docs/requirements/platform_assumptions/index.rst +++ b/docs/requirements/platform_assumptions/index.rst @@ -435,19 +435,3 @@ In this section assumptions are described which need to be fulfilled by the syst - C library - math library - high precision time source (HW synchronized) - -.. aou_req:: Vehicle time end-to-end integrity - :id: aou_req__platform__veh_time_e2e_integrity - :reqtype: Non-Functional - :security: NO - :safety: ASIL_B - :status: valid - :version: 1 - :tags: environment - - If the system using the SW-platform has the safety goal to achive end-to-end integrity of the vehicle time - information, the involved external components (like the grand master clock, any intermediate master clock, - and time-aware bridges/switches) must support respective measures for the integrity protection. - - Note: If this assumption is violated, the data integrity level of the vehicle time information will fall - back to QM and must be marked accordingly in the respective project documentation. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index d68a414b505..d9109e99827 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -862,110 +862,58 @@ Communication Time ---- -.. stkh_req:: Vehicle Time base Synchronization +.. stkh_req:: Vehicle Time base :id: stkh_req__time__vehicle_time_sync :reqtype: Functional :security: NO :safety: QM - :rationale: Enables the system to compare in-vehicle events chronologically. + :rationale: Enables applications to correlate their data with a vehicle-internal time reference and to compare in-vehicle events chronologically. :status: valid :version: 1 :valid_from: v1.0.0 - The SW-platform shall provide a framework to synchronize its local vehicle clock representation to a Time Master within the vehicle. + The SW-platform shall provide to applications a common vehicle time base synchronized to a Time Master within the vehicle. -.. stkh_req:: Vehicle Time base API - :id: stkh_req__time__vehicle_time_api - :reqtype: Functional - :security: NO - :safety: ASIL_B - :rationale: Enables an application to correlate its data with a vehicle-internal time reference for event timestamp and chronological events comparison. - :status: valid - :version: 1 - :valid_from: v1.0.0 - - The SW-platform shall provide access to the synchronized vehicle time. - Access shall be free from interferences for the consuming components. - -Note (providing tracebility as long as safety analysis is not available): - :need:`stkh_req__time__vehicle_time_api` requires backing by :need:`aou_req__platform__veh_time_e2e_integrity` - to guarantee end-to-end data integrity. - -.. stkh_req:: Synchronize the HW clock with Vehicle Time - :id: stkh_req__time__hw_clock_sync - :reqtype: Functional - :security: NO - :safety: QM - :rationale: Enables the system to compare events from different ECUs chronologically, using the same time base for timestamping ingress and egress frames. - :status: valid - :version: 1 - :valid_from: v2.0.0 - - The SW-platform shall synchronize the local HW clock to vehicle time. - -.. stkh_req:: Time Synchronization with external sources +.. stkh_req:: Absolute Time base :id: stkh_req__time__absolute_time_sync :reqtype: Functional :security: YES :safety: QM - :rationale: Enables the system to validate a certificate or token with temporal validity conditions, to add a UTC-timestamp to a data set, etc. + :rationale: Enables applications to correlate their data with an absolute vehicle-external time reference (e.g. to validate a certificate with temporal validity or to add a UTC timestamp). :status: valid :version: 1 :valid_from: v1.0.0 - The SW-platform shall provide a framework to synchronize its local absolute clock representation to an external-to-vehicle absolute time base (e.g. UTC). - -.. stkh_req:: Absolute time base API - :id: stkh_req__time__absolute_time_api - :reqtype: Functional - :security: YES - :safety: QM - :rationale: Enables an application to correlate its data with an absolute vehicle-external time reference for event timestamping and chronological events comparison. - :status: valid - :version: 1 - :valid_from: v1.0.0 - - The SW-platform shall provide access to the absolute time base, synchronized with external time sources. - Access shall be free from interferences for the consuming components. + The SW-platform shall provide to applications an absolute time base synchronized to an external-to-vehicle absolute time source (e.g. UTC). .. stkh_req:: Local High Resolution Clock API :id: stkh_req__time__high_res_clock_api :reqtype: Functional :security: NO - :safety: ASIL_B + :safety: QM :rationale: Enables an application to get the current system time, which is essential for time-sensitive operations and event scheduling, via common, mockable and standardized API. :status: valid :version: 1 :valid_from: v1.0.0 The SW-platform shall provide access to the current high resolution clock from the system time provider in nanoseconds. - Access shall be free from interferences for the consuming components. Note: to which clock the high resolution clock is mapped, depends on the system design. -Note (allowing tracebility as long as safety analysis is not available): - :need:`stkh_req__time__high_res_clock_api` requires backing by :need:`aou_req__platform__os_safety_functions` - to guarantee FFI and clock data integrity on OS and HW level. - .. stkh_req:: Local Monotonic Clock API :id: stkh_req__time__monotonic_clock_api :reqtype: Functional :security: NO - :safety: ASIL_B + :safety: QM :rationale: Enables an application to get the current system time, which is essential for time-sensitive operations and event scheduling, via common, mockable and standardized API. :status: valid :version: 1 :valid_from: v1.0.0 The SW-platform shall provide access to the current monotonic clock from the system time provider. - Access shall be free from interferences for the consuming components. Note: to which clock the monotonic clock is mapped, depends on the system design. -Note (allowing tracebility as long as safety analysis is not available): - :need:`stkh_req__time__monotonic_clock_api` requires backing by :need:`aou_req__platform__os_safety_functions` - to guarantee FFI and clock data integrity on OS and HW level. - AI SW-platform --------------