docs/devel/tcg-plugins.rst

   1 ..
   2    Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
   3    Copyright (c) 2019, Linaro Limited
   4    Written by Emilio Cota and Alex Bennée
   5
   6 ================
   7 QEMU TCG Plugins
   8 ================
   9
  10 QEMU TCG plugins provide a way for users to run experiments taking
  11 advantage of the total system control emulation can have over a guest.
  12 It provides a mechanism for plugins to subscribe to events during
  13 translation and execution and optionally callback into the plugin
  14 during these events. TCG plugins are unable to change the system state
  15 only monitor it passively. However they can do this down to an
  16 individual instruction granularity including potentially subscribing
  17 to all load and store operations.
  18
  19 API Stability
  20 =============
  21
  22 This is a new feature for QEMU and it does allow people to develop
  23 out-of-tree plugins that can be dynamically linked into a running QEMU
  24 process. However the project reserves the right to change or break the
  25 API should it need to do so. The best way to avoid this is to submit
  26 your plugin upstream so they can be updated if/when the API changes.
  27
  28 API versioning
  29 --------------
  30
  31 All plugins need to declare a symbol which exports the plugin API
  32 version they were built against. This can be done simply by::
  33
  34   QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION;
  35
  36 The core code will refuse to load a plugin that doesn't export a
  37 `qemu_plugin_version` symbol or if plugin version is outside of QEMU's
  38 supported range of API versions.
  39
  40 Additionally the `qemu_info_t` structure which is passed to the
  41 `qemu_plugin_install` method of a plugin will detail the minimum and
  42 current API versions supported by QEMU. The API version will be
  43 incremented if new APIs are added. The minimum API version will be
  44 incremented if existing APIs are changed or removed.
  45
  46 Exposure of QEMU internals
  47 --------------------------
  48
  49 The plugin architecture actively avoids leaking implementation details
  50 about how QEMU's translation works to the plugins. While there are
  51 conceptions such as translation time and translation blocks the
  52 details are opaque to plugins. The plugin is able to query select
  53 details of instructions and system configuration only through the
  54 exported *qemu_plugin* functions.
  55
  56 Query Handle Lifetime
  57 ---------------------
  58
  59 Each callback provides an opaque anonymous information handle which
  60 can usually be further queried to find out information about a
  61 translation, instruction or operation. The handles themselves are only
  62 valid during the lifetime of the callback so it is important that any
  63 information that is needed is extracted during the callback and saved
  64 by the plugin.
  65
  66 Usage
  67 =====
  68
  69 The QEMU binary needs to be compiled for plugin support::
  70
  71   configure --enable-plugins
  72
  73 Once built a program can be run with multiple plugins loaded each with
  74 their own arguments::
  75
  76   $QEMU $OTHER_QEMU_ARGS \
  77       -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \
  78       -plugin tests/plugin/libhotblocks.so
  79
  80 Arguments are plugin specific and can be used to modify their
  81 behaviour. In this case the howvec plugin is being asked to use inline
  82 ops to count and break down the hint instructions by type.
  83
  84 Plugin Life cycle
  85 =================
  86
  87 First the plugin is loaded and the public qemu_plugin_install function
  88 is called. The plugin will then register callbacks for various plugin
  89 events. Generally plugins will register a handler for the *atexit*
  90 if they want to dump a summary of collected information once the
  91 program/system has finished running.
  92
  93 When a registered event occurs the plugin callback is invoked. The
  94 callbacks may provide additional information. In the case of a
  95 translation event the plugin has an option to enumerate the
  96 instructions in a block of instructions and optionally register
  97 callbacks to some or all instructions when they are executed.
  98
  99 There is also a facility to add an inline event where code to
 100 increment a counter can be directly inlined with the translation.
 101 Currently only a simple increment is supported. This is not atomic so
 102 can miss counts. If you want absolute precision you should use a
 103 callback which can then ensure atomicity itself.
 104
 105 Finally when QEMU exits all the registered *atexit* callbacks are
 106 invoked.
 107
 108 Internals
 109 =========
 110
 111 Locking
 112 -------
 113
 114 We have to ensure we cannot deadlock, particularly under MTTCG. For
 115 this we acquire a lock when called from plugin code. We also keep the
 116 list of callbacks under RCU so that we do not have to hold the lock
 117 when calling the callbacks. This is also for performance, since some
 118 callbacks (e.g. memory access callbacks) might be called very
 119 frequently.
 120
 121   * A consequence of this is that we keep our own list of CPUs, so that
 122     we do not have to worry about locking order wrt cpu_list_lock.
 123   * Use a recursive lock, since we can get registration calls from
 124     callbacks.
 125
 126 As a result registering/unregistering callbacks is "slow", since it
 127 takes a lock. But this is very infrequent; we want performance when
 128 calling (or not calling) callbacks, not when registering them. Using
 129 RCU is great for this.
 130
 131 We support the uninstallation of a plugin at any time (e.g. from
 132 plugin callbacks). This allows plugins to remove themselves if they no
 133 longer want to instrument the code. This operation is asynchronous
 134 which means callbacks may still occur after the uninstall operation is
 135 requested. The plugin isn't completely uninstalled until the safe work
 136 has executed while all vCPUs are quiescent.
 137
 138 Example Plugins
 139 ===============
 140
 141 There are a number of plugins included with QEMU and you are
 142 encouraged to contribute your own plugins plugins upstream. There is a
 143 `contrib/plugins` directory where they can go.
 144
 145 - tests/plugins
 146
 147 These are some basic plugins that are used to test and exercise the
 148 API during the `make check-tcg` target.
 149
 150 - contrib/plugins/hotblocks.c
 151
 152 The hotblocks plugin allows you to examine the where hot paths of
 153 execution are in your program. Once the program has finished you will
 154 get a sorted list of blocks reporting the starting PC, translation
 155 count, number of instructions and execution count. This will work best
 156 with linux-user execution as system emulation tends to generate
 157 re-translations as blocks from different programs get swapped in and
 158 out of system memory.
 159
 160 If your program is single-threaded you can use the `inline` option for
 161 slightly faster (but not thread safe) counters.
 162
 163 Example::
 164
 165   ./aarch64-linux-user/qemu-aarch64 \
 166     -plugin contrib/plugins/libhotblocks.so -d plugin \
 167     ./tests/tcg/aarch64-linux-user/sha1
 168   SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
 169   collected 903 entries in the hash table
 170   pc, tcount, icount, ecount
 171   0x0000000041ed10, 1, 5, 66087
 172   0x000000004002b0, 1, 4, 66087
 173   ...
 174
 175 - contrib/plugins/hotpages.c
 176
 177 Similar to hotblocks but this time tracks memory accesses::
 178
 179   ./aarch64-linux-user/qemu-aarch64 \
 180     -plugin contrib/plugins/libhotpages.so -d plugin \
 181     ./tests/tcg/aarch64-linux-user/sha1
 182   SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
 183   Addr, RCPUs, Reads, WCPUs, Writes
 184   0x000055007fe000, 0x0001, 31747952, 0x0001, 8835161
 185   0x000055007ff000, 0x0001, 29001054, 0x0001, 8780625
 186   0x00005500800000, 0x0001, 687465, 0x0001, 335857
 187   0x0000000048b000, 0x0001, 130594, 0x0001, 355
 188   0x0000000048a000, 0x0001, 1826, 0x0001, 11
 189
 190 - contrib/plugins/howvec.c
 191
 192 This is an instruction classifier so can be used to count different
 193 types of instructions. It has a number of options to refine which get
 194 counted. You can give an argument for a class of instructions to break
 195 it down fully, so for example to see all the system registers
 196 accesses::
 197
 198   ./aarch64-softmmu/qemu-system-aarch64 $(QEMU_ARGS) \
 199     -append "root=/dev/sda2 systemd.unit=benchmark.service" \
 200     -smp 4 -plugin ./contrib/plugins/libhowvec.so,arg=sreg -d plugin
 201
 202 which will lead to a sorted list after the class breakdown::
 203
 204   Instruction Classes:
 205   Class:   UDEF                   not counted
 206   Class:   SVE                    (68 hits)
 207   Class:   PCrel addr             (47789483 hits)
 208   Class:   Add/Sub (imm)          (192817388 hits)
 209   Class:   Logical (imm)          (93852565 hits)
 210   Class:   Move Wide (imm)        (76398116 hits)
 211   Class:   Bitfield               (44706084 hits)
 212   Class:   Extract                (5499257 hits)
 213   Class:   Cond Branch (imm)      (147202932 hits)
 214   Class:   Exception Gen          (193581 hits)
 215   Class:     NOP                  not counted
 216   Class:   Hints                  (6652291 hits)
 217   Class:   Barriers               (8001661 hits)
 218   Class:   PSTATE                 (1801695 hits)
 219   Class:   System Insn            (6385349 hits)
 220   Class:   System Reg             counted individually
 221   Class:   Branch (reg)           (69497127 hits)
 222   Class:   Branch (imm)           (84393665 hits)
 223   Class:   Cmp & Branch           (110929659 hits)
 224   Class:   Tst & Branch           (44681442 hits)
 225   Class:   AdvSimd ldstmult       (736 hits)
 226   Class:   ldst excl              (9098783 hits)
 227   Class:   Load Reg (lit)         (87189424 hits)
 228   Class:   ldst noalloc pair      (3264433 hits)
 229   Class:   ldst pair              (412526434 hits)
 230   Class:   ldst reg (imm)         (314734576 hits)
 231   Class: Loads & Stores           (2117774 hits)
 232   Class: Data Proc Reg            (223519077 hits)
 233   Class: Scalar FP                (31657954 hits)
 234   Individual Instructions:
 235   Instr: mrs x0, sp_el0           (2682661 hits)  (op=0xd5384100/  System Reg)
 236   Instr: mrs x1, tpidr_el2        (1789339 hits)  (op=0xd53cd041/  System Reg)
 237   Instr: mrs x2, tpidr_el2        (1513494 hits)  (op=0xd53cd042/  System Reg)
 238   Instr: mrs x0, tpidr_el2        (1490823 hits)  (op=0xd53cd040/  System Reg)
 239   Instr: mrs x1, sp_el0           (933793 hits)   (op=0xd5384101/  System Reg)
 240   Instr: mrs x2, sp_el0           (699516 hits)   (op=0xd5384102/  System Reg)
 241   Instr: mrs x4, tpidr_el2        (528437 hits)   (op=0xd53cd044/  System Reg)
 242   Instr: mrs x30, ttbr1_el1       (480776 hits)   (op=0xd538203e/  System Reg)
 243   Instr: msr ttbr1_el1, x30       (480713 hits)   (op=0xd518203e/  System Reg)
 244   Instr: msr vbar_el1, x30        (480671 hits)   (op=0xd518c01e/  System Reg)
 245   ...
 246
 247 To find the argument shorthand for the class you need to examine the
 248 source code of the plugin at the moment, specifically the `*opt`
 249 argument in the InsnClassExecCount tables.
 250
 251 - contrib/plugins/lockstep.c
 252
 253 This is a debugging tool for developers who want to find out when and
 254 where execution diverges after a subtle change to TCG code generation.
 255 It is not an exact science and results are likely to be mixed once
 256 asynchronous events are introduced. While the use of -icount can
 257 introduce determinism to the execution flow it doesn't always follow
 258 the translation sequence will be exactly the same. Typically this is
 259 caused by a timer firing to service the GUI causing a block to end
 260 early. However in some cases it has proved to be useful in pointing
 261 people at roughly where execution diverges. The only argument you need
 262 for the plugin is a path for the socket the two instances will
 263 communicate over::
 264
 265
 266   ./sparc-softmmu/qemu-system-sparc -monitor none -parallel none \
 267     -net none -M SS-20 -m 256 -kernel day11/zImage.elf \
 268     -plugin ./contrib/plugins/liblockstep.so,arg=lockstep-sparc.sock \
 269   -d plugin,nochain
 270
 271 which will eventually report::
 272
 273   qemu-system-sparc: warning: nic lance.0 has no peer
 274   @ 0x000000ffd06678 vs 0x000000ffd001e0 (2/1 since last)
 275   @ 0x000000ffd07d9c vs 0x000000ffd06678 (3/1 since last)
 276   Δ insn_count @ 0x000000ffd07d9c (809900609) vs 0x000000ffd06678 (809900612)
 277     previously @ 0x000000ffd06678/10 (809900609 insns)
 278     previously @ 0x000000ffd001e0/4 (809900599 insns)
 279     previously @ 0x000000ffd080ac/2 (809900595 insns)
 280     previously @ 0x000000ffd08098/5 (809900593 insns)
 281     previously @ 0x000000ffd080c0/1 (809900588 insns)
 282