[PATCH v3.1] libxl: Design of an async API to issue QMP commands to QEMU

[Anthony PERARD <anthony.perard@citrix.com>]

All the functions will be implemented in later patches.

Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>

---

What do you think of this design? This is the same as in my patch series
with new names (to avoid confusion with libxl___ev_*) and documentation.

I'll write something as well for the internal of the engine (the QMP
client itself).
---
 tools/libxl/libxl_internal.h         | 98 ++++++++++++++++++++++++++++
 tools/libxl/libxl_types_internal.idl | 14 ++++
 2 files changed, 112 insertions(+)

diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index c582894589..ac5a8a21f2 100644
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -357,6 +357,104 @@ struct libxl__ev_child {
 };
 
 
+/*
+ * QMP asynchronous calls
+ */
+
+/*
+ * This struct is used to register one command to send to QEMU with an
+ * associated callback.
+ *
+ * Possible states:
+ *  Undefined
+ *    Might contain anything.
+ *  Idle
+ *    Struct contents are defined enough to pass to any
+ *    libxl__qmp_cmd_* functions but is not registered and callback
+ *    will not be called. The struct does not contain references to
+ *    any allocated resources so can be thrown away.
+ *  Active
+ *    Currently waiting for a response from QEMU, and callback can be
+ *    called. _dispose must be called to reclaim resources.
+ */
+typedef struct libxl__qmp_cmd_state libxl__qmp_cmd_state;
+
+/*
+ * cmd_state:   In Idle state (with value domid available).
+ * response:    QMP response on success, or NULL on error.
+ * error_class: NONE on success, otherwise QMP error class or libxl error.
+ */
+typedef libxl__qmp_cmd_callback(libxl__gc *gc,
+                                libxl__qmp_cmd_state *cmd_state,
+                                const libxl__json_object *response,
+                                libxl__qmp_error_class error_class);
+
+/*
+ * Initialize libxl__qmp_cmd_state.
+ *    Which must be in Undefined or Idle state.
+ *    On return it is Idle.
+ */
+_hidden void libxl__qmp_cmd_init(libxl__qmp_cmd_state *cmd_state);
+
+/*
+ * Register a command to be issued to QEMU.
+ *   On entry cmd_state must be Idle.
+ *   Returns a libxl error code; on error return cmd_state is Idle.
+ *   On successful return cmd_state is Active and callback will be
+ *   called in the future.
+ *   Callback will not be called from within the call to this
+ *   function.
+ *
+ * This function will attempt to connect to the QMP socket if not
+ * already connected. No other communication will be done before the
+ * function returns.
+ *
+ * The callback will be called with the same cmd_state, but the
+ * cmd_state will be Idle.
+ *
+ * When called from within a callback, the same QMP connection will be
+ * reused to execute the new command. This is important in the case
+ * where the first command is "add-fd" and the second command use the
+ * fdset created by QEMU.
+ */
+_hidden int libxl__qmp_cmd_exec(libxl__gc *gc,
+                                libxl__qmp_cmd_state *cmd_state,
+                                libxl__qmp_cmd_callback *callback,
+                                uint32_t domid,
+                                const char *cmd, libxl__json_object *args);
+
+/*
+ * On entry, cmd_state must be in state Active or Idle.
+ * On return it is Idle.
+ */
+_hidden void libxl__qmp_cmd_dispose(libxl__gc *gc,
+                                    libxl__qmp_cmd_state *cmd_state);
+
+struct libxl__qmp_cmd_state {
+    /* read-only once Active and from within the callback */
+    uint32_t domid;
+    libxl__qmp_cmd_callback *callback;
+
+    /* private */
+
+    /*
+     * id == 0: initial state or response already received and callback called.
+     *          State is Idle.
+     * id > 0:  id used to send a command to qemu.
+     *          State is Active.
+     */
+    int id;
+    LIBXL_TAILQ_ENTRY(libxl__ev_qmp) entry;
+
+    /*
+     * This value can be initialise before calling _qmp_cmd_exec. The
+     * file descriptor will sent to QEMU along with the command, then
+     * the fd will be closed.
+     */
+    libxl__carefd *efd;
+};
+
+
 /*
  * evgen structures, which are the state we use for generating
  * events for the caller.
diff --git a/tools/libxl/libxl_types_internal.idl b/tools/libxl/libxl_types_internal.idl
index f2ff01718d..ada97615d5 100644
--- a/tools/libxl/libxl_types_internal.idl
+++ b/tools/libxl/libxl_types_internal.idl
@@ -13,6 +13,20 @@ libxl__qmp_message_type = Enumeration("qmp_message_type", [
     (5, "invalid"),
     ])
 
+libxl__qmp_error_class = Enumeration("qmp_error_class", [
+    # No error
+    (0, "NONE"),
+    # Error generated by libxl (e.g. socket closed unexpectedly, no mem, ...)
+    (1, "libxl_error"),
+    # QMP error classes described in QEMU sources code (QapiErrorClass)
+    (2, "GenericError"),
+    (3, "CommandNotFound"),
+    (4, "DeviceNotActive"),
+    (5, "DeviceNotFound"),
+    # Unrecognized QMP error class
+    (6, "Unknown"),
+    ])
+
 libxl__device_kind = Enumeration("device_kind", [
     (0, "NONE"),
     (1, "VIF"),
-- 
Anthony PERARD


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel