docs/about/emulation.rst

6 :ref:`System Emulation` and :ref:`User Mode Emulation` are supported
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
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-non-isa/riscv-semihosting/blob/main/riscv-semihosting.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
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
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
571 asynchronous events are introduced. While the use of -icount can
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
605 the user to see what hardware is accessed how often. It has a number of options:
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
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
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
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 ------------------------