motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-02 15:23:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

Testing, docs, semihosting and plugin updates

Browse source 
- update playbooks for custom runners
   - add section timing support to gitlab
   - upgrade fedora images to 37
   - purge perl from the build system and deps
   - disable unstable tests in CI
   - improve intro, emulation and semihosting docs
   - semihosting bug fix and O_BINARY default
   - add memory-sve test
   - fix some races in qht
   - improve plugin handling of memory helpers
   - optimise plugin hooks
   - fix some plugin deadlocks
   - reduce win64-cross build time by dropping some targets
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmPb3fgACgkQ+9DbCVqe
 KkQbXAf9Eoc+PdNvafbqzH/blPjvd9ve8pJ+GcPDukNXwxP8OF/jFEJUQ1E7l9O7
 y0qV4akKCdIqVice4R5bK2CAq44Y3aut8SDf56C8E3Riha2zA2RbQWOv/zCvA3OP
 LFF+OaXZyg4JTR48HUKzh9ei2bd1+ccBSUe+xlRi59XaV5K8+5bmcZj10QKUR0lD
 0HC5auEWWpayvd5D7Da15C7+oVY3LMCFxSdpHwbuIPPan/TRo5yqMI6ChYDKB8QD
 gdwMCL8znj2ADCTBftyBDYDAtjKVyLQidf7KdQHiSF+nmXYopS6SbsPCOMtJqCMH
 tXcKAIxs/MEntPrWTKTdtdnzotJVKw==
 =AtfN
 -----END PGP SIGNATURE-----

Merge tag 'pull-jan-omnibus-020223-1' of https://gitlab.com/stsquad/qemu into staging

Testing, docs, semihosting and plugin updates

  - update playbooks for custom runners
  - add section timing support to gitlab
  - upgrade fedora images to 37
  - purge perl from the build system and deps
  - disable unstable tests in CI
  - improve intro, emulation and semihosting docs
  - semihosting bug fix and O_BINARY default
  - add memory-sve test
  - fix some races in qht
  - improve plugin handling of memory helpers
  - optimise plugin hooks
  - fix some plugin deadlocks
  - reduce win64-cross build time by dropping some targets

# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmPb3fgACgkQ+9DbCVqe
# KkQbXAf9Eoc+PdNvafbqzH/blPjvd9ve8pJ+GcPDukNXwxP8OF/jFEJUQ1E7l9O7
# y0qV4akKCdIqVice4R5bK2CAq44Y3aut8SDf56C8E3Riha2zA2RbQWOv/zCvA3OP
# LFF+OaXZyg4JTR48HUKzh9ei2bd1+ccBSUe+xlRi59XaV5K8+5bmcZj10QKUR0lD
# 0HC5auEWWpayvd5D7Da15C7+oVY3LMCFxSdpHwbuIPPan/TRo5yqMI6ChYDKB8QD
# gdwMCL8znj2ADCTBftyBDYDAtjKVyLQidf7KdQHiSF+nmXYopS6SbsPCOMtJqCMH
# tXcKAIxs/MEntPrWTKTdtdnzotJVKw==
# =AtfN
# -----END PGP SIGNATURE-----
# gpg: Signature made Thu 02 Feb 2023 15:59:52 GMT
# gpg:                using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [full]
# Primary key fingerprint: 6685 AE99 E751 67BC AFC8  DF35 FBD0 DB09 5A9E 2A44

* tag 'pull-jan-omnibus-020223-1' of https://gitlab.com/stsquad/qemu: (36 commits)
  gitlab: cut even more from cross-win64-system build
  plugins: Iterate on cb_lists in qemu_plugin_user_exit
  cpu-exec: assert that plugin_mem_cbs is NULL after execution
  tcg: exclude non-memory effecting helpers from instrumentation
  translator: always pair plugin_gen_insn_{start, end} calls
  plugins: fix optimization in plugin_gen_disable_mem_helpers
  plugins: make qemu_plugin_user_exit's locking order consistent with fork_start's
  util/qht: use striped locks under TSAN
  thread: de-const qemu_spin_destroy
  util/qht: add missing atomic_set(hashes[i])
  cpu: free cpu->tb_jmp_cache with RCU
  tests/tcg: add memory-sve test for aarch64
  semihosting: add O_BINARY flag in host_open for NT compatibility
  semihosting: Write back semihosting data before completion callback
  docs: add an introduction to the system docs
  semihosting: add semihosting section to the docs
  docs: add a new section to outline emulation support
  docs: add hotlinks to about preface text
  MAINTAINERS: Fix the entry for tests/tcg/nios2
  gitlab: wrap up test results for custom runners
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell 2023-02-02 18:00:40 +00:00
commit f991d61d35
75 changed files with 756 additions and 275 deletions
Download patch file Download diff file Expand all files Collapse all files

