From 55ee0329c5cd73797a35ae3a66b38445e35b43a2 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Wed, 14 Aug 2013 17:40:24 +0100
Subject: [PATCH] guestfs-performance: Add a section on the performance of UML.

---
 examples/guestfs-performance.pod | 37 ++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/examples/guestfs-performance.pod b/examples/guestfs-performance.pod
index d61fcf2a8..05a00e67d 100644
--- a/examples/guestfs-performance.pod
+++ b/examples/guestfs-performance.pod
@@ -368,6 +368,43 @@ L<http://rwmj.wordpress.com/2013/02/25/multiple-libguestfs-appliances-in-paralle
      printf ("%d %.2f\n", $nr_threads, $end_t - $start_t);
  }
 
+=head1 USING USER-MODE LINUX
+
+Since libguestfs 1.24, it has been possible to use the User-Mode Linux
+(uml) backend instead of KVM
+(see L<guestfs(3)/USER-MODE LINUX BACKEND>).  This section makes some
+general remarks about this backend, but it is B<highly advisable> to
+measure your own workload under UML rather than trusting comments or
+intuition.
+
+=over 4
+
+=item *
+
+UML usually performs the same or slightly slower than KVM, on baremetal.
+
+=item *
+
+However UML often performs the same under virtualization as it does on
+baremetal, whereas KVM can run much slower under virtualization (since
+hardware virt acceleration is not available).
+
+=item *
+
+Upload and download is as much as 10 times slower on UML than KVM.
+Libguestfs sends this data over the UML emulated serial port, which is
+far less efficient than KVM's virtio-serial.
+
+=item *
+
+UML lacks some features (eg. qcow2 support), so it may not be
+applicable at all.
+
+=back
+
+For some actual figures, see:
+L<http://rwmj.wordpress.com/2013/08/14/performance-of-user-mode-linux-as-a-libguestfs-backend/#content>
+
 =head1 TROUBLESHOOTING POOR PERFORMANCE
 
 =head2 ENSURE HARDWARE VIRTUALIZATION IS AVAILABLE