Prepare the new score::time API by lavrovvalera · Pull Request #18 · eclipse-score/inc_time

lavrovvalera · 2026-04-30T07:40:44Z

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

closes: #31
closes: #26
closes: #13

Summary

Introduces score::time — a unified, tag-based clock API built around a single scalable
template wrapper Clock<Tag>. Automotive domains (vehicle time, HPLS) and standard library
wrappers (std::chrono::steady_clock, std::chrono::system_clock) share the same call
pattern and test infrastructure. Additional domains can be added by specializing
ClockTraits<Tag>.

Motivation

Fragmented APIs — each clock domain had its own unrelated construction pattern.
No mockable std::chrono wrapper — unit tests required manual per-component adapters.
Factory injection in SUTs — test doubles needed factory objects as constructor
parameters, leaking test concerns into production code.
Mutable snapshots — public data members and non-const accessors triggered static
analysis suppressions.

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_snapshot.h`	`ClockSnapshot<TimepointT, StatusT>` immutable snapshot
`clock_status.h`	`ClockStatus<FlagEnumT>` bit-flag status utility
`no_status.h`	`NoStatus` 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
`scoped_clock_override.h`	`test_utils::ScopedClockOverride<Tag>` RAII mock injection
`clock_test_factory.h`	`test_utils::ClockTestFactory<Tag>` constructor-injection helper

New clock domains

Package	Public Bazel targets	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>`

Bazel structure and visibility

Each domain uses a two-level layout: <domain>/src/BUILD owns all definitions; the root
<domain>/BUILD exposes only thin alias targets.

src:*_clock — domain bundle (backend interface + tag type + Clock<Tag> specialisation); visibility //score/time:__subpackages__
src:*_clock_mock — GMock test double; //visibility:public
src:*_clock_impl — production wiring (select over platform backends); //visibility:public

Three named public aliases per domain: :*_time (prod), :*_time_mock (test), :interface (header-only).

Legacy removal

score/time/SynchronizedVehicleTime/ and score/time/HighPrecisionLocalSteadyClock/ have
been removed. TimeDaemon consumers must migrate to the new domain packages.

Documentation

Sphinx RST documentation added under docs/time/. The former docs/time/ (TimeDaemon
architecture) is moved to docs/TimeDaemon/.

API example

// Production — no factory, no constructor injection
auto snap = score::time::VehicleClock::GetInstance().Now();
if (snap.Status().IsSet(VehicleTime::StatusFlag::kSynchronized)) {
    UseTime(snap.TimePoint());
}

// Test — RAII override (SUT calls GetInstance() internally)
auto mock = std::make_shared<VehicleClockBackendMock>();
test_utils::ScopedClockOverride<VehicleTime> guard{mock};
EXPECT_CALL(*mock, Now()).WillOnce(Return(snapshot));
MySvc svc{};

// Test — constructor injection (no global state)
auto mock  = std::make_shared<HplsClockBackendMock>();
auto clock = test_utils::ClockTestFactory<HplsTime>::Make(mock);
MyComponent component{clock};
EXPECT_CALL(*mock, Now()).WillOnce(Return(snapshot));

github-actions · 2026-04-30T07:41:44Z

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]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 0ddb7145-e26d-4c54-8e7e-02cc72d0f470
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: 
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: 
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: 
Analyzing: target //:license-check (3 packages loaded)
Analyzing: target //:license-check (3 packages loaded, 0 targets configured)
Analyzing: target //:license-check (3 packages loaded, 0 targets configured)

Analyzing: target //:license-check (79 packages loaded, 9 targets configured)

Analyzing: target //:license-check (148 packages loaded, 2654 targets configured)

Analyzing: target //:license-check (158 packages loaded, 7961 targets configured)

Analyzing: target //:license-check (159 packages loaded, 7996 targets configured)

Analyzing: target //:license-check (159 packages loaded, 7996 targets configured)

Analyzing: target //:license-check (169 packages loaded, 8049 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (172 packages loaded, 9937 targets configured)

Analyzing: target //:license-check (173 packages loaded, 10057 targets configured)

