Features/QOM-QAPI integration

From QEMU

Separating configuration of QOM objects from their run-time state, and express the configuration as a QAPI struct.

Implementation

New input visitor function (the implementation in QObjectInputVisitor visits QLIST_FIRST(&qiv->stack)->h) 

bool visit_struct_foreach_member(Visitor *v, void (*cb)(void *opaque, const char *name, Visitor *v, Error **errp),
                                 void *opaque, Error **errp);

New ObjectClass function pointer "configure" replaces the visitor step of user_creatable_add_type 

void (*configure)(Object *obj, Visitor *v, Error **errp);

The object_configure function wraps the "configure" function pointer and falls back to properties for anything that isn't consumed by the classes: 

bool object_configure(Object *obj, Visitor *v, Error **errp) {
    Error *local_err = NULL;
    /*
     * Possibly, instead of using v directly, we'd need to interpose
     * another visitor that looks up global properties?
     */
    visit_start_struct(v, NULL, NULL, 0, &local_err);
    if (local_err) {
        goto out;
    }
    if (oc->configure) {
        oc->configure(obj, v, &local_err);
        if (local_err) {
            goto out;
        }
    }
    if (!visit_struct_foreach_member(v, object_property_set, obj, errp)) {
        return false;
    }
out:
    if (local_err) {
        error_propagate(errp, local_err);
    } else {
        visit_check_struct(v, &local_err);
    }
    visit_end_struct(v, NULL);
    return local_err != NULL;
}

user_creatable_add_type uses object_configure to set properties 

    obj = object_new(type);
    if (!object_configure(obj, v, &local_err)) {
        goto out;
    }
    if (id != NULL) {
        ...
    }

Conversion

Conversion from writable properties to options struct starts by defining oc->configure, such as: 

struct RngEgd {
    RngBackend parent;

    CharBackend chr;

    /*
     * Not perfect, as it causes a leak unless you free in an instance finalize function
     * or elsewhere.  However, "RngEgdOptions config" doesn't work too well either, as there
     * is no visit_free_RngEgdOptions_members function to free config->chardev only.
     */
    RngEgdOptions *config;
};

void qapi_RngEgd_configure(Object *obj, Visitor *v, Error **errp)
{
    RngEgd *s = RNG_EGD(obj);
    s->config = g_new0(RngEgdOptions, 1);
    visit_type_RngEgdOptions(v, NULL, &s->config, errp);
}
...
oc->configure = qapi_RngEgd_configure;

(See full-ish patch later in the page). Default values would be handled like: 

void qapi_MemoryBackendOptions_configure(Object *obj, Visitor *v, Error **errp)
{
    RngEgd *s = RNG_EGD(obj);
    s->config = g_new0(MemoryBackendOptions, 1);
    visit_type_MemoryBackendOptions(v, NULL, &s->config, errp);

    s->config->share = s->config->has_share ? s->config->share : false;
    ...
}

or at the QAPI level (i.e. the QAPI description of MemoryBackendOptions would have a default value that would be filled in by visit_type_MemoryBackendOptions).

The qapi_RngEgd_configure function could be later generated by QAPI, for example from: 

{ 'object': 'RngEgd',
  'qom-type': 'rng-egd',    # used to go from rng-egd to RNG_EGD()
  'configuration': 'RngEgdOptions'
}


The above QAPI declaration could also generate a constructor function for use in C code, for example: 

Object *object_new_configure(const char *type, void (*v)(Visitor *v, const char *name, void **ptr, Error **errp),
                             void *data, Error **errp)
{
    Object *o;
    QObject *ret = NULL;
    Error *local_err = NULL;
    Visitor *qiv, *qov;

    qov = qobject_output_visitor_new(&ret);
    v(qov, NULL, &data, &local_err);
    visit_free(qov);
    if (local_err) {
        error_propagate(errp, local_err);
        return NULL;
    }

    qiv = qobject_input_visitor_new(ret);
    o = object_new(type);
    object_configure(o, qiv, &local_err);
    visit_free(qiv);
    if (local_err) {
        error_propagate(errp, local_err);
        object_unref(o);
        return NULL;
    }
    return o;
}

static inline RngEgd *rng_egd_new(RngOptions *opt, Error **errp)
{
    return RNG_EGD(object_new_configure(TYPE_RNG_EGD, visit_type_RngEgdOptions, opt, errp));
}

Properties

