Merge tag 'pull-request-2022-12-04' of https://gitlab.com/thuth/qemu into staging
[qemu.git] / 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 QEMU TCG Plugins
7 ================
8
9 QEMU TCG plugins provide a way for users to run experiments taking
10 advantage of the total system control emulation can have over a guest.
11 It provides a mechanism for plugins to subscribe to events during
12 translation and execution and optionally callback into the plugin
13 during these events. TCG plugins are unable to change the system state
14 only monitor it passively. However they can do this down to an
15 individual instruction granularity including potentially subscribing
16 to all load and store operations.
17
18 Usage
19 -----
20
21 Any QEMU binary with TCG support has plugins enabled by default.
22 Earlier releases needed to be explicitly enabled with::
23
24   configure --enable-plugins
25
26 Once built a program can be run with multiple plugins loaded each with
27 their own arguments::
28
29   $QEMU $OTHER_QEMU_ARGS \
30       -plugin contrib/plugin/libhowvec.so,inline=on,count=hint \
31       -plugin contrib/plugin/libhotblocks.so
32
33 Arguments are plugin specific and can be used to modify their
34 behaviour. In this case the howvec plugin is being asked to use inline
35 ops to count and break down the hint instructions by type.
36
37 Linux user-mode emulation also evaluates the environment variable
38 ``QEMU_PLUGIN``::
39
40   QEMU_PLUGIN="file=contrib/plugins/libhowvec.so,inline=on,count=hint" $QEMU
41
42 Writing plugins
43 ---------------
44
45 API versioning
46 ~~~~~~~~~~~~~~
47
48 This is a new feature for QEMU and it does allow people to develop
49 out-of-tree plugins that can be dynamically linked into a running QEMU
50 process. However the project reserves the right to change or break the
51 API should it need to do so. The best way to avoid this is to submit
52 your plugin upstream so they can be updated if/when the API changes.
53
54 All plugins need to declare a symbol which exports the plugin API
55 version they were built against. This can be done simply by::
56
57   QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION;
58
59 The core code will refuse to load a plugin that doesn't export a
60 ``qemu_plugin_version`` symbol or if plugin version is outside of QEMU's
61 supported range of API versions.
62
63 Additionally the ``qemu_info_t`` structure which is passed to the
64 ``qemu_plugin_install`` method of a plugin will detail the minimum and
65 current API versions supported by QEMU. The API version will be
66 incremented if new APIs are added. The minimum API version will be
67 incremented if existing APIs are changed or removed.
68
69 Lifetime of the query handle
70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
72 Each callback provides an opaque anonymous information handle which
73 can usually be further queried to find out information about a
74 translation, instruction or operation. The handles themselves are only
75 valid during the lifetime of the callback so it is important that any
76 information that is needed is extracted during the callback and saved
77 by the plugin.
78
79 Plugin life cycle
80 ~~~~~~~~~~~~~~~~~
81
82 First the plugin is loaded and the public qemu_plugin_install function
83 is called. The plugin will then register callbacks for various plugin
84 events. Generally plugins will register a handler for the *atexit*
85 if they want to dump a summary of collected information once the
86 program/system has finished running.
87
88 When a registered event occurs the plugin callback is invoked. The
89 callbacks may provide additional information. In the case of a
90 translation event the plugin has an option to enumerate the
91 instructions in a block of instructions and optionally register
92 callbacks to some or all instructions when they are executed.
93
94 There is also a facility to add an inline event where code to
95 increment a counter can be directly inlined with the translation.
96 Currently only a simple increment is supported. This is not atomic so
97 can miss counts. If you want absolute precision you should use a
98 callback which can then ensure atomicity itself.
99
100 Finally when QEMU exits all the registered *atexit* callbacks are
101 invoked.
102
103 Exposure of QEMU internals
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106 The plugin architecture actively avoids leaking implementation details
107 about how QEMU's translation works to the plugins. While there are
108 conceptions such as translation time and translation blocks the
109 details are opaque to plugins. The plugin is able to query select
110 details of instructions and system configuration only through the
111 exported *qemu_plugin* functions.
112
113 API
114 ~~~
115
116 .. kernel-doc:: include/qemu/qemu-plugin.h
117
118 Internals
119 ---------
120
121 Locking
122 ~~~~~~~
123
124 We have to ensure we cannot deadlock, particularly under MTTCG. For
125 this we acquire a lock when called from plugin code. We also keep the
126 list of callbacks under RCU so that we do not have to hold the lock
127 when calling the callbacks. This is also for performance, since some
128 callbacks (e.g. memory access callbacks) might be called very
129 frequently.
130
131   * A consequence of this is that we keep our own list of CPUs, so that
132     we do not have to worry about locking order wrt cpu_list_lock.
133   * Use a recursive lock, since we can get registration calls from
134     callbacks.
135
136 As a result registering/unregistering callbacks is "slow", since it
137 takes a lock. But this is very infrequent; we want performance when
138 calling (or not calling) callbacks, not when registering them. Using
139 RCU is great for this.
140
141 We support the uninstallation of a plugin at any time (e.g. from
142 plugin callbacks). This allows plugins to remove themselves if they no
143 longer want to instrument the code. This operation is asynchronous
144 which means callbacks may still occur after the uninstall operation is
145 requested. The plugin isn't completely uninstalled until the safe work
146 has executed while all vCPUs are quiescent.
147
148 Example Plugins
149 ---------------
150
151 There are a number of plugins included with QEMU and you are
152 encouraged to contribute your own plugins plugins upstream. There is a
153 ``contrib/plugins`` directory where they can go.
154
155 - tests/plugins
156
157 These are some basic plugins that are used to test and exercise the
158 API during the ``make check-tcg`` target.
159
160 - contrib/plugins/hotblocks.c
161
162 The hotblocks plugin allows you to examine the where hot paths of
163 execution are in your program. Once the program has finished you will
164 get a sorted list of blocks reporting the starting PC, translation
165 count, number of instructions and execution count. This will work best
166 with linux-user execution as system emulation tends to generate
167 re-translations as blocks from different programs get swapped in and
168 out of system memory.
169
170 If your program is single-threaded you can use the ``inline`` option for
171 slightly faster (but not thread safe) counters.
172
173 Example::
174
175   ./aarch64-linux-user/qemu-aarch64 \
176     -plugin contrib/plugins/libhotblocks.so -d plugin \
177     ./tests/tcg/aarch64-linux-user/sha1
178   SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
179   collected 903 entries in the hash table
180   pc, tcount, icount, ecount
181   0x0000000041ed10, 1, 5, 66087
182   0x000000004002b0, 1, 4, 66087
183   ...
184
185 - contrib/plugins/hotpages.c
186
187 Similar to hotblocks but this time tracks memory accesses::
188
189   ./aarch64-linux-user/qemu-aarch64 \
190     -plugin contrib/plugins/libhotpages.so -d plugin \
191     ./tests/tcg/aarch64-linux-user/sha1
192   SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
193   Addr, RCPUs, Reads, WCPUs, Writes
194   0x000055007fe000, 0x0001, 31747952, 0x0001, 8835161
195   0x000055007ff000, 0x0001, 29001054, 0x0001, 8780625
196   0x00005500800000, 0x0001, 687465, 0x0001, 335857
197   0x0000000048b000, 0x0001, 130594, 0x0001, 355
198   0x0000000048a000, 0x0001, 1826, 0x0001, 11
199
200 The hotpages plugin can be configured using the following arguments:
201
202   * sortby=reads|writes|address
203
204   Log the data sorted by either the number of reads, the number of writes, or
205   memory address. (Default: entries are sorted by the sum of reads and writes)
206
207   * io=on
208
209   Track IO addresses. Only relevant to full system emulation. (Default: off)
210
211   * pagesize=N
212
213   The page size used. (Default: N = 4096)
214
215 - contrib/plugins/howvec.c
216
217 This is an instruction classifier so can be used to count different
218 types of instructions. It has a number of options to refine which get
219 counted. You can give a value to the ``count`` argument for a class of
220 instructions to break it down fully, so for example to see all the system
221 registers accesses::
222
223   ./aarch64-softmmu/qemu-system-aarch64 $(QEMU_ARGS) \
224     -append "root=/dev/sda2 systemd.unit=benchmark.service" \
225     -smp 4 -plugin ./contrib/plugins/libhowvec.so,count=sreg -d plugin
226
227 which will lead to a sorted list after the class breakdown::
228
229   Instruction Classes:
230   Class:   UDEF                   not counted
231   Class:   SVE                    (68 hits)
232   Class:   PCrel addr             (47789483 hits)
233   Class:   Add/Sub (imm)          (192817388 hits)
234   Class:   Logical (imm)          (93852565 hits)
235   Class:   Move Wide (imm)        (76398116 hits)
236   Class:   Bitfield               (44706084 hits)
237   Class:   Extract                (5499257 hits)
238   Class:   Cond Branch (imm)      (147202932 hits)
239   Class:   Exception Gen          (193581 hits)
240   Class:     NOP                  not counted
241   Class:   Hints                  (6652291 hits)
242   Class:   Barriers               (8001661 hits)
243   Class:   PSTATE                 (1801695 hits)
244   Class:   System Insn            (6385349 hits)
245   Class:   System Reg             counted individually
246   Class:   Branch (reg)           (69497127 hits)
247   Class:   Branch (imm)           (84393665 hits)
248   Class:   Cmp & Branch           (110929659 hits)
249   Class:   Tst & Branch           (44681442 hits)
250   Class:   AdvSimd ldstmult       (736 hits)
251   Class:   ldst excl              (9098783 hits)
252   Class:   Load Reg (lit)         (87189424 hits)
253   Class:   ldst noalloc pair      (3264433 hits)
254   Class:   ldst pair              (412526434 hits)
255   Class:   ldst reg (imm)         (314734576 hits)
256   Class: Loads & Stores           (2117774 hits)
257   Class: Data Proc Reg            (223519077 hits)
258   Class: Scalar FP                (31657954 hits)
259   Individual Instructions:
260   Instr: mrs x0, sp_el0           (2682661 hits)  (op=0xd5384100/  System Reg)
261   Instr: mrs x1, tpidr_el2        (1789339 hits)  (op=0xd53cd041/  System Reg)
262   Instr: mrs x2, tpidr_el2        (1513494 hits)  (op=0xd53cd042/  System Reg)
263   Instr: mrs x0, tpidr_el2        (1490823 hits)  (op=0xd53cd040/  System Reg)
264   Instr: mrs x1, sp_el0           (933793 hits)   (op=0xd5384101/  System Reg)
265   Instr: mrs x2, sp_el0           (699516 hits)   (op=0xd5384102/  System Reg)
266   Instr: mrs x4, tpidr_el2        (528437 hits)   (op=0xd53cd044/  System Reg)
267   Instr: mrs x30, ttbr1_el1       (480776 hits)   (op=0xd538203e/  System Reg)
268   Instr: msr ttbr1_el1, x30       (480713 hits)   (op=0xd518203e/  System Reg)
269   Instr: msr vbar_el1, x30        (480671 hits)   (op=0xd518c01e/  System Reg)
270   ...
271
272 To find the argument shorthand for the class you need to examine the
273 source code of the plugin at the moment, specifically the ``*opt``
274 argument in the InsnClassExecCount tables.
275
276 - contrib/plugins/lockstep.c
277
278 This is a debugging tool for developers who want to find out when and
279 where execution diverges after a subtle change to TCG code generation.
280 It is not an exact science and results are likely to be mixed once
281 asynchronous events are introduced. While the use of -icount can
282 introduce determinism to the execution flow it doesn't always follow
283 the translation sequence will be exactly the same. Typically this is
284 caused by a timer firing to service the GUI causing a block to end
285 early. However in some cases it has proved to be useful in pointing
286 people at roughly where execution diverges. The only argument you need
287 for the plugin is a path for the socket the two instances will
288 communicate over::
289
290
291   ./sparc-softmmu/qemu-system-sparc -monitor none -parallel none \
292     -net none -M SS-20 -m 256 -kernel day11/zImage.elf \
293     -plugin ./contrib/plugins/liblockstep.so,sockpath=lockstep-sparc.sock \
294   -d plugin,nochain
295
296 which will eventually report::
297
298   qemu-system-sparc: warning: nic lance.0 has no peer
299   @ 0x000000ffd06678 vs 0x000000ffd001e0 (2/1 since last)
300   @ 0x000000ffd07d9c vs 0x000000ffd06678 (3/1 since last)
301   Δ insn_count @ 0x000000ffd07d9c (809900609) vs 0x000000ffd06678 (809900612)
302     previously @ 0x000000ffd06678/10 (809900609 insns)
303     previously @ 0x000000ffd001e0/4 (809900599 insns)
304     previously @ 0x000000ffd080ac/2 (809900595 insns)
305     previously @ 0x000000ffd08098/5 (809900593 insns)
306     previously @ 0x000000ffd080c0/1 (809900588 insns)
307
308 - contrib/plugins/hwprofile.c
309
310 The hwprofile tool can only be used with system emulation and allows
311 the user to see what hardware is accessed how often. It has a number of options:
312
313  * track=read or track=write
314
315  By default the plugin tracks both reads and writes. You can use one
316  of these options to limit the tracking to just one class of accesses.
317
318  * source
319
320  Will include a detailed break down of what the guest PC that made the
321  access was. Not compatible with the pattern option. Example output::
322
323    cirrus-low-memory @ 0xfffffd00000a0000
324     pc:fffffc0000005cdc, 1, 256
325     pc:fffffc0000005ce8, 1, 256
326     pc:fffffc0000005cec, 1, 256
327
328  * pattern
329
330  Instead break down the accesses based on the offset into the HW
331  region. This can be useful for seeing the most used registers of a
332  device. Example output::
333
334     pci0-conf @ 0xfffffd01fe000000
335       off:00000004, 1, 1
336       off:00000010, 1, 3
337       off:00000014, 1, 3
338       off:00000018, 1, 2
339       off:0000001c, 1, 2
340       off:00000020, 1, 2
341       ...
342
343 - contrib/plugins/execlog.c
344
345 The execlog tool traces executed instructions with memory access. It can be used
346 for debugging and security analysis purposes.
347 Please be aware that this will generate a lot of output.
348
349 The plugin takes no argument::
350
351   qemu-system-arm $(QEMU_ARGS) \
352     -plugin ./contrib/plugins/libexeclog.so -d plugin
353
354 which will output an execution trace following this structure::
355
356   # vCPU, vAddr, opcode, disassembly[, load/store, memory addr, device]...
357   0, 0xa12, 0xf8012400, "movs r4, #0"
358   0, 0xa14, 0xf87f42b4, "cmp r4, r6"
359   0, 0xa16, 0xd206, "bhs #0xa26"
360   0, 0xa18, 0xfff94803, "ldr r0, [pc, #0xc]", load, 0x00010a28, RAM
361   0, 0xa1a, 0xf989f000, "bl #0xd30"
362   0, 0xd30, 0xfff9b510, "push {r4, lr}", store, 0x20003ee0, RAM, store, 0x20003ee4, RAM
363   0, 0xd32, 0xf9893014, "adds r0, #0x14"
364   0, 0xd34, 0xf9c8f000, "bl #0x10c8"
365   0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM
366
367 - contrib/plugins/cache.c
368
369 Cache modelling plugin that measures the performance of a given L1 cache
370 configuration, and optionally a unified L2 per-core cache when a given working
371 set is run::
372
373     qemu-x86_64 -plugin ./contrib/plugins/libcache.so \
374       -d plugin -D cache.log ./tests/tcg/x86_64-linux-user/float_convs
375
376 will report the following::
377
378     core #, data accesses, data misses, dmiss rate, insn accesses, insn misses, imiss rate
379     0       996695         508             0.0510%  2642799        18617           0.7044%
380
381     address, data misses, instruction
382     0x424f1e (_int_malloc), 109, movq %rax, 8(%rcx)
383     0x41f395 (_IO_default_xsputn), 49, movb %dl, (%rdi, %rax)
384     0x42584d (ptmalloc_init.part.0), 33, movaps %xmm0, (%rax)
385     0x454d48 (__tunables_init), 20, cmpb $0, (%r8)
386     ...
387
388     address, fetch misses, instruction
389     0x4160a0 (__vfprintf_internal), 744, movl $1, %ebx
390     0x41f0a0 (_IO_setb), 744, endbr64
391     0x415882 (__vfprintf_internal), 744, movq %r12, %rdi
392     0x4268a0 (__malloc), 696, andq $0xfffffffffffffff0, %rax
393     ...
394
395 The plugin has a number of arguments, all of them are optional:
396
397   * limit=N
398
399   Print top N icache and dcache thrashing instructions along with their
400   address, number of misses, and its disassembly. (default: 32)
401
402   * icachesize=N
403   * iblksize=B
404   * iassoc=A
405
406   Instruction cache configuration arguments. They specify the cache size, block
407   size, and associativity of the instruction cache, respectively.
408   (default: N = 16384, B = 64, A = 8)
409
410   * dcachesize=N
411   * dblksize=B
412   * dassoc=A
413
414   Data cache configuration arguments. They specify the cache size, block size,
415   and associativity of the data cache, respectively.
416   (default: N = 16384, B = 64, A = 8)
417
418   * evict=POLICY
419
420   Sets the eviction policy to POLICY. Available policies are: :code:`lru`,
421   :code:`fifo`, and :code:`rand`. The plugin will use the specified policy for
422   both instruction and data caches. (default: POLICY = :code:`lru`)
423
424   * cores=N
425
426   Sets the number of cores for which we maintain separate icache and dcache.
427   (default: for linux-user, N = 1, for full system emulation: N = cores
428   available to guest)
429
430   * l2=on
431
432   Simulates a unified L2 cache (stores blocks for both instructions and data)
433   using the default L2 configuration (cache size = 2MB, associativity = 16-way,
434   block size = 64B).
435
436   * l2cachesize=N
437   * l2blksize=B
438   * l2assoc=A
439
440   L2 cache configuration arguments. They specify the cache size, block size, and
441   associativity of the L2 cache, respectively. Setting any of the L2
442   configuration arguments implies ``l2=on``.
443   (default: N = 2097152 (2MB), B = 64, A = 16)