[RFC PATCHv2 1/8] threshold: new API virDomainBlockSetWriteThreshold

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



qemu 2.3 added a new QMP command block-set-write-threshold,
which allows callers to get an interrupt when a file hits a
write threshold, rather than the current approach of repeatedly
polling for file allocation.  This patch prepares the API for
callers to register to receive the event, as well as a way
to query the threshold via virDomainListGetStats().

The event is one-shot in qemu - a guest must re-register a new
threshold after each time it triggers.  However, the
virConnectDomainEventRegisterAny() call does not allow
parameterization, so callers must use a pair of APIs - one
to register the callback (one-time call) that will be used each
time a threshold triggers for any guest disk, and another to
repeatedly set the desired threshold (must be called each time
a threshold should be changed).

Note that the threshold can either be registered by a byte
offset, or by a thousandth of a percentage (a value between
0 and 100000, scaled to the disk size).  But the value is
always reported as a byte offset, even when registered as a
percentage.  I also considered having the setup parameter be
a double, to allow a finer resolution on percentage; with the
choice of an integer fixed-point scale, this means a 100G
disk can only set a threshold to a granularity of 1M, but
that is probably sufficient for the usage.

To make the patch series more digestible, this patch
intentionally omits remote support, by using a couple of
placeholders at a point where the compiler forces the addition
of a case label within a switch statement.

* include/libvirt/libvirt-domain.h
(virDomainBlockSetWriteThreshold): New API.
(virConnectDomainEventWriteThresholdCallback): New event.
* src/libvirt_public.syms (LIBVIRT_1.2.17): Export it.
* src/libvirt-domain.c (virDomainBlockSetWriteThreshold): New API.
(virConnectGetAllDomainStats): New stat.
* src/driver-hypervisor.h (virDrvDomainBlockSetWriteThreshold):
New hypervisor entry point.
* tools/virsh-domain.c (vshEventWriteThresholdPrint): Print new
event.
* tools/virsh.pod (domstats): Document new stat.
* daemon/remote.c (domainEventCallbacks): Add stub.
* src/conf/domain_event.c (virDomainEventDispatchDefaultFunc):
Likewise.

Signed-off-by: Eric Blake <eblake@xxxxxxxxxx>
---
 daemon/remote.c                  |  2 +
 include/libvirt/libvirt-domain.h | 47 ++++++++++++++++++++
 src/conf/domain_event.c          |  4 +-
 src/driver-hypervisor.h          |  7 +++
 src/libvirt-domain.c             | 95 ++++++++++++++++++++++++++++++++++++++++
 src/libvirt_public.syms          |  5 +++
 tools/virsh-domain.c             | 23 ++++++++++
 tools/virsh.pod                  |  1 +
 8 files changed, 183 insertions(+), 1 deletion(-)

diff --git a/daemon/remote.c b/daemon/remote.c
index e9e2dca..283ece2 100644
--- a/daemon/remote.c
+++ b/daemon/remote.c
@@ -1102,6 +1102,8 @@ static virConnectDomainEventGenericCallback domainEventCallbacks[] = {
     VIR_DOMAIN_EVENT_CALLBACK(remoteRelayDomainEventTunable),
     VIR_DOMAIN_EVENT_CALLBACK(remoteRelayDomainEventAgentLifecycle),
     VIR_DOMAIN_EVENT_CALLBACK(remoteRelayDomainEventDeviceAdded),
+    /* TODO: Implement RPC support for this */
+    VIR_DOMAIN_EVENT_CALLBACK(NULL),
 };

 verify(ARRAY_CARDINALITY(domainEventCallbacks) == VIR_DOMAIN_EVENT_ID_LAST);
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index d851225..7514656 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1297,6 +1297,17 @@ int                     virDomainBlockStatsFlags (virDomainPtr dom,
                                                   virTypedParameterPtr params,
                                                   int *nparams,
                                                   unsigned int flags);
