KVM - User contributions [en]

USB

2010-03-01T14:38:50Z

KevinWolf:

= Feature functional description =
This feature is about providing virtual USB devices to guests. For passing
through real USB hardware from the host, see [[UsbPassthrough]].

qemu provides three different USB controllers that can be used:
* PIIX3 UHCI controller (called ''piix3-usb-uhci'', default on PC)
* PIIX4 UHCI controller (called ''piix4-usb-uhci'')
* Apple OHCI controller (called ''pci-ohci'')

It provides a bunch of virtual USB devices. To see all of the devices built
into your qemu binary, run ''qemu -device ?'' and look for entries with a
"bus USB" on them. The most interesting ones are probably:
* USB tablet (called ''usb-tablet''): Provides an absolute pointer device which often helps with getting a consistent mouse cursor position in VNC.
* USB disk (called ''usb-storage'')
* Keyboard (''usb-kbd'') and mouse (''usb-mouse'')

= Detailed =
== Building ==
When building qemu for x86_64-softmmu with default options, you
get all of the mentioned devices with the expection of OHCI. To build it, add
the following line to x86_64-softmmu/config-devices.mak before running make:

<pre>CONFIG_USB_OHCI = y</pre>

== Running ==
To be able to use USB at all, you need to start qemu with a USB controller. If
you use the legacy ''-usb'' and ''-usbdevice'' options, you will automatically
get a ''piix3-usb-uhci'' for PCs unless you specify something else. The new
method works like this:

<pre>qemu-system-x86_64 -device piix3-usb-uhci ...</pre>

Do the same for any USB devices that you want to be present from start. Some of
them need some more options, like in the following example for a USB disk:

<pre>qemu-system-x86_64 -device piix3-usb-uhci \
-drive id=my_usb_disk,file=usbdisk.img,if=none \
-device usb-storage,drive=my_usb_disk</pre>

== Hotplugging ==
Just like in real hardware, USB allows hotplugging. You can use the monitor
commands ''device_add'' and ''device_del'' to attach a new device or remove
a previously attached one. For device_add, use the same format as for -device.
Attaching a new USB disk would look like this:

<pre>(qemu) drive_add 0 id=my_usb_disk,if=none,file=usbdisk.img
OK
(qemu) device_add usb-storage,id=my_usb_disk,drive=my_usb_disk</pre>

For removing the disk you need the ID that you have assigned in the device_add
call:

<pre>(qemu) device_del my_usb_disk</pre>

= Test cases =
The following sections describe test cases to verify correct function of the
USB emulation in qemu. Each of the test cases should be run with multiple guest
OSes. Consider variation of the USB host controller, though piix3-usb-uhci is
the most important one for PCs.

== Basic usage ==
This sections contains test cases which only consider coldplugged USB devices.

=== Input devices ===
* Keyboard: Type a few lines to see if there is any unexpected behaviour like missing or additional characters, or if the keymap is wrong. This can be tested both in different OSes with a proper USB HID driver and in DOS or bootloaders like GRUB (testing the PS/2 keyboard emulation).
* Pointer devices (''usb-mouse'', ''usb-tablet'' and ''usb-wacom-tablet''): Can the mouse cursor be moved? Do all three buttons work? Does the mouse wheel work?

=== USB disks ===
* Attach a raw image as a USB disk to the VM (no filesystem needed on it). Write some data to it and get the md5sum in the guest. Compare it to the md5sum of the image on the host.

== Hotplugging devices ==
=== Basic hotplugging ===
* Attach a USB disk during runtime and check if it's accessible by the OS. You can run the same test as for coldplugged USB disks.
* Detach the USB disk and check if the OS correctly detects this.

=== Unusual numbers of input devices ===
* What happens if the keyboard is unplugged and you type some text? Expected result is that nothing happens. After re-attaching an usb-kbd, it should be possible again to enter text.
* Same test with unplugging and re-attaching the pointer device.
* What happens with multiple keyboards or pointer devices attached? Expected result is that inputs are passed to one of the attached device (e.g. no duplicate characters). After removing the first keyboard, inputs should be directed to the keyboard that was attached later (i.e. you should still be able to input text as long as at least one keyboard is attached).

=== Repeated hotplug/unplug ===
* Attach 15 USB devices to the VM. USB hubs should automatically be added (check with ''info qtree'' in the monitor)
* Attach a USB device and detach it. Repeat this for a large number of iterations (probably best to do using a shell script). Check if no devices are left in the end and if the OS's USB driver is still fine (check dmesg, for example)
* Attach 15 USB devices and detach them again. Repeat this. Are automatically created hubs reused or are new hubs created each time?

USB

2010-01-29T17:01:36Z

KevinWolf:

= Feature functional description =
This feature is about providing virtual USB devices to guests. For passing
through real USB hardware from the host, see [[UsbPassthrough]].