190
docs/about/emulation.rst Normal file
View file

@ -0,0 +1,190 @@
Emulation
=========
QEMU's Tiny Code Generator (TCG) provides the ability to emulate a
number of CPU architectures on any supported host platform. Both
:ref:`System Emulation` and :ref:`User Mode Emulation` are supported
depending on the guest architecture.
.. list-table:: Supported Guest Architectures for Emulation
:widths: 30 10 10 50
:header-rows: 1
* - Architecture (qemu name)
- System
- User
- Notes
* - Alpha
- Yes
- Yes
- Legacy 64 bit RISC ISA developed by DEC
* - Arm (arm, aarch64)
- :ref:`Yes<ARM-System-emulator>`
- Yes
- Wide range of features, see :ref:`Arm Emulation` for details
* - AVR
- :ref:`Yes<AVR-System-emulator>`
- No
- 8 bit micro controller, often used in maker projects
* - Cris
- Yes
- Yes
- Embedded RISC chip developed by AXIS
* - Hexagon
- No
- Yes
- Family of DSPs by Qualcomm
* - PA-RISC (hppa)
- Yes
- Yes
- A legacy RISC system used in HP's old minicomputers
* - x86 (i386, x86_64)
- :ref:`Yes<QEMU-PC-System-emulator>`
- Yes
- The ubiquitous desktop PC CPU architecture, 32 and 64 bit.
* - Loongarch
- Yes
- Yes
- A MIPS-like 64bit RISC architecture developed in China
* - m68k
- :ref:`Yes<ColdFire-System-emulator>`
- Yes
- Motorola 68000 variants and ColdFire
* - Microblaze
- Yes
- Yes
- RISC based soft-core by Xilinx
* - MIPS (mips*)
- :ref:`Yes<MIPS-System-emulator>`
- Yes
- Venerable RISC architecture originally out of Stanford University
* - Nios2
- Yes
- Yes
- 32 bit embedded soft-core by Altera
* - OpenRISC
- :ref:`Yes<OpenRISC-System-emulator>`
- Yes
- Open source RISC architecture developed by the OpenRISC community
* - Power (ppc, ppc64)
- :ref:`Yes<PowerPC-System-emulator>`
- Yes
- A general purpose RISC architecture now managed by IBM
* - RISC-V
- :ref:`Yes<RISC-V-System-emulator>`
- Yes
- An open standard RISC ISA maintained by RISC-V International
* - RX
- :ref:`Yes<RX-System-emulator>`
- No
- A 32 bit micro controller developed by Renesas
* - s390x
- :ref:`Yes<s390x-System-emulator>`
- Yes
- A 64 bit CPU found in IBM's System Z mainframes
* - sh4
- Yes
- Yes
- A 32 bit RISC embedded CPU developed by Hitachi
* - SPARC (sparc, sparc64)
- :ref:`Yes<Sparc32-System-emulator>`
- Yes
- A RISC ISA originally developed by Sun Microsystems
* - Tricore
- Yes
- No
- A 32 bit RISC/uController/DSP developed by Infineon
* - Xtensa
- :ref:`Yes<Xtensa-System-emulator>`
- Yes
- A configurable 32 bit soft core now owned by Cadence
A number of features are are only available when running under
emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
.. _Semihosting:
Semihosting
-----------
Semihosting is a feature defined by the owner of the architecture to
allow programs to interact with a debugging host system. On real
hardware this is usually provided by an In-circuit emulator (ICE)
hooked directly to the board. QEMU's implementation allows for
semihosting calls to be passed to the host system or via the
``gdbstub``.
Generally semihosting makes it easier to bring up low level code before a
more fully functional operating system has been enabled. On QEMU it
also allows for embedded micro-controller code which typically doesn't
have a full libc to be run as "bare-metal" code under QEMU's user-mode
emulation. It is also useful for writing test cases and indeed a
number of compiler suites as well as QEMU itself use semihosting calls
to exit test code while reporting the success state.
Semihosting is only available using TCG emulation. This is because the
instructions to trigger a semihosting call are typically reserved
causing most hypervisors to trap and fault on them.
.. warning::
Semihosting inherently bypasses any isolation there may be between
the guest and the host. As a result a program using semihosting can
happily trash your host system. You should only ever run trusted
code with semihosting enabled.
Redirection
~~~~~~~~~~~
Semihosting calls can be re-directed to a (potentially remote) gdb
during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
semihosting console is configured as a ``chardev`` so can be
redirected to a file, pipe or socket like any other ``chardev``
device.
Supported Targets
~~~~~~~~~~~~~~~~~
Most targets offer similar semihosting implementations with some
minor changes to define the appropriate instruction to encode the
semihosting call and which registers hold the parameters. They tend to
presents a simple POSIX-like API which allows your program to read and
write files, access the console and some other basic interactions.
For full details of the ABI for a particular target, and the set of
calls it provides, you should consult the semihosting specification
for that architecture.
.. note::
QEMU makes an implementation decision to implement all file
access in ``O_BINARY`` mode. The user-visible effect of this is
regardless of the text/binary mode the program sets QEMU will
always select a binary mode ensuring no line-terminator conversion
is performed on input or output. This is because gdb semihosting
support doesn't make the distinction between the modes and
magically processing line endings can be confusing.
.. list-table:: Guest Architectures supporting Semihosting
:widths: 10 10 80
:header-rows: 1
* - Architecture
- Modes
- Specification
* - Arm
- System and User-mode
- https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
* - m68k
- System
- https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
* - MIPS
- System
- Unified Hosting Interface (MD01069)
* - Nios II
- System
- https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
* - RISC-V
- System and User-mode
- https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
* - Xtensa
- System
- Tensilica ISS SIMCALL

