diff --git a/score/time_daemon/docs/index.rst b/score/time_daemon/docs/index.rst index 6d2f6e8f..83d81418 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,48 @@ 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. - -.. code-block:: rst - - .. 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 - -.. attention:: - The above directives must be updated according to your Component. - - - Adjust ``status`` to be ``valid`` - - Adjust ``safety`` and ``tags`` according to your needs +.. comp:: Time Daemon + :id: comp__time_daemon + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + :belongs_to: feat__time Abstract ======== -[A short (~200 word) description of the component.] - +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. Specification ============= -[Describe the requirements, architecture of any component.] or - - -How to Teach This -================= - -[How to teach users, new and experienced, how to apply the CR to their work.] - -.. 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 component requirements are: + +* :need:`comp_req__time_daemon__initialization` +* :need:`comp_req__time_daemon__shutdown` +* :need:`comp_req__time_daemon__gptp_shm_reception` +* :need:`comp_req__time_daemon__sync_validation` +* :need:`comp_req__time_daemon__sync_debounce` +* :need:`comp_req__time_daemon__time_jump_detection` +* :need:`comp_req__time_daemon__timeout_detection` +* :need:`comp_req__time_daemon__time_data_publishing` +* :need:`comp_req__time_daemon__published_data_content` +* :need:`comp_req__time_daemon__time_point_qualifier` +* :need:`comp_req__time_daemon__publish_interval` +* :need:`comp_req__time_daemon__periodic_fallback` +* :need:`comp_req__time_daemon__multi_client` +* :need:`comp_req__time_daemon__error_reporting` +* :need:`comp_req__time_daemon__time_jump_reaction` +* :need:`comp_req__time_daemon__time_jump_recovery` +* :need:`comp_req__time_daemon__timeout_reaction` +* :need:`comp_req__time_daemon__platform_linux` +* :need:`comp_req__time_daemon__platform_qnx` +* :need:`aou_req__time_daemon__gptp_shm_available` 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..bdb40c21 100644 --- a/score/time_daemon/docs/requirements/index.rst +++ b/score/time_daemon/docs/requirements/index.rst @@ -12,13 +12,285 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Requirements -############ +Component Time Daemon Requirements +################################## -.. note:: - Work in progress: page structure only, content to follow in later PRs. +.. document:: Time Daemon Requirements + :id: doc__time_daemon_requirements + :status: draft + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: time_daemon + +Functional Requirements +----------------------- + +Initialization and Lifecycle +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Component Initialization + :id: comp_req__time_daemon__initialization + :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 initialize the gPTP shared memory reader, time data verification (synchronization validation, time jump detection, timeout detection), and IPC publisher during initialization. Initialization shall fail if not completed within 20 seconds. + +.. 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, release shared memory mappings, and close IPC resources when deinitialized or 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 the gPTP shared memory region written by the time_slave component. + +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 synchronization state changes during the first 5 seconds after initial synchronization to avoid spurious time jump detection 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 consecutive gPTP frames differ by more than 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 frame is received within 3.3 seconds. + +Data Publishing +^^^^^^^^^^^^^^^ + +.. comp_req:: Time Data Publishing + :id: comp_req__time_daemon__time_data_publishing + :reqtype: Interface + :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 time data that has passed verification checks to client applications via the VehicleTime IPC interface. + +.. 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_time_api[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__time_daemon + + The time_daemon component shall include in published time data: time value, synchronization status, time jump status, and timeout status. + +.. 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 interval of maximum 250 milliseconds to provide consistent read latency for VehicleTime clients. + +.. comp_req:: Periodic Publishing Fallback + :id: comp_req__time_daemon__periodic_fallback + :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 republish the last valid time data at the publishing interval when no new upstream data has arrived. + +.. 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 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 new gPTP frames. + +Platform Abstraction +^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Linux Platform Support + :id: comp_req__time_daemon__platform_linux + :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 Linux platforms for shared memory access and IPC communication. + +.. comp_req:: QNX Platform Support + :id: comp_req__time_daemon__platform_qnx + :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 QNX 8.0 SDP platforms 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