qemu provides three different USB controllers that can be used:
* PIIX3 UHCI controller (called ''piix3-usb-uhci'', default on PC)
* PIIX4 UHCI controller (called ''piix4-usb-uhci'')
* Apple OHCI controller (called ''pci-ohci'')

It provides a bunch of virtual USB devices. To see all of the devices built
into your qemu binary, run ''qemu -device ?'' and look for entries with a
"bus USB" on them. The most interesting ones are probably:
* USB tablet (called ''usb-tablet''): Provides an absolute pointer device which often helps with getting a consistent mouse cursor position in VNC.
* USB disk (called ''usb-storage'')
* Keyboard (''usb-kbd'') and mouse (''usb-mouse'')

= Detailed =
== Building ==
When building qemu for x86_64-softemu with default options, you
get all of the mentioned devices with the expection of OHCI. To build it, add
the following line to x86_64-softemu/config-devices.mak before running make:

<pre>CONFIG_USB_OHCI = y</pre>

== Running ==
To be able to use USB at all, you need to start qemu with a USB controller. If
you use the legacy ''-usb'' and ''-usbdevice'' options, you will automatically
get a ''piix3-usb-uhci'' for PCs unless you specify something else. The new
method works like this:

<pre>qemu-system-x86_64 -device piix3-usb-uhci ...</pre>

Do the same for any USB devices that you want to be present from start. Some of
them need some more options, like in the following example for a USB disk:

<pre>qemu-system-x86_64 -device piix3-usb-uhci \
-drive id=my_usb_disk,file=usbdisk.img,if=none \
-device usb-storage,drive=my_usb_disk</pre>

== Hotplugging ==
Just like in real hardware, USB allows hotplugging. You can use the monitor
commands ''device_add'' and ''device_del'' to attach a new device or remove
a previously attached one. For device_add, use the same format as for -device.
Attaching a new USB disk would look like this:

<pre>(qemu) drive_add 0 id=my_usb_disk,if=none,file=usbdisk.img
OK
(qemu) device_add usb-storage,id=my_usb_disk,drive=my_usb_disk</pre>

For removing the disk you need the ID that you have assigned in the device_add
call:

<pre>(qemu) device_del my_usb_disk</pre>

= Test cases =
The following sections describe test cases to verify correct function of the
USB emulation in qemu. Each of the test cases should be run with multiple guest
OSes. Consider variation of the USB host controller, though piix3-usb-uhci is
the most important one for PCs.

== Basic usage ==
This sections contains test cases which only consider coldplugged USB devices.

=== Input devices ===
* Keyboard: Type a few lines to see if there is any unexpected behaviour like missing or additional characters, or if the keymap is wrong. This can be tested both in different OSes with a proper USB HID driver and in DOS or bootloaders like GRUB (testing the PS/2 keyboard emulation).
* Pointer devices (''usb-mouse'', ''usb-tablet'' and ''usb-wacom-tablet''): Can the mouse cursor be moved? Do all three buttons work? Does the mouse wheel work?

=== USB disks ===
* Attach a raw image as a USB disk to the VM (no filesystem needed on it). Write some data to it and get the md5sum in the guest. Compare it to the md5sum of the image on the host.

== Hotplugging devices ==
=== Basic hotplugging ===
* Attach a USB disk during runtime and check if it's accessible by the OS. You can run the same test as for coldplugged USB disks.
* Detach the USB disk and check if the OS correctly detects this.

=== Unusual numbers of input devices ===
* What happens if the keyboard is unplugged and you type some text? Expected result is that nothing happens. After re-attaching an usb-kbd, it should be possible again to enter text.
* Same test with unplugging and re-attaching the pointer device.
* What happens with multiple keyboards or pointer devices attached? Expected result is that inputs are passed to one of the attached device (e.g. no duplicate characters). After removing the first keyboard, inputs should be directed to the keyboard that was attached later (i.e. you should still be able to input text as long as at least one keyboard is attached).

=== Repeated hotplug/unplug ===
* Attach 15 USB devices to the VM. USB hubs should automatically be added (check with ''info qtree'' in the monitor)
* Attach a USB device and detach it. Repeat this for a large number of iterations (probably best to do using a shell script). Check if no devices are left in the end and if the OS's USB driver is still fine (check dmesg, for example)
* Attach 15 USB devices and detach them again. Repeat this. Are automatically created hubs reused or are new hubs created each time?

KVM Features

2010-01-29T08:52:09Z

KevinWolf: typo

= KVM-Features =

This is a possibly incomplete list of KVM features, together with their status. Feel free to update any of them as you see fit.

As a guideline, there is a feature description template in [[FeatureDescription/Template|here]]

