1Emulation 2========= 3 4QEMU's Tiny Code Generator (TCG) provides the ability to emulate a 5number of CPU architectures on any supported host platform. Both 6:ref:`System Emulation` and :ref:`User Mode Emulation` are supported 7depending on the guest architecture. 8 9.. list-table:: Supported Guest Architectures for Emulation 10 :widths: 30 10 10 50 11 :header-rows: 1 12 13 * - Architecture (qemu name) 14 - System 15 - User 16 - Notes 17 * - Alpha 18 - Yes 19 - Yes 20 - Legacy 64 bit RISC ISA developed by DEC 21 * - Arm (arm, aarch64) 22 - :ref:`Yes<ARM-System-emulator>` 23 - Yes 24 - Wide range of features, see :ref:`Arm Emulation` for details 25 * - AVR 26 - :ref:`Yes<AVR-System-emulator>` 27 - No 28 - 8 bit micro controller, often used in maker projects 29 * - Hexagon 30 - No 31 - Yes 32 - Family of DSPs by Qualcomm 33 * - PA-RISC (hppa) 34 - Yes 35 - Yes 36 - A legacy RISC system used in HP's old minicomputers 37 * - x86 (i386, x86_64) 38 - :ref:`Yes<QEMU-PC-System-emulator>` 39 - Yes 40 - The ubiquitous desktop PC CPU architecture, 32 and 64 bit. 41 * - LoongArch 42 - Yes 43 - Yes 44 - A MIPS-like 64bit RISC architecture developed in China 45 * - m68k 46 - :ref:`Yes<ColdFire-System-emulator>` 47 - Yes 48 - Motorola 68000 variants and ColdFire 49 * - Microblaze 50 - Yes 51 - Yes 52 - RISC based soft-core by Xilinx 53 * - MIPS (mips*) 54 - :ref:`Yes<MIPS-System-emulator>` 55 - Yes 56 - Venerable RISC architecture originally out of Stanford University 57 * - OpenRISC 58 - :ref:`Yes<OpenRISC-System-emulator>` 59 - Yes 60 - Open source RISC architecture developed by the OpenRISC community 61 * - Power (ppc, ppc64) 62 - :ref:`Yes<PowerPC-System-emulator>` 63 - Yes 64 - A general purpose RISC architecture now managed by IBM 65 * - RISC-V 66 - :ref:`Yes<RISC-V-System-emulator>` 67 - Yes 68 - An open standard RISC ISA maintained by RISC-V International 69 * - RX 70 - :ref:`Yes<RX-System-emulator>` 71 - No 72 - A 32 bit micro controller developed by Renesas 73 * - s390x 74 - :ref:`Yes<s390x-System-emulator>` 75 - Yes 76 - A 64 bit CPU found in IBM's System Z mainframes 77 * - sh4 78 - Yes 79 - Yes 80 - A 32 bit RISC embedded CPU developed by Hitachi 81 * - SPARC (sparc, sparc64) 82 - :ref:`Yes<Sparc32-System-emulator>` 83 - Yes 84 - A RISC ISA originally developed by Sun Microsystems 85 * - Tricore 86 - Yes 87 - No 88 - A 32 bit RISC/uController/DSP developed by Infineon 89 * - Xtensa 90 - :ref:`Yes<Xtensa-System-emulator>` 91 - Yes 92 - A configurable 32 bit soft core now owned by Cadence 93 94.. _Semihosting: 95 96Semihosting 97----------- 98 99Semihosting is a feature defined by the owner of the architecture to 100allow programs to interact with a debugging host system. On real 101hardware this is usually provided by an In-circuit emulator (ICE) 102hooked directly to the board. QEMU's implementation allows for 103semihosting calls to be passed to the host system or via the 104``gdbstub``. 105 106Generally semihosting makes it easier to bring up low level code before a 107more fully functional operating system has been enabled. On QEMU it 108also allows for embedded micro-controller code which typically doesn't 109have a full libc to be run as "bare-metal" code under QEMU's user-mode 110emulation. It is also useful for writing test cases and indeed a 111number of compiler suites as well as QEMU itself use semihosting calls 112to exit test code while reporting the success state. 113 114Semihosting is only available using TCG emulation. This is because the 115instructions to trigger a semihosting call are typically reserved 116causing most hypervisors to trap and fault on them. 117 118.. warning:: 119 Semihosting inherently bypasses any isolation there may be between 120 the guest and the host. As a result a program using semihosting can 121 happily trash your host system. Some semihosting calls (e.g. 122 ``SYS_READC``) can block execution indefinitely. You should only 123 ever run trusted code with semihosting enabled. 124 125Redirection 126~~~~~~~~~~~ 127 128Semihosting calls can be re-directed to a (potentially remote) gdb 129during debugging via the :ref:`gdbstub<GDB usage>`. Output to the 130semihosting console is configured as a ``chardev`` so can be 131redirected to a file, pipe or socket like any other ``chardev`` 132device. 133 134Supported Targets 135~~~~~~~~~~~~~~~~~ 136 137Most targets offer similar semihosting implementations with some 138minor changes to define the appropriate instruction to encode the 139semihosting call and which registers hold the parameters. They tend to 140presents a simple POSIX-like API which allows your program to read and 141write files, access the console and some other basic interactions. 142 143For full details of the ABI for a particular target, and the set of 144calls it provides, you should consult the semihosting specification 145for that architecture. 146 147.. note:: 148 QEMU makes an implementation decision to implement all file 149 access in ``O_BINARY`` mode. The user-visible effect of this is 150 regardless of the text/binary mode the program sets QEMU will 151 always select a binary mode ensuring no line-terminator conversion 152 is performed on input or output. This is because gdb semihosting 153 support doesn't make the distinction between the modes and 154 magically processing line endings can be confusing. 155 156.. list-table:: Guest Architectures supporting Semihosting 157 :widths: 10 10 80 158 :header-rows: 1 159 160 * - Architecture 161 - Modes 162 - Specification 163 * - Arm 164 - System and User-mode 165 - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst 166 * - m68k 167 - System 168 - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD 169 * - MIPS 170 - System 171 - Unified Hosting Interface (MD01069) 172 * - RISC-V 173 - System and User-mode 174 - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc 175 * - Xtensa 176 - System 177 - Tensilica ISS SIMCALL 178 179TCG Plugins 180----------- 181 182QEMU TCG plugins provide a way for users to run experiments taking 183advantage of the total system control emulation can have over a guest. 184It provides a mechanism for plugins to subscribe to events during 185translation and execution and optionally callback into the plugin 186during these events. TCG plugins are unable to change the system state 187only monitor it passively. However they can do this down to an 188individual instruction granularity including potentially subscribing 189to all load and store operations. 190 191See the developer section of the manual for details about 192:ref:`writing plugins<TCG Plugins>`. 193 194Usage 195~~~~~ 196 197Any QEMU binary with TCG support has plugins enabled by default. 198Earlier releases needed to be explicitly enabled with:: 199 200 configure --enable-plugins 201 202Once built a program can be run with multiple plugins loaded each with 203their own arguments:: 204 205 $QEMU $OTHER_QEMU_ARGS \ 206 -plugin contrib/plugins/libhowvec.so,inline=on,count=hint \ 207 -plugin contrib/plugins/libhotblocks.so 208 209Arguments are plugin specific and can be used to modify their 210behaviour. In this case the howvec plugin is being asked to use inline 211ops to count and break down the hint instructions by type. 212 213Linux user-mode emulation also evaluates the environment variable 214``QEMU_PLUGIN``:: 215 216 QEMU_PLUGIN="file=contrib/plugins/libhowvec.so,inline=on,count=hint" $QEMU 217 218QEMU plugins avoid to write directly to stdin/stderr, and use the log provided 219by the API (see function ``qemu_plugin_outs``). 220To show output, you may use this additional parameter:: 221 222 $QEMU $OTHER_QEMU_ARGS \ 223 -d plugin \ 224 -plugin contrib/plugins/libhowvec.so,inline=on,count=hint 225 226Example Plugins 227~~~~~~~~~~~~~~~ 228 229There are a number of plugins included with QEMU and you are 230encouraged to contribute your own plugins plugins upstream. There is a 231``contrib/plugins`` directory where they can go. There are also some 232basic plugins that are used to test and exercise the API during the 233``make check-tcg`` target in ``tests/tcg/plugins`` that are never the 234less useful for basic analysis. 235 236Empty 237..... 238 239``tests/tcg/plugins/empty.c`` 240 241Purely a test plugin for measuring the overhead of the plugins system 242itself. Does no instrumentation. 243 244Basic Blocks 245............ 246 247``tests/tcg/plugins/bb.c`` 248 249A very basic plugin which will measure execution in coarse terms as 250each basic block is executed. By default the results are shown once 251execution finishes:: 252 253 $ qemu-aarch64 -plugin tests/plugin/libbb.so \ 254 -d plugin ./tests/tcg/aarch64-linux-user/sha1 255 SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6 256 bb's: 2277338, insns: 158483046 257 258Behaviour can be tweaked with the following arguments: 259 260.. list-table:: Basic Block plugin arguments 261 :widths: 20 80 262 :header-rows: 1 263 264 * - Option 265 - Description 266 * - inline=true|false 267 - Use faster inline addition of a single counter. 268 * - idle=true|false 269 - Dump the current execution stats whenever the guest vCPU idles 270 271Basic Block Vectors 272................... 273 274``contrib/plugins/bbv.c`` 275 276The bbv plugin allows you to generate basic block vectors for use with the 277`SimPoint <https://cseweb.ucsd.edu/~calder/simpoint/>`__ analysis tool. 278 279.. list-table:: Basic block vectors arguments 280 :widths: 20 80 281 :header-rows: 1 282 283 * - Option 284 - Description 285 * - interval=N 286 - The interval to generate a basic block vector specified by the number of 287 instructions (Default: N = 100000000) 288 * - outfile=PATH 289 - The path to output files. 290 It will be suffixed with ``.N.bb`` where ``N`` is a vCPU index. 291 292Example:: 293 294 $ qemu-aarch64 \ 295 -plugin contrib/plugins/libbbv.so,interval=100,outfile=sha1 \ 296 tests/tcg/aarch64-linux-user/sha1 297 SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6 298 $ du sha1.0.bb 299 23128 sha1.0.bb 300 301Instruction 302........... 303 304``tests/tcg/plugins/insn.c`` 305 306This is a basic instruction level instrumentation which can count the 307number of instructions executed on each core/thread:: 308 309 $ qemu-aarch64 -plugin tests/plugin/libinsn.so \ 310 -d plugin ./tests/tcg/aarch64-linux-user/threadcount 311 Created 10 threads 312 Done 313 cpu 0 insns: 46765 314 cpu 1 insns: 3694 315 cpu 2 insns: 3694 316 cpu 3 insns: 2994 317 cpu 4 insns: 1497 318 cpu 5 insns: 1497 319 cpu 6 insns: 1497 320 cpu 7 insns: 1497 321 total insns: 63135 322 323Behaviour can be tweaked with the following arguments: 324 325.. list-table:: Instruction plugin arguments 326 :widths: 20 80 327 :header-rows: 1 328 329 * - Option 330 - Description 331 * - inline=true|false 332 - Use faster inline addition of a single counter. 333 * - sizes=true|false 334 - Give a summary of the instruction sizes for the execution 335 * - match=<string> 336 - Only instrument instructions matching the string prefix 337 338The ``match`` option will show some basic stats including how many 339instructions have executed since the last execution. For 340example:: 341 342 $ qemu-aarch64 -plugin tests/plugin/libinsn.so,match=bl \ 343 -d plugin ./tests/tcg/aarch64-linux-user/sha512-vector 344 ... 345 0x40069c, 'bl #0x4002b0', 10 hits, 1093 match hits, Δ+1257 since last match, 98 avg insns/match 346 0x4006ac, 'bl #0x403690', 10 hits, 1094 match hits, Δ+47 since last match, 98 avg insns/match 347 0x4037fc, 'bl #0x4002b0', 18 hits, 1095 match hits, Δ+22 since last match, 98 avg insns/match 348 0x400720, 'bl #0x403690', 10 hits, 1096 match hits, Δ+58 since last match, 98 avg insns/match 349 0x4037fc, 'bl #0x4002b0', 19 hits, 1097 match hits, Δ+22 since last match, 98 avg insns/match 350 0x400730, 'bl #0x403690', 10 hits, 1098 match hits, Δ+33 since last match, 98 avg insns/match 351 0x4037ac, 'bl #0x4002b0', 12 hits, 1099 match hits, Δ+20 since last match, 98 avg insns/match 352 ... 353 354For more detailed execution tracing see the ``execlog`` plugin for 355other options. 356 357Memory 358...... 359 360``tests/tcg/plugins/mem.c`` 361 362Basic instruction level memory instrumentation:: 363 364 $ qemu-aarch64 -plugin tests/plugin/libmem.so,inline=true \ 365 -d plugin ./tests/tcg/aarch64-linux-user/sha1 366 SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6 367 inline mem accesses: 79525013 368 369Behaviour can be tweaked with the following arguments: 370 371.. list-table:: Memory plugin arguments 372 :widths: 20 80 373 :header-rows: 1 374 375 * - Option 376 - Description 377 * - inline=true|false 378 - Use faster inline addition of a single counter 379 * - callback=true|false 380 - Use callbacks on each memory instrumentation. 381 * - hwaddr=true|false 382 - Count IO accesses (only for system emulation) 383 384System Calls 385............ 386 387``tests/tcg/plugins/syscall.c`` 388 389A basic syscall tracing plugin. This only works for user-mode. By 390default it will give a summary of syscall stats at the end of the 391run:: 392 393 $ qemu-aarch64 -plugin tests/plugin/libsyscall \ 394 -d plugin ./tests/tcg/aarch64-linux-user/threadcount 395 Created 10 threads 396 Done 397 syscall no. calls errors 398 226 12 0 399 99 11 11 400 115 11 0 401 222 11 0 402 93 10 0 403 220 10 0 404 233 10 0 405 215 8 0 406 214 4 0 407 134 2 0 408 64 2 0 409 96 1 0 410 94 1 0 411 80 1 0 412 261 1 0 413 78 1 0 414 160 1 0 415 135 1 0 416 417Behaviour can be tweaked with the following arguments: 418 419.. list-table:: Syscall plugin arguments 420 :widths: 20 80 421 :header-rows: 1 422 423 * - Option 424 - Description 425 * - print=true|false 426 - Print the number of times each syscall is called 427 * - log_writes=true|false 428 - Log the buffer of each write syscall in hexdump format 429 430Test inline operations 431...................... 432 433``tests/plugins/inline.c`` 434 435This plugin is used for testing all inline operations, conditional callbacks and 436scoreboard. It prints a per-cpu summary of all events. 437 438 439Hot Blocks 440.......... 441 442``contrib/plugins/hotblocks.c`` 443 444The hotblocks plugin allows you to examine the where hot paths of 445execution are in your program. Once the program has finished you will 446get a sorted list of blocks reporting the starting PC, translation 447count, number of instructions and execution count. This will work best 448with linux-user execution as system emulation tends to generate 449re-translations as blocks from different programs get swapped in and 450out of system memory. 451 452Example:: 453 454 $ qemu-aarch64 \ 455 -plugin contrib/plugins/libhotblocks.so -d plugin \ 456 ./tests/tcg/aarch64-linux-user/sha1 457 SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6 458 collected 903 entries in the hash table 459 pc, tcount, icount, ecount 460 0x0000000041ed10, 1, 5, 66087 461 0x000000004002b0, 1, 4, 66087 462 ... 463 464 465Hot Pages 466......... 467 468``contrib/plugins/hotpages.c`` 469 470Similar to hotblocks but this time tracks memory accesses:: 471 472 $ qemu-aarch64 \ 473 -plugin contrib/plugins/libhotpages.so -d plugin \ 474 ./tests/tcg/aarch64-linux-user/sha1 475 SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6 476 Addr, RCPUs, Reads, WCPUs, Writes 477 0x000055007fe000, 0x0001, 31747952, 0x0001, 8835161 478 0x000055007ff000, 0x0001, 29001054, 0x0001, 8780625 479 0x00005500800000, 0x0001, 687465, 0x0001, 335857 480 0x0000000048b000, 0x0001, 130594, 0x0001, 355 481 0x0000000048a000, 0x0001, 1826, 0x0001, 11 482 483The hotpages plugin can be configured using the following arguments: 484 485.. list-table:: Hot pages arguments 486 :widths: 20 80 487 :header-rows: 1 488 489 * - Option 490 - Description 491 * - sortby=reads|writes|address 492 - Log the data sorted by either the number of reads, the number of writes, or 493 memory address. (Default: entries are sorted by the sum of reads and writes) 494 * - io=on 495 - Track IO addresses. Only relevant to full system emulation. (Default: off) 496 * - pagesize=N 497 - The page size used. (Default: N = 4096) 498 499Instruction Distribution 500........................ 501 502``contrib/plugins/howvec.c`` 503 504This is an instruction classifier so can be used to count different 505types of instructions. It has a number of options to refine which get 506counted. You can give a value to the ``count`` argument for a class of 507instructions to break it down fully, so for example to see all the system 508registers accesses:: 509 510 $ qemu-system-aarch64 $(QEMU_ARGS) \ 511 -append "root=/dev/sda2 systemd.unit=benchmark.service" \ 512 -smp 4 -plugin ./contrib/plugins/libhowvec.so,count=sreg -d plugin 513 514which will lead to a sorted list after the class breakdown:: 515 516 Instruction Classes: 517 Class: UDEF not counted 518 Class: SVE (68 hits) 519 Class: PCrel addr (47789483 hits) 520 Class: Add/Sub (imm) (192817388 hits) 521 Class: Logical (imm) (93852565 hits) 522 Class: Move Wide (imm) (76398116 hits) 523 Class: Bitfield (44706084 hits) 524 Class: Extract (5499257 hits) 525 Class: Cond Branch (imm) (147202932 hits) 526 Class: Exception Gen (193581 hits) 527 Class: NOP not counted 528 Class: Hints (6652291 hits) 529 Class: Barriers (8001661 hits) 530 Class: PSTATE (1801695 hits) 531 Class: System Insn (6385349 hits) 532 Class: System Reg counted individually 533 Class: Branch (reg) (69497127 hits) 534 Class: Branch (imm) (84393665 hits) 535 Class: Cmp & Branch (110929659 hits) 536 Class: Tst & Branch (44681442 hits) 537 Class: AdvSimd ldstmult (736 hits) 538 Class: ldst excl (9098783 hits) 539 Class: Load Reg (lit) (87189424 hits) 540 Class: ldst noalloc pair (3264433 hits) 541 Class: ldst pair (412526434 hits) 542 Class: ldst reg (imm) (314734576 hits) 543 Class: Loads & Stores (2117774 hits) 544 Class: Data Proc Reg (223519077 hits) 545 Class: Scalar FP (31657954 hits) 546 Individual Instructions: 547 Instr: mrs x0, sp_el0 (2682661 hits) (op=0xd5384100/ System Reg) 548 Instr: mrs x1, tpidr_el2 (1789339 hits) (op=0xd53cd041/ System Reg) 549 Instr: mrs x2, tpidr_el2 (1513494 hits) (op=0xd53cd042/ System Reg) 550 Instr: mrs x0, tpidr_el2 (1490823 hits) (op=0xd53cd040/ System Reg) 551 Instr: mrs x1, sp_el0 (933793 hits) (op=0xd5384101/ System Reg) 552 Instr: mrs x2, sp_el0 (699516 hits) (op=0xd5384102/ System Reg) 553 Instr: mrs x4, tpidr_el2 (528437 hits) (op=0xd53cd044/ System Reg) 554 Instr: mrs x30, ttbr1_el1 (480776 hits) (op=0xd538203e/ System Reg) 555 Instr: msr ttbr1_el1, x30 (480713 hits) (op=0xd518203e/ System Reg) 556 Instr: msr vbar_el1, x30 (480671 hits) (op=0xd518c01e/ System Reg) 557 ... 558 559To find the argument shorthand for the class you need to examine the 560source code of the plugin at the moment, specifically the ``*opt`` 561argument in the InsnClassExecCount tables. 562 563Lockstep Execution 564.................. 565 566``contrib/plugins/lockstep.c`` 567 568This is a debugging tool for developers who want to find out when and 569where execution diverges after a subtle change to TCG code generation. 570It is not an exact science and results are likely to be mixed once 571asynchronous events are introduced. While the use of -icount can 572introduce determinism to the execution flow it doesn't always follow 573the translation sequence will be exactly the same. Typically this is 574caused by a timer firing to service the GUI causing a block to end 575early. However in some cases it has proved to be useful in pointing 576people at roughly where execution diverges. The only argument you need 577for the plugin is a path for the socket the two instances will 578communicate over:: 579 580 581 $ qemu-system-sparc -monitor none -parallel none \ 582 -net none -M SS-20 -m 256 -kernel day11/zImage.elf \ 583 -plugin ./contrib/plugins/liblockstep.so,sockpath=lockstep-sparc.sock \ 584 -d plugin,nochain 585 586which will eventually report:: 587 588 qemu-system-sparc: warning: nic lance.0 has no peer 589 @ 0x000000ffd06678 vs 0x000000ffd001e0 (2/1 since last) 590 @ 0x000000ffd07d9c vs 0x000000ffd06678 (3/1 since last) 591 Δ insn_count @ 0x000000ffd07d9c (809900609) vs 0x000000ffd06678 (809900612) 592 previously @ 0x000000ffd06678/10 (809900609 insns) 593 previously @ 0x000000ffd001e0/4 (809900599 insns) 594 previously @ 0x000000ffd080ac/2 (809900595 insns) 595 previously @ 0x000000ffd08098/5 (809900593 insns) 596 previously @ 0x000000ffd080c0/1 (809900588 insns) 597 598 599Hardware Profile 600................ 601 602``contrib/plugins/hwprofile.c`` 603 604The hwprofile tool can only be used with system emulation and allows 605the user to see what hardware is accessed how often. It has a number of options: 606 607.. list-table:: Hardware Profile arguments 608 :widths: 20 80 609 :header-rows: 1 610 611 * - Option 612 - Description 613 * - track=[read|write] 614 - By default the plugin tracks both reads and writes. You can use 615 this option to limit the tracking to just one class of accesses. 616 * - source 617 - Will include a detailed break down of what the guest PC that made the 618 access was. Not compatible with the pattern option. Example output:: 619 620 cirrus-low-memory @ 0xfffffd00000a0000 621 pc:fffffc0000005cdc, 1, 256 622 pc:fffffc0000005ce8, 1, 256 623 pc:fffffc0000005cec, 1, 256 624 625 * - pattern 626 - Instead break down the accesses based on the offset into the HW 627 region. This can be useful for seeing the most used registers of 628 a device. Example output:: 629 630 pci0-conf @ 0xfffffd01fe000000 631 off:00000004, 1, 1 632 off:00000010, 1, 3 633 off:00000014, 1, 3 634 off:00000018, 1, 2 635 off:0000001c, 1, 2 636 off:00000020, 1, 2 637 ... 638 639 640Execution Log 641............. 642 643``contrib/plugins/execlog.c`` 644 645The execlog tool traces executed instructions with memory access. It can be used 646for debugging and security analysis purposes. 647Please be aware that this will generate a lot of output. 648 649The plugin needs default argument:: 650 651 $ qemu-system-arm $(QEMU_ARGS) \ 652 -plugin ./contrib/plugins/libexeclog.so -d plugin 653 654which will output an execution trace following this structure:: 655 656 # vCPU, vAddr, opcode, disassembly[, load/store, memory addr, device]... 657 0, 0xa12, 0xf8012400, "movs r4, #0" 658 0, 0xa14, 0xf87f42b4, "cmp r4, r6" 659 0, 0xa16, 0xd206, "bhs #0xa26" 660 0, 0xa18, 0xfff94803, "ldr r0, [pc, #0xc]", load, 0x00010a28, RAM 661 0, 0xa1a, 0xf989f000, "bl #0xd30" 662 0, 0xd30, 0xfff9b510, "push {r4, lr}", store, 0x20003ee0, RAM, store, 0x20003ee4, RAM 663 0, 0xd32, 0xf9893014, "adds r0, #0x14" 664 0, 0xd34, 0xf9c8f000, "bl #0x10c8" 665 0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM 666 667Please note that you need to configure QEMU with Capstone support to get disassembly. 668 669The output can be filtered to only track certain instructions or 670addresses using the ``ifilter`` or ``afilter`` options. You can stack the 671arguments if required:: 672 673 $ qemu-system-arm $(QEMU_ARGS) \ 674 -plugin ./contrib/plugins/libexeclog.so,ifilter=st1w,afilter=0x40001808 -d plugin 675 676This plugin can also dump registers when they change value. Specify the name of the 677registers with multiple ``reg`` options. You can also use glob style matching if you wish:: 678 679 $ qemu-system-arm $(QEMU_ARGS) \ 680 -plugin ./contrib/plugins/libexeclog.so,reg=\*_el2,reg=sp -d plugin 681 682Be aware that each additional register to check will slow down 683execution quite considerably. You can optimise the number of register 684checks done by using the rdisas option. This will only instrument 685instructions that mention the registers in question in disassembly. 686This is not foolproof as some instructions implicitly change 687instructions. You can use the ifilter to catch these cases:: 688 689 $ qemu-system-arm $(QEMU_ARGS) \ 690 -plugin ./contrib/plugins/libexeclog.so,ifilter=msr,ifilter=blr,reg=x30,reg=\*_el1,rdisas=on 691 692Cache Modelling 693............... 694 695``contrib/plugins/cache.c`` 696 697Cache modelling plugin that measures the performance of a given L1 cache 698configuration, and optionally a unified L2 per-core cache when a given working 699set is run:: 700 701 $ qemu-x86_64 -plugin ./contrib/plugins/libcache.so \ 702 -d plugin -D cache.log ./tests/tcg/x86_64-linux-user/float_convs 703 704will report the following:: 705 706 core #, data accesses, data misses, dmiss rate, insn accesses, insn misses, imiss rate 707 0 996695 508 0.0510% 2642799 18617 0.7044% 708 709 address, data misses, instruction 710 0x424f1e (_int_malloc), 109, movq %rax, 8(%rcx) 711 0x41f395 (_IO_default_xsputn), 49, movb %dl, (%rdi, %rax) 712 0x42584d (ptmalloc_init.part.0), 33, movaps %xmm0, (%rax) 713 0x454d48 (__tunables_init), 20, cmpb $0, (%r8) 714 ... 715 716 address, fetch misses, instruction 717 0x4160a0 (__vfprintf_internal), 744, movl $1, %ebx 718 0x41f0a0 (_IO_setb), 744, endbr64 719 0x415882 (__vfprintf_internal), 744, movq %r12, %rdi 720 0x4268a0 (__malloc), 696, andq $0xfffffffffffffff0, %rax 721 ... 722 723The plugin has a number of arguments, all of them are optional: 724 725.. list-table:: Cache modelling arguments 726 :widths: 20 80 727 :header-rows: 1 728 729 * - Option 730 - Description 731 * - limit=N 732 - Print top N icache and dcache thrashing instructions along with 733 their address, number of misses, and its disassembly. (default: 32) 734 * - icachesize=N 735 iblksize=B 736 iassoc=A 737 - Instruction cache configuration arguments. They specify the 738 cache size, block size, and associativity of the instruction 739 cache, respectively. (default: N = 16384, B = 64, A = 8) 740 * - dcachesize=N 741 - Data cache size (default: 16834) 742 * - dblksize=B 743 - Data cache block size (default: 64) 744 * - dassoc=A 745 - Data cache associativity (default: 8) 746 * - evict=POLICY 747 - Sets the eviction policy to POLICY. Available policies are: 748 ``lru``, ``fifo``, and ``rand``. The plugin will use 749 the specified policy for both instruction and data caches. 750 (default: POLICY = ``lru``) 751 * - cores=N 752 - Sets the number of cores for which we maintain separate icache 753 and dcache. (default: for linux-user, N = 1, for full system 754 emulation: N = cores available to guest) 755 * - l2=on 756 - Simulates a unified L2 cache (stores blocks for both 757 instructions and data) using the default L2 configuration (cache 758 size = 2MB, associativity = 16-way, block size = 64B). 759 * - l2cachesize=N 760 - L2 cache size (default: 2097152 (2MB)), implies ``l2=on`` 761 * - l2blksize=B 762 - L2 cache block size (default: 64), implies ``l2=on`` 763 * - l2assoc=A 764 - L2 cache associativity (default: 16), implies ``l2=on`` 765 766Stop on Trigger 767............... 768 769``contrib/plugins/stoptrigger.c`` 770 771The stoptrigger plugin allows to setup triggers to stop emulation. 772It can be used for research purposes to launch some code and precisely stop it 773and understand where its execution flow went. 774 775Two types of triggers can be configured: a count of instructions to stop at, 776or an address to stop at. Multiple triggers can be set at once. 777 778By default, QEMU will exit with return code 0. A custom return code can be 779configured for each trigger using ``:CODE`` syntax. 780 781For example, to stop at the 20-th instruction with return code 41, at address 7820xd4 with return code 0 or at address 0xd8 with return code 42:: 783 784 $ qemu-system-aarch64 $(QEMU_ARGS) \ 785 -plugin ./contrib/plugins/libstoptrigger.so,icount=20:41,addr=0xd4,addr=0xd8:42 -d plugin 786 787The plugin will log the reason of exit, for example:: 788 789 0xd4 reached, exiting 790 791Limit instructions per second 792............................. 793 794This plugin can limit the number of Instructions Per Second that are executed:: 795 796 # get number of instructions 797 $ num_insn=$(./build/qemu-x86_64 -plugin ./build/tests/plugin/libinsn.so -d plugin /bin/true |& grep total | sed -e 's/.*: //') 798 # limit speed to execute in 10 seconds 799 $ time ./build/qemu-x86_64 -plugin ./build/contrib/plugins/libips.so,ips=$(($num_insn/10)) /bin/true 800 real 10.000s 801 802 803.. list-table:: IPS arguments 804 :widths: 20 80 805 :header-rows: 1 806 807 * - Option 808 - Description 809 * - ips=N 810 - Maximum number of instructions per cpu that can be executed in one second. 811 The plugin will sleep when the given number of instructions is reached. 812 813Other emulation features 814------------------------ 815 816When running system emulation you can also enable deterministic 817execution which allows for repeatable record/replay debugging. See 818:ref:`Record/Replay<replay>` for more details. 819