Skip to content

Prepare the new score::time API#18

Draft
lavrovvalera wants to merge 4 commits into
eclipse-score:mainfrom
lavrovvalera:vala_time_gen_api
Draft

Prepare the new score::time API#18
lavrovvalera wants to merge 4 commits into
eclipse-score:mainfrom
lavrovvalera:vala_time_gen_api

Conversation

@lavrovvalera
Copy link
Copy Markdown
Contributor

@lavrovvalera lavrovvalera commented Apr 30, 2026 •
edited
Loading

score::time — Unified Clock API (new Clock<Tag> framework)

Ref: #9

Summary

Introduces score::time — a unified, tag-based clock API that replaces the
SynchronizedVehicleTime and HighPrecisionLocalSteadyClock class hierarchies with a
single, scalable template wrapper Clock<Tag>. All four clock domains (vehicle time,
HPLS, steady, system) are accessible through the same call pattern. Legacy packages are
marked deprecated and will be removed once TimeDaemon consumers have migrated.

Motivation

The existing API had several pain points across safe-posix-platform and ddad consumers:

  • Two unrelated APIs — SynchronizedVehicleTime::FactoryImpl and
    HighPrecisionLocalSteadyClock::FactoryImpl had completely different construction patterns.
  • Factory injection in SUTs — components took factory objects as constructor parameters,
    requiring test-specific constructor signatures.
  • Mutable TimeStatus snapshot — public data members, raw-uint64_t constructors, and
    non-const accessors triggered Coverity M11-0-1 suppressions.
  • Four named callback methods — Set*/Unset* for each PTP event type; no generic
    subscription pattern.
  • No steady_clock / system_clock unification — callers mixed std::chrono clocks and
    BMW-specific clocks with incompatible APIs.

Changes

New framework — score/time/clock/

Header Purpose
clock.h Clock<Tag> value wrapper — Now(), Subscribe<E>(), IsAvailable(), GetInstance()
clock_traits.h ClockTraits<Tag> primary template + std::chrono specialisations
clock_override_guard.h ClockOverrideGuard<Tag> RAII guard for test mock injection
clock_snapshot.h ClockSnapshot<TimepointT, StatusT> immutable two-field snapshot
clock_status.h ClockStatus<FlagEnumT> bit-flag status utility
no_status.h NoStatus empty placeholder for always-ready clocks
subscription_hook.h SubscriptionHook<Tag, E> extension point for PTP callbacks
availability_hook.h AvailabilityHook<Tag> extension point for async readiness

New clock domains

Package Bazel target Description
score/time/vehicle_time/ :vehicle_time / :vehicle_time_mock / :interface PTP-synchronized vehicle time
score/time/hpls_time/ :hpls_time / :hpls_time_mock / :interface High-Precision Local Steady Clock
score/time/steady_time/ :steady_time / :steady_time_mock / :interface std::chrono::steady_clock wrapper
score/time/system_time/ :system_time / :system_time_mock / :interface std::chrono::system_clock wrapper
score/time/ptp/ :ptp_types TimeSlaveSyncData<Tag>, PDelayMeasurementData<Tag>

Visibility hardening

  • Internal targets (*_clock, *_clock_iface, *_clock_impl, *_clock_mock,
    clock_core) restricted to //score/time:__subpackages__.
  • Three named public aliases per domain: :vehicle_time (prod), :vehicle_time_mock
    (test), :interface (header-only).
  • examples/time/ aggregation moved to its own //examples/time:unit_test_suite; no longer
    referenced from //score/time:unit_test_suite.

Examples — examples/time/

Four self-contained examples (one per domain) demonstrating polling, status checks, and
callback registration. Handler filenames match class names
(vehicle_time_handler.h / VehicleTimeHandler, etc.).

Legacy deprecation

score/time/SynchronizedVehicleTime/BUILD and score/time/HighPrecisionLocalSteadyClock/BUILD
retain a DEPRECATED comment block and carry deprecation = "..." on their alias targets
so any target that still depends on them receives a Bazel analysis-time warning. Both packages
are kept until score/TimeDaemon/ consumers complete migration.

