| Message ID | 20191016101241.24405-14-slp@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Introduce the microvm machine type | expand |
Hi On Wed, Oct 16, 2019 at 12:19 PM Sergio Lopez <slp@redhat.com> wrote: > > Document the new microvm machine type. > > Signed-off-by: Sergio Lopez <slp@redhat.com> > Reviewed-by: Michael S. Tsirkin <mst@redhat.com> > --- > docs/microvm.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 98 insertions(+) > create mode 100644 docs/microvm.rst > > diff --git a/docs/microvm.rst b/docs/microvm.rst > new file mode 100644 > index 0000000000..0aab55576c > --- /dev/null > +++ b/docs/microvm.rst > @@ -0,0 +1,98 @@ > +==================== > +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) > + > + > +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,server \ server? doesn't make sense here :) > + -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 > -- > 2.21.0 > > seem to work with appropriate kernel otherwise, so Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Marc-André Lureau <marcandre.lureau@gmail.com> writes: > Hi > > On Wed, Oct 16, 2019 at 12:19 PM Sergio Lopez <slp@redhat.com> wrote: >> >> Document the new microvm machine type. >> >> Signed-off-by: Sergio Lopez <slp@redhat.com> >> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> >> --- >> docs/microvm.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 98 insertions(+) >> create mode 100644 docs/microvm.rst >> >> diff --git a/docs/microvm.rst b/docs/microvm.rst >> new file mode 100644 >> index 0000000000..0aab55576c >> --- /dev/null >> +++ b/docs/microvm.rst >> @@ -0,0 +1,98 @@ >> +==================== >> +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) >> + >> + >> +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,server \ > > server? doesn't make sense here :) Heh, good catch! Thanks, Sergio. >> + -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 >> -- >> 2.21.0 >> >> > > seem to work with appropriate kernel otherwise, so > Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Hi Sergio, On 10/16/19 12:12 PM, Sergio Lopez wrote: > +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) If we have VirtIO devices, why not use virtio-serial instead of the one on the ISA bus?
Philippe Mathieu-Daudé <philmd@redhat.com> writes: > Hi Sergio, > > On 10/16/19 12:12 PM, Sergio Lopez wrote: >> +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) > > If we have VirtIO devices, why not use virtio-serial instead of the > one on the ISA bus? The serial port on the ISA bus is simpler, and thus is supported for both SeaBIOS debugging and Linux's earlyprintk. This makes it *very* convenient for debugging boot issues. Also, as it's explained in the documentation, users that no longer need it can disable the device and just rely on virtio-console. Sergio.
On 10/17/19 12:45 PM, Sergio Lopez wrote: > > Philippe Mathieu-Daudé <philmd@redhat.com> writes: > >> Hi Sergio, >> >> On 10/16/19 12:12 PM, Sergio Lopez wrote: >>> +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) >> >> If we have VirtIO devices, why not use virtio-serial instead of the >> one on the ISA bus? > > The serial port on the ISA bus is simpler, and thus is supported for > both SeaBIOS debugging and Linux's earlyprintk. This makes it *very* > convenient for debugging boot issues. "... but it's also compatible with SeaBIOS" OK. Maybe we can add a comment such "These devices are the minimum required to run SeaBIOS" in the 'Supported devices' section. > > Also, as it's explained in the documentation, users that no longer need > it can disable the device and just rely on virtio-console. > > Sergio. >
On Wed, Oct 16, 2019 at 12:12:40PM +0200, Sergio Lopez wrote: > Document the new microvm machine type. > > Signed-off-by: Sergio Lopez <slp@redhat.com> > Reviewed-by: Michael S. Tsirkin <mst@redhat.com> > --- > docs/microvm.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 98 insertions(+) > create mode 100644 docs/microvm.rst > > diff --git a/docs/microvm.rst b/docs/microvm.rst > new file mode 100644 > index 0000000000..0aab55576c > --- /dev/null > +++ b/docs/microvm.rst > @@ -0,0 +1,98 @@ > +==================== > +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. I'm wondering about live migration support across QEMU versions. IIUC, this is not intended to be a versioned machined type, so live migration won't be supportable across QEMU versions. Given that its for short lived guests, this shouldn't be an issue, but it might be worth saying something explicit here about migration to avoid any risk of misunderstanding. > + > + > +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) > + > + > +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,server \ > + -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 > -- > 2.21.0 > > Regards, Daniel
Daniel P. Berrangé <berrange@redhat.com> writes: > On Wed, Oct 16, 2019 at 12:12:40PM +0200, Sergio Lopez wrote: >> Document the new microvm machine type. >> >> Signed-off-by: Sergio Lopez <slp@redhat.com> >> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> >> --- >> docs/microvm.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 98 insertions(+) >> create mode 100644 docs/microvm.rst >> >> diff --git a/docs/microvm.rst b/docs/microvm.rst >> new file mode 100644 >> index 0000000000..0aab55576c >> --- /dev/null >> +++ b/docs/microvm.rst >> @@ -0,0 +1,98 @@ >> +==================== >> +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. > > I'm wondering about live migration support across QEMU versions. > > IIUC, this is not intended to be a versioned machined type, so > live migration won't be supportable across QEMU versions. > > Given that its for short lived guests, this shouldn't be an > issue, but it might be worth saying something explicit here > about migration to avoid any risk of misunderstanding. It may be worth adding a Limitations section. Something like this: Limitations ----------- Currently, microvm does *not* support the following features: - PCI-only devices. - Hotplug of any kind. - Live migration across QEMU versions. Any other thing we should highlight there? Thanks, Sergio. >> + >> + >> +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) >> + >> + >> +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,server \ >> + -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 >> -- >> 2.21.0 >> >> > > Regards, > Daniel
Philippe Mathieu-Daudé <philmd@redhat.com> writes: > On 10/17/19 12:45 PM, Sergio Lopez wrote: >> >> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >> >>> Hi Sergio, >>> >>> On 10/16/19 12:12 PM, Sergio Lopez wrote: >>>> +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) >>> >>> If we have VirtIO devices, why not use virtio-serial instead of the >>> one on the ISA bus? >> >> The serial port on the ISA bus is simpler, and thus is supported for >> both SeaBIOS debugging and Linux's earlyprintk. This makes it *very* >> convenient for debugging boot issues. > > "... but it's also compatible with SeaBIOS" > > OK. Maybe we can add a comment such "These devices are the minimum > required to run SeaBIOS" in the 'Supported devices' section. Well, that's not exactly true. SeaBIOS works without a serial port, it's just you can't get it to send its debugging messages anywhere (which most people won't see anyway). Sergio. >> >> Also, as it's explained in the documentation, users that no longer need >> it can disable the device and just rely on virtio-console. >> >> Sergio. >>
diff --git a/docs/microvm.rst b/docs/microvm.rst new file mode 100644 index 0000000000..0aab55576c --- /dev/null +++ b/docs/microvm.rst @@ -0,0 +1,98 @@ +==================== +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) + + +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,server \ + -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