From 16589fa02545e5fba6a61416cdf37b0ef02ef09a Mon Sep 17 00:00:00 2001 From: Ryan Steel Date: Mon, 31 Aug 2026 13:40:10 +0100 Subject: [PATCH] add ts_client comp reqs --- score/ts_client/docs/index.rst | 38 +-- score/ts_client/docs/manuals/.gitkeep | 0 .../requirements/chklst_req_inspection.rst | 3 - score/ts_client/docs/requirements/index.rst | 232 +++++++++++++++++- .../docs/requirements/requirements.rst | 111 --------- 5 files changed, 248 insertions(+), 136 deletions(-) delete mode 100644 score/ts_client/docs/manuals/.gitkeep delete mode 100644 score/ts_client/docs/requirements/requirements.rst diff --git a/score/ts_client/docs/index.rst b/score/ts_client/docs/index.rst index ce32b5b9..1cc2a810 100644 --- a/score/ts_client/docs/index.rst +++ b/score/ts_client/docs/index.rst @@ -21,13 +21,13 @@ Time Sync Client :id: doc__ts_client :status: draft :version: 1 - :safety: ASIL_B + :safety: QM :security: NO :realizes: wp__cmpt_request :tags: ts_client .. comp:: Time Sync Client - :id: comp__time_ts_client + :id: comp__ts_client :security: NO :safety: ASIL_B :status: valid @@ -37,29 +37,33 @@ Time Sync Client Abstract ======== -[A short (~200 word) description of the component.] - +This component provides IPC mechanisms for time synchronization data exchange between time daemons and client applications within an ECU. 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 provides shared memory-based IPC for distributing time synchronization data with thread-safe, low-latency access: + +* :need:`comp_req__ts_client__shared_memory_mgmt` +* :need:`comp_req__ts_client__shm_validation` +* :need:`comp_req__ts_client__publisher_creates` +* :need:`comp_req__ts_client__receiver_multi_reader` +* :need:`comp_req__ts_client__data_validity` +* :need:`comp_req__ts_client__seqlock_protocol` +* :need:`comp_req__ts_client__sync_status_data` +* :need:`comp_req__ts_client__sync_fup_data` +* :need:`comp_req__ts_client__pdelay_data` +* :need:`comp_req__ts_client__time_correlation_data` +* :need:`comp_req__ts_client__platform_linux` +* :need:`comp_req__ts_client__platform_qnx` +* :need:`comp_req__ts_client__error_reporting` +* :need:`comp_req__ts_client__cache_optimization` +* :need:`aou_req__ts_client__single_publisher` +* :need:`aou_req__ts_client__shm_permissions` 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/ts_client/docs/manuals/.gitkeep b/score/ts_client/docs/manuals/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/score/ts_client/docs/requirements/chklst_req_inspection.rst b/score/ts_client/docs/requirements/chklst_req_inspection.rst index 9a5d1ef2..c956e5cc 100644 --- a/score/ts_client/docs/requirements/chklst_req_inspection.rst +++ b/score/ts_client/docs/requirements/chklst_req_inspection.rst @@ -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/ts_client/docs/requirements/index.rst b/score/ts_client/docs/requirements/index.rst index 400d1d03..327d31cb 100644 --- a/score/ts_client/docs/requirements/index.rst +++ b/score/ts_client/docs/requirements/index.rst @@ -12,13 +12,235 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Requirements -############ +Component Time Sync Client Requirements +######################################## -.. note:: - Work in progress: page structure only, content to follow in later PRs. +.. document:: Time Sync Client Requirements + :id: doc__ts_client_requirements + :status: draft + :version: 1 + :safety: ASIL_B + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, ts_client + + +Functional Requirements +----------------------- + +Shared Memory Management +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Shared Memory Channel Management + :id: comp_req__ts_client__shared_memory_mgmt + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall provide operations to create, open, and close shared memory channels for gPTP data exchange between time daemon and time-aware applications. + +.. comp_req:: Shared Memory Region Validation + :id: comp_req__ts_client__shm_validation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall validate shared memory region integrity on Open operations and reject regions that fail validation. + +.. comp_req:: Publisher Creates Channels + :id: comp_req__ts_client__publisher_creates + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client Publisher shall create shared memory channels that Receivers subsequently open. + +.. comp_req:: Receiver Multi-Reader Semantics + :id: comp_req__ts_client__receiver_multi_reader + :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__ts_client + + The ts_client Receiver shall support multiple concurrent readers accessing shared memory channels in read-only mode. + +.. comp_req:: Data Validity Indication + :id: comp_req__ts_client__data_validity + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client Receiver shall indicate whether received data is valid or corrupted. + +Data Synchronization +^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Lock-Free Synchronization + :id: comp_req__ts_client__seqlock_protocol + :reqtype: Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall implement lock-free synchronization between writer and readers to prevent blocking and ensure readers can detect concurrent writes. + +Data Exchange Interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: gPTP Synchronization Status Exchange + :id: comp_req__ts_client__sync_status_data + :reqtype: Interface + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall exchange gPTP synchronization status information containing synchronized state, timeout condition, time discontinuity detection (future and past), and correctness indication. + +.. comp_req:: Sync/FollowUp Message Metadata Exchange + :id: comp_req__ts_client__sync_fup_data + :reqtype: Interface + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall exchange gPTP Sync and FollowUp message metadata containing precise origin timestamp, reference global timestamp, reference local timestamp, sync ingress timestamp, correction field, sequence identifier, path delay, port number, and clock identity. + +.. comp_req:: PDelay Message Metadata Exchange + :id: comp_req__ts_client__pdelay_data + :reqtype: Interface + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall exchange gPTP Peer Delay (PDelay) message metadata containing request origin timestamp, request receipt timestamp, response origin timestamp, response receipt timestamp, path delay measurement, request port number, response port number, and request clock identity. + +.. comp_req:: Time Correlation Data Exchange + :id: comp_req__ts_client__time_correlation_data + :reqtype: Interface + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_sync[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall exchange time correlation data containing synchronized PTP assumed time, local system time reference, and clock rate deviation. + +Platform Abstraction +^^^^^^^^^^^^^^^^^^^^ + +.. comp_req:: Linux Platform Support + :id: comp_req__ts_client__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__ts_client + + The ts_client component shall support Linux platforms for shared memory operations and inter-process communication. + +.. comp_req:: QNX Platform Support + :id: comp_req__ts_client__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__ts_client + + The ts_client component shall support QNX 8.0 SDP platforms for shared memory operations and inter-process communication. + +Error Handling +^^^^^^^^^^^^^^ + +.. comp_req:: Error Reporting + :id: comp_req__ts_client__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__ts_client + + The ts_client component shall log messages via the score::mw::log interface when shared memory operations fail (error level), validation errors occur (error level), or channel creation/opening fails (error level). + +Non-Functional Requirements +--------------------------- + +.. comp_req:: Cache-Optimized Memory Layout + :id: comp_req__ts_client__cache_optimization + :reqtype: Non-Functional + :security: NO + :safety: ASIL_B + :derived_from: feat_req__time__vehicle_time_ctrl_flow[version==1] + :status: valid + :version: 1 + :satisfied_by: comp__ts_client + + The ts_client component shall optimize shared memory layout to prevent cache contention between concurrent writer and reader processes. + +Assumption of Use Requirements +------------------------------ + +.. aou_req:: Single Publisher Process + :id: aou_req__ts_client__single_publisher + :reqtype: Process + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + + The ts_client user shall ensure that only one publisher process opens and writes to a shared memory segment to maintain data consistency. Multiple publishers writing to the same segment will cause data corruption and readers will receive invalid data. + +.. aou_req:: Shared Memory Permissions + :id: aou_req__ts_client__shm_permissions + :reqtype: Process + :security: NO + :safety: ASIL_B + :status: valid + :version: 1 + + The user shall configure shared memory permissions to allow publisher write access and reader read access. Incorrect permissions will cause channel creation or opening failures. + +.. needextend:: "c.this_doc()" + :+tags: ts_client .. toctree:: + :maxdepth: 1 - requirements chklst_req_inspection diff --git a/score/ts_client/docs/requirements/requirements.rst b/score/ts_client/docs/requirements/requirements.rst deleted file mode 100644 index 6049c292..00000000 --- a/score/ts_client/docs/requirements/requirements.rst +++ /dev/null @@ -1,111 +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 Sync Client Requirements -######################################## - -.. document:: Time Sync Client Requirements - :id: doc__ts_client_requirements - :status: draft - :version: 1 - :safety: ASIL_B - :security: NO - :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__ts_client__some_title - :reqtype: Functional - :security: NO - :safety: ASIL_B - :derived_from: feat_req__time__example_req - :status: invalid - :version: 1 - :satisfied_by: comp__time_ts_client - - 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 ------------------------------- - -.. code-block:: rst - - .. aou_req:: Next Title - :id: aou_req__ts_client__next_title - :reqtype: Process - :security: NO - :safety: ASIL_B - :status: invalid - :version: 1 - - The Component User shall do xyz to use the component safely/securely - -Environmental Requirements --------------------------- - -.. code-block:: rst - - .. aou_req:: Another Title - :id: aou_req__ts_client__another - :reqtype: Process - :security: NO - :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: ts_client