+
+typedef enum {
+    /* threshold is thousandth of a percentage (0 to 100000) relative to
+     * image size rather than byte limit */
+    VIR_DOMAIN_BLOCK_SET_WRITE_THRESHOLD_PERCENTAGE = (1 << 0),
+} virDomainBlockSetWriteThresholdFlags;
+int virDomainBlockSetWriteThreshold(virDomainPtr dom,
+                                    const char *disk,
+                                    unsigned long long threshold,
+                                    unsigned int flags);
+
 int                     virDomainInterfaceStats (virDomainPtr dom,
                                                  const char *path,
                                                  virDomainInterfaceStatsPtr stats,
@@ -3246,6 +3257,41 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
                                                          void *opaque);

 /**
+ * virConnectDomainEventWriteThresholdCallback:
+ * @conn: connection object
+ * @dom: domain on which the event occurred
+ * @devAlias: device alias
+ * @threshold: threshold that was exceeded, in bytes
+ * @length: length beyond @threshold that was involved in the triggering
+ *          write, or 0 if not known
+ * @opaque: application specified data
+ *
+ * The callback signature to use when registering for an event of type
+ * VIR_DOMAIN_EVENT_ID_WRITE_THRESHOLD with virConnectDomainEventRegisterAny()
+ *
+ * This callback occurs when a block device detects a write event that
+ * exceeds a non-zero threshold set by
+ * virDomainBlockSetWriteThreshold().  When this event occurs, the
+ * threshold is reset to 0, and a new limit must be installed to see
+ * the event again on the same device.  The intent of this event is to
+ * allow time for the underlying storage to be resized dynamically
+ * prior to the point where the guest would be paused due to running
+ * out of space, without having to poll for allocation values.
+ *
+ * The contents of @devAlias will be "vda" when the threshold is triggered
+ * on the active layer of guest disk vda.  Some hypervisors also support
+ * threshold reporting on backing images, such as during a block commit;
+ * when that happens, @devAlias will be "vda[1]" for the backingStore at
+ * index 1 within the chain of host resources for guest disk vda.
+ */
+typedef void (*virConnectDomainEventWriteThresholdCallback)(virConnectPtr conn,
+                                                            virDomainPtr dom,
+                                                            const char *devAlias,
+                                                            unsigned long long threshold,
+                                                            unsigned long long length,
+                                                            void *opaque);
+
+/**
  * VIR_DOMAIN_TUNABLE_CPU_VCPUPIN:
  *
  * Macro represents formatted pinning for one vcpu specified by id which is
@@ -3528,6 +3574,7 @@ typedef enum {
     VIR_DOMAIN_EVENT_ID_TUNABLE = 17,        /* virConnectDomainEventTunableCallback */
     VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE = 18,/* virConnectDomainEventAgentLifecycleCallback */
     VIR_DOMAIN_EVENT_ID_DEVICE_ADDED = 19,   /* virConnectDomainEventDeviceAddedCallback */
+    VIR_DOMAIN_EVENT_ID_WRITE_THRESHOLD = 20, /* virConnectDomainEventWriteThreshold */

 # ifdef VIR_ENUM_SENTINELS
     VIR_DOMAIN_EVENT_ID_LAST
diff --git a/src/conf/domain_event.c b/src/conf/domain_event.c
index 20d66e1..c43799f 100644
--- a/src/conf/domain_event.c
+++ b/src/conf/domain_event.c
@@ -1,7 +1,7 @@
 /*
  * domain_event.c: domain event queue processing helpers
  *
- * Copyright (C) 2010-2014 Red Hat, Inc.
+ * Copyright (C) 2010-2015 Red Hat, Inc.
  * Copyright (C) 2008 VirtualIron
  * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
  *
@@ -1614,6 +1614,8 @@ virDomainEventDispatchDefaultFunc(virConnectPtr conn,
             goto cleanup;
         }

+    case VIR_DOMAIN_EVENT_ID_WRITE_THRESHOLD:
+        /* TODO: Implement RPC support for this */
     case VIR_DOMAIN_EVENT_ID_LAST:
         break;
     }
diff --git a/src/driver-hypervisor.h b/src/driver-hypervisor.h
index 3275343..b5b51f1 100644
--- a/src/driver-hypervisor.h
+++ b/src/driver-hypervisor.h
@@ -484,6 +484,12 @@ typedef int
                                unsigned int flags);

 typedef int