INFO: Analyzed target //:license-check (174 packages loaded, 10184 targets configured).
[9 / 16] checking cached actions
[11 / 16] checking cached actions
INFO: From Generating Dash formatted dependency file ...:
INFO: Successfully converted 2 packages from Cargo.lock to bazel-out/k8-fastbuild/bin/formatted.txt
[14 / 16] checking cached actions
[14 / 16] JavaToolchainCompileBootClasspath external/rules_java+/toolchains/platformclasspath.jar; 0s disk-cache, processwrapper-sandbox
INFO: Found 1 target...
Target //:license.check.license_check up-to-date:
  bazel-bin/license.check.license_check
  bazel-bin/license.check.license_check.jar
INFO: Elapsed time: 48.132s, Critical Path: 2.29s
INFO: 16 processes: 12 internal, 3 processwrapper-sandbox, 1 worker.
INFO: Build completed successfully, 16 total actions
INFO: Running command line: bazel-bin/license.check.license_check ./formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

github-actions · 2026-04-30T07:44:43Z

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

Copilot

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.

BjoernAtBosch

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 ...

BjoernAtBosch · 2026-05-07T09:57:35Z

+===========================+==============================================================+
+| ``kSynchronized``         | Synchronized at least once to the PTP Grand Master           |
+---------------------------+--------------------------------------------------------------+
+| ``kSynchToGateway``       | Currently in sync with the PTP gateway                       |


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

it is the mirroring form autosar TIMEBASE_STATUS_SYNC_TO_GATEWAY
and means if we are synchronized to the gateway in current frame or not
its more infomrational flag

Would this then be relevant for the Abs/GlobalTime, only? Meaning: The local global clock is synced with the in-vehicle "master" but not with the grandmaster outside?
Would be not relevant for the vehicle time then.
But then the description should be different, e.g.: Currently in sync with the vehicle local master
I'd also not reference the term PTP here, as it is a specific protocol which could change over time whereas the generic concept should be stable

BjoernAtBosch · 2026-05-07T09:58:50Z

+---------------------------+--------------------------------------------------------------+
+| ``kTimeLeapPast``         | A large backward adjustment was applied                      |
+---------------------------+--------------------------------------------------------------+
+| ``kUnknown``              | Status cannot be determined                                  |


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

but what is the difference between it and Timeout then?
it might be needed on diagnostic side, but then th ediagnostic shall keep track on it or?

kNotSynchonizedDueToStartup no sync yet at all - local time might be completely unrelated to master
kTimeout tells there was a sync in the past, but last successful sync is long ago

BjoernAtBosch · 2026-05-07T13:48:41Z

+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``,


"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 ;-))

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?

My idea was the following: API shall represent the following groups of time i nthe system:

VehicleTime - to access ptp time with its status

Localsystem time, usually accessed through std::chrono: std::system_time, std::steady_time

AbsTime - to access the Global UTC time including the preceision and security qualifiers.

Hight resolution steady clock - to access asil-b steady high resolsution cloclk

1 and 3 are external synchronized, the rest - local clock.

lets sync on the weekly meeting and talk about the proper namings and gaps

Yes - clear so far. But in the end all those clocks are local. But some of them are synced and some are not: VehicleTime and AbsTime shall be synced, but the local users of it just see a local representation of that time bases. Things like PTP are just a medium to enable the syncing process, but there could be others.

The local system time could also be synced and represent the same time as the AbsTime (maybe w/o handling leap seconds). From that point of perspective I even more appreciate this abstract clock concept, because it would allow to put the syncing info also to the system_time.

BjoernAtBosch · 2026-05-07T14:12:15Z

+``{kTimeOut, kTimeLeapFuture, kTimeLeapPast}`` is set.

-   </div>
+UC2 — Availability waiting at startup


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

that has different meaning:
in autosar and here it might be needed to initialize somehting liek ipc
in case the ipc or daemon will no tbe initialize, we jsut don't know anything about the state.
and here isAvailable is responsible exactly for that - is the timebase (with any status) already available or not. It could be treated like "was it initilaized succeefully already".

maybe we could think about renaming of course.

Hmh - yes, but that makes the handling more complicated for users: They need to check multiple things now. And I guess initialization of ipc is something which should be hidden and expect to normally work. Means, imho the availability state would be info relevant during development but not later and could be handled by logging means.

