aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2021-01-05 21:06:42 +0000
committerPeter Maydell <peter.maydell@linaro.org>2021-01-05 21:06:42 +0000
commit2e0b5bbe813930021b2baab03c9d424c1c52d18b (patch)
treed5e5ccd86c2c9b60cf5405f82bf34a99f4590abe /docs
parent52d25464605dc20022ad94aa8bc8e8473e600833 (diff)
parent457027298749333047bf81a856ce95ea5f9dccd9 (diff)
downloadqemu-2e0b5bbe813930021b2baab03c9d424c1c52d18b.zip
qemu-2e0b5bbe813930021b2baab03c9d424c1c52d18b.tar.gz
qemu-2e0b5bbe813930021b2baab03c9d424c1c52d18b.tar.bz2
Merge remote-tracking branch 'remotes/philmd-gitlab/tags/mips-20210104' into staging
MIPS patches queue - Use PCI macros (Philippe Mathieu-Daudé) - Clean up VT82C686B south bridge (BALATON Zoltan) - Introduce clock_ticks_to_ns() (Peter Maydell) - Add Loongson-3 machine (Huacai Chen) - Make addresses used by bootloader unsigned (Jiaxun Yang) - Clean fuloong2e PROM environment (Jiaxun Yang) - Add integration test of fuloong2e booting Linux (Jiaxun Yang) # gpg: Signature made Mon 04 Jan 2021 22:37:48 GMT # gpg: using RSA key FAABE75E12917221DCFD6BB2E3E32C2CDEADC0DE # gpg: Good signature from "Philippe Mathieu-Daudé (F4BUG) <f4bug@amsat.org>" [full] # Primary key fingerprint: FAAB E75E 1291 7221 DCFD 6BB2 E3E3 2C2C DEAD C0DE * remotes/philmd-gitlab/tags/mips-20210104: (35 commits) tests/acceptance: Test boot_linux_console for fuloong2e hw/mips/fuloong2e: Correct cpuclock in PROM environment hw/mips/fuloong2e: Remove unused env entry hw/mips/fuloong2e: Replace faulty documentation links hw/mips/fuloong2e: Remove define DEBUG_FULOONG2E_INIT hw/mips: Use address translation helper to handle ENVP_ADDR hw/mips/malta: Use address translation helper to calculate bootloader_run_addr hw/mips: Make bootloader addresses unsigned docs/system: Update MIPS machine documentation hw/mips: Add Loongson-3 machine support hw/mips: Add Loongson-3 boot parameter helpers hw/mips: Implement fw_cfg_arch_key_name() hw/intc: Rework Loongson LIOINTC clock: Define and use new clock_display_freq() clock: Remove clock_get_ns() target/mips: Don't use clock_get_ns() in clock period calculation clock: Introduce clock_ticks_to_ns() vt82c686: Rename superio config related parts vt82c686: Use shorter name for local variable holding object state vt82c686: Remove unneeded includes and defines ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/devel/clocks.rst51
-rw-r--r--docs/system/target-mips.rst10
2 files changed, 57 insertions, 4 deletions
diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst
index e5da28e..2548d84 100644
--- a/docs/devel/clocks.rst
+++ b/docs/devel/clocks.rst
@@ -238,8 +238,17 @@ object during device instance init. For example:
Fetching clock frequency/period
-------------------------------
-To get the current state of a clock, use the functions ``clock_get()``,
-``clock_get_ns()`` or ``clock_get_hz()``.
+To get the current state of a clock, use the functions ``clock_get()``
+or ``clock_get_hz()``.
+
+``clock_get()`` returns the period of the clock in its fully precise
+internal representation, as an unsigned 64-bit integer in units of
+2^-32 nanoseconds. (For many purposes ``clock_ticks_to_ns()`` will
+be more convenient; see the section below on expiry deadlines.)
+
+``clock_get_hz()`` returns the frequency of the clock, rounded to the
+next lowest integer. This implies some inaccuracy due to the rounding,
+so be cautious about using it in calculations.
It is also possible to register a callback on clock frequency changes.
Here is an example:
@@ -254,10 +263,44 @@ Here is an example:
*/
/* do something with the new period */
- fprintf(stdout, "device new period is %" PRIu64 "ns\n",
- clock_get_ns(dev->my_clk_input));
+ fprintf(stdout, "device new period is %" PRIu64 "* 2^-32 ns\n",
+ clock_get(dev->my_clk_input));
}
+If you are only interested in the frequency for displaying it to
+humans (for instance in debugging), use ``clock_display_freq()``,
+which returns a prettified string-representation, e.g. "33.3 MHz".
+The caller must free the string with g_free() after use.
+
+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
-----------------------
diff --git a/docs/system/target-mips.rst b/docs/system/target-mips.rst
index cd2a931..138441b 100644
--- a/docs/system/target-mips.rst
+++ b/docs/system/target-mips.rst
@@ -84,6 +84,16 @@ The Fuloong 2E emulation supports:
- RTL8139D as a network card chipset
+The Loongson-3 virtual platform emulation supports:
+
+- Loongson 3A CPU
+
+- LIOINTC as interrupt controller
+
+- GPEX and virtio as peripheral devices
+
+- Both KVM and TCG supported
+
The mipssim pseudo board emulation provides an environment similar to
what the proprietary MIPS emulator uses for running Linux. It supports: