From 64049ad027b7930c1cb9133d159d34f5c7e7c7d0 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Wed, 5 Aug 2026 12:51:00 +0100 Subject: [PATCH 1/2] AZB #101279: Add Bazel targets for unit/component tests and coverage --- .github/tools/coverage.sh | 84 +++++++++++ BUILD | 24 ++++ docs/features/time/component_requirements.rst | 62 ++++++++ docs/features/time/feature_requirements.rst | 44 ++++++ docs/features/time/index.rst | 7 + docs/index.rst | 1 + docs/quality_pack.rst | 132 ++++++++++++++++++ score/time/high_res_steady_time/src/BUILD | 1 + .../src/high_res_steady_clock_test.cpp | 6 + score/time/steady_time/src/BUILD | 1 + .../steady_time/src/steady_clock_test.cpp | 6 + score/time/system_time/src/BUILD | 1 + .../system_time/src/system_clock_test.cpp | 6 + score/time/vehicle_time/src/BUILD | 9 ++ score/time/vehicle_time/src/vehicle_clock.cpp | 4 + .../vehicle_time/src/vehicle_clock_test.cpp | 11 ++ 16 files changed, 399 insertions(+) create mode 100755 .github/tools/coverage.sh create mode 100644 docs/features/time/component_requirements.rst create mode 100644 docs/features/time/feature_requirements.rst create mode 100644 docs/quality_pack.rst diff --git a/.github/tools/coverage.sh b/.github/tools/coverage.sh new file mode 100755 index 00000000..508521ec --- /dev/null +++ b/.github/tools/coverage.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +# ******************************************************************************* +# 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 +# ******************************************************************************* +# +# Runs unit + component tests with code coverage and generates HTML + +# Cobertura XML reports. +# +# Prerequisites (install once): +# sudo apt-get install -y lcov +# pipx install lcov-cobertura +# +# Usage: +# .github/tools/coverage.sh [] [--config ] [--output-dir ] +# +# Options: +# Bazel target to collect coverage for (default: //score/...) +# --config Bazel config to use (default: time-x86_64-linux) +# --output-dir Directory for generated reports (default: cpp_coverage) + +set -euo pipefail + +OUTPUT_DIR="cpp_coverage" +BAZEL_CONFIG="time-x86_64-linux" +BAZEL_TARGET="${1:-//score/...}" + +# Consume the target argument if it was provided positionally +[[ $# -gt 0 && "$1" != --* ]] && shift + +while [[ $# -gt 0 ]]; do + case "$1" in + --config) + BAZEL_CONFIG="$2" + shift 2 + ;; + --output-dir) + OUTPUT_DIR="$2" + shift 2 + ;; + --target) + BAZEL_TARGET="$2" + shift 2 + ;; + *) + echo "Unknown option: $1" >&2 + exit 1 + ;; + esac +done + +echo "==> Running tests with coverage..." +bazel coverage --config="${BAZEL_CONFIG}" -- "${BAZEL_TARGET}" + +OUTPUT_PATH="$(bazel info output_path)" +EXEC_ROOT="$(bazel info execution_root)" +DAT_FILE="${OUTPUT_PATH}/_coverage/_coverage_report.dat" + +echo "==> Generating HTML report in '${OUTPUT_DIR}'..." +genhtml "${DAT_FILE}" \ + --output-directory="${OUTPUT_DIR}" \ + --show-details \ + --source-directory="${EXEC_ROOT}" \ + --legend \ + --function-coverage \ + --branch-coverage + +echo "==> Generating Cobertura XML report at '${OUTPUT_DIR}/coverage.xml'..." +lcov_cobertura "${DAT_FILE}" \ + --base-dir "${EXEC_ROOT}" \ + --output "${OUTPUT_DIR}/coverage.xml" + +echo "" +echo "Coverage reports written to '${OUTPUT_DIR}/'." +echo " HTML: ${OUTPUT_DIR}/index.html" +echo " Cobertura: ${OUTPUT_DIR}/coverage.xml" diff --git a/BUILD b/BUILD index cfb90305..e478fe87 100644 --- a/BUILD +++ b/BUILD @@ -24,6 +24,9 @@ docs( data = [ "@score_process//:needs_json", ], + scan_code = [ + "//score/time/vehicle_time/src:requirement_marked_sources", + ], source_dir = "docs", ) @@ -58,3 +61,24 @@ use_format_targets(languages = [ "yaml", "cpp", ]) + +# Aggregated component-test suite. Component tests exercise a clock facade +# (Clock) together with a mocked backend, i.e. more than one unit of code +# but without a real driver. Run with: +# bazel test --config=time-x86_64-linux //:component_tests +test_suite( + name = "component_tests", + tests = [ + "//score/time/high_res_steady_time/src:high_res_steady_clock_test", + "//score/time/steady_time/src:steady_clock_test", + "//score/time/system_time/src:system_clock_test", + "//score/time/vehicle_time/src:vehicle_clock_test", + ], + visibility = ["//visibility:public"], +) + +# Unit tests: every cc_test under //score/... is already tagged "unit", +# so `bazel test //score/...` is the canonical unit-tests invocation. +# No aggregate test_suite is needed here — a `test_suite` in a top-level +# BUILD file cannot use `//score/...` as an element of its `tests` +# attribute (package wildcards are rejected). diff --git a/docs/features/time/component_requirements.rst b/docs/features/time/component_requirements.rst new file mode 100644 index 00000000..c70c95ce --- /dev/null +++ b/docs/features/time/component_requirements.rst @@ -0,0 +1,62 @@ +Component Requirements +====================== + +.. comp_req:: VehicleClock returns snapshot with status + :id: comp_req__time__vehicle_clock_snapshot + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__time__snapshot_with_status + + ``VehicleClock::Now`` shall return a ``ClockSnapshot`` whose timepoint + and ``VehicleTimeStatus`` originate from the same backend read, so + downstream callers observe consistent time and status values. + +.. comp_req:: VehicleClock lifecycle operations + :id: comp_req__time__vehicle_clock_lifecycle + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__time__explicit_lifecycle + + ``VehicleClock`` shall provide ``Init``, ``IsAvailable`` and + ``WaitUntilAvailable`` operations that delegate to the backend and + report backend init failure and availability-wait timeouts to the + caller without blocking indefinitely. + +.. comp_req:: HighResSteadyClock always-ready snapshot + :id: comp_req__time__hirs_clock_snapshot + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__time__unified_clock_facade + + ``HighResSteadyClock::Now`` shall return a monotonic + ``ClockSnapshot`` without requiring prior initialization, and shall + not expose ``Init`` / ``IsAvailable`` / ``WaitUntilAvailable`` on the + facade (using them is a compile error). + +.. comp_req:: SteadyClock always-ready snapshot + :id: comp_req__time__steady_clock_snapshot + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__time__unified_clock_facade + + ``SteadyClock::Now`` shall return a snapshot backed by + ``std::chrono::steady_clock`` without requiring initialization. + +.. comp_req:: SystemClock always-ready snapshot + :id: comp_req__time__system_clock_snapshot + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__time__unified_clock_facade + + ``SystemClock::Now`` shall return a snapshot backed by + ``std::chrono::system_clock`` without requiring initialization. diff --git a/docs/features/time/feature_requirements.rst b/docs/features/time/feature_requirements.rst new file mode 100644 index 00000000..0816c2df --- /dev/null +++ b/docs/features/time/feature_requirements.rst @@ -0,0 +1,44 @@ +Feature Requirements +==================== + +.. feat_req:: Unified clock facade across time domains + :id: feat_req__time__unified_clock_facade + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :satisfies: + + ``score::time`` shall expose a single, type-safe entry point + (``Clock::GetInstance``) for reading time snapshots across the + supported clock domains (``VehicleTime``, ``HighResSteadyTime``, + ``std::chrono::steady_clock``, ``std::chrono::system_clock``), so + clients select a clock domain at compile time and cannot accidentally + mix domains at run time. + +.. feat_req:: Immutable snapshot with quality metadata + :id: feat_req__time__snapshot_with_status + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: + + Every ``Clock::Now`` call shall return a single immutable + ``ClockSnapshot`` value that bundles the timepoint with the domain's + status metadata, so callers can inspect synchronization quality + without a separate status call. + +.. feat_req:: Explicit lifecycle for backends that need it + :id: feat_req__time__explicit_lifecycle + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: + + Clock domains that depend on an external resource (currently + ``VehicleTime``) shall provide ``Init``, ``IsAvailable`` and + ``WaitUntilAvailable`` operations, and shall keep those operations + unavailable — at compile time — on clock domains that are always + ready. diff --git a/docs/features/time/index.rst b/docs/features/time/index.rst index 653b8a15..ba52b650 100644 --- a/docs/features/time/index.rst +++ b/docs/features/time/index.rst @@ -5,6 +5,13 @@ score::time — Unified Clock Interface :depth: 3 :local: +.. toctree:: + :maxdepth: 1 + :caption: Requirements + + feature_requirements + component_requirements + Overview -------- diff --git a/docs/index.rst b/docs/index.rst index e35c841d..bbc7099e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ For a detailed concept and architectural design, please refer to the :doc:`time_ :caption: Contents: features/index + quality_pack Project Layout -------------- diff --git a/docs/quality_pack.rst b/docs/quality_pack.rst new file mode 100644 index 00000000..80b0c9ba --- /dev/null +++ b/docs/quality_pack.rst @@ -0,0 +1,132 @@ +Quality Pack Targets +#################### + +The ``score_time`` module plugs into the Score docs-as-code +dashboards and quality gates as described in the upstream how-to: +https://eclipse-score.github.io/docs-as-code/main/how-to/dashboards_and_quality_gates.html. + +The Bazel targets below are the ones consumed by CI to produce +dashboard artefacts and to enforce traceability thresholds. + +Unit tests +========== + +- **Tag:** ``unit`` (already carried by every ``cc_test`` under + ``//score/...``). +- **Command:** ``bazel test --config=time-x86_64-linux //score/...`` — this + runs the full unit-test set because every ``cc_test`` in the tree + carries the ``unit`` tag. +- **Results:** JUnit XML and stdout log per test target under + ``bazel-testlogs///{test.log,test.xml}``. + +Component tests +=============== + +Component tests exercise a clock facade (``Clock``) together with a +mocked backend via ``ScopedClockOverride`` — the seam between the framework +layer and a domain-specific backend is covered end to end. + +- **Tag:** ``component``. +- **Aggregate target:** ``//:component_tests``. +- **Command:** ``bazel test --config=time-x86_64-linux //:component_tests``. +- **Included tests (existing tests reclassified, not new ones):** + + - ``//score/time/vehicle_time/src:vehicle_clock_test`` + - ``//score/time/high_res_steady_time/src:high_res_steady_clock_test`` + - ``//score/time/system_time/src:system_clock_test`` + - ``//score/time/steady_time/src:steady_clock_test`` + +- **Results:** JUnit XML and stdout log per test target under + ``bazel-testlogs///{test.log,test.xml}``. + +Code coverage +============= + +- **Command:** ``.github/tools/coverage.sh //score/... --config time-x86_64-linux``. +- **Underlying target:** ``bazel coverage`` with the ``coverage`` config + from ``.bazelrc``. +- **Results:** HTML report at ``cpp_coverage/index.html`` and Cobertura + XML at ``cpp_coverage/coverage.xml``. The raw ``lcov`` data lives under + ``$(bazel info output_path)/_coverage/_coverage_report.dat``. +- **CI:** ``.github/workflows/code-coverage.yml`` runs the reusable + ``eclipse-score/cicd-workflows`` coverage workflow with the same + target and config and enforces the configured minimum coverage + threshold. + +Requirements traceability (dashboards + gate) +============================================= + +Requirements live under ``docs/features/time/`` and use the Score +metamodel directives (``feat_req::`` / ``comp_req::``). Source-code +and test-code links are consumed by ``score_docs_as_code``: + +- **Source-code markers** — in the C++ implementation: + + .. code-block:: cpp + + // # req-Id: comp_req__time__vehicle_clock_snapshot + Snapshot Now() { ... } + + The leading ``// #`` is intentional; the linker regex looks for the + literal token ``# req-Id:`` and this is the neutral C++ form. The + files that carry markers are collected in + ``//score/time/vehicle_time/src:requirement_marked_sources`` (a + ``filegroup``) and passed to the root ``docs()`` macro via its + ``scan_code`` attribute. + +- **Test-code links** — use GoogleTest ``RecordProperty`` inside each + linked test body: + + .. code-block:: cpp + + TEST(VehicleClockTest, InitForwardsToBackend) + { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_lifecycle"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); + ::testing::Test::RecordProperty("Description", "…"); + ... + } + + The properties land in ``bazel-testlogs/.../test.xml`` and are read by + ``score_source_code_linker`` when docs are built. + +- **Bazel targets:** + + - ``//:needs_json`` — needs.json produced by Sphinx-Needs. + - ``//:metrics_json`` — traceability metrics extracted from needs.json. + - ``//:traceability_gate`` — enforces coverage thresholds. + +- **Local flow** (order matters — the gate reads ``bazel-testlogs`` for + test links): + + .. code-block:: bash + + bazel test --config=time-x86_64-linux //:component_tests //score/... + bazel run //:docs + bazel run //:traceability_gate -- \ + --metrics-json "$(pwd)/_build/metrics.json" \ + --need-type comp_req \ + --min-req-code 40 \ + --min-req-test 100 \ + --min-req-fully-linked 40 \ + --min-tests-linked 15 + + Current baseline (component requirements only): + + ========================= =============== + Metric Value + ========================= =============== + Requirements with source 2/5 (40.0%) + Requirements with test 5/5 (100.0%) + Requirements fully linked 2/5 (40.0%) + Tests linked to reqs 5/27 (18.5%) + ========================= =============== + +.. note:: + + The exact target names and result folders above are the current + convention for this repository. They can be renamed together with + ``@Zwinkau Andreas (ETAS-ECM ESY3)`` if a project-wide naming scheme + is agreed upon; the CI workflows in ``.github/workflows`` reference + these targets directly and would need to move in lockstep. diff --git a/score/time/high_res_steady_time/src/BUILD b/score/time/high_res_steady_time/src/BUILD index a7ed6a7b..fad0335a 100644 --- a/score/time/high_res_steady_time/src/BUILD +++ b/score/time/high_res_steady_time/src/BUILD @@ -75,6 +75,7 @@ cc_test( srcs = ["high_res_steady_clock_test.cpp"], features = COMPILER_WARNING_FEATURES, tags = [ + "component", "exclusive", "unit", ], diff --git a/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp b/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp index 61abfe2a..8582cecf 100644 --- a/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp +++ b/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp @@ -28,6 +28,12 @@ namespace time TEST(HighResSteadyClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__hirs_clock_snapshot"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); + ::testing::Test::RecordProperty("Description", + "HighResSteadyClock::Now returns a monotonic snapshot without requiring Init."); + auto mock = std::make_shared(); test_utils::ScopedClockOverride guard{mock}; diff --git a/score/time/steady_time/src/BUILD b/score/time/steady_time/src/BUILD index 9c1b0111..c1b51234 100644 --- a/score/time/steady_time/src/BUILD +++ b/score/time/steady_time/src/BUILD @@ -60,6 +60,7 @@ cc_test( srcs = ["steady_clock_test.cpp"], features = COMPILER_WARNING_FEATURES, tags = [ + "component", "exclusive", "unit", ], diff --git a/score/time/steady_time/src/steady_clock_test.cpp b/score/time/steady_time/src/steady_clock_test.cpp index d988896d..377cf08f 100644 --- a/score/time/steady_time/src/steady_clock_test.cpp +++ b/score/time/steady_time/src/steady_clock_test.cpp @@ -43,6 +43,12 @@ class SampleSteadyService TEST(SteadyClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__steady_clock_snapshot"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); + ::testing::Test::RecordProperty("Description", + "SteadyClock::Now returns a snapshot backed by std::chrono::steady_clock."); + auto mock = std::make_shared(); test_utils::ScopedClockOverride guard{mock}; diff --git a/score/time/system_time/src/BUILD b/score/time/system_time/src/BUILD index b0691b1c..913776c2 100644 --- a/score/time/system_time/src/BUILD +++ b/score/time/system_time/src/BUILD @@ -60,6 +60,7 @@ cc_test( srcs = ["system_clock_test.cpp"], features = COMPILER_WARNING_FEATURES, tags = [ + "component", "exclusive", "unit", ], diff --git a/score/time/system_time/src/system_clock_test.cpp b/score/time/system_time/src/system_clock_test.cpp index 0a9db024..385990da 100644 --- a/score/time/system_time/src/system_clock_test.cpp +++ b/score/time/system_time/src/system_clock_test.cpp @@ -43,6 +43,12 @@ class SampleSystemService TEST(SystemClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__system_clock_snapshot"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); + ::testing::Test::RecordProperty("Description", + "SystemClock::Now returns a snapshot backed by std::chrono::system_clock."); + auto mock = std::make_shared(); test_utils::ScopedClockOverride guard{mock}; diff --git a/score/time/vehicle_time/src/BUILD b/score/time/vehicle_time/src/BUILD index 49ae57ef..6d9e59ff 100644 --- a/score/time/vehicle_time/src/BUILD +++ b/score/time/vehicle_time/src/BUILD @@ -14,6 +14,14 @@ load("@score_baselibs//:bazel/unit_tests.bzl", "cc_unit_test_suites_for_host_and_qnx") load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES") +# Source files carrying `// # req-Id:` markers, exposed to the root +# docs() macro's scan_code attribute for source-code traceability. +filegroup( + name = "requirement_marked_sources", + srcs = ["vehicle_clock.cpp"], + visibility = ["//visibility:public"], +) + cc_library( name = "vehicle_clock", srcs = ["vehicle_clock.cpp"], @@ -65,6 +73,7 @@ cc_test( srcs = ["vehicle_clock_test.cpp"], features = COMPILER_WARNING_FEATURES, tags = [ + "component", "exclusive", "unit", ], diff --git a/score/time/vehicle_time/src/vehicle_clock.cpp b/score/time/vehicle_time/src/vehicle_clock.cpp index ee6af884..56fce856 100644 --- a/score/time/vehicle_time/src/vehicle_clock.cpp +++ b/score/time/vehicle_time/src/vehicle_clock.cpp @@ -41,21 +41,25 @@ std::ostringstream ClockStatus::PrintTo() const return oss; } +// # req-Id: comp_req__time__vehicle_clock_snapshot ClockTraits::Snapshot ClockTraits::CallNow(const Backend& impl) noexcept { return impl.Now(); } +// # req-Id: comp_req__time__vehicle_clock_lifecycle bool InitializationHook::CallInit(Backend& impl) noexcept { return impl.Init(); } +// # req-Id: comp_req__time__vehicle_clock_lifecycle bool AvailabilityHook::CallIsAvailable(const Backend& impl) noexcept { return impl.IsAvailable(); } +// # req-Id: comp_req__time__vehicle_clock_lifecycle bool AvailabilityHook::CallWaitUntilAvailable(const Backend& impl, const score::cpp::stop_token& token, std::chrono::steady_clock::time_point until) noexcept diff --git a/score/time/vehicle_time/src/vehicle_clock_test.cpp b/score/time/vehicle_time/src/vehicle_clock_test.cpp index cb5b72a5..ac242c42 100644 --- a/score/time/vehicle_time/src/vehicle_clock_test.cpp +++ b/score/time/vehicle_time/src/vehicle_clock_test.cpp @@ -52,6 +52,12 @@ class SampleVehicleService TEST(VehicleClockTest, NowReturnsSynchronizedStatusAndTimepoint) { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_snapshot"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "equivalence-classes"); + ::testing::Test::RecordProperty("Description", + "VehicleClock::Now returns a snapshot combining backend timepoint and status."); + auto mock = std::make_shared(); test_utils::ScopedClockOverride guard{mock}; @@ -97,6 +103,11 @@ TEST(VehicleClockTest, NowIsReliableReturnsFalseWhenTimeoutSet) TEST(VehicleClockTest, InitForwardsToBackend) { + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_lifecycle"); + ::testing::Test::RecordProperty("TestType", "requirements-based"); + ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); + ::testing::Test::RecordProperty("Description", "VehicleClock::Init delegates to the backend Init call."); + auto mock = std::make_shared(); test_utils::ScopedClockOverride guard{mock}; From 7444a7c9bd5aa569cd2606d2148b9dec9d1a0860 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Thu, 6 Aug 2026 15:21:47 +0100 Subject: [PATCH 2/2] Update to match module_template --- docs/features/time/component_requirements.rst | 62 ----- docs/features/time/index.rst | 1 - docs/quality_pack.rst | 14 +- .../architecture/chklst_arc_inspection.rst | 216 ++++++++++++++++++ .../architecture/component_architecture.rst | 72 ++++++ .../docs/architecture/index.rst | 23 ++ .../time/high_res_steady_time/docs/index.rst | 56 +++++ .../requirements/chklst_req_inspection.rst | 195 ++++++++++++++++ .../docs/requirements/index.rst | 21 ++ .../docs/requirements/requirements.rst | 46 ++++ .../src/high_res_steady_clock_test.cpp | 2 +- .../architecture/chklst_arc_inspection.rst | 216 ++++++++++++++++++ .../architecture/component_architecture.rst | 72 ++++++ .../steady_time/docs/architecture/index.rst | 23 ++ score/time/steady_time/docs/index.rst | 56 +++++ .../requirements/chklst_req_inspection.rst | 195 ++++++++++++++++ .../steady_time/docs/requirements/index.rst | 21 ++ .../docs/requirements/requirements.rst | 44 ++++ .../steady_time/src/steady_clock_test.cpp | 2 +- .../architecture/chklst_arc_inspection.rst | 216 ++++++++++++++++++ .../architecture/component_architecture.rst | 72 ++++++ .../system_time/docs/architecture/index.rst | 23 ++ score/time/system_time/docs/index.rst | 56 +++++ .../requirements/chklst_req_inspection.rst | 195 ++++++++++++++++ .../system_time/docs/requirements/index.rst | 21 ++ .../docs/requirements/requirements.rst | 44 ++++ .../system_time/src/system_clock_test.cpp | 2 +- .../architecture/chklst_arc_inspection.rst | 216 ++++++++++++++++++ .../architecture/component_architecture.rst | 72 ++++++ .../vehicle_time/docs/architecture/index.rst | 23 ++ score/time/vehicle_time/docs/index.rst | 62 +++++ .../requirements/chklst_req_inspection.rst | 195 ++++++++++++++++ .../vehicle_time/docs/requirements/index.rst | 21 ++ .../docs/requirements/requirements.rst | 60 +++++ score/time/vehicle_time/src/vehicle_clock.cpp | 8 +- .../vehicle_time/src/vehicle_clock_test.cpp | 4 +- 36 files changed, 2550 insertions(+), 77 deletions(-) delete mode 100644 docs/features/time/component_requirements.rst create mode 100644 score/time/high_res_steady_time/docs/architecture/chklst_arc_inspection.rst create mode 100644 score/time/high_res_steady_time/docs/architecture/component_architecture.rst create mode 100644 score/time/high_res_steady_time/docs/architecture/index.rst create mode 100644 score/time/high_res_steady_time/docs/index.rst create mode 100644 score/time/high_res_steady_time/docs/requirements/chklst_req_inspection.rst create mode 100644 score/time/high_res_steady_time/docs/requirements/index.rst create mode 100644 score/time/high_res_steady_time/docs/requirements/requirements.rst create mode 100644 score/time/steady_time/docs/architecture/chklst_arc_inspection.rst create mode 100644 score/time/steady_time/docs/architecture/component_architecture.rst create mode 100644 score/time/steady_time/docs/architecture/index.rst create mode 100644 score/time/steady_time/docs/index.rst create mode 100644 score/time/steady_time/docs/requirements/chklst_req_inspection.rst create mode 100644 score/time/steady_time/docs/requirements/index.rst create mode 100644 score/time/steady_time/docs/requirements/requirements.rst create mode 100644 score/time/system_time/docs/architecture/chklst_arc_inspection.rst create mode 100644 score/time/system_time/docs/architecture/component_architecture.rst create mode 100644 score/time/system_time/docs/architecture/index.rst create mode 100644 score/time/system_time/docs/index.rst create mode 100644 score/time/system_time/docs/requirements/chklst_req_inspection.rst create mode 100644 score/time/system_time/docs/requirements/index.rst create mode 100644 score/time/system_time/docs/requirements/requirements.rst create mode 100644 score/time/vehicle_time/docs/architecture/chklst_arc_inspection.rst create mode 100644 score/time/vehicle_time/docs/architecture/component_architecture.rst create mode 100644 score/time/vehicle_time/docs/architecture/index.rst create mode 100644 score/time/vehicle_time/docs/index.rst create mode 100644 score/time/vehicle_time/docs/requirements/chklst_req_inspection.rst create mode 100644 score/time/vehicle_time/docs/requirements/index.rst create mode 100644 score/time/vehicle_time/docs/requirements/requirements.rst diff --git a/docs/features/time/component_requirements.rst b/docs/features/time/component_requirements.rst deleted file mode 100644 index c70c95ce..00000000 --- a/docs/features/time/component_requirements.rst +++ /dev/null @@ -1,62 +0,0 @@ -Component Requirements -====================== - -.. comp_req:: VehicleClock returns snapshot with status - :id: comp_req__time__vehicle_clock_snapshot - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :satisfies: feat_req__time__snapshot_with_status - - ``VehicleClock::Now`` shall return a ``ClockSnapshot`` whose timepoint - and ``VehicleTimeStatus`` originate from the same backend read, so - downstream callers observe consistent time and status values. - -.. comp_req:: VehicleClock lifecycle operations - :id: comp_req__time__vehicle_clock_lifecycle - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :satisfies: feat_req__time__explicit_lifecycle - - ``VehicleClock`` shall provide ``Init``, ``IsAvailable`` and - ``WaitUntilAvailable`` operations that delegate to the backend and - report backend init failure and availability-wait timeouts to the - caller without blocking indefinitely. - -.. comp_req:: HighResSteadyClock always-ready snapshot - :id: comp_req__time__hirs_clock_snapshot - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :satisfies: feat_req__time__unified_clock_facade - - ``HighResSteadyClock::Now`` shall return a monotonic - ``ClockSnapshot`` without requiring prior initialization, and shall - not expose ``Init`` / ``IsAvailable`` / ``WaitUntilAvailable`` on the - facade (using them is a compile error). - -.. comp_req:: SteadyClock always-ready snapshot - :id: comp_req__time__steady_clock_snapshot - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :satisfies: feat_req__time__unified_clock_facade - - ``SteadyClock::Now`` shall return a snapshot backed by - ``std::chrono::steady_clock`` without requiring initialization. - -.. comp_req:: SystemClock always-ready snapshot - :id: comp_req__time__system_clock_snapshot - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :satisfies: feat_req__time__unified_clock_facade - - ``SystemClock::Now`` shall return a snapshot backed by - ``std::chrono::system_clock`` without requiring initialization. diff --git a/docs/features/time/index.rst b/docs/features/time/index.rst index ba52b650..da85e914 100644 --- a/docs/features/time/index.rst +++ b/docs/features/time/index.rst @@ -10,7 +10,6 @@ score::time — Unified Clock Interface :caption: Requirements feature_requirements - component_requirements Overview -------- diff --git a/docs/quality_pack.rst b/docs/quality_pack.rst index 80b0c9ba..a8d1ce77 100644 --- a/docs/quality_pack.rst +++ b/docs/quality_pack.rst @@ -56,15 +56,19 @@ Code coverage Requirements traceability (dashboards + gate) ============================================= -Requirements live under ``docs/features/time/`` and use the Score -metamodel directives (``feat_req::`` / ``comp_req::``). Source-code -and test-code links are consumed by ``score_docs_as_code``: +Feature requirements live under ``docs/features/time/feature_requirements.rst``. +Component requirements live alongside each component under +``score/time//docs/requirements/requirements.rst`` +(``vehicle_time``, ``steady_time``, ``system_time``, ``high_res_steady_time``), +matching the ``module_template`` layout. All entries use the Score metamodel +directives (``feat_req::`` / ``comp_req::``). Source-code and test-code links +are consumed by ``score_docs_as_code``: - **Source-code markers** — in the C++ implementation: .. code-block:: cpp - // # req-Id: comp_req__time__vehicle_clock_snapshot + // # req-Id: comp_req__vehicle_time__snapshot Snapshot Now() { ... } The leading ``// #`` is intentional; the linker regex looks for the @@ -81,7 +85,7 @@ and test-code links are consumed by ``score_docs_as_code``: TEST(VehicleClockTest, InitForwardsToBackend) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_lifecycle"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__vehicle_time__lifecycle"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); ::testing::Test::RecordProperty("Description", "…"); diff --git a/score/time/high_res_steady_time/docs/architecture/chklst_arc_inspection.rst b/score/time/high_res_steady_time/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..8787d259 --- /dev/null +++ b/score/time/high_res_steady_time/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,216 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: HighResSteadyTime Architecture Inspection Checklist + :id: doc__high_res_steady_time_arc_inspection + :status: draft + :version: 1 + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + :tags: template + +.. attention:: + The above directive must be updated according to your component. + + - Modify ``HighResSteadyTime`` to be your component Name + - Modify ``id`` to be your component Name in lower snake case preceded by ``doc__`` and followed by ``_arc_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Architecture Inspection Checklist +================================= + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per project processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - Trace should be checked automatically by tool support in the future. Will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented. Refer to `Tool Requirements `_ for the current status. + - + - + - + * - ARC_01_02 + - Does the software architecture design consider all the requirements allocated or belonging to the architectural element, including functional, non-functional, safety, and security requirements and all related design decisions? + - Check if all requirements allocated or belonging to the architectural element are considered in the design. This includes functional requirements (e.g. functional safety requirements), non-functional requirements (e.g. performance, reliability), and security requirements (e.g. confidentiality, integrity). Additionally, ensure that all related design decisions are taken into account and documented in the architectural design. + - + - + - + * - ARC_01_03 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - + - + - + * - ARC_01_04 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented by automated tool check. See `Tool Requirements `_. + Details of possible linking can be depicted from the traceability concept. + - + - + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - + - + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - + - + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - + - + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behaviour or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - + - + - + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - + - + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - + - + - + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - + - + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - + - + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture and the component? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + The belonging code metrics should be checked. + + Notes: + + If the "number of use cases" or "number of interfaces" above exceeds "3" or "number of function parameters" exceeds "5" or the "number of operations" exceeds "20" or global variables are used, a design rationale is mandatory. + + See also if component classification :need:`gd_temp__component_classification` as measure is present. + + - + - + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - + - + - + * - ARC_04_03 + - If your software architectural design of the component includes processes and tasks, are their scheduling policies and priorities (at least the needed relation one to another) defined to ensure that timing requirements are met? Please note, that the particular priorities or priority ranges will be probably defined by the project handbook or the software development plan. + + Note: see :need:`std_req__iso26262__software_743` + - Give a reason for these scheduling policies and priorities or explain why not needed. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "high_res_steady_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :tags: high_res_steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "high_res_steady_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :tags: high_res_steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/high_res_steady_time/docs/architecture/component_architecture.rst b/score/time/high_res_steady_time/docs/architecture/component_architecture.rst new file mode 100644 index 00000000..6e60dc0d --- /dev/null +++ b/score/time/high_res_steady_time/docs/architecture/component_architecture.rst @@ -0,0 +1,72 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _high_res_steady_time_component_architecture: + +HighResSteadyTime Architecture Documentation +============================================ + +.. document:: HighResSteadyTime Architecture + :id: doc__high_res_steady_time_architecture + :status: draft + :version: 1 + :safety: QM + :security: NO + :realizes: wp__component_arch + :tags: high_res_steady_time + +Overview +-------- + + + +Static Architecture +------------------- + +.. comp:: HighResSteadyTime + :id: comp__high_res_steady_time + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: feat__time + +.. comp_arc_sta:: HighResSteadyTime (Static View) + :id: comp_arc_sta__high_res_steady_time__sv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__high_res_steady_time + :fulfils: + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: HighResSteadyTime Dynamic View + :id: comp_arc_dyn__high_res_steady_time__dv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__high_res_steady_time + :fulfils: + + Put here a sequence diagram diff --git a/score/time/high_res_steady_time/docs/architecture/index.rst b/score/time/high_res_steady_time/docs/architecture/index.rst new file mode 100644 index 00000000..3ea0100b --- /dev/null +++ b/score/time/high_res_steady_time/docs/architecture/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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_architecture_template: + +Component Architecture +====================== + +.. toctree:: + + component_architecture + chklst_arc_inspection diff --git a/score/time/high_res_steady_time/docs/index.rst b/score/time/high_res_steady_time/docs/index.rst new file mode 100644 index 00000000..6fe449a9 --- /dev/null +++ b/score/time/high_res_steady_time/docs/index.rst @@ -0,0 +1,56 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _high_res_steady_time: + +HighResSteadyTime +################# + +.. note:: Always-ready high-resolution monotonic clock component + +.. document:: HighResSteadyTime + :id: doc__high_res_steady_time + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__cmpt_request + :tags: high_res_steady_time + +Abstract +======== + +This component provides the ``HighResSteadyClock`` facade. ``Now`` +returns a monotonic ``ClockSnapshot`` without prior initialization; the +lifecycle operations (``Init`` / ``IsAvailable`` / +``WaitUntilAvailable``) are compile-time unavailable on this facade. + +Specification +============= + +* :need:`comp_req__high_res_steady_time__snapshot` + +Footnotes +========= + +Further Documentation of the component can be found in the following sections: + +Component Detail Information +============================ + +.. toctree:: + :maxdepth: 1 + + requirements/index + architecture/index diff --git a/score/time/high_res_steady_time/docs/requirements/chklst_req_inspection.rst b/score/time/high_res_steady_time/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..475c1bdb --- /dev/null +++ b/score/time/high_res_steady_time/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,195 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: HighResSteadyTime Requirements Inspection Checklist + :id: doc__high_res_steady_time_req_inspection + :status: draft + :version: 2 + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + :tags: template + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``HighResSteadyTime`` to be your Component Name + - Modify ``id`` to be your Component Name in lower snake case preceded by ``doc__`` and followed by ``_req_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: +- test expert: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + * - REQ_10_01 + - Is the requirement description *complete* ? + - For every requirement in the inspection, follow to its parent (feature) requirement(s) and then check if this/these are fulfilled completely by its/their linked children (component requirements, including those which are not in scope of the inspection). + - + - + - + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "high_res_steady_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: high_res_steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "high_res_steady_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: high_res_steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/high_res_steady_time/docs/requirements/index.rst b/score/time/high_res_steady_time/docs/requirements/index.rst new file mode 100644 index 00000000..9eea1fc7 --- /dev/null +++ b/score/time/high_res_steady_time/docs/requirements/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements + chklst_req_inspection diff --git a/score/time/high_res_steady_time/docs/requirements/requirements.rst b/score/time/high_res_steady_time/docs/requirements/requirements.rst new file mode 100644 index 00000000..c3f709b2 --- /dev/null +++ b/score/time/high_res_steady_time/docs/requirements/requirements.rst @@ -0,0 +1,46 @@ +.. + # ******************************************************************************* + # 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 HighResSteadyTime Requirements +######################################## + +.. document:: HighResSteadyTime Requirements + :id: doc__high_res_steady_time_requirements + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, high_res_steady_time + +Functional Requirements +----------------------- + +.. comp_req:: HighResSteadyClock always-ready snapshot + :id: comp_req__high_res_steady_time__snapshot + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: feat_req__time__unified_clock_facade + :status: valid + :version: 1 + :satisfied_by: comp__high_res_steady_time + + ``HighResSteadyClock::Now`` shall return a monotonic + ``ClockSnapshot`` without requiring prior initialization, and shall + not expose ``Init`` / ``IsAvailable`` / ``WaitUntilAvailable`` on the + facade (using them is a compile error). + +.. needextend:: is_external == False and "high_res_steady_time" in id + :+tags: high_res_steady_time diff --git a/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp b/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp index 8582cecf..825bc48b 100644 --- a/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp +++ b/score/time/high_res_steady_time/src/high_res_steady_clock_test.cpp @@ -28,7 +28,7 @@ namespace time TEST(HighResSteadyClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__hirs_clock_snapshot"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__high_res_steady_time__snapshot"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); ::testing::Test::RecordProperty("Description", diff --git a/score/time/steady_time/docs/architecture/chklst_arc_inspection.rst b/score/time/steady_time/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..7d027628 --- /dev/null +++ b/score/time/steady_time/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,216 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: SteadyTime Architecture Inspection Checklist + :id: doc__steady_time_arc_inspection + :status: draft + :version: 1 + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + :tags: template + +.. attention:: + The above directive must be updated according to your component. + + - Modify ``SteadyTime`` to be your component Name + - Modify ``id`` to be your component Name in lower snake case preceded by ``doc__`` and followed by ``_arc_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Architecture Inspection Checklist +================================= + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per project processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - Trace should be checked automatically by tool support in the future. Will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented. Refer to `Tool Requirements `_ for the current status. + - + - + - + * - ARC_01_02 + - Does the software architecture design consider all the requirements allocated or belonging to the architectural element, including functional, non-functional, safety, and security requirements and all related design decisions? + - Check if all requirements allocated or belonging to the architectural element are considered in the design. This includes functional requirements (e.g. functional safety requirements), non-functional requirements (e.g. performance, reliability), and security requirements (e.g. confidentiality, integrity). Additionally, ensure that all related design decisions are taken into account and documented in the architectural design. + - + - + - + * - ARC_01_03 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - + - + - + * - ARC_01_04 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented by automated tool check. See `Tool Requirements `_. + Details of possible linking can be depicted from the traceability concept. + - + - + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - + - + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - + - + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - + - + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behaviour or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - + - + - + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - + - + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - + - + - + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - + - + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - + - + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture and the component? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + The belonging code metrics should be checked. + + Notes: + + If the "number of use cases" or "number of interfaces" above exceeds "3" or "number of function parameters" exceeds "5" or the "number of operations" exceeds "20" or global variables are used, a design rationale is mandatory. + + See also if component classification :need:`gd_temp__component_classification` as measure is present. + + - + - + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - + - + - + * - ARC_04_03 + - If your software architectural design of the component includes processes and tasks, are their scheduling policies and priorities (at least the needed relation one to another) defined to ensure that timing requirements are met? Please note, that the particular priorities or priority ranges will be probably defined by the project handbook or the software development plan. + + Note: see :need:`std_req__iso26262__software_743` + - Give a reason for these scheduling policies and priorities or explain why not needed. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "steady_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :tags: steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "steady_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :tags: steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/steady_time/docs/architecture/component_architecture.rst b/score/time/steady_time/docs/architecture/component_architecture.rst new file mode 100644 index 00000000..893fd070 --- /dev/null +++ b/score/time/steady_time/docs/architecture/component_architecture.rst @@ -0,0 +1,72 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _steady_time_component_architecture: + +SteadyTime Architecture Documentation +===================================== + +.. document:: SteadyTime Architecture + :id: doc__steady_time_architecture + :status: draft + :version: 1 + :safety: QM + :security: NO + :realizes: wp__component_arch + :tags: steady_time + +Overview +-------- + + + +Static Architecture +------------------- + +.. comp:: SteadyTime + :id: comp__steady_time + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: feat__time + +.. comp_arc_sta:: SteadyTime (Static View) + :id: comp_arc_sta__steady_time__sv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__steady_time + :fulfils: + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: SteadyTime Dynamic View + :id: comp_arc_dyn__steady_time__dv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__steady_time + :fulfils: + + Put here a sequence diagram diff --git a/score/time/steady_time/docs/architecture/index.rst b/score/time/steady_time/docs/architecture/index.rst new file mode 100644 index 00000000..3ea0100b --- /dev/null +++ b/score/time/steady_time/docs/architecture/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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_architecture_template: + +Component Architecture +====================== + +.. toctree:: + + component_architecture + chklst_arc_inspection diff --git a/score/time/steady_time/docs/index.rst b/score/time/steady_time/docs/index.rst new file mode 100644 index 00000000..fc79b4bb --- /dev/null +++ b/score/time/steady_time/docs/index.rst @@ -0,0 +1,56 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _steady_time: + +SteadyTime +########## + +.. note:: Always-ready monotonic clock component backed by ``std::chrono::steady_clock`` + +.. document:: SteadyTime + :id: doc__steady_time + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__cmpt_request + :tags: steady_time + +Abstract +======== + +This component provides the ``SteadyClock`` facade over +``std::chrono::steady_clock``. It is always ready and does not expose +``Init`` / ``IsAvailable`` / ``WaitUntilAvailable`` — using them on this +facade is a compile-time error. + +Specification +============= + +* :need:`comp_req__steady_time__snapshot` + +Footnotes +========= + +Further Documentation of the component can be found in the following sections: + +Component Detail Information +============================ + +.. toctree:: + :maxdepth: 1 + + requirements/index + architecture/index diff --git a/score/time/steady_time/docs/requirements/chklst_req_inspection.rst b/score/time/steady_time/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..c36930a6 --- /dev/null +++ b/score/time/steady_time/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,195 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: SteadyTime Requirements Inspection Checklist + :id: doc__steady_time_req_inspection + :status: draft + :version: 2 + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + :tags: template + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``SteadyTime`` to be your Component Name + - Modify ``id`` to be your Component Name in lower snake case preceded by ``doc__`` and followed by ``_req_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: +- test expert: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + * - REQ_10_01 + - Is the requirement description *complete* ? + - For every requirement in the inspection, follow to its parent (feature) requirement(s) and then check if this/these are fulfilled completely by its/their linked children (component requirements, including those which are not in scope of the inspection). + - + - + - + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "steady_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "steady_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: steady_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/steady_time/docs/requirements/index.rst b/score/time/steady_time/docs/requirements/index.rst new file mode 100644 index 00000000..9eea1fc7 --- /dev/null +++ b/score/time/steady_time/docs/requirements/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements + chklst_req_inspection diff --git a/score/time/steady_time/docs/requirements/requirements.rst b/score/time/steady_time/docs/requirements/requirements.rst new file mode 100644 index 00000000..a960312f --- /dev/null +++ b/score/time/steady_time/docs/requirements/requirements.rst @@ -0,0 +1,44 @@ +.. + # ******************************************************************************* + # 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 SteadyTime Requirements +################################# + +.. document:: SteadyTime Requirements + :id: doc__steady_time_requirements + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, steady_time + +Functional Requirements +----------------------- + +.. comp_req:: SteadyClock always-ready snapshot + :id: comp_req__steady_time__snapshot + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: feat_req__time__unified_clock_facade + :status: valid + :version: 1 + :satisfied_by: comp__steady_time + + ``SteadyClock::Now`` shall return a snapshot backed by + ``std::chrono::steady_clock`` without requiring initialization. + +.. needextend:: is_external == False and "steady_time" in id + :+tags: steady_time diff --git a/score/time/steady_time/src/steady_clock_test.cpp b/score/time/steady_time/src/steady_clock_test.cpp index 377cf08f..27ec0cf3 100644 --- a/score/time/steady_time/src/steady_clock_test.cpp +++ b/score/time/steady_time/src/steady_clock_test.cpp @@ -43,7 +43,7 @@ class SampleSteadyService TEST(SteadyClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__steady_clock_snapshot"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__steady_time__snapshot"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); ::testing::Test::RecordProperty("Description", diff --git a/score/time/system_time/docs/architecture/chklst_arc_inspection.rst b/score/time/system_time/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..4cedc21c --- /dev/null +++ b/score/time/system_time/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,216 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: SystemTime Architecture Inspection Checklist + :id: doc__system_time_arc_inspection + :status: draft + :version: 1 + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + :tags: template + +.. attention:: + The above directive must be updated according to your component. + + - Modify ``SystemTime`` to be your component Name + - Modify ``id`` to be your component Name in lower snake case preceded by ``doc__`` and followed by ``_arc_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Architecture Inspection Checklist +================================= + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per project processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - Trace should be checked automatically by tool support in the future. Will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented. Refer to `Tool Requirements `_ for the current status. + - + - + - + * - ARC_01_02 + - Does the software architecture design consider all the requirements allocated or belonging to the architectural element, including functional, non-functional, safety, and security requirements and all related design decisions? + - Check if all requirements allocated or belonging to the architectural element are considered in the design. This includes functional requirements (e.g. functional safety requirements), non-functional requirements (e.g. performance, reliability), and security requirements (e.g. confidentiality, integrity). Additionally, ensure that all related design decisions are taken into account and documented in the architectural design. + - + - + - + * - ARC_01_03 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - + - + - + * - ARC_01_04 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented by automated tool check. See `Tool Requirements `_. + Details of possible linking can be depicted from the traceability concept. + - + - + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - + - + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - + - + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - + - + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behaviour or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - + - + - + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - + - + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - + - + - + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - + - + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - + - + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture and the component? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + The belonging code metrics should be checked. + + Notes: + + If the "number of use cases" or "number of interfaces" above exceeds "3" or "number of function parameters" exceeds "5" or the "number of operations" exceeds "20" or global variables are used, a design rationale is mandatory. + + See also if component classification :need:`gd_temp__component_classification` as measure is present. + + - + - + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - + - + - + * - ARC_04_03 + - If your software architectural design of the component includes processes and tasks, are their scheduling policies and priorities (at least the needed relation one to another) defined to ensure that timing requirements are met? Please note, that the particular priorities or priority ranges will be probably defined by the project handbook or the software development plan. + + Note: see :need:`std_req__iso26262__software_743` + - Give a reason for these scheduling policies and priorities or explain why not needed. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "system_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :tags: system_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "system_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :tags: system_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/system_time/docs/architecture/component_architecture.rst b/score/time/system_time/docs/architecture/component_architecture.rst new file mode 100644 index 00000000..06c1bdb9 --- /dev/null +++ b/score/time/system_time/docs/architecture/component_architecture.rst @@ -0,0 +1,72 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _system_time_component_architecture: + +SystemTime Architecture Documentation +===================================== + +.. document:: SystemTime Architecture + :id: doc__system_time_architecture + :status: draft + :version: 1 + :safety: QM + :security: NO + :realizes: wp__component_arch + :tags: system_time + +Overview +-------- + + + +Static Architecture +------------------- + +.. comp:: SystemTime + :id: comp__system_time + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: feat__time + +.. comp_arc_sta:: SystemTime (Static View) + :id: comp_arc_sta__system_time__sv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__system_time + :fulfils: + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: SystemTime Dynamic View + :id: comp_arc_dyn__system_time__dv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__system_time + :fulfils: + + Put here a sequence diagram diff --git a/score/time/system_time/docs/architecture/index.rst b/score/time/system_time/docs/architecture/index.rst new file mode 100644 index 00000000..3ea0100b --- /dev/null +++ b/score/time/system_time/docs/architecture/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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_architecture_template: + +Component Architecture +====================== + +.. toctree:: + + component_architecture + chklst_arc_inspection diff --git a/score/time/system_time/docs/index.rst b/score/time/system_time/docs/index.rst new file mode 100644 index 00000000..1e849f19 --- /dev/null +++ b/score/time/system_time/docs/index.rst @@ -0,0 +1,56 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _system_time: + +SystemTime +########## + +.. note:: Always-ready wall-clock component backed by ``std::chrono::system_clock`` + +.. document:: SystemTime + :id: doc__system_time + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__cmpt_request + :tags: system_time + +Abstract +======== + +This component provides the ``SystemClock`` facade over +``std::chrono::system_clock``. It is always ready and does not expose +``Init`` / ``IsAvailable`` / ``WaitUntilAvailable`` — using them on this +facade is a compile-time error. + +Specification +============= + +* :need:`comp_req__system_time__snapshot` + +Footnotes +========= + +Further Documentation of the component can be found in the following sections: + +Component Detail Information +============================ + +.. toctree:: + :maxdepth: 1 + + requirements/index + architecture/index diff --git a/score/time/system_time/docs/requirements/chklst_req_inspection.rst b/score/time/system_time/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..ca778bac --- /dev/null +++ b/score/time/system_time/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,195 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: SystemTime Requirements Inspection Checklist + :id: doc__system_time_req_inspection + :status: draft + :version: 2 + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + :tags: template + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``SystemTime`` to be your Component Name + - Modify ``id`` to be your Component Name in lower snake case preceded by ``doc__`` and followed by ``_req_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: +- test expert: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + * - REQ_10_01 + - Is the requirement description *complete* ? + - For every requirement in the inspection, follow to its parent (feature) requirement(s) and then check if this/these are fulfilled completely by its/their linked children (component requirements, including those which are not in scope of the inspection). + - + - + - + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "system_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: system_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "system_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: system_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/system_time/docs/requirements/index.rst b/score/time/system_time/docs/requirements/index.rst new file mode 100644 index 00000000..9eea1fc7 --- /dev/null +++ b/score/time/system_time/docs/requirements/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements + chklst_req_inspection diff --git a/score/time/system_time/docs/requirements/requirements.rst b/score/time/system_time/docs/requirements/requirements.rst new file mode 100644 index 00000000..73c39d7a --- /dev/null +++ b/score/time/system_time/docs/requirements/requirements.rst @@ -0,0 +1,44 @@ +.. + # ******************************************************************************* + # 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 SystemTime Requirements +################################# + +.. document:: SystemTime Requirements + :id: doc__system_time_requirements + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, system_time + +Functional Requirements +----------------------- + +.. comp_req:: SystemClock always-ready snapshot + :id: comp_req__system_time__snapshot + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: feat_req__time__unified_clock_facade + :status: valid + :version: 1 + :satisfied_by: comp__system_time + + ``SystemClock::Now`` shall return a snapshot backed by + ``std::chrono::system_clock`` without requiring initialization. + +.. needextend:: is_external == False and "system_time" in id + :+tags: system_time diff --git a/score/time/system_time/src/system_clock_test.cpp b/score/time/system_time/src/system_clock_test.cpp index 385990da..5c2f4875 100644 --- a/score/time/system_time/src/system_clock_test.cpp +++ b/score/time/system_time/src/system_clock_test.cpp @@ -43,7 +43,7 @@ class SampleSystemService TEST(SystemClockTest, NowReturnsTimepointSuitableForDurationArithmetic) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__system_clock_snapshot"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__system_time__snapshot"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); ::testing::Test::RecordProperty("Description", diff --git a/score/time/vehicle_time/docs/architecture/chklst_arc_inspection.rst b/score/time/vehicle_time/docs/architecture/chklst_arc_inspection.rst new file mode 100644 index 00000000..49ed2c49 --- /dev/null +++ b/score/time/vehicle_time/docs/architecture/chklst_arc_inspection.rst @@ -0,0 +1,216 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: VehicleTime Architecture Inspection Checklist + :id: doc__vehicle_time_arc_inspection + :status: draft + :version: 1 + :safety: ASIL_B + :security: YES + :realizes: wp__sw_arch_verification + :tags: template + +.. attention:: + The above directive must be updated according to your component. + + - Modify ``VehicleTime`` to be your component Name + - Modify ``id`` to be your component Name in lower snake case preceded by ``doc__`` and followed by ``_arc_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Architecture Inspection Checklist +================================= + +Purpose +------- + +The purpose of the software architecture checklist is to ensure that the design meets the criteria and quality as +defined per project processes and guidelines for feature and component architectural design elements. +It helps to check the compliance with requirements, identify errors or inconsistencies, and ensure adherence to best +practices. +The checklist guides evaluation of the architecture design, identifies potential problems, and aids in +communication and documentation of architectural decisions to stakeholders. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Architecture Design Review Checklist + :header-rows: 1 + + * - Review Id + - Acceptance criteria + - Guidance + - passed + - Remarks + - Issue link + * - ARC_01_01 + - Is the traceability from software architectural elements to requirements, and other level architectural elements (e.g. component to interface) established according to the "Relations between the architectural elements" as described in :need:`doc_concept__arch_process`? + - Trace should be checked automatically by tool support in the future. Will be removed from the checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented. Refer to `Tool Requirements `_ for the current status. + - + - + - + * - ARC_01_02 + - Does the software architecture design consider all the requirements allocated or belonging to the architectural element, including functional, non-functional, safety, and security requirements and all related design decisions? + - Check if all requirements allocated or belonging to the architectural element are considered in the design. This includes functional requirements (e.g. functional safety requirements), non-functional requirements (e.g. performance, reliability), and security requirements (e.g. confidentiality, integrity). Additionally, ensure that all related design decisions are taken into account and documented in the architectural design. + - + - + - + * - ARC_01_03 + - If the architectural element is related to any supplier manuals (incl. safety and security) + are the relevant parts covered? + - If the architecture makes use of supplied elements, their manuals (like safety) have to be considered (i.e. its provided functionality matches the expectation and assumptions are fulfilled). Note that in case of safety component this means that assumed Technical Safety Requirements and AoUs of the safety manual are covered. + - + - + - + * - ARC_01_04 + - Is the architectural element traceable to the lower level artifacts as defined by the workproduct traceability? + - Will be removed from checklist once the requirement (:need:`Correlations of the architectural building blocks `) is implemented by automated tool check. See `Tool Requirements `_. + Details of possible linking can be depicted from the traceability concept. + - + - + - + * - ARC_02_01 + - Is the software architecture design compliant with the (overall) feature architecture? + - On component level check against the feature architecture, on feature level check other features with common components used. + - + - + - + * - ARC_02_02 + - Is appropriate and comprehensible operation/interface naming present in the architectural design? + - Check :need:`gd_guidl__arch_design` + - + - + - + * - ARC_02_03 + - Are correctness of data flow and control flow within the architectural elements considered? + - E.g. examine definitions, transformations, integrity, and interaction of data; check error handling, data + exchange between elements, correct response to inputs and documented decision making. + Note: consistency is ensured by the process/tooling, by defining each interface only once. + - + - + - + * - ARC_02_04 + - Are the interfaces between the software architectural element and other architectural elements well-defined? + - Check if the interface reacts on non-defined behaviour or errors; can established protocols be used; are the + interfaces for inputs, outputs, error codes documented; is loose coupling considered and only limited exposure; + can unit or integration test be written against the interface; data amount transferred; no sensitive data + exposure; + - + - + - + * - ARC_02_05 + - Does the software architectural element consider the timing constraints (from the parent requirement)? + - If there are hard requirements on the timing a programming time estimation should be performed and also + deadline supervision considered. + - + - + - + * - ARC_02_06 + - Is the documentation of the software architectural element, including textual and graphical descriptions + (e.g., UML diagrams), comprehensible and complete? + - Use of semi-formal notation is expected for architectural elements with an allocated ASIL level. + Is the architecture template correctly filled? + - + - + - + * - ARC_03_01 + - Is the architectural element modular and encapsulated? + - Check e.g. that only minimal interfaces are used. Design should be object oriented. Interfaces and interactions are clearly defined. Usage of access types (private, protected) properly set. Limited global variables. + - + - + - + * - ARC_03_02 + - Is the suitability of the software architecture for future modifications and maintainability considered? + - Check for e.g. loose coupling, separation of concerns, high cohesion, versioning strategy for interfaces, + decision records, use of established design patterns. + - + - + - + * - ARC_03_03 + - Are simplicity and avoidance of unnecessary complexity present in the software architecture and the component? + - Indicators for complexity are: number of use cases (corresponding to dynamic diagrams) + allocated to single design element, number of interfaces and operations in an interface, + function parameters, global variables, complex types, limited comprehensibility. + The belonging code metrics should be checked. + + Notes: + + If the "number of use cases" or "number of interfaces" above exceeds "3" or "number of function parameters" exceeds "5" or the "number of operations" exceeds "20" or global variables are used, a design rationale is mandatory. + + See also if component classification :need:`gd_temp__component_classification` as measure is present. + + - + - + - + * - ARC_03_04 + - Is the software architecture design following best practices and design principles? + - Refer to architectural guidelines and recommendations within the project documentation. + - + - + - + * - ARC_04_03 + - If your software architectural design of the component includes processes and tasks, are their scheduling policies and priorities (at least the needed relation one to another) defined to ensure that timing requirements are met? Please note, that the particular priorities or priority ranges will be probably defined by the project handbook or the software development plan. + + Note: see :need:`std_req__iso26262__software_743` + - Give a reason for these scheduling policies and priorities or explain why not needed. + - + - + - + + +.. attention:: + The above checklist entries must be filled according to your component architecture in scope. + +Note: If a Review ID is not applicable for your architecture, then state ""n/a" in status and comment accordingly in remarks. + +The following static views in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "vehicle_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_sta + :tags: vehicle_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +and the following dynamic views: + +.. needtable:: + :filter: "vehicle_time" in docname and "architecture" in docname and docname is not None and status == "valid" + :style: table + :types: comp_arc_dyn + :tags: vehicle_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/vehicle_time/docs/architecture/component_architecture.rst b/score/time/vehicle_time/docs/architecture/component_architecture.rst new file mode 100644 index 00000000..4dee27ea --- /dev/null +++ b/score/time/vehicle_time/docs/architecture/component_architecture.rst @@ -0,0 +1,72 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _vehicle_time_component_architecture: + +VehicleTime Architecture Documentation +====================================== + +.. document:: VehicleTime Architecture + :id: doc__vehicle_time_architecture + :status: draft + :version: 1 + :safety: QM + :security: NO + :realizes: wp__component_arch + :tags: vehicle_time + +Overview +-------- + + + +Static Architecture +------------------- + +.. comp:: VehicleTime + :id: comp__vehicle_time + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: feat__time + +.. comp_arc_sta:: VehicleTime (Static View) + :id: comp_arc_sta__vehicle_time__sv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__vehicle_time + :fulfils: + + .. needarch:: + :scale: 50 + :align: center + + {{ draw_component(need(), needs) }} + +Dynamic Architecture +-------------------- + +.. comp_arc_dyn:: VehicleTime Dynamic View + :id: comp_arc_dyn__vehicle_time__dv + :security: NO + :safety: QM + :status: invalid + :version: 1 + :belongs_to: comp__vehicle_time + :fulfils: + + Put here a sequence diagram diff --git a/score/time/vehicle_time/docs/architecture/index.rst b/score/time/vehicle_time/docs/architecture/index.rst new file mode 100644 index 00000000..3ea0100b --- /dev/null +++ b/score/time/vehicle_time/docs/architecture/index.rst @@ -0,0 +1,23 @@ +.. + # ******************************************************************************* + # 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_architecture_template: + +Component Architecture +====================== + +.. toctree:: + + component_architecture + chklst_arc_inspection diff --git a/score/time/vehicle_time/docs/index.rst b/score/time/vehicle_time/docs/index.rst new file mode 100644 index 00000000..f9b152df --- /dev/null +++ b/score/time/vehicle_time/docs/index.rst @@ -0,0 +1,62 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _vehicle_time: + +VehicleTime +########### + +.. note:: PTP-synchronized vehicle clock component + +.. document:: VehicleTime + :id: doc__vehicle_time + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__cmpt_request + :tags: vehicle_time + +Abstract +======== + +This component implements the PTP-synchronized vehicle clock facade. +``VehicleClock::Now`` returns a ``ClockSnapshot`` bundling the timepoint +with a ``VehicleTimeStatus`` (synchronization / leap flags, rate +deviation), and the component exposes ``Init`` / ``IsAvailable`` / +``WaitUntilAvailable`` because the underlying backend depends on an IPC +channel to the time master. + +Specification +============= + +The component provides a snapshot-with-status API and explicit +availability lifecycle: + +* :need:`comp_req__vehicle_time__snapshot` +* :need:`comp_req__vehicle_time__lifecycle` + +Footnotes +========= + +Further Documentation of the component can be found in the following sections: + +Component Detail Information +============================ + +.. toctree:: + :maxdepth: 1 + + requirements/index + architecture/index diff --git a/score/time/vehicle_time/docs/requirements/chklst_req_inspection.rst b/score/time/vehicle_time/docs/requirements/chklst_req_inspection.rst new file mode 100644 index 00000000..26e66b17 --- /dev/null +++ b/score/time/vehicle_time/docs/requirements/chklst_req_inspection.rst @@ -0,0 +1,195 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +.. document:: VehicleTime Requirements Inspection Checklist + :id: doc__vehicle_time_req_inspection + :status: draft + :version: 2 + :safety: ASIL_B + :security: YES + :realizes: wp__requirements_inspect + :tags: template + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``VehicleTime`` to be your Component Name + - Modify ``id`` to be your Component Name in lower snake case preceded by ``doc__`` and followed by ``_req_inspection`` + - Adjust ``status`` to be ``valid`` + - Adjust ``safety``, ``security`` and ``tags`` according to your needs + +Requirement Inspection Checklist +================================ + +Purpose +------- + +The purpose of this requirement inspection checklist is to collect the topics to be checked during requirements inspection. + +Conduct +------- + +As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: + +- content responsible (author): +- reviewer: +- moderator: +- test expert: + +Checklist +--------- + +It is mandatory to fill in the "passed" column with "yes" or "no" for each checklist item and additionally to add in the remarks why it is passed or not passed. +In case of "no" an issue link to the issue tracking system has to be added in the last column (if not solved in the same issue). +See also :need:`doc_concept__wp_inspections` for further information about reviews in general and inspection in particular. + +.. list-table:: Component Requirement Inspection Checklist + :header-rows: 1 + :widths: 10,30,50,6,6,8 + + * - Review ID + - Acceptance Criteria + - Guidance + - Passed + - Remarks + - Issue link + * - REQ_01_01 + - Is the requirement formulation template used? + - see :need:`gd_temp__req_formulation`, this includes the use of "shall". + - + - + - + * - REQ_02_01 + - Is the requirement description *comprehensible* ? + - If you think the requirement is hard to understand, comment here. + - + - + - + * - REQ_02_02 + - Is the requirement description *unambiguous* ? + - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. + - + - + - + * - REQ_02_03 + - Is the requirement description *atomic* ? + - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. + - + - + - + * - REQ_02_04 + - Is the requirement description *feasible* ? + - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. + - + - + - + * - REQ_02_05 + - Is the requirement description *independent from implementation* ? + - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. + - + - + - + * - REQ_03_01 + - Is the *linkage to the parent requirement* correct? + - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. + - + - + - + * - REQ_04_01 + - Is the requirement *internally and externally consistent*? + - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). + - + - + - + * - REQ_05_01 + - Do the software requirements consider *timing constraints*? + - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". + - + - + - + * - REQ_06_01 + - Does the requirement consider *external interfaces*? + - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? + - + - + - + * - REQ_07_01 + - Is the *safety* attribute set correctly? + - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. + - + - + - + * - REQ_07_02 + - Is the attribute *security* set correctly? + - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. + - + - + - + * - REQ_08_01 + - Is the requirement *verifiable*? + - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. + - + - + - + * - REQ_08_02 + - Is the requirement verifiable by design or code review in case it is not feasibly testable? + - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. + - + - + - + * - REQ_09_01 + - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? + - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. + - + - + - + * - REQ_10_01 + - Is the requirement description *complete* ? + - For every requirement in the inspection, follow to its parent (feature) requirement(s) and then check if this/these are fulfilled completely by its/their linked children (component requirements, including those which are not in scope of the inspection). + - + - + - + +.. attention:: + The above checklist entries must be filled according to your component requirements in scope. + +Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + +The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: + +.. needtable:: + :filter: "vehicle_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: comp_req + :tags: vehicle_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): + +.. needtable:: + :filter: "vehicle_time" in docname and "requirements" in docname and docname is not None and status == "valid" + :style: table + :types: aou_req + :tags: vehicle_time + :columns: id;status;tags + :colwidths: 25,25,25 + :sort: title + +.. attention:: + The above tables filtering must be updated according to your Component. + + - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/score/time/vehicle_time/docs/requirements/index.rst b/score/time/vehicle_time/docs/requirements/index.rst new file mode 100644 index 00000000..9eea1fc7 --- /dev/null +++ b/score/time/vehicle_time/docs/requirements/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements + chklst_req_inspection diff --git a/score/time/vehicle_time/docs/requirements/requirements.rst b/score/time/vehicle_time/docs/requirements/requirements.rst new file mode 100644 index 00000000..db33026b --- /dev/null +++ b/score/time/vehicle_time/docs/requirements/requirements.rst @@ -0,0 +1,60 @@ +.. + # ******************************************************************************* + # 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 VehicleTime Requirements +################################## + +.. document:: VehicleTime Requirements + :id: doc__vehicle_time_requirements + :status: valid + :version: 1 + :safety: QM + :security: NO + :realizes: wp__requirements_comp[version==1] + :tags: requirements, vehicle_time + +Functional Requirements +----------------------- + +.. comp_req:: VehicleClock returns snapshot with status + :id: comp_req__vehicle_time__snapshot + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: feat_req__time__snapshot_with_status + :status: valid + :version: 1 + :satisfied_by: comp__vehicle_time + + ``VehicleClock::Now`` shall return a ``ClockSnapshot`` whose timepoint + and ``VehicleTimeStatus`` originate from the same backend read, so + downstream callers observe consistent time and status values. + +.. comp_req:: VehicleClock lifecycle operations + :id: comp_req__vehicle_time__lifecycle + :reqtype: Functional + :security: NO + :safety: QM + :derived_from: feat_req__time__explicit_lifecycle + :status: valid + :version: 1 + :satisfied_by: comp__vehicle_time + + ``VehicleClock`` shall provide ``Init``, ``IsAvailable`` and + ``WaitUntilAvailable`` operations that delegate to the backend and + report backend init failure and availability-wait timeouts to the + caller without blocking indefinitely. + +.. needextend:: is_external == False and "vehicle_time" in id + :+tags: vehicle_time diff --git a/score/time/vehicle_time/src/vehicle_clock.cpp b/score/time/vehicle_time/src/vehicle_clock.cpp index 56fce856..ef441677 100644 --- a/score/time/vehicle_time/src/vehicle_clock.cpp +++ b/score/time/vehicle_time/src/vehicle_clock.cpp @@ -41,25 +41,25 @@ std::ostringstream ClockStatus::PrintTo() const return oss; } -// # req-Id: comp_req__time__vehicle_clock_snapshot +// # req-Id: comp_req__vehicle_time__snapshot ClockTraits::Snapshot ClockTraits::CallNow(const Backend& impl) noexcept { return impl.Now(); } -// # req-Id: comp_req__time__vehicle_clock_lifecycle +// # req-Id: comp_req__vehicle_time__lifecycle bool InitializationHook::CallInit(Backend& impl) noexcept { return impl.Init(); } -// # req-Id: comp_req__time__vehicle_clock_lifecycle +// # req-Id: comp_req__vehicle_time__lifecycle bool AvailabilityHook::CallIsAvailable(const Backend& impl) noexcept { return impl.IsAvailable(); } -// # req-Id: comp_req__time__vehicle_clock_lifecycle +// # req-Id: comp_req__vehicle_time__lifecycle bool AvailabilityHook::CallWaitUntilAvailable(const Backend& impl, const score::cpp::stop_token& token, std::chrono::steady_clock::time_point until) noexcept diff --git a/score/time/vehicle_time/src/vehicle_clock_test.cpp b/score/time/vehicle_time/src/vehicle_clock_test.cpp index ac242c42..1fa192b1 100644 --- a/score/time/vehicle_time/src/vehicle_clock_test.cpp +++ b/score/time/vehicle_time/src/vehicle_clock_test.cpp @@ -52,7 +52,7 @@ class SampleVehicleService TEST(VehicleClockTest, NowReturnsSynchronizedStatusAndTimepoint) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_snapshot"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__vehicle_time__snapshot"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "equivalence-classes"); ::testing::Test::RecordProperty("Description", @@ -103,7 +103,7 @@ TEST(VehicleClockTest, NowIsReliableReturnsFalseWhenTimeoutSet) TEST(VehicleClockTest, InitForwardsToBackend) { - ::testing::Test::RecordProperty("FullyVerifies", "comp_req__time__vehicle_clock_lifecycle"); + ::testing::Test::RecordProperty("FullyVerifies", "comp_req__vehicle_time__lifecycle"); ::testing::Test::RecordProperty("TestType", "requirements-based"); ::testing::Test::RecordProperty("DerivationTechnique", "requirements-analysis"); ::testing::Test::RecordProperty("Description", "VehicleClock::Init delegates to the backend Init call.");