diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst index 956bd147ea..675fbeb6ab 100644 --- a/docs/devel/clocks.rst +++ b/docs/devel/clocks.rst @@ -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 ------------------------ diff --git a/hw/core/clock-vmstate.c b/hw/core/clock-vmstate.c index 260b13fc2c..9d9174ffbd 100644 --- a/hw/core/clock-vmstate.c +++ b/hw/core/clock-vmstate.c @@ -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 + }, }; diff --git a/hw/core/clock.c b/hw/core/clock.c index fc5a99683f..916875e07a 100644 --- a/hw/core/clock.c +++ b/hw/core/clock.c @@ -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); } diff --git a/hw/core/trace-events b/hw/core/trace-events index 360ddeb2c8..9b3ecce3b2 100644 --- a/hw/core/trace-events +++ b/hw/core/trace-events @@ -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" diff --git a/include/hw/clock.h b/include/hw/clock.h index a7187eab95..11f67fb970 100644 --- a/include/hw/clock.h +++ b/include/hw/clock.h @@ -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 */