QMP

QEMU's machine protocol, by its command and event names. Every command of QEMU 11.1's schema for aarch64 is known; this page lists what each does here.

QMP is QEMU's JSON protocol for controlling a machine. WEMU speaks it by QEMU's names: every command of QEMU 11.1's aarch64 schema is known, and what this machine has no counterpart for is answered as QEMU answers on a machine without it.

Using QMP

From JavaScript

vm.qmp() runs a command and resolves with its return value; errors reject with a QmpError. vm.qmpJson() takes and returns JSON text, and vm.on() delivers events. No negotiation is needed.

await vm.qmp("stop");
const { status } = await vm.qmp("query-status");   // "paused"
vm.on("RESUME", () => console.log("running again"));
await vm.qmp("cont");

Over a socket

Start wemu-system-aarch64 with a QMP server and connect any QMP client, such as QEMU's qmp-shell or socat:

wemu-system-aarch64 -m 1G -kernel vmlinuz-virt -initrd initramfs-virt -nographic \
  -qmp unix:/tmp/wemu.sock,server,nowait

socat - UNIX-CONNECT:/tmp/wemu.sock

{"QMP": {"version": {"wemu": {"major": 11, "minor": 1, "micro": 50}, "package": "warm64 0.1.0"}, "capabilities": ["oob"]}}
{"execute": "qmp_capabilities"}
{"return": {}}
{"execute": "query-status", "id": 1}
{"return": {"status": "running", "singlestep": false, "running": true}, "id": 1}

• The server sends a greeting; the client answers with qmp_capabilities before anything else. Until then every command is refused with CommandNotFound.
• Requests may span lines. Replies are one line each, echoing the request's id.
• Events go to every client that has negotiated.
• exec-oob is accepted and runs as an ordinary command.
• Several clients may connect at once, and -qmp may be given more than once. See -qmp for the endpoints.

Errors

An error reply has QEMU's shape: {"error": {"class": "...", "desc": "..."}}. The classes are GenericError, CommandNotFound, DeviceNotFound and DeviceNotActive.

Run state

Information

Memory and dumps

Block devices

Disks are fixed while the machine runs: block_resize, eject, change and the other removable-media commands are refused (Device 'ID' is not removable), and so are backing chains, block jobs, NBD and I/O throttling, in QEMU's words for a raw image.

The refused commands still look up the disk they name first, so a name that isn't a disk gets QMP's DeviceNotFound (Device 'ID' not found) rather than the refusal. A disk's name is its drive id (virtio0, drive0… when none is given). They read it from:

Snapshots and migration

Only migration to and from a file exists. See Snapshots.

Character devices

A console a script drives without a terminal:

wemu-system-aarch64 ... -chardev ringbuf,id=con,size=1M -serial chardev:con -display none

await vm.qmp("ringbuf-write", { device: "con", data: "uname -a\n" });
const text = await vm.qmp("ringbuf-read", { device: "con", size: 65536 });

Input

The pointer is an absolute tablet; rel moves are applied to it. Input needs a keyboard and tablet on the command line, such as -device virtio-keyboard-pci. See Display and input.

await vm.qmp("send-key", { keys: [{ type: "qcode", data: "ctrl" }, { type: "qcode", data: "alt" }, { type: "qcode", data: "f2" }] });
await vm.qmp("input-send-event", { events: [
  { type: "abs", data: { axis: "x", value: 16384 } },
  { type: "abs", data: { axis: "y", value: 16384 } },
  { type: "btn", data: { down: true, button: "left" } },
  { type: "btn", data: { down: false, button: "left" } },
] });

Display

Network

Devices and objects

Properties can't be changed while the machine runs: qom-set is refused.

Events

Every command

Every command of QEMU 11.1's aarch64 schema is known. Those not in the tables above fall into these groups.

More information commands

Empty results

These return [], the answer for a machine with none of the thing asked about: query-acpi-ospm-status, query-block-exports, query-block-jobs, query-command-line-options, query-cryptodev, query-fdsets, query-iothreads, query-memdev, query-memory-devices, query-pr-managers, query-rocker-ports, query-stats, query-stats-schemas, query-tpm, query-tpm-models, query-tpm-types, query-vcpu-dirty-limit, query-vnc-servers, query-yank, trace-event-get-state.

Accepted, with no effect

These return {}: announce-self, block-latency-histogram-set, block-set-write-threshold, blockdev-set-active, calc-dirty-rate, migrate_cancel, migrate-set-capabilities, migrate-set-parameters (both stored), nbd-server-stop, transaction (with no actions), watchdog-set-action, yank (with no instances).

Refused

See also

• The monitor
• WEMU
• wemu-system-aarch64