diff options
Diffstat (limited to 'docs/about')
| -rw-r--r-- | docs/about/build-platforms.rst | 36 | ||||
| -rw-r--r-- | docs/about/deprecated.rst | 315 | ||||
| -rw-r--r-- | docs/about/emulation.rst | 211 | ||||
| -rw-r--r-- | docs/about/removed-features.rst | 199 |
4 files changed, 567 insertions, 194 deletions
diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst index 1552b1a..e95784c 100644 --- a/docs/about/build-platforms.rst +++ b/docs/about/build-platforms.rst @@ -44,8 +44,6 @@ Those hosts are officially supported, with various accelerators: - Accelerators * - Arm - hvf (64 bit only), kvm (64 bit only), tcg, xen - * - MIPS (64 bit little endian only) - - kvm, tcg * - PPC - kvm, tcg * - RISC-V @@ -55,7 +53,7 @@ Those hosts are officially supported, with various accelerators: * - SPARC - tcg * - x86 - - hvf (64 bit only), kvm, nvmm, tcg, whpx (64 bit only), xen + - hvf (64 bit only), mshv (64 bit only), kvm, nvmm, tcg, whpx (64 bit only), xen Other host architectures are not supported. It is possible to build QEMU system emulation on an unsupported host architecture using the configure @@ -101,7 +99,7 @@ Python runtime option of the ``configure`` script to point QEMU to a supported version of the Python runtime. - As of QEMU |version|, the minimum supported version of Python is 3.8. + As of QEMU |version|, the minimum supported version of Python is 3.9. Python build dependencies Some of QEMU's build dependencies are written in Python. Usually these @@ -118,16 +116,30 @@ Rust build dependencies include bindgen or have an older version, it is recommended to install a newer version using ``cargo install bindgen-cli``. - Developers may want to use Cargo-based tools in the QEMU source tree; - this requires Cargo 1.74.0. Note that Cargo is not required in order - to build QEMU. + QEMU requires Rust 1.83.0. This is available on all supported platforms + except for the ``mips64el`` architecture on Debian bookworm. For all other + architectures, Debian bookworm provides a new-enough Rust compiler + in the ``rustc-web`` package. + + For Ubuntu 22.04 ("Jammy") and 24.04 ("Noble") updated versions of + Rust are available through packages such as ``rustc-1.83`` package; + the path to ``rustc`` and ``rustdoc`` has to be provided manually to + the configure script. + + Some distros prefer to avoid vendored crate sources, and instead use + local sources from e.g. ``/usr/share/cargo/registry``. QEMU includes a + script, ``scripts/get-wraps-from-cargo-registry.py``, that automatically + performs this task. The script is meant to be invoked after unpacking + the QEMU tarball. QEMU also includes ``rust/Cargo.toml`` and + ``rust/Cargo.lock`` files that can be used to compute QEMU's build + dependencies, e.g. using ``cargo2rpm -p rust/Cargo.toml buildrequires``. Optional build dependencies - Build components whose absence does not affect the ability to build - QEMU may not be available in distros, or may be too old for QEMU's - requirements. Many of these, such as the Avocado testing framework - or various linters, are written in Python and therefore can also - be installed using ``pip``. Cross compilers are another example + Build components whose absence does not affect the ability to build QEMU + may not be available in distros, or may be too old for our requirements. + Many of these, such as additional modules for the functional testing + framework or various linters, are written in Python and therefore can + also be installed using ``pip``. Cross compilers are another example of optional build-time dependency; in this case it is possible to download them from repositories such as EPEL, to use container-based cross compilation using ``docker`` or ``podman``, or to use pre-built diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index 0f41a99..ac31a2b 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -54,43 +54,6 @@ as short-form boolean values, and passed to plugins as ``arg_name=on``. However, short-form booleans are deprecated and full explicit ``arg_name=on`` form is preferred. -``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Specified CPU topology parameters must be supported by the machine. - -In the SMP configuration, users should provide the CPU topology parameters that -are supported by the target machine. - -However, historically it was allowed for users to specify the unsupported -topology parameter as "1", which is meaningless. So support for this kind of -configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is -marked deprecated since 9.0, users have to ensure that all the topology members -described with -smp are supported by the target machine. - -``-old-param`` option for booting Arm kernels via param_struct (since 10.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The ``-old-param`` command line option is specific to Arm targets: -it is used when directly booting a guest kernel to pass it the -command line and other information via the old ``param_struct`` ABI, -rather than the newer ATAGS or DTB mechanisms. This option was only -ever needed to support ancient kernels on some old board types -like the ``akita`` or ``terrier``; it has been deprecated in the -kernel since 2001. None of the board types QEMU supports need -``param_struct`` support, so this option has been deprecated and will -be removed in a future QEMU version. - -User-mode emulator command line arguments ------------------------------------------ - -``-p`` (since 9.0) -'''''''''''''''''' - -The ``-p`` option pretends to control the host page size. However, -it is not possible to change the host page size, and using the -option only causes failures. - QEMU Machine Protocol (QMP) commands ------------------------------------ @@ -156,37 +119,73 @@ threads (for example, it only reports source side of multifd threads, without reporting any destination threads, or non-multifd source threads). For debugging purpose, please use ``-name $VM,debug-threads=on`` instead. -Incorrectly typed ``device_add`` arguments (since 6.2) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' +``block-job-pause`` (since 10.1) +'''''''''''''''''''''''''''''''' + +Use ``job-pause`` instead. The only difference is that ``job-pause`` +always reports GenericError on failure when ``block-job-pause`` reports +DeviceNotActive when block-job is not found. + +``block-job-resume`` (since 10.1) +''''''''''''''''''''''''''''''''' + +Use ``job-resume`` instead. The only difference is that ``job-resume`` +always reports GenericError on failure when ``block-job-resume`` reports +DeviceNotActive when block-job is not found. + +``block-job-complete`` (since 10.1) +''''''''''''''''''''''''''''''''''' + +Use ``job-complete`` instead. The only difference is that ``job-complete`` +always reports GenericError on failure when ``block-job-complete`` reports +DeviceNotActive when block-job is not found. + +``block-job-dismiss`` (since 10.1) +'''''''''''''''''''''''''''''''''' + +Use ``job-dismiss`` instead. + +``block-job-finalize`` (since 10.1) +''''''''''''''''''''''''''''''''''' + +Use ``job-finalize`` instead. + +``migrate`` argument ``detach`` (since 10.1) +'''''''''''''''''''''''''''''''''''''''''''' + +This argument has always been ignored. + +Human Machine Protocol (HMP) commands +------------------------------------- + +``wavcapture`` (since 10.2) +'''''''''''''''''''''''''''' + +The ``wavcapture`` command is deprecated and will be removed in a future release. + +Use ``-audiodev wav`` or your host audio system to capture audio. + +``stopcapture`` (since 10.2) +'''''''''''''''''''''''''''' + +The ``stopcapture`` command is deprecated and will be removed in a future release. -Due to shortcomings in the internal implementation of ``device_add``, QEMU -incorrectly accepts certain invalid arguments: Any object or list arguments are -silently ignored. Other argument types are not checked, but an implicit -conversion happens, so that e.g. string values can be assigned to integer -device properties or vice versa. +``info`` argument ``capture`` (since 10.2) +'''''''''''''''''''''''''''''''''''''''''' -This is a bug in QEMU that will be fixed in the future so that previously -accepted incorrect commands will return an error. Users should make sure that -all arguments passed to ``device_add`` are consistent with the documented -property types. +The ``info capture`` command is deprecated and will be removed in a future release. Host Architectures ------------------ -Big endian MIPS since 7.2; 32-bit little endian MIPS since 9.2 -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +MIPS (since 10.2) +''''''''''''''''' -As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of -MIPS moved out of support making it hard to maintain our -cross-compilation CI tests of the architecture. As we no longer have -CI coverage support may bitrot away before the deprecation process +MIPS is not supported by Debian 13 ("Trixie") and newer, making it hard to +maintain our cross-compilation CI tests of the architecture. As we no longer +have CI coverage support may bitrot away before the deprecation process completes. -Likewise, the little endian variant of 32 bit MIPS is not supported by -Debian 13 ("Trixie") and newer. - -64 bit little endian MIPS is still a supported host architecture. - System emulation on 32-bit x86 hosts (since 8.0) '''''''''''''''''''''''''''''''''''''''''''''''' @@ -224,27 +223,6 @@ Keeping 32-bit host support alive is a substantial burden for the QEMU project. Thus QEMU will in future drop the support for all 32-bit host systems. -linux-user mode CPUs --------------------- - -iwMMXt emulation and the ``pxa`` CPUs (since 10.0) -'''''''''''''''''''''''''''''''''''''''''''''''''' - -The ``pxa`` CPU family (``pxa250``, ``pxa255``, ``pxa260``, -``pxa261``, ``pxa262``, ``pxa270-a0``, ``pxa270-a1``, ``pxa270``, -``pxa270-b0``, ``pxa270-b1``, ``pxa270-c0``, ``pxa270-c5``) are no -longer used in system emulation, because all the machine types which -used these CPUs were removed in the QEMU 9.2 release. These CPUs can -now only be used in linux-user mode, and to do that you would have to -explicitly select one of these CPUs with the ``-cpu`` command line -option or the ``QEMU_CPU`` environment variable. - -We don't believe that anybody is using the iwMMXt emulation, and we do -not have any tests to validate it or any real hardware or similar -known-good implementation to test against. GCC is in the process of -dropping their support for iwMMXt codegen. These CPU types are -therefore deprecated in QEMU, and will be removed in a future release. - System emulator CPUs -------------------- @@ -275,9 +253,25 @@ embedded 405 for power management (OCC) and other internal tasks, it is theoretically possible to use QEMU to model them. Let's keep the CPU implementation for a while before removing all support. +Power8E and Power8NVL CPUs and corresponding Pnv chips (since 10.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The Power8E and Power8NVL variants of Power8 are not really useful anymore +in qemu, and are old and unmaintained now. + +The CPUs as well as corresponding Power8NVL and Power8E PnvChips will also +be considered deprecated. + System emulator machines ------------------------ +Versioned machine types (aarch64, arm, i386, m68k, ppc64, s390x, x86_64) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +In accordance with our versioned machine type deprecation policy, all machine +types with version |VER_MACHINE_DEPRECATION_VERSION|, or older, have been +deprecated. + Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' @@ -286,23 +280,51 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -Big-Endian variants of MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines (since 9.2) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +Arm ``ast2700a0-evb`` machine (since 10.1) +'''''''''''''''''''''''''''''''''''''''''' + +The ``ast2700a0-evb`` machine represents the first revision of the AST2700 +and serves as the initial engineering sample rather than a production version. +A newer revision, A1, is now supported, and the ``ast2700a1-evb`` should +replace the older A0 version. -Both ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` were added for little endian -CPUs. Big endian support is not tested. +Arm ``sonorapass-bmc`` machine (since 10.2) +''''''''''''''''''''''''''''''''''''''''''' -Mips ``mipssim`` machine (since 10.0) -''''''''''''''''''''''''''''''''''''' +The ``sonorapass-bmc`` machine represents a lab server that never +entered production. Since it does not rely on any specific device +models, it can be replaced by the ``ast2500-evb`` machine using the +``fmc-model`` option to specify the flash type. The I2C devices +connected to the board can be defined via the QEMU command line. + +Arm ``qcom-dc-scm-v1-bmc`` and ``qcom-firework-bmc`` machine (since 10.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``qcom-dc-scm-v1-bmc`` and ``qcom-firework-bmc`` represent lab +servers that never entered production. Since they do not rely on any +specific device models, they can be replaced by the ``ast2600-evb`` +machine using the ``fmc-model`` option to specify the flash type. The +I2C devices connected to the board can be defined via the QEMU command +line. + +Arm ``fp5280g2-bmc`` machine (since 10.2) +''''''''''''''''''''''''''''''''''''''''' + +The ``fp5280g2-bmc`` machine does not rely on any specific device +models, it can be replaced by the ``ast2500-evb`` machine using the +``fmc-model`` option to specify the flash type. The I2C devices +connected to the board can be defined via the QEMU command line. + +Arm ``fby35`` machine (since 10.2) +'''''''''''''''''''''''''''''''''' + +The ``fby35`` machine was originally added as an example of a +multi-SoC system, with the expectation the models would evolve over +time in an heterogeneous system. This hasn't happened and no public +firmware is available to boot it. It can be replaced by the +``ast2700fc``, another multi-SoC machine based on the newer AST2700 +SoCs which are excepted to receive better support in the future. -Linux dropped support for this virtual machine type in kernel v3.7, and -there does not seem to be anybody around who is still using this board -in QEMU: Most former MIPS-related people are working on other architectures -in their everyday job nowadays, and we are also not aware of anybody still -using old binaries with this board (i.e. there is also no binary available -online to check that this board did not completely bitrot yet). It is -recommended to use another MIPS machine for future MIPS code development -instead. RISC-V default machine option (since 10.0) '''''''''''''''''''''''''''''''''''''''''' @@ -321,6 +343,26 @@ they want to use and avoids confusion. Existing users of the ``spike`` machine must ensure that they're setting the ``spike`` machine in the command line (``-M spike``). +Arm ``highbank`` and ``midway`` machines (since 10.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +There are no known users left for these machines (if you still use it, +please write a mail to the qemu-devel mailing list). If you just want to +boot a Cortex-A15 or Cortex-A9 Linux, use the ``virt`` machine instead. + + +System emulator binaries +------------------------ + +``qemu-system-microblazeel`` (since 10.1) +''''''''''''''''''''''''''''''''''''''''' + +The ``qemu-system-microblaze`` binary can emulate little-endian machines +now, too, so the separate binary ``qemu-system-microblazeel`` (with the +``el`` suffix) for little-endian targets is not required anymore. The +``petalogix-s3adsp1800`` machine can now be switched to little endian by +setting its ``endianness`` property to ``little``. + Backend options --------------- @@ -340,6 +382,15 @@ Options are: - move backing file to NVDIMM storage and keep ``pmem=on`` (to have NVDIMM with persistence guaranties). +Using an external DH (Diffie-Hellman) parameters file (since 10.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Loading of external Diffie-Hellman parameters from a 'dh-params.pem' +file is deprecated and will be removed with no replacement in a +future release. Where no 'dh-params.pem' file is provided, the DH +parameters will be automatically negotiated in accordance with +RFC7919. + Device options -------------- @@ -393,12 +444,6 @@ recommending to switch to their stable counterparts: - "Zve64f" should be replaced with "zve64f" - "Zve64d" should be replaced with "zve64d" -``-device sd-card,spec_version=1`` (since 9.1) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -SD physical layer specification v2.00 supersedes the v1.10 one. -v2.00 is the default since QEMU 3.0.0. - Block device options '''''''''''''''''''' @@ -449,58 +494,10 @@ Backend ``memory`` (since 9.0) ``memory`` is a deprecated synonym for ``ringbuf``. -``reconnect`` (since 9.2) -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``reconnect`` option only allows specifiying second granularity timeouts, -which is not enough for all types of use cases, use ``reconnect-ms`` instead. - - -Net device options -'''''''''''''''''' - -Stream ``reconnect`` (since 9.2) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``reconnect`` option only allows specifiying second granularity timeouts, -which is not enough for all types of use cases, use ``reconnect-ms`` instead. - -VFIO device options -''''''''''''''''''' - -``-device vfio-calxeda-xgmac`` (since 10.0) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank -10Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility -string) to a guest. Calxeda HW has been ewasted now and there is no point -keeping that device. - -``-device vfio-amd-xgbe`` (since 10.0) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller -to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle" -is not supported anymore and there is no point keeping that device. - -``-device vfio-platform`` (since 10.0) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The vfio-platform device allows to assign a host platform device -to a guest in a generic manner. Integrating a new device into -the vfio-platform infrastructure requires some adaptation at -both kernel and qemu level. No such attempt has been done for years -and the conclusion is that vfio-platform has not got any traction. -PCIe passthrough shall be the mainline solution. CPU device properties ''''''''''''''''''''' -``pcommit`` on x86 (since 9.1) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The PCOMMIT instruction was never included in any physical processor. -It was implemented as a no-op instruction in TCG up to QEMU 9.0, but -only with ``-cpu max`` (which does not guarantee migration compatibility -across versions). - ``pmu-num=n`` on RISC-V CPUs (since 8.2) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -510,6 +507,14 @@ be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits must be left clear. +``pcommit`` on x86 (since 9.1) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The PCOMMIT instruction was never included in any physical processor. +It was implemented as a no-op instruction in TCG up to QEMU 9.0, but +only with ``-cpu max`` (which does not guarantee migration compatibility +across versions). + Backwards compatibility ----------------------- @@ -550,6 +555,20 @@ available firmwares that are using the current (wrong) name. The property is kept as is in 9.1, together with "riscv,delegation", to give more time for firmware developers to change their code. +x86 "isapc" board use of modern x86 CPUs (since 10.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The "isapc" board represents a historical x86 ISA PC and is intended for +older 32-bit x86 CPU models, defaulting to a 486 CPU model. Previously it +was possible (but non-sensical) to specify a more modern x86 CPU, including +``-cpu host`` or ``-cpu max`` even if the features were incompatible with many +of the intended guest OSs. + +If the user requests a modern x86 CPU model (i.e. not one of ``486``, +``athlon``, ``kvm32``, ``pentium``, ``pentium2``, ``pentium3``or ``qemu32``) +a warning will be displayed until a future QEMU version when such CPUs will +be rejected. + Migration --------- diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst index a72591e..4a7d1f4 100644 --- a/docs/about/emulation.rst +++ b/docs/about/emulation.rst @@ -811,6 +811,217 @@ This plugin can limit the number of Instructions Per Second that are executed:: * - ips=N - Maximum number of instructions per cpu that can be executed in one second. The plugin will sleep when the given number of instructions is reached. + * - ipq=N + - Instructions per quantum. How many instructions before we re-calculate time. + The lower the number the more accurate time will be, but the less efficient the plugin. + Defaults to ips/10 + +Uftrace +....... + +``contrib/plugins/uftrace.c`` + +This plugin generates a binary trace compatible with +`uftrace <https://github.com/namhyung/uftrace>`_. + +Plugin supports aarch64 and x64, and works in user and system mode, allowing to +trace a system boot, which is not something possible usually. + +In user mode, the memory mapping is directly copied from ``/proc/self/maps`` at +the end of execution. Uftrace should be able to retrieve symbols by itself, +without any additional step. +In system mode, the default memory mapping is empty, and you can generate +one (and associated symbols) using ``contrib/plugins/uftrace_symbols.py``. +Symbols must be present in ELF binaries. + +It tracks the call stack (based on frame pointer analysis). Thus, your program +and its dependencies must be compiled using ``-fno-omit-frame-pointer +-mno-omit-leaf-frame-pointer``. In 2024, `Ubuntu and Fedora enabled it by +default again on x64 +<https://www.brendangregg.com/blog/2024-03-17/the-return-of-the-frame-pointers.html>`_. +On aarch64, this is less of a problem, as they are usually part of the ABI, +except for leaf functions. That's true for user space applications, but not +necessarily for bare metal code. You can read this `section +<uftrace_build_system_example>` to easily build a system with frame pointers. + +When tracing long scenarios (> 1 min), the generated trace can become very long, +making it hard to extract data from it. In this case, a simple solution is to +trace execution while generating a timestamped output log using +``qemu-system-aarch64 ... | ts "%s"``. Then, ``uftrace --time-range=start~end`` +can be used to reduce trace for only this part of execution. + +Performance wise, overhead compared to normal tcg execution is around x5-x15. + +.. list-table:: Uftrace plugin arguments + :widths: 20 80 + :header-rows: 1 + + * - Option + - Description + * - trace-privilege-level=[on|off] + - Generate separate traces for each privilege level (Exception Level + + Security State on aarch64, Rings on x64). + +.. list-table:: uftrace_symbols.py arguments + :widths: 20 80 + :header-rows: 1 + + * - Option + - Description + * - elf_file [elf_file ...] + - path to an ELF file. Use /path/to/file:0xdeadbeef to add a mapping offset. + * - --prefix-symbols + - prepend binary name to symbols + +Example user trace +++++++++++++++++++ + +As an example, we can trace qemu itself running git:: + + $ ./build/qemu-aarch64 -plugin \ + build/contrib/plugins/libuftrace.so \ + ./build/qemu-aarch64 /usr/bin/git --help + + # and generate a chrome trace directly + $ uftrace dump --chrome | gzip > ~/qemu_aarch64_git_help.json.gz + +For convenience, you can download this trace `qemu_aarch64_git_help.json.gz +<https://github.com/pbo-linaro/qemu-assets/raw/refs/heads/master/qemu-uftrace/qemu_aarch64_git_help.json.gz>`_. +Download it and open this trace on https://ui.perfetto.dev/. You can zoom in/out +using :kbd:`W`, :kbd:`A`, :kbd:`S`, :kbd:`D` keys. +Some sequences taken from this trace: + +- Loading program and its interpreter + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/loader_exec.png?raw=true + :height: 200px + +- open syscall + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/open_syscall.png?raw=true + :height: 200px + +- TB creation + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/tb_translation.png?raw=true + :height: 200px + +It's usually better to use ``uftrace record`` directly. However, tracing +binaries through qemu-user can be convenient when you don't want to recompile +them (``uftrace record`` requires instrumentation), as long as symbols are +present. + +Example system trace +++++++++++++++++++++ + +A full trace example (chrome trace, from instructions below) generated from a +system boot can be found `here +<https://github.com/pbo-linaro/qemu-assets/raw/refs/heads/master/qemu-uftrace/aarch64_boot.json.gz>`_. +Download it and open this trace on https://ui.perfetto.dev/. You can see code +executed for all privilege levels, and zoom in/out using +:kbd:`W`, :kbd:`A`, :kbd:`S`, :kbd:`D` keys. You can find below some sequences +taken from this trace: + +- Two first stages of boot sequence in Arm Trusted Firmware (EL3 and S-EL1) + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/bl3_to_bl1.png?raw=true + :height: 200px + +- U-boot initialization (until code relocation, after which we can't track it) + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/uboot.png?raw=true + :height: 200px + +- Stat and open syscalls in kernel + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/stat.png?raw=true + :height: 200px + +- Timer interrupt + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/timer_interrupt.png?raw=true + :height: 200px + +- Poweroff sequence (from kernel back to firmware, NS-EL2 to EL3) + +.. image:: https://github.com/pbo-linaro/qemu-assets/blob/master/qemu-uftrace/poweroff.png?raw=true + :height: 200px + +Build and run system example +++++++++++++++++++++++++++++ + +.. _uftrace_build_system_example: + +Building a full system image with frame pointers is not trivial. + +We provide a `simple way <https://github.com/pbo-linaro/qemu-linux-stack>`_ to +build an aarch64 system, combining Arm Trusted firmware, U-boot, Linux kernel +and debian userland. It's based on containers (``podman`` only) and +``qemu-user-static (binfmt)`` to make sure it's easily reproducible and does not depend +on machine where you build it. + +You can follow the exact same instructions for a x64 system, combining edk2, +Linux, and Ubuntu, simply by switching to +`x86_64 <https://github.com/pbo-linaro/qemu-linux-stack/tree/x86_64>`_ branch. + +To build the system:: + + # Install dependencies + $ sudo apt install -y podman qemu-user-static + + $ git clone https://github.com/pbo-linaro/qemu-linux-stack + $ cd qemu-linux-stack + $ ./build.sh + + # system can be started using: + $ ./run.sh /path/to/qemu-system-aarch64 + +To generate a uftrace for a system boot from that:: + + # run true and poweroff the system + $ env INIT=true ./run.sh path/to/qemu-system-aarch64 \ + -plugin path/to/contrib/plugins/libuftrace.so,trace-privilege-level=on + + # generate symbols and memory mapping + $ path/to/contrib/plugins/uftrace_symbols.py \ + --prefix-symbols \ + arm-trusted-firmware/build/qemu/debug/bl1/bl1.elf \ + arm-trusted-firmware/build/qemu/debug/bl2/bl2.elf \ + arm-trusted-firmware/build/qemu/debug/bl31/bl31.elf \ + u-boot/u-boot:0x60000000 \ + linux/vmlinux + + # inspect trace with + $ uftrace replay + +Uftrace allows to filter the trace, and dump flamegraphs, or a chrome trace. +This last one is very interesting to see visually the boot process:: + + $ uftrace dump --chrome > boot.json + # Open your browser, and load boot.json on https://ui.perfetto.dev/. + +Long visual chrome traces can't be easily opened, thus, it might be +interesting to generate them around a particular point of execution:: + + # execute qemu and timestamp output log + $ env INIT=true ./run.sh path/to/qemu-system-aarch64 \ + -plugin path/to/contrib/plugins/libuftrace.so,trace-privilege-level=on |& + ts "%s" | tee exec.log + + $ cat exec.log | grep 'Run /init' + 1753122320 [ 11.834391] Run /init as init process + # init was launched at 1753122320 + + # generate trace around init execution (2 seconds): + $ uftrace dump --chrome --time-range=1753122320~1753122322 > init.json + +Count traps +........... + +``contrib/plugins/traps.c`` + +This plugin counts the number of interrupts (asyncronous events), exceptions +(synchronous events) and host calls (e.g. semihosting) per cpu. Other emulation features ------------------------ diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst index 2527a91..422b9c9 100644 --- a/docs/about/removed-features.rst +++ b/docs/about/removed-features.rst @@ -162,6 +162,12 @@ specified with ``-mem-path`` can actually provide the guest RAM configured with The ``name`` parameter of the ``-net`` option was a synonym for the ``id`` parameter, which should now be used instead. +RISC-V firmware not booted by default (removed in 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default`` +for the RISC-V ``virt`` machine and ``sifive_u`` machine. + ``-numa node,mem=...`` (removed in 5.1) ''''''''''''''''''''''''''''''''''''''' @@ -324,12 +330,6 @@ devices. Drives the board doesn't pick up can no longer be used with This option was undocumented and not used in the field. Use ``-device usb-ccid`` instead. -RISC-V firmware not booted by default (removed in 5.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default`` -for the RISC-V ``virt`` machine and ``sifive_u`` machine. - ``-no-quit`` (removed in 7.0) ''''''''''''''''''''''''''''' @@ -560,6 +560,18 @@ the options along with the machine models they were intended for. Use ``-run-with user=..`` instead. +``-old-param`` option for booting Arm kernels via param_struct (removed in 10.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``-old-param`` command line option was specific to Arm targets: +it was used when directly booting a guest kernel to pass it the +command line and other information via the old ``param_struct`` ABI, +rather than the newer ATAGS or DTB mechanisms. This option was only +ever needed to support ancient kernels on some old board types +like the ``akita`` or ``terrier``; it has been deprecated in the +kernel since 2001. None of the board types QEMU supports need +``param_struct`` support, so this option has been removed. + User-mode emulator command line arguments ----------------------------------------- @@ -571,6 +583,14 @@ The ``-singlestep`` option has been given a name that better reflects what it actually does. For both linux-user and bsd-user, use the ``-one-insn-per-tb`` option instead. +``-p`` (removed in 10.2) +'''''''''''''''''''''''' + +The ``-p`` option pretends to control the host page size. However, +it is not possible to change the host page size; we stopped trying +to do anything with the option except print a warning from 9.0, +and now the option is removed entirely. + QEMU Machine Protocol (QMP) commands ------------------------------------ @@ -722,6 +742,15 @@ Use ``multifd-channels`` instead. Use ``multifd-compression`` instead. +Incorrectly typed ``device_add`` arguments (removed in 9.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Due to shortcomings in the internal implementation of ``device_add``, +QEMU used to incorrectly accept certain invalid arguments. Any object +or list arguments were silently ignored. Other argument types were not +checked, but an implicit conversion happened, so that e.g. string +values could be assigned to integer device properties or vice versa. + QEMU Machine Protocol (QMP) events ---------------------------------- @@ -858,6 +887,26 @@ QEMU. Since all recent x86 hardware from the past >10 years is capable of the 64-bit x86 extensions, a corresponding 64-bit OS should be used instead. +32-bit hosts for 64-bit guests (removed in 10.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +In general, 32-bit hosts cannot support the memory space or atomicity +requirements of 64-bit guests. Prior to 10.0, QEMU attempted to +work around the atomicity issues in system mode by running all vCPUs +in a single thread context; in user mode atomicity was simply broken. +From 10.0, QEMU has disabled configuration of 64-bit guests on 32-bit hosts. + +32-bit MIPS (since 10.2) +'''''''''''''''''''''''' + +Debian 12 "Bookworm" removed support for 32-bit MIPS, making it hard to +maintain our cross-compilation CI tests of the architecture. + +32-bit PPC (since 10.2) +''''''''''''''''''''''' + +The QEMU project no longer supports 32-bit host builds. + Guest Emulator ISAs ------------------- @@ -893,14 +942,6 @@ The RISC-V no MMU cpus have been removed. The two CPUs: ``rv32imacu-nommu`` and ``rv64imacu-nommu`` can no longer be used. Instead the MMU status can be specified via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. -RISC-V 'any' CPU type ``-cpu any`` (removed in 9.2) -''''''''''''''''''''''''''''''''''''''''''''''''''' - -The 'any' CPU type was introduced back in 2018 and was around since the -initial RISC-V QEMU port. Its usage was always been unclear: users don't know -what to expect from a CPU called 'any', and in fact the CPU does not do anything -special that isn't already done by the default CPUs rv32/rv64. - ``compat`` property of server class POWER CPUs (removed in 6.0) ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' @@ -947,6 +988,14 @@ The CRIS architecture was pulled from Linux in 4.17 and the compiler was no longer packaged in any distro making it harder to run the ``check-tcg`` tests. +RISC-V 'any' CPU type ``-cpu any`` (removed in 9.2) +''''''''''''''''''''''''''''''''''''''''''''''''''' + +The 'any' CPU type was introduced back in 2018 and was around since the +initial RISC-V QEMU port. Its usage was always been unclear: users don't know +what to expect from a CPU called 'any', and in fact the CPU does not do anything +special that isn't already done by the default CPUs rv32/rv64. + System accelerators ------------------- @@ -957,25 +1006,27 @@ Userspace local APIC with KVM (x86, removed in 8.0) a local APIC. The ``split`` setting is supported, as is using ``-M kernel-irqchip=off`` when the CPU does not have a local APIC. -HAXM (``-accel hax``) (removed in 8.2) -'''''''''''''''''''''''''''''''''''''' - -The HAXM project has been retired (see https://github.com/intel/haxm#status). -Use "whpx" (on Windows) or "hvf" (on macOS) instead. - MIPS "Trap-and-Emulate" KVM support (removed in 8.0) '''''''''''''''''''''''''''''''''''''''''''''''''''' The MIPS "Trap-and-Emulate" KVM host and guest support was removed from Linux in 2021, and is not supported anymore by QEMU either. +HAXM (``-accel hax``) (removed in 8.2) +'''''''''''''''''''''''''''''''''''''' + +The HAXM project has been retired (see https://github.com/intel/haxm#status). +Use "whpx" (on Windows) or "hvf" (on macOS) instead. + System emulator machines ------------------------ -Note: Versioned machine types that have been introduced in a QEMU version -that has initially been released more than 6 years before are considered -obsolete and will be removed without further notice in this document. -Please use newer machine types instead. +Versioned machine types (aarch64, arm, i386, m68k, ppc64, s390x, x86_64) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +In accordance with our versioned machine type deprecation policy, all machine +types with version |VER_MACHINE_DELETION_VERSION|, or older, have been +removed. ``s390-virtio`` (removed in 2.6) '''''''''''''''''''''''''''''''' @@ -1024,16 +1075,6 @@ Aspeed ``swift-bmc`` machine (removed in 7.0) This machine was removed because it was unused. Alternative AST2500 based OpenPOWER machines are ``witherspoon-bmc`` and ``romulus-bmc``. -Aspeed ``tacoma-bmc`` machine (removed in 10.0) -''''''''''''''''''''''''''''''''''''''''''''''' - -The ``tacoma-bmc`` machine was removed because it didn't bring much -compared to the ``rainier-bmc`` machine. Also, the ``tacoma-bmc`` was -a board used for bring up of the AST2600 SoC that never left the -labs. It can be easily replaced by the ``rainier-bmc`` machine, which -was the actual final product, or by the ``ast2600-evb`` with some -tweaks. - ppc ``taihu`` machine (removed in 7.2) ''''''''''''''''''''''''''''''''''''''''''''' @@ -1064,6 +1105,16 @@ for all machine types using the PXA2xx and OMAP2 SoCs. We are also dropping the ``cheetah`` OMAP1 board, because we don't have any test images for it and don't know of anybody who does. +Aspeed ``tacoma-bmc`` machine (removed in 10.0) +''''''''''''''''''''''''''''''''''''''''''''''' + +The ``tacoma-bmc`` machine was removed because it didn't bring much +compared to the ``rainier-bmc`` machine. Also, the ``tacoma-bmc`` was +a board used for bring up of the AST2600 SoC that never left the +labs. It can be easily replaced by the ``rainier-bmc`` machine, which +was the actual final product, or by the ``ast2600-evb`` with some +tweaks. + ppc ``ref405ep`` machine (removed in 10.0) '''''''''''''''''''''''''''''''''''''''''' @@ -1071,6 +1122,20 @@ This machine was removed because PPC 405 CPU have no known users, firmware images are not available, OpenWRT dropped support in 2019, U-Boot in 2017, and Linux in 2024. +Big-Endian variants of ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines (removed in 10.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Both the MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines +were added for little endian CPUs. Big endian support was never tested +and likely never worked. Starting with QEMU v10.1, the machines are now +only available as little-endian machines. + +Mips ``mipssim`` machine (removed in 10.2) +'''''''''''''''''''''''''''''''''''''''''' + +Linux dropped support for this virtual machine type in kernel v3.7, and +there was also no binary available online to use with that board. + linux-user mode CPUs -------------------- @@ -1096,6 +1161,20 @@ reason the maintainers strongly suspected no one actually used it. QEMU Nios II architecture was orphan; Intel has EOL'ed the Nios II processor IP (see `Intel discontinuance notification`_). +iwMMXt emulation and the ``pxa`` CPUs (removed in 10.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``pxa`` CPU family (``pxa250``, ``pxa255``, ``pxa260``, +``pxa261``, ``pxa262``, ``pxa270-a0``, ``pxa270-a1``, ``pxa270``, +``pxa270-b0``, ``pxa270-b1``, ``pxa270-c0``, ``pxa270-c5``) were +not available in system emulation, because all the machine types which +used these CPUs were removed in the QEMU 9.2 release. We don't +believe that anybody was using the iwMMXt emulation (which you +would have to explicitly enable on the command line), and we did +not have any tests to validate it or any real hardware or similar +known-good implementation to test against. These CPUs have +therefore been removed in linux-user mode as well. + TCG introspection features -------------------------- @@ -1149,6 +1228,11 @@ by using ``-machine graphics=off``. The 'pvrdma' device and the whole RDMA subsystem have been removed. +``-device sd-card,spec_version=1`` (since 10.2) +''''''''''''''''''''''''''''''''''''''''''''''' + +SD physical layer specification v2.00 supersedes the v1.10 one. + Related binaries ---------------- @@ -1233,6 +1317,31 @@ The corresponding upstream server project is no longer maintained. Users are recommended to switch to an alternative distributed block device driver such as RBD. +VFIO devices +------------ + +``-device vfio-calxeda-xgmac`` (since 10.2) +''''''''''''''''''''''''''''''''''''''''''' +The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank +10Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility +string) to a guest. Calxeda HW has been ewasted now and there is no point +keeping that device. + +``-device vfio-amd-xgbe`` (since 10.2) +'''''''''''''''''''''''''''''''''''''' +The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller +to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle" +is not supported anymore and there is no point keeping that device. + +``-device vfio-platform`` (since 10.2) +'''''''''''''''''''''''''''''''''''''' +The vfio-platform device allows to assign a host platform device +to a guest in a generic manner. Integrating a new device into +the vfio-platform infrastructure requires some adaptation at +both kernel and qemu level. No such attempt has been done for years +and the conclusion is that vfio-platform has not got any traction. +PCIe passthrough shall be the mainline solution. + Tools ----- @@ -1263,4 +1372,26 @@ The ``blacklist`` config file option has been renamed to ``block-rpcs`` (to be in sync with the renaming of the corresponding command line option). +Device options +-------------- + +Character device options +'''''''''''''''''''''''' + +``reconnect`` (removed in 10.2) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``reconnect`` has been replaced by ``reconnect-ms``, which provides +better precision. + +Net device options +'''''''''''''''''' + +Stream ``reconnect`` (removed in 10.2) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``reconnect`` has been replaced by ``reconnect-ms``, which provides +better precision. + + .. _Intel discontinuance notification: https://www.intel.com/content/www/us/en/content-details/781327/intel-is-discontinuing-ip-ordering-codes-listed-in-pdn2312-for-nios-ii-ip.html |