add_drive: Introduce 'cachemode' parameter to control drive caching.

This commit adds an optional 'cachemode' parameter to the 'add_drive'
API to control caching.  This corresponds approximately to the
'-drive ...,cache=' parameter in qemu, but the choices are much more
restrictive, just 'writeback' or 'unsafe', for reasons outlined below.

The caching modes supported by recent QEMU are:

  writeback:
   - Reports data writes completed when data is present in the host
     page cache.
     Only safe provided guest correctly issues flush operations.

  writethrough:
   - Reports data writes completed only when each write has been
     flushed to disk.  Performance is reported as not good.

  none:
   - Uses O_DIRECT (avoids all interaction with host cache), but does
     not ensure every write is flushed to disk.
     Only safe provided guest correctly issues flush operations.

  directsync:
   - Uses O_DIRECT (avoids all interaction with host cache), and
     ensures every write has been flushed to disk.

  unsafe:
   - No special handling.

Since the libguestfs appliance kernel always issues flush operations
(eg. for filesystem journalling and for sync) the following modes can
be ignored: 'directsync', 'writethrough'.

That leaves 'writeback', 'none' and 'unsafe'.  However 'none' is both
a constant source of pain (RHBZ#994517), is inefficient because it
doesn't use the host cache, and does not give us any safety guarantees
over and above 'writeback'.  Therefore we should ignore 'none'.

This leaves 'writeback' (safe) and 'unsafe' (fast, useful for scratch
disks), which is what we implement in this patch.

Note that the previous behaviour was to use 'none' if possible, else
to use 'writeback'.  The new behaviour is to use 'writeback' only
which is (in safety terms) equivalent to 'none', and also faster and
less painful (RHBZ#994517).

This patch also allows you to specify a cache mode for network drives
which also previously defaulted to 'writeback'.

There is a considerable performance benefit to using unsafe (for
scratch disks only, of course).  The C API tests only use scratch
disks (since they are just tests, the final state of the disk doesn't
matter), and this decreases total run time from 202 seconds to 163
seconds, about 25% faster.

generator/actions.ml

@@ -1286,7 +1286,7 @@ not all belong to a single logical operating system
 
   { defaults with
     name = "add_drive";
-    style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"; OString "label"; OString "protocol"; OStringList "server"; OString "username"; OString "secret"];
+    style = RErr, [String "filename"], [OBool "readonly"; OString "format"; OString "iface"; OString "name"; OString "label"; OString "protocol"; OStringList "server"; OString "username"; OString "secret"; OString "cachemode"];
     once_had_no_optargs = true;
     blocking = false;
     fish_alias = ["add"];
@@ -1476,6 +1476,34 @@ If not given, then a secret matching the given username will be looked up in the
 default keychain locations, or if no username is given, then no authentication
 will be used.
 
+=item C<cachemode>
+
+Choose whether or not libguestfs will obey sync operations (safe but slow)
+or not (unsafe but fast).  The possible values for this string are:
+
+=over 4
+
+=item C<cachemode = \"writeback\">
+
+This is the default.
+
+Write operations in the API do not return until a L<write(2)>
+call has completed in the host [but note this does not imply
+that anything gets written to disk].
+
+Sync operations in the API, including implicit syncs caused by
+filesystem journalling, will not return until an L<fdatasync(2)>
+call has completed in the host, indicating that data has been
+committed to disk.
+
+=item C<cachemode = \"unsafe\">
+
+In this mode, there are no guarantees.  Libguestfs may cache
+anything and ignore sync requests.  This is suitable only
+for scratch or temporary disks.
+
+=back
+
 =back" };
 
   { defaults with