+++ /dev/null
-====================
-microvm Machine Type
-====================
-
-``microvm`` is a machine type inspired by ``Firecracker`` and
-constructed after its machine model.
-
-It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
-designed for short-lived guests. microvm also establishes a baseline
-for benchmarking and optimizing both QEMU and guest operating systems,
-since it is optimized for both boot time and footprint.
-
-
-Supported devices
------------------
-
-The microvm machine type supports the following devices:
-
-- ISA bus
-- i8259 PIC (optional)
-- i8254 PIT (optional)
-- MC146818 RTC (optional)
-- One ISA serial port (optional)
-- LAPIC
-- IOAPIC (with kernel-irqchip=split by default)
-- kvmclock (if using KVM)
-- fw_cfg
-- Up to eight virtio-mmio devices (configured by the user)
-
-
-Limitations
------------
-
-Currently, microvm does *not* support the following features:
-
-- PCI-only devices.
-- Hotplug of any kind.
-- Live migration across QEMU versions.
-
-
-Using the microvm machine type
-------------------------------
-
-Machine-specific options
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-It supports the following machine-specific options:
-
-- microvm.x-option-roms=bool (Set off to disable loading option ROMs)
-- microvm.pit=OnOffAuto (Enable i8254 PIT)
-- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
-- microvm.pic=OnOffAuto (Enable i8259 PIC)
-- microvm.rtc=OnOffAuto (Enable MC146818 RTC)
-- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
-
-
-Boot options
-~~~~~~~~~~~~
-
-By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
-times, but it's also compatible with ``SeaBIOS``.
-
-As no current FW is able to boot from a block device using
-``virtio-mmio`` as its transport, a microvm-based VM needs to be run
-using a host-side kernel and, optionally, an initrd image.
-
-
-Running a microvm-based VM
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, microvm aims for maximum compatibility, enabling both
-legacy and non-legacy devices. In this example, a VM is created
-without passing any additional machine-specific option, using the
-legacy ``ISA serial`` device as console::
-
- $ qemu-system-x86_64 -M microvm \
- -enable-kvm -cpu host -m 512m -smp 2 \
- -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
- -nodefaults -no-user-config -nographic \
- -serial stdio \
- -drive id=test,file=test.img,format=raw,if=none \
- -device virtio-blk-device,drive=test \
- -netdev tap,id=tap0,script=no,downscript=no \
- -device virtio-net-device,netdev=tap0
-
-While the example above works, you might be interested in reducing the
-footprint further by disabling some legacy devices. If you're using
-``KVM``, you can disable the ``RTC``, making the Guest rely on
-``kvmclock`` exclusively. Additionally, if your host's CPUs have the
-``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and
-the i8254 PIT (make sure you're also emulating a CPU with such feature
-in the guest).
-
-This is an example of a VM with all optional legacy features
-disabled::
-
- $ qemu-system-x86_64 \
- -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \
- -enable-kvm -cpu host -m 512m -smp 2 \
- -kernel vmlinux -append "console=hvc0 root=/dev/vda" \
- -nodefaults -no-user-config -nographic \
- -chardev stdio,id=virtiocon0 \
- -device virtio-serial-device \
- -device virtconsole,chardev=virtiocon0 \
- -drive id=test,file=test.img,format=raw,if=none \
- -device virtio-blk-device,drive=test \
- -netdev tap,id=tap0,script=no,downscript=no \
- -device virtio-net-device,netdev=tap0
-
-
-Triggering a guest-initiated shut down
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As the microvm machine type includes just a small set of system
-devices, some x86 mechanisms for rebooting or shutting down the
-system, like sending a key sequence to the keyboard or writing to an
-ACPI register, doesn't have any effect in the VM.
-
-The recommended way to trigger a guest-initiated shut down is by
-generating a ``triple-fault``, which will cause the VM to initiate a
-reboot. Additionally, if the ``-no-reboot`` argument is present in the
-command line, QEMU will detect this event and terminate its own
-execution gracefully.
-
-Linux does support this mechanism, but by default will only be used
-after other options have been tried and failed, causing the reboot to
-be delayed by a small number of seconds. It's possible to instruct it
-to try the triple-fault mechanism first, by adding ``reboot=t`` to the
-kernel's command line.
--- /dev/null
+'microvm' virtual platform (``microvm``)
+========================================
+
+``microvm`` is a machine type inspired by ``Firecracker`` and
+constructed after its machine model.
+
+It's a minimalist machine type without ``PCI`` nor ``ACPI`` support,
+designed for short-lived guests. microvm also establishes a baseline
+for benchmarking and optimizing both QEMU and guest operating systems,
+since it is optimized for both boot time and footprint.
+
+
+Supported devices
+-----------------
+
+The microvm machine type supports the following devices:
+
+- ISA bus
+- i8259 PIC (optional)
+- i8254 PIT (optional)
+- MC146818 RTC (optional)
+- One ISA serial port (optional)
+- LAPIC
+- IOAPIC (with kernel-irqchip=split by default)
+- kvmclock (if using KVM)
+- fw_cfg
+- Up to eight virtio-mmio devices (configured by the user)
+
+
+Limitations
+-----------
+
+Currently, microvm does *not* support the following features:
+
+- PCI-only devices.
+- Hotplug of any kind.
+- Live migration across QEMU versions.
+
+
+Using the microvm machine type
+------------------------------
+
+Machine-specific options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It supports the following machine-specific options:
+
+- microvm.x-option-roms=bool (Set off to disable loading option ROMs)
+- microvm.pit=OnOffAuto (Enable i8254 PIT)
+- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port)
+- microvm.pic=OnOffAuto (Enable i8259 PIC)
+- microvm.rtc=OnOffAuto (Enable MC146818 RTC)
+- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline)
+
+
+Boot options
+~~~~~~~~~~~~
+
+By default, microvm uses ``qboot`` as its BIOS, to obtain better boot
+times, but it's also compatible with ``SeaBIOS``.
+
+As no current FW is able to boot from a block device using
+``virtio-mmio`` as its transport, a microvm-based VM needs to be run
+using a host-side kernel and, optionally, an initrd image.
+
+
+Running a microvm-based VM
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, microvm aims for maximum compatibility, enabling both
+legacy and non-legacy devices. In this example, a VM is created
+without passing any additional machine-specific option, using the
+legacy ``ISA serial`` device as console::
+
+ $ qemu-system-x86_64 -M microvm \
+ -enable-kvm -cpu host -m 512m -smp 2 \
+ -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
+ -nodefaults -no-user-config -nographic \
+ -serial stdio \
+ -drive id=test,file=test.img,format=raw,if=none \
+ -device virtio-blk-device,drive=test \
+ -netdev tap,id=tap0,script=no,downscript=no \
+ -device virtio-net-device,netdev=tap0
+
+While the example above works, you might be interested in reducing the
+footprint further by disabling some legacy devices. If you're using
+``KVM``, you can disable the ``RTC``, making the Guest rely on
+``kvmclock`` exclusively. Additionally, if your host's CPUs have the
+``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and
+the i8254 PIT (make sure you're also emulating a CPU with such feature
+in the guest).
+
+This is an example of a VM with all optional legacy features
+disabled::
+
+ $ qemu-system-x86_64 \
+ -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \
+ -enable-kvm -cpu host -m 512m -smp 2 \
+ -kernel vmlinux -append "console=hvc0 root=/dev/vda" \
+ -nodefaults -no-user-config -nographic \
+ -chardev stdio,id=virtiocon0 \
+ -device virtio-serial-device \
+ -device virtconsole,chardev=virtiocon0 \
+ -drive id=test,file=test.img,format=raw,if=none \
+ -device virtio-blk-device,drive=test \
+ -netdev tap,id=tap0,script=no,downscript=no \
+ -device virtio-net-device,netdev=tap0
+
+
+Triggering a guest-initiated shut down
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As the microvm machine type includes just a small set of system
+devices, some x86 mechanisms for rebooting or shutting down the
+system, like sending a key sequence to the keyboard or writing to an
+ACPI register, doesn't have any effect in the VM.
+
+The recommended way to trigger a guest-initiated shut down is by
+generating a ``triple-fault``, which will cause the VM to initiate a
+reboot. Additionally, if the ``-no-reboot`` argument is present in the
+command line, QEMU will detect this event and terminate its own
+execution gracefully.
+
+Linux does support this mechanism, but by default will only be used
+after other options have been tried and failed, causing the reboot to
+be delayed by a small number of seconds. It's possible to instruct it
+to try the triple-fault mechanism first, by adding ``reboot=t`` to the
+kernel's command line.
projects / mirror_qemu.git / commitdiff