BjoernAtBosch · 2026-05-28T15:52:57Z

+class ClockStatus final
+{
+    static_assert(std::is_enum<FlagEnumT>::value, "FlagEnumT must be an enum");
+    using StatusFlagT = std::underlying_type_t<FlagEnumT>;


I think, this is not correct: The StatusFlagT needs to be an int type which has a number of bits >= max. enum value +1. I don't know if that's feasible with C++.

BjoernAtBosch · 2026-05-28T16:00:47Z

+        kTimeOut        = 0U, /*!< TB was not synchronized within a certain time frame. */
+        kSynchronized   = 1U, /*!< The TB was synchronized at least once. */
+        kSynchToGateway = 2U, /*!< The TB is in sync with the gateway. */
+        kTimeLeapFuture = 3U, /*!< An adjustment greater than a certain threshold has been made. */
+        kTimeLeapPast   = 4U, /*!< An adjustment back in time greater than a certain threshold has been made. */
+        kUnknown        = 7U  /*!< Unknown status. */


I'm not sure if we should handle all these states via separate flags (booleans). For example the time leaps: There could be only one flag set or none, but not both. BTW: shall we add flags for the situation, when rate adaption is active?

I mean, I see the advantage of this generic definition of flags, but not sure if it fits well for cases where a "flag" can have more than two states.

We should also define, what the behavior is if an app calls Now() - once before and once after a time leap:

Is one of the time leap flags set on the second call?

What happens on a third call? Is the flag cleared then?

Should there be a way apps could query the "size" of the time leap?

BjoernAtBosch · 2026-05-29T07:19:08Z

+                                  VehicleTime::StatusFlag::kTimeLeapFuture,
+                                  VehicleTime::StatusFlag::kTimeLeapPast})));


Why does a time leap in the (near) past mean that the clock is not synced?

BjoernAtBosch · 2026-05-29T07:22:06Z

+    if (IsFlagActive(VehicleTime::StatusFlag::kTimeLeapFuture) &&
+        IsFlagActive(VehicleTime::StatusFlag::kTimeLeapPast))


Same here: Why does a time leap contradict validity?

BjoernAtBosch · 2026-05-29T07:24:49Z

