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