* src/remote/remote_driver.c (remote_driver): Add new callbacks.
* src/remote/remote_protocol.x (remote_procedure): New RPCs.
(remote_domain_save_image_get_xml_desc_args)
(remote_domain_save_image_get_xml_desc_ret)
(remote_domain_save_image_define_xml_args): New structs.
* src/remote_protocol-structs: Update.

Modifying the xml on either save or restore only gets you so
far - you have to remember to 'virsh dumpxml dom' just prior
to the 'virsh save' in order to have an xml file worth modifying
that won't be rejected due to abi breaks.  To make this more
powerful, we need a way to grab the xml embedded within a state
file, and from there, it's not much harder to also support
modifying a state file in-place.

Also, virDomainGetXMLDesc didn't document its flags.

* include/libvirt/libvirt.h.in (virDomainSaveImageGetXMLDesc)
(virDomainSaveImageDefineXML): New prototypes.
* src/libvirt.c (virDomainSaveImageGetXMLDesc)
(virDomainSaveImageDefineXML): New API.
* src/libvirt_public.syms: Export them.
* src/driver.h (virDrvDomainSaveImageGetXMLDesc)
(virDrvDomainSaveImgeDefineXML): New driver callbacks.

When auto-dumping a domain on crash events, or autostarting a domain
with managed save state, let the user configure whether to imply
the bypass cache flag.

* src/qemu/qemu.conf (auto_dump_bypass_cache, auto_start_bypass_cache):
Document new variables.
* src/qemu/libvirtd_qemu.aug (vnc_entry): Let augeas parse them.
* src/qemu/qemu_conf.h (qemud_driver): Store new preferences.
* src/qemu/qemu_conf.c (qemudLoadDriverConfig): Parse them.
* src/qemu/qemu_driver.c (processWatchdogEvent, qemuAutostartDomain):
Honor them.

Wire together the previous patches to support file system cache
bypass during API save/restore requests in qemu.

* src/qemu/qemu_driver.c (qemuDomainSaveInternal, doCoreDump)
(qemudDomainObjStart, qemuDomainSaveImageOpen, qemuDomainObjRestore)
(qemuDomainObjStart): Add parameter.
(qemuDomainSaveFlags, qemuDomainManagedSave, qemudDomainCoreDump)
(processWatchdogEvent, qemudDomainStartWithFlags, qemuAutostartDomain)
(qemuDomainRestoreFlags): Update callers.

O_DIRECT has stringent requirements.  Rather than make lots of changes
at each site that wants to use O_DIRECT, it is easier to offload
the work through a helper process that mirrors the I/O between a
pipe and the actual direct fd, so that the other end of the pipe
no longer has to worry about constraints.

Plus, if the kernel ever gains better posix_fadvise support, then we
only have to touch a single file to let all callers benefit from a
more efficient way to avoid file system caching.

* src/util/virfile.h (virFileDirectFdFlag, virFileDirectFdNew)
(virFileDirectFdClose, virFileDirectFdFree): New prototypes.
* src/util/virdirect.c: Implement new wrapper object.
* src/libvirt_private.syms (virfile.h): Export new symbols.
* cfg.mk (useless_free_options): Add to list.
* po/POTFILES.in: Add new translations.

Required for a coming patch where iohelper will operate on O_DIRECT
fds.  There, the user-space memory must be aligned to file system
boundaries (at least 512, but using page-aligned works better, and
some file systems prefer 64k).  Made tougher by the fact that
VIR_ALLOC won't work on void *, but posix_memalign won't work on
char * and isn't available everywhere.

This patch makes some simplifying assumptions - namely, output
to an O_DIRECT fd will only be attempted on an empty seekable
file (hence, no need to worry about preserving existing data
on a partial block, and ftruncate will work to undo the effects
of having to round up the size of the last block written), and
input from an O_DIRECT fd will only be attempted on a complete
seekable file with the only possible short read at EOF.

* configure.ac (AC_CHECK_FUNCS_ONCE): Check for posix_memalign.
* src/util/iohelper.c (runIO): Use aligned memory, and handle
quirks of O_DIRECT on last write.

Rather than making the iohelper subject to a race in reopening
the file, it is nicer to pass an already-open fd by inheritance.

The old synopsis form must continue to work - if someone updates
their libvirt package and installs a new libvirt_iohelper but
without restarting the old libvirtd daemon, then the daemon can
still make calls using the old syntax but the new iohelper.

* src/util/iohelper.c (runIO): Split code for open...
(prepare): ...to new function.
(usage): Update synopsis.
(main): Allow alternate calling form.
* src/fdstream.c (virFDStreamOpenFileInternal): Use alternate form.

For all hypervisors that support save and restore, the new API
now performs the same functions as the old.