Properties still exist, but they are mostly read-only. For example, rng_egd_get_chardev remains exactly the same but rng_egd_set_chardev goes away. They also keep their role in releasing resources on "object-del" (though it's visible mostly in devices, and not for example in rng-egd because it uses a string property for "chardev").

Properties are _not_ exposed to QAPI (not yet at least). Properties will be of one of three kinds:

  • read-only 1:1 mapping to configuration fields (e.g. rng-random.filename)
  • read-only 1:1 mapping to runtime state fields (e.g. rng-egd.chardev)
  • writable, with side effects (e.g. throttle-group.limits)

Writable 1:1 mapping to runtime state fields are probably rare enough that we can treat them the same as the third case.

QAPI can express the first two. The third must remain in C code unless somebody has ideas... It is arguably the most important for introspection, but qom-list might be enough since it only applies after an object has been generated and configured.

Sample backends/rng-egd.c patch

diff --git a/backends/rng-egd.c b/backends/rng-egd.c
index 4de142b9dc..7bf732d292 100644
--- a/backends/rng-egd.c
+++ b/backends/rng-egd.c
@@ -25,7 +25,7 @@ struct RngEgd {
     RngBackend parent;
 
     CharBackend chr;
-    char *chr_name;
+    RngOptions *config;
 };
 
 static void rng_egd_request_entropy(RngBackend *b, RngRequest *req)
@@ -89,16 +89,10 @@ static void rng_egd_opened(RngBackend *b, Error **errp)
     RngEgd *s = RNG_EGD(b);
     Chardev *chr;
 
-    if (s->chr_name == NULL) {
-        error_setg(errp, QERR_INVALID_PARAMETER_VALUE,
-                   "chardev", "a valid character device");
-        return;
-    }
-
-    chr = qemu_chr_find(s->chr_name);
+    chr = qemu_chr_find(s->config->chardev);
     if (chr == NULL) {
         error_set(errp, ERROR_CLASS_DEVICE_NOT_FOUND,
-                  "Device '%s' not found", s->chr_name);
+                  "Device '%s' not found", s->config->chardev);
         return;
     }
     if (!qemu_chr_fe_init(&s->chr, chr, errp)) {
@@ -110,19 +104,6 @@ static void rng_egd_opened(RngBackend *b, Error **errp)
                              rng_egd_chr_read, NULL, NULL, s, NULL, true);
 }
 
-static void rng_egd_set_chardev(Object *obj, const char *value, Error **errp)
-{
-    RngBackend *b = RNG_BACKEND(obj);
-    RngEgd *s = RNG_EGD(b);
-
-    if (b->opened) {
-        error_setg(errp, QERR_PERMISSION_DENIED);
-    } else {
-        g_free(s->chr_name);
-        s->chr_name = g_strdup(value);
-    }
-}
-
 static char *rng_egd_get_chardev(Object *obj, Error **errp)
 {
     RngEgd *s = RNG_EGD(obj);
@@ -140,17 +121,24 @@ static void rng_egd_finalize(Object *obj)
     RngEgd *s = RNG_EGD(obj);
 
     qemu_chr_fe_deinit(&s->chr, false);
-    g_free(s->chr_name);
+    qapi_free_RngOptions(s->config);
 }
 
+void rng_egd_configure(Object *obj, Visitor *v, Error **errp)
+{
+    RngEgd *s = RNG_EGD(obj);
+    s->config = g_new(RngEgdOptions, 1);
+    visit_type_RngEgdOptions(v, NULL, &s->config, errp);
+}
+
  static void rng_egd_class_init(ObjectClass *klass, void *data)
 {
     RngBackendClass *rbc = RNG_BACKEND_CLASS(klass);
 
+    klass->configure = rng_egd_configure;
     rbc->request_entropy = rng_egd_request_entropy;
     rbc->opened = rng_egd_opened;
-    object_class_property_add_str(klass, "chardev",
-                                  rng_egd_get_chardev, rng_egd_set_chardev);
+    object_class_property_add_str(klass, "chardev", rng_egd_get_chardev, NULL);
 }
 
 static const TypeInfo rng_egd_info = {
diff --git a/qapi/qom.json b/qapi/qom.json
index 0b0b92944b..662fdeea8c 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -254,3 +254,7 @@
 #
 ##
 { 'command': 'object-del', 'data': {'id': 'str'} }
+
+
+{ 'struct': 'RngEgdOptions',
+  'data: {'chardev': 'str'} }
Retrieved from "https://wiki.qemu.org/index.php?title=Features/QOM-QAPI_integration&oldid=10057"