From 554d523785ef8681905ec13ad28a025ec0af40fe Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Tue, 15 Dec 2020 15:09:26 +0000 Subject: clock: Introduce clock_ticks_to_ns() The clock_get_ns() API claims to return the period of a clock in nanoseconds. Unfortunately since it returns an integer and a clock's period is represented in units of 2^-32 nanoseconds, the result is often an approximation, and calculating a clock expiry deadline by multiplying clock_get_ns() by a number-of-ticks is unacceptably inaccurate. Introduce a new API clock_ticks_to_ns() which returns the number of nanoseconds it takes the clock to make a given number of ticks. This function can do the complete calculation internally and will thus give a more accurate result. Signed-off-by: Peter Maydell Tested-by: Philippe Mathieu-Daudé Reviewed-by: Luc Michel Reviewed-by: Richard Henderson Reviewed-by: Philippe Mathieu-Daudé Message-Id: <20201215150929.30311-2-peter.maydell@linaro.org> Signed-off-by: Philippe Mathieu-Daudé --- docs/devel/clocks.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst index e5da28e211..c2e70e64db 100644 --- a/docs/devel/clocks.rst +++ b/docs/devel/clocks.rst @@ -258,6 +258,35 @@ Here is an example: clock_get_ns(dev->my_clk_input)); } +Calculating expiry deadlines +---------------------------- + +A commonly required operation for a clock is to calculate how long +it will take for the clock to tick N times; this can then be used +to set a timer expiry deadline. Use the function ``clock_ticks_to_ns()``, +which takes an unsigned 64-bit count of ticks and returns the length +of time in nanoseconds required for the clock to tick that many times. + +It is important not to try to calculate expiry deadlines using a +shortcut like multiplying a "period of clock in nanoseconds" value +by the tick count, because clocks can have periods which are not a +whole number of nanoseconds, and the accumulated error in the +multiplication can be significant. + +For a clock with a very long period and a large number of ticks, +the result of this function could in theory be too large to fit in +a 64-bit value. To avoid overflow in this case, ``clock_ticks_to_ns()`` +saturates the result to INT64_MAX (because this is the largest valid +input to the QEMUTimer APIs). Since INT64_MAX nanoseconds is almost +300 years, anything with an expiry later than that is in the "will +never happen" category. Callers of ``clock_ticks_to_ns()`` should +therefore generally not special-case the possibility of a saturated +result but just allow the timer to be set to that far-future value. +(If you are performing further calculations on the returned value +rather than simply passing it to a QEMUTimer function like +``timer_mod_ns()`` then you should be careful to avoid overflow +in those calculations, of course.) + Changing a clock period ----------------------- -- cgit v1.2.3-55-g7522