Update the Feature design

docs/conf.py

@@ -0,0 +1,25 @@
+# *******************************************************************************
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+# Based on the conf.py generated by the docs() macro; extends it with
+# required_in_id so that feat_arc_sta__time__* / feat_arc_dyn__time__* IDs
+# are accepted under docs/features/architecture/ (feature part "time" is
+# declared as valid here rather than enforced via the folder path).
+
+project = "S-CORE Time"
+project_url = "https://eclipse-score.github.io/time"
+version = "0.0.0"
+
+extensions = ["score_sphinx_bundle"]
+
+# Allow IDs containing "time" to live outside a "time/" subdirectory.
+required_in_id = ["time"]

docs/features/architecture/_assets/absolute_time_read_flow.puml

@@ -0,0 +1,62 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+hide footbox
+
+autonumber "<font color=red><b>[00]"
+
+title Absolute Time read (feature view)
+
+legend top left
+| <#LightCoral>  | external time source |
+| <#LightBlue>   | score platform stack |
+| <#LightGreen>  | score::time feature  |
+| <#LightSalmon> | application          |
+endlegend
+
+!pragma teoz true
+box "ECU" #f0f5f5
+  box "Application process" #e6ffe6
+    participant "Application"                   as app    #LightSalmon
+    participant "score::time::AbsoluteClock" as ac     #LightGreen
+  end box
+  participant "TimeDaemon\n(absolute time receiver)" as recv   #LightGreen
+  participant "score::someip" as someip #LightBlue
+end box
+participant "External time master" as master #LightCoral
+
+== Initialization ==
+app -> ac : init()
+ac --> app : ready
+
+== Absolute time provisioning (background) ==
+loop periodically
+  master -> master : capture absolute time;\nattach Delay Tag;\nderive accuracy & security
+  master -> someip : absolute time, Delay Tag,\naccuracy & security
+  someip -->> recv : deliver the four values
+  recv -> recv : convert Delay Tag to a local monotonic tag;\nderive Absolute Time status
+  note left
+    Side effect: absolute time is
+    also applied to OS CLOCK_REALTIME
+  end note
+  recv -->> ac : publish latest snapshot
+end
+
+== Reading the time ==
+app -> ac : now()
+ac -> ac : compensate on the local monotonic base\n(elapsed since the local tag)
+ac --> app : Snapshot\n(absolute TimePoint + \nAbsolute Time status)
+
+@enduml

docs/features/architecture/_assets/clock_testability.puml

@@ -0,0 +1,47 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+hide footbox
+
+autonumber "<font color=red><b>[00]"
+
+title Clock mocking support (feature view)
+
+legend top left
+| <#LightGreen>  | score::time feature |
+| <#LightSalmon> | application         |
+endlegend
+
+!pragma teoz true
+box "ECU" #f0f5f5
+  box "Application process" #e6ffe6
+    participant "Application"              as app   #LightSalmon
+    participant "Clock<Tag>\n(mock)"  as clock #LightGreen
+  end box
+end box
+
+note over app, clock
+  Applies to Vehicle Clock, Local Clock
+  and Absolute Clock
+end note
+
+== Test setup ==
+app -> clock : inject mock
+
+== Application reads time ==
+app -> clock : now()
+clock --> app : controlled Snapshot\n(predetermined TimePoint + status)
+
+@enduml

docs/features/architecture/_assets/local_time_read_flow.puml

@@ -0,0 +1,59 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+hide footbox
+
+autonumber "<font color=red><b>[00]"
+
+title Local Time read (feature view)
+
+legend top left
+| <#LightGreen>  | score::time feature  |
+| <#LightSalmon> | application          |
+| <#LightGrey>   | OS / local time base |
+endlegend
+
+!pragma teoz true
+box "ECU" #f0f5f5
+  box "Application process" #e6ffe6
+    participant "Application"                as app #LightSalmon
+    participant "score::time::SteadyClock\n/ HighResSteadyClock\n/ SystemClock" as lc  #LightGreen
+  end box
+  participant "OS" as os #LightGrey
+end box
+
+== Steady Clock ==
+app -> lc : now()
+lc -> os : CLOCK_MONOTONIC\n(std::chrono::steady_clock)
+os --> lc : TimePoint
+lc --> app : Snapshot (TimePoint)
+
+== System Clock ==
+app -> lc : now()
+lc -> os : CLOCK_REALTIME\n(std::chrono::system_clock)
+os --> lc : TimePoint
+note left
+  Kept aligned to Absolute Time
+  by score::time
+end note
+lc --> app : Snapshot (TimePoint)
+
+== High-Resolution Steady Clock ==
+app -> lc : now()
+lc -> os : ClockCycles
+os --> lc : TimePoint
+lc --> app : Snapshot (TimePoint)
+
+@enduml

docs/features/architecture/_assets/static_arch.puml

