wemu-system-aarch64

The command line that builds a machine. It is qemu-system-aarch64's, option for option, with the differences listed here.

wemu-system-aarch64 takes the command line of qemu-system-aarch64. The same line works in a shell and in WEMU.launch(), which accepts it as one string or as an argv array.

wemu-system-aarch64 -M virt -m 1G -kernel vmlinuz-virt -initrd initramfs-virt \
  -append "console=ttyAMA0 root=/dev/vda rw" -drive file=rootfs.img,if=virtio -nographic

Syntax

wemu-system-aarch64 [options] [disk_image]

Options are QEMU's: -name value, with sub-options as key=value,key=value. A comma inside a value is written ,,. A bare key means key=on, and a leading bare word fills the option's main key, so -drive disk.img is -drive file=disk.img.
--option works the same as -option.
A lone argument that isn't an option is a disk image, as -drive file=ARG.
Sizes take k, M, G and T suffixes, in powers of 1024. A bare number is MiB for -m and bytes elsewhere.
Booleans accept on, yes, true, 1 and off, no, false, 0.
An option this machine has no use for, but QEMU users often pass (such as -nodefaults, -object or -global), is accepted with a warning: wemu-system-aarch64: warning: <option>: ignored (no effect on this machine).
An option it can't honour is refused in QEMU's wording, prefixed wemu-system-aarch64:, and the command exits with status 1.

Standard options

Option	Description
`-h`, `-help`	Prints a summary of the options and exits.
`-version`	Prints `WEMU emulator version 11.1.50 (warm64 0.1.0)` and exits.
`-M`, `-machine [type=]virt[,prop=value…]`	The board. `virt` is the only one (`virt-X.Y` versions are accepted). See Machine properties.
`-cpu MODEL[,feature=on\|off…]`	The CPU. See CPU models.
`-accel tcg`	The only accelerator: the emulated CPU.
`-m [size=]SIZE`	Guest RAM. Default `128M`. See Cores and memory for the limits.
`-smp [cpus=]N`	Number of cores, 1 to 8. Default 1. Without `cpus`, `maxcpus` is the count; without either, `sockets`, `cores` and `threads` are multiplied together.
`-name [guest=]NAME`	A name `query-name` and `info name` report.
`-uuid UUID`	A UUID in `8-4-4-4-12` hex form.

Machine properties

Given as -M virt,PROP=VALUE,… (or -machine):

Property	Values	Default	Description
`gic-version`	`2`, `3`, `max`, `host`	`3`	The interrupt controller. `max` and `host` mean 3.
`virtualization`	`on`, `off`	`on`	EL2. With it on, Linux boots at EL2 and runs with VHE.
`iommu`	`none`, `smmuv3`	`none`	An SMMUv3 in front of the devices.
`accel`	`tcg`	`tcg`	As `-accel`.

Properties that only matter on real firmware or other boards (acpi, its, highmem, secure, ras, usb and others) are accepted and ignored. So is mte: MTE comes with -cpu max, and mte=on only undoes an earlier -cpu …,mte=off. dumpdtb=FILE is refused when the machine starts (the device tree is handed to the guest, not written out); QMP's and the monitor's dumpdtb write it.

CPU models

cortex-a53, cortex-a55, cortex-a57, cortex-a72, cortex-a76 (the default), neoverse-n1 and max are listed by -cpu help, and any cortex-a*, neoverse-* or a64fx name is accepted. -cpu host is refused: The 'host' CPU type can only be used with KVM or HVF.

The guest always sees a Cortex-A76 (r4p1). A model name only decides which optional features are advertised.
Every model advertises the Armv8 base, Advanced SIMD, the crypto extension, LSE atomics and BTI.
max also advertises pointer authentication, MTE and SVE, which every other name hides.
pauth=off, bti=off, mte=off and sve=off hide a feature from max. sme=on|off is accepted too; SME is never advertised, and sme=off hides SVE as sve=off does.
sve128 and the other vector lengths, pauth-impdef, pauth-qarma3, lpa2, aarch64, pmu, kvm-* and x-* are accepted and ignored. Any other property is refused with Property '.NAME' not found.
SME and 32-bit (AArch32) user programs are implemented but never advertised.

