QEMU

https://qemu-project.gitlab.io/qemu/
Admin
QEMU is a free and open-source emulator and virtualizer that performs hardware virtualization to...
Tokens:706,521
Snippets:4,261
Trust Score:7
Update:1 year ago
Show doc for...
Tokens:
Raw
### QEMU Monitor Command: Hello-World Example

Source: https://qemu-project.gitlab.io/qemu/devel/index-internals

Provides a step-by-step guide on writing a simple monitor command in QEMU, using 'hello-world' as a basic example.

```c
/* Example of defining a simple monitor command */
#include "monitor/monitor.h"
#include "monitor/qdev-monitor.h"

static void monitor_hello_world(Monitor *mon, const QDict *qdict) {
    qmon_printf(mon, "Hello, QEMU World!\n");
}

static MonitorCmd hello_cmd = {
    .name = "hello-world",
    .handler = monitor_hello_world,
    .args_type = "",
    .params = "",
    .help = "Prints a greeting."
};

static void hello_mon_register(void) {
    monitor_register_cmd(&hello_cmd);
}

// Call hello_mon_register() during QEMU initialization.
```

--------------------------------

### Start vhost-user Daemon Example (Shell)

Source: https://qemu-project.gitlab.io/qemu/system/devices/vhost-user

An example shell command to start a hypothetical vhost-user daemon named 'virtio-foo'. It specifies a socket path for communication.

```bash
$ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
```

--------------------------------

### KVM COLO Setup Example

Source: https://qemu-project.gitlab.io/qemu/system/invocation

Example configuration for KVM COLO, setting up a tap network device, an e1000 network device, and a character device for mirroring.

```bash
-netdev tap,id=hn0,vhost=off
-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
```

--------------------------------

### Install QEMU Build Dependencies on Debian/Ubuntu

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Installs QEMU build dependencies on Debian/Ubuntu systems. This involves updating the package list and then installing the build dependencies for QEMU using APT.

```bash
sudo apt update && sudo apt build-dep qemu
```

--------------------------------

### Passt Migration: Source Setup

Source: https://qemu-project.gitlab.io/qemu/system/devices/net

Steps to set up the source side for QEMU migration with passt, including starting passt and passt-repair with specified socket paths.

```bash
passt --vhost-user --socket ~/passt_src.socket --repair-path ~/passt-repair_src.socket
```

```bash
passt-repair ~/passt-repair_src.socket
```

```bash
qemu-system-x86_64 [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio
```

--------------------------------

### Install Core MSYS2 Packages for QEMU

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Installs essential packages required for building QEMU within an MSYS2 environment. This includes development tools, libraries, and specific QEMU dependencies.

```shell
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
```

--------------------------------

### Start Interpretive Execution (SIE) Instruction Example

Source: https://qemu-project.gitlab.io/qemu/system/targets

This section provides examples of using the Start Interpretive Execution (SIE) instruction, including valid and invalid configurations for s390x architecture. These examples illustrate how to manage protected execution environments.

```assembly
; Example 1: Valid configuration for SIE instruction
; Assume R1 points to a valid SIE control block
SIE

; Example 2: Another valid configuration scenario
; ...
SIE

; Example 3: Invalid configuration scenario (e.g., control block issues)
; ...
; SIE (may result in an interruption or error)

```

--------------------------------

### Install MSYS2 Dependencies using PKGBUILD

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Installs QEMU build dependencies on MSYS2 by downloading and processing the official PKGBUILD file. This method ensures all necessary components are fetched and built.

```shell
pacman -S wget base-devel git
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 --syncdeps --nobuild PKGBUILD || true
```

--------------------------------

### QEMU aarch64 VM Setup: Machine and Memory

Source: https://qemu-project.gitlab.io/qemu/system/introduction

Example of configuring an aarch64 virtual machine with the 'virt' machine type, enabling virtualization, and setting up pflash devices.

```bash
$ qemu-system-aarch64 \
   -machine type=virt,virtualization=on,pflash0=rom,pflash1=efivars \
   -m 4096 \
```

--------------------------------

### Build libcanokey-qemu

Source: https://qemu-project.gitlab.io/qemu/system/devices/canokey

Steps to clone the canokey-qemu repository, create a build directory, and install the libcanokey-qemu library. It includes options for specifying an installation prefix.

```bash
git clone https://github.com/canokeys/canokey-qemu

```

```bash
mkdir canokey-qemu/build
pushd canokey-qemu/build

```

```bash
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/your/place

```

```bash
make
make install # may need sudo
popd

```

--------------------------------

### Download Precompiled Shakti SDK Examples