+template <>
+inline bool ClockStatus<VehicleTime::StatusFlag>::IsValid() const noexcept
+{
+    if (IsFlagActive(VehicleTime::StatusFlag::kUnknown))


I'd prefer something more concrete than unkown: Would that state represent internal errors? Then we should name it that way - or at least give a hint in the description.

Rename HighPrecisionLocalSteady clock to HIResolutionSteady Time

- IsSynchronized -> IsReliable - added HasBeenSynchronized - IsValid -> IsConsistent

- Added the hook to the timebases, which needs to be initialized - Moved the VehcileTime initialization to the dedicated method - Adjust examples and docs

- fix name files - fix formatiing - remove unneccessary comments

github-project-automation Bot added this to TIM - Time FT Apr 30, 2026

github-project-automation Bot moved this to In Progress in TIM - Time FT Apr 30, 2026

lavrovvalera had a problem deploying to workflow-approval April 30, 2026 07:40 — with GitHub Actions Failure

lavrovvalera force-pushed the vala_time_gen_api branch from efabbd2 to def162d Compare April 30, 2026 12:42

lavrovvalera had a problem deploying to workflow-approval April 30, 2026 12:43 — with GitHub Actions Failure

lavrovvalera force-pushed the vala_time_gen_api branch from def162d to 64adae9 Compare April 30, 2026 14:39

lavrovvalera had a problem deploying to workflow-approval April 30, 2026 14:39 — with GitHub Actions Failure

lavrovvalera force-pushed the vala_time_gen_api branch from 64adae9 to ea3b132 Compare April 30, 2026 14:40

lavrovvalera had a problem deploying to workflow-approval April 30, 2026 14:40 — with GitHub Actions Failure

lavrovvalera temporarily deployed to workflow-approval May 2, 2026 20:43 — with GitHub Actions Inactive

BlueXMarv3l requested a review from Copilot May 6, 2026 10:21

Copilot started reviewing on behalf of BlueXMarv3l May 6, 2026 10:22 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread docs/time/_assets/uc_availability.puml Outdated

Comment thread score/TimeDaemon/code/verification_machine/svt/validators/timeout_validator.h

BlueXMarv3l reviewed May 7, 2026

View reviewed changes

Comment thread score/time/vehicle_time/vehicle_clock_test.cpp Outdated

BlueXMarv3l reviewed May 7, 2026

View reviewed changes

Comment thread score/time/system_time/BUILD

BjoernAtBosch reviewed May 7, 2026

View reviewed changes

lavrovvalera temporarily deployed to workflow-approval May 19, 2026 09:01 — with GitHub Actions Inactive

lavrovvalera force-pushed the vala_time_gen_api branch from dd6f65e to 865aba1 Compare May 21, 2026 13:25

lavrovvalera requested a deployment to workflow-approval May 21, 2026 13:25 — with GitHub Actions Waiting

lavrovvalera commented May 21, 2026

View reviewed changes

Comment thread docs/time/_assets/architecture_layers.puml

lavrovvalera requested a deployment to workflow-approval May 25, 2026 10:06 — with GitHub Actions Waiting

lavrovvalera added 8 commits May 28, 2026 17:35

Add the new score::time API

f6da2a8

Update documentaiton

f1965ba

Remove the legacy time bases

fc7f34b

Refactor mock targets and objects

d2e6c5a

Fix review comments

2c0d3d6

Adapt folder structure as per SCORE rules

38e3103

rename backend files and bazel targets

01e4ae4

Fix build after rebasing

d7795e0

lavrovvalera force-pushed the vala_time_gen_api branch from 277042e to d7795e0 Compare May 28, 2026 15:54

lavrovvalera requested a deployment to workflow-approval May 28, 2026 15:54 — with GitHub Actions Waiting

BjoernAtBosch reviewed May 28, 2026

View reviewed changes

BjoernAtBosch reviewed May 29, 2026

View reviewed changes

lavrovvalera commented May 29, 2026

View reviewed changes

Comment thread score/time/clock/src/clock_status.h Outdated

lavrovvalera commented May 29, 2026

View reviewed changes

Comment thread score/time/vehicle_time/src/details/td_impl/vehicle_clock_backend_impl.cpp Outdated

Rename hplsc -> hirs

8d0b9a7

Rename HighPrecisionLocalSteady clock to HIResolutionSteady Time

lavrovvalera requested a deployment to workflow-approval May 29, 2026 12:51 — with GitHub Actions Waiting

[vehicle time] Renamed status functions

d278949

- IsSynchronized -> IsReliable - added HasBeenSynchronized - IsValid -> IsConsistent

lavrovvalera requested a deployment to workflow-approval June 1, 2026 17:13 — with GitHub Actions Waiting

lavrovvalera added 3 commits June 2, 2026 14:11

[VehcileTime] Make initialization explicit

c12c6be

- Added the hook to the timebases, which needs to be initialized - Moved the VehcileTime initialization to the dedicated method - Adjust examples and docs

Cleaning up

b5e1a74

- fix name files - fix formatiing - remove unneccessary comments

Clean the status interfaces

328c0fc

lavrovvalera requested a deployment to workflow-approval June 2, 2026 13:52 — with GitHub Actions Waiting

Update docs

a862f99

lavrovvalera requested a deployment to workflow-approval June 2, 2026 15:47 — with GitHub Actions Waiting

		VehicleTime::StatusFlag::kTimeLeapFuture,
		VehicleTime::StatusFlag::kTimeLeapPast})));

		if (IsFlagActive(VehicleTime::StatusFlag::kTimeLeapFuture) &&
		IsFlagActive(VehicleTime::StatusFlag::kTimeLeapPast))

Conversation

lavrovvalera commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Summary

Motivation

Changes

New framework — score/time/clock/

New clock domains

Bazel structure and visibility

Legacy removal

Documentation

API example

Uh oh!

github-actions Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

License Check Results

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BjoernAtBosch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lavrovvalera commented Apr 30, 2026 •

edited

Loading

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

New framework — `score/time/clock/`

github-actions Bot commented Apr 30, 2026 •

edited

Loading