Documentation — docs/time/

New Sphinx RST documentation for the score::time API, with six use-case sections and five
PlantUML sequence/class diagrams. The former docs/time/ (TimeDaemon architecture) is
renamed to docs/TimeDaemon/.

API example

// Production code — no factory, no constructor injection
auto clock = score::time::VehicleClock::GetInstance();
if (clock.IsAvailable()) {
    auto snap = clock.Now();
    if (snap.Status().IsSynchronized()) {
        UseTime(snap.TimePoint());
    }
}

// Unit test — RAII mock injection, SUT unchanged
auto mock = std::make_shared<score::time::VehicleTimeMock>();
score::time::ClockOverrideGuard<score::time::VehicleTime> guard{mock};
EXPECT_CALL(*mock, Now()).WillOnce(Return(snapshot));
MySvc svc{};  // calls GetInstance() internally — gets mock

@github-project-automation github-project-automation Bot moved this to In Progress in TIM - Time FT Apr 30, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 30, 2026 •
edited
Loading

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //:license-check

Status: ⚠️ Needs Review

Click to expand output 
[License Check Output]
2026/05/02 20:43:23 Downloading https://releases.bazel.build/8.3.0/release/bazel-8.3.0-linux-x86_64...
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: c452ad9e-ba85-4240-af45-a0530ba63e71
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
WARNING: For repository 'aspect_rules_lint', the root module requires module version aspect_rules_lint@1.5.3, but got aspect_rules_lint@2.0.0 in the resolved dependency graph. Please update the version in your MODULE.bazel or set --check_direct_dependencies=off
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 2 packages loaded
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
Loading: 2 packages loaded
    currently loading: 
WARNING: Download from https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz failed: class java.io.IOException GET returned 502 Bad Gateway or Proxy Error
INFO: Repository aspect_rules_lint+ instantiated at:
  <builtin>: in <toplevel>
Repository rule http_archive defined at:
  /home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl:394:31: in <toplevel>