Source: https://qemu-project.gitlab.io/qemu/system/riscv/shakti-c

Downloads a zip archive containing precompiled example applications for the Shakti SDK and then unzips the archive.

```bash
wget -c https://gitlab.com/behindbytes/shakti-binaries/-/raw/master/sdk/shakti_sdk_qemu.zip
unzip shakti_sdk_qemu.zip
```

--------------------------------

### Passt Migration: Destination Setup

Source: https://qemu-project.gitlab.io/qemu/system/devices/net

Details on configuring the destination side for QEMU migration with passt, including starting passt and passt-repair for the target VM.

```bash
passt --vhost-user --socket ~/passt_dst.socket --repair-path ~/passt-repair_dst.socket
```

```bash
passt-repair ~/passt-repair_dst.socket
```

```bash
qemu-system-x86_64 [...OPTIONS...] [...VHOST USER OPTIONS...] -incoming tcp:localhost:4444
```

--------------------------------

### QEMU Instance with vhost-user Backend (Shell)

Source: https://qemu-project.gitlab.io/qemu/system/devices/vhost-user

An example shell command demonstrating how to start a QEMU x86_64 instance with a vhost-user backend. It configures memory, a character device for the socket, the vhost-user device itself, and shared memory.

```bash
$ qemu-system-x86_64 \
    -m 4096 \
    -chardev socket,id=ba1,path=/var/run/foo.sock \
    -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \
    -object memory-backend-memfd,id=mem,size=4G,share=on \
    -numa node,memdev=mem \
      ...
```

--------------------------------

### QATzip Installation on Ubuntu

Source: https://qemu-project.gitlab.io/qemu/devel/migration/qatzip-compression

Provides commands to search for and install the QATzip package and its development files on Ubuntu systems. This includes installing the library and the command-line tool.

```bash
#apt search qatzip
libqatzip-dev/noble 1.2.0-0ubuntu3 amd64
  Intel QuickAssist user space library development files

libqatzip3/noble 1.2.0-0ubuntu3 amd64
  Intel QuickAssist user space library

qatzip/noble,now 1.2.0-0ubuntu3 amd64 [installed]
  Compression user-space tool for Intel QuickAssist Technology

#sudo apt install libqatzip-dev libqatzip3 qatzip
```

--------------------------------

### Default Configuration Example in Makefile

Source: https://qemu-project.gitlab.io/qemu/devel/kconfig

This is an example of a default configuration file (`TARGETNAME-softmmu.mak`) used in QEMU. It initializes Kconfig variables and provides a starting point for enabling devices and subsystems, often by commenting out lines to disable optional components.

```makefile
# Default configuration for alpha-softmmu

# Uncomment the following lines to disable these optional devices:
#
#CONFIG_PCI_DEVICES=n
#CONFIG_TEST_DEVICES=n

# Boards:

```

--------------------------------

### Start QEMU with S390x CPU Topology

Source: https://qemu-project.gitlab.io/qemu/devel/s390-cpu-topology

Example command to start a QEMU system with S390x architecture, specifying CPU configuration including drawers, books, sockets, and cores. This sets up the environment for topology management.

```bash
qemu-system-s390x \
   -enable-kvm \
   -cpu z14,ctop=on \
   -smp 1,drawers=3,books=3,sockets=2,cores=2,maxcpus=36 \
   -device z14-s390x-cpu,core-id=19,entitlement=high \
   -device z14-s390x-cpu,core-id=11,entitlement=low \
   -device z14-s390x-cpu,core-id=12,entitlement=high \
  ...
```

--------------------------------

### Example: QEMU with vhost-user

Source: https://qemu-project.gitlab.io/qemu/system/invocation

An example demonstrating how to set up QEMU with a vhost-user network backend. It includes memory backend configuration, NUMA setup, character device for the socket, and the vhost-user netdev connected to a virtio-net-pci device.

```bash
qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
     -numa node,memdev=mem \
     -chardev socket,id=chr0,path=/path/to/socket \
     -netdev type=vhost-user,id=net0,chardev=chr0 \
     -device virtio-net-pci,netdev=net0
```

--------------------------------

### QEMU VNC Initialization (No Start)

Source: https://qemu-project.gitlab.io/qemu/system/invocation

Initializes VNC but does not start the server, allowing it to be started later via the monitor command.

```Shell
none
```

--------------------------------

### QEMU QMP Protocol Notation Example

Source: https://qemu-project.gitlab.io/qemu/interop/qemu-storage-daemon-qmp-ref

