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