Note feature=on can't reveal a feature a model hides. For pointer authentication, MTE or SVE, use -cpu max.

Boot

Option	Description
`-kernel FILE`	An arm64 Linux `Image`. EFI zboot and gzip-compressed kernels are unpacked.
`-initrd FILE`	An initial ramdisk (gzip is inflated). Used only with `-kernel`.
`-append CMDLINE`	The kernel command line. With `-bios`, it goes to the firmware loader.
`-bios FILE`	Firmware for QEMU's virt board: U-Boot.
`-pflash FILE`	Flash images: the first is the code, the second the variables. Writes to flash are not saved back to the file.
`-boot [order=]…[,menu=on\|off]`	Accepted; has no effect. `menu` must still be a boolean.
`-dtb FILE`	Refused: the machine builds its own device tree from the devices on the command line.

One of -kernel, -bios or -pflash is required, in that order of precedence. With none of them the command fails with nothing to boot: this machine has no ROM of its own (-kernel, -bios or -pflash).

Block devices

-drive

-drive file=IMAGE[,if=virtio|none|pflash][,format=raw][,readonly=on][,snapshot=on][,discard=unmap][,media=cdrom][,id=ID]

Sub-option	Default	Description
`file`		The image. Required: an empty drive can't be made (create a sparse one with `wemu-img create -f raw`).
`if`	`virtio`	`virtio` attaches a virtio disk. `none` makes a drive for a `-device` to bind. `pflash` is flash, as `-pflash`.
`format` (or `driver`)	`raw`	The image format. The Node host opens raw images only; convert others with `wemu-img convert -O raw`.
`readonly`	`off`	Read-only.
`snapshot`	`off`	Keep the guest's writes in memory and discard them at exit.
`discard`	`ignore`	`unmap` passes the guest's discards to the host.
`media`	`disk`	`cdrom` makes the drive read-only.
`id`, `index`, `unit`		As in QEMU.

QEMU's tuning keys are accepted and ignored, each with a warning: cache, aio, detect-zeroes, werror, rerror, copy-on-read, bps, iops, throttling.bps-total, serial, cyls, heads, secs, trans, addr, bus, boot, node-name, auto-read-only, force-share and locking. read-only is the same as readonly. Any other key is refused with Invalid parameter 'KEY'.

if=ide, if=scsi, if=sd, if=floppy and if=mtd are refused with machine type does not support if=X,bus=0,unit=0; any other if with unsupported bus type 'X'. discard takes ignore or off, and unmap or on.

-hda, -hdb, -hdc and -hdd are virtio drives 0 to 3, and -cdrom FILE a read-only virtio drive. -snapshot makes every drive snapshot=on. -sd, -fda, -fdb and -mtdblock are refused: the board has no SD, floppy or MTD bus.

The Node command line opens images in place: the guest's writes reach the file as they happen. See Disks and images.

-blockdev

A file node and a format node over it, bound by a -device:

-blockdev driver=file,node-name=f0,filename=disk.img \
-blockdev driver=raw,node-name=d0,file=f0 \
-device virtio-blk-pci,drive=d0

`driver`	Node	Takes
`file`, `host_device`	A file	`filename` (required), `read-only`
`raw`	The format over a file node	`file=NODE`, or `file.filename=IMAGE` for both nodes in one
`qcow2`, `vmdk`, `vdi`, `vpc`, `vhdx`, `qed`	Accepted here, then refused when the image is opened: only raw images are opened. Convert with `wemu-img convert -O raw`.	as `raw`

Every node needs a node-name. Only read-only and discard carry over to the drive. Any other driver is refused with Unknown driver 'X'.

Devices

-device DRIVER[,prop=value…] accepts these drivers. -device help lists them.