This snippet illustrates the notation used in examples for the QEMU Storage Daemon QMP Reference Manual. It shows how client-sent commands and server-sent responses/events are represented using '->' and '<-' prefixes respectively. The text highlights that while examples are formatted for readability, actual protocol usage often emits data on a single line.

```text
-> ... text sent by client (commands) ...
<- ... text sent by server (command responses and events) ...
```

--------------------------------

### Install QEMU Build Dependencies on macOS

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Installs QEMU build dependencies on macOS using Homebrew. It first updates Homebrew and then installs all build dependencies required for QEMU.

```bash
brew update && brew install $(brew deps --include-build qemu)
```

--------------------------------

### Install Bindgen CLI with Cargo

Source: https://qemu-project.gitlab.io/qemu/about/build-platforms

Provides instructions for installing a newer version of the `bindgen-cli` tool using `cargo install`, as recommended when a distribution does not include `bindgen` or has an older version.

```Shell
cargo install bindgen-cli
```

--------------------------------

### Start VNC Client

Source: https://qemu-project.gitlab.io/qemu/system/invocation

Starts a VNC client and switches to virtual console 2 using the Ctrl-Alt-2 key combination.

```bash
vncviewer :0
```

--------------------------------

### Install QEMU Build Dependencies on Fedora

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Installs QEMU build dependencies on Fedora systems using the DNF package manager. It updates the system and then installs the build dependencies for QEMU.

```bash
sudo dnf update && sudo dnf builddep qemu
```

--------------------------------

### Build and Install QPL Library

Source: https://qemu-project.gitlab.io/qemu/devel/migration/qpl-compression

Steps to clone the QPL repository, build it using CMake with specific release and shared library configurations, and install it. This process sets up the QPL library for use in projects.

```bash
#!/bin/bash
git clone --recursive https://github.com/intel/qpl.git qpl
mkdir qpl/build
cd qpl/build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DQPL_LIBRARY_TYPE=SHARED ..
sudo cmake --build . --target install
```

--------------------------------

### QEMU Help for Device Options

Source: https://qemu-project.gitlab.io/qemu/system/introduction

Shows how to get help on specific device options, such as those for a SCSI hard disk.

```bash
$ qemu-system-x86_64 -device scsi-hd,help
```

--------------------------------

### QEMU Help for Machine Types

Source: https://qemu-project.gitlab.io/qemu/system/introduction

Demonstrates how to query QEMU for a list of supported machine types for a specific architecture.

```bash
$ qemu-system-x86_64 -M help
```

--------------------------------

### Get Start Address of Text Segment

Source: https://qemu-project.gitlab.io/qemu/devel/tcg-plugins

Returns the nominal start address of the main text segment in user-mode. Currently returns 0 for system emulation.

```C
uint64_t qemu_plugin_start_code(void)
```

--------------------------------

### Build and Run spdm-emu

Source: https://qemu-project.gitlab.io/qemu/specs/spdm

Steps to clone, build, and prepare the spdm-emu tool, including generating necessary certificates for SPDM authentication. This involves initializing git submodules, configuring CMake, compiling the project, and creating sample keys.

```bash
cd spdm-emu
git submodule init; git submodule update --recursive
mkdir build; cd build
cmake -DARCH=x64 -DTOOLCHAIN=GCC -DTARGET=Debug -DCRYPTO=openssl ..
make -j32
make copy_sample_key # Build certificates, required for SPDM authentication.

```

--------------------------------

### QEMU QMP Example: Simple JSON Request/Response

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-code-gen

Demonstrates a basic QMP example using the '.. qmp-example::' directive, showing a simple JSON command execution and its expected return.

```rst
# .. qmp-example::
#
#     -> { "execute": "query-name" }
#     <- { "return": { "name": "Fred" } }
```

--------------------------------

### Guest1 AP Matrix Output Example

Source: https://qemu-project.gitlab.io/qemu/system/s390x/vfio-ap

This shows an example of the output when displaying the AP matrix configuration for Guest1, listing the assigned APQNs.

```bash
05.0004
05.00ab
06.0004
06.00ab
```

--------------------------------

### QEMU Documentation: Literal Block Example

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-code-gen

Demonstrates the use of the '::' literal block in QEMU documentation to pre-format text, often used for code examples or structured text.

```rst
# ::
#
#   Text of the example, may span
#   multiple lines
```

--------------------------------

### Subchannel Passthrough via vfio-ccw Example Configuration

Source: https://qemu-project.gitlab.io/qemu/system/targets

This example demonstrates the configuration for subchannel passthrough using vfio-ccw on s390x. It outlines the necessary steps for both the host device configuration and the QEMU setup.

