Browse Source
- log a guest_error for failed semihosting open()
- clean up semihosting includes to reduce build duplication
- re-factor misc device initialisation to fail with &error_exit
- propagate Error * to gdbserver_start sub-functions
- fix 32-bit build of plugins and re-enable by default
- ensure IRQs don't preempt io recompiled instructions
- remove usage of gcc_struct to enable clang builds
- enable clang/lld to build plugins on windows
- various small kdoc typo fixes
- add perl scripts to editorconfig
- remove unused field from MemoryRegion
- make kdoc script a dependency so doc rebuilds get triggered
- expand developer documentation:
- notes on git-publish
- describe usage of b4
- setting up build dependencies
- codebase layout
- add a glossary of common terms
- optimise the windows ndis script
-----BEGIN PGP SIGNATURE-----
iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmeKO8sACgkQ+9DbCVqe
KkTbBQf9HRlspCl2r5a8K9O1ymylKiZ653OBWMStGTQ8xPXeLDFhT+ION34VBgBh
LXHEcjIHn24cN2s1BO5+xJs0nzqYe7UEAK6JQmdX3/HEuf8VmaVslvhm+nCWKoIL
JQbsHno92wh6vvTWQu53zijEuG5HdBseWiwQKHbE1oSRc2CikG70o902AL9zXAsp
mpUYWxUmWwg5uQATztp4XfylJBcSX3SiVgv22jXLqBj9drXPftl/E33fcWXxTj5f
AM3kz9fxaCfo5+znmYw3R1tT/Hv52Q6hW+oNAm34XeWp1/+ho27QMRrpIi/dpdwX
mCbvJwI75sCnD91p9NW7vZIYZJKsLg==
=SLCY
-----END PGP SIGNATURE-----
Merge tag 'pull-10.0-gdb-plugins-doc-updates-170125-1' of https://gitlab.com/stsquad/qemu into staging
semihosting, plugin and doc updates:
- log a guest_error for failed semihosting open()
- clean up semihosting includes to reduce build duplication
- re-factor misc device initialisation to fail with &error_exit
- propagate Error * to gdbserver_start sub-functions
- fix 32-bit build of plugins and re-enable by default
- ensure IRQs don't preempt io recompiled instructions
- remove usage of gcc_struct to enable clang builds
- enable clang/lld to build plugins on windows
- various small kdoc typo fixes
- add perl scripts to editorconfig
- remove unused field from MemoryRegion
- make kdoc script a dependency so doc rebuilds get triggered
- expand developer documentation:
- notes on git-publish
- describe usage of b4
- setting up build dependencies
- codebase layout
- add a glossary of common terms
- optimise the windows ndis script
# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmeKO8sACgkQ+9DbCVqe
# KkTbBQf9HRlspCl2r5a8K9O1ymylKiZ653OBWMStGTQ8xPXeLDFhT+ION34VBgBh
# LXHEcjIHn24cN2s1BO5+xJs0nzqYe7UEAK6JQmdX3/HEuf8VmaVslvhm+nCWKoIL
# JQbsHno92wh6vvTWQu53zijEuG5HdBseWiwQKHbE1oSRc2CikG70o902AL9zXAsp
# mpUYWxUmWwg5uQATztp4XfylJBcSX3SiVgv22jXLqBj9drXPftl/E33fcWXxTj5f
# AM3kz9fxaCfo5+znmYw3R1tT/Hv52Q6hW+oNAm34XeWp1/+ho27QMRrpIi/dpdwX
# mCbvJwI75sCnD91p9NW7vZIYZJKsLg==
# =SLCY
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 17 Jan 2025 06:15:23 EST
# gpg: using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [unknown]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 6685 AE99 E751 67BC AFC8 DF35 FBD0 DB09 5A9E 2A44
* tag 'pull-10.0-gdb-plugins-doc-updates-170125-1' of https://gitlab.com/stsquad/qemu: (37 commits)
scripts/nsis.py: Run dependency check for each DLL file only once
docs: add a glossary
docs/devel: add a codebase section
docs/devel: add information on how to setup build environments
docs/devel: add b4 for patch retrieval
docs/devel: add git-publish for patch submitting
docs/sphinx: include kernel-doc script as a dependency
include/exec: remove warning_printed from MemoryRegion
include/exec: fix some copy and paste errors in kdoc
tests/qtest: fix some copy and paste errors in kdoc
editorconfig: update for perl scripts
plugins: fix kdoc annotation
plugins: enable linking with clang/lld
docs/devel/style: add a section about bitfield, and disallow them for packed structures
win32: remove usage of attribute gcc_struct
accel/tcg: also suppress asynchronous IRQs for cpu_io_recompile
configure: reenable plugins by default for 32-bit hosts
contrib/plugins/hotpages: fix 32-bit build
contrib/plugins/hwprofile: fix 32-bit build
contrib/plugins/cflow: fix 32-bit build
...
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
pull/281/head
Stefan Hajnoczi
1 year ago
68 changed files with 1035 additions and 226 deletions
@ -0,0 +1,118 @@ |
|||
|
|||
.. _setup-build-env: |
|||
|
|||
Setup build environment |
|||
======================= |
|||
|
|||
QEMU uses a lot of dependencies on the host system. glib2 is used everywhere in |
|||
the code base, and most of the other dependencies are optional. |
|||
|
|||
We present here simple instructions to enable native builds on most popular |
|||
systems. |
|||
|
|||
You can find additional instructions on `QEMU wiki <https://wiki.qemu.org/>`_: |
|||
|
|||
- `Linux <https://wiki.qemu.org/Hosts/Linux>`_ |
|||
- `MacOS <https://wiki.qemu.org/Hosts/Mac>`_ |
|||
- `Windows <https://wiki.qemu.org/Hosts/W32>`_ |
|||
- `BSD <https://wiki.qemu.org/Hosts/BSD>`_ |
|||
|
|||
Note: Installing dependencies using your package manager build dependencies may |
|||
miss out on deps that have been newly introduced in qemu.git. In more, it misses |
|||
deps the distribution has decided to exclude. |
|||
|
|||
Linux |
|||
----- |
|||
|
|||
Fedora |
|||
++++++ |
|||
|
|||
:: |
|||
|
|||
sudo dnf update && sudo dnf builddep qemu |
|||
|
|||
Debian/Ubuntu |
|||
+++++++++++++ |
|||
|
|||
You first need to enable `Sources List <https://wiki.debian.org/SourcesList>`_. |
|||
Then, use apt to install dependencies: |
|||
|
|||
:: |
|||
|
|||
sudo apt update && sudo apt build-dep qemu |
|||
|
|||
MacOS |
|||
----- |
|||
|
|||
You first need to install `Homebrew <https://brew.sh/>`_. Then, use it to |
|||
install dependencies: |
|||
|
|||
:: |
|||
|
|||
brew update && brew install $(brew deps --include-build qemu) |
|||
|
|||
Windows |
|||
------- |
|||
|
|||
You first need to install `MSYS2 <https://www.msys2.org/>`_. |
|||
MSYS2 offers `different environments <https://www.msys2.org/docs/environments/>`_. |
|||
x86_64 environments are based on GCC, while aarch64 is based on Clang. |
|||
|
|||
We recommend to use MINGW64 for windows-x86_64 and CLANGARM64 for windows-aarch64 |
|||
(only available on windows-aarch64 hosts). |
|||
|
|||
Then, you can open a windows shell, and enter msys2 env using: |
|||
|
|||
:: |
|||
|
|||
c:/msys64/msys2_shell.cmd -defterm -here -no-start -mingw64 |
|||
# Replace -ucrt64 by -clangarm64 or -ucrt64 for other environments. |
|||
|
|||
MSYS2 package manager does not offer a built-in way to install build |
|||
dependencies. You can start with this list of packages using pacman: |
|||
|
|||
Note: Dependencies need to be installed again if you use a different MSYS2 |
|||
environment. |
|||
|
|||
:: |
|||
|
|||
# update MSYS2 itself, you need to reopen your shell at the end. |
|||
pacman -Syu |
|||
pacman -S \ |
|||
base-devel binutils bison diffutils flex git grep make sed \ |
|||
${MINGW_PACKAGE_PREFIX}-toolchain \ |
|||
${MINGW_PACKAGE_PREFIX}-glib2 \ |
|||
${MINGW_PACKAGE_PREFIX}-gtk3 \ |
|||
${MINGW_PACKAGE_PREFIX}-libnfs \ |
|||
${MINGW_PACKAGE_PREFIX}-libssh \ |
|||
${MINGW_PACKAGE_PREFIX}-ninja \ |
|||
${MINGW_PACKAGE_PREFIX}-pixman \ |
|||
${MINGW_PACKAGE_PREFIX}-pkgconf \ |
|||
${MINGW_PACKAGE_PREFIX}-python \ |
|||
${MINGW_PACKAGE_PREFIX}-SDL2 \ |
|||
${MINGW_PACKAGE_PREFIX}-zstd |
|||
|
|||
If you want to install all dependencies, it's possible to use recipe used to |
|||
build QEMU in MSYS2 itself. |
|||
|
|||
:: |
|||
|
|||
pacman -S wget |
|||
wget https://raw.githubusercontent.com/msys2/MINGW-packages/refs/heads/master/mingw-w64-qemu/PKGBUILD |
|||
# Some packages may be missing for your environment, installation will still |
|||
# be done though. |
|||
makepkg -s PKGBUILD || true |
|||
|
|||
Build on windows-aarch64 |
|||
++++++++++++++++++++++++ |
|||
|
|||
When trying to cross compile meson for x86_64 using UCRT64 or MINGW64 env, |
|||
configure will run into an error because the cpu detected is not correct. |
|||
|
|||
Meson detects x86_64 processes emulated, so you need to manually set the cpu, |
|||
and force a cross compilation (with empty prefix). |
|||
|
|||
:: |
|||
|
|||
./configure --cpu=x86_64 --cross-prefix= |
|||
|
|||
@ -0,0 +1,220 @@ |
|||
======== |
|||
Codebase |
|||
======== |
|||
|
|||
This section presents the various parts of QEMU and how the codebase is |
|||
organized. |
|||
|
|||
Beyond giving succint descriptions, the goal is to offer links to various |
|||
parts of the documentation/codebase. |
|||
|
|||
Subsystems |
|||
---------- |
|||
|
|||
An exhaustive list of subsystems and associated files can be found in the |
|||
`MAINTAINERS <https://gitlab.com/qemu-project/qemu/-/blob/master/MAINTAINERS>`_ |
|||
file. |
|||
|
|||
Some of the main QEMU subsystems are: |
|||
|
|||
- `Accelerators<Accelerators>` |
|||
- Block devices and `disk images<disk images>` support |
|||
- `CI<ci>` and `Tests<testing>` |
|||
- `Devices<device-emulation>` & Board models |
|||
- `Documentation <documentation-root>` |
|||
- `GDB support<GDB usage>` |
|||
- `Migration<migration>` |
|||
- `Monitor<QEMU monitor>` |
|||
- :ref:`QOM (QEMU Object Model)<qom>` |
|||
- `System mode<System emulation>` |
|||
- :ref:`TCG (Tiny Code Generator)<tcg>` |
|||
- `User mode<user-mode>` (`Linux<linux-user-mode>` & `BSD<bsd-user-mode>`) |
|||
- User Interfaces |
|||
|
|||
More documentation on QEMU subsystems can be found on :ref:`internal-subsystem` |
|||
page. |
|||
|
|||
The Grand tour |
|||
-------------- |
|||
|
|||
We present briefly here what every folder in the top directory of the codebase |
|||
contains. Hop on! |
|||
|
|||
The folder name links here will take you to that folder in our gitlab |
|||
repository. Other links will take you to more detailed documentation for that |
|||
subsystem, where we have it. Unfortunately not every subsystem has documentation |
|||
yet, so sometimes the source code is all you have. |
|||
|
|||
* `accel <https://gitlab.com/qemu-project/qemu/-/tree/master/accel>`_: |
|||
Infrastructure and architecture agnostic code related to the various |
|||
`accelerators <Accelerators>` supported by QEMU |
|||
(TCG, KVM, hvf, whpx, xen, nvmm). |
|||
Contains interfaces for operations that will be implemented per |
|||
`target <https://gitlab.com/qemu-project/qemu/-/tree/master/target>`_. |
|||
* `audio <https://gitlab.com/qemu-project/qemu/-/tree/master/audio>`_: |
|||
Audio (host) support. |
|||
* `authz <https://gitlab.com/qemu-project/qemu/-/tree/master/authz>`_: |
|||
`QEMU Authorization framework<client authorization>`. |
|||
* `backends <https://gitlab.com/qemu-project/qemu/-/tree/master/backends>`_: |
|||
Various backends that are used to access resources on the host (e.g. for |
|||
random number generation, memory backing or cryptographic functions). |
|||
* `block <https://gitlab.com/qemu-project/qemu/-/tree/master/block>`_: |
|||
Block devices and `image formats<disk images>` implementation. |
|||
* `bsd-user <https://gitlab.com/qemu-project/qemu/-/tree/master/bsd-user>`_: |
|||
`BSD User mode<bsd-user-mode>`. |
|||
* build: Where the code built goes by default. You can tell the QEMU build |
|||
system to put the built code anywhere else you like. |
|||
* `chardev <https://gitlab.com/qemu-project/qemu/-/tree/master/chardev>`_: |
|||
Various backends used by char devices. |
|||
* `common-user <https://gitlab.com/qemu-project/qemu/-/tree/master/common-user>`_: |
|||
User-mode assembly code for dealing with signals occuring during syscalls. |
|||
* `configs <https://gitlab.com/qemu-project/qemu/-/tree/master/configs>`_: |
|||
Makefiles defining configurations to build QEMU. |
|||
* `contrib <https://gitlab.com/qemu-project/qemu/-/tree/master/contrib>`_: |
|||
Community contributed devices/plugins/tools. |
|||
* `crypto <https://gitlab.com/qemu-project/qemu/-/tree/master/crypto>`_: |
|||
Cryptographic algorithms used in QEMU. |
|||
* `disas <https://gitlab.com/qemu-project/qemu/-/tree/master/disas>`_: |
|||
Disassembly functions used by QEMU target code. |
|||
* `docs <https://gitlab.com/qemu-project/qemu/-/tree/master/docs>`_: |
|||
QEMU Documentation. |
|||
* `dump <https://gitlab.com/qemu-project/qemu/-/tree/master/dump>`_: |
|||
Code to dump memory of a running VM. |
|||
* `ebpf <https://gitlab.com/qemu-project/qemu/-/tree/master/ebpf>`_: |
|||
eBPF program support in QEMU. `virtio-net RSS<ebpf-rss>` uses it. |
|||
* `fpu <https://gitlab.com/qemu-project/qemu/-/tree/master/fpu>`_: |
|||
Floating-point software emulation. |
|||
* `fsdev <https://gitlab.com/qemu-project/qemu/-/tree/master/fsdev>`_: |
|||
`VirtFS <https://www.linux-kvm.org/page/VirtFS>`_ support. |
|||
* `gdbstub <https://gitlab.com/qemu-project/qemu/-/tree/master/gdbstub>`_: |
|||
`GDB <GDB usage>` support. |
|||
* `gdb-xml <https://gitlab.com/qemu-project/qemu/-/tree/master/gdb-xml>`_: |
|||
Set of XML files describing architectures and used by `gdbstub <GDB usage>`. |
|||
* `host <https://gitlab.com/qemu-project/qemu/-/tree/master/host>`_: |
|||
Various architecture specific header files (crypto, atomic, memory |
|||
operations). |
|||
* `linux-headers <https://gitlab.com/qemu-project/qemu/-/tree/master/linux-headers>`_: |
|||
A subset of headers imported from Linux kernel and used for implementing |
|||
KVM support and user-mode. |
|||
* `linux-user <https://gitlab.com/qemu-project/qemu/-/tree/master/linux-user>`_: |
|||
`User mode <user-mode>` implementation. Contains one folder per target |
|||
architecture. |
|||
* `.gitlab-ci.d <https://gitlab.com/qemu-project/qemu/-/tree/master/.gitlab-ci.d>`_: |
|||
`CI <ci>` yaml and scripts. |
|||
* `include <https://gitlab.com/qemu-project/qemu/-/tree/master/include>`_: |
|||
All headers associated to different subsystems in QEMU. The hierachy used |
|||
mirrors source code organization and naming. |
|||
* `hw <https://gitlab.com/qemu-project/qemu/-/tree/master/hw>`_: |
|||
`Devices <device-emulation>` and boards emulation. Devices are categorized by |
|||
type/protocol/architecture and located in associated subfolder. |
|||
* `io <https://gitlab.com/qemu-project/qemu/-/tree/master/io>`_: |
|||
QEMU `I/O channels <https://lists.gnu.org/archive/html/qemu-devel/2015-11/msg04208.html>`_. |
|||
* `libdecnumber <https://gitlab.com/qemu-project/qemu/-/tree/master/libdecnumber>`_: |
|||
Import of gcc library, used to implement decimal number arithmetic. |
|||
* `migration <https://gitlab.com/qemu-project/qemu/-/tree/master/migration>`__: |
|||
`Migration framework <migration>`. |
|||
* `monitor <https://gitlab.com/qemu-project/qemu/-/tree/master/monitor>`_: |
|||
`Monitor <QEMU monitor>` implementation (HMP & QMP). |
|||
* `nbd <https://gitlab.com/qemu-project/qemu/-/tree/master/nbd>`_: |
|||
QEMU `NBD (Network Block Device) <nbd>` server. |
|||
* `net <https://gitlab.com/qemu-project/qemu/-/tree/master/net>`_: |
|||
Network (host) support. |
|||
* `pc-bios <https://gitlab.com/qemu-project/qemu/-/tree/master/pc-bios>`_: |
|||
Contains pre-built firmware binaries and boot images, ready to use in |
|||
QEMU without compilation. |
|||
* `plugins <https://gitlab.com/qemu-project/qemu/-/tree/master/plugins>`_: |
|||
:ref:`TCG plugins <tcg-plugins>` core implementation. Plugins can be found in |
|||
`tests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tcg/plugins>`__ |
|||
and `contrib <https://gitlab.com/qemu-project/qemu/-/tree/master/contrib/plugins>`__ |
|||
folders. |
|||
* `po <https://gitlab.com/qemu-project/qemu/-/tree/master/po>`_: |
|||
Translation files. |
|||
* `python <https://gitlab.com/qemu-project/qemu/-/tree/master/python>`_: |
|||
Python part of our build/test system. |
|||
* `qapi <https://gitlab.com/qemu-project/qemu/-/tree/master/qapi>`_: |
|||
`QAPI <qapi>` implementation. |
|||
* `qobject <https://gitlab.com/qemu-project/qemu/-/tree/master/qobject>`_: |
|||
QEMU Object implementation. |
|||
* `qga <https://gitlab.com/qemu-project/qemu/-/tree/master/qga>`_: |
|||
QEMU `Guest agent <qemu-ga>` implementation. |
|||
* `qom <https://gitlab.com/qemu-project/qemu/-/tree/master/qom>`_: |
|||
QEMU :ref:`Object model <qom>` implementation, with monitor associated commands. |
|||
* `replay <https://gitlab.com/qemu-project/qemu/-/tree/master/replay>`_: |
|||
QEMU :ref:`Record/replay <replay>` implementation. |
|||
* `roms <https://gitlab.com/qemu-project/qemu/-/tree/master/roms>`_: |
|||
Contains source code for various firmware and ROMs, which can be compiled if |
|||
custom or updated versions are needed. |
|||
* `rust <https://gitlab.com/qemu-project/qemu/-/tree/master/rust>`_: |
|||
Rust integration in QEMU. It contains the new interfaces defined and |
|||
associated devices using it. |
|||
* `scripts <https://gitlab.com/qemu-project/qemu/-/tree/master/scripts>`_: |
|||
Collection of scripts used in build and test systems, and various |
|||
tools for QEMU codebase and execution traces. |
|||
* `scsi <https://gitlab.com/qemu-project/qemu/-/tree/master/scsi>`_: |
|||
Code related to SCSI support, used by SCSI devices. |
|||
* `semihosting <https://gitlab.com/qemu-project/qemu/-/tree/master/semihosting>`_: |
|||
QEMU `Semihosting <Semihosting>` implementation. |
|||
* `stats <https://gitlab.com/qemu-project/qemu/-/tree/master/stats>`_: |
|||
`Monitor <QEMU monitor>` stats commands implementation. |
|||
* `storage-daemon <https://gitlab.com/qemu-project/qemu/-/tree/master/storage-daemon>`_: |
|||
QEMU `Storage daemon <storage-daemon>` implementation. |
|||
* `stubs <https://gitlab.com/qemu-project/qemu/-/tree/master/stubs>`_: |
|||
Various stubs (empty functions) used to compile QEMU with specific |
|||
configurations. |
|||
* `subprojects <https://gitlab.com/qemu-project/qemu/-/tree/master/subprojects>`_: |
|||
QEMU submodules used by QEMU build system. |
|||
* `system <https://gitlab.com/qemu-project/qemu/-/tree/master/system>`_: |
|||
QEMU `system mode <System emulation>` implementation (cpu, mmu, boot support). |
|||
* `target <https://gitlab.com/qemu-project/qemu/-/tree/master/target>`_: |
|||
Contains code for all target architectures supported (one subfolder |
|||
per arch). For every architecture, you can find accelerator specific |
|||
implementations. |
|||
* `tcg <https://gitlab.com/qemu-project/qemu/-/tree/master/tcg>`_: |
|||
:ref:`TCG <tcg>` related code. |
|||
Contains one subfolder per host supported architecture. |
|||
* `tests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests>`_: |
|||
QEMU `test <testing>` suite |
|||
|
|||
- `avocado <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/avocado>`_: |
|||
Functional tests booting full VM using `Avocado framework <checkavocado-ref>`. |
|||
Those tests will be transformed and moved into |
|||
`tests/functional <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/functional>`_ |
|||
in the future. |
|||
- `data <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/data>`_: |
|||
Data for various tests. |
|||
- `decode <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/decode>`_: |
|||
Testsuite for :ref:`decodetree <decodetree>` implementation. |
|||
- `docker <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/docker>`_: |
|||
Code and scripts to create `containers <container-ref>` used in `CI <ci>`. |
|||
- `fp <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/fp>`_: |
|||
QEMU testsuite for soft float implementation. |
|||
- `functional <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/functional>`_: |
|||
`Functional tests <checkfunctional-ref>` (full VM boot). |
|||
- `lcitool <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/lcitool>`_: |
|||
Generate dockerfiles for CI containers. |
|||
- `migration <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/migration>`_: |
|||
Test scripts and data for `Migration framework <migration>`. |
|||
- `multiboot <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/multiboot>`_: |
|||
Test multiboot functionality for x86_64/i386. |
|||
- `qapi-schema <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qapi-schema>`_: |
|||
Test scripts and data for `QAPI <qapi-tests>`. |
|||
- `qemu-iotests <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qemu-iotests>`_: |
|||
`Disk image and block tests <qemu-iotests>`. |
|||
- `qtest <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/qtest>`_: |
|||
`Device emulation testing <qtest>`. |
|||
- `tcg <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tcg>`__: |
|||
`TCG related tests <checktcg-ref>`. Contains code per architecture |
|||
(subfolder) and multiarch tests as well. |
|||
- `tsan <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/tsan>`_: |
|||
`Suppressions <tsan-suppressions>` for thread sanitizer. |
|||
- `uefi-test-tools <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/uefi-test-tools>`_: |
|||
Test tool for UEFI support. |
|||
- `unit <https://gitlab.com/qemu-project/qemu/-/tree/master/tests/unit>`_: |
|||
QEMU `Unit tests <unit-tests>`. |
|||
* `trace <https://gitlab.com/qemu-project/qemu/-/tree/master/trace>`_: |
|||
:ref:`Tracing framework <tracing>`. Used to print information associated to various |
|||
events during execution. |
|||
* `ui <https://gitlab.com/qemu-project/qemu/-/tree/master/ui>`_: |
|||
QEMU User interfaces. |
|||
* `util <https://gitlab.com/qemu-project/qemu/-/tree/master/util>`_: |
|||
Utility code used by other parts of QEMU. |
|||
@ -0,0 +1,280 @@ |
|||
.. _Glossary: |
|||
|
|||
-------- |
|||
Glossary |
|||
-------- |
|||
|
|||
This section of the manual presents brief definitions of acronyms and terms used |
|||
by QEMU developers. |
|||
|
|||
Accelerator |
|||
----------- |
|||
|
|||
A specific API used to accelerate execution of guest instructions. It can be |
|||
hardware-based, through a virtualization API provided by the host OS (kvm, hvf, |
|||
whpx, ...), or software-based (tcg). See this description of `supported |
|||
accelerators<Accelerators>`. |
|||
|
|||
Board |
|||
----- |
|||
|
|||
Another name for :ref:`machine`. |
|||
|
|||
Block |
|||
----- |
|||
|
|||
Block drivers are the available `disk formats and front-ends |
|||
<block-drivers>` available, and block devices `(see Block device section on |
|||
options page)<sec_005finvocation>` are using them to implement disks for a |
|||
virtual machine. |
|||
|
|||
CFI |
|||
--- |
|||
|
|||
Control Flow Integrity is a hardening technique used to prevent exploits |
|||
targeting QEMU by detecting unexpected branches during execution. QEMU `actively |
|||
supports<cfi>` being compiled with CFI enabled. |
|||
|
|||
Device |
|||
------ |
|||
|
|||
In QEMU, a device is a piece of hardware visible to the guest. Examples include |
|||
UARTs, PCI controllers, PCI cards, VGA controllers, and many more. |
|||
|
|||
QEMU is able to emulate a CPU, and all the hardware interacting with it, |
|||
including `many devices<device-emulation>`. When QEMU runs a virtual machine |
|||
using a hardware-based accelerator, it is responsible for emulating, using |
|||
software, all devices. |
|||
|
|||
EDK2 |
|||
---- |
|||
|
|||
EDK2, as known as `TianoCore <https://www.tianocore.org/>`_, is an open source |
|||
implementation of UEFI standard. QEMU virtual machines that boot a UEFI firmware |
|||
usually use EDK2. |
|||
|
|||
gdbstub |
|||
------- |
|||
|
|||
QEMU implements a `gdb server <GDB usage>`, allowing gdb to attach to it and |
|||
debug a running virtual machine, or a program in user-mode. This allows |
|||
debugging the guest code that is running inside QEMU. |
|||
|
|||
glib2 |
|||
----- |
|||
|
|||
`GLib2 <https://docs.gtk.org/glib/>`_ is one of the most important libraries we |
|||
are using through the codebase. It provides many data structures, macros, string |
|||
and thread utilities and portable functions across different OS. It's required |
|||
to build QEMU. |
|||
|
|||
Guest agent |
|||
----------- |
|||
|
|||
The `QEMU Guest Agent <qemu-ga>` is a daemon intended to be run within virtual |
|||
machines. It provides various services to help QEMU to interact with it. |
|||
|
|||
.. _guest: |
|||
|
|||
Guest |
|||
----- |
|||
|
|||
Guest is the architecture of the virtual machine, which is emulated. |
|||
See also :ref:`host`. |
|||
|
|||
Sometimes this is called the :ref:`target` architecture, but that term |
|||
can be ambiguous. |
|||
|
|||
.. _host: |
|||
|
|||
Host |
|||
---- |
|||
|
|||
Host is the architecture on which QEMU is running on, which is native. |
|||
See also :ref:`guest`. |
|||
|
|||
Hypervisor |
|||
---------- |
|||
|
|||
The formal definition of an hypervisor is a program or API than can be used to |
|||
manage a virtual machine. QEMU is a virtualizer, that interacts with various |
|||
hypervisors. |
|||
|
|||
In the context of QEMU, an hypervisor is an API, provided by the Host OS, |
|||
allowing to execute virtual machines. Linux implementation is KVM (and supports |
|||
Xen as well). For MacOS, it's HVF. Windows defines WHPX. And NetBSD provides |
|||
NVMM. |
|||
|
|||
.. _machine: |
|||
|
|||
Machine |
|||
------- |
|||
|
|||
QEMU's system emulation models many different types of hardware. A machine model |
|||
(sometimes called a board model) is the model of a complete virtual system with |
|||
RAM, one or more CPUs, and various devices. It can be selected with the option |
|||
``-machine`` of qemu-system. Our machine models can be found on this `page |
|||
<system-targets-ref>`. |
|||
|
|||
Migration |
|||
--------- |
|||
|
|||
QEMU can save and restore the execution of a virtual machine between different |
|||
host systems. This is provided by the `Migration framework<migration>`. |
|||
|
|||
NBD |
|||
--- |
|||
|
|||
The `QEMU Network Block Device server <qemu-nbd>` is a tool that can be used to |
|||
mount and access QEMU images, providing functionality similar to a loop device. |
|||
|
|||
Mailing List |
|||
------------ |
|||
|
|||
This is `where <https://wiki.qemu.org/Contribute/MailingLists>`_ all the |
|||
development happens! Changes are posted as series, that all developers can |
|||
review and share feedback for. |
|||
|
|||
For reporting issues, our `GitLab |
|||
<https://gitlab.com/qemu-project/qemu/-/issues>`_ tracker is the best place. |
|||
|
|||
.. _softmmu: |
|||
|
|||
MMU / softmmu |
|||
------------- |
|||
|
|||
The Memory Management Unit is responsible for translating virtual addresses to |
|||
physical addresses and managing memory protection. QEMU system mode is named |
|||
"softmmu" precisely because it implements this in software, including a TLB |
|||
(Translation lookaside buffer), for the guest virtual machine. |
|||
|
|||
QEMU user-mode does not implement a full software MMU, but "simply" translates |
|||
virtual addresses by adding a specific offset, and relying on host MMU/OS |
|||
instead. |
|||
|
|||
Monitor / QMP / HMP |
|||
------------------- |
|||
|
|||
The `QEMU Monitor <QEMU monitor>` is a text interface which can be used to interact |
|||
with a running virtual machine. |
|||
|
|||
QMP stands for QEMU Monitor Protocol and is a json based interface. |
|||
HMP stands for Human Monitor Protocol and is a set of text commands available |
|||
for users who prefer natural language to json. |
|||
|
|||
MTTCG |
|||
----- |
|||
|
|||
Multiple CPU support was first implemented using a round-robin algorithm |
|||
running on a single thread. Later on, `Multi-threaded TCG <mttcg>` was developed |
|||
to benefit from multiple cores to speed up execution. |
|||
|
|||
Plugins |
|||
------- |
|||
|
|||
`TCG Plugins <TCG Plugins>` is an API used to instrument guest code, in system |
|||
and user mode. The end goal is to have a similar set of functionality compared |
|||
to `DynamoRIO <https://dynamorio.org/>`_ or `valgrind <https://valgrind.org/>`_. |
|||
|
|||
One key advantage of QEMU plugins is that they can be used to perform |
|||
architecture agnostic instrumentation. |
|||
|
|||
Patchew |
|||
------- |
|||
|
|||
`Patchew <https://patchew.org/QEMU/>`_ is a website that tracks patches on the |
|||
Mailing List. |
|||
|
|||
PR |
|||
-- |
|||
|
|||
Once a series is reviewed and accepted by a subsystem maintainer, it will be |
|||
included in a PR (Pull Request) that the project maintainer will merge into QEMU |
|||
main branch, after running tests. |
|||
|
|||
The QEMU project doesn't currently expect most developers to directly submit |
|||
pull requests. |
|||
|
|||
QCOW2 |
|||
----- |
|||
|
|||
QEMU Copy On Write is a disk format developed by QEMU. It provides transparent |
|||
compression, automatic extension, and many other advantages over a raw image. |
|||
|
|||
qcow2 is the recommended format to use. |
|||
|
|||
QEMU |
|||
---- |
|||
|
|||
`QEMU (Quick Emulator) <https://www.qemu.org/>`_ is a generic and open source |
|||
machine emulator and virtualizer. |
|||
|
|||
QOM |
|||
--- |
|||
|
|||
`QEMU Object Model <qom>` is an object oriented API used to define various |
|||
devices and hardware in the QEMU codebase. |
|||
|
|||
Record/replay |
|||
------------- |
|||
|
|||
`Record/replay <replay>` is a feature of QEMU allowing to have a deterministic |
|||
and reproducible execution of a virtual machine. |
|||
|
|||
Rust |
|||
---- |
|||
|
|||
`A new programming language <https://www.rust-lang.org/>`_, memory safe by |
|||
default. There is a work in progress to integrate it in QEMU codebase for |
|||
various subsystems. |
|||
|
|||
System mode |
|||
----------- |
|||
|
|||
QEMU System mode 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 or Hypervisor.Framework to |
|||
allow the guest to run directly on the host CPU. |
|||
|
|||
QEMU System mode is called :ref:`softmmu <softmmu>` as well. |
|||
|
|||
.. _target: |
|||
|
|||
Target |
|||
------ |
|||
|
|||
The term "target" can be ambiguous. In most places in QEMU it is used as a |
|||
synonym for :ref:`guest`. For example the code for emulating Arm CPUs is in |
|||
``target/arm/``. However in the :ref:`TCG subsystem <tcg>` "target" refers to the |
|||
architecture which QEMU is running on, i.e. the :ref:`host`. |
|||
|
|||
TCG |
|||
--- |
|||
|
|||
TCG is the QEMU `Tiny Code Generator <tcg>`. It is the JIT (just-in-time) |
|||
compiler we use to emulate a guest CPU in software. |
|||
|
|||
It is one of the accelerators supported by QEMU, and supports a lot of |
|||
guest/host architectures. |
|||
|
|||
User mode |
|||
--------- |
|||
|
|||
QEMU User mode can launch processes compiled for one CPU on another CPU. In this |
|||
mode the CPU is always emulated. In this mode, QEMU translate system calls from |
|||
guest to host kernel. It is available for Linux and BSD. |
|||
|
|||
VirtIO |
|||
------ |
|||
|
|||
VirtIO is an open standard used to define and implement virtual devices with a |
|||
minimal overhead, defining a set of data structures and hypercalls (similar to |
|||
system calls, but targeting an hypervisor, which happens to be QEMU in our |
|||
case). It's designed to be more efficient than emulating a real device, by |
|||
minimizing the amount of interactions between a guest VM and its hypervisor. |
|||
|
|||
vhost-user |
|||
---------- |
|||
|
|||
`Vhost-user <vhost_user>` is an interface used to implement VirtIO devices |
|||
outside of QEMU itself. |
|||
Loading…
Reference in new issue