From 664b4eba6c4465a8378416eb4dff20d7becf0a6e Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Tue, 5 Aug 2025 16:44:10 +0200 Subject: [PATCH 1/5] feature time: Add stakeholder requirements --- .../features/time/docs/requirements/index.rst | 24 +++++++++++++++---- docs/requirements/stakeholder/index.rst | 22 +++++++++++++++++ 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/features/time/docs/requirements/index.rst b/docs/features/time/docs/requirements/index.rst index 0c3bb66c43..cf33ab2575 100644 --- a/docs/features/time/docs/requirements/index.rst +++ b/docs/features/time/docs/requirements/index.rst @@ -15,12 +15,15 @@ Requirements ############ +Time Synchronization +^^^^^^^^^^^^^^^^^^^^ + .. feat_req:: Time client PTP sync :id: feat_req__time__trec_external_sync_ptp :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__synchronization :status: valid The **time client**, as part of score::time feature, shall synchronize the local clock with an external **time host** using the PTP protocol (IEEE 802.1AS). @@ -44,7 +47,7 @@ Requirements :status: valid The score::time shall validate the current synchronized time, which was received from the **time host** and reflect the validation results in the time point status accordingly. - + Validation of the current synchronized time includes: * checking the time point for loss of synchronization * checking the time point for monotonicity @@ -94,8 +97,8 @@ Requirements *Use case:* Debugging and diagnostics of the time synchronization process. -External Time Synchronization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Time Synchronization to external sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. feat_req:: score::time external synchronization :id: feat_req__time__external_sync :reqtype: Functional @@ -164,3 +167,16 @@ Monotonic Clock :status: valid The score::time feature shall provide a mechanism to access (read only) to monotonic, not adjustable clock value, which is mapped from the known OS or HW clock. + +Testability +^^^^^^^^^^^^ + +.. feat_req:: score::time fake APIs implementation + :id: feat_req__time__apis_faking + :reqtype: Functional + :security: NO + :safety: QM + :satisfies: stkh_req__dev_experience__fake_public_apis + :status: valid + + The score::time feature shall provide support for mocking (faking) its public interfaces, enabling unit, component and integration testing of applications. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index de63a11d64..d1c1226e33 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -557,6 +557,18 @@ Communication * Diagnostic trouble codes * Diagnostic jobs +Time Synchronization +-------------------- + +.. stkh_req:: Time Synchronization + :id: stkh_req__time__synchronization + :reqtype: Functional + :security: NO + :safety: QM + :rationale: Enables the system to synchronize its internal clock with external time sources, ensuring the data aging across distributed ECUs. + :status: valid + + The software platform shall provide time synchronization framework to synchronize its clock with external time sources. Diagnostics and Fault Management -------------------------------- @@ -796,6 +808,16 @@ Developer experience The software platform shall provide a method and interface to enable debugging of the software on target and in vehicle. +.. stkh_req:: Fake implementation for application testing + :id: stkh_req__dev_experience__fake_public_apis + :reqtype: Functional + :security: NO + :safety: QM + :rationale: tbd + :status: valid + + The software platform shall provide support for mocking and faking its public interfaces, + enabling unit, component and integration testing of applications. .. stkh_req:: Programming languages for application development :id: stkh_req__dev_experience__prog_languages From 83961de7eacb2e5580d48b8524eb22fdc5c6c6fc Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Wed, 6 Aug 2025 17:11:11 +0200 Subject: [PATCH 2/5] feature:time: Update stakeholder requirements - Update requirements - Fix review comments --- .../architecture/_assets}/data_flow.puml | 0 .../features/time/docs/requirements/index.rst | 26 +++--- docs/features/time/index.rst | 2 +- docs/requirements/stakeholder/index.rst | 84 +++++++++++++++++-- 4 files changed, 89 insertions(+), 23 deletions(-) rename docs/features/time/{ => docs/architecture/_assets}/data_flow.puml (100%) diff --git a/docs/features/time/data_flow.puml b/docs/features/time/docs/architecture/_assets/data_flow.puml similarity index 100% rename from docs/features/time/data_flow.puml rename to docs/features/time/docs/architecture/_assets/data_flow.puml diff --git a/docs/features/time/docs/requirements/index.rst b/docs/features/time/docs/requirements/index.rst index cf33ab2575..2c1a08eae3 100644 --- a/docs/features/time/docs/requirements/index.rst +++ b/docs/features/time/docs/requirements/index.rst @@ -33,7 +33,7 @@ Time Synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__synchronization_validation :status: valid The score::time shall get the current synchronized time and its metadata from the **time host**. @@ -43,7 +43,7 @@ Time Synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__synchronization_validation :status: valid The score::time shall validate the current synchronized time, which was received from the **time host** and reflect the validation results in the time point status accordingly. @@ -102,9 +102,9 @@ Time Synchronization to external sources .. feat_req:: score::time external synchronization :id: feat_req__time__external_sync :reqtype: Functional - :security: NO + :security: YES :safety: QM - :satisfies: + :satisfies: stkh_req__time__external_timebase_sync :status: valid The score::time feature shall support synchronization with external time sources, such as GPS, based on SOME/IP messages. @@ -112,9 +112,9 @@ Time Synchronization to external sources .. feat_req:: score::time external synchronization status :id: feat_req__time__external_sync_status :reqtype: Functional - :security: NO + :security: YES :safety: QM - :satisfies: + :satisfies: stkh_req__time__external_timebase_security_qualifier, stkh_req__time__external_timebase_accuracy_qualifier :status: valid The score::time shall maintain the current synchronized time and its synchronization status, to be able to provide the latest values by clients request. @@ -122,9 +122,9 @@ Time Synchronization to external sources .. feat_req:: score::time external synchronization time :id: feat_req__time__external_sync_time :reqtype: Functional - :security: NO + :security: YES :safety: QM - :satisfies: + :satisfies: stkh_req__time__external_timebase_api :status: valid The score::time feature shall provide a mechanism to access (read only) the current synchronized time from external time sources and its synchronization status. @@ -134,7 +134,7 @@ Time Synchronization to external sources :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__dev_experience__debugging :status: valid The score::time feature shall provide a mechanism to log the internal state of the external time synchronization process, to be able to debug and diagnose the synchronization process. @@ -171,12 +171,12 @@ Monotonic Clock Testability ^^^^^^^^^^^^ -.. feat_req:: score::time fake APIs implementation - :id: feat_req__time__apis_faking +.. feat_req:: score::time mocking APIs implementation + :id: feat_req__time__apis_mocking :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__dev_experience__fake_public_apis + :satisfies: stkh_req__dev_experience__mockup_public_apis :status: valid - The score::time feature shall provide support for mocking (faking) its public interfaces, enabling unit, component and integration testing of applications. + The score::time feature shall provide support for mocking its public interfaces, enabling unit, component and integration testing of applications. diff --git a/docs/features/time/index.rst b/docs/features/time/index.rst index 00b3ee2e2c..abbd42762b 100644 --- a/docs/features/time/index.rst +++ b/docs/features/time/index.rst @@ -156,7 +156,7 @@ Data which is provided by the **time client** and includes the current synchroni The diagram bellow illustrates the data flow and interactions between the Time client, score::time middleware, and client applications within an ECU during PTP-based time synchronization. -.. uml:: data_flow.puml +.. uml:: architecture/_assets/data_flow.puml :caption: Data flow between time client, score::time, and clients Where diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index d1c1226e33..801ec8d9f9 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -557,18 +557,84 @@ Communication * Diagnostic trouble codes * Diagnostic jobs -Time Synchronization --------------------- +Time +---- + +Time synchronization to internal (in-vehicle) sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. stkh_req:: Time Synchronization +.. stkh_req:: In-Vehicle Time base Synchronization :id: stkh_req__time__synchronization :reqtype: Functional :security: NO :safety: QM - :rationale: Enables the system to synchronize its internal clock with external time sources, ensuring the data aging across distributed ECUs. + :rationale: Enables the system to compare events chronologically. + :status: valid + + The software platform shall provide a time synchronization framework to synchronize its clock with external to ECU time sources. + +.. stkh_req:: Validation of In-Vehicle Time base synchronization + :id: stkh_req__time__synchronization_validation + :reqtype: Functional + :security: NO + :safety: QM + :rationale: Enables the system to validate the time synchronization process, ensuring that the synchronized clock is accurate and reliable. + :status: valid + + The software platform shall provide a mechanism to validate the synchronized clock. + +.. stkh_req:: In-Vehicle Time base API + :id: stkh_req__time__in_time_base_api + :reqtype: Functional + :security: NO + :safety: QM + :rationale: Enables an application to correlate its data with a vehicle-internal time reference for event timestamping and chronological events comparison. + :status: valid + + The software platform shall provide the APIs to read the synchronized time from Local Time Slave. + +Time synchronization to external (out-of-vehicle) sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. stkh_req:: Time Synchronization with absolute external time sources + :id: stkh_req__time__external_timebase_sync + :reqtype: Functional + :security: YES + :safety: QM + :rationale: Enables the system to validate a certificate or token with temporal validity conditions, adding a UTC-timestamp to a data set. + :status: valid + + The software platform shall provide a framework for external time synchronization (UTC) to ensure accurate timekeeping across distributed systems. + +.. stkh_req:: Ext-Vehicle Time base API + :id: stkh_req__time__external_timebase_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 + + The software platform shall provide the APIs to read the absolute time bases, synchronized to external time sources. + +.. stkh_req:: Ext-Vehicle Time base accuracy qualifier + :id: stkh_req__time__external_timebase_accuracy_qualifier + :reqtype: Functional + :security: YES + :safety: QM + :rationale: Enables an application to make informed decisions based on the accuracy of the external time reference, ensuring that timestamped data is reliable and consistent. + :status: valid + + The software platform shall provide the APIs to read accuracy qualifier of the absolute time base, synchronized to external time sources. + +.. stkh_req:: Ext-Vehicle Time base security qualifier + :id: stkh_req__time__external_timebase_security_qualifier + :reqtype: Functional + :security: YES + :safety: QM + :rationale: Enables an application to make informed decisions based on the security of the external time reference, ensuring that timestamped data is reliable and consistent. :status: valid - The software platform shall provide time synchronization framework to synchronize its clock with external time sources. + The software platform shall provide the APIs to read security qualifier of the absolute time base, synchronized to external time sources. Diagnostics and Fault Management -------------------------------- @@ -808,15 +874,15 @@ Developer experience The software platform shall provide a method and interface to enable debugging of the software on target and in vehicle. -.. stkh_req:: Fake implementation for application testing - :id: stkh_req__dev_experience__fake_public_apis +.. stkh_req:: Mockup implementation for application testing + :id: stkh_req__dev_experience__mockup_public_apis :reqtype: Functional :security: NO :safety: QM - :rationale: tbd + :rationale: Enables unit, component and integration testing for both platform related and non-platform related applications. :status: valid - The software platform shall provide support for mocking and faking its public interfaces, + The software platform shall provide support for mocking its public interfaces, enabling unit, component and integration testing of applications. .. stkh_req:: Programming languages for application development From b520a28e3acc44d3617c658644de0a3ceed93649 Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Fri, 8 Aug 2025 15:37:03 +0200 Subject: [PATCH 3/5] feature:time: Update stakeholder requirements --- docs/requirements/stakeholder/index.rst | 74 +++++++++++++++++++++---- 1 file changed, 64 insertions(+), 10 deletions(-) diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 801ec8d9f9..5a9def0bb4 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -564,34 +564,88 @@ Time synchronization to internal (in-vehicle) sources ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. stkh_req:: In-Vehicle Time base Synchronization - :id: stkh_req__time__synchronization + :id: stkh_req__time__in_vehicle_synchronization :reqtype: Functional :security: NO :safety: QM :rationale: Enables the system to compare events chronologically. :status: valid - The software platform shall provide a time synchronization framework to synchronize its clock with external to ECU time sources. + The software platform shall provide a time synchronization framework to synchronize its clock + with external to ECU, but internal to vehicle time sources. -.. stkh_req:: Validation of In-Vehicle Time base synchronization - :id: stkh_req__time__synchronization_validation +.. stkh_req:: In-Vehicle Time base API + :id: stkh_req__time__in_vehicle_time_base_api :reqtype: Functional :security: NO :safety: QM - :rationale: Enables the system to validate the time synchronization process, ensuring that the synchronized clock is accurate and reliable. + :rationale: Enables an application to correlate its data with a vehicle-internal time reference + for event timestamping and chronological events comparison. :status: valid - The software platform shall provide a mechanism to validate the synchronized clock. + The software platform shall provide an API to read the synchronized time from Local Time Slave. -.. stkh_req:: In-Vehicle Time base API - :id: stkh_req__time__in_time_base_api +.. stkh_req:: In-Vehicle Time synchronization precision + :id: stkh_req__time__in_vehicle_time_sync_precision + :reqtype: Functional + :security: NO + :safety: QM + :rationale: Enables the system to compare high frequent events chronologically. + :status: valid + + The software platform shall synchronized the local time base with Global Time within a defined + precision, based on the system setup. + + Note: + + * for AVB nodes the maximum difference in the synchronized time between two AVB ports/ECUs while + both are in state SYNC, and could be 1 usec + * for non-AVB node the precision is released, comparing to AVB ones + +.. stkh_req:: In-Vehicle Time synchronization local clock adaptations + :id: stkh_req__time__in_vehicle_time_sync_local_clock_adaptations :reqtype: Functional :security: NO :safety: QM - :rationale: Enables an application to correlate its data with a vehicle-internal time reference for event timestamping and chronological events comparison. + :rationale: Enables the system to compare high frequent events chronologically. + :status: valid + + The software platform shall keep the threshold for all local clock adaptations (including + timestamping, converting and so on) which take part in time communication, based on the system setup. + Note: + + * for AVB nodes the threshold the threshold might be 100 nsec + * for non-AVB node the precision is released, comparing to AVB ones, and be up to 500 usec + +.. stkh_req:: in-Vehicle Time base accuracy qualifier + :id: stkh_req__time__in_vehicle_timebase_accuracy_qualifier + :reqtype: Functional + :security: YES + :safety: QM + :rationale: Enables an application to make informed decisions based on the accuracy of the local time reference, ensuring that timestamped data is reliable and consistent. + :status: valid + + The software platform shall provide an API to read accuracy qualifier of the local synchronized time base. + + Note: qualifier shall reflect the accuracy of the local time base, e.g. + + * if it is synchronized to an external time source or not, + * are there any time jumps, etc. + +.. stkh_req:: in-Vehicle Time base time point qualifier + :id: stkh_req__time__in_vehicle_timebase_time_point_qualifier + :reqtype: Functional + :security: YES + :safety: QM + :rationale: Enables an application to make informed decisions based on the accuracy of the local time reference, ensuring that timestamped data is reliable and consistent. :status: valid - The software platform shall provide the APIs to read the synchronized time from Local Time Slave. + The software platform shall provide the APIs to read the 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 + + TODO: do we need this qualifier? + Time synchronization to external (out-of-vehicle) sources ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 6cb5ddc3be24417534f362c968864d9c456ee11a Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Fri, 8 Aug 2025 17:00:47 +0200 Subject: [PATCH 4/5] feature:time: Update stakeholder requirements --- .../features/time/docs/requirements/index.rst | 10 ++--- docs/requirements/stakeholder/index.rst | 43 +++++++++++++++++-- 2 files changed, 44 insertions(+), 9 deletions(-) diff --git a/docs/features/time/docs/requirements/index.rst b/docs/features/time/docs/requirements/index.rst index 2c1a08eae3..8b7819f994 100644 --- a/docs/features/time/docs/requirements/index.rst +++ b/docs/features/time/docs/requirements/index.rst @@ -23,7 +23,7 @@ Time Synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__synchronization + :satisfies: stkh_req__time__in_vehicle_synchronization :status: valid The **time client**, as part of score::time feature, shall synchronize the local clock with an external **time host** using the PTP protocol (IEEE 802.1AS). @@ -33,7 +33,7 @@ Time Synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__synchronization_validation + :satisfies: stkh_req__time__in_vehicle_timebase_accuracy_qualifier :status: valid The score::time shall get the current synchronized time and its metadata from the **time host**. @@ -43,7 +43,7 @@ Time Synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__synchronization_validation + :satisfies: stkh_req__time__in_vehicle_timebase_accuracy_qualifier :status: valid The score::time shall validate the current synchronized time, which was received from the **time host** and reflect the validation results in the time point status accordingly. @@ -148,7 +148,7 @@ High precision Clock :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__external_high_precision_clock_api :status: valid The score::time feature shall provide a mechanism to access (read only) the high precision clock in nanoseconds precision. @@ -163,7 +163,7 @@ Monotonic Clock :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__external_monotonic_clock_api :status: valid The score::time feature shall provide a mechanism to access (read only) to monotonic, not adjustable clock value, which is mapped from the known OS or HW clock. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 5a9def0bb4..4371102a55 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -561,7 +561,7 @@ Time ---- Time synchronization to internal (in-vehicle) sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. stkh_req:: In-Vehicle Time base Synchronization :id: stkh_req__time__in_vehicle_synchronization @@ -648,7 +648,7 @@ Time synchronization to internal (in-vehicle) sources Time synchronization to external (out-of-vehicle) sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. stkh_req:: Time Synchronization with absolute external time sources :id: stkh_req__time__external_timebase_sync @@ -678,7 +678,13 @@ Time synchronization to external (out-of-vehicle) sources :rationale: Enables an application to make informed decisions based on the accuracy of the external time reference, ensuring that timestamped data is reliable and consistent. :status: valid - The software platform shall provide the APIs to read accuracy qualifier of the absolute time base, synchronized to external time sources. + The software platform shall provide the API to read accuracy qualifier of the absolute time base, synchronized to external time sources. + + Note: the inaccuracy could be indicated in the following manner + + * Inaccuracy higher than 24h + * Inaccuracy less than 24h + * Inaccuracy less than 1h and so on. .. stkh_req:: Ext-Vehicle Time base security qualifier :id: stkh_req__time__external_timebase_security_qualifier @@ -688,7 +694,36 @@ Time synchronization to external (out-of-vehicle) sources :rationale: Enables an application to make informed decisions based on the security of the external time reference, ensuring that timestamped data is reliable and consistent. :status: valid - The software platform shall provide the APIs to read security qualifier of the absolute time base, synchronized to external time sources. + The software platform shall provide the API to read security qualifier of the absolute time base, synchronized to external time sources. + +System time provider +^^^^^^^^^^^^^^^^^^^^ + +.. stkh_req:: High precision Clock API + :id: stkh_req__time__external_high_precision_clock_api + :reqtype: Functional + :security: YES + :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 + + The software platform shall provide the APIs to read the current high precision clock from the system time provider in nanoseconds. + + Note: to which clock the high precision clock is mapped, depends on the system design. + +.. stkh_req:: Monotonic Clock API + :id: stkh_req__time__external_monotonic_clock_api + :reqtype: Functional + :security: YES + :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 + + The software platform shall provide the APIs to read the current monotonic clock from the system time provider. + + Note: to which clock the monotonic clock is mapped, depends on the system design. Diagnostics and Fault Management -------------------------------- From 701b157edadcb8ccd8d7102bb8f19a60ab78919f Mon Sep 17 00:00:00 2001 From: Valery Lavrov Date: Mon, 11 Aug 2025 11:21:39 +0200 Subject: [PATCH 5/5] Fix review comments --- .../features/time/docs/requirements/index.rst | 187 ++++++++++++------ docs/requirements/stakeholder/index.rst | 142 +++---------- 2 files changed, 150 insertions(+), 179 deletions(-) diff --git a/docs/features/time/docs/requirements/index.rst b/docs/features/time/docs/requirements/index.rst index 8b7819f994..83423e4991 100644 --- a/docs/features/time/docs/requirements/index.rst +++ b/docs/features/time/docs/requirements/index.rst @@ -18,118 +18,179 @@ Requirements Time Synchronization ^^^^^^^^^^^^^^^^^^^^ -.. feat_req:: Time client PTP sync - :id: feat_req__time__trec_external_sync_ptp +.. feat_req:: Vehicle Time synchronization + :id: feat_req__time__vehicle_time__sync_with_ptp :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__in_vehicle_synchronization + :satisfies: stkh_req__time__vehicle_time__time_synchronization :status: valid - The **time client**, as part of score::time feature, shall synchronize the local clock with an external **time host** using the PTP protocol (IEEE 802.1AS). + The **score::time feature** shall synchronize the local clock with an external **Time Master** using the gPTP protocol (IEEE 802.1AS). -.. feat_req:: score::time metadata - :id: feat_req__time__time_metadata +.. feat_req:: Vehicle Time synchronization precision + :id: feat_req__time__vehicle_time__sync_precision :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__in_vehicle_timebase_accuracy_qualifier + :satisfies: stkh_req__time__vehicle_time__time_synchronization :status: valid - The score::time shall get the current synchronized time and its metadata from the **time host**. + The **score::time feature** shall synchronize the local time, see feat_req__time__vehicle_time__sync_with_ptp, base with **Time Master** within a defined + precision, based on the system setup. -.. feat_req:: score::time validation - :id: feat_req__time__time_validataion + Note: + + * the particular target precision depends on the system setup + * for AVB nodes the maximum difference in the synchronized time between two AVB ports/ECUs while + both are in state SYNC, and could be 1 usec + * for non-AVB node the precision is relaxed, and could be 200-500 usec + +.. feat_req:: Update the HW clock with Vehicle Time + :id: feat_req__time__vehicle_time__hw_synchronization :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__in_vehicle_timebase_accuracy_qualifier + :satisfies: stkh_req__time__vehicle_time__hw_clock_synchronization :status: valid - The score::time shall validate the current synchronized time, which was received from the **time host** and reflect the validation results in the time point status accordingly. + The **score::time feature** shall synchronize the local HW clock, which is being used for timestamping ingress and egress network frames, to vehicle time. - Validation of the current synchronized time includes: - * checking the time point for loss of synchronization - * checking the time point for monotonicity - * checking the time point for instability, like time jumps to the past or to the future - -.. feat_req:: score::time multiple applications - :id: feat_req__time__multiple_applications +.. feat_req:: Vehicle Time base API + :id: feat_req__time__vehicle_time__time_base_api :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__vehicle_time__time_base_api :status: valid - The score::time feature shall provide a mechanism to access (read only) to the synchronized time and its status across multiple applications within one ECU. + The **score::time feature** shall provide an API to access the synchronized vehicle time. -.. feat_req:: score::time efficiency - :id: feat_req__time__client_efficiency +.. feat_req:: Vehicle Time base accuracy qualifier + :id: feat_req__time__vehicle_time__accuracy_qualifier_api :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__time__vehicle_time__time_base_api :status: valid - The score::time feature shall provide an access to the synchronized time and its status, see feat_req__time__multiple_applications, in an efficient way without any additional overhead, like kernel calls, Resource manager involvement and so on. - *Use case:* frequent access to the current synchronized time and its metadata by multiple clients within one ECU. + The **score::time feature** shall provide an API to read the accuracy qualifier of the local synchronized time base. + + Note: qualifier shall reflect the accuracy of the local time base, e.g. + + * if it is synchronized to an external time source or not, + * are there any instabilities, like time jumps to the past or to the future + * does the time increase in a monotonic manner. +.. feat_req:: Vehicle Time base time point qualifier + :id: feat_req__time__vehicle_time__time_point_qualifier_api + :reqtype: Functional + :security: NO + :safety: ASIL-B + :satisfies: stkh_req__time__vehicle_time__time_base_api + :status: valid + + The **score::time feature** shall provide an API to read the time point qualifier of the local synchronized time base. -.. feat_req:: score::time synchronization process metadata - :id: feat_req__time__sync_process_metadata + Note: qualifier shall reflect if the time point could be treated as ASIL-B data or QM data + +.. feat_req:: Vehicle Time control flow + :id: feat_req__time__vehicle_time__control_flow :reqtype: Functional :security: NO :safety: QM :satisfies: :status: valid - The score::time feature shall provide a mechanism to access (read only) to the internal state of the synchronization process, see **Synchronization process metadata**, across multiple applications within one ECU. + The **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:: score::time synchronization stat logging - :id: feat_req__time__sync_stat_logging + * feat_req__time__vehicle_time__time_base_api + * feat_req__time__vehicle_time__accuracy_qualifier_api + * feat_req__time__vehicle_time__time_point_qualifier_api + + *Use case:* frequent access to the current synchronized time and its metadata by multiple clients within one ECU. + +.. feat_req:: Vehicle Time synchronization logging + :id: feat_req__time__vehicle_time__sync_logging :reqtype: Functional :security: NO :safety: QM - :satisfies: + :satisfies: stkh_req__dev_experience__debugging :status: valid - The score::time shall provide a mechanism to log the internal state of the synchronization process, see **Synchronization process metadata**, to be able to debug and diagnose the time synchronization process. - *Use case:* Debugging and diagnostics of the time synchronization process. + The **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. -Time Synchronization to external sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Time Synchronization to absolute external sources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. feat_req:: score::time external synchronization - :id: feat_req__time__external_sync + :id: feat_req__time__absolute_time_syncronization :reqtype: Functional :security: YES :safety: QM - :satisfies: stkh_req__time__external_timebase_sync + :satisfies: stkh_req__time__absolute_time__time_synchronization :status: valid - The score::time feature shall support synchronization with external time sources, such as GPS, based on SOME/IP messages. + The **score::time feature** shall support synchronization with external time sources, such as UTC time from GPS. -.. feat_req:: score::time external synchronization status - :id: feat_req__time__external_sync_status +.. feat_req:: Absolute Time base API + :id: stkh_req__time__external_timebase_api :reqtype: Functional :security: YES :safety: QM - :satisfies: stkh_req__time__external_timebase_security_qualifier, stkh_req__time__external_timebase_accuracy_qualifier + :satisfies: stkh_req__time__absolute_time__time_base_api :status: valid - The score::time shall maintain the current synchronized time and its synchronization status, to be able to provide the latest values by clients request. + The **score::time feature** shall provide an API to read the absolute time base, synchronized to external time sources. -.. feat_req:: score::time external synchronization time - :id: feat_req__time__external_sync_time +.. feat_req:: Absolute Time base accuracy qualifier + :id: stkh_req__time__external_timebase_accuracy_qualifier :reqtype: Functional :security: YES :safety: QM - :satisfies: stkh_req__time__external_timebase_api + :satisfies: stkh_req__time__absolute_time__time_base_api :status: valid - The score::time feature shall provide a mechanism to access (read only) the current synchronized time from external time sources and its synchronization status. + The **score::time feature** shall provide an API to read accuracy qualifier of the absolute time base, synchronized to external time sources. + + Note: the inaccuracy could be indicated in the following manner + + * Inaccuracy higher than 24h + * Inaccuracy less than 24h + * Inaccuracy less than 1h + * Inaccuracy less than 15min + * Inaccuracy less than 60s + * Inaccuracy less than 10s + * Inaccuracy less than 1s + * Inaccuracy less than 500ms + * Inaccuracy less than 100ms + * Inaccuracy less than 50ms + * Inaccuracy less than 10ms + * Inaccuracy not available + +.. feat_req:: Absolute Time base security qualifier + :id: stkh_req__time__external_timebase_security_qualifier + :reqtype: Functional + :security: YES + :safety: QM + :satisfies: stkh_req__time__absolute_time__time_base_api + :status: valid + + The **score::time feature** shall provide an API to read security qualifier of the absolute time base, synchronized to external time sources. + + Note: the security level might be indicated in the following steps + + * No time available + * Time not trustworthy + * Time trustworthy + * Time very trustworthy -.. feat_req:: score::time external synchronization status log +.. feat_req:: Absolute Time synchronization status log :id: feat_req__time__external_sync_status_log :reqtype: Functional :security: NO @@ -137,36 +198,35 @@ Time Synchronization to external sources :satisfies: stkh_req__dev_experience__debugging :status: valid - The score::time feature shall provide a mechanism to log the internal state of the external time synchronization process, to be able to debug and diagnose the synchronization process. + The **score::time feature** shall provide a mechanism to log the internal state of the absolute time synchronization process, + to be able to debug and diagnose the synchronization process. - -High precision Clock +Local Clock ^^^^^^^^^^^^^^^^^^^^ -.. feat_req:: score::time high precision clock - :id: feat_req__time__high_precision_clock +.. feat_req:: High precision clock API + :id: feat_req__time__local_time__high_precision_clock_api :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__external_high_precision_clock_api + :satisfies: stkh_req__time__local_time__high_precision_clock_api :status: valid - The score::time feature shall provide a mechanism to access (read only) the high precision clock in nanoseconds precision. - *Use case:* such clocks might be used for time-critical applications, such as audio/video streaming, event logging, and diagnostics. + The **score::time feature** shall provide an API to read the high precision clock in nanoseconds precision. + Note: to which clock the high precision clock is mapped, depends on the system design. -Monotonic Clock -^^^^^^^^^^^^^^^ + *Use case:* such clocks might be used for time-critical applications, such as audio/video streaming, event logging, and diagnostics. -.. feat_req:: score::time monotonic clock - :id: feat_req__time__monotonic_clock +.. feat_req:: Monotonic clock API + :id: feat_req__time__local_time__monotonic_clock_api :reqtype: Functional :security: NO :safety: QM - :satisfies: stkh_req__time__external_monotonic_clock_api + :satisfies: stkh_req__time__local_time__monotonic_clock_api :status: valid - The score::time feature shall provide a mechanism to access (read only) to monotonic, not adjustable clock value, which is mapped from the known OS or HW clock. + The **score::time feature** shall provide an API to read monotonic, not adjustable clock value. Testability ^^^^^^^^^^^^ @@ -179,4 +239,5 @@ Testability :satisfies: stkh_req__dev_experience__mockup_public_apis :status: valid - The score::time feature shall provide support for mocking its public interfaces, enabling unit, component and integration testing of applications. + The **score::time feature** shall provide support for mocking its public interfaces, enabling unit, + component and integration testing of applications. diff --git a/docs/requirements/stakeholder/index.rst b/docs/requirements/stakeholder/index.rst index 4371102a55..3ed644e391 100644 --- a/docs/requirements/stakeholder/index.rst +++ b/docs/requirements/stakeholder/index.rst @@ -560,11 +560,8 @@ Communication Time ---- -Time synchronization to internal (in-vehicle) sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. stkh_req:: In-Vehicle Time base Synchronization - :id: stkh_req__time__in_vehicle_synchronization +.. stkh_req:: Vehicle Time base Synchronization + :id: stkh_req__time__vehicle_time__time_synchronization :reqtype: Functional :security: NO :safety: QM @@ -572,156 +569,69 @@ Time synchronization to internal (in-vehicle) sources :status: valid The software platform shall provide a time synchronization framework to synchronize its clock - with external to ECU, but internal to vehicle time sources. - -.. stkh_req:: In-Vehicle Time base API - :id: stkh_req__time__in_vehicle_time_base_api - :reqtype: Functional - :security: NO - :safety: QM - :rationale: Enables an application to correlate its data with a vehicle-internal time reference - for event timestamping and chronological events comparison. - :status: valid + to Time Master within the vehicle. - The software platform shall provide an API to read the synchronized time from Local Time Slave. - -.. stkh_req:: In-Vehicle Time synchronization precision - :id: stkh_req__time__in_vehicle_time_sync_precision +.. stkh_req:: Vehicle Time base API + :id: stkh_req__time__vehicle_time__time_base_api :reqtype: Functional :security: NO :safety: QM - :rationale: Enables the system to compare high frequent events chronologically. + :rationale: Enables an application to correlate its data with a vehicle-internal time reference for event timestamp and chronological events comparison. :status: valid - The software platform shall synchronized the local time base with Global Time within a defined - precision, based on the system setup. - - Note: - - * for AVB nodes the maximum difference in the synchronized time between two AVB ports/ECUs while - both are in state SYNC, and could be 1 usec - * for non-AVB node the precision is released, comparing to AVB ones + The software platform shall provide access to synchronized vehicle time. -.. stkh_req:: In-Vehicle Time synchronization local clock adaptations - :id: stkh_req__time__in_vehicle_time_sync_local_clock_adaptations +.. stkh_req:: Synchrnize the HW clock with Vehicle Time + :id: stkh_req__time__vehicle_time__hw_clock_synchronization :reqtype: Functional :security: NO :safety: QM - :rationale: Enables the system to compare high frequent events chronologically. - :status: valid - - The software platform shall keep the threshold for all local clock adaptations (including - timestamping, converting and so on) which take part in time communication, based on the system setup. - Note: - - * for AVB nodes the threshold the threshold might be 100 nsec - * for non-AVB node the precision is released, comparing to AVB ones, and be up to 500 usec - -.. stkh_req:: in-Vehicle Time base accuracy qualifier - :id: stkh_req__time__in_vehicle_timebase_accuracy_qualifier - :reqtype: Functional - :security: YES - :safety: QM - :rationale: Enables an application to make informed decisions based on the accuracy of the local time reference, ensuring that timestamped data is reliable and consistent. - :status: valid - - The software platform shall provide an API to read accuracy qualifier of the local synchronized time base. - - Note: qualifier shall reflect the accuracy of the local time base, e.g. - - * if it is synchronized to an external time source or not, - * are there any time jumps, etc. - -.. stkh_req:: in-Vehicle Time base time point qualifier - :id: stkh_req__time__in_vehicle_timebase_time_point_qualifier - :reqtype: Functional - :security: YES - :safety: QM - :rationale: Enables an application to make informed decisions based on the accuracy of the local time reference, ensuring that timestamped data is reliable and consistent. + :rationale: Enables the system to compare events from different ECUs chronologically, using the same time base for timestamping ingress and egress frames. :status: valid - The software platform shall provide the APIs to read the 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 - - TODO: do we need this qualifier? - - -Time synchronization to external (out-of-vehicle) sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The software platform shall synchronize the local HW clock to vehicle time. .. stkh_req:: Time Synchronization with absolute external time sources - :id: stkh_req__time__external_timebase_sync + :id: stkh_req__time__absolute_time__time_synchronization :reqtype: Functional :security: YES :safety: QM :rationale: Enables the system to validate a certificate or token with temporal validity conditions, adding a UTC-timestamp to a data set. :status: valid - The software platform shall provide a framework for external time synchronization (UTC) to ensure accurate timekeeping across distributed systems. + The software platform shall provide a framework to synchronize the clock to external-to-vehicle absolute time base (UTC). -.. stkh_req:: Ext-Vehicle Time base API - :id: stkh_req__time__external_timebase_api +.. stkh_req:: Absolute time base API + :id: stkh_req__time__absolute_time__time_base_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 - The software platform shall provide the APIs to read the absolute time bases, synchronized to external time sources. - -.. stkh_req:: Ext-Vehicle Time base accuracy qualifier - :id: stkh_req__time__external_timebase_accuracy_qualifier - :reqtype: Functional - :security: YES - :safety: QM - :rationale: Enables an application to make informed decisions based on the accuracy of the external time reference, ensuring that timestamped data is reliable and consistent. - :status: valid - - The software platform shall provide the API to read accuracy qualifier of the absolute time base, synchronized to external time sources. - - Note: the inaccuracy could be indicated in the following manner - - * Inaccuracy higher than 24h - * Inaccuracy less than 24h - * Inaccuracy less than 1h and so on. + The software platform shall provide access to the absolute time base, synchronized with external time sources. -.. stkh_req:: Ext-Vehicle Time base security qualifier - :id: stkh_req__time__external_timebase_security_qualifier +.. stkh_req:: Local High precision Clock API + :id: stkh_req__time__local_time__high_precision_clock_api :reqtype: Functional - :security: YES - :safety: QM - :rationale: Enables an application to make informed decisions based on the security of the external time reference, ensuring that timestamped data is reliable and consistent. - :status: valid - - The software platform shall provide the API to read security qualifier of the absolute time base, synchronized to external time sources. - -System time provider -^^^^^^^^^^^^^^^^^^^^ - -.. stkh_req:: High precision Clock API - :id: stkh_req__time__external_high_precision_clock_api - :reqtype: Functional - :security: YES + :security: NO :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. + :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 - The software platform shall provide the APIs to read the current high precision clock from the system time provider in nanoseconds. + The software platform shall provide access to the current high precision clock from the system time provider in nanoseconds. Note: to which clock the high precision clock is mapped, depends on the system design. -.. stkh_req:: Monotonic Clock API - :id: stkh_req__time__external_monotonic_clock_api +.. stkh_req:: Local Monotonic Clock API + :id: stkh_req__time__local_time__monotonic_clock_api :reqtype: Functional - :security: YES + :security: NO :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. + :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 - The software platform shall provide the APIs to read the current monotonic clock from the system time provider. + The software platform shall provide access to the current monotonic clock from the system time provider. Note: to which clock the monotonic clock is mapped, depends on the system design.