```bash
# Example Configuration for vfio-ccw subchannel passthrough

# Step 1: Configure the host device (conceptual example)
# This might involve identifying the subchannel ID and binding it to vfio-ccw.
# Example: 
# subchannel_id="0.0.0001"
# echo $subchannel_id > /sys/bus/css/devices/0.0.0001/driver/bind

# Step 2: Configure QEMU
# qemu-system-s390x \
#   ... \
#   -device vfio-ccw,devno=<SUBCHANNEL_ID> \
#   ...

```

--------------------------------

### QEMU Example Descriptor Buffer Structure

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

A visual representation of an example descriptor buffer in QEMU, showing the alignment and arrangement of two TLVs with their headers and values.

```Text
                <------- 8 bytes ------->

8-byte  +––––+  +–––––––––––+–––––+–––––+                     +–+
align           |   type    | len | pad |    TLV#1 hdr          |
                +–––––––––––+–––––+–––––+    (len=22)           |
                |                       |                       |
                |  value                |    TVL#1 value        |
                |                       |    (padded to 8-byte  |
                |                 +–––––+     alignment)        |
                |                 |/////|                       |
 8-byte +––––+  +–––––––––––+–––––––––––+                       |
 align          |   type    | len | pad |    TLV#2 hdr    DESC_BUF_SIZE
                +–––––+–––––+–––––+–––––+    (len=2)            |
                |value|/////////////////|    TLV#2 value        |

```

--------------------------------

### QEMU Documentation: Basic Formatting and Lists

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-code-gen

An example combining basic text formatting like bold and emphasis with numbered lists and a code block, showcasing common documentation patterns.

```rst
# Some text foo with **bold** and *emphasis*
#
# 1. with a list
# 2. like that
#
# And some code:
#
# ::
#
#   $ echo foo
#   -> do this
#   <- get that
```

--------------------------------

### QEMU Diskless VM Snapshotting

Source: https://qemu-project.gitlab.io/qemu/system/replay

Shows the command line for starting a diskless virtual machine with an 'orphan' qcow2 image used for storing VM snapshots. This ensures snapshots are saved in a dedicated image.

```bash
qemu-system-x86_64 \
  -icount shift=auto,rr=replay,rrfile=record.bin,rrsnapshot=init \
  -net none -drive file=empty.qcow2,if=none,id=rr
```

--------------------------------

### Ansible Inventory File for QEMU CI Machine Setup

Source: https://qemu-project.gitlab.io/qemu/devel/testing/ci

Example of an Ansible inventory file used to define hosts for QEMU CI machine setup. It specifies fully qualified domain names or hostnames.

```INI
fully.qualified.domain
other.machine.hostname
```

--------------------------------

### QEMU Coding Style Guide

Source: https://qemu-project.gitlab.io/qemu/devel/index-process

Details the formatting, style, and language usage conventions specific to QEMU development. It also covers QEMU-specific idioms to ensure code consistency and maintainability.

```Text
Formatting and style
Language usage
QEMU Specific Idioms
```

--------------------------------

### Example: Aggregating PTY and VC with Hub

Source: https://qemu-project.gitlab.io/qemu/system/invocation

An example demonstrating the use of a hub device to aggregate a pseudo-TTY (pty0) and a virtual console (vc0) for a virtio hvc console. This setup allows bidirectional communication and shared rendering.

```bash
-chardev pty,path=/tmp/pty,id=pty0 \
-chardev vc,id=vc0 \
-chardev hub,id=hub0,chardevs.0=pty0,chardevs.1=vc0 \
-device virtconsole,chardev=hub0 \
-vnc 0.0.0.0:0
```

--------------------------------

### QEMU Preconfiguration with --preconfig

Source: https://qemu-project.gitlab.io/qemu/system/managed-startup

This snippet illustrates the use of the experimental --preconfig command-line option in QEMU. It allows pausing QEMU before initial VM creation, enabling configuration via QMP commands that do not depend on an initialized machine.

```bash
qemu-system-x86_64 --preconfig
```

--------------------------------

### QUORUM_FAILURE Event Example

Source: https://qemu-project.gitlab.io/qemu/interop/qemu-storage-daemon-qmp-ref

Example of a QUORUM_FAILURE event, emitted by the Quorum block driver when it fails to establish a quorum. It includes device/node reference, the starting sector number, and the count of sectors involved in the failed read operation.

```json
<- { "event": "QUORUM_FAILURE",
     "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
```

--------------------------------

### QEMU Get Stats Command Completion Status

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Details the descriptor buffer contents upon completion of the get stats command in QEMU, including flow duration and packet counts. It also lists possible status return codes.