Kind	Drivers	Properties
Disk	`virtio-blk-pci`, `virtio-blk-device`, `virtio-blk`	`drive` (required)
Network	`virtio-net-pci`, `virtio-net-device`, `virtio-net`	`netdev` (required), `mac`
Display	`virtio-gpu-pci`, `virtio-gpu-device`, `virtio-gpu`, `virtio-vga`	`xres`, `yres` (default 1280×800)
3D display	`virtio-gpu-gl-pci`, `virtio-gpu-gl-device`, `virtio-gpu-gl`, `virtio-vga-gl`	as above
Framebuffer	`ramfb`	1024×768; used when there's no GPU
Input	`virtio-keyboard-`, `virtio-tablet-`, `virtio-mouse-*`	Any one adds both a keyboard and a tablet.
USB controller	`wemu-xhci` (also `qemu-xhci`, `nec-usb-xhci`), or `-usb`
USB devices	`usb-kbd`, `usb-tablet`, `usb-mouse` (as a tablet), `usb-storage`	`usb-storage` needs `drive`; its writes aren't saved.
Sound	`virtio-sound-pci`, `virtio-sound-device`, `virtio-snd-pci`, `intel-hda` (with `hda-duplex`, `hda-output` or `hda-micro`)	`audiodev`. `intel-hda` becomes a virtio sound card.
Shared folder	`virtio-9p-pci`, `virtio-9p-device`	`fsdev`, `mount_tag`
Shared folder	`vhost-user-fs-pci`, `vhost-user-fs-device`	`tag`; no chardev is needed
IOMMU	`virtio-iommu-pci`, `virtio-iommu-device`	Becomes an SMMUv3.

Accepted with no effect: virtio-rng-*, virtio-balloon-*, virtio-serial-*, virtconsole, virtserialport, pcie-root-port, ioh3420, pcie-pci-bridge, pci-bridge, usb-hub, usb-ehci, pci-ohci.

Note PCI or MMIO is chosen for the whole machine. If any device name ends in -pci (or starts with virtio-vga), every virtio disk, network card and shared folder sits behind the PCIe host bridge; otherwise they're virtio-mmio.

Non-virtio network cards (e1000, rtl8139…), IDE, SCSI and NVMe disks, VGA adapters and passthrough devices are refused.

Display

Option	Description
`-display none`	No display.
`-display TYPE[,gl=on\|off]`	`gtk`, `sdl`, `cocoa`, `default` and the other QEMU types all mean the host's display (`WEMUHost.display`). `gl=off` keeps 3D rendering in software.
`-vga virtio`	Adds `virtio-gpu-pci`. `-vga none` adds nothing.
`-nographic`	No display. Serial 0 goes to the terminal, shared with the monitor.
`-vnc`, `-spice`	Refused: there's no VNC or SPICE server.
`-usb`	Adds the xHCI USB controller.

Note The command line in Node has no window, so -display there only matters to screendump. In a web page, the display is the canvas your host passes in.

Network

Option	Description
`-netdev user,id=ID[,net=][,host=][,dns=][,dhcpstart=]`	The built-in NAT. The guest is `10.0.2.15`, the gateway `10.0.2.2`, DNS `10.0.2.3`. `hostfwd` and `guestfwd` are refused: the guest reaches out, nothing reaches in.
`-netdev socket,id=ID,connect=ADDRESS`	An Ethernet hub over a WebSocket (`ws://…`, `wss://…`, or `:PORT` for `ws://localhost:PORT`), such as `examples/net/relay-hub.mjs` in the repository. It is not QEMU's socket protocol.
`-nic [user\|socket…][,id=][,model=][,mac=]`	A netdev and its network card in one option (default `virtio-net-pci`). `id` names the netdev (default `nicN`); the other keys go to the netdev.
`-net nic …`, `-net user …`	The legacy form.
`-nic none`, `-net none`	Accepted. There's no network card unless one is asked for, so they change nothing.

-netdev user also accepts QEMU's restrict, hostname, domainname, ipv4, ipv6, tftp, bootfile, smb and dnssearch, and ignores them with a warning. -netdev socket with listen, mcast, udp or fd is refused: only socket,connect= exists here.

Other backends (tap, bridge, …) are refused: network backend 'X' is not compiled into this binary. See Networking.

Shared folders and sound

