@@ -260,6 +260,29 @@ clocks get the new clock period value: *Clock 2*, *Clock 3* and *Clock 4*.
It is not possible to disconnect a clock or to change the clock connection
after it is connected.
+Clock multiplier and divider settings
+-------------------------------------
+
+By default, when clocks are connected together, the child
+clocks run with the same period as their source (parent) clock.
+The Clock API supports a built-in period multiplier/divider
+mechanism so you can configure a clock to make its children
+run at a different period from its own. If you call the
+``clock_set_mul_div()`` function you can specify the clock's
+multiplier and divider values. The children of that clock
+will all run with a period of ``parent_period * multiplier / divider``.
+For instance, if the clock has a frequency of 8MHz and you set its
+multiplier to 2 and its divider to 3, the child clocks will run
+at 12MHz.
+
+You can change the multiplier and divider of a clock at runtime,
+so you can use this to model clock controller devices which
+have guest-programmable frequency multipliers or dividers.
+
+Note that ``clock_set_mul_div()`` does not automatically call
+``clock_propagate()``. If you make a runtime change to the
+multiplier or divider you must call clock_propagate() yourself.
+
Unconnected input clocks
------------------------
@@ -81,6 +81,10 @@ struct Clock {
void *callback_opaque;
unsigned int callback_events;
+ /* Ratio of the parent clock to run the child clocks at */
+ uint32_t multiplier;
+ uint32_t divider;
+
/* Clocks are organized in a clock tree */
Clock *source;
QLIST_HEAD(, Clock) children;
@@ -350,4 +354,29 @@ static inline bool clock_is_enabled(const Clock *clk)
*/
char *clock_display_freq(Clock *clk);
+/**
+ * clock_set_mul_div: set multiplier/divider for child clocks
+ * @clk: clock
+ * @multiplier: multiplier value
+ * @divider: divider value
+ *
+ * By default, a Clock's children will all run with the same period
+ * as their parent. This function allows you to adjust the multiplier
+ * and divider used to derive the child clock frequency.
+ * For example, setting a multiplier of 2 and a divider of 3
+ * will run child clocks with a period 2/3 of the parent clock,
+ * so if the parent clock is an 8MHz clock the children will
+ * be 12MHz.
+ *
+ * Setting the multiplier to 0 will stop the child clocks.
+ * Setting the divider to 0 is a programming error (diagnosed with
+ * an assertion failure).
+ * Setting a multiplier value that results in the child period
+ * overflowing is not diagnosed.
+ *
+ * Note that this function does not call clock_propagate(); the
+ * caller should do that if necessary.
+ */
+void clock_set_mul_div(Clock *clk, uint32_t multiplier, uint32_t divider);
+
#endif /* QEMU_HW_CLOCK_H */
@@ -14,12 +14,50 @@
#include "migration/vmstate.h"
#include "hw/clock.h"
+static bool muldiv_needed(void *opaque)
+{
+ Clock *clk = opaque;
+
+ return clk->multiplier != 1 || clk->divider != 1;
+}
+
+static int clock_pre_load(void *opaque)
+{
+ Clock *clk = opaque;
+ /*
+ * The initial out-of-reset settings of the Clock might have been
+ * configured by the device to be different from what we set
+ * in clock_initfn(), so we must here set the default values to
+ * be used if they are not in the inbound migration state.
+ */
+ clk->multiplier = 1;
+ clk->divider = 1;
+
+ return 0;
+}
+
+const VMStateDescription vmstate_muldiv = {
+ .name = "clock/muldiv",
+ .version_id = 1,
+ .minimum_version_id = 1,
+ .needed = muldiv_needed,
+ .fields = (VMStateField[]) {
+ VMSTATE_UINT32(multiplier, Clock),
+ VMSTATE_UINT32(divider, Clock),
+ },
+};
+
const VMStateDescription vmstate_clock = {
.name = "clock",
.version_id = 0,
.minimum_version_id = 0,
+ .pre_load = clock_pre_load,
.fields = (VMStateField[]) {
VMSTATE_UINT64(period, Clock),
VMSTATE_END_OF_LIST()
- }
+ },
+ .subsections = (const VMStateDescription*[]) {
+ &vmstate_muldiv,
+ NULL
+ },
};
@@ -64,6 +64,15 @@ bool clock_set(Clock *clk, uint64_t period)
return true;
}
+static uint64_t clock_get_child_period(Clock *clk)
+{
+ /*
+ * Return the period to be used for child clocks, which is the parent
+ * clock period adjusted for for multiplier and divider effects.
+ */
+ return muldiv64(clk->period, clk->multiplier, clk->divider);
+}
+
static void clock_call_callback(Clock *clk, ClockEvent event)
{
/*
@@ -78,15 +87,16 @@ static void clock_call_callback(Clock *clk, ClockEvent event)
static void clock_propagate_period(Clock *clk, bool call_callbacks)
{
Clock *child;
+ uint64_t child_period = clock_get_child_period(clk);
QLIST_FOREACH(child, &clk->children, sibling) {
- if (child->period != clk->period) {
+ if (child->period != child_period) {
if (call_callbacks) {
clock_call_callback(child, ClockPreUpdate);
}
- child->period = clk->period;
+ child->period = child_period;
trace_clock_update(CLOCK_PATH(child), CLOCK_PATH(clk),
- CLOCK_PERIOD_TO_HZ(clk->period),
+ CLOCK_PERIOD_TO_HZ(child->period),
call_callbacks);
if (call_callbacks) {
clock_call_callback(child, ClockUpdate);
@@ -110,7 +120,7 @@ void clock_set_source(Clock *clk, Clock *src)
trace_clock_set_source(CLOCK_PATH(clk), CLOCK_PATH(src));
- clk->period = src->period;
+ clk->period = clock_get_child_period(src);
QLIST_INSERT_HEAD(&src->children, clk, sibling);
clk->source = src;
clock_propagate_period(clk, false);
@@ -133,10 +143,23 @@ char *clock_display_freq(Clock *clk)
return freq_to_str(clock_get_hz(clk));
}
+void clock_set_mul_div(Clock *clk, uint32_t multiplier, uint32_t divider)
+{
+ assert(divider != 0);
+
+ trace_clock_set_mul_div(CLOCK_PATH(clk), clk->multiplier, multiplier,
+ clk->divider, divider);
+ clk->multiplier = multiplier;
+ clk->divider = divider;
+}
+
static void clock_initfn(Object *obj)
{
Clock *clk = CLOCK(obj);
+ clk->multiplier = 1;
+ clk->divider = 1;
+
QLIST_INIT(&clk->children);
}
@@ -34,3 +34,4 @@ clock_disconnect(const char *clk) "'%s'"
clock_set(const char *clk, uint64_t old, uint64_t new) "'%s', %"PRIu64"Hz->%"PRIu64"Hz"
clock_propagate(const char *clk) "'%s'"
clock_update(const char *clk, const char *src, uint64_t hz, int cb) "'%s', src='%s', val=%"PRIu64"Hz cb=%d"
+clock_set_mul_div(const char *clk, uint32_t oldmul, uint32_t mul, uint32_t olddiv, uint32_t div) "'%s', mul: %u -> %u, div: %u -> %u"