```text
On completion of get stats command, the descriptor buffer is written back with the following TLVs:
field                   width   description
---------------------------------------------------
OF_DPA_STAT_DURATION    4       Flow duration
OF_DPA_STAT_RX_PKTS     8       Received packets
OF_DPA_STAT_TX_PKTS     8       Transmit packets

Possible status return codes in descriptor on completion are:
DESC_COMP_ERR   command                 reason
--------------------------------------------------------------------
0               all                     OK
```

--------------------------------

### QEMU Device Configuration Help

Source: https://qemu-project.gitlab.io/qemu/system/device-emulation

This snippet shows how to list all available devices QEMU is aware of and how to get specific help for a particular device using command-line options.

```bash
--device help
```

```bash
--device foo,help
```

--------------------------------

### Run QEMU with Multiple Plugins

Source: https://qemu-project.gitlab.io/qemu/about/emulation

Demonstrates how to run a QEMU binary with multiple TCG plugins loaded. Each plugin can be specified with its own arguments to modify its behavior.

```bash
$QEMU $OTHER_QEMU_ARGS \
    -plugin contrib/plugins/libhowvec.so,inline=on,count=hint \
    -plugin contrib/plugins/libhotblocks.so
```

--------------------------------

### QUORUM_REPORT_BAD Event Example

Source: https://qemu-project.gitlab.io/qemu/interop/qemu-storage-daemon-qmp-ref

Example of a QUORUM_REPORT_BAD event, used to report corruption in a Quorum file. It specifies the operation type, the node name, the starting sector number, and the sector count of the failed operation. An optional error message may be included.

```json
<- { "event": "QUORUM_REPORT_BAD",
     "data": { "type": "write", "node-name": "mydevice", "sector-num": 12345, "sectors-count": 10, "error": "CRC mismatch" },
     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
```

--------------------------------

### QEMU DASD Boot: Initial IPL Steps

Source: https://qemu-project.gitlab.io/qemu/devel/s390-dasd-ipl

This outlines the initial steps for IPLing a guest OS from a DASD device in QEMU, involving placing a 'Read IPL' ccw and executing a channel program.

```Assembly
1. Place a “Read IPL” ccw into memory location `0x0` with chaining bit on.
2. Execute channel program at `0x0`.
3. LPSW `0x0`.
```

--------------------------------

### GDB Stdio Connection Example

Source: https://qemu-project.gitlab.io/qemu/system/invocation

Connects GDB via stdio, allowing QEMU to be started within GDB and communicate over a pipe.

```bash
(gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
```

--------------------------------

### Test QMP Command with Arguments (JSON)

Source: https://qemu-project.gitlab.io/qemu/devel/writing-monitor-commands

These JSON examples demonstrate how to call the 'hello-world' QMP command with and without arguments. The first call uses default arguments, while the second provides a custom 'message'.

```JSON
{ "execute": "hello-world" }
{
    "return": {
    }
}

{ "execute": "hello-world", "arguments": { "message": "We love QEMU" } }
{
    "return": {
    }
}
```

--------------------------------

### QEMU Group Table Get Stats Response TLVs

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Specifies the Type-Length-Value (TLV) fields returned in the descriptor buffer upon completion of a 'get stats' command for the QEMU group table. These include flow group ID, duration, reference count, and bucket count.

```C
field                   width   description
---------------------------------------------------
FLOW_GROUP_ID           2       Flow group ID
FLOW_STAT_DURATION      4       Flow duration
FLOW_STAT_REF_COUNT     4       Flow reference count
FLOW_STAT_BUCKET_COUNT  4       Flow bucket count
```

--------------------------------

### Create QEMU Machine with Options

Source: https://qemu-project.gitlab.io/qemu/devel/testing/qgraph

Similar to qos_node_create_machine, but allows for optional command-line arguments to be passed. This enables more flexible machine configuration.

```C
void qos_node_create_machine_args(const char *name, QOSCreateMachineFunc function, const char *opts)
```

--------------------------------

### Start RX System Emulator with BIOS

Source: https://qemu-project.gitlab.io/qemu/system/target-rx

This command starts the QEMU system emulator for the RX target using the `gdbsim-r5f562n8` machine type and loads a U-Boot BIOS image. Ensure you have downloaded the `u-boot.bin.gz` file.

```bash
qemu-system-rx -M gdbsim-r5f562n8 -bios <u-boot_image_file>
```

--------------------------------

### Start QEMU VM from Template with Read-Only Memory

Source: https://qemu-project.gitlab.io/qemu/system/vm-templating

