docs/about/emulation.rst

9 .. list-table:: Supported Guest Architectures for Emulation
11   :header-rows: 1
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
97 -----------
101 hardware this is usually provided by an In-circuit emulator (ICE)
108 also allows for embedded micro-controller code which typically doesn't
109 have a full libc to be run as "bare-metal" code under QEMU's user-mode
122    ``SYS_READC``) can block execution indefinitely. You should only
128 Semihosting calls can be re-directed to a (potentially remote) gdb
140 presents a simple POSIX-like API which allows your program to read and
149    access in ``O_BINARY`` mode. The user-visible effect of this is
151    always select a binary mode ensuring no line-terminator conversion
156 .. list-table:: Guest Architectures supporting Semihosting
158   :header-rows: 1
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
180 -----------
200   configure --enable-plugins
206       -plugin contrib/plugins/libhowvec.so,inline=on,count=hint \
207       -plugin contrib/plugins/libhotblocks.so
213 Linux user-mode emulation also evaluates the environment variable
223     -d plugin \
224     -plugin contrib/plugins/libhowvec.so,inline=on,count=hint
233 ``make check-tcg`` target in ``tests/tcg/plugins`` that are never the
250 each basic block is executed. By default the results are shown once
253   $ qemu-aarch64 -plugin tests/plugin/libbb.so \
254       -d plugin ./tests/tcg/aarch64-linux-user/sha1
260 .. list-table:: Basic Block plugin arguments
262   :header-rows: 1
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
271 Basic Block Vectors
276 The bbv plugin allows you to generate basic block vectors for use with the
279 .. list-table:: Basic block vectors arguments
281   :header-rows: 1
283   * - Option
284     - Description
285   * - interval=N
286     - The interval to generate a basic block vector specified by the number of
288   * - outfile=PATH
289     - The path to output files.
294   $ qemu-aarch64 \
295     -plugin contrib/plugins/libbbv.so,interval=100,outfile=sha1 \
296     tests/tcg/aarch64-linux-user/sha1
309   $ qemu-aarch64 -plugin tests/plugin/libinsn.so \
310       -d plugin ./tests/tcg/aarch64-linux-user/threadcount
325 .. list-table:: Instruction plugin arguments
327   :header-rows: 1
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
342    $ qemu-aarch64 -plugin tests/plugin/libinsn.so,match=bl \
343        -d plugin ./tests/tcg/aarch64-linux-user/sha512-vector
364   $ qemu-aarch64 -plugin tests/plugin/libmem.so,inline=true \
365       -d plugin ./tests/tcg/aarch64-linux-user/sha1
371 .. list-table:: Memory plugin arguments
373   :header-rows: 1
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)
389 A basic syscall tracing plugin. This only works for user-mode. By
393   $ qemu-aarch64 -plugin tests/plugin/libsyscall \
394       -d plugin ./tests/tcg/aarch64-linux-user/threadcount
419 .. list-table:: Syscall plugin arguments
421   :header-rows: 1
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
436 scoreboard. It prints a per-cpu summary of all events.
448 with linux-user execution as system emulation tends to generate
449 re-translations as blocks from different programs get swapped in and
454   $ qemu-aarch64 \
455     -plugin contrib/plugins/libhotblocks.so -d plugin \
456     ./tests/tcg/aarch64-linux-user/sha1
472   $ qemu-aarch64 \
473     -plugin contrib/plugins/libhotpages.so -d plugin \
474     ./tests/tcg/aarch64-linux-user/sha1
485 .. list-table:: Hot pages arguments
487   :header-rows: 1
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
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)
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
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)
571 asynchronous events are introduced. While the use of -icount can
574 caused by a timer firing to service the GUI causing a block to end
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
588   qemu-system-sparc: warning: nic lance.0 has no peer
607 .. list-table:: Hardware Profile arguments
609   :header-rows: 1
611   * - Option
612     - Description
613   * - track=[read|write]
614     - By default the plugin tracks both reads and writes. You can use
616   * - source
617     - Will include a detailed break down of what the guest PC that made the
620         cirrus-low-memory @ 0xfffffd00000a0000
625   * - pattern
626     - Instead break down the accesses based on the offset into the HW
630         pci0-conf @ 0xfffffd01fe000000
651   $ qemu-system-arm $(QEMU_ARGS) \
652     -plugin ./contrib/plugins/libexeclog.so -d plugin
673   $ qemu-system-arm $(QEMU_ARGS) \
674     -plugin ./contrib/plugins/libexeclog.so,ifilter=st1w,afilter=0x40001808 -d plugin
679   $ qemu-system-arm $(QEMU_ARGS) \
680     -plugin ./contrib/plugins/libexeclog.so,reg=\*_el2,reg=sp -d plugin
689   $ qemu-system-arm $(QEMU_ARGS) \
690     -plugin ./contrib/plugins/libexeclog.so,ifilter=msr,ifilter=blr,reg=x30,reg=\*_el1,rdisas=on
692 Cache Modelling
695 ``contrib/plugins/cache.c``
697 Cache modelling plugin that measures the performance of a given L1 cache
698 configuration, and optionally a unified L2 per-core cache when a given working
701   $ qemu-x86_64 -plugin ./contrib/plugins/libcache.so \
702       -d plugin -D cache.log ./tests/tcg/x86_64-linux-user/float_convs
725 .. list-table:: Cache modelling arguments
727   :header-rows: 1
729   * - Option
730     - Description
731   * - limit=N
732     - Print top N icache and dcache thrashing instructions along with
734   * - icachesize=N
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:
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
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``
781 For example, to stop at the 20-th instruction with return code 41, at address
784   $ qemu-system-aarch64 $(QEMU_ARGS) \
785     -plugin ./contrib/plugins/libstoptrigger.so,icount=20:41,addr=0xd4,addr=0xd8:42 -d plugin
797 …$ num_insn=$(./build/qemu-x86_64 -plugin ./build/tests/plugin/libinsn.so -d plugin /bin/true |& gr…
799 …$ time ./build/qemu-x86_64 -plugin ./build/contrib/plugins/libips.so,ips=$(($num_insn/10)) /bin/tr…
803 .. list-table:: IPS arguments
805   :header-rows: 1
807   * - Option
808     - Description
809   * - ips=N
810     - Maximum number of instructions per cpu that can be executed in one second.
814 ------------------------