VBox is excluded from this list, because its existing domainsave
is broken (there is no corresponding domainrestore, and there
is no control over the filename used in the save).  A later
patch should change vbox to use its implementation for
managedsave, and teach start to use managedsave results.

* src/libxl/libxl_driver.c (libxlDomainSave): Move guts...
(libxlDomainSaveFlags): ...to new function.
(libxlDomainRestore): Move guts...
(libxlDomainRestoreFlags): ...to new function.
* src/test/test_driver.c (testDomainSave, testDomainSaveFlags)
(testDomainRestore, testDomainRestoreFlags): Likewise.
* src/xen/xen_driver.c (xenUnifiedDomainSave)
(xenUnifiedDomainSaveFlags, xenUnifiedDomainRestore)
(xenUnifiedDomainRestoreFlags): Likewise.
* src/qemu/qemu_driver.c (qemudDomainSave, qemudDomainRestore):
Rename and move guts.
(qemuDomainSave, qemuDomainSaveFlags, qemuDomainRestore)
(qemuDomainRestoreFlags): ...here.
(qemudDomainSaveFlag): Rename...
(qemuDomainSaveInternal): ...to this, and update callers.

VIR_ERR_INVALID_ARG implies that an argument cannot possibly
be correct, given the current state of the API.
VIR_ERR_CONFIG_UNSUPPORTED implies that a configuration is
wrong, but arguments aren't configuration.
VIR_ERR_NO_SUPPORT implies that a function is completely
unimplemented.

But in the case of a function that is partially implemented,
yet the full power of the API is not available for that
driver, none of the above messages make sense.  Hence a new
error message, implying that the argument is known to comply
with the current state of the API, and that while the driver
supports aspects of the function, it does not support that
particular use of the argument.

A good use case for this is a driver that supports
virDomainSaveFlags, but not the dxml argument of that API.

It might be feasible to also use this new error for all functions
that check flags, and which accept fewer flags than what is possible
in the public API.  But doing so would get complicated, since
neither libvirt.c nor the remote driver may do flag filtering,
and every other driver would have to do a two-part check, first
using virCheckFlags on all public flags (which gives
VIR_ERR_INVALID_ARG for an impossible flag), followed by a
particular mask check for VIR_ERR_ARGUMENT_UNSUPPORTED (for a
possible public flag but unsupported by this driver).

* include/libvirt/virterror.h (VIR_ERR_ARGUMENT_UNSUPPORTED): New
error.
* src/util/virterror.c (virErrorMsg): Give it a message.
Suggested by Daniel P. Berrange.

Build failure on xenapi_driver from compiler warnings (flags was unused).

Build failure on xen (incorrect number of arguments).  And in fixing
that, I obeyed the comments of struct xenUnifiedDriver that state
that we want to minimize the number of callback functions in that
struct, not add to it.

* src/xen/xen_driver.c (xenUnifiedDomainDestroyFlags): Use correct
arguments.
(xenUnifiedDomainDestroy): Simplify.
* src/xen/xen_driver.h (xenUnifiedDriver): Remove unused callback.
* src/xen/xen_hypervisor.c (xenHypervisorDestroyDomain): Likewise.
* src/xen/xend_internal.c (xenDaemonDomainDestroy): Likewise.
* src/xen/xend_internal.h (xenDaemonDomainDestroyFlags): Likewise.
* src/xen/xm_internal.c (xenXMDriver): Likewise.
* src/xen/xs_internal.c (xenStoreDriver): Likewise.
* src/xen/xen_inotify.c (xenInotifyDriver): Likewise.
* src/xenapi/xenapi_driver.c (xenapiDomainDestroyFlags): Reject
unknown flags.

during conflict resolving

The network driver needs to assign physical devices for use by modes
that use macvtap, keeping track of which physical devices are in use
(and how many instances, when the devices can be shared). Three calls
are added:

networkAllocateActualDevice - finds a physical device for use by the
domain, and sets up the virDomainActualNetDef accordingly.

networkNotifyActualDevice - assumes that the domain was already
running, but libvirtd was restarted, and needs to be notified by each
already-running domain about what interfaces they are using.

networkReleaseActualDevice - decrements the usage count of the
allocated physical device, and frees the virDomainActualNetDef to
avoid later accidentally using the device.

bridge_driver.[hc] - the new APIs. When WITH_NETWORK is false, these
functions are all #defined to be "0" in the .h file (effectively
becoming a NOP) to prevent link errors.

qemu_(command|driver|hotplug|process).c - add calls to the above APIs
    in the appropriate places.

tests/Makefile.am - we need to include libvirt_driver_network.la
    whenever libvirt_driver_qemu.la is linked, to avoid unreferenced
    symbols (in functions that are never called by the test
    programs...)

This is the one function outside of domain_conf.c that plays around
with (even modifying) the internals of the virDomainNetDef, and thus
can't be fixed up simply by replacing direct accesses to the fields of
the struct with the GetActual*() access functions.

In this case, we need to check if the defined type is "network", and
if it is *then* check the actual type; if the actual type is "bridge",
then we can at least put the bridgename in a place where it can be
used; otherwise (if type isn't "bridge"), we behave exactly as we used
to - just null out *everything*.

The qemu driver accesses fields in the virDomainNetDef directly, but
with the advent of the virDomainActualNetDef, some pieces of
information may be found in a different place (the ActualNetDef) if
the network connection is of type='network' and that network is of
forward type='bridge|private|vepa|passthrough'. The previous patch
added functions to mask this difference from callers - they hide the
decision making process and just pick the value from the proper place.

This patch uses those functions in the qemu driver as a first step in
making qemu work with the new network types. At this point, the
virDomainActualNetDef is guaranteed always NULL, so the GetActualX()
function will return exactly what the def->X that's being replaced
would have returned (ie bisecting is not compromised).

There is one place (in qemu_driver.c) where the internal details of
the NetDef are directly manipulated by the code, so the GetActual
functions cannot be used there without extra additional code; that
file will be treated in a separate patch.

Previously all networks were composed of bridge devices created and
managed by libvirt, and the same operations needed to be done for all
of them when they were started and stopped (create and start the
bridge device, configure its MAC address and IP address, add iptables
rules). The new network types are (for now at least) managed outside
of libvirt, and the network object is used only to contain information
about the network, which is then used as each individual guest
connects itself.

This means that when starting/stopping one of these new networks, we
really want to do nothing, aside from marking the network as
active/inactive.

This has been setup as toplevel Start/Shutdown functions that do the
small bit of common stuff, then have a switch statement to execute
network type-specific start/shutdown code, then do a bit more common
code. The type-specific functions called for the new host bridge and
macvtap based types are currently empty.

In the future these functions may actually do something, and we will
surely add more functions that are similarly patterned. Once
everything has settled, we can make a table of "sub-driver" function
pointers for each network type, and store a pointer to that table in
the network object, then we can replace the switch statements with
calls to functions in the table.

The final step in this will be to add a new table (and corresponding
new functions) for new network types as they are added.

The network XML is updated in the following ways:

1) The <forward> element can now contain a list of forward interfaces:

     <forward .... >
       <interface dev='eth10'/>
       <interface dev='eth11'/>
       <interface dev='eth12'/>
       <interface dev='eth13'/>
     </forward>

   The first of these takes the place of the dev attribute that is
   normally in <forward> - when defining a network you can specify
   either one, and on output both will be present. If you specify
   both on input, they must match.

2) In addition to forward modes of 'nat' and 'route', these new modes
   are supported:

     private, passthrough, vepa - when this network is referenced by a
     domain's interface, it will have the same effect as if the
     interface had been defined as type='direct', e.g.:

        <interface type='direct'>
          <source mode='${mode}' dev='${dev}>
          ...
        </interface>

     where ${mode} is one of the three new modes, and ${dev} is an interface
     selected from the list given in <forward>.

     bridge - if a <forward> dev (or multiple devs) is defined, and
     forward mode is 'bridge' this is just like the modes 'private',
     'passthrough', and 'vepa' above. If there is no forward dev
     specified but a bridge name is given (e.g. "<bridge
     name='br0'/>"), then guest interfaces using this network will use
     libvirt's "host bridge" mode, equivalent to this:

       <interface type='bridge'>
          <source bridge='${bridge-name}'/>
          ...
       </interface>

3) A network can have multiple <portgroup> elements, which may be
   selected by the guest interface definition (by adding
   "portgroup='${name}'" in the <source> element along with the
   network name). Currently a portgroup can only contain a
   virtportprofile, but the intent is that other configuration items
   may be put there int the future (e.g. bandwidth config). When
   building a guest's interface, if the <interface> XML itself has no
   virtportprofile, and if the requested network has a portgroup with
   a name matching the name given in the <interface> (or if one of the
   network's portgroups is marked with the "default='yes'" attribute),
   the virtportprofile from that portgroup will be used by the
   interface.

4) A network can have a virtportprofile defined at the top level,
   which will be used by a guest interface when connecting in one of
   the 'direct' modes if the guest interface XML itself hasn't
   specified any virtportprofile, and if there are also no matching
   portgroups on the network.

the domain XML <interface> element is updated in the following ways:

1) <virtualportprofile> can be specified when source type='network'
(previously it was only valid for source type='direct')

2) A new attribute "portgroup" has been added to the <source>
element. When source type='network' (the only time portgroup is
recognized), extra configuration information will be taken from the
<portgroup> element of the given name in the network definition.

3) Each virDomainNetDef now also potentially has a
virDomainActualNetDef which is a private object (never
exported/imported via the public API, and not defined in the RNG) that
is used to maintain information about the physical device that was
actually used for a NetDef of type VIR_DOMAIN_NET_TYPE_NETWORK.

The virDomainActualNetDef will only be parsed/formatted if the
parse/format function is called with the
VIR_DOMAIN_XML_INTERNAL_ACTUAL_NET flag set (which is only needed when
saving/loading a running domain's state info to the stateDir).

The virtPortProfile in the domain interface struct is now a separately
allocated object *pointed to by* (rather than contained in) the main
virDomainNetDef object. This is done to make it easier to figure out
when a virtualPortProfile has/hasn't been specified in a particular
config.

virtPortProfiles are currently only used in the domain XML, but will
soon also be used in the network XML. To prepare for that change, this
patch moves the structure definition into util/network.h and the parse
and format functions into util/network.c (I decided that this was a
better choice than macvtap.h/c for something that needed to always be
available on all platforms).

If util.h is going to have a MIN, it may as well also have MAX.

This introduces new API virDomainDestroyFlags to allow
domain destroying with flags, as the existing API virDomainDestroy
misses flags.

The set of flags is defined in virDomainDestroyFlagsValues enum,
which is currently commented, because it is empty.

Calling this API with no flags set (@flags == 0) is equivalent calling
virDomainDestroy.

* src/remote/remote_driver.c (remote_driver): Add new callbacks.
* src/remote/remote_protocol.x (remote_procedure): New RPCs.
(remote_domain_save_flags_args, remote_domain_restore_flags_args):
New structs.
* src/remote_protocol-structs: Update.

In order to choose whether to use O_DIRECT when saving a domain image
to a file, we need a new flag.  But virDomainSave was implemented
before our policy of all new APIs having a flag argument.  Likewise
for virDomainRestore when restoring from a file.

The new flag name is chosen as CACHE_BYPASS so as not to preclude
a future solution that uses posix_fadvise once the Linux kernel has
a smarter implementation of that interface.

* include/libvirt/libvirt.h.in (virDomainCreateFlags)
(virDomainCoreDumpFlags): Add a flag.
(virDomainSaveFlags, virDomainRestoreFlags): New prototypes.
* src/libvirt.c (virDomainSaveFlags, virDomainRestoreFlags): New API.
* src/libvirt_public.syms: Export them.
* src/driver.h (virDrvDomainSaveFlags, virDrvDomainRestoreFlags):
New driver callbacks.

Otherwise, an ABI mismatch gives error messages attributing the target
xml string as current, and the current domain state as the new xml.

* src/qemu/qemu_migration.c (qemuMigrationBegin): Use correct
argument order.

In preparation for a future patch adding new virFile APIs.

* src/util/files.h, src/util/files.c: Move...
* src/util/virfile.h, src/util/virfile.c: ...here, and rename
functions to virFile prefix.  Macro names are intentionally
left alone.
* *.c: All '#include "files.h"' uses changed.
* src/Makefile.am (UTIL_SOURCES): Reflect rename.
* cfg.mk (exclude_file_name_regexp--sc_prohibit_close): Likewise.
* src/libvirt_private.syms: Likewise.
* docs/hacking.html.in: Likewise.
* HACKING: Regenerate.

Since libvirt is multi-threaded, we should use FD_CLOEXEC as much
as possible in the parent, and only relax fds to inherited after
forking, to avoid leaking an fd created in one thread to a fork
run in another thread.  This gets us closer to that ideal, by
making virCommand automatically clear FD_CLOEXEC on fds intended
for the child, as well as avoiding a window of time with non-cloexec
pipes created for capturing output.

* src/util/command.c (virExecWithHook): Use CLOEXEC in parent.  In
child, guarantee that all fds to pass to child are inheritable.
(getDevNull): Use CLOEXEC.
(prepareStdFd): New helper function.
(virCommandRun, virCommandRequireHandshake): Use pipe2.
* src/qemu/qemu_command.c (qemuBuildCommandLine): Simplify caller.

We already have a precedent of function documentation in C files,
where it is closer to the implementation (witness libvirt.h vs.
libvirt.c); maintaining docs in both files risks docs going stale.

While I was at it, I used consistent doxygen style on all comments.

* src/util/command.h: Remove duplicate docs, and move unique
documentation...
* src/util/command.c: ...here.
Suggested by Matthias Bolte.

The only 'void name(void)' style procedure in the protocol is 'close' that
is handled special, but also programming errors like a missing _args or
_ret suffix on the structs in the .x files can create such a situation by
accident. Making the generator aware of this avoids bogus errors from the
generator such as:

  Use of uninitialized value in exists at ./rpc/gendispatch.pl line 967.

Also this allows to get rid of the -c option and the special case code for
the 'close' procedure, as the generator handles it now correctly.

Reported by Michal Privoznik