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