This command starts a new QEMU VM based on an existing 'template' memory file. `readonly=on` ensures the template file is not modified by the new VM, and `rom=off` allows the VM's memory to be writable internally. Copy-on-write ensures changes are private.

```bash
qemu-system-x86_64 [...] -m 2g \
    -object memory-backend-file,id=pc.ram,mem-path=template,size=2g,readonly=on,rom=off,... \
    -machine q35,memory-backend=pc.ram
```

--------------------------------

### Basic Block Plugin Execution Example

Source: https://qemu-project.gitlab.io/qemu/about/emulation

An example of running the 'bb' (Basic Block) plugin with QEMU for AArch64 architecture. It measures basic block execution and reports the count and instruction count upon completion.

```bash
$ qemu-aarch64 -plugin tests/plugin/libbb.so \
    -d plugin ./tests/tcg/aarch64-linux-user/sha1
SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
bb's: 2277338, insns: 158483046
```

--------------------------------

### Get Switch ID

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Retrieves a unique identifier for the switch. This is a read-only 64-bit register at offset 0x0320, with its value being opaque to software.

```Assembly
SWITCH_ID: offset 0x0320, 64-bit, (R)

Value is opaque to switch software and no special encoding is implied.

```

--------------------------------

### QEMU Guest Agent Configuration File Example

Source: https://qemu-project.gitlab.io/qemu/interop/qemu-ga

This snippet provides an example of the qemu-ga.conf configuration file, demonstrating how to set various parameters for the QEMU Guest Agent daemon, such as daemonize, pidfile, verbosity, transport method, and paths.

```ini
# qemu-ga configuration sample
[general]
demonize = 0
pidfile = /var/run/qemu-ga.pid
verbose = 0
method = virtio-serial
path = /dev/virtio-ports/org.qemu.guest_agent.0
statedir = /var/run

```

--------------------------------

### Start QEMU for CCID Passthrough with Host Hardware

Source: https://qemu-project.gitlab.io/qemu/system/devices/ccid

Starts QEMU with a USB CCID device and a CCID passthrough device, connected to a server socket. This setup allows a client application to connect to the socket and forward smart card data from the host's hardware reader to the guest.

```shell
qemu -chardev socket,server=on,host=0.0.0.0,port=2001,id=ccid,wait=off \
     -usb -device usb-ccid -device ccid-card-passthru,chardev=ccid
```

--------------------------------

### QEMU: Booting the ast2700fc Machine

Source: https://qemu-project.gitlab.io/qemu/system/targets

This section provides instructions for booting the ast2700fc machine using QEMU. It covers the specific boot options and configurations for this board.

```Shell
# Example command to boot the ast2700fc machine
# qemu-system-arm -M ast2700fc -nographic
```

--------------------------------

### QMP Command Definition Example

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-code-gen

Demonstrates the structure for defining a QMP command, including 'allow-preconfig' to indicate availability before machine build.

```JSON
{ 'enum': 'QMPCapability',
  'data': [ 'oob' ] }
{ 'command': 'qmp_capabilities',
  'data': { '*enable': [ 'QMPCapability' ] },
  'allow-preconfig': true }
```

--------------------------------

### QEMU Execution Log Plugin Basic Usage

Source: https://qemu-project.gitlab.io/qemu/about/emulation

Shows the basic command to run the QEMU execlog plugin, which traces executed instructions and memory access. It requires the plugin library and '-d plugin' option.

```bash
$ qemu-system-arm $(QEMU_ARGS) \
  -plugin ./contrib/plugins/libexeclog.so -d plugin

```

--------------------------------

### Get Physical Port Count

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Retrieves the number of physical ports available on the switch. This is a read-only 32-bit register located at offset 0x0304.

```Assembly
PORT_PHYS_COUNT, offset 0x0304, 32-bit, (R)
```

--------------------------------

### Get PORT_SETTINGS Descriptor

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Defines the descriptor structure for retrieving physical port settings. It requires a CMD_GET command and the physical port number (PPORT).

```Assembly
Get PORT_SETTINGS descriptor:

        field           width   description
        ----------------------------------------------
        PORT_SETTINGS   2       CMD_GET
        PPORT           4       Physical port #

```

--------------------------------

### QEMU blockdev-add and blockdev-snapshot Command Example

Source: https://qemu-project.gitlab.io/qemu/interop/qemu-storage-daemon-qmp-ref

This example shows the process of adding a block device with a specified driver and filename, and then taking a snapshot of another block device, linking it to the newly added node. It utilizes 'blockdev-add' and 'blockdev-snapshot' commands.