17
docs/about/index.rst
View file

@ -5,24 +5,25 @@ About QEMU
QEMU is a generic and open source machine emulator and virtualizer.
QEMU can be used in several different ways. The most common is for
"system emulation", where it provides a virtual model of an
:ref:`System Emulation`, where it provides a virtual model of an
entire machine (CPU, memory and emulated devices) to run a guest OS.
In this mode the CPU may be fully emulated, or it may work with
a hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to
allow the guest to run directly on the host CPU.
In this mode the CPU may be fully emulated, or it may work with a
hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to allow the
guest to run directly on the host CPU.
The second supported way to use QEMU is "user mode emulation",
The second supported way to use QEMU is :ref:`User Mode Emulation`,
where QEMU can launch processes compiled for one CPU on another CPU.
In this mode the CPU is always emulated.
QEMU also provides a number of standalone commandline utilities,
such as the ``qemu-img`` disk image utility that allows you to create,
convert and modify disk images.
QEMU also provides a number of standalone :ref:`command line
utilities<Tools>`, such as the ``qemu-img`` disk image utility that
allows you to create, convert and modify disk images.
.. toctree::
:maxdepth: 2
build-platforms
emulation
deprecated
removed-features
license

13
docs/conf.py
View file

@ -297,19 +297,6 @@ man_pages = [
]
man_make_section_directory = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'QEMU', u'QEMU Documentation',
author, 'QEMU', 'One line description of project.',
'Miscellaneous'),
]
# We use paths starting from qemu_docdir here so that you can run
# sphinx-build from anywhere and the kerneldoc extension can still
# find everything.

2
docs/devel/tcg-plugins.rst
View file

@ -3,6 +3,8 @@
Copyright (c) 2019, Linaro Limited
Written by Emilio Cota and Alex Bennée
.. _TCG Plugins:
QEMU TCG Plugins
================

2
docs/interop/live-block-operations.rst
View file

@ -4,6 +4,8 @@
This work is licensed under the terms of the GNU GPL, version 2 or
later. See the COPYING file in the top-level directory.
.. _Live Block Operations:
============================
Live Block Device Operations
============================

2
docs/interop/qemu-qmp-ref.rst
View file