Option	Description
`-virtfs local,mount_tag=TAG[,path=…]`	A 9p shared folder.
`-fsdev local,id=ID[,path=…]`	A 9p share for `-device virtio-9p-*,fsdev=ID`.
`-audiodev DRIVER,id=ID`	`none` drops the sound, `wav[,path=FILE]` writes it to a WAV file when the machine ends (default `wemu.wav`), any other driver plays through `WEMUHost.audio`.
`-audio DRIVER[,model=virtio\|hda][,path=FILE]`	A sound card and its backend in one option. `path` is the WAV file for `wav`. Without `model`, only the backend is made.

Warning A share's path= directory isn't mirrored into the guest. The share starts empty and is filled from JavaScript with vm.shares.get(tag).put(). See Shared folders.

Character devices, serial and monitor

Option	Description
`-serial stdio\|mon:stdio\|file:PATH\|chardev:ID\|vc\|null\|none`	A serial port; twice at most (`ttyAMA0`, `ttyAMA1`). Without `-nographic` the default is `vc`, the console your code reads with `vm.serial[0]`. `file:` appends. `pty`, `tcp:`, `unix:`, `udp:`, `pipe:`, `/dev/…`, `COM…`, `msmouse` and `braille` are refused: `could not connect serial device to character backend 'X'`.
`-chardev ringbuf,id=ID[,size=]`	A console kept in memory, read and written with QMP's `ringbuf-read` and `ringbuf-write`.
`-chardev stdio\|file\|socket\|null,id=ID`	Accepted, but not connected to anything.
`-chardev memory,id=ID[,size=]`	The same as `ringbuf`. `-chardev pty` is refused: `a pty cannot be made here`.
`-monitor stdio\|none\|chardev:ID`	The human monitor on the terminal. `chardev:ID` is accepted, as with `-mon`, but not served.
`-mon chardev=ID[,mode=readline\|control]`	A monitor on a chardev. Accepted, but only `stdio` monitors are served.
`-qmp unix:PATH,server[,nowait]`	A QMP server on a Unix socket.
`-qmp tcp:[HOST]:PORT,server[,nowait]`	A QMP server on TCP (default host `127.0.0.1`).
`-qmp stdio`	QMP on standard input and output.
`-qmp chardev:ID`	Accepted, then refused when the machine starts in Node: `only unix:, tcp: and stdio QMP endpoints exist here`.
`-qmp-pretty ENDPOINT`	As `-qmp`; replies are not pretty-printed.

With a -qmp server that waits (wait=on, the default without nowait; wait=off is nowait), the machine stays paused until the first client connects.

The terminal

With -nographic or -serial stdio, the terminal is in raw mode and Ctrl+C goes to the guest. Press Ctrl+A, then:

Key	Action
`x`	Quit.
`c`	Switch between the console and the monitor (`(wemu)` prompt).
`b`	Send a serial break (magic SysRq).
`h`	List these keys.
`Ctrl`+`A`	Send a literal `Ctrl`+`A`.

Run control

Option	Description
`-S`	Start paused; `cont` runs the machine.
`-no-reboot`	A guest reboot shuts the machine down instead.
`-no-shutdown`	A guest power-off pauses the machine instead of exiting.
`-action shutdown=poweroff\|pause`	What a guest power-off does. Default `poweroff`.
`-action reboot=reset\|shutdown`	What a guest reboot does. Default `reset`.
`-action panic=pause\|shutdown\|exit-failure\|none`	What a guest panic does. Default `pause`. `exit-failure` is the same as `shutdown`.
`-action watchdog=…`	Accepted and ignored: there's no watchdog.
`-rtc base=utc\|localtime\|DATE`	The real-time clock's start. `DATE` is `YYYY-MM-DDThh:mm:ss`, in UTC. `clock=host\|vm\|rt` is checked and has no effect; `driftfix` is ignored.
`-loadvm TAG`	Start from a snapshot. See Snapshots.
`-incoming file:PATH`	Start from a state saved with QMP's `migrate`.
`-incoming defer`	Wait for QMP's `migrate-incoming`.

Options accepted and ignored

These QEMU options are accepted so that existing command lines run, and have no effect here. Each prints wemu-system-aarch64: warning: <option>: ignored (no effect on this machine).