```json
-> { "execute": "blockdev-add",
     "arguments": { "driver": "qcow2",
                    "node-name": "node1534",
                    "file": { "driver": "file",
                              "filename": "hd1.qcow2" },
                    "backing": null } }

<- { "return": {} }

-> { "execute": "blockdev-snapshot",
     "arguments": { "node": "ide-hd0",
                    "overlay": "node1534" } }
<- { "return": {} }
```

--------------------------------

### QEMU Documentation: Indentation Example

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-code-gen

Demonstrates correct indentation for multi-line documentation comments, ensuring proper alignment of subsequent lines.

```rst
# @none: None (no memory side cache in this proximity domain,
#     or cache associativity unknown)
#     (since 5.0)
```

--------------------------------

### Define QOSGraphObject Structure

Source: https://qemu-project.gitlab.io/qemu/devel/testing/qgraph

Defines the core structure for drivers, tests, and machines in the framework. It contains function pointers for getting devices/drivers, starting hardware, and destruction/freeing.

```C
struct QOSGraphObject {
    QOSGetDriver get_driver;
    QOSGetDevice get_device;
    QOSStartFunct start_hw;
    QOSDestructorFunc destructor;
    GDestroyNotify free;
};
```

--------------------------------

### Get Virtual Address of Translation Block Start

Source: https://qemu-project.gitlab.io/qemu/devel/tcg-plugins

Returns the virtual address at which a translation block (TB) begins. This function is useful for understanding the memory location of code blocks being processed.

```C
uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb)
```

--------------------------------

### QEMU System Emulator Command Line Structure

Source: https://qemu-project.gitlab.io/qemu/system/introduction

Illustrates the general structure of a QEMU system emulator command line, showing the order of common option categories.

```bash
$ qemu-system-x86_64 [machine opts] \
                [cpu opts] \
                [accelerator opts] \
                [device opts] \
                [backend opts] \
                [interface opts] \
                [boot opts]
```

--------------------------------

### Open MSYS2 MINGW64 Shell on Windows

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Opens a specific MSYS2 shell environment for Windows development. This command is used to enter the MINGW64 environment, recommended for x86_64 builds.

```shell
c:/msys64/msys2_shell.cmd -defterm -here -no-start -mingw64
# Replace -ucrt64 by -clangarm64 or -ucrt64 for other environments.
```

--------------------------------

### Get Memory Access Size Shift

Source: https://qemu-project.gitlab.io/qemu/devel/tcg-plugins

Retrieves the size of a memory access operation, represented as a power of 2. For example, 0 indicates a byte access, 1 indicates a 16-bit access, and so on.

```C
unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info)
```

--------------------------------

### Load Xen Hypervisor with Guest Loader

Source: https://qemu-project.gitlab.io/qemu/system/guest-loader

This example demonstrates how to load the Xen hypervisor using QEMU's system emulation. It specifies the kernel, appends boot arguments for Dom0, and uses the guest-loader device to load kernel and initrd blobs into memory at specific addresses.

```bash
qemu-system-x86_64 -kernel ~/xen.git/xen/xen   -append "dom0_mem=1G,max:1G loglvl=all guest_loglvl=all"   -device guest-loader,addr=0x42000000,kernel=Image,bootargs="root=/dev/sda2 ro console=hvc0 earlyprintk=xen"   -device guest-loader,addr=0x47000000,initrd=rootfs.cpio
```

--------------------------------

### Launch QEMU with AF_XDP (Basic)

Source: https://qemu-project.gitlab.io/qemu/system/invocation

Launches a QEMU instance with an AF_XDP network backend connected to eth0, using a single queue and starting at queue 1. This is a basic setup for XDP acceleration.

```bash
qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 \
    -netdev af-xdp,id=n1,ifname=eth0,queues=1,start-queue=1
```

--------------------------------

### QEMU VirtIO Backend Implementation

Source: https://qemu-project.gitlab.io/qemu/devel/index-internals

Guides on writing VirtIO backends for QEMU, covering VirtIO transports, utilizing the QEMU Object Model (QOM), and implementing backend logic.