@@ -0,0 +1,62 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+title Time feature static architecture
+
+legend top left
+| <#LightCoral>  | external time source |
+| <#LightGrey>   | OS / local time base |
+| <#LightBlue>   | score platform stack |
+| <#LightGreen>  | score::time feature  |
+| <#LightSalmon> | application          |
+endlegend
+
+rectangle "ECU" #f0f5f5 {
+  actor "Application" as user #LightSalmon
+
+  package "score::time feature" #e6ffe6 {
+    package "score::time\n(clock library)" #d4f7d4 {
+      component "score::time::VehicleClock" as veh_clock_api #LightGreen
+      component "score::time::<Local>Clock\n(Steady|HiRes|System)" as local_clock_api #LightGreen
+      component "score::time::AbsoluteClock" as abs_clock_api #LightGreen
+    }
+    component "ts_client\n(TimeSlave<->TimeDaemon shm IPC)" as time_slave_client #LightGreen
+    component "TimeDaemon\n" as time_daemon #LightGreen
+    component "TimeSlave\n(gPTP slave endpoint)" as time_slave #LightGreen
+  }
+
+  component "score::someip" as score_someip #LightBlue
+  component "OS / local clock" as os #LightGrey
+}
+
+cloud "Vehicle network\n(gPTP / IEEE 802.1AS)" as veh_net #LightCoral
+cloud "Absolute time source\n(e.g. GPS / UTC)" as abs_master #LightCoral
+
+user --> veh_clock_api : read vehicle time
+user --> local_clock_api : read local time
+user --> abs_clock_api : read absolute time
+
+veh_clock_api --> time_daemon : IPC
+abs_clock_api --> time_daemon : IPC
+time_daemon --> time_slave_client : uses
+time_slave_client <-- time_slave : PTP data
+time_slave ..> veh_net : Synchronization via gPTP
+
+time_daemon <-- score_someip : absolute time
+score_someip ..> abs_master : obtains absolute time
+
+local_clock_api ..> os : reads OS clock
+
+@enduml

docs/features/architecture/_assets/vehicle_time_notification.puml

@@ -0,0 +1,72 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+hide footbox
+
+autonumber "<font color=red><b>[00]"
+
+title Vehicle Time notification (feature view)
+
+legend top left
+| <#LightCoral>  | external time source |
+| <#LightGreen>  | score::time feature  |
+| <#LightSalmon> | application          |
+endlegend
+
+!pragma teoz true
+box "ECU" #f0f5f5
+  box "Application process" #e6ffe6
+    participant "Application"                      as app  #LightSalmon
+    participant "score::time::VehicleClock"        as vc   #LightGreen
+  end box
+  participant "TimeDaemon\n(validation & distribution)" as td #LightGreen
+  participant "ts_client\n(gPTP shm IPC)" as tsc #LightGreen
+  participant "TimeSlave\n(gPTP endpoint)" as ts #LightGreen
+end box
+participant "Grand Master" as host #LightCoral
+
+== Subscribe ==
+app -> vc : subscribe(handler, event kind)
+note right
+  Event kinds:
+  - Vehicle Time status change
+  - sync / follow-up frame (sync-fup)
+  - pdelay frame
+  sync-fup and pdelay are independent sequences
+end note
+vc --> app : subscribed
+
+== Event (background) ==
+loop on each subscribed event
+  host <--> ts : gPTP synchronization
+  ts -> tsc : publish PTP data (shared memory)
+  tsc --> td : receive PTP data
+  td -> td : validate, derive Vehicle Time status
+  td -->> vc : notify event
+  vc -->> app : invoke handler(event)
+end
+
+note over app, td
+  The PTP payload data (sync-fup / pdelay) is available only via
+  subscription. The Vehicle Time status can also be read from now();
+  subscription additionally delivers it on change.
+  Main use case: diagnostics.
+end note
+
+== Unsubscribe ==
+app -> vc : unsubscribe()
+vc --> app : unsubscribed
+
+@enduml

docs/features/architecture/_assets/vehicle_time_read_flow.puml

@@ -0,0 +1,58 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml
+
+hide footbox
+
+autonumber "<font color=red><b>[00]"
+
+title Vehicle Time read (feature view)
+
+legend top left
+| <#LightCoral>  | external time source |
+| <#LightGreen>  | score::time feature  |
+| <#LightSalmon> | application          |
+endlegend
+
+!pragma teoz true
+box "ECU" #f0f5f5
+  box "Application process" #e6ffe6
+    participant "Application"                      as app  #LightSalmon
+    participant "score::time::VehicleClock"        as vc   #LightGreen
+  end box
+  participant "TimeDaemon\n(validation & distribution)" as td #LightGreen
+  participant "ts_client\n(gPTP shm IPC)" as tsc #LightGreen
+  participant "TimeSlave\n(gPTP endpoint)" as ts #LightGreen
+end box
+participant "Grand Master" as host #LightCoral
+
+== Initialization ==
+app -> vc : init()
+vc --> app : ready
+
+== Synchronization (background) ==
+loop periodically
+  host <--> ts : gPTP synchronization
+  ts -> tsc : publish PTP data (shared memory)
+  tsc --> td : receive PTP data
+  td -> td : validate, derive Vehicle Time status,\ntimestamp on local monotonic clock
+  td -->> vc : distribute latest snapshot\n(time, local timestamp, status, metadata)
+end
+
+== Reading the time (on demand) ==
+app -> vc : now()
+vc -> vc : use latest snapshot;\ninterpolate on current local monotonic clock
+vc --> app : Snapshot\n(vehicle TimePoint + Vehicle Time status)
+
+@enduml