From c8d6116a2479ab49c9bbdb07a68ef18ce0076703 Mon Sep 17 00:00:00 2001
From: Klaus Schuch <klaus.schuch@avl.com>
Date: Wed, 15 May 2024 14:32:49 +0200
Subject: [PATCH] Clarify the information flow of clocks

---
 docs/2_2_common_mechanisms.adoc | 10 ++++++++--
 docs/2_4_common_schema.adoc     |  7 +++++--
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/2_2_common_mechanisms.adoc b/docs/2_2_common_mechanisms.adoc
index 83e6f5236..68782daaf 100644
--- a/docs/2_2_common_mechanisms.adoc
+++ b/docs/2_2_common_mechanisms.adoc
@@ -284,7 +284,9 @@ All variables are listed in <<modelDescription.xml>> as elements of `<fmiModelDe
 
 They are identified with a unique handle called <<valueReference, value reference>>.
 
-The attribute <<causality>> defines the direction of the information flow with respect to the FMU (e.g. <<input>>, <<output>>, <<parameter>>).
+The attribute <<causality>> defines the direction of the information flow with respect to the FMU (e.g. <<input>>, <<output>>, <<parameter>>). +
+For Clocks the <<causality>> indicates the information flow of the activation of the Clock. +
+Only for triggered Clocks, the <<causality>> also indicates the information flow of the timing.
 
 Variables, except Clocks, may be scalar or multi-dimensional arrays.
 Clocks must always be scalar.
@@ -536,7 +538,11 @@ Input Clock::
 is a variable of type Clock with <<causality>> = <<input>>.
 In Model Exchange and Co-Simulation, when input Clocks tick, the importer will activate the input Clocks using <<fmi3SetClock>>.
 In Scheduled Execution, when input Clocks tick, the importer will activate the associated model partitions (but not the input Clocks) using <<fmi3ActivateModelPartition>>.
-While the importer is the source of the actual Clock activations, the timing of the Clocks is defined by the FMU, either through the <<modelDescription.xml>> or calling <<fmi3GetInterval>>, or by another Clock connected to a <<triggered>> input Clock.
+
+The importer is the source of the actual Clock activations of input Clocks.
+For time-based input Clocks, the timing is defined by the FMU, either through the <<modelDescription.xml>> or by the importer calling <<fmi3GetInterval>>.
+For <<triggered>> input clocks, the timing is determined by the importer.
+_[The timing could be given by a triggered output Clock, or a time-based input Clock of a connected FMU, or any other source.]_
 
 Output Clock::
 [[outputClock, `output Clock`]]
diff --git a/docs/2_4_common_schema.adoc b/docs/2_4_common_schema.adoc
index b90791d3a..ae64126e5 100644
--- a/docs/2_4_common_schema.adoc
+++ b/docs/2_4_common_schema.adoc
@@ -965,8 +965,11 @@ If a <<structuralParameter,`structural parameter`>> is referenced in <<Dimension
 The `min` attribute might still be 0.
 
 The default of <<causality>> is <<local>>. +
-A continuous-time <<state>> or an event indicator must have <<causality>> = <<local>> or <<output>>, see also <<ModelStructure>>. +
-The causality of variables of type <<Clock>> must be either <<input>>, <<output>> or <<local>>.
+A continuous-time <<state>> or an event indicator must have <<causality>> = <<local>> or <<output>>, see also <<ModelStructure>>.
+
+The causality of variables of type <<Clock>> must be either <<input>>, <<output>> or <<local>>. +
+For Clocks the <<causality>> indicates the information flow of the activation of the Clock. +
+Only for triggered Clocks, the <<causality>> also indicates the information flow of the timing.
 
 |`variability`
 |