```c
/* Conceptual example of a VirtIO backend */
#include "hw/virtio/virtio.h"
#include "hw/virtio/virtio-creators.h"

struct VirtioMyBackend {
    VirtIODevice parent;
    // ... backend specific data ...
};

static void virtio_my_backend_realize(VirtIODevice *vdev, Error **errp) {
    VirtioMyBackend *vb = VIRTIO_MY_BACKEND(vdev);
    // Initialize backend features, queues, etc.
}

static void virtio_my_backend_class_init(ObjectClass *klass, void *data) {
    VirtIODeviceClass *vdc = VIRTIO_DEVICE_CLASS(klass);
    vdc->realize = virtio_my_backend_realize;
    // ... other VirtIODevice methods ...
}

static const TypeInfo virtio_my_backend_type = {
    .name = "virtio-my-backend",
    .parent = TYPE_VIRTIO_DEVICE,
    .instance_size = sizeof(VirtioMyBackend),
    .class_init = virtio_my_backend_class_init,
};

void virtio_my_backend_register(void) {
    type_register(&virtio_my_backend_type);
}
```

--------------------------------

### Connect multiple authz drivers with VNC/TLS/SASL

Source: https://qemu-project.gitlab.io/qemu/system/authz

A comprehensive example showing how to connect multiple authorization drivers (`authz-simple` for SASL and `authz-list-file` for TLS) to a VNC server. It also includes TLS credentials setup and verification.

```bash
echo "CN=laptop.qemu.org,O=QEMU Project,L=London,ST=London,C=GB" >> tls.acl
$QEMU --object authz-simple,id=authz0,identity=fred \
      --object authz-list-file,id=authz1,filename=tls.acl \
      --object tls-creds-x509,id=tls0,dir=/etc/qemu/tls,verify-peer=yes \
      --vnc 0.0.0.0:1,sasl,sasl-authz=auth0,tls-creds=tls0,tls-authz=authz1
```

--------------------------------

### QEMU Flow Delete and Get Stats Commands

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Specifies the TLVs used for initiating flow deletion and retrieving statistics commands in QEMU. It includes the command type and a cookie for identification.

```text
TLVs for flow delete and get stats command are:
field                   width   description
---------------------------------------------------
OF_DPA_CMD              2       CMD_[DEL|GET_STATS]
OF_DPA_COOKIE           8       Cookie
```

--------------------------------

### Reference Any QAPI Entity

Source: https://qemu-project.gitlab.io/qemu/devel/qapi-domain

Example of referencing any QAPI entity (module, command, event, enum, object, etc.) using the `:qapi:any:` role. This creates a general link to the documentation for the specified QAPI entity.

```rst
:qapi:any:`block-job-set-speed`

```

--------------------------------

### Get Physical Port Link Status

Source: https://qemu-project.gitlab.io/qemu/specs/rocker

Retrieves the link status for all front-panel ports. This is a read-only 64-bit register at offset 0x0310, where bits 1-62 indicate link UP (1) or DOWN (0).

```Assembly
PORT_PHYS_LINK_STATUS, offset 0x0310, 64-bit, (R)
```

--------------------------------

### QEMU: Booting the ast2700-evb Machine

Source: https://qemu-project.gitlab.io/qemu/system/targets

This section provides instructions for booting the ast2700-evb machine using QEMU. It covers the specific boot options and configurations for this board.

```Shell
# Example command to boot the ast2700-evb machine
# qemu-system-arm -M ast2700-evb -nographic
```

--------------------------------

### Configure QEMU for Cross-Compilation on Windows aarch64

Source: https://qemu-project.gitlab.io/qemu/devel/build-environment

Configures QEMU for cross-compilation targeting x86_64 on Windows aarch64 hosts. This command manually sets the CPU architecture and forces cross-compilation to resolve detection errors.

```shell
./configure --cpu=x86_64 --cross-prefix=
```

--------------------------------

### QEMU Container Based Tests

Source: https://qemu-project.gitlab.io/qemu/devel/testing/index

This section provides an overview of container-based testing for QEMU, including prerequisites for Docker and Podman, quickstart guides, registry usage, image management, running tests, and debugging Docker test failures.

```Shell
# Example of running a containerized test (conceptual)
# docker run qemu-test-image make check
```

--------------------------------

### Boot from GlusterFS Disk Image (URI)

Source: https://qemu-project.gitlab.io/qemu/system/images

Demonstrates booting a QEMU virtual machine directly from a GlusterFS disk image using a URI. The URI specifies the GlusterFS protocol, host, port, volume, and path to the image, along with optional parameters for debugging and logging.

```bash
qemu-system-x86_64 -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
                             [?socket=...][,file.debug=9][,file.logfile=...]
```

```bash
qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
```

```bash
qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
```

```bash
qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
```

--------------------------------

### Run QEMU Storage Daemon

Source: https://qemu-project.gitlab.io/qemu/tools/qemu-storage-daemon

Starts the QEMU Storage Daemon with specified options. This daemon provides disk image functionality and is controlled via QMP commands.

```bash
qemu-storage-daemon [options]
```
Tokens:
Raw