@ -1,3 +1,5 @@
.. _QMP Ref:
QEMU QMP Reference Manual
=========================

2
docs/system/arm/emulation.rst
View file

@ -1,3 +1,5 @@
.. _Arm Emulation:
A-profile CPU architecture support
==================================

4
docs/system/index.rst
View file

@ -1,3 +1,5 @@
.. _System Emulation:
----------------
System Emulation
----------------
@ -10,7 +12,7 @@ or Hypervisor.Framework.
.. toctree::
:maxdepth: 3
quickstart
introduction
invocation
device-emulation
keys

220
docs/system/introduction.rst Normal file
View file

@ -0,0 +1,220 @@
Introduction
============
Virtualisation Accelerators
---------------------------
QEMU's system emulation provides a virtual model of a machine (CPU,
memory and emulated devices) to run a guest OS. It supports a number
of hypervisors (known as accelerators) as well as a JIT known as the
Tiny Code Generator (TCG) capable of emulating many CPUs.
.. list-table:: Supported Accelerators
:header-rows: 1
* - Accelerator
- Host OS
- Host Architectures
* - KVM
- Linux
- Arm (64 bit only), MIPS, PPC, RISC-V, s390x, x86
* - Xen
- Linux (as dom0)
- Arm, x86
* - Intel HAXM (hax)
- Linux, Windows
- x86
* - Hypervisor Framework (hvf)
- MacOS
- x86 (64 bit only), Arm (64 bit only)
* - Windows Hypervisor Platform (wphx)
- Windows
- x86
* - NetBSD Virtual Machine Monitor (nvmm)
- NetBSD
- x86
* - Tiny Code Generator (tcg)
- Linux, other POSIX, Windows, MacOS
- Arm, x86, Loongarch64, MIPS, PPC, s390x, Sparc64
Feature Overview
----------------
System emulation provides a wide range of device models to emulate
various hardware components you may want to add to your machine. This
includes a wide number of VirtIO devices which are specifically tuned
for efficient operation under virtualisation. Some of the device
emulation can be offloaded from the main QEMU process using either
vhost-user (for VirtIO) or :ref:`Multi-process QEMU`. If the platform
supports it QEMU also supports directly passing devices through to
guest VMs to eliminate the device emulation overhead. See
:ref:`device-emulation` for more details.
There is a full :ref:`featured block layer<Live Block Operations>`
which allows for construction of complex storage topology which can be
stacked across multiple layers supporting redirection, networking,
snapshots and migration support.
The flexible ``chardev`` system allows for handling IO from character
like devices using stdio, files, unix sockets and TCP networking.
QEMU provides a number of management interfaces including a line based
:ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to
dynamically add and remove devices as well as introspect the system
state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well
defined, versioned, machine usable API that presents a rich interface
to other tools to create, control and manage Virtual Machines. This is
the interface used by higher level tools interfaces such as `Virt
Manager <https://virt-manager.org/>`_ using the `libvirt framework
<https://libvirt.org>`_.
For the common accelerators QEMU, supported debugging with its
:ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug
system software images.
Running
-------
QEMU provides a rich and complex API which can be overwhelming to
understand. While some architectures can boot something with just a
disk image, those examples elide a lot of details with defaults that
may not be optimal for modern systems.
For a non-x86 system where we emulate a broad range of machine types,
the command lines are generally more explicit in defining the machine
and boot behaviour. You will find often find example command lines in
the :ref:`system-targets-ref` section of the manual.
While the project doesn't want to discourage users from using the
command line to launch VMs, we do want to highlight that there are a
number of projects dedicated to providing a more user friendly
experience. Those built around the ``libvirt`` framework can make use
of feature probing to build modern VM images tailored to run on the
hardware you have.
That said, the general form of a QEMU command line can be expressed
as:
.. parsed-literal::
$ |qemu_system| [machine opts] \\
[cpu opts] \\
[accelerator opts] \\
[device opts] \\
[backend opts] \\
[interface opts] \\
[boot opts]
Most options will generate some help information. So for example:
.. parsed-literal::
$ |qemu_system| -M help
will list the machine types supported by that QEMU binary. ``help``
can also be passed as an argument to another option. For example:
.. parsed-literal::
$ |qemu_system| -device scsi-hd,help
will list the arguments and their default values of additional options
that can control the behaviour of the ``scsi-hd`` device.
.. list-table:: Options Overview
:header-rows: 1
:widths: 10, 90
* - Options
-
* - Machine
- Define the machine type, amount of memory etc
* - CPU
- Type and number/topology of vCPUs. Most accelerators offer
a ``host`` cpu option which simply passes through your host CPU
configuration without filtering out any features.
* - Accelerator
- This will depend on the hypervisor you run. Note that the
default is TCG, which is purely emulated, so you must specify an
accelerator type to take advantage of hardware virtualization.
* - Devices
- Additional devices that are not defined by default with the
machine type.
* - Backends
- Backends are how QEMU deals with the guest's data, for example
how a block device is stored, how network devices see the
network or how a serial device is directed to the outside world.
* - Interfaces
- How the system is displayed, how it is managed and controlled or
debugged.
* - Boot
- How the system boots, via firmware or direct kernel boot.
In the following example we first define a ``virt`` machine which is a
general purpose platform for running Aarch64 guests. We enable
virtualisation so we can use KVM inside the emulated guest. As the
``virt`` machine comes with some built in pflash devices we give them
names so we can override the defaults later.
.. code::
$ qemu-system-aarch64 \
-machine type=virt,virtualization=on,pflash0=rom,pflash1=efivars \
-m 4096 \
We then define the 4 vCPUs using the ``max`` option which gives us all
the Arm features QEMU is capable of emulating. We enable a more
emulation friendly implementation of Arm's pointer authentication
algorithm. We explicitly specify TCG acceleration even though QEMU
would default to it anyway.
.. code::
-cpu max,pauth-impdef=on \
-smp 4 \
-accel tcg \
As the ``virt`` platform doesn't have any default network or storage
devices we need to define them. We give them ids so we can link them
with the backend later on.
.. code::
-device virtio-net-pci,netdev=unet \
-device virtio-scsi-pci \
-device scsi-hd,drive=hd \
We connect the user-mode networking to our network device. As
user-mode networking isn't directly accessible from the outside world
we forward localhost port 2222 to the ssh port on the guest.
.. code::
-netdev user,id=unet,hostfwd=tcp::2222-:22 \
We connect the guest visible block device to an LVM partition we have
set aside for our guest.
.. code::
-blockdev driver=raw,node-name=hd,file.driver=host_device,file.filename=/dev/lvm-disk/debian-bullseye-arm64 \
We then tell QEMU to multiplex the :ref:`QEMU monitor` with the serial
port output (we can switch between the two using :ref:`keys in the
character backend multiplexer`). As there is no default graphical
device we disable the display as we can work entirely in the terminal.
.. code::
-serial mon:stdio \
-display none \
Finally we override the default firmware to ensure we have some
storage for EFI to persist its configuration. That firmware is
responsible for finding the disk, booting grub and eventually running
our system.
.. code::
-blockdev node-name=rom,driver=file,filename=(pwd)/pc-bios/edk2-aarch64-code.fd,read-only=true \
-blockdev node-name=efivars,driver=file,filename=$HOME/images/qemu-arm64-efivars

2
docs/system/multi-process.rst
View file

@ -1,3 +1,5 @@
.. _Multi-process QEMU:
Multi-process QEMU
==================

21
docs/system/quickstart.rst
View file

@ -1,21 +0,0 @@
.. _pcsys_005fquickstart:
Quick Start
-----------
Download and uncompress a PC hard disk image with Linux installed (e.g.
``linux.img``) and type:
.. parsed-literal::
|qemu_system| linux.img
Linux should boot and give you a prompt.
Users should be aware the above example elides a lot of the complexity
of setting up a VM with x86_64 specific defaults and assumes the
first non switch argument is a PC compatible disk image with a boot
sector. For a non-x86 system where we emulate a broad range of machine
types, the command lines are generally more explicit in defining the
machine and boot behaviour. You will find more example command lines
in the :ref:`system-targets-ref` section of the manual.

2
docs/tools/index.rst
View file

@ -1,3 +1,5 @@
.. _Tools:
-----
Tools
-----

2
docs/user/index.rst
View file

@ -1,3 +1,5 @@
.. _User Mode Emulation:
-------------------
User Mode Emulation
-------------------