+(*virDrvDomainBlockSetWriteThreshold)(virDomainPtr domain,
+                                      const char *disk,
+                                      unsigned long long threshold,
+                                      unsigned int flags);
+
+typedef int
 (*virDrvDomainInterfaceStats)(virDomainPtr domain,
                               const char *path,
                               virDomainInterfaceStatsPtr stats);
@@ -1324,6 +1330,7 @@ struct _virHypervisorDriver {
     virDrvDomainBlockResize domainBlockResize;
     virDrvDomainBlockStats domainBlockStats;
     virDrvDomainBlockStatsFlags domainBlockStatsFlags;
+    virDrvDomainBlockSetWriteThreshold domainBlockSetWriteThreshold;
     virDrvDomainInterfaceStats domainInterfaceStats;
     virDrvDomainSetInterfaceParameters domainSetInterfaceParameters;
     virDrvDomainGetInterfaceParameters domainGetInterfaceParameters;
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 7e6d749..53114d3 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -5743,6 +5743,99 @@ virDomainBlockStatsFlags(virDomainPtr dom,


 /**
+ * virDomainBlockSetWriteThreshold:
+ * @dom: pointer to domain object
+ * @disk: path to the block device, or device shorthand
+ * @threshold: limit at which a write threshold event can trigger
+ * @flags: bitwise-OR of virDomainBlockSetWriteThresholdFlags
+ *
+ * This function is used to set a one-shot write threshold.  It should
+ * be used in tandem with virConnectDomainEventRegisterAny()
+ * installing a handler for VIR_DOMAIN_EVENT_ID_WRITE_THRESHOLD.  If
+ * the hypervisor detects that a write request (whether guest data, or
+ * host metadata) would exceed the host byte offset specified in
+ * @threshold, then an event is raised, and the threshold is reset to
+ * 0 at that time.  The event registration is only needed once, but
+ * this function must be called each time a new threshold is desired;
+ * the event will only fire if a non-zero threshold is
+ * exceeded.
+ *
+ * By default, @threshold is specified in bytes, and must not exceed
+ * the size of the block device.  However, when @flags includes
+ * VIR_DOMAIN_BLOCK_SET_WRITE_THRESHOLD_PERCENTAGE, @threshold is
+ * instead a value between 0 an 100,000, as a thousandth of a percent
+ * of the current size of the disk, and the driver will compute the
+ * corresponding byte value.  For example, 80000 represents 80.000%.
+ * A driver may round the requested threshold to a granularity that
+ * can actually be supported.
+ *
+ * Setting a threshold allows event-based resizing of host resources
+ * that back a guest disk without having to poll the current disk
+ * allocation, while still having enough time to complete the resize
+ * before the guest would end up halting due to insufficient space.
+ * Calling this function to set the threshold back to zero will stop
+ * further firing of the event.  virConnectGetAllDomainStats() can be
+ * used to track the current threshold value, always in the form
+ * normalized to bytes.
+ *
+ * The @disk parameter is either the device target shorthand (the
+ * <target dev='...'/> sub-element, such as "vda"), or (since 0.9.8)
+ * an unambiguous source name of the block device (the <source
+ * file='...'/> sub-element, such as "/path/to/image").  Valid names
+ * can be found by calling virDomainGetXMLDesc() and inspecting
+ * elements within //domain/devices/disk. Some drivers might also
+ * accept strings such as "vda[1]" for setting the threshold of a
+ * backing image, useful when doing a block commit into the backing
+ * image.
+ *
+ * Domains may have more than one block device.  To set thresholds for
+ * each you should make multiple calls to this function.  If write
+ * thresholds are not supported, an application will have to instead
+ * poll virDomainGetBlockInfo() or similar to track allocation.
+ *
+ * Returns -1 in case of error, 0 in case of success.
+ */
+int
+virDomainBlockSetWriteThreshold(virDomainPtr dom,
+                                const char *disk,
+                                unsigned long long threshold,
+                                unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(dom, "disk=%s, threshold=%llu, flags=%x",
+                     disk, threshold, flags);
+
+    virResetLastError();
+
+    virCheckDomainReturn(dom, -1);
+    virCheckNonNullArgGoto(disk, error);
+    if (flags & VIR_DOMAIN_BLOCK_SET_WRITE_THRESHOLD_PERCENTAGE &&
+        threshold > 100000) {
+        virReportError(VIR_ERR_INVALID_ARG,
+                       _("threshold in %s is larger than 100%%"),
+                       __FUNCTION__);
+        goto error;
+    }
+    conn = dom->conn;
+
+    if (conn->driver->domainBlockSetWriteThreshold) {
+        int ret;
+        ret = conn->driver->domainBlockSetWriteThreshold(dom, disk, threshold,
+                                                         flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+    virReportUnsupportedError();
+
+ error:
+    virDispatchError(dom->conn);
+    return -1;
+}
+
+
+/**
  * virDomainInterfaceStats:
  * @dom: pointer to the domain object
  * @path: path to the interface
@@ -11182,6 +11275,8 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
  *                          unsigned long long.
  * "block.<num>.errors" - Xen only: the 'oo_req' value as
  *                        unsigned long long.
+ * "block.<num>.write-threshold" - byte at which a write threshold event
+ *                                 will fire, as unsigned long long.
  * "block.<num>.allocation" - offset of the highest written sector
  *                            as unsigned long long.
  * "block.<num>.capacity" - logical size in bytes of the block device backing
diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms
index 716dd2f..d2bf1fa 100644
--- a/src/libvirt_public.syms
+++ b/src/libvirt_public.syms
@@ -715,4 +715,9 @@ LIBVIRT_1.2.16 {
         virDomainSetUserPassword;
 } LIBVIRT_1.2.15;

+LIBVIRT_1.2.17 {
+    global:
+        virDomainBlockSetWriteThreshold;
+} LIBVIRT_1.2.16;
+
 # .... define new API here using predicted next version number ....
diff --git a/tools/virsh-domain.c b/tools/virsh-domain.c
index 4c47473..f334570 100644
--- a/tools/virsh-domain.c
+++ b/tools/virsh-domain.c
@@ -12056,6 +12056,27 @@ vshEventDeviceAddedPrint(virConnectPtr conn ATTRIBUTE_UNUSED,
 }

 static void
+vshEventWriteThresholdPrint(virConnectPtr conn ATTRIBUTE_UNUSED,
+                            virDomainPtr dom,
+                            const char *alias,
+                            unsigned long long threshold,
+                            unsigned long long length,
+                            void *opaque)
+{
+    vshDomEventData *data = opaque;
+
+    if (!data->loop && *data->count)
+        return;
+    vshPrint(data->ctl,
+             _("event 'write-threshold' for domain %s disk %s: threshold %lld "
+               "exceeded by %lld bytes\n"),
+             virDomainGetName(dom), alias, threshold, length);
+    (*data->count)++;
+    if (!data->loop)
+        vshEventDone(data->ctl);
+}
+
+static void
 vshEventTunablePrint(virConnectPtr conn ATTRIBUTE_UNUSED,
                      virDomainPtr dom,
                      virTypedParameterPtr params,
@@ -12162,6 +12183,8 @@ static vshEventCallback vshEventCallbacks[] = {
       VIR_DOMAIN_EVENT_CALLBACK(vshEventAgentLifecyclePrint), },
     { "device-added",
       VIR_DOMAIN_EVENT_CALLBACK(vshEventDeviceAddedPrint), },
+    { "write-threshold",
+      VIR_DOMAIN_EVENT_CALLBACK(vshEventWriteThresholdPrint), },
 };
 verify(VIR_DOMAIN_EVENT_ID_LAST == ARRAY_CARDINALITY(vshEventCallbacks));

diff --git a/tools/virsh.pod b/tools/virsh.pod
index 9b57c8c..84e8fc4 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -919,6 +919,7 @@ local file or block device,
 "block.<num>.fl.reqs" - total flush requests,
 "block.<num>.fl.times" - total time (ns) spent on cache flushing,
 "block.<num>.errors" - Xen only: the 'oo_req' value,
+"block.<num>.write-threshold" - write threshold event trigger, in bytes,
 "block.<num>.allocation" - offset of highest written sector in bytes,
 "block.<num>.capacity" - logical size of source file in bytes,
 "block.<num>.physical" - physical size of source file in bytes
-- 
2.4.2

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]