Time Daemon Detailed Design

Time Daemon Detailed Design		status: draft security: YES safety: ASIL_B
tags: time_daemon version: 1 realizes: wp__sw_implementation
doc__time_daemon_detailed_design		Generic Document

Description

Use Cases

TimeDaemon is the non Autosar adaptive process who is intended to get the Vehicle Time from the ptp slave daemon (ptpd or any other), verify and validate the timepoints and distribute time information across the clients.

More precisely we can specify the following use cases for the time daemon:

1. Providing current Vehicle time to different applications

2. Setting the synchronization qualifier (aka Synchronized, Timeout, so on)

3. Providing needed information for diagnostics

4. Providing needed information for addition verification, ex SafeCarTime

The raw architectural diagram is represented below.

Rationale Behind Decomposition into Units

TimeDaemon is decomposed into six implementation units following SOLID principles (Single Responsibility, Open/Closed) and design patterns (Publish-Subscribe, State Machines):

1. Application — Orchestrates initialization and lifecycle of all daemon components

2. Message Broker — Central publish-subscribe hub for decoupled inter-unit communication

3. ControlFlowDivider — Separates execution threads to prevent blocking and maintain data flow consistency

4. PTP Machine — Retrieves raw time data from PTP stack at consistent rates

5. Verification Machine — Validates and qualifies time data (sync status, jump detection, timeout)

6. IPC Machine — Exports qualified time snapshots to client applications via shared-memory interface

This separation enables independent testing, reusable implementations (e.g., different PTP stacks), and clear responsibility boundaries critical for ASIL_B safety qualification.

Static Diagrams for Unit Interactions

Class View

Main classes and unit relationships are presented on this diagram:

Deployment View

The design deployment and process architecture is represented on this diagram:

Dynamic Diagrams for Unit Interactions

Data and Control Flow

The data and control flow between units is presented in the following diagram:

On this view you can see several execution scopes:

1. PTP retrieving scope — retrieves latest PTP data and publishes to input_ptp_data topic

2. PTP decoupling scope — decouples the retrieving scope from the following scopes for cases when PTP data is coming in rapidly or new data is missing too long. It publishes PTP data to raw_ptp_data topic.

3. PTPTimeInfo handling scope — validates time data and publishes to verified_ptp_data topic

