Time sync

The AAOS Software Defined Vehicle (SDV) platform defines standard mechanisms for time source reporting from electronic control units (ECUs) and standard surfaces for exposing time information in SDV Instances. This page provides details and guidance for the SDV standard.

Clock architecture

The SDV platform has two standard clocks:

  • UTC clock: This is the standard Coordinated Universal Time clock. SOME/IP usually provides this from ECUs to the platform runtime. Use cases include certificate freshness, diagnostics, and V2X.

  • Network monotonic clock: This is a nondecreasing, highly accurate clock signal provided from ECUs that the broader vehicle architecture uses to ensure events are coordinated. ECUs provide this to the SDV platform through gPTP. This clock is also known as the steady clock.

Clocks in the SDV platform have specific architectural requirements:

  • Clock delivery: Each VM instance gets access to the same monotonic clock signal provided by the ECUs.

  • Clock integrity: The network monotonic clock input is expected to be a reliable source for coordinating events across services. Defense against possible system vulnerabilities like replay attacks or time inversion is based on the integrity of the monotonic clock.

  • Alarm usage: SDV platform clock APIs shouldn't be used for events with high-frequency occurrence (> 100 Hz) or < 10 ms latency between scheduling and event time. High-frequency or low-latency APIs should use a kernel driver.

Clock APIs

The network monotonic clock is exposed through the standard clock_gettime(3) API:

// Network monotonic clock uses standard Linux API.
// This is represented as a dynamic clock in clock_gettime(3)
clock_gettime(clockid_t id, &timespec)

This clock is provided through a PTP network mechanism to all VMs and is registered as a dynamic clock for clock_gettime(3) purposes.

The UTC clock is represented by CLOCK_REALTIME in clock_gettime(3).

Optional device driver

OEMs have the option to expose a Linux device block for additional time properties. Expose this with permissions handling through sepolicy:

# in device/OEM/target/sepolicy/time/file_contexts
/dev/sdvtime u:object_r:time_device:s0

OEMs are responsible for the development and capabilities of the custom Linux device driver that exposes APIs to the device block.

Notifications and callbacks

Notifications and callbacks for time components in SDV are userland capabilities that are provided by the OEM. The SDV platform doesn't provide specific APIs for these functions.

There should be up to one OEM service per VM requiring time sync functionality that handles all relevant time changes to be monitored. As an example when the trusted state changes for the current time source:

  • Changes to time source states are expected as low frequency events, so an OEM service can check changes through polling, for example, once per minute.

  • ECUs communicate the trusted state status of the UTC clock through the network, for example, over SOME/IP.

  • An OEM service publishes specific Data Tunnel topics to surface these changes to subscribers.

  • OEMs customize authorization policy for services to determine which ones can subscribe to these Data Tunnel topics to listen to trusted time state changes.

Error status and handling

Error codes follow the conventions of the standard Linux APIs involved, for example:

  • If clock_gettime() fails, this returns -1 and errno is set; this implies the clock operation isn't supported or the underlying clock source isn't ready.

  • If fopen() fails, this returns a null pointer and errno is set; this implies the block device isn't available.

  • If an ioctl() call fails, this returns -1 and errno is set; this implies the specified request code doesn't have a matching response from the underlying driver.