ERROR: /home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl:139:45: An error occurred during the fetch of repository 'aspect_rules_lint+':
   Traceback (most recent call last):
	File "/home/runner/.bazel/external/bazel_tools/tools/build_defs/repo/http.bzl", line 139, column 45, in _http_archive_impl
		download_info = ctx.download_and_extract(
Error in download_and_extract: java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
WARNING: Target pattern parsing failed.
ERROR: Skipping '//:license-check': no such package '@@aspect_rules_lint+//format': java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
ERROR: no such package '@@aspect_rules_lint+//format': java.io.IOException: Error downloading [https://github.com/aspect-build/rules_lint/releases/download/v2.0.0/rules_lint-v2.0.0.tar.gz] to /home/runner/.bazel/external/aspect_rules_lint+/temp15498933779504688265/rules_lint-v2.0.0.tar.gz: GET returned 502 Bad Gateway or Proxy Error
INFO: Elapsed time: 35.201s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 30, 2026

The created documentation from the pull request is available at: docu-html

@BlueXMarv3l BlueXMarv3l requested a review from Copilot May 6, 2026 10:21
Copilot AI reviewed May 6, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces the new score::time unified, tag-based clock framework (Clock<Tag>) and migrates TimeDaemon and related components away from the legacy SynchronizedVehicleTime / HighPrecisionLocalSteadyClock APIs toward the new vehicle_time and hpls_time domains. It also adds steady_time and system_time domains, PTP structural types, examples, and extensive PlantUML/Sphinx documentation updates.

Changes:

  • Migrate TimeDaemon SVT verification/ptp stub code to use score::time::HplsClock (new Clock<Tag> API) instead of the legacy HPLSC factory/unique_ptr model.
  • Add new clock domains and core framework pieces (score/time/clock/*, vehicle_time, steady_time, system_time, ptp), including mocks/stubs and unit tests.
  • Remove legacy SynchronizedVehicleTime and HighPrecisionLocalSteadyClock implementation files and update documentation structure/diagrams.

Reviewed changes

Copilot reviewed 185 out of 215 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
score/TimeDaemon/code/verification_machine/svt/validators/timeout_validator.h Switch validator to value-type ReferenceClock and new snapshot API.
score/TimeDaemon/code/verification_machine/svt/validators/timeout_validator.cpp Use ClockSnapshot accessors (TimeSinceEpoch) instead of time_since_epoch().
score/TimeDaemon/code/verification_machine/svt/validators/timeout_validator_test.cpp Update tests to use HplsClockMock and ClockTestFactory.
score/TimeDaemon/code/verification_machine/svt/validators/time_jumps_validator.h Switch validator to value-type ReferenceClock.
score/TimeDaemon/code/verification_machine/svt/validators/time_jumps_validator.cpp Update time reads to new snapshot API.
score/TimeDaemon/code/verification_machine/svt/validators/time_jumps_validator_test.cpp Update tests to new HPLS clock mock/snapshot types.
score/TimeDaemon/code/verification_machine/svt/validators/BUILD Replace legacy HPLSC deps with hpls_time interface/mock targets.
score/TimeDaemon/code/verification_machine/svt/factory.cpp Construct validators using HplsClock::GetInstance() instead of legacy factory.
score/TimeDaemon/code/verification_machine/svt/BUILD Add hpls_time_mock to SVT test deps.
score/TimeDaemon/code/ptp_machine/stub/gptp_stub_machine_integration_test.cpp Migrate integration test timing to HplsClock.
score/TimeDaemon/code/ptp_machine/stub/factory.cpp Build stub machine with HplsClock::GetInstance().
score/TimeDaemon/code/ptp_machine/stub/details/stub_ptp_engine.h Switch engine clock member from unique_ptr to ReferenceClock value.
score/TimeDaemon/code/ptp_machine/stub/details/stub_ptp_engine.cpp Use ClockSnapshot accessors to fill PtpTimeInfo.
score/TimeDaemon/code/ptp_machine/stub/details/BUILD Replace legacy HPLSC interface dep with hpls_time:interface.
score/TimeDaemon/code/ptp_machine/stub/BUILD Swap legacy HPLSC targets for hpls_time prod/mock targets.
score/TimeDaemon/code/ptp_machine/core/BUILD Replace legacy HPLSC dep with hpls_time:interface.
score/TimeDaemon/code/ipc/svt/svt_time_info.h Drop now-unneeded legacy HPLSC include from IPC snapshot types.
score/TimeDaemon/code/ipc/BUILD Adjust visibility from legacy SVT packages to new vehicle_time td_impl pkg.
score/TimeDaemon/code/common/data_types/ptp_time_info.h Redefine ReferenceClock as score::time::HplsClock.
score/TimeDaemon/code/common/data_types/BUILD Update deps to hpls_time:interface.
score/time/vehicle_time/vehicle_clock.cpp Implement VehicleTime hooks/traits wiring into backend iface.
score/time/vehicle_time/vehicle_clock_iface.h Add internal backend interface for VehicleTime domain.
score/time/vehicle_time/details/td_impl/BUILD Add TimeDaemon-backed production impl build targets and tests.
score/time/vehicle_time/details/stub_impl/vehicle_clock_impl.h Add stub backend returning safe defaults.
score/time/vehicle_time/details/stub_impl/vehicle_clock_impl.cpp Provide CreateBackend<VehicleTime>() stub specialization.
score/time/vehicle_time/details/stub_impl/BUILD Build target for VehicleTime stub backend.
score/time/vehicle_time/details/logging_contexts.h Introduce VehicleTime log context header (and add include guards).
score/time/vehicle_time/details/BUILD Aggregate VehicleTime detail test suites.
score/time/system_time/system_clock.h Add SystemClock domain (Clock<std::chrono::system_clock>).
score/time/system_time/system_clock.cpp Implement ClockTraits<std::chrono::system_clock>::CallNow.
score/time/system_time/system_clock_mock.h Add gmock backend for SystemClock.
score/time/system_time/system_clock_iface.h Add backend iface contract for SystemClock.
score/time/system_time/details/system_time_impl/system_clock_impl.h Add production backend calling std::chrono::system_clock::now().
score/time/system_time/details/system_time_impl/system_clock_impl.cpp Provide CreateBackend<std::chrono::system_clock>() specialization.
score/time/system_time/details/system_time_impl/system_clock_impl_test.cpp Unit tests for SystemClock production backend.
score/time/system_time/details/system_time_impl/BUILD Build rules for system_time production backend + tests.
score/time/system_time/details/stub_impl/system_clock_impl.h Add stub backend for tests (epoch-zero snapshots).
score/time/system_time/details/stub_impl/system_clock_impl.cpp Provide stub CreateBackend<std::chrono::system_clock>().
score/time/system_time/details/stub_impl/BUILD Build rules for system_time stub backend.
score/time/system_time/details/BUILD Aggregate system_time detail test suites.
score/time/SynchronizedVehicleTime/synchronized_vehicle_time.cpp Remove legacy SVT implementation source.
score/time/SynchronizedVehicleTime/synchronized_vehicle_time_mock.h Remove legacy SVT mock header.
score/time/SynchronizedVehicleTime/slave_timebase_notification_types.cpp Remove legacy SVT notification types TU.
score/time/SynchronizedVehicleTime/factory.h Remove legacy SVT factory interface.
score/time/SynchronizedVehicleTime/factory_mock.h Remove legacy SVT factory mock.
score/time/SynchronizedVehicleTime/details/tdr/factory_impl_test.cpp Remove legacy SVT factory impl tests.
score/time/SynchronizedVehicleTime/details/logging_contexts.h Remove legacy SVT logging contexts header.
score/time/SynchronizedVehicleTime/details/factory_shm_impl.h Remove legacy SVT shm factory impl.
score/time/SynchronizedVehicleTime/details/factory_mock_helper.h Remove legacy static factory mock helper.
score/time/SynchronizedVehicleTime/details/factory_impl.h Remove legacy SVT factory impl header.
score/time/SynchronizedVehicleTime/details/clock_realtime/factory_impl.cpp Remove legacy realtime SVT factory impl TU.
score/time/SynchronizedVehicleTime/details/clock_realtime/factory_impl_test.cpp Remove legacy realtime SVT factory impl tests.
score/time/SynchronizedVehicleTime/details/clock_realtime/clock_provider.cpp Remove legacy realtime SVT clock provider TU.
score/time/steady_time/steady_clock.h Add SteadyClock domain (Clock<std::chrono::steady_clock>).
score/time/steady_time/steady_clock.cpp Implement ClockTraits<std::chrono::steady_clock>::CallNow.
score/time/steady_time/steady_clock_mock.h Add gmock backend for SteadyClock.
score/time/steady_time/steady_clock_iface.h Add backend iface contract for SteadyClock.
score/time/steady_time/details/stub_impl/steady_clock_impl.h Add stub backend for SteadyClock tests.
score/time/steady_time/details/stub_impl/steady_clock_impl.cpp Provide stub CreateBackend<std::chrono::steady_clock>().
score/time/steady_time/details/stub_impl/BUILD Build rules for steady_time stub backend.
score/time/steady_time/details/steady_time_impl/steady_clock_impl.h Add production backend calling std::chrono::steady_clock::now().
score/time/steady_time/details/steady_time_impl/steady_clock_impl.cpp Provide CreateBackend<std::chrono::steady_clock>() specialization.
score/time/steady_time/details/steady_time_impl/steady_clock_impl_test.cpp Unit tests for steady_time production backend.
score/time/steady_time/details/steady_time_impl/BUILD Build rules for steady_time production backend + tests.
score/time/steady_time/details/BUILD Aggregate steady_time detail test suites.
score/time/ptp/time_slave_sync_data_test.cpp Add unit test for TimeSlaveSyncData streaming/PrintTo.
score/time/ptp/port_identity.h Add PortIdentity type with stream formatting helpers.
score/time/ptp/pdelay_measurement_data_test.cpp Add unit test for PDelayMeasurementData streaming/PrintTo.
score/time/ptp/master_ptp_device_timer.h Define master device timer tag + time_point alias.
score/time/ptp/local_ptp_device_timer.h Define local device timer tag + time_point alias.
score/time/ptp/BUILD Add ptp_types library and unit tests + suite.
score/time/hpls_time/test/benchmark/BUILD Rename benchmark target and swap deps to new hpls_time target.
score/time/hpls_time/test/benchmark/benchmark.cpp Update benchmark to call HplsClock::Now() via new API.
score/time/hpls_time/hpls_time.h Define HplsTime tag (duration/timepoint).
score/time/hpls_time/hpls_clock.h Add HplsClock domain (Clock<HplsTime>) traits.
score/time/hpls_time/hpls_clock.cpp Implement ClockTraits<HplsTime>::CallNow.
score/time/hpls_time/hpls_clock_mock.h Add gmock backend for HplsClock + test utilities integration.
score/time/hpls_time/hpls_clock_iface.h Add backend iface contract for HplsClock.
score/time/hpls_time/details/system_clock/hpls_time_impl.h Add non-QNX production backend for HplsTime.
score/time/hpls_time/details/system_clock/hpls_time_impl.cpp Provide CreateBackend<HplsTime>() specialization for non-QNX backend.
score/time/hpls_time/details/system_clock/hpls_time_impl_test.cpp Update/rename tests for new HplsTimeImpl backend.
score/time/hpls_time/details/system_clock/BUILD Build rules for non-QNX backend and unit tests.
score/time/hpls_time/details/stub_impl/hpls_clock_impl.h Add test-only stub backend for HplsTime.
score/time/hpls_time/details/stub_impl/hpls_clock_impl.cpp Provide stub CreateBackend<HplsTime>().
score/time/hpls_time/details/stub_impl/BUILD Replace prior content with stub backend build rules.
score/time/hpls_time/details/qtime/tick_provider.h Rename/move QNX tick provider API under new namespace/guards.
score/time/hpls_time/details/qtime/tick_provider.cpp Update tick provider implementation include/namespace.
score/time/hpls_time/details/qtime/tick_provider_test.cpp Update tick provider test namespaces and assertions.
score/time/hpls_time/details/qtime/tick_provider_mock.h Add singleton mock wrapper for QNX tick provider.
score/time/hpls_time/details/qtime/tick_provider_mock.cpp Provide mock-routed GetClockCyclesPerSec() and static storage.
score/time/hpls_time/details/qtime/hpls_qclock.h Add QNX production backend for HplsTime.
score/time/hpls_time/details/qtime/hpls_qclock.cpp Implement QNX backend and CreateBackend<HplsTime>().
score/time/hpls_time/details/qtime/factory_test.cpp Add factory test for QNX backend creation.
score/time/hpls_time/details/BUILD Add hpls_time details test suite aggregation and QNX test suites.
score/time/HighPrecisionLocalSteadyClock/high_precision_local_steady_clock.h Remove legacy HPLSC interface header.
score/time/HighPrecisionLocalSteadyClock/high_precision_local_steady_clock_mock.h Remove legacy HPLSC mock header.
score/time/HighPrecisionLocalSteadyClock/high_precision_local_steady_clock_mock.cpp Remove legacy HPLSC mock implementation TU.
score/time/HighPrecisionLocalSteadyClock/factory.h Remove legacy HPLSC factory interface header.
score/time/HighPrecisionLocalSteadyClock/factory_mock.h Remove legacy HPLSC factory mock header.
score/time/HighPrecisionLocalSteadyClock/details/system_clock/system_clock.h Remove legacy system_clock backend header.
score/time/HighPrecisionLocalSteadyClock/details/qtime/tick_provider_mock.h Remove legacy tick provider mock header.
score/time/HighPrecisionLocalSteadyClock/details/qtime/qclock.h Remove legacy QNX qclock header.
score/time/HighPrecisionLocalSteadyClock/details/qtime/qclock.cpp Remove legacy QNX qclock implementation TU.
score/time/HighPrecisionLocalSteadyClock/details/factory_impl.h Remove legacy factory implementation header.
score/time/HighPrecisionLocalSteadyClock/details/factory_impl_stub.cpp Remove legacy utest factory stub TU.
score/time/HighPrecisionLocalSteadyClock/details/BUILD Remove legacy HPLSC details build definitions.
score/time/HighPrecisionLocalSteadyClock/BUILD Remove legacy HPLSC package build definitions.
score/time/clock/subscription_hook.h Add subscription SFINAE hook for event subscription.
score/time/clock/no_status.h Define NoStatus placeholder status type.
score/time/clock/clock_traits.h Add ClockTraits<Tag> primary template.
score/time/clock/clock_test_factory.h Add test-only factory for constructor-injected clocks.
score/time/clock/clock_snapshot.h Add immutable snapshot type with helper accessors.
score/time/clock/BUILD Add clock core + test utilities build targets and unit tests.
score/time/clock/availability_hook.h Add availability SFINAE hook + HasAvailability trait.
score/time/BUILD Add umbrella unit test suite aggregation for all new time packages.
examples/time/system_time/system_time_handler.h Add system_time example handler demonstrating SystemClock.
examples/time/system_time/BUILD Add system_time example binary and handler unit test target.
examples/time/steady_time/steady_time_handler.h Add steady_time example handler demonstrating SteadyClock.
examples/time/steady_time/steady_time_handler_test.cpp Add steady_time handler unit test using clock override.
examples/time/steady_time/BUILD Add steady_time example binary and tests.
examples/time/hpls_time/hpls_time_handler.h Add hpls_time example handler demonstrating HplsClock.
examples/time/hpls_time/hpls_time_handler_test.cpp Add hpls_time handler unit test using clock override.
examples/time/hpls_time/BUILD Add hpls_time example binary and tests.
examples/time/BUILD Add examples/time unit test suite aggregation.
docs/TimeDaemon/_assets/ver_machine/ver_verification_seq.puml Add VerificationMachine workflow diagram.
docs/TimeDaemon/_assets/ver_machine/ver_init_seq.puml Add VerificationMachine init sequence diagram.
docs/TimeDaemon/_assets/ver_machine/ver_class.puml Add VerificationMachine class diagram.
docs/TimeDaemon/_assets/sad_deployment.puml Add deployment view diagram.
docs/TimeDaemon/_assets/ptp_machine/ptp_machine_init_seq.puml Add PTP machine init sequence diagram.
docs/TimeDaemon/_assets/ptp_machine/ptp_machine_get_new_data_seq.puml Add PTP periodic publish workflow diagram.
docs/TimeDaemon/_assets/ptp_machine/ptp_machine_class.puml Add PTP machine class diagram.
docs/TimeDaemon/_assets/mw/mw_time_receive_simple_seq.puml Add simplified middleware receive diagram.
docs/TimeDaemon/_assets/mw/mw_time_receive_seq.puml Add middleware receive flow diagram.
docs/TimeDaemon/_assets/mw/mw_class.puml Add middleware class diagram.
docs/TimeDaemon/_assets/msg_broker/msg_broker_workflow_seq.puml Add message broker workflow sequence diagram.
docs/TimeDaemon/_assets/msg_broker/msg_broker_init_seq.puml Add message broker init sequence diagram.
docs/TimeDaemon/_assets/msg_broker/msg_broker_class.puml Add message broker class diagram.
docs/TimeDaemon/_assets/ipc/ipc_receive_seq.puml Add IPC receive sequence diagram.
docs/TimeDaemon/_assets/ipc/ipc_publish_seq.puml Add IPC publish sequence diagram.
docs/TimeDaemon/_assets/ipc/ipc_init_seq.puml Add IPC init sequence diagram.
docs/TimeDaemon/_assets/ipc/ipc_class.puml Add IPC class diagram.
docs/TimeDaemon/_assets/examples/qvt/qvt_deployment.puml Add example deployment diagram for QVT.
docs/TimeDaemon/_assets/examples/abs_time/abs_time_deployment.puml Add example deployment diagram for absolute time.
docs/TimeDaemon/_assets/examples/abs_time/abs_time_data_control_flow.puml Add absolute time multi-pipeline flow diagram.
docs/TimeDaemon/_assets/dd_deployment.puml Add baseline deployment diagram.
docs/TimeDaemon/_assets/ctrlflow/ctrlflow_workflow_seq.puml Add control flow divider workflow diagram.
docs/TimeDaemon/_assets/ctrlflow/ctrlflow_init_seq.puml Add control flow divider init diagram.
docs/TimeDaemon/_assets/ctrlflow/ctrlflow_class.puml Add control flow divider class diagram.
docs/TimeDaemon/_assets/app/app_workflow_seq.puml Add app workflow sequence diagram.
docs/TimeDaemon/_assets/app/app_init_seq.puml Add app init sequence diagram.
docs/TimeDaemon/_assets/app/app_class.puml Add app class diagram.
docs/time/_assets/uc_testing.puml Add UC diagram for scope-bound clock override in tests.
docs/time/_assets/uc_subscription.puml Add UC diagram for async PTP event subscription.
docs/time/_assets/uc_polling.puml Add UC diagram for polling with status check.
docs/time/_assets/uc_availability.puml Add UC diagram for availability waiting.
docs/index.rst Update docs index to include new TimeDaemon/ docs path.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/time/_assets/uc_availability.puml
Comment on lines +58 to +62
deactivate clock

note over of app
Only Clock<Tag> domains that require
async init expose IsAvailable().
Comment thread score/TimeDaemon/code/verification_machine/svt/validators/timeout_validator.h
Comment on lines 30 to +34
*/
class TimeoutValidator : public VerificationStage<PtpTimeInfo>
{
public:
explicit TimeoutValidator(std::unique_ptr<PtpTimeInfo::ReferenceClock> timeout_clock,
explicit TimeoutValidator(PtpTimeInfo::ReferenceClock timeout_clock,
BlueXMarv3l
BlueXMarv3l reviewed May 7, 2026
View reviewed changes
Comment thread score/time/vehicle_time/vehicle_clock_test.cpp
EXPECT_TRUE(VehicleClock::GetInstance().WaitUntilAvailable(source.get_token(), until));
}

// ── UC3: Subscribe / Unsubscribe — callback is captured and invocable ─────────
Copy link
Copy Markdown

@BlueXMarv3l BlueXMarv3l May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Subscribe<E>() appears compile-time-safe for unsupported events. Still, I only see clear test coverage for TimeSlaveSyncData<VehicleTime>—please point to equivalent coverage for PDelayMeasurementData<VehicleTime> as well.

BlueXMarv3l
BlueXMarv3l reviewed May 7, 2026
View reviewed changes
Comment thread score/time/system_time/BUILD
Copy link
Copy Markdown

@BlueXMarv3l BlueXMarv3l May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VehicleTime, HplsClock, SteadyClock, and SystemClock currently look like peers under one unified API, but in automotive use, they serve very different purposes. SteadyClock is typically just a local monotonic source for timeout/debounce/duration logic and often does not need daemon/service involvement at all(often stdlib is enough); SystemClock is even less equivalent, since absolute time usually comes from RTC/GNSS/NTP/backend sync and cannot guarantee monotonic/no-leap behavior. From the likely automotive use cases, do we really need these wrappers inside the TimeDaemon?

BjoernAtBosch
BjoernAtBosch reviewed May 7, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically, I like this "unified API" approach.
Unfortunately, I'm not fully through all this. Some general questions I still have in my mind:

  • Would we need further time bases besides the ones predefined here? And should they be runtime configurable?
  • How do we assume that syncing the system_clock is done? Via NTP?

More to come maybe - need to step out for today ...

Comment thread docs/time/index.rst
+===========================+==============================================================+
| ``kSynchronized`` | Synchronized at least once to the PTP Grand Master |
+---------------------------+--------------------------------------------------------------+
| ``kSynchToGateway`` | Currently in sync with the PTP gateway |
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this state required (in comparison to kSynchronized)?

Comment thread docs/time/index.rst
+---------------------------+--------------------------------------------------------------+
| ``kTimeLeapPast`` | A large backward adjustment was applied |
+---------------------------+--------------------------------------------------------------+
| ``kUnknown`` | Status cannot be determined |
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we have a state kNotSynchonizedDueToStartup like it's defined in AUTOSAR?

Comment thread docs/time/index.rst
Comment on lines +304 to +309
UC5 — HPLSC as reference steady clock
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. raw:: html

<div style="overflow-x: auto; max-width: 100%;">

.. uml:: _assets/examples/qvt/qvt_deployment.puml
:alt: Deployment view

.. raw:: html
``HplsClock`` (High-Precision Local Steady Clock) is a monotonic clock that provides
nanosecond-resolution time without any PTP dependency. It has **no status** — it is always
ready.
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer resolution over precision because the term precision is already occupied (like in "precision time protocol") for how precise the frequency (and deviation) of a clock is in sync with a certain/ideal clock. Which is different of how fine-granular the time can be measured. Also, this is the term used in the C++ stdlib (std::high_resolution_clock).

I'd also prefer another ordering - especially the term local should be moved:

  • local steady high-precision clock
  • high-precison steady local clock
  • local high-precision steady clock

Comment thread docs/time/index.rst
The design separates three concerns:

More precisely we can specify the following use cases for the time daemon:
1. **What kind of time** — expressed as a *tag struct* (``VehicleTime``, ``HplsTime``,
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"What kind of time": Initially, I was thinking that a clock would be defined by aspects like epoch, resolution, precision and so on, e.g. VehicleTime's epoch is start of vehicle's current power cycle and SystemTime's epoch is Unix epoch.
But I think, it's more the purpose or use cases, that define a certain type of clock. For example, in theory the epochs of VehicleTime and SystemTime could be the same (if someone could guarantee reliable sync with UTC/TAI). The difference between both are the requirements/use cases:
VehicleTime must be highly (and fast) available and shall be steady and precise. It's epoch and validity to the outside world of the vehicle is irrelevant.
SystemTime/"WorldTime" is a bit opposite: It's used for syncing events with things outside the vehicle. Its availability cannot be guaranteed.
This is not necessarily a finding, but more "wrapping up" some thinking. (Still learning ;-))

Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've some findings regarding the naming and meanings:

  • Imho HplsTime should be changed (see finding below), but besides I have some doubts about its meaning: I think you defined it as an alternative to C++'s std::high_resolution_clock because you're unhappy (as me also) with it's unclear definition (is it steady or not?). The potential difficulty of our own definition will be its mapping: If you just map it to std::high_resolution_clock you'll have the same issue again. If you'd map it to std::steady_clock you can't guarantee the high resolution". (My observation under WSL Linux is that the high resolution clock is mapped to std::system_clock.)
  • system_clock: Is basically fine - it represents the local clock of the S-CORE underlying OS. But with that it will most probably represent unix time, which has the issue of ignoring possible leap seconds; ignoring means that in case of a leap second the same second will "show up" twice in unix time, i.e. it has the same representation as the second before the leap second. Whereas in UTC or TAI each second in time is clearly separable. I'm not sure if this could lead to issues in cases "worldwide" ordering of events.
  • Question is if we need something like "GlobalTime" or explicitly TAI or UTC? This is also about the naming - system_time is somehow unspecific: Is it the time of the local S-CORE based system? Or the of the "vehicle system"? I mean, because of the std::system_clock it should be quite clear. But how does s.o. know that it is sync (or not) with a global time master?

Comment thread docs/time/index.rst
``{kTimeOut, kTimeLeapFuture, kTimeLeapPast}`` is set.

</div>
UC2 — Availability waiting at startup
Copy link
Copy Markdown
Contributor

@BjoernAtBosch BjoernAtBosch May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if we need the separated availability handling or if that could be solved via sync state kNotSynchonizedDueToStartup

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

+2 more reviewers

@BjoernAtBosch BjoernAtBosch BjoernAtBosch left review comments

@BlueXMarv3l BlueXMarv3l BlueXMarv3l left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

TIM - Time FT
Status: In Progress

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@lavrovvalera @BjoernAtBosch @BlueXMarv3l