4. PTPTimeInfo receiving scope — propagates qualified time to client applications```

Each control flow is implemented with a dedicated thread and is independent from the others.

Data Types or Events

Main data exchanged between units via MessageBroker topics:

• PtpTimeInfo — internal time snapshot struct containing sync data, peer delay, status flags, and timestamps

Topic names:

input_ptp_data

Input PTP snapshot from PtpMachine; published to ControlFlowDivider for thread separation.

raw_ptp_data

Same data as input_ptp_data but republished at consistent rate by ControlFlowDivider; consumed by VerificationMachine.

verified_ptp_data

Validated and qualified time snapshot from VerificationMachine; includes sync status, timeout flags, time jump detection; published to PublisherImpl.

Units within the Component

The following units comprise TimeDaemon’s internal implementation:

• TimeDaemon — main entry point orchestrating lifecycle and initialization

• MessageBroker — publish-subscribe hub for decoupled inter-unit communication

• ControlFlowDivider — separates execution threads to prevent blocking

• PtpMachine — retrieves raw time data from PTP stack

• ShmPtpEngine — reads gPTP data from TimeSlave shared memory channel

• VerificationMachine — validates and qualifies time data

• PublisherImpl — publishes qualified time snapshots via shared memory

• ReceiverImpl — receives time data from shared memory

Per-Unit Diagrams

Application

The Application component is the main entry point for TimeDaemon, orchestrating lifecycle and initialization of all daemon components.

The TimebaseHandler component implements timebase-specific logic. Multiple handlers may exist per supported timebase count, allowing different timebase implementations while maintaining consistent application structure.

During initialization, the Application uses a factory pattern to create components in specific order:

• Create MessageBroker first (other components depend on it)

• Create ProactiveMachines (PtpMachine, ControlFlowDivider) that drive system behavior, then initialize and wire subscriptions

• Create ReactiveMachines (VerificationMachine, IPCMachine) that respond to events, then initialize and wire subscriptions

During execution, ProactiveMachines start in correct order. On termination, they stop in reverse order.

Class diagram:

Initialization sequence showing component creation order and MessageBroker subscription wiring:

Runtime workflow showing ProactiveMachine startup and shutdown coordination:

MessageBroker

Class diagram:

Initialization workflow:

Message flow through MessageBroker showing topic distribution to multiple subscribers:

ControlFlowDivider

Class diagram:

Initialization workflow:

Thread separation and periodic republishing workflow:

PTPMachine

Class diagram:

Initialization workflow:

PTP data retrieval cycle from shared memory:

ShmPTPEngine

Class diagram:

Initialization workflow:

Shared memory read from TimeSlave gPTP publisher:

VerificationMachine

Class diagram:

Initialization workflow:

Time data validation stages (sync check, timeout, jump detection):

IPC Machine

Class diagram:

Initialization workflow:

Qualified time snapshot publishing to client shared memory:

Client-side receive from TimeDaemon shared memory channel:

Logging configuration

The daemon should have the following logging contexts:

Table 11 Logging Contexts

component	App/Context ID	Comments
TimeDaemon	TDON	TimeDaemON
Application	TDAP	TimeDaemon APplication
MessageBroker	TDMB	TimeDaemon MessageBroker
ControlFlowDivider	TDCD	TimeDaemon ControlFlowDivider
PTPMachine	TDPM	TimeDaemon PTPMachine
ShmPTPEngine	GPTP	GPTP Shm adapter (Initialize / ReadPTPSnapshot)
VerificationMachine	TDVM	TimeDaemon VerificationMachine
IPCMachine::receiver	TDIR	TimeDaemon IPCMachine::Receiver
IPCMachine::publisher	TDIP	TimeDaemon IPCMachine::Publisher

Variability

Configuration files

The TimeDaemon uses structured configuration files to enable customization of its runtime behavior. These data could be configured:

1. Component-specific Configuration:

   1. Each component can have dedicated configuration sections

   2. Parameters such as update rates, timeouts, and thresholds can be specified

2. Topic Configuration:

   1. Topics for the Message Broker can be defined in configuration

   2. Publisher and subscriber relationships can be specified externally

   3. Component roles (publisher/subscriber) can be assigned through configuration

3. File Format and Structure: The configuration files use JSON format for readability and easy parsing:

{
  "message_broker": {
    "topics": [
      {
        "name": "raw_ptp_data",
        "publishers": ["PtpMachine"],
        "subscribers": ["ControlFlowDivider"]
      },
      {
        "name": "input_ptp_data",
        "publishers": ["ControlFlowDivider"],
        "subscribers": ["VerificationMachine"]
      },
      {
        "name": "verified_ptp_data",
        "publishers": ["VerificationMachine"],
        "subscribers": ["IPCMachine"]
      }
    ]
  },
  "ptp_machine": {
    "update_interval_ms": 50,
    "ptp_stack_type": "ptp",
    "ptp_stack_parameters": {
      "device": "/dev/ptp0"
    }
  },
  "control_flow_divider": {
    "timeout_ms": 500,
    "publishing_rate_ms": 100
  },
  "verification_machine": {
    "validation_stages": ["synchronization", "timejumps", "timeout"],
    "timejumps_parameters": {
      "max_backward_jump_ns": 100000
    },
    "timeout_parameters": {
      "threshold_ns": 100000
    }
  },
  "ipc_machine": {
    "shared_memory_name": "vehicle_time",
    "shared_memory_size": 4096
  }
}

Scalability

The TimeDaemon’s architecture supports scalability in the following ways:

Component Extensibility:

1. New machine components can be added by implementing the BaseMachine interface

2. Additional validation stages can be plugged into the VerificationMachine pipeline

3. Alternative IPC mechanisms or communication with ptp stack can be implemented by alternative the IPCMachine or PTPMachine implementation

Example based on Qualified Vehicle Time integration

The Qualified Vehicle Time integration extends the standard TimeDaemon architecture with:

1. A Qualified Vehicle Time component that performs additional time qualification and provide new topics: qualified_ptp_data and diagnostic_sct_data

2. A dedicated IPC channel for SCT diagnostic data

3. A score::time::qvt library for diagnostic applications

The Qualified Vehicle Time component is integrated into the existing processing pipeline:

1. It subscribes to the verified_ptp_data topic from the VerificationMachine

2. It processes and qualifies the time data with additional QVT-specific checks

3. It publishes two types of data:

   1. Qualified time data to the standard IPC Machine towards clients interested in the qualified Vehicle Time

   2. Diagnostic data to a dedicated QVT IPC channel towards Diagnostic and Central Validator notifications

The extended data flow with Qualified Vehicle Time integration is shown below:

Example based on Absolute Time integration

Another example of the TimeDaemon extension is the integration of an Absolute Time source, such as GNSS, to provide absolute time information alongside the relative Vehicle Time from PTP.

The Absolute Time integration extends the standard TimeDaemon architecture with:

1. An SDatMachine component that retrieves absolute time from GNSS via SOMEIP or other sources and provide new topics: absolute_time_data

2. A dedicated verification stage in the VerificationMachine for Absolute Time qualification

3. A dedicated IPC channel for Absolute Time data

4. A score::time::abs library for applications requiring absolute time on Clients side.

The way how it is integrated is presented below.

The control and data flow with Absolute Time integration is shown below.

Using in test environment

Using in ITF

Normal behavior is expected.

Using in Component Tests on the host

Overview

The TimeDaemon can be utilized in the Component Tests environment to enable comprehensive testing of time-dependent components without relying on physical PTP hardware. This approach allows test cases to manipulate time values and synchronization states to validate application behavior under various timing conditions.

For the Component tests the PtpMachine::PtpEngine library is the only one platform-dependent. Thus the TimeDaemon components remain largely unchanged except for the PTPMachine component, which is replaced with an test-specific implementation that can be controlled via test cases This component shall:

1. simulate “normal” PTPMachine behavior

2. have the communication channel to the test case and react on the manipulations

Next steps: plugin system

The TimeDaemon could be extended with a flexible plugin system that enables dynamic component loading, configuration, subscription and extension without requiring code changes or recompilation.

Plugin Architecture

The plugin system is structured around the following key elements:

1. Component Registry: A central registry that maintains information about available component implementations

2. Component Factory: Creates component instances based on configuration

3. Plugin Manager: Loads and initializes plugins at runtime

4. Configuration-Driven Assembly: Components and their relationships defined in configuration files

Component Creation Process

During TimeDaemon initialization:

1. The Plugin Manager loads all specified plugins from configured directories or bazel targets

2. Each plugin registers its component factories with the registry

3. The Application reads the component configuration

4. For each component in the configuration:

   1. The appropriate factory is retrieved from the registry

   2. The component is created with its specified parameters

   3. Components are connected based on the MessageBroker topic configuration

ASIL-B qualification

Clean separation of concerns allows the VehicleClock td_impl backend as well as TimeDaemon to be qualified according to ASIL-B requirements following ISO 26262 standard.

Inspection Checklist

The checklist for verification of the detailed design and code can be found here:

• Implementation Inspection Checklist
  • Purpose
  • Conduct
  • Checklist