diff --git a/score/time_daemon/docs/index.rst b/score/time_daemon/docs/index.rst index 6d2f6e8f..3cf64713 100644 --- a/score/time_daemon/docs/index.rst +++ b/score/time_daemon/docs/index.rst @@ -15,9 +15,7 @@ .. _time_daemon: Time Daemon -##################### - -.. note:: Document header +########### .. document:: Time Daemon :id: doc__time_daemon @@ -28,52 +26,54 @@ Time Daemon :realizes: wp__cmpt_request :tags: time_daemon -.. note:: - Work in progress: structure, titles, and needs IDs only. Content and req/comp/feat traceability links to follow in later PRs. +.. comp:: Time Daemon + :id: comp__time_daemon + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :belongs_to: feat__time[version==1] + +Abstract +======== + +This component implements a time synchronization daemon that receives time data from time_slave via IPC, performs verification and qualification, and provides validated time information to applications. -.. code-block:: rst +Specification +============= - .. comp:: Time Daemon - :id: comp__time_daemon_template - :security: YES - :safety: ASIL_B - :status: invalid - :implements: logic_arc_int__feature_name__interface_name1 - :consists_of: comp__component_name_internal_1, comp__component_name_internal_2, comp__component_name_internal_3 - :belongs_to: feat__feature_name +The time_daemon component acts as a verification and publishing layer between the time_slave component and client applications. It receives gPTP time synchronization data from shared memory, validates it through multiple verification stages, and publishes qualified time data via IPC. -.. attention:: - The above directives must be updated according to your Component. +The component operates as a continuous loop with the following stages: - - Adjust ``status`` to be ``valid`` - - Adjust ``safety`` and ``tags`` according to your needs +1. **Data Reception**: Reads gPTP time synchronization data from shared memory written by time_slave +2. **Verification Pipeline**: Validates data through three checks: -Abstract -======== + * Synchronization status validation + * Timeout detection (no new time sync data within configured span of time) + * Time jump detection (received master timestamp deviates from its expected value by more than the configured threshold) -[A short (~200 word) description of the component.] +3. **Publishing**: Publishes verified time data with quality indicators to clients via VehicleTime IPC interface at a fixed interval +Key Behaviors +------------- -Specification -============= +**Startup Stabilization**: Synchronization state changes are not reported during a configurable span of time after initial synchronization to avoid spurious time jump detection. -[Describe the requirements, architecture of any component.] or +**Error Recovery**: Time jump and timeout conditions are non-fatal. The component continues publishing with appropriate status flags set. Time jump condition clears after configurable number of consecutive valid frames. +**Multi-Client Support**: Multiple client applications can concurrently read published time data. -How to Teach This -================= +**Platform Support**: Linux and QNX 8.0 SDP platforms supported for shared memory and IPC operations. -[How to teach users, new and experienced, how to apply the CR to their work.] +Assumptions of Use +------------------ -.. note:: - For a CR that adds new functionality or changes behaviour, it is helpful to include a section on how to teach users, new and experienced, how to apply the CR to their work. +The gPTP shared memory must be available and initialized before synchronized time data published by time_daemon is relied upon. Otherwise shared memory access failures or stale data may occur. Footnotes ========= -[A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.] - - Further Documentation of the component can be found in the following sections: Component Detail Information diff --git a/score/time_daemon/docs/requirements/chklst_req_inspection.rst b/score/time_daemon/docs/requirements/chklst_req_inspection.rst index c0211fd8..194e5981 100644 --- a/score/time_daemon/docs/requirements/chklst_req_inspection.rst +++ b/score/time_daemon/docs/requirements/chklst_req_inspection.rst @@ -16,9 +16,9 @@ .. document:: Time Daemon Requirements Inspection Checklist :id: doc__time_daemon_req_inspection :status: draft - :version: 2 + :version: 1 :safety: ASIL_B - :security: YES + :security: NO :realizes: wp__requirements_inspect :tags: time_daemon @@ -189,6 +189,3 @@ And also the following AoUs in "valid" state and with "inspected" tag set (for t :columns: id;status;tags :colwidths: 25,25,25 :sort: title - -.. attention:: - The above tables filtering must be updated according to your Component. diff --git a/score/time_daemon/docs/requirements/index.rst b/score/time_daemon/docs/requirements/index.rst index 400d1d03..8d5aa5ea 100644 --- a/score/time_daemon/docs/requirements/index.rst +++ b/score/time_daemon/docs/requirements/index.rst @@ -12,13 +12,275 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Requirements -############ +Time Daemon Component Requirements +################################## -.. note:: - Work in progress: page structure only, content to follow in later PRs. +.. document:: Time Daemon Requirements + :id: doc__time_daemon_requirements + :status: valid + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, time_daemon + +Functional Requirements +----------------------- + +Initialization and Lifecycle +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Component Initialization + :id: comp_req__time_daemon__startup + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + On startup the time_daemon component shall determine its configuration, initialize the configured time synchronization data receiver, time data verification pipeline (synchronization validation, timeout detection, time jump detection), and IPC publisher. If initialization of any of those units fails, the time_daemon shall retry to initialize the respective unit. Overall initialization shall fail if not completed within 20 seconds and shall end the time_slave process. + +.. comp_req:: Component Shutdown + :id: comp_req__time_daemon__shutdown + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_ctrl_flow[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall stop the publishing loop and close plus release any IPC resources (e.g. shared memory mappings) when a stop signal is received. + +Data Reception and Validation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Time Synchronization Data Reception + :id: comp_req__time_daemon__gptp_shm_reception + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall receive time synchronization data from time_slave component using the ts_client component for IPC abstraction. + +Verification Pipeline +^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Synchronization Status Validation + :id: comp_req__time_daemon__sync_validation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall validate synchronization status based on received time synchronization data. + +.. comp_req:: Synchronization State Stabilization + :id: comp_req__time_daemon__sync_debounce + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall not report time jumps during the configured time span (default: 5 seconds) after initial synchronization to avoid spuriously detected time jumps during startup. + +.. comp_req:: Time Jump Detection + :id: comp_req__time_daemon__time_jump_detection + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall detect time jumps when the master clock timestamp of a gPTP time sync data update differs from the expected value by more than the configured time span (default: 500 microseconds). Both forward and backward time jumps shall be detected. + +.. comp_req:: Timeout Detection + :id: comp_req__time_daemon__timeout_detection + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall detect timeout condition when no new time synchronization data is received within the configured time span (default: 3.3 seconds). + +Data Publishing +^^^^^^^^^^^^^^^ + +.. comp_req:: Time Data Publishing + :id: comp_req__time_daemon__time_data_publishing + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_time_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall publish the verified time synchronization data to the time component linked as a library into client applications. + +.. comp_req:: Published Time Data Content + :id: comp_req__time_daemon__published_data_content + :reqtype: Interface + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1], + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall include in published time data: the timestamp of the master clock, the corresponding timestamp of the local reference clock, the rate deviation between those two clocks, synchronization status, time jump status, and timeout status. + + Also it shall include condensed raw data of the last received Sync/FollowUp pair and the last finished Pdelay measurement. + +.. comp_req:: Time Point Qualifier Production + :id: comp_req__time_daemon__time_point_qualifier + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_time_pt_qual[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall determine the time point qualifier (quality indicator) of the published time data from the outcome of the synchronization, time jump and timeout verification checks. + +.. comp_req:: Publish Interval + :id: comp_req__time_daemon__publish_interval + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_ctrl_flow[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall publish time data to client applications at a fixed configurable interval (default: 250 milliseconds). + +.. comp_req:: Non-Blocking Access Path + :id: comp_req__time_daemon__non_blocking + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_ctrl_flow[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall use a non-blocking, lock-free shared memory access path for receiving time synchronization data and providing published time data to client applications. + +.. comp_req:: Multi-Client Support + :id: comp_req__time_daemon__multi_client + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_ctrl_flow[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall support concurrent non-blocking read access from multiple client applications to the published time data. + +Error Handling and Recovery +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Error Reporting + :id: comp_req__time_daemon__error_reporting + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync_log[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall log messages via the score::mw::log interface when initialization fails (error level), shared memory access fails (error level), verification stage failures occur (warning level), or time synchronization data reception fails (error level). + +.. comp_req:: Time Jump Error Reaction + :id: comp_req__time_daemon__time_jump_reaction + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall continue publishing time data with time jump status set when time jump is detected. + +.. comp_req:: Time Jump Recovery + :id: comp_req__time_daemon__time_jump_recovery + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_acc_qual_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall clear time jump condition after receiving 2 consecutive valid gPTP frames without time jump. + +.. comp_req:: Timeout Error Reaction + :id: comp_req__time_daemon__timeout_reaction + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall continue publishing time data with timeout status set when the timeout detection period elapses without receiving new gPTP data. + +Platform Abstraction +^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Platform Support + :id: comp_req__time_daemon__platform_support + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall support POSIX and QNX 8.0 SDPplatforms for shared memory access and IPC communication. + +Assumption of Use Requirements +------------------------------- + +.. aou_req:: gPTP Shared Memory Availability + :id: aou_req__time_daemon__gptp_shm_available + :reqtype: Process + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + + The user shall ensure gPTP shared memory is initialized and the time_slave component is running before starting time_daemon. Starting time_daemon without an initialized shared memory region will cause shared memory access failures or reading of stale/uninitialized time data during startup. + + +.. needextend:: "c.this_doc()" + :+tags: time_daemon .. toctree:: + :maxdepth: 1 - requirements chklst_req_inspection diff --git a/score/time_daemon/docs/requirements/requirements.rst b/score/time_daemon/docs/requirements/requirements.rst deleted file mode 100644 index 9020f9b0..00000000 --- a/score/time_daemon/docs/requirements/requirements.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component Time Daemon Requirements -################################### - -.. document:: Time Daemon Requirements - :id: doc__time_daemon_requirements - :status: draft - :version: 1 - :safety: ASIL_B - :security: YES - :realizes: wp__requirements_comp[version==1] - -.. note:: - Work in progress: structure, titles, and needs IDs only. Content and req/comp/feat traceability links to follow in later PRs. - -.. attention:: - The above directive must be updated according to your Component. - - - Adjust ``status`` to be ``valid`` - - Adjust ``safety``, ``security`` and ``tags`` according to your needs - - -=================================================================== - -Functional Requirements ------------------------ - -.. code-block:: rst - - .. comp_req:: Some Title - :id: comp_req__time_daemon__some_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :derived_from: feat_req__example_feature__example_req - :status: invalid - :version: 1 - :satisfied_by: comp__time_daemon - - The Component shall do xyz to another component to bring it to this condition at this time - - Note: (optional, not to be verified) - -.. attention:: - The above directive must be updated according to your component requirements. - - - Replace the example content by the real content for your first requirement - - Set ``derived_from`` with links to Feature requirements - - Set ``satisfied_by`` with a link to the right Component id - - Set ``safety`` and ``security`` to the right value - - Set the status to valid and start the review/merge process - - Add other needed requirements for your component - -Assumption of Use Requirements ------------------------------- - -.. aou_req:: Next Title - :id: aou_req__time_daemon__next_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: invalid - :version: 1 - - The Component User shall do xyz to use the component safely/securely - -Environmental Requirements --------------------------- - -.. aou_req:: Another Title - :id: aou_req__time_daemon__another - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: invalid - :version: 1 - :tags: environment - - The Component shall only be used in a xyz environment to ensure its proper functioning. - -Hints ------ - -.. attention:: - The above directives must be updated according to your feature requirements. - - - Replace the example content by the real content for your first requirement (according to :need:`gd_guidl__req_engineering`) - - Set ``safety`` and ``security`` to the right value (ASIL B/QM; YES/NO) - - Set ``reqtype`` with a link to the right value () - - Add other needed requirements for your feature - - Set ``status`` to ``valid`` and start the review/merge process - -.. needextend:: "c.this_doc()" - :+tags: time_daemon