Kind	Options
Configuration and objects	`-object`, `-global`, `-set`, `-readconfig`, `-writeconfig`, `-compat`, `-plugin`, `-nodefaults`, `-no-user-config`, `-nodefconfig`, `-old-param`
Memory and NUMA	`-numa`, `-mem-path`, `-mem-prealloc`, `-overcommit`
Firmware tables	`-smbios`, `-acpitable`, `-fw_cfg`, `-option-rom`, `-prom-env`, `-no-acpi`, `-no-hpet`, `-no-fd-bootchk`
Logging, tracing and debugging	`-d`, `-D`, `-trace`, `-dfilter`, `-icount`, `-perfmap`, `-jitdump`, `-enable-sync-profile`, `-dump-vmstate`, `-qtest`, `-qtest-log`, `-debugcon`, `-semihosting`, `-semihosting-config`, `-only-migratable`
Process and host	`-pidfile`, `-runas`, `-sandbox`, `-seed`, `-msg`, `-L`, `-k`, `-add-fd`, `-run-with`, `-preconfig`, `-no-start`, `-realtime`, `-tb-size`
Display windows	`-sdl`, `-curses`, `-full-screen`, `-alt-grab`, `-ctrl-grab`, `-no-frame`, `-no-quit`, `-portrait`, `-rotate`, `-show-cursor`, `-g`
Devices QEMU no longer has, or this board doesn't	`-usbdevice`, `-parallel`, `-soundhw`, `-watchdog`, `-watchdog-action`, `-tpmdev`, `-balloon`, `-bt`, `-echr`
Clock	`-startdate`, `-localtime`, `-clock`, `-rtc-td-hack`, `-win2k-hack`
KVM and Xen tuning	`-no-kvm-pit`, `-no-kvm-irqchip`, `-kernel-kqemu`, `-xen-attach`, `-xen-domid-restrict`

-m maxmem= and -m slots=, -accel properties other than the accelerator's name, and machine properties such as acpi and highmem are ignored the same way.

Options refused

Options	Message
`-enable-kvm`, `-no-kvm`	`KVM is not available here (the CPU is emulated, as with -accel tcg)`
`-gdb`, `-gdbstub`, `-s`, `-singlestep`	`the gdb stub is not available here`
`-vnc`, `-spice`	`no VNC or SPICE server here; the display is the platform's (-display default: WEMUHost.display) or screendump`
`-daemonize`	`this machine is a library object, not a process to daemonize`
`-shim`, `-xen-domid`	`Xen is not available here`
`-iscsi`	`iSCSI is not available here (disks are raw images the host opens)`
`-dtb`	`this machine builds its own device tree from the devices attached; a -dtb of your own cannot describe them`
`-sd`, `-fda`, `-fdb`, `-mtdblock`	`machine type does not support that bus`
`-chroot`, and any option QEMU doesn't have	`invalid option`

Exit status

Status	When
0	`quit`, `Ctrl`+`A` `x`, the guest powered off, `-help`, `-version`.
1	The command line was refused, the machine couldn't start, or the guest panicked with `-action panic=shutdown`.

-M help, -cpu help, -device help and the other help listings print to standard error and exit with status 1.

Differences from QEMU

	WEMU	QEMU
Default CPU	`cortex-a76`	`cortex-a15`
Default GIC	version 3	version 2 (up to 8 CPUs)
`virtualization`	on	off
`-action panic`	`pause`	`shutdown`
Most CPUs	8	512
Disk formats	raw	raw, qcow2 and more
Accelerators	TCG only	TCG, KVM, HVF…

Also not available: KVM, the gdb stub, VNC and SPICE, hot-plug, block jobs and backing files, migration other than to a file, -dtb, -daemonize, pseudo-terminals, and Xen. QEMU's user-mode emulator (qemu-aarch64) has no WEMU counterpart.

Names differ in one way: where QEMU says qemu, WEMU says wemu (wemu-system-aarch64, wemu-img, the (wemu) prompt, -device wemu-xhci). The qemu spellings are still accepted.