[RFC 2/4] clock: Add ClockPreUpdate callback event type

[Peter Maydell <peter.maydell@linaro.org>]

Add a new callback event type ClockPreUpdate, which is called
on period changes before the period is updated.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/clocks.rst | 9 ++++++++-
 include/hw/clock.h    | 1 +
 hw/core/clock.c       | 3 +++
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst
index 8d3b456561f..dea63742fb0 100644
--- a/docs/devel/clocks.rst
+++ b/docs/devel/clocks.rst
@@ -179,7 +179,14 @@ specific events they need to handle, so that if in future different
 events are added the callback code doesn't need to be updated.
 The events currently supported are:
 
- * ``ClockUpdate`` : called after the input clock's period has changed
+ * ``ClockPreUpdate`` : called when the input clock's period is about to
+   update. This is useful if the device needs to do some action for
+   which it needs to know the old value of the clock period. During
+   this callback, Clock API functions like ``clock_get()`` or
+   ``clock_ticks_to_ns()`` will use the old period.
+ * ``ClockUpdate`` : called after the input clock's period has changed.
+   During this callback, Clock API functions like ``clock_ticks_to_ns()``
+   will use the new period.
 
 Retrieving clocks from a device
 -------------------------------
diff --git a/include/hw/clock.h b/include/hw/clock.h
index 323f8d49fed..7d0eb286faa 100644
--- a/include/hw/clock.h
+++ b/include/hw/clock.h
@@ -27,6 +27,7 @@ OBJECT_DECLARE_SIMPLE_TYPE(Clock, CLOCK)
  * has been called.
  */
 typedef enum ClockEvent {
+    ClockPreUpdate, /* Clock period is about to update */
     ClockUpdate, /* Clock period has just updated */
 } ClockEvent;
 
diff --git a/hw/core/clock.c b/hw/core/clock.c
index 772d03a2eb5..963fe83a363 100644
--- a/hw/core/clock.c
+++ b/hw/core/clock.c
@@ -68,6 +68,9 @@ static void clock_propagate_period(Clock *clk, bool call_callbacks)
 
     QLIST_FOREACH(child, &clk->children, sibling) {
         if (child->period != clk->period) {
+            if (call_callbacks && child->callback) {
+                child->callback(child->callback_opaque, ClockPreUpdate);
+            }
             child->period = clk->period;
             trace_clock_update(CLOCK_PATH(child), CLOCK_PATH(clk),
                                CLOCK_PERIOD_TO_HZ(clk->period),
-- 
2.20.1