* [[MonitorProtocol|QMP]] - Qemu Monitor Protocol
* [[KSM|KSM]] - Kernel Samepage Merging
* [[KVMClock|Kvm Paravirtual Clock]] - A Paravirtual timesource for KVM
* [[CPUHotPlug|CPU Hotplug support]] - Adding cpus on the fly
* [[pcihotplug|PCI Hotplug support]] - Adding pci devices on the fly
* [[VMchannel_Requirements | vmchannel ]] - Communication channel between the host and guests
* [[migration]] - Migrating Virtual Machines
* [[vhost]] -
* [[scsi|SCSI disk emulation]] -
* [[virtio|Virtio Devices]] -
* [[CPU clustering]] -
* [[hpet]] -
* [[device assignment]] -
* [[pxe boot]] -
* [[iscsi boot]] -
* [[x2apic]] -
* [[floppy]] -
* [[cdrom]] -
* [[USB]] -
* [[UsbPassthrough|USB host device passthrough]] -
* [[sound]] -
* [[UserspaceIrqchip|Userspace Irqchip emulation]] -
* [[UserspacePit|Userspace Pit emulation]] -
* [[Balloon|Balloon memory driver]] -
* [[LargePages|Large pages support]] -
* [[StableABI|Stable Guest ABI]] -

Qcow2

2009-07-22T12:14:38Z

KevinWolf:

== Performance status ==
=== Growing images (IDE) ===
An image format like qcow2 has the largest overhead compared to raw images when it needs grow the image, i.e. allocate new clusters. One scenario where you constantly get this worst case is the installation of an OS to an empty qcow2 image. Therefore installations are a good test to see if we get reasonable performance in this case.

The following table shows the installation times for a minimal RHEL 5.3 VM with
old and new qcow2 drivers, and for comparison raw images. The installation was
done with all three different cache settings. The VMs used IDE disks.

{| style="width:auto"
! cache =
! width="100" | off
! width="100" | writethrough
! width="100" | writeback
|-
| Old qcow2 (0.10.5)
| align="right" | 16:52 min
| align="right" | 28:58 min
| align="right" | 6:02 min
|-
| New qcow2 (0.11.0-rc1)
| align="right" | 5:44 min
| align="right" | 9:18 min
| align="right" | 6:11 min
|-
| raw
| align="right" | 5:41 min
| align="right" | 7:24 min
| align="right" | 6:03 min
|-
|}

=== Growing images (virtio) ===

This is the same test as above, with IDE replaced by virtio.

{| style="width:auto"
! cache =
! width="100" | off
! width="100" | writeback
|-
| Old qcow2 (0.10.5)
| align="right" | 31:09 min
| align="right" | 8:00 min
|-
| New qcow2 (0.11.0-rc1)
| align="right" | 18:35 min
| align="right" | 8:41 min
|-
| raw
| align="right" | 8:48 min
| align="right" | 7:51 min
|-
|}

=== Using allocated images ===

The above numbers are important for installation and running a freshly
installed VM. After a certain time, accesses to the disk only touch already
allocated clusters of the disk image.

For the following bonnie++ test results, the disk image have been completely
allocated, then an ext2 file system has been created and bonnie++ was run on
it. The test was run with the following qemu command line:

<pre>$ qemu-system-x86_64 -drive file=systen.img,if=ide -drive file=scratch.qcow2,if=virtio,cache=off -m 768</pre>

In the guest:

<pre># dd if=/dev/zero of=/dev/vda bs=1M
# mke2fs /dev/vda
# mount /dev/vda /mnt
# bonnie++ -b -u root -d /mnt</pre>

In addition to the qcow2 and raw numbers, both for virtio and IDE, the test results contain a test with qcow2 and IDE in qemu-kvm 0.10.5, referred to as "qcow2 old IDE".

<pre>
Version 1.03e ------Sequential Output------ --Sequential Input- --Random-
-Per Chr- --Block-- -Rewrite- -Per Chr- --Block-- --Seeks--
Machine Size K/sec %CP K/sec %CP K/sec %CP K/sec %CP K/sec %CP /sec %CP
qcow2 IDE 1472M 38232 46 36762 3 16095 4 43605 64 32968 3 112.4 2
qcow2 virtio 1472M 37644 49 37606 3 20626 5 43612 64 46813 7 110.9 1
raw IDE 1472M 37432 44 36824 3 15037 4 43167 71 35088 3 113.2 2
raw virtio 1472M 28301 39 30347 5 19738 5 41751 65 43537 7 109.4 1
qcow2 old IDE 1472M 20777 26 21894 2 9257 2 36482 60 30461 2 67.4 0

------Sequential Create------ --------Random Create--------
-Create-- --Read--- -Delete-- -Create-- --Read--- -Delete--
files /sec %CP /sec %CP /sec %CP /sec %CP /sec %CP /sec %CP
qcow2 IDE 16 296 29 +++++ +++ 594 16 276 29 +++++ +++ 537 18
qcow2 virtio 16 303 22 +++++ +++ 609 14 323 24 +++++ +++ 589 20
raw IDE 16 288 28 +++++ +++ 550 15 272 27 +++++ +++ 525 18
raw virtio 16 344 47 +++++ +++ 656 57 324 47 +++++ +++ 604 60
qcow2 old IDE 16 83 22 +++++ +++ 121 14 84 22 